docs(reference): 固化 Todo Note 写端点 + 秘书 CLI 摩擦调查方法论

三处文档改动:
- microservices.md「Todo Note On Main Server」补 actions 端点形态段、backend-only 真实语义、404 catch-all 误判陷阱
- cli.md「microservice proxy」段补 Todo Note 写操作 CLI 范式(toggleTodoCompleted / addTodo / undo / redo)
- secretary-reference.md 加「CLI 报错四步调查方法论」(读源码+容器实测+git history+复盘 issue)

沉淀 pikasTech/unidesk#188 复盘教训,关闭 #190 文档缺口。剩下 diary --summary 吞并的 P0 由 #9 跟踪。
This commit is contained in:
Codex
2026-06-01 06:34:24 +00:00
parent 12d79a80bf
commit 49cf814e74
3 changed files with 26 additions and 1 deletions
+2
View File
@@ -49,6 +49,8 @@
秘书应保护用户的整片清醒时间。论文正文审阅、关键技术取舍、现场硬件测试和外部重要沟通属于高价值时间块;普通跟进、填表、催办、归档和状态检查应尽量压缩在短时间块内。
**遇到 CLI 报错或"看起来锁了"的现象,不要凭错误文案下结论;按"读源码 + 容器内实测 + git history + 复盘 issue"四步调查。** 第一步读 microservice 源码(UniDesk 主仓 vendoring 的镜像源或外部仓的 `server.ts` / `microservice_proxy.rs`),定位注册路由表、mode 标志位、错误文案生成点;第二步在容器内直接实测(`docker exec ... node ...``wget http://service:port/...`),拿到真实 200 / 4xx 响应,验证假设;第三步查 git history 看是谁、什么时候、为什么加的;第四步把"原诊断 + 真因 + 实测证据 + 修复点"蒸馏到 `docs/reference/` 并开/更新对应 issue(参考 [pikasTech/unidesk#188](https://github.com/pikasTech/unidesk/issues/188) 复盘结构)。特别警惕"错误文案暗示的因果"——例如 `404 {"error":"X is running in backend-only mode"}` 不代表 mode 锁了写,只代表请求路径没匹配上 catch-all;模式措辞误导是常见陷阱。
**秘书的本份是维护 Todo NoteDecision Center diary 是用户自己的工作日志,秘书只读不写。** 收到用户口述的进展(完成/未完成/卡点/决策/排程登记),秘书维护 Todo Note(标 completed / 新增子 todo / 拆分 / 改 reminder),不写到 diary。Decision Center diary 是用户承载自己反思和工作日志的私域,秘书写进去等于抢用户的笔、污染第一人称叙述。例外只有读:秘书可以调用 `diary show` / `diary list` / `diary months` 对齐上下文,**不调用 `diary upsert` / `diary edit` / `diary import` / `diary today`**。当 Todo Note 写路径被外部阻塞(如 issue #188 的 backend-only mode)时,秘书必须先把修复升级到日程或明确告诉用户「无法维护 Todo Note,你的进展请你自己在 Todo Note 里勾完成」,不能绕道用 diary 替代。
## Todo Note 使用规则