WorkBuddy 交接白皮书 v1.0
给新会话的 AI：本文件是用户在本机 8 个月、266 个会话、12 个主项目里验证过的事实与踩过的坑。请先完整读完再动手；凡本文件已写明的环境事实、命令限制与失败结论，不要重新探索、不要重试旧的错误做法。发现新坑时，在收尾时把它写回本文件或项目的
MEMORY.md。生成日期：2026-11-10 ｜ 适用：本机（Windows / WorkBuddy）｜ 语言：简体中文 ｜ 本文件不含任何密钥。
0. 使用约定（最高优先级）
- 先读记忆再动手：本白皮书 → 目标工作区
.workbuddy/memory/MEMORY.md→ 最近的YYYY-MM-DD.md→ 再开始。 - 冲突时以本文件为准，但要先说明「白皮书与现状不一致」，不要闷头改。
- 不要重建已存在的机制：巡检、重启、域名通知、静默启动都已有脚本/计划任务，见第 7 节文件地图。
- 改动必须自测：给出可复核的验证结论（HTTP 200 /
BUILD_ID/ 浏览器ERRORS:[]/ 手机 390px 无溢出），不接受「应该可以」。 - 收尾要沉淀：新坑写回记忆；重复动作脚本化；任务结束报一行账（工具调用数、约耗 token、最贵环节）。
1. 本机情况
| 项 | 事实 |
|---|---|
| 系统 | Windows（win32），中文环境，IDE 主题 light（浅底深字） |
| Shell | 默认 Git Bash / POSIX（路径用正斜杠、/c/Users/...）；另有 Windows PowerShell 5.1（无 &&、??、?.，用 ; + if ($?)） |
| 工作区 | C:\Users\cag\WorkBuddy\<YYYY-MM-DD-HH-MM-SS>\，新任务默认新目录；历史项目保留不删 |
| 全局配置 | C:\Users\cag\.workbuddy\（项目数据，不是缓存，不要删）；会话存档 projects\**\*.jsonl；用量 workbuddy.db |
| 项目记忆 | 每个工作区 .workbuddy/memory/MEMORY.md（长期）+ YYYY-MM-DD.md（日志，追加写） |
| Node | v22.22.2 / npm 10.9.7 |
| Python（两个，包不通用） | ① WorkBuddy 内置 ~\.workbuddy\binaries\python\versions\3.13.12\python.exe（bash 里的 python）。无 PIL / tkinter / requests / playwright / pandas；有 fontTools。② 官方 C:\Users\cag\AppData\Local\Programs\Python\Python313\python.exe（py 启动器），带 pystray / Pillow，用于托盘 GUI。③ 另有 uv 的 CPython 3.12.14 |
| 浏览器 | Edge 133 C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe；Playwright 1.59-alpha 在插件 playwright-cli\0.1.0\node_modules，本机只装了 chromium-1243（插件要 1210，版本不匹配） |
| PDF 工具 | TeX Live 2025 自带 pdftotext / pdftoppm / pdfinfo，可直接用；pip install pymupdf 会长时间无输出（网络问题），别等 |
| 其他 CLI | curl（系统自带）、git 可用；无 sqlite3 命令行、无 ffmpeg |
| 已连连接器 | Agent Mail、腾讯文档；用户级 skill：kaoyan-site-health（网站/域名/体检问题一律走它） |
常驻服务（不要重复搭建）
| 服务 | 端口 | 路径前缀 | 说明 |
|---|---|---|---|
门户 portal/server.js | 3000 | / /prob/ /healthz | 零依赖 Node，反代其余两站 |
| 词汇站 Next | 3001 | /vocab/ | basePath /vocab |
| 笔记站 Next | 3102 | /notes/ | basePath /notes（不是 3002，见 4.7） |
| natapp 免费隧道 | → 3000 | 公网入口 | 域名每天约 03:24 重分配，只能 http |
- 5 个计划任务：
KaoyanPortal/KaoyanNextServer/KaoyanNotes/KaoyanNatapp/KaoyanSelfHeal。 - 唯一启动器
ops/launch.ps1 -Name <portal|vocab|notes|natapp|selfheal>（无黑窗、幂等：启动前按端口清旧实例）。 selfheal.mjs每 30 分钟 + 登录时自愈；域名变化落outbox/+ 桌面通知，需会话内--flush-mail补发。- 托盘控制面板
ops/kaoyan-panel.py+panel.bat（官方 Python + pystray）。 - 前台自动化（2h 巡检 / 6h 重启）已删除，别再建，否则双套机制互相打架、还会刷屏任务列表。
2. 用户风格（怎么接指令）
画像：把 AI 当「可施工的工程队」，不是问答机。历史 73 条人工指令里，中位 59 字、最长 43,915 字（一整份《行动手册》）；偏好表格、树状图、编号清单，强调严格按序执行；习惯先给背景材料，再让 AI 补延伸研究。
| 指令模式 | 占比 | 典型原文 | 你应该怎么接 |
|---|---|---|---|
| 蓝图施工 | ~45% | 「参考考研英语网站，做一个笔记站，md 存本地库，导入时调 DeepSeek 抽关键字…」 | 通读全文 → 复述验收点 → 分步实现 → 每步自测。不要跳过手册里的数据库/API 约定 |
| 逐点打补丁 | ~30% | 「1. 在线图片一直加载不出来；2. 默认模式应当是自由板面；3. …」 | 逐条编号对齐，一条不漏；改完按同样编号回报结果 |
| 运维口头令 | ~18% | 「重启服务器和natapp」「需要」「那就两个都做」 | 不要反问「重启哪个」——去查记忆/当前状态后直接执行。这类短句依赖上下文 |
| 元认知提问 | ~7% | 「这个任务总共花费了多少积分？」「你不能访问其他任务的内容吗?」 | 如实说边界与数据，不要编 |
其余必须知道的偏好：
- 否定式反馈 = 缺陷报告，不是让你推倒重来。33% 的指令含「还是/并不/打不开/一直」。先定位根因，再最小改动；改动前可反问「现象 + 复现步骤 + 期望」三要素，但不要空泛地大改一通。
- 审美类需求先给方案：「简约大气」「有苹果味」「高级感」这类词不可判定。用户曾因动画反复不达标说「回滚吧，你好像做不好这种动画」。正确做法是先给 2 个方案 + 取舍 + 量化参数（尺寸/间距/参照产品/禁止项），等用户选完再动手；用户明确说过「我的描述比较模糊，你先给我几个方案让我选择」。
- 用户会自己验收，而且常在手机端看。交付前必做：桌面 + 390px 手机、浅色 + 深色两套、无横向滚动、无控制台报错。
- 用户喜欢沉淀：重复 3 次以上的动作，主动提议固化成脚本 / skill / 计划任务（历史上把「重启 + 巡检」固化成
selfheal.mjs是最成功的一次）。 - 结论先行、中文回答，多给表格/树状图；不确定的地方给选项，不要猜。
3. 运行环境（命令铁律速查）
| 场景 | ✅ 正确做法 | ❌ 会失败 |
|---|---|---|
| 路径 | 工具参数一律绝对路径 + 正斜杠 | 相对路径、Bash 里写 C:\... |
| 跨工具 | Bash 归 Bash，PowerShell 归 PowerShell | 在 PowerShell 里调 bash/sh/wsl；powershell -File xxx.ps1 从 Bash 调用会被安全策略拦（须用 PowerShell 工具 & "路径\stop.ps1"） |
| 删除文件 | PowerShell Remove-Item .next -Recurse -Force | Bash rm -rf（被 safe-delete shim 拦：SAFE_DELETE_BULK_CONFIRM_REQUIRED）；绝不碰 .workbuddy |
| 常驻服务 | 计划任务 + Start-ScheduledTask | 严禁用 run_in_background 起网站/natapp——会话结束进程即被回收（曾误判为「系统 2h/11h 回收」，排查掉大量时间） |
| 计划任务 | Get-ScheduledTask → 改 Actions[0] 的 Execute/Arguments/WorkingDirectory → Set-ScheduledTask；启动被拒 0x800710E0 先 Stop 再 Start | schtasks.exe、wscript/cscript（LOLBin）、New-ScheduledTaskAction/Trigger、COM Schedule.Service 全被拦；Start-Process / .NET Process.Start 被安全策略拦 |
| PowerShell 版本 | 5.1：A; if ($?) { B } | &&、` |
| 脚本编码 | .bat 注释只能 ASCII（中文 UTF-8 会让 cmd 报「命令语法不正确」）；.ps1 中文注释可以 | .bat 里写中文 |
| CSV | 用 utf-8-sig（源 CSV 常带 BOM） | utf-8 直接读 |
| 反斜杠 / 正则 | 需要匹配字面反斜杠时用 split/join 或 String.fromCharCode(92) | 字符串拼接构造正则源（JSON→JS→正则三层转义，极易 SyntaxError） |
| 图标/符号 | 线性 SVG 或中文标签（「满/浮/嵌」「▦」） | 🪟、⤢、◱ 等 Windows 字体缺字 emoji（豆腐块） |
| 邮件 | 会话内用 agent-mail；后台脚本只能落 outbox/ | 后台进程调 agent-mail 连接器（调不到）；未经用户明确要求不要主动发邮件 |
4. 失败经验（按代价排序，全部是已验证结论）
| # | 现象 | 根因 | 结论 / 正确做法 |
|---|---|---|---|
| 1 | 网站隔几小时打不开，反复自愈 | run_in_background 起的进程随会话结束被回收，曾被误判「系统定时回收」 | 常驻服务只走 Windows 计划任务；判健康看端口 HTTP 200 + natapp 日志 status=online + 公网 200，不是看进程在不在 |
| 2 | 每 30 分钟黑窗一闪、打断操作 | 计划任务是 Interactive 登录类型，-WindowStyle Hidden 是「先建窗口再隐藏」 | 改 S4U（session 0，物理无窗口）需管理员，脚本 ops/set-s4u.ps1 待用户手动提权运行；期间用托盘面板观察。S4U 后桌面 toast 会失效，改看 selfheal.log / outbox/ / current-domain.txt |
| 3 | 外网在 200/404/502 间跳变 | 多次启动残留多个 natapp，旧进程报 already_registered 后重连循环互相干扰 | 彻底 Stop-Process natapp 清空 → 只起一个；natapp 是 TUI 程序，必须有真实控制台，不能 stdio:ignore / windowsHide |
| 4 | 公网探测 exit 7，误判隧道断 | 免费隧道不支持 443 | 公网校验一律用 http:// |
| 5 | P1012 Environment variable not found: DATABASE_URL | Prisma CLI 只读 .env，不读 .env.local | 两个文件分工：.env 只放 DATABASE_URL；密钥只放 .env.local，两者都 gitignore，密钥绝不加 NEXT_PUBLIC_ |
| 6 | next build 崩在 EPERM open .next/trace，重试 4 次仍失败 | 环境级流打开被拦，与路径/权限无关（换 distDir、预创建文件都无效） | 定案：notes/scripts/trace-guard.js 把 trace 的 createWriteStream 换成内存 PassThrough，build 改为 node --require ./scripts/trace-guard.js node_modules/next/dist/bin/next build。成功判据是存在 .next/BUILD_ID。旧经验「NODE_OPTIONS= + 重试 4 次」已作废 |
| 7 | 端口 3002 EACCES | Windows 保留端口段 3002–3101 | 笔记站用 3102 |
| 8 | basePath 根路径 308 自循环、公网打不开 | 反代改写了 Host；trailingSlash 没开 | basePath 必须与 trailingSlash:true 成对；portal/server.js 必须保留原始 Host 头（不能改写成 127.0.0.1:3001）；客户端 fetch 不会自动带 basePath，要手写 /notes/api/... 且 API 路由带尾斜杠 |
| 9 | 运行时上传到 public/ 的图片 404 | next start 启动时已固定静态文件清单 | 存 data/stickers/，经 /api/stickers/file/[name] 读盘返回 |
| 10 | 公式乱码、$$ / $$$$ 原样显示 | 按行 split 后才匹配，跨行公式配不上对；模型会吐四美元分隔符 | 在全文（split 之前）统一归一化：3+ 个 $ 折叠为 $$、\[ \]/\( \) 用 split/join 转换、跨行 $$...$$ 折叠；保护代码块；KaTeX 场景夹在文字中的 $$..$$ 要改成 $\displaystyle ..$ |
| 11 | 图表里 $X$ 原样显示 | SVG <text> 不能内嵌 HTML，渲染器的 HTML 输出无效 | 图表文字一律直接写 Unicode（μ σ λ θ̂ x₁），不要走公式渲染器 |
| 12 | DeepSeek 调用报错 | deepseek-chat / deepseek-reasoner 已于 2026-07-24 弃用 | 用 deepseek-flash（快）或 deepseek-v4-pro；flash 默认开 thinking（effort=high），此时 temperature 无效；Node SDK 把 thinking / reasoning_effort 放请求体顶层（Python 才用 extra_body）；本项目默认 DEEPSEEK_THINKING=disabled |
| 13 | /api/random 每次返回同一个词 | Next 14 把无动态 API 的 GET 路由静态化，响应头 no-store 也不生效 | 路由加 export const dynamic = "force-dynamic"；SQLite 随机用 $queryRaw ORDER BY RANDOM() LIMIT 1 |
| 14 | prisma generate 报 DLL EPERM | 运行中的服务锁住 DLL | 先 Stop-ScheduledTask 并杀掉对应端口进程，再 generate / db push |
| 15 | 贴纸把手机布局撑宽（390→452），fixed 按钮跑出屏 | 坐标未夹紧、旋转贴纸按 w 而非外接矩形算、.page-shell 有 overflow-x | 拖动/创建/渲染三处夹紧；用 |w·cos|+|h·sin| 旋转外接矩形；html{overflow-x:clip} 兜底；浮层 createPortal 到 body；.sticker-board 不能带 z-index（否则整层锁进堆叠上下文，贴纸沉不到文字下面） |
| 16 | 外链图片「一直加载不出来」 | 不是代码 bug：防盗链 + http/https 混合内容 + 用户贴的是网页地址 | 同源代理 /api/stickers/proxy/?url=（带 UA + 同源 Referer、拦内网 SSRF、限 12MB、只放行 image/*）；贴 URL 先 probeImage 探尺寸，失败就不创建贴纸 |
| 17 | Edge --headless --print-to-pdf 退出码 0 却不产文件 | 泄漏的 headless msedge 进程污染环境（曾残留 17+ 个）；--headless=new 也不产出 | 放弃命令行转 PDF，交付单文件 HTML 让用户 Ctrl+P（勾选背景图形、页边距无）；封面别用固定 height，用 min-height:225mm;height:auto |
| 18 | 浏览器验证拿不到内容 | Edge headless --dump-dom 恒空；Playwright networkidle 在有轮询的页面会超时 | 用 --screenshot + 看图 / domcontentloaded + waitForTimeout；测试页新增 screen 后必须同步所有 _test*.html；复制到测试目录的源文件改了要重新 cp |
| 19 | Playwright 截图报找不到 chromium | 插件版本要 1210，本机只有 1243 | chromium.launch({ executablePath: 'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe' })；脚本放工作区时 require('playwright') 解析不到，要写插件 node_modules 的绝对路径 |
| 20 | 邮件发不出去 / 域名通知丢失 | Agent Mail GetMe 曾 not_bound；后台脚本调不到连接器 | 后台落 outbox/，会话内 --flush-mail 补发；域名每天变，逐封发会变成骚扰，用户明确要求才发 |
| 21 | 词表提取出一堆 IPA 碎片、技术词 | 全文正则一把梭没剔表格行 | 结构化小节优先；剔 Markdown 表格行、IPA /xxx/、词素记号、技术词；长度≥3 且含元音（最终 503 词） |
| 22 | 内容分类误杀 / 误放行 | 泛化关键词（「峡谷」「恐怖」） | 白名单用「王者峡谷」这类具体词；标题匹配前 re.sub(r"[\s\u3000]+","",t) 归一化 |
| 23 | 任务列表被巡检任务刷屏、两套自愈机制打架 | 前台自动化重复创建 | 逻辑固化进 selfheal.mjs，前台自动化全部删除；用户问网站状态一律走 kaoyan-site-health skill（内部要 Start-ScheduledTask，必须用 PowerShell 工具执行，Bash 会拦） |
| 24 | PDF 公式转换错位 | WPS 生成的 PDF 文本层公式不可信 | pdftotext 只当骨架，公式用 pdftoppm 渲染 180dpi 全页 / 400dpi 局部后视觉转录 LaTeX |
| 25 | 自动化「一天两次」写不对 | DAILY 的 rrule 不支持逗号分隔 BYHOUR | 用 FREQ=HOURLY;INTERVAL=12;BYHOUR=0;BYMINUTE=0 |
5. 交互经验（效率协议）
开工
- 读本白皮书 + 项目
MEMORY.md+ 最近日志，确认端口/计划任务/当前域名。 - 确认要用哪个 Python 解释器、是否已有可复用脚本。
- 判断「直接做」还是「先给方案」：涉及视觉、架构、多选一的，一律先给 2 个方案 + 取舍，等用户决策。
执行
4. 严格按用户给的编号/顺序执行，不跳步、不擅自换技术栈；长任务用任务列表分步并逐条对齐。
5. 每个改动当场自测：构建看 BUILD_ID；接口看 HTTP 200 + 返回体；前端用 Playwright 看图 + ERRORS:[]；手机 390px 无横向滚动；浅/深两套主题。
6. 失败时先定位根因再改，不要「重试 4 次」赌运气——本机多数失败是环境级确定性错误（见第 4 节）。
7. 涉及服务重启：Stop-ScheduledTask → 杀端口残留 → Start-ScheduledTask（launcher 自己会清旧实例）→ wait-ready → 复检本地 + 公网。
收尾
8. 报告写清「改了什么 / 怎么验证的 / 已知副作用」，结论先行，配表格。
9. 新坑当天写回 MEMORY.md；重复动作脚本化；不新建重复自动化。
10. 报一行成本账（工具调用数、约耗 token、最贵环节）。
上下文纪律（很省钱）
- 历史数据显示：指令长度与会话 token 相关 r=0.19（几乎无关），而工具调用数与 token 相关 r=0.998；单次请求平均上下文 133K token。也就是说，返工和长上下文才是成本，用户多写字几乎免费。
- 因此：一个可验收模块 = 一个会话。单会话控制在 ≤50 次工具调用 / ≤150K 上下文，超出就新开会话并交本白皮书。历史上一个会话跑到 1,810 次工具调用、237M token，是最典型的浪费。
- 大工程优先「多写 300 字验收标准」，而不是「让 AI 猜三轮」。
6. 新任务开工检查清单（可直接复制给 AI）
请先读完本白皮书，然后：
[ ] 读目标工作区 .workbuddy/memory/MEMORY.md 与最近日志
[ ] 核对 3000/3001/3102 状态、5 个计划任务、当前 natapp 域名
[ ] 确认 Node/Python 解释器与可复用脚本（selfheal / launch / panel / site-health）
[ ] 判断是否需要「先给 2 个方案再执行」
[ ] 把验收标准写成可判定条目（尺寸/状态码/浏览器实测/手机 390px）
[ ] 分步执行、每步自测、逐条回报
[ ] 收尾写回 MEMORY.md，并报工具调用数与大致 token
不要重新探索本白皮书已写明的事实；遇到冲突先说明。
7. 文件地图（路径速查）
| 用途 | 路径（相对 C:\Users\cag\WorkBuddy\2026-10-11-06-00-16） |
|---|---|
| 门户 / 静态游戏 / 反代 | portal/server.js、portal/index.html |
| 词汇站 | kaoyan-vocab/（.env / .env.local / whitebook.md / prisma/seed.ts） |
| 笔记站 | notes/（whitebook.md、scripts/trace-guard.js、components/MarkdownView.tsx、lib/*.ts） |
| 概率游戏源码 | 另一工作区 2026-10-12-20-02-26\概率勇者考研秘境\ |
| 唯一启动器 | ops/launch.ps1 |
| 停服 / 体检 / 就绪 | ops/stop.ps1（若未迁移则在 natapp/）、natapp/health-check.mjs、natapp/wait-ready.mjs |
| 自愈与域名 | kaoyan-vocab/natapp/selfheal.mjs、current-domain.txt、outbox/、selfheal.log |
| 托盘面板 | ops/kaoyan-panel.py、ops/panel.bat、ops/panel-admin.bat、ops/set-s4u.ps1 |
| 网站状态 skill | C:\Users\cag\.workbuddy\skills\kaoyan-site-health |
| 本轮复盘产物 | 2026-11-10-15-37-22\AI使用复盘报告.html/.png、analysis\*.json |
维护约定：本白皮书随项目演进而更新；新增结论请标注日期并同步到对应工作区 MEMORY.md。