docs(reference): CLI 摩擦改进(交互验证优先 + body-file 范式 + 时区取时细节 + #191 规避)

四处文档改动(2026-06-01 摩擦改进沉淀,不写测试脚本,改完用真实命令交互验证):

- cli.md: Todo Note 段补「复杂 JSON body 优先 --body-file 替代 --body-json」段(避免 shell escape 痛点,支持 stdin)
- secretary-reference.md: 扩「自取北京时间」段(主 server 本地 TZ='Asia/Shanghai' date 即可,跨节点用 ssh route)+ 加「CLI 改进用直接交互调用验证,不写测试脚本」原则段(关联 cli-friction-no-over-testing)+ 加「#191 P0 决策日记 --summary 被吞临时规避」段(摘要写进 body 第一段,等 backend-core 修复)

交互验证清单(2026-06-01 15:39):
- TZ='Asia/Shanghai' date = 2026-06-01 15:39:02 CST ✅
- microservice proxy todo-note /api/instances/<id> = 200 OK ✅
- addTodo via --body-file = 200 OK, probe id=todo_9arljoqk ✅
- deleteTodo via --body-file = 200 OK, probe removed ✅

docs/reference/secretary-reference.md

@@ -49,12 +49,21 @@
 
 秘书应保护用户的整片清醒时间。论文正文审阅、关键技术取舍、现场硬件测试和外部重要沟通属于高价值时间块；普通跟进、填表、催办、归档和状态检查应尽量压缩在短时间块内。
 
-**每次开始正式工作前（进入排程、回读 Todo Note、回写决策、安排时间块），秘书必须自己拉取一次最新北京时间作为基准时间。** 不能依赖对话首部日期、上下文里的"现在"、历史时间戳或上一次会话的"今天"推断；用户口述时间（如"现在是 14:57"）作为交叉验证，但不是基准。取时方式优先 `bun scripts/cli.ts ssh <route> script` 跑 `date '+%Y-%m-%d %H:%M:%S %Z'` 或读 NTP 校对过的本地时间，把结果在排程第一句明确告诉用户（"我现在看到的时间是 X,按这个重排"），让用户能立刻发现时间错位。这样做的原因：用户可能在两次对话之间休息或离开，秘书用缓存时间排程会与用户实际位置偏移，反馈格式"完成/未完成 + 卡点"对不上，日程序列累积错位。
+**每次开始正式工作前（进入排程、回读 Todo Note、回写决策、安排时间块），秘书必须自己拉取一次最新北京时间作为基准时间。** 不能依赖对话首部日期、上下文里的"现在"、历史时间戳或上一次会话的"今天"推断；用户口述时间（如"现在是 14:57"）作为交叉验证，但不是基准。取时方式（2026-06-01 验证）：
+
+- **主 server 本地调用**（秘书本机场景）：`TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S %Z'`，15:39 CST = 真实北京时间，无需走 ssh route。优点：低摩擦、单命令、无 dep。
+- **跨节点/远端校时**（需要确认远端 host 时钟时）：`bun scripts/cli.ts ssh <route> script -- 'date "+%Y-%m-%d %H:%M:%S %Z"'`，route 写明定位（如 `G14` / `D601`）。
+
+把结果在排程第一句明确告诉用户（"我现在看到的时间是 X,按这个重排"），让用户能立刻发现时间错位。这样做的原因：用户可能在两次对话之间休息或离开，秘书用缓存时间排程会与用户实际位置偏移，反馈格式"完成/未完成 + 卡点"对不上，日程序列累积错位。
 
 **遇到 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；模式措辞误导是常见陷阱。
 
+**CLI 改进用直接交互调用验证，不写测试脚本**（[cli-friction-no-over-testing](file:///home/ubuntu/.claude/projects/-home-ubuntu-unidesk/memory/cli-friction-no-over-testing.md) 原则）。一次性的 CLI 调用范式、参数形态、shell escape 规避、端点可用性，直接 `bun scripts/cli.ts ...` 跑一次看 200 / body 就够了；不要为一次性改进堆 `bun:test` / `mocha` / `jest` 的 contract test。contract test 只在结构性边界（如 action type 全清单、权限边界、长期回归）需要时才写。`docs/reference/cli.md` 已固化的 CLI 范式都经过 2026-06-01 交互验证（actions 端点 addTodo / toggleTodoCompleted / deleteTodo 全部 200 OK），见 cli.md 的 Todo Note 写操作段。
+
 **秘书的本份是维护 Todo Note；Decision 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 替代。
 
+**`decision diary upsert --summary` 在 `--body-file` 模式下被吞（[#191](https://github.com/pikasTech/unidesk/issues/191) P0）的临时规避**：在 backend-core 修复前，秘书 upsert 决策日记时**不传 `--summary`**，把摘要写进 body 文件的第一段（用 `## 进展` 段首句承担 summary 角色）。示例：先 `cat > /tmp/diary.md <<'EOF'` 写"## 进展\n- 一句话摘要\n\n## 详细\n- ..."，再 `bun scripts/cli.ts decision diary upsert YYYY-MM-DD --title "..." --body-file /tmp/diary.md`，不要传 `--summary`。摘要实际写到 body 字段，前端展示时由 Decision Center 渲染层处理。秘书不在 diary 上越界写(见上条),但如果用户在 chat 里给了完整进展,秘书可以用这个 workaround 把"用户原话摘要"写进 body 首段,等用户后续自行覆盖。
+
 ## Todo Note 使用规则
 
 `Todo Note` 适合承载同日或近期可执行的提醒和短任务。任务标题必须包含动作、对象和可判断结果，避免只写主题词。