pi-multi-viewers 0.8.0 → 0.8.2

package/AGENTS.md

@@ -28,13 +28,15 @@ human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
 scripts/mv.sh        稳定入口 shim（exec mv_cli.py；路径被 prompt/README 引用）
 scripts/pi-probe.sh  LLM 探针（跑 pi + 登记新 session → 残留检查器可追溯）
 scripts/check-residue.sh  残留检查（session/进程/目录三类；增删 scripts/ 时同步本节）
-mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say/viewers）
+scripts/archive-result.sh  归档 result.md（机械部分：逐字复制+校验/存档头骨架/索引行/删源副本）
+mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say/viewers/set-viewer）
 extensions/multi-viewers/  【单一扩展单元】index.ts = 三命令 + shared.ts = 助手
                            /multi-viewers 分析入口（prepare→暂停点弹窗→start→预填+打印观看命令）
                            /multi-viewers-finish 收尾（status→确认→cleanup）
                            /multi-viewers-say 插话（零 LLM，直接 spawn human_sayer.py）
                            ⚠ extensions/ 平级禁放 .ts 助手（加载器会把平级文件当独立扩展）
-prompts/multi-viewers-setup.md  /multi-viewers-setup 建视角入口（建议→你定→落盘→给审）
+prompts/multi-viewers-setup.md  /multi-viewers-setup 建视角入口（建议→你定→**mv.sh --set-viewer** 落盘→给审）
+                           # 那四条本来写进 prompt 的纪律（命名/不覆盖/非空/校验）改由命令保证
 docs/design.md       设计文档（fork 源模式与规模口径 + 决策记录）
 package.json         npm 包 pi-multi-viewers（pi.prompts 注册；**版本号唯一事实源**）
 templates/           AGENTS.md.tpl / agent.md.tpl / gitignore.tpl / spec-readme.md.tpl
@@ -233,7 +235,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 
 ## 安装/发版状态（2026-09-11）
 
-- **当前形态**：prompt × 1（multi-viewers-setup 建视角）+ extension × 2
+- **当前形态**：prompt × 1（multi-viewers-setup 建视角）+ extension × 1（一单元注册三命令）
   ——一个扩展单元内注册三命令（`multi-viewers` 分析 / `multi-viewers-finish` 收尾 /
   `multi-viewers-say` 插话；前两个靠 CLI 机器标记行取值 `[prepare] spec=` /
   `[start] dir=` / `[start] watch=` / `[status]`，后者零 LLM 直接 spawn human_sayer.py；

package/README.md

@@ -112,15 +112,16 @@ scripts/mv.sh --view                          # 一次性增量查看（主 pi
 scripts/mv.sh --say "<文本>"                   # 插话（命令行形态；pi 内用 /multi-viewers-say）
 scripts/mv.sh --status                        # 状态 + 路径（取值与含义以该命令输出为准）
 scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM/档位对照；冷路径，不持久化）
-scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存到 <dir>-result.md）
+scripts/mv.sh --cleanup                       # 收尾（result.md + 报告都留存到 <dir>-*.md/.txt）
 scripts/mv.sh --viewers                       # 列出+校验当前项目 viewers/（只读；建视角时用）
+scripts/mv.sh --set-viewer <名字>             # 新建视角文件（正文从 stdin 读；只新建不覆盖）
 ```
 
 ## 视角文件写什么（`viewers/<视角名>.md`）
 
 建视角**推荐**走 `/multi-viewers-setup`（交互式：先给候选建议 → 你定建哪几个 →
-落盘 → 展示给你审）；也可以手写。写完用 `scripts/mv.sh --viewers` 自查（列出并
-用代码判据校验名字与空正文）。
+`--set-viewer` 落盘 → 展示给你审）；也可以手写，写完用 `scripts/mv.sh --viewers`
+自查（列出并用代码判据校验名字与空正文）。
 
 一个视角文件 = **一份视角说明**，纯内容、无格式要求（无 frontmatter、
 无需标题，**文件名就是全部元数据**）。三个要点（措辞经实验验证）：

package/docs/design.md

@@ -103,7 +103,7 @@ compaction 的 `firstKeptEntryId` 起 + 其后的条目"——窗口内含 compa
 | `status-<agent>.json` | loop | `{"sessionID": ...}` | 流程（崩溃恢复） | 是（恢复用） | O(1) |
 | `pi-sessions/fork-src-*.jsonl` | pi | 文档化 session schema（`usage`/`stopReason`/`timestamp`/`thinkingLevel`） | fork 构建 + `--report` | 否（报告用） | O(MB) 全量 → **禁轮询** |
 | `result.md`（固定位） | resultWriter loop | 结论文档 | 人 | 是（收尾判据） | — |
-| `--report`（视图） | observability | 文本行 | 人（**三个出口**，见下） | **否**（不得升级为验收 gate） | 冷路径一次性 —— **O(session 大小)**：每 agent 读整个 fork-src jsonl（实测 3 × 789KB ≈ 2.4MB/次、50–150ms/次，×3 出口 <0.3s/次分析），**不得进入任何轮询路径**（e2e16 评审量化） |
+| `--report`（视图） | observability | 文本行（`--cleanup` 另落盘 `<base>-report.txt`） | 人（**三个出口**，见下） | **否**（不得升级为验收 gate） | 冷路径一次性 —— **O(session 大小)**：每 agent 读整个 fork-src jsonl（实测 3 × 789KB ≈ 2.4MB/次、50–150ms/次，×3 出口 <0.3s/次分析），**不得进入任何轮询路径**（e2e16 评审量化） |
 
 **报告的字段集**（e2e17 评审后定稿，后续增补不计数——字段行以本表为准）——
 **谓词分组 + 对照 + 事实行**，
@@ -168,7 +168,7 @@ BOUNDARY_TYPE`）——**显式登记"历史（fork 携带）/ 本轮"的分界*
 
 **报告的打印位置**：`--report`（手动，任意时刻）+ `--cleanup` 前（自动，
 删目录前最后一次可读——目录删后 `--report` 不可用）。cleanup 层对报告
-fail-open（报告失败不阻断清理，且**打印**失败原因不静默）。
+fail-open（报告失败不阻断清理，且**打印**失败原因不静默）。报告随 `--cleanup` **落盘**一份到 `<base>-report.txt`（与 `-result.md` 同级）——原先只在终端出现一次，目录删掉后无法复查（复盘时长口径时踩到，用户 2026-09-25 定）。
 
 消费规则：`meeting_fs.iter_after_boundary` 只产出边界之后的条目；**未找到
 边界（老产物/手工 session）→ 返回空、按 n/a 处理，不得退回全文扫描**
@@ -567,19 +567,27 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     内容起草仍是真 LLM 工作（任务类型/产出形态），故为**两段式**——骨架零 LLM，
     起草/摘要走普通对话；门禁取消则保留 spec，用户编辑后自行 `mv.sh --start`。
     **收尾状态语义（2026-09-25 评审）**：`running` 等待；`done | stalled` 并流进
-    "notify → confirm → cleanup"（`stalled` = 无存活 loop 的静止态，照 running 处理
-    会让用户等一个永不到来的收尾）；`stopped` 只提示手动清理。`stalled` 用独立文案
-    （其 result 由清理时保存，不复用 done 的"已留存"路径文案）；扩展是唯一守卫
+    "notify → confirm → cleanup"（照 running 处理会让用户等一个永不到来的收尾）；
+    `stopped` 只提示手动清理。**状态定义以 `observability.check_status` 为单一
+    事实源**（`stalled` = 有 result.md、无 concluded、loop 均不存活）——此处不复述其判据。
+    `stalled` 用独立文案（其 result 由清理时保存，不复用 done 的"已留存"路径文案）；扩展是唯一守卫
     （CLI 的 cleanup 无状态防护）。**本轮明确不做**（防翻案）：`--json` 输出模式、
     resume 新命令面、env 回退配置、`runCli` 超时、启动路径继续优化（已在 1–2s 地板）、
     给 stalled 加第三种动作。**契约例外**：扩展作为包内第一方消费者**直连**
     `mv_cli.py`（实测 shim 61ms vs 直连 58–66ms，性能上零差异；按契约一致性记例外一行）。
-      **UI 通道按 mode 分级（2026-09-25 实测）**：dialog（`select`/`confirm`/`input`/`editor`）
-      全模式可用（RPC/web 走请求-响应子协议、阻塞等用户；不带 `timeout` 即不倒计时，
-      暂停点成立）；`notify` 全模式可用（TUI = showStatus 行；pi-web = **追加进聊天流的
-      常驻行**，非瞬时提示）；**`setEditorText` 仅 TUI**——pi-web 忽略（`pi-web/static/app.js`
-      注释「set_editor_text … ignored」+ SDK `ui-context.ts` 里是空实现）。⇒ **交付观看命令
-      必须有 notify 兜底**（预填只是增强，不能当唯一出口）；需要分级时用 `ctx.mode`。
+    **建视角流程（`/multi-viewers-setup`，仍是 prompt）**：机械部分下移到
+    `mv.sh --set-viewer <名字>`（正文从 stdin 读）——**命名规则 / 不覆盖已有 / 空正文拒绝 /
+    写完校验并回显**四条由命令保证（此前是 prompt 里给 LLM 的纪律，会漏）；prompt 只负责
+    **看项目给候选 + 内容撰写 + 与用户来回**（那才是 LLM 该做的）。
+    **UI 通道按 mode 分级（2026-09-25 实测）**：dialog（`select`/`confirm`/`input`/`editor`）
+    全模式可用（RPC/web 走请求-响应子协议、阻塞等用户；不带 `timeout` 即不倒计时，
+    暂停点成立）；`notify` 全模式可用（TUI = showStatus 行；pi-web = **追加进聊天流的
+    常驻行**，非瞬时提示）；**`setEditorText` 仅 TUI**——pi-web 忽略（`pi-web/static/app.js`
+    注释「set_editor_text … ignored」+ SDK `ui-context.ts` 里是空实现）。⇒ **交付观看命令
+    必须有 notify 兜底**（预填只是增强，不能当唯一出口）；需要分级时用 `ctx.mode`。
+    但 pi-web 实测**关掉 notify 弹窗即消失** ⇒ 观看命令还写一条 `pi.sendMessage`
+    （`customType: multi-viewers`、`display: true`）进消息流：持久可回滚复制，
+    代价 = 参与 LLM 上下文的一行（用户 2026-09-25 要求「message 流中也能显示」）。
     被否决：A（handler 里 `sendUserMessage` 触发 LLM 回合改 spec——时序不可控）、
     D（拆两条命令——把门禁成本转嫁用户；B1 变体/第三种即现形态）。
 

package/docs/reviews/2026-09-25-multi-viewers-postfix-review.md

@@ -0,0 +1,211 @@
+<!-- 存档：docs/reviews/2026-09-25-multi-viewers-postfix-review.md
+     来源：一次真实多视角分析的 result.md 原文（未删改，仅加本头与下方说明）。
+     分析场次目录已随 cleanup 删除；文中消息编号（如 效率/0012、铁律/0004）不可再核验，
+     仅作溯源线索（与代码注释引用约定一致：行为以自描述为准）。 -->
+
+# 存档说明
+
+- **主题**：复验 0.8.0 这批改动 —— extension 合并后的实现（一单元三命令）、
+  P1–P6 修复是否到位、扩展层 harness 的覆盖是否有漏
+- **场次**：`mv-mv-main-20260925-105614`（3 视角：效率 / 简单 / 铁律；真实 pi 讨论，
+  默认档 `mc-tools`、`forkMode=budget`、`maxMeeting=15`；三方共识收敛）
+- **复验判定**：P1–P6 **逐条到位**；合并（P5）判定**净简化**（`findPackageRoot`
+  全仓 1 定义 1 调用、旧目录不存在）；**未触碰唤醒路径** → 分析总时长期望零变化
+- **本场新抓（多数是上一批引入的）**：
+  - **漏 A（最重要，接线 bug）**：`run_tests.sh --reuse` 的错误成功信号 ——
+    `last_ok()` 只扫任意一行 `^OK`，而 harness 输出追加在 python 的 OK 之后 →
+    harness 失败时它仍为真；指纹又无条件写 → 下次 `--reuse` 命中并 exit 0 而日志含失败。
+    修法 **②′**：真跑前清指纹、`rc==0` 才写回（不变式「指纹存在 ∧ 匹配 ⇒ 最近同源真跑全绿」）。
+    本仓落地时做了同款三连红绿验证（全绿→指纹在；环境性失败→rc=1 且指纹已清；随后
+    `--reuse` 必须未命中→真跑）
+  - **D2**：启动通知「已预填进输入框」在 pi-web 为**不实断言**（`setEditorText` 仅 TUI）
+  - **B1**：`mv_cli.py` 两条人类行复用 `[start]` 契约前缀；**B2**：五处出路提示引用裸
+    `mv.sh`（不在 PATH 上，出路不可执行）
+  - **7 类现存分支零覆盖** + 两项装置缺口：**sid 注入零断言**（漏注入 = say/finish
+    静默定位失败而全绿）、harness 的 `new URL().pathname` 不还 percent-encoding
+  - **D1/D3** 文档漂移（AGENTS「extension × 2」；决策 22 复述 stalled 判据）
+- **落地**：`69a415a`（六文件一次收口；harness 28 → 44 断言，含 sid 装置与
+  `findPackageRoot` 直断 throw；先红后绿：去掉 sid 注入 → 3 条断言失败）
+- **本场暴露的用户可见事实**（不在代码里）：① 门禁暂停点**真的停住**（用户实测）；
+  ② pi-web 的 `notify` **关掉弹窗即消失** → 后续加第三交付出口
+  `pi.sendMessage`（custom_message 进消息流，`e92eacc`）
+
+# 0.8.0 复验 · 三方共识结果
+
+**主题**：复验 0.8.0 这批改动：extension 合并后的实现（一单元三命令）、P1–P6 修复是否到位、
+扩展层 harness 的覆盖是否有漏——只提意见，不改代码。
+**参与者**：效率 / 简单 / 铁律（3 视角；meeting 自由讨论 + round-robin 全体 pass）。
+**方法**：只读核对、每项带 `文件:行`；零 LLM 验证（harness 实跑、/tmp 逐字复刻门逻辑复现、
+grep/源码核对）；**未修改任何文件、未运行真实分析**。
+**场次**：`mv-mv-main-20260925-105614`（fork 模式 budget；mc-tools 档）。
+
+---
+
+## 0. 结论摘要
+
+1. **P1–P6 行为修复逐条到位，合并（P5）判定为净简化**：`extensions/multi-viewers/` 现为单一
+   单元、三命令（`index.ts` + `shared.ts`），逐字重复消失；**未触碰唤醒路径**
+   （48–82s/唤醒的大头一行未改，agent 注入内容未变）→ 分析总时长期望零变化，收益落在
+   人类交互层与维护期（效率/0001）。
+2. **本场共发现**：2 处新缺陷（漏 A：`--reuse` 错误成功信号；漏 B：P4 加载期分支无覆盖）、
+   3 处设计符合度偏差（D1/D2/D3）、2 处职责边界问题（B1/B2）、7 类 harness 覆盖漏 +
+   2 项装置缺口（sid 断言、percent-encoding）。**其中漏 A 的完整修法 ②′ 是本场最重要产出**
+   （三方认账，效率/0012、简单/0012）。
+3. **②′（铁律 0004 §二）**：`run_tests.sh` 的"失败不写指纹"（原方案②）**不能消除漏 A**——
+   同源码环境性失败会残留旧绿指纹，`--reuse` 仍命中 exit 0 而日志含失败（已复现）。
+   完整修法 = 真跑开始前 `rm -f "$FP_FILE"`、结束 `rc -eq 0` 才写回（:90 现为无条件写）。
+   不变式「指纹存在 ∧ 匹配 ⇒ 最近一次同源真跑全绿」，单一 rc 判据、零文本解析、覆盖中断。
+4. **净复杂度账为正（变简）**：S1 消 ≈35–50 行同构 spawn 样板、S2/S3 消软分支与 no-op、
+   批量条目多为 1–6 行改动；本批**零新装置**（新增能力仅 = 假 python3 多记一个 env 变量 +
+   导出 1 个函数 + 一个字符串常量）。
+5. **执行**：六文件一次编辑 → 一次 `/reload` → **约 5 分钟验证**（`run_tests.sh --force` +
+   零 LLM 门禁路径 + ②′ 红绿 ~10s）；**不专门真跑**（改动不触唤醒路径/协议注入/分析逻辑）。
+
+---
+
+## 1. 复验判定（0.8.0 本批 = dfe71cc 合并与 P1–P6）
+
+| 项 | 判定 | 依据（抽核） |
+|---|---|---|
+| **P1** stalled 并流 | ✓ 到位 | `index.ts` 状态分派：running 早退，`done｜stalled` 并流到 confirm→cleanup；harness 断言 stalled 不再落 running |
+| **P2** stalled 独立文案 | ✓ 到位 | stalled 不复用 done 的 result 路径文案；harness 断言不含 done fallback 文本 |
+| **P3** 删与暂停点矛盾的旧注释 | ✓ 到位 | 文件头现为「取消则不启动并保留 spec」，无「先取消再自行 start」旧句 |
+| **P4** 删单机回退、加载期响亮失败 | ✓ 到位 | 全仓 `FALLBACK_ROOT` 0 命中；`shared.ts` 找不到包根即 throw（行动性信息）；覆盖缺口见 §2.2 |
+| **P5** 合并为一单元三命令 | ✓ 到位 | `findPackageRoot` 全仓 1 定义 1 调用；旧 `multi-viewers-say/` 目录不存在 |
+| **P6** 取消提示 + harness 进仓库 | ✓ 到位 | 取消提示含「当前 pi session 内」；`tests/extension_harness.ts` 被 `run_tests.sh` 接入（缺 bun 可见跳过、`MV_REQUIRE_BUN=1` 严格、失败置 rc=1） |
+
+**复验实测**：harness **28 通过 / 0 失败**（口径更正：效率/0001 的 29 = `grep -c 'check('`
+含 1 处函数定义；运行汇总为 28）；harness 墙钟 **0.113–0.155s**（3 次，本机）——占全量
+（~250s 口径）≈0.05%，"反对 unittest↔harness 并行"由预测变为数据支撑。
+
+---
+
+## 2. 本场新发现（按类别）
+
+### 2.1 漏 A：`--reuse` 的错误成功信号 → 修法 ②′（最重要）
+
+- **机制**：`last_ok()` 只扫全日志任意一行 `^OK`（`run_tests.sh:50`），harness 输出**追加**在
+  python `OK` 之后 → harness 失败时 `last_ok` 仍真；指纹无条件写（`:90`）→ 下次 `--reuse`
+  命中（`:56-57`）并 **exit 0** 而缓存日志含 harness 失败。
+- **原方案②的残余洞（铁律 0004 复现）**：仅"失败不写指纹"时，**同源码环境性失败**
+  （`MV_REQUIRE_BUN=1` 缺 bun / 中断 / harness 并发）会残留上一轮旧绿指纹 → 仍命中 exit 0。
+  已用**逐字复刻的门逻辑**在 /tmp 复现（`→ REUSE 命中：exit 0（而 LAST_LOG 含 harness 失败）`）。
+- **②′**：真跑前 `rm -f "$FP_FILE"`；结束 `rc -eq 0` 才写回。`last_ok` 可留但**不能当 ② 的
+  替代**（它挡不住本反例）；②′ 后其定位退为"遗留指纹/篡改面"。
+- **红绿核验（3 条命令，同参数隔离源指纹）**：① module 全绿 → FP 存在；②
+  `env PATH=/usr/bin:/bin MV_REQUIRE_BUN=1` 同参数跑 → rc=1 **且 FP 不存在**；③ `--reuse`
+  → 必须"未命中→真跑"（现状会命中 exit 0）。
+- **三方裁决**：效率/0012、简单/0012 均认账采纳（补洞 + 单一 rc 判据 + 覆盖中断）。
+
+### 2.2 漏 B：P4 加载期失败分支无覆盖 → 内联（可裁）
+
+- `findPackageRoot` 未导出（`shared.ts:29`），harness 内 import 成功即无法触发；子进程负例
+  需**复制** `shared.ts` → 违反「测试对象 = 生产对象」（副本漂移）。
+- **裁定**：导出该函数直调、**只断言 throw**（至多含稳定标识 `pi-multi-viewers`）、不锁散文；
+  **残差明账**（锁函数、不锁加载期接线；坏掉症状=三命令消失，响亮）。
+- **内联本批**（不做事后追加：验证是批次级成本，事后追加=第二次验证循环）；优先级低，若砍
+  则记账留与下次改动同批（效率/0007 自我更正）。
+
+### 2.3 设计符合度偏差（D1/D2/D3）
+
+- **D1**:`AGENTS.md:236`「extension × 2」未随 P5 合并同步（同段已写"一个扩展单元内注册
+  三命令"）；`git show dfe71cc` 证实该行未动——"改了实现忘改抄本"的漂移。简单认领，改一行。
+- **D2**:启动通知「已预填进输入框，按 Enter 执行」在 **pi-web 为不实断言**
+  （决策 22:577-581 已写明 `setEditorText` 仅 TUI；复核 `pi-web/static/app.js:1907`、
+  `ui-context.ts:456` 空实现）——与 0.8.0 首用事故（预填被忽略）同源。
+  **修法：中性单串**（如「复制执行；TUI 下已预填」），**不引 `ctx.mode` 分支**（无 mock/断言
+  增量，断言体零改动，仅标签措辞随统一改名处理）；`setEditorText` 调用保留（TUI 增强）。
+- **D3**:决策 22:570 对 `stalled` 的复述（"无存活 loop 的静止态"）宽于单一事实源
+  （`observability.check_status`：**有 result.md**、无 concluded、loop 均不存活）——按字面
+  把 `stopped` 也涵盖。**扩展文案不改**（正常路径恒真），**决策 22 引用化**。
+  - **边界观察（简单/0007 读码定案，不进本批）**：status 判"有结果"看 `git log --all`，而
+    `preserve_result_md` 读 `HEAD:result.md`（`meeting_fs.py:1238`）→ 侧分支/删除场景可达性低；
+    **将来统一必须偏 loud**（危险方向 = 清理静默丢产物），不得选静默侧。
+
+### 2.4 职责边界问题（B1/B2）
+
+- **B1**:`mv_cli.py:368/371` 两条人类行复用 `[start]` 契约前缀且带路径（唯一契约清单外同前缀
+  行）——"方括号=机器契约"被稀释。修法：**去方括号**（非新增 `[spec]` 前缀）；已核
+  `test_mv_cli.py:312` 只断子串、零测试连锁。
+- **B2**:`index.ts:67/72/86/129/198` 五处出路提示引用裸 `mv.sh`，而 `which mv.sh` 为空、
+  README:55 教的是安装绝对路径 → 出路不可执行。修法：`shared.ts` 增**常量**
+  `MV_SH = \`bash ${PACKAGE_ROOT}/scripts/mv.sh\``，五处引用（PACKAGE_ROOT 现为模块私有，
+  常量化非抽象层）。
+
+### 2.5 harness 覆盖漏与装置缺口
+
+**漏场景（7 类，均为现存分支）**：① MV `!specDir`（rc=0 无 `[prepare] spec=`）② MV
+`!watch` ③ FIN 状态读取失败整支 ④ FIN cleanup 失败 ⑤ SAY find-dir 成功 + sayer 失败
+⑥ SAY 空输出（"插话已发送"）⑦ `[start] dir=` 缺失（按 §3-S2 定案 (b) 写作"→ 报错"）。
+补方式按"追加用例"（两处必然例外：S2 改成功夹具、sid 装置改 calls 输出格式）；断言名带
+分支标识（替代另立清单表——清单=第二抄本必漂移）；现有断言一并统一改名（纯改名零行为）。
+
+**装置缺口（本场新增两项）**：
+- **sid 传递零断言**：假 python3 只记 argv（`harness:25-31`）；sid 是 `mv-<sid>-*` 命名与
+  find-dir 的唯一钥匙，漏注入 = say/finish **静默定位失败**而 28 条全绿 → 假装置多记
+  `$PI_SESSION_ID` + 各命令断言（**升为防静默同级**）。
+- **`HERE = new URL(…).pathname`**（`harness:18`）不还原 percent-encoding——实测把
+  `extensions/` 与 harness 复制到 `/tmp/space test/repo` 运行即报
+  `Cannot find module '/tmp/space%20test/repo/…'`；改 `fileURLToPath`（与生产 `shared.ts`
+  同处理）。
+
+---
+
+## 3. 冻结的批次清单（六文件、一次收口）
+
+**编辑顺序**（依赖者后写；S1 与 harness 无强依赖，真依赖仅 S2→#7 场景、D2 措辞→标签文案）：
+
+1. `extensions/multi-viewers/shared.ts`：S1 三 spawn 样板合一（原语 ≤~15 行、三调用点语义
+   逐一保留：stderr 合并与否 / rc vs ok / env 差异；**不顺手给 sayer 注入 sid**——现语义照抄）
+   + `MV_SH` 常量 + 漏 B 导出（+头注释契约行同步）
+2. `mv_cli.py`：S2 定案 **(b)**（`!dir` 并入 guard，删三元；dir 契约项保留）+ B1 去方括号
+3. `extensions/multi-viewers/index.ts`：D2 中性文案 + B2 用 `MV_SH` + S3 删三处
+   `getArgumentCompletions: () => null`（`argumentHint` 保留——上游扩展命令映射未转发，
+   留着将来生效）
+4. `tests/test_mv_cli.py`：S2 断言微调（如需）
+5. `tests/extension_harness.ts`：7 类场景 + sid 装置/断言 + `fileURLToPath` + 断言名统一
+   （含现有断言）+ 漏 B 用例（导出直调、只断 throw）
+6. `tests/run_tests.sh`：漏 A **②′**（真跑前清指纹 + `rc==0` 才写回）
+
+**文档两行**：D1（`AGENTS.md:236`）、D3（决策 22 引用化）。**可裁顺序**：A 防静默 → B 用户
+可见 → C 文档 → D 简化（漏 B 用例可裁，但要砍则记账留与下次同批）。
+
+**批次约束**：零新装置、不触碰唤醒路径；验证 = `run_tests.sh --force`（~250s）+ `/reload`
+零 LLM 走"假主题到门禁取消"（数十秒，顺带见到 D2/B2 新文案）+ ②′ 红绿（~10s）。
+
+---
+
+## 4. 明确不做 / 边界记录
+
+- **不专门真跑**本批（改动全在扩展/CLI 人类输出/测试/文档层；不触唤醒路径与协议注入）。
+- `last_ok()` 本批**不动**（对修复前遗留指纹有保护面；其精简留待下批评估）。
+- **stalled+取消** 场景低价值可裁（两表均未列）。
+- D3 的 `--all` vs `HEAD` 判据分叉：记为边界观察，**不进本批**；将来统一偏 loud。
+- S2 的 (a)（删 `[start] dir=`）**留作将来因其它原因动契约时的清理候选**（本批不划算：
+  7–8 处连锁 + doc×3 漂移面；简单/0008、效率/0008 均持此记录）。
+- `argumentHint` 上游未转发：保留，随上游补丁生效（不属本仓缺口）。
+
+---
+
+## 5. 收敛过程（消息索引）
+
+- **效率**（0001–0012）：墙钟四层账（唤醒是大头、extension 层非瓶颈）+ 省时账（P1 最大、
+  harness 性价比最高）+ 反对常驻/框架/并行/再弹 dialog；发现漏 A 并给出两方案 → 认账转 ②；
+  对漏 B"导出 vs 子进程"更正为内联；提供批内编辑顺序与"不专门真跑"验证分级；0002 提出
+  "补场景必须与修 `last_ok` 同批"的联动点。
+- **简单**（0001–0012）：S1/S2/S3 三处简化主张（spawn 样板合一、dir 半必填二选一、
+  删 no-op 字段）+ 反对过度抽象三条 + harness 覆盖表 + 主张"断言名带标识替代清单表"；
+  读码定案 D3（`--all`/`HEAD` 分叉，比两边原表述更细）；B2 提出 `MV_SH` 常量；
+  在 S2 (b)/(a) 与漏 B 口径上随证据两度更新立场。
+- **铁律**（0001–0007）：首轮以三条铁律逐项检视（P1–P6 到位 + D1/D2/D3 + B1/B2 + harness
+  六类 + 两项装置缺口）；裁决漏 B（导出+只断 throw）、漏 A（②）、S2 语义、S1 验收三条；
+  认账并裁定 S2 定案 **(b)**；**发现并复现 ② 的残余洞，给出完整修法 ②′**（本场最重要产出）；
+  复核 D2/D3 并记录 loud 方向；round-robin pass 收口。
+
+---
+
+## 6. 一句话结论
+
+**0.8.0 的合并与 P1–P6 修复复验通过（harness 28/28、零行为反例）；需在下一批补齐
+②′（漏 A 完整修法）、7 类覆盖漏与 sid/路径两装置缺口、以及 5 处文案/文档偏差（D1/D2/D3、
+B1/B2）——全部为 1–6 行级、零新装置、不触唤醒路径，一次收口 + 约 5 分钟验证即可。**

package/docs/reviews/README.md

@@ -11,6 +11,9 @@
    真实缺陷（见下）。
 2. **决策溯源**：修复批次（commit）常引用报告中的编号（如"P0/P1/P2"），
    保留原文才能核对当时的事实与推理。
+
+归档动作的**机械部分**由 `scripts/archive-result.sh` 做（命名、正文逐字复制+字节校验、
+存档头骨架、索引行、删仓库根松散副本）——判断部分（主题/问题/commit）仍由人写。
 3. **方法论的样本**：报告本身演示了"观察句 vs 机制句"的证据强度要求
    （`docs/test-methodology.md` 方法 16）——其中也有几处机制句在讨论中被
    交叉复核推翻，是活教材。
@@ -33,6 +36,7 @@
 | `2026-09-14-e2e24-extension-policy-review.md` | 扩展策略三档（默认 mc-tools）的实现与证据链 + `ctx_search` 价值评估 | **S1：缺 MC 的降级路径提前 return → 命令被截断（缺 model/print/注入、cwd 错）**；S1a 测试判别力不足；E2 报告缺"声明 vs 生效"；E1 成本口径超出精度；T1–T3 文本矛盾；F5/F6/F7/S2/F9 解析链缺陷；**ctx_search 9 次调用全为问卷诱导、0 次决定性帮助、命中 1 条过期记忆** | `91a1171`（Batch 1+3）、`b9329fb`（Batch 2 删死代码）|
 | `2026-09-14-e2e25-doc-drift-review.md` | 文档 vs 代码一致性（文档漂移）+ ctx_search 的**自然使用**观察 | **三处文档仍写"兜底 mv-* 并警告"而代码是无兜底、未匹配报错**（行为语义相反）；README 缺 `--extension-policy`；报告字段列表过期；4 条缺失项；**根因 = 对实现的复述**（治本：引事实源不复制）；自然使用观察：`ctx_search` **0 次**、historian 0 次 | `ba204ef` |
 | `2026-09-25-multi-viewers-extension-review.md` | 把 `/multi-viewers` 改成 extension 这次的实现（extension 代码 / CLI 机器标记行契约 / 文档同步） | **P1：`stalled` 被当成 running → 让用户等一个永不到来的收尾**（唯一行为错误）；P2 `[result]` 只在 done 打印；P3 头注释与暂停点自相矛盾；P4 `/root/pi-multi-viewers` 单机死回退；P5 两扩展逐字重复 ≈35 行且已漂移（→ 合并为一单元三命令）；P6 取消提示缺 sid 提醒 + **扩展消费端零仓库内测试**；首用另暴露：主题带引号、观看命令只有预填一个出口 | 本批（合并 + P1–P6 + 首用两项 + harness 进仓库） |
+| `2026-09-25-multi-viewers-postfix-review.md` | 复验 0.8.0 的 extension 合并与 P1–P6（含 harness 覆盖审查） | **P1–P6 逐条到位、合并净简化**；新抓 **漏 A：`run_tests.sh --reuse` 的错误成功信号**（harness 失败仍算绿 → 命中旧绿 + exit 0，修法 ②′ 清指纹 + rc==0 才写回）；D2 通知里的不实断言（pi-web 忽略 `setEditorText`）；B1/B2 契约前缀与不可执行出路；7 类现存分支零覆盖 + sid 注入与 percent-encoding 两装置缺口；D1/D3 文档漂移；S1–S3 简化 | `69a415a`（+ `e92eacc` 第三交付出口） |
 
 ## 环境口径（读报告时的背景）
 

package/extensions/multi-viewers/index.ts

@@ -16,14 +16,17 @@
  *
  * 与 CLI 的契约（标记行/退出码）与全部原语见 ./shared.ts。
  *
- * 观看命令交付 = `ctx.ui.setEditorText` 预填输入框（按 Enter 即执行）**并**
- * 在 notify 里带一份（预填会被后续输入覆盖——只留预填这一个出口，用户就
- * 再也找不到它；2026-09-25 首次真实使用暴露）。
+ * 观看命令交付 = **三个出口**（缺一不可，都是实测暴露的）：
+ * ① `ctx.ui.setEditorText` 预填输入框（按 Enter 即执行；**仅 TUI**，pi-web 忽略）
+ * ② `notify` 带一份（即时可见；但 pi-web 上关掉弹窗即消失）
+ * ③ `pi.sendMessage` 写一条 custom_message 进消息流（**持久可回滚复制**；
+ *    代价 = 参与 LLM 上下文的一行）
  */
 
 import {
   findCurrentDir,
   grab,
+  MV_SH,
   runCli,
   runSayer,
   specListing,
@@ -35,7 +38,6 @@ export default function register(pi: any) {
   pi.registerCommand("multi-viewers", {
     description: "多视角协同分析：生成 spec → 你审阅 → 启动（零 LLM 流程）",
     argumentHint: "<主题>",
-    getArgumentCompletions: () => null,
     handler: async (args: string, ctx: any) => {
       const topic = stripQuotes(args.trim());
       if (!topic) {
@@ -64,12 +66,12 @@ export default function register(pi: any) {
         "启动多视角分析？（现在暂停中，可在其它窗口修改 spec）",
         `spec：${specDir}\n文件：${specListing(specDir)}\n\n` +
           "需要修改就去改这个目录，改完点「确认」继续；\n" +
-          "点「取消」则不启动（spec 保留，可稍后 mv.sh --start）。",
+          "点「取消」则不启动（spec 保留，可稍后 " + MV_SH + " --start）。",
       );
       if (!go) {
         ctx.ui.notify(
           `已取消，spec 保留在：${specDir}\n` +
-            `之后可在**当前 pi session 内**用：mv.sh --start ${specDir}\n` +
+            `之后可在**当前 pi session 内**用：${MV_SH} --start ${specDir}\n` +
             "（外部终端执行时目录名不带 session id，插话/收尾命令定位不到它）",
           "info",
         );
@@ -80,20 +82,29 @@ export default function register(pi: any) {
       const start = await runCli(["--start", specDir], cwd, sid);
       const watch = grab(start.output, "[start] watch=");
       const dir = grab(start.output, "[start] dir=");
-      if (start.rc !== 0 || !watch) {
+      if (start.rc !== 0 || !watch || !dir) {
         ctx.ui.notify(
           `启动失败：\n${start.output || "(无输出)"}\n` +
-            "可用 mv.sh --status 查看环境状态。",
+            "可用 `" + MV_SH + " --status` 查看环境状态。",
           "error",
         );
         return;
       }
 
-      // ④ 观看命令：预填进输入框 + notify 里留一份副本（见文件头）
+      // ④ 观看命令：三个出口（见文件头）——预填（仅 TUI）+ notify（即时）+ 消息流（持久）
       ctx.ui.setEditorText(watch);
+      // 消息流里留一条持久记录：用户实测 pi-web 的 notify 会随弹窗关闭而消失，
+      // 关了窗口就再也找不到这行命令。custom_message 进会话（**参与 LLM 上下文**，
+      // 一行开销），在用户空闲时追加 → 立即显示、可回滚复制（agent-session.ts:
+      // 非 streaming + 无 triggerTurn → _appendCustomMessage，不触发回合）。
+      pi.sendMessage({
+        customType: "multi-viewers",
+        content: `多视角分析已启动：${dir}\n观看命令（复制执行，不进 LLM）：\n${watch}`,
+        display: true,
+      });
       ctx.ui.notify(
-        `分析已启动${dir ? `：${dir}` : ""}\n` +
-          "观看（已预填进输入框，按 Enter 执行；也可复制这行）:\n" +
+        `分析已启动：${dir}\n` +
+          "观看（复制执行；TUI 下已预填进输入框）:\n" +
           `${watch}\n` +
           "插话：/multi-viewers-say <文本>　收尾：/multi-viewers-finish",
         "success",
@@ -104,7 +115,6 @@ export default function register(pi: any) {
   // ---------------------------------------------------------------- 收尾
   pi.registerCommand("multi-viewers-finish", {
     description: "收尾：查状态 → 确认 → 清理分析目录（结果留存；摘要走对话）",
-    getArgumentCompletions: () => null,
     handler: async (_args: string, ctx: any) => {
       const sid = ctx.sessionManager.getSessionId();
       const st = await runCli(["--status"], ctx.cwd, sid);
@@ -126,7 +136,7 @@ export default function register(pi: any) {
       if (state === "stopped") {
         ctx.ui.notify(
           "分析已结束但未生成结果（状态 stopped）。" +
-            "要清理请自行运行 mv.sh --cleanup。",
+            "要清理请自行运行 `" + MV_SH + " --cleanup`。",
           "warning",
         );
         return;
@@ -179,7 +189,6 @@ export default function register(pi: any) {
   pi.registerCommand("multi-viewers-say", {
     description: "向正在进行的多视角分析插话（human 消息，各视角可见可回应）",
     argumentHint: "<插话内容>",
-    getArgumentCompletions: () => null,
     handler: async (args: string, ctx: any) => {
       const text = args.trim();
       if (!text) {
@@ -195,7 +204,7 @@ export default function register(pi: any) {
         ctx.ui.notify(
           "本 session 没有正在进行的多视角分析（cwd 下无 " +
             `mv-${sid}-* 分析环境）。先用 /multi-viewers 启动，` +
-            "或改用 mv.sh --say <目录> \"<文本>\" 显式指定。",
+            "或改用 `" + MV_SH + " --say <目录> \"<文本>\"` 显式指定。",
           "error",
         );
         return;

package/extensions/multi-viewers/shared.ts

@@ -25,8 +25,11 @@ const PKG_NAME = "pi-multi-viewers";
  *  **找不到就响亮失败**（评审 P4）：此前回退到 `/root/pi-multi-viewers` 是单机
  *  死分支——触发条件（包被拆散/复制）恰恰发生在开发机以外，回退只会把"包根
  *  解析失败"变成更晚、更难诊断的失败。这里在**加载期** throw，错误信息给出行动。
+ *
+ *  导出仅供测试直调（断言 throw；不锁散文措辞）——加载期接线本身无覆盖，
+ *  残差明账：坏掉时症状 = 三个命令消失（响亮）。
  */
-function findPackageRoot(start: string, pkgName: string): string {
+export function findPackageRoot(start: string, pkgName: string): string {
   let dir = start;
   for (let i = 0; i < 8; i++) {
     try {
@@ -52,26 +55,48 @@ const CLI = path.join(PACKAGE_ROOT, "mv_cli.py");
 const SAYER = path.join(PACKAGE_ROOT, "human_sayer.py");
 const OBSERVABILITY = path.join(PACKAGE_ROOT, "observability.py");
 
-/** 运行 mv_cli 一条命令；返回 { rc, output }（stdout+stderr 合并）。 */
-export function runCli(
+/** 稳定的 CLI 入口（给用户的出路提示用）——裸 `mv.sh` 不在 PATH 上，
+ *  按此常量给绝对路径（评审 B2：出路必须可执行）。 */
+export const MV_SH = `bash ${PACKAGE_ROOT}/scripts/mv.sh`;
+
+/** 跑一次子进程并收输出。三处调用点的差异全部显式化（合并前是三份样板）：
+ *  `sid` 决定是否注入 PI_SESSION_ID（目录名与 find-dir 的唯一钥匙）；
+ *  `mergeStderr` 决定 stderr 是否并进同一缓冲（不并时必须 resume 掉，否则管道满阻塞）。 */
+function capture(
   args: string[],
-  cwd: string,
-  sid: string,
-): Promise<{ rc: number; output: string }> {
+  opts: { cwd?: string; sid?: string; mergeStderr?: boolean } = {},
+): Promise<{ code: number; output: string }> {
   return new Promise((resolve) => {
-    const proc = spawn("python3", [CLI, ...args], {
-      cwd,
-      env: { ...process.env, PI_SESSION_ID: sid },
+    const env = opts.sid
+      ? { ...process.env, PI_SESSION_ID: opts.sid }
+      : process.env;
+    const proc = spawn("python3", args, {
+      cwd: opts.cwd,
+      env,
       stdio: ["ignore", "pipe", "pipe"],
     });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", (d) => (out += d.toString()));
-    proc.on("close", (code) => resolve({ rc: code ?? 1, output: out.trim() }));
-    proc.on("error", (e) => resolve({ rc: 1, output: String(e) }));
+    let output = "";
+    proc.stdout.on("data", (d) => (output += d.toString()));
+    if (opts.mergeStderr) {
+      proc.stderr.on("data", (d) => (output += d.toString()));
+    } else {
+      proc.stderr.resume(); // 丢弃但必须消费
+    }
+    proc.on("close", (code) => resolve({ code: code ?? 1, output }));
+    proc.on("error", (e) => resolve({ code: 1, output: String(e) }));
   });
 }
 
+/** 运行 mv_cli 一条命令；返回 { rc, output }（stdout+stderr 合并）。 */
+export async function runCli(
+  args: string[],
+  cwd: string,
+  sid: string,
+): Promise<{ rc: number; output: string }> {
+  const r = await capture([CLI, ...args], { cwd, sid, mergeStderr: true });
+  return { rc: r.code, output: r.output.trim() };
+}
+
 /** 取机器可读标记行的值（`[label] value`）；没有 → null。 */
 export function grab(output: string, label: string): string | null {
   for (const line of output.split("\n")) {
@@ -116,37 +141,21 @@ export function specListing(specDir: string): string {
  *  判据 = **退出码**（不是 stderr 文案——中文提示一改就静默失配，e2e16 F2）：
  *  rc 0 → stdout 是绝对路径；rc 1 → 未找到（无同 sid 分析）。无降级通道
  *  （不会回退到"项目下最新"——那会插错分析，e2e16 F1）。 */
-export function findCurrentDir(cwd: string, sid: string): Promise<string | null> {
-  return new Promise((resolve) => {
-    const proc = spawn("python3", [OBSERVABILITY, "--find-dir"], {
-      cwd,
-      env: { ...process.env, PI_SESSION_ID: sid },
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", () => {}); // 原因只在 rc=1 时通知用户（见 handler）
-    proc.on("close", (code) => {
-      const dir = out.trim();
-      resolve(code === 0 && dir ? dir : null);
-    });
-    proc.on("error", () => resolve(null));
-  });
+export async function findCurrentDir(
+  cwd: string,
+  sid: string,
+): Promise<string | null> {
+  const r = await capture([OBSERVABILITY, "--find-dir"], { cwd, sid });
+  const dir = r.output.trim();
+  return r.code === 0 && dir ? dir : null;
 }
 
-/** 执行 human_sayer.py 一次插话。返回 { ok, output }。 */
-export function runSayer(
+/** 执行 human_sayer.py 一次插话。返回 { ok, output }。
+ *  现语义照抄（不注入 sid——sayer 用显式目录参数）。 */
+export async function runSayer(
   dir: string,
   text: string,
 ): Promise<{ ok: boolean; output: string }> {
-  return new Promise((resolve) => {
-    const proc = spawn("python3", [SAYER, dir, text], {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", (d) => (out += d.toString()));
-    proc.on("close", (code) => resolve({ ok: code === 0, output: out.trim() }));
-    proc.on("error", (e) => resolve({ ok: false, output: String(e) }));
-  });
+  const r = await capture([SAYER, dir, text], { mergeStderr: true });
+  return { ok: r.code === 0, output: r.output.trim() };
 }

package/meeting_fs.py

@@ -47,6 +47,17 @@ def result_path(base):
     """
     return f"{base}-{RESULT_MD}"
 
+
+def report_path(base):
+    """分析报告的固定落盘位（`<分析目录>-report.txt`，与 result.md 同级）。
+
+    报告原本只在 `--cleanup` 时往终端打一次，目录一删就再也拿不到——复盘
+    （时长口径、配额、provider 失败这类）时无据可查（用户 2026-09-25 复盘
+    回算不出实际时长，正是此缺口）。观测数字应当可复查，故随清理落盘一份。
+    `--report` 命令本身仍不持久化（冷路径视图，三个出口共享同一实现）。
+    """
+    return f"{base}-report.txt"
+
 # 协议参数默认值（gen_protocol 固化进 protocol.json）——**唯一声明点**：
 # CLI default、engine 签名默认、observability 的兜底读取都引用这里
 # （此前 10/7 在三处各写一遍，改一处不改另一处就会漂移）。

package/mv_cli.py

@@ -54,6 +54,7 @@ USAGE = f"""用法:
   {PROG} --view    [dir] [--since <ref>]
   {PROG} --say     [dir] "<文本>"
   {PROG} --viewers                           # 列出并校验当前项目的 viewers/（只读；建视角时用）
+  {PROG} --set-viewer <名字>                 # 新建一个视角文件（正文从 stdin 读；只新建不覆盖）
 
 消费命令的 <dir> 可省略（自动发现本 session 当前分析——按 cwd 下
 mv-<PI_SESSION_ID>-* 最新；无匹配则报错要求显式传目录）
@@ -153,9 +154,6 @@ def cmd_viewers(args):
     目录**（消费命令的目录自动发现对此不适用——它找的是 mv-<sid>-*）。判据全部
     复用 `spec_gen` 的单一实现（列举 `list_agent_md` / 名字 `check_agent_name` /
     集合 `viewer_set_error`），这一层不另写一套规则。
-
-    数量不足（<2）在这里是**提示**不是错误：建 1 个是合法的中间状态，只有启动
-    一次分析时才要求 ≥2（那条判据仍由 `viewer_set_error` 独占）。
     """
     if args:
         fail(f"未知参数: {' '.join(args)}（--viewers 不接受参数——只检查项目 cwd 的 viewers/）")
@@ -163,6 +161,17 @@ def cmd_viewers(args):
     if not os.path.isdir(vdir):
         fail(f"未找到 {vdir}——视角文件放在项目 cwd 的 viewers/<视角名>.md"
              f"（文件名即视角名；可跑 /multi-viewers-setup 交互式建立）")
+    return _validate_and_print_viewers(vdir)
+
+
+def _validate_and_print_viewers(vdir):
+    """列出 + 校验 + 打印（`--viewers` 与 `--set-viewer` 的**同一实现**）。
+
+    判据全部复用 `spec_gen` 的单一实现（列举 `list_agent_md` / 名字
+    `check_agent_name` / 集合 `viewer_set_error`）——这一层不另写规则。
+    数量不足（<2）是**提示**不是错误：建 1 个是合法中间状态（只有启动一次
+    分析才要求 ≥2，那条判据由 `viewer_set_error` 独占）。
+    """
     names, _briefs, empty = spec_gen._discover_viewers(vdir)
     if not names:
         fail(f"{vdir} 下没有 *.md——文件名即视角名（如 viewers/效率.md）")
@@ -190,6 +199,38 @@ def cmd_viewers(args):
     return 0
 
 
+def cmd_set_viewer(args):
+    """新建一个视角文件：`--set-viewer <名字>`，正文**从 stdin 读**。
+
+    为什么是命令而不是"让 LLM 直接写文件"：文件名即视角名，于是**命名规则 /
+    不覆盖已有 / 空正文拒绝 / 写完校验并回显**这四条本来只能写在 prompt 里当
+    纪律（LLM 会漏），现在由机制保证（判据复用 `spec_gen` 单一实现）。LLM/人
+    只负责**内容**——那是它该做的部分。不提供 `--force`：本命令语义 = 只新建，
+    改已有视角请直接编辑文件。
+    """
+    if len(args) != 1:
+        fail("用法: --set-viewer <名字>（正文从 stdin 读；如 "
+             "`mv.sh --set-viewer 效率 <<'EOF' … EOF`）")
+    name = args[0]
+    err = spec_gen.check_agent_name(name)
+    if err:
+        fail(f"非法视角名（{err}）：{name}")
+    vdir = os.path.join(os.getcwd(), "viewers")
+    target = os.path.join(vdir, f"{name}.md")
+    if os.path.exists(target):
+        fail(f"视角已存在，不覆盖: {target}（改名，或直接编辑该文件）")
+    body = sys.stdin.read().strip()
+    if not body:
+        fail(f"视角内容为空（{name}）——正文从 stdin 传入；空视角没有 lenses，"
+             f"分析会退化成同名随机视角")
+    os.makedirs(vdir, exist_ok=True)
+    with open(target, "w", encoding="utf-8") as f:
+        f.write(body + "\n")
+    print(f"[set-viewer] 已写入 {target}\n")
+    print(body + "\n")
+    return _validate_and_print_viewers(vdir)
+
+
 def cmd_status(args):
     d = _dir_only("--status", args)
     return _call([PYTHON, START_DISCUSSION, "--dir", d, "--status"])
@@ -365,10 +406,10 @@ def cmd_start(spec_dir, extra):
     # 条件 = 观测到一次 launch 失败，或将来引入 resume/retry 通道。
     if fnmatch.fnmatch(os.path.basename(os.path.normpath(spec_dir)),
                        "mv-spec-*"):
-        print(f"[start] spec 已消费，删除（本工具生成形态）: {spec_dir}")
+        print(f"spec 已消费，删除（本工具生成形态）: {spec_dir}")
         shutil.rmtree(spec_dir, ignore_errors=True)
     else:
-        print(f"[start] spec 已消费（保留未删——非 mv-spec-* 形态）: {spec_dir}")
+        print(f"spec 已消费（保留未删——非 mv-spec-* 形态）: {spec_dir}")
 
     # 第 2 步：启动已有环境
     if _call([PYTHON, START_DISCUSSION, "--dir", dir_path,
@@ -418,6 +459,8 @@ def main(argv=None):
         return cmd_start(rest[0], rest[1:])
     if cmd == "--viewers":
         return cmd_viewers(rest)
+    if cmd == "--set-viewer":
+        return cmd_set_viewer(rest)
     if cmd == "--status":
         return cmd_status(rest)
     if cmd == "--report":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-viewers",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Multi-perspective analysis for Pi: fork the main session into N perspective agents over the meeting protocol.",
   "type": "module",
   "private": false,

package/prompts/multi-viewers-setup.md

@@ -15,8 +15,8 @@ description: 建立多视角分析的 viewers/ 视角文件（交互式：先建
     1. <名字> —— <一行镜头>（与其它候选怎样互补/对立）
 
 - 这一步**只提议**：不建文件、不改任何东西
-- 名字：中文、短（≤32 字符）、不含空白与路径分隔符、**不要用 `human`**（保留名）
 - 建几个**由用户决定**（只建 1 个也行）
+- 名字规则由第 3 步的命令强制（顺带一提：中文、短、不含空白与路径分隔符）
 
 **然后结束本回合，等用户输入。**
 
@@ -25,10 +25,9 @@ description: 建立多视角分析的 viewers/ 视角文件（交互式：先建
 用户会告诉你建哪几个（可能只有一个、也可能点名不在候选里的）。**以用户输入为准**；
 若某个视角该用什么镜头没说清 → **问一句**，不要替他定。
 
-## 第 3 步：按用户输入建文件（只新建）
+## 第 3 步：用命令建文件（内容经 stdin 传给命令，不要直接写文件）
 
-写之前**先读 `README.md` 的「视角文件写什么」节**（唯一事实源：三个要点 + 正误对照 +
-命名规则）。要点：
+先读 `README.md` 的「视角文件写什么」节（唯一事实源：三个要点 + 正误对照）。要点：
 
 - 纯内容、无 frontmatter、无标题——**文件名就是全部元数据**
 - 必含三条：① **单一 lenses**（所有观点必须从该视角出发）② **不越界**（其它视角由
@@ -37,19 +36,23 @@ description: 建立多视角分析的 viewers/ 视角文件（交互式：先建
 - **只写视角本身**：身份（"你是 X"）、参与者名单、消息格式、独立参与者纪律都由脚本
   生成，**不要写进文件**
 
-写完跑一次只读检查（会列出视角并用代码判据校验名字与空正文）：
+每个视角调用一次（正文经 stdin；**命名合法性、不覆盖已有、空正文拒绝、写完校验并
+回显**都由命令保证，不需要你另外检查）：
 
 ```bash
-~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --viewers
+~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --set-viewer <视角名> <<'EOF'
+<视角正文>
+EOF
 ```
 
-**已有同名文件 → 不覆盖**：告诉用户"该视角已存在"，停下等他决定（改名，或他明确
-要求改动）。
+命令会回显**写入路径 + 正文全文 + 校验结果**——那就是第 4 步要展示的东西。
+若命令报"视角已存在"：告诉用户，停下等他决定（改名，或他明确要求改动）。
 
 ## 第 4 步：展示，等审阅
 
-把每个新建文件的**路径 + 全文**展示给用户，请他提修改意见或确认：
+把命令的回显（路径 + 全文 + 校验）给用户看，请他提修改意见或确认：
 
-- 有意见 → 改 → **再展示**（反复直到他确认）
+- 有意见 → **直接编辑该文件**（`viewers/<名字>.md`）→ 跑一次
+  `~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --viewers` 复核 → 再展示（反复直到他确认）
 - 确认后一行交接：视角已建好（启动一次分析至少需要 2 个视角），接下来
   `/multi-viewers "<主题>"` 即可

package/scripts/archive-result.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# archive-result.sh —— 把一场分析的 result.md 归档进 docs/reviews/
+#
+# 为什么是脚本：每场分析后都要做同一串机械动作，靠人/LLM 记（实测会漏——
+# 最容易漏的是索引行）。这里把**机械部分**固化成命令：
+#   · 命名（<日期>-<slug>.md）
+#   · 正文**逐字复制**并做字节校验（存档不改原文）
+#   · 存档头骨架（TODO 标记留在文件里，判断内容仍由人写）
+#   · 索引表加一行（插在最后一行存档之后）
+#   · 删掉仓库根的松散副本
+# **判断部分不代劳**：写什么主题/抓到什么问题/落地哪个 commit，是人的判断。
+#
+# 用法：
+#   scripts/archive-result.sh <result.md> --slug <slug> [--date YYYY-MM-DD] [--dry-run]
+# 例：
+#   scripts/archive-result.sh mv-mv-main-20260925-105614-result.md \
+#       --slug multi-viewers-postfix-review
+#
+# 退出码：0 成功（或 dry-run）；1 参数/环境错；2 目标已存在（不覆盖）
+
+set -u
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+REVIEWS="$HERE/docs/reviews"
+INDEX="$REVIEWS/README.md"
+
+SRC=""; SLUG=""; DATE="$(date +%F)"; DRY=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --slug) SLUG="${2:-}"; shift 2 ;;
+        --date) DATE="${2:-}"; shift 2 ;;
+        --dry-run) DRY=1; shift ;;
+        -h|--help) sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+        -*) echo "错误: 未知参数 $1" >&2; exit 1 ;;
+        *) SRC="$1"; shift ;;
+    esac
+done
+
+[ -n "$SRC" ] || { echo "错误: 缺少 result.md 路径（--help 看用法）" >&2; exit 1; }
+[ -n "$SLUG" ] || { echo "错误: 缺少 --slug <slug>" >&2; exit 1; }
+[ -f "$SRC" ] || { echo "错误: 文件不存在: $SRC" >&2; exit 1; }
+case "$SLUG" in *[!a-zA-Z0-9._-]*) echo "错误: slug 只允许字母/数字/._-（当前: $SLUG）" >&2; exit 1 ;; esac
+[ -f "$INDEX" ] || { echo "错误: 找不到索引 $INDEX" >&2; exit 1; }
+
+DEST="$REVIEWS/$DATE-$SLUG.md"
+if [ -e "$DEST" ]; then
+    echo "错误: 目标已存在（不覆盖）: $DEST" >&2; exit 2
+fi
+
+if [ "$DRY" -eq 1 ]; then
+    echo "[dry-run] 将归档: $SRC → $DEST"
+    echo "[dry-run] 正文 $(wc -c < "$SRC") 字节，逐字复制"
+    echo "[dry-run] 将写存档头骨架（含 TODO）+ 在 $INDEX 加一行 + 删 $SRC"
+    exit 0
+fi
+
+# 1) 存档头骨架 + 正文（逐字）
+{
+    cat <<EOF
+<!-- 存档：docs/reviews/$DATE-$SLUG.md
+     来源：一次真实多视角分析的 result.md 原文（未删改，仅加本头与下方说明）。
+     分析场次目录已随 cleanup 删除；文中消息编号不可再核验，仅作溯源线索
+     （与代码注释引用约定一致：行为以自描述为准）。 -->
+
+# 存档说明
+
+- **主题**：TODO（一句话）
+- **场次**：\`TODO（分析目录名）\`（视角 / 档位 / 收敛方式）
+- **判定/发现**：TODO
+- **落地**：TODO（commit 或"未落地"）
+- **备注**：TODO（可不填则删掉本行）
+
+EOF
+    cat "$SRC"
+} > "$DEST"
+
+# 2) 逐字校验（正文必须与源**逐字相同**——存档不改原文）
+if ! cmp -s <(tail -c "$(wc -c < "$SRC")" "$DEST") "$SRC"; then
+    echo "错误: 正文校验失败（存档与源不一致）——已保留 $DEST 供排查" >&2
+    exit 1
+fi
+echo "[archive] 正文逐字校验通过（$(wc -c < "$SRC") 字节）"
+
+# 3) 索引加一行（紧跟最后一行存档；TODO 留给写索引的人）
+python3 - "$INDEX" "$DATE-$SLUG.md" <<'PY'
+import sys
+idx_path, fname = sys.argv[1], sys.argv[2]
+lines = open(idx_path, encoding="utf-8").read().splitlines(True)
+hits = [i for i, l in enumerate(lines) if l.startswith("| `2026-")]
+if not hits:
+    print("错误: 索引里找不到存档行（| `2026-…）", file=sys.stderr)
+    sys.exit(1)
+row = f"| `{fname}` | TODO 主题 | TODO 抓到的问题 | TODO 落地 commit |\n"
+lines.insert(hits[-1] + 1, row)
+open(idx_path, "w", encoding="utf-8").write("".join(lines))
+print(f"[archive] 索引已加一行（{idx_path}；TODO 待补）")
+PY
+[ $? -eq 0 ] || exit 1
+
+# 4) 删仓库根松散副本（**只删源文件**，且必须在写成功后）
+rm -f "$SRC"
+echo "[archive] 已写 $DEST；源副本已删；下一步：补 $DEST 与索引行里的 TODO"

package/start_discussion.py

@@ -450,11 +450,24 @@ def cleanup_discussion(base):
     # 报告是附加信息、清理是主职责：报告生成失败**不阻断**清理
     # （fail-open 只在这一层兜底——build_report 内部各段已各自 fail-open）。
     print("[cleanup] —— 本次分析报告（删除目录前最后一次可读）——")
+    lines = None
     try:
-        for line in build_report(base):
+        lines = list(build_report(base))
+        for line in lines:
             print(line)
     except Exception as e:                       # noqa: BLE001（兜底不吞：打印）
         print(f"[cleanup] 报告生成失败（不影响清理）: {e!r}")
+    if lines is not None:
+        # 落盘一份（与 <base>-result.md 同级）：报告本来只在终端出现一次，
+        # 目录删掉后 --report 也不可用 → 观测数字不可复查（复盘时长口径时
+        # 踩过）。与 result.md 同样的 fail-open：写不动不阻断清理。
+        rp = meeting_fs.report_path(base)
+        try:
+            with open(rp, "w", encoding="utf-8") as f:
+                f.write("\n".join(lines) + "\n")
+            print(f"[cleanup] 报告已保存 → {rp}")
+        except OSError as e:
+            print(f"[cleanup] 报告保存失败（不影响清理）: {e!r}")
     shutil.rmtree(base)
     print(f"[cleanup] 已删除目录 {base}（含 pi-sessions）")