pi-multi-viewers 0.8.2 → 0.9.0

package/AGENTS.md

@@ -68,7 +68,7 @@ tests/               测试（unittest discover tests）
 
 | 档 | 唤醒命令 | 用途 |
 |---|---|---|
-| **mc-tools**（默认） | 四个 `--no-*` + `-e <MC 的 subagent-entry.js>` | 给 agents **按需检索项目背景**（`ctx_search`）——背景蒸馏机制已移除，这是其补充通道。**允许而非要求 MC**：找不到 MC → 降级为零扩展 + 一行可见说明（`ctx_search` 本次不可用）|
+| **mc-tools**（默认） | 四个 `--no-*` + `-e <MC 的 subagent-entry.js>` + `-e <pi-mcp-adapter 入口>` | 给 agents **按需检索项目背景**（`ctx_search`）——背景蒸馏机制已移除，这是其补充通道。**允许而非要求 MC**：找不到 MC → 降级为零扩展 + 一行可见说明（`ctx_search` 本次不可用）|
 | **none** | 四个 `--no-*` | 零扩展、**零依赖**（无 MC 的机器/CI 用这档）|
 | **all** | 不加任何 `--no-*`（pi 默认发现）| A/B 实验与显式 opt-in |
 
@@ -85,7 +85,7 @@ tests/               测试（unittest discover tests）
 生产基线：本场 strict=1、n=19，唤醒启动段中位 **0.68s**、收尾中位 0.04s ✓）。
 **入口解析 fail-fast**（`meeting_fs.resolve_mc_tools_entry`：从 pi 的 packages 找 MC 包 →
 读它声明的扩展入口 → 取同目录的 subagent-entry.js）；缺 MC 时**可见降级**为零扩展。
-**依赖边界**：mc-tools 档**允许而非要求** MC——缺 MC 时降级为零扩展，且**可见**
+**依赖边界**：mc-tools 档的**两份入口各自独立**（MC 的 ctx_search、MCP adapter 的 web_search 等）——**允许而非要求**，缺谁少谁、都**可见**
 （打印一行"本次按零扩展运行：ctx_search 不可用"；无静默铁律）；`none` 档零依赖
 （无 MC 的机器/CI 显式选它）。**测试/探针保真**：设 `MV_MC_TOOLS_STRICT=1` →
 缺 MC 即报错退出（否则测试可能在"没装 MC"下通过而 ctx_search 从未生效）。
@@ -261,3 +261,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 - **核验法**（照上游约定，不用命令行长度判断）：
   `readlink -f ~/.pi/agent/npm/node_modules/pi-multi-viewers` 指向仓库根，
   且该路径下 `scripts/mv.sh` 存在。
+- **registry 核验别只看 `/latest`**（实测踩两次）：npm 的 abbreviated 元数据
+  （`registry.npmjs.org/<pkg>/latest`）有缓存，发布后可能持续返回旧版本；
+  **权威判据 = 完整文档的 `dist-tags`**：
+  `curl -s https://registry.npmjs.org/pi-multi-viewers | python3 -c "import json,sys;print(json.load(sys.stdin)['dist-tags'])"`

package/README.md

@@ -1,12 +1,30 @@
 # pi-multi-viewers
 
-多视角协同分析（Pi 插件）：把主 pi session **fork** 成 N 个视角 agent，
-各带一份视角任务书（效率/简单/铁律/……），在 meeting 协议下交锋、
-修正、收敛，产出一份共识结果。
+**多视角协同分析（Pi 插件）**：把当前 pi 会话 fork 成 N 个视角 agent，让它们带着你的真实上下文互相交锋，产出共识与分歧。
 
-与 [pi-agents-helper](https://github.com/maxdai/pi-agents-helper)（多方
-讨论达成共识，agent 无主上下文）平行演化；共享 meeting 协议核心
-（core/fs/engine），差异在初始化层。
+## 它想解决什么问题
+
+需要考虑多种因素或者准则时，LLM 容易出现**逐渐忽略其中一部分因素**的问题。
+
+对策是**给每个因素一条独立的会话**：一个视角 agent 只关注一个因素（效率 / 简单 / 铁律 / …），
+各带一份视角任务书与独立发言配额，并且必须对其它视角的观点表态（认同或反驳，都要用自己的论据）。
+这样**只要这些会话存在，对应因素就不会被忽略**——关注不靠提醒模型"别忘了 X"，
+而是让每个 X 有一个独立的载体。
+
+讨论由代码驱动的 meeting 协议推进（发言配额 → 冻结 → 轮转表态 → 共识收束），
+最终产出 `result.md`：**共识结论 + 明确否决项（含理由与重估触发条件）+ 各自保留的分歧**。
+
+## 什么时候值得跑
+
+**当一个问题需要长思考、并且需要在长思考过程中保持若干个视角的关注时**，可以尝试使用。
+
+（反过来说：查一个事实、跑一条命令、一两分钟能自己确认的问题，直接问 pi 更快。）
+
+## 代价
+
+一次分析通常 **12–35 分钟**（3 视角、20–50 次唤醒，正常情况）。这个区间**不含**异常外溢：
+provider 连续失败或扩展异常时可能显著更久（历史场次里出现过 55 分钟与 73 分钟）。
+它换来的不是"更快"，而是"多几个独立立场 + 一份可复查的分歧记录"。
 
 ## 核心机制（2026-09-09/10 实测验证，见 docs/examples/first-experiment）
 
@@ -67,16 +85,20 @@ ls ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh
 
 ## 用法
 
-```
-/multi-viewers-setup          # ① 建视角（首次使用先跑这个；prompt：先建议 → 你定 → 落盘 → 给你审）
-/multi-viewers "<主题>"        # ② 分析（extension：生成 spec → 弹窗门禁 → 启动 → 预填观看命令）
-/multi-viewers-say "<文本>"    # ③ 插话（分析进行中；extension：零 LLM 直接写入 human 消息）
-/multi-viewers-finish         # ④ 收尾（extension：查状态 → 确认 → 清理，报告随清理打印）
-```
+**接口总表**（pi 内 1 个 prompt + 3 个命令；终端侧另有等价 CLI）：
 
-四个 pi 命令入口，按使用顺序排列。**②③④ 是 extension**（流程完全由代码执行、
-零 LLM：跑命令、门禁弹窗、观看命令预填、状态判据都走退出码/机器标记行，
-不靠 LLM 转述）；**① 是 prompt**——写视角是内容工作，本就需要 LLM 参与。
+| 入口 | 形态 | 作用 |
+|---|---|---|
+| `/multi-viewers-setup` | prompt | 建视角（建议 → 你定 → `--set-viewer` 落盘 → 给你审） |
+| `/multi-viewers "<主题>"` | extension | 分析：prepare → **暂停点弹窗** → start → 交付观看命令 |
+| `/multi-viewers-finish` | extension | 收尾：status → 确认 → cleanup（报告随清理打印并落盘） |
+| `/multi-viewers-say "<文本>"` | extension | 插话（human 消息，各视角可见可回应） |
+| `scripts/mv.sh <子命令>` | CLI | 终端侧等价入口（`--prepare` / `--start` / `--status` / `--view` / `--say` / `--report` / `--wait` / `--cleanup` / `--viewers` / `--set-viewer`）——pi 内命令内部也走它 |
+
+按使用顺序：先 `/multi-viewers-setup` 建视角（一次就够），之后 `/multi-viewers "<主题>"` 跑分析，
+分析进行中用 `/multi-viewers-say` 插话，结束后 `/multi-viewers-finish` 收尾。
+**后三个是 extension**（流程完全由代码执行、零 LLM：跑命令、门禁弹窗、观看命令交付、状态判据
+都走退出码/机器标记行，不靠 LLM 转述）；**`setup` 是 prompt**——写视角是内容工作，本就需要 LLM 参与。
 
 **目录可以省略**：`--view`/`--say`/`--status`/`--report`/`--wait`/`--cleanup`
 不带目录时自动定位"本 session 当前分析"（只匹配 `mv-<sessionId>-*` 最新；**未匹配
@@ -98,8 +120,9 @@ scripts/mv.sh --start <spec目录>              # 启动（自动挂载主 sessi
 #  可选：--fork-mode compaction|budget|full（见上表；一般不调）
 #  可选：--max-meeting 15 --max-rr 7 --stall-timeout 600
 #        （配额：建环境时固化进 protocol.json，之后不可改；meeting 配额是"每 agent"）
-#  可选：--extension-policy mc-tools|none|all（默认 mc-tools = agents 带 MC 的只读检索工具
-#        ctx_search；none = 零扩展、零依赖；all = 走 pi 默认发现。缺 MC 时 mc-tools 可见降级）
+#  可选：--extension-policy mc-tools|none|all（默认 mc-tools = 零扩展 + 两份只读工具入口：
+#        MC 的 ctx_search 与 MCP adapter 的 web 检索等；none = 零扩展、零依赖；
+#        all = 走 pi 默认发现。两份入口各自独立，缺谁少谁且可见降级）
 #  高级：--agents "a,b" 起一次性视角（不建 viewers/ 时用；prompt 入口不传它）
 
 # 观看：--start 会输出可直接执行的 !! 流式观看命令（复制执行）
@@ -156,6 +179,9 @@ frontmatter 字段、写文件路径、独立参与者纪律。
 | 完全一次性（项目还没建 viewers/） | `mv.sh --prepare "<主题>" --agents "a,b"`（wrapper 高级用法） |
 
 ## 架构
+与 [pi-agents-helper](https://github.com/maxdai/pi-agents-helper)（多方
+讨论达成共识，agent 无主上下文）平行演化；共享 meeting 协议核心
+（core/fs/engine），差异在初始化层。
 
 ```
 meeting_core.py     纯判定（冻结级联/RR/聚合 + 状态机词汇常量）

package/docs/design.md

@@ -201,7 +201,7 @@ fail-open（报告失败不阻断清理，且**打印**失败原因不静默）
 轮询路径消费 MB 面、不做运行期 LLM 评分（有效性判断留给人 + result.md）、
 不做目录内 retention（cleanup 是唯一清理点）、message frontmatter 不加
 时间戳（第二事实源 + 该字段由 LLM 写，不可信；权威时间 = commit 时间）、
-日志不 JSON 化（主消费者是人）、报告不自动落固定位（视图不占"家"）。
+日志不 JSON 化（主消费者是人）、报告不自动落固定位（视图不占“家”；**例外**：cleanup 删目录前打印并落盘一份快照 `<base>-report.txt`，见观测面契约）。
 
 ## 数字的归宿（一个数字只留一个"家"）
 
@@ -495,7 +495,7 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
 
     | 档 | 唤醒命令 | 语义 |
     |---|---|---|
-    | `mc-tools`（默认） | 四个 `--no-*` + `-e <MC subagent-entry.js>`（找不到 MC 时退化为四个 `--no-*`）| 只要 MC 的**只读检索工具**（`ctx_search`）；**允许而非要求** MC |
+    | `mc-tools`（默认） | 四个 `--no-*` + `-e <MC subagent-entry.js>` + `-e <pi-mcp-adapter 入口>`（任一份入口缺失即**部分降级**：缺谁少谁、都可见；全缺 = 等价 none）
     | `none` | 四个 `--no-*` | 零扩展：最快、**零依赖** |
     | `all` | 不加任何 `--no-*` | pi 默认发现（A/B 与显式 opt-in）|
 
@@ -517,6 +517,7 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     spawn cwd 全截断（"无 MC 的机器"上产出残缺命令）。**登记行**：首唤打
     `扩展策略: 声明=X 生效=Y strict=0|1 [降级原因=…]`——报告据此给"声明 vs 生效"
     （E2；与"档位"同型），否则降级只在 loop log 里、产品面看不见。
+    **两份入口（2026-09-25 用户裁决 B）**：`mc-tools` 除 MC 的只读检索工具外，再显式 `-e` 加载 **pi-mcp-adapter**（web_search / web_reader / zread 等 MCP 工具）——`--no-extensions` 关的是**扩展发现**，显式路径照常生效（pi `--help` 原文），不加载就等于 agents 完全失去联网检索能力。两份入口**各自独立降级**（缺谁少谁、都可见），不新增档位（保持简单）。
 
     **依赖边界（用户 2026-09-14 定）**：mc-tools **允许而非要求** MC——缺 MC 时
     **降级为零扩展并按 none 运行**，但**必须可见**（打印一行"mc-tools 档未生效
@@ -579,17 +580,27 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     `mv.sh --set-viewer <名字>`（正文从 stdin 读）——**命名规则 / 不覆盖已有 / 空正文拒绝 /
     写完校验并回显**四条由命令保证（此前是 prompt 里给 LLM 的纪律，会漏）；prompt 只负责
     **看项目给候选 + 内容撰写 + 与用户来回**（那才是 LLM 该做的）。
+    **有意的 LLM 义务残留**：prompt 第 4 步要求「改完再跑 `--viewers` 复核」——它不新增
+    命令面，且有硬 gate 兜底（prepare/start 的集合校验不过就拒绝启动），故保留。
     **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 变体/第三种即现形态）。
+    暂停点成立）；`notify` 全模式可用（TUI = showStatus 行；pi-web 会关闭即消失）；
+    **`setEditorText` 仅 TUI**——pi-web 忽略（`pi-web/static/app.js` 注释
+    「set_editor_text … ignored」+ SDK `ui-context.ts` 里是空实现）。⇒ 交付观看命令
+    不能只靠一个通道，**四个通道各司其职**：
+    | 通道 | 作用域 | 上下文成本 | 角色 |
+    |---|---|---|---|
+    | `setEditorText` 预填 | 仅 TUI | 0 | TUI 便利（能直接回车跑） |
+    | `notify` | 全模式 | 0 | 即时反馈（pi-web 关掉弹窗即消失） |
+    | `pi.sendMessage`（custom_message） | 全模式 | ~百 token（主 session）+ 随 fork 进每场分析 | 持久留痕（pi-web 渲染为折叠块、需点击；起 0.5.19 实时出现） |
+    | `ctx.ui.setWidget` | 全模式 | 0（纯 UI） | 运行期常驻可见（一眼看到、不需点击） |
+    三条注记：① `sendMessage` 的 custom_message **会随 fork 进每场分析各视角的上下文**
+    （fork 源在首唤由主 session 条目构建，不做类型过滤）——~2 行/场，有界；不为它加
+    过滤（那会让构造层获得扩展类型知识，跨层耦合换几行噪音，不配）。② widget 是
+    **运行期**状态（fire-and-forget UI，非会话条目；reload/重启后不恢复——持久记录靠
+    custom_message）。③ 零上下文留痕档确实存在（`pi.appendEntry` + `registerEntryRenderer`，
+    明确不进 LLM 上下文），但其渲染器是 TUI 组件、pi-web 无渲染路径 ⇒
+    **可见 ∩ 零上下文 = 空集**，跨模式成本不可归零，接受现值。需要分级时用 `ctx.mode`。
 
 ### 被否决方案（含重估触发条件）
 

package/docs/reviews/2026-09-25-extension-mechanisms-review.md

@@ -0,0 +1,182 @@
+<!-- 存档：docs/reviews/2026-09-25-extension-mechanisms-review.md
+     来源：一次真实多视角分析的 result.md 原文（未删改，仅加本头与下方说明）。
+     分析场次目录已随 cleanup 删除；文中消息编号不可再核验，仅作溯源线索
+     （与代码注释引用约定一致：行为以自描述为准）。 -->
+
+# 存档说明
+
+- **主题**：复验 0.8.2 新上线的三处机制（① `--cleanup` 落盘报告 ② `mv.sh --set-viewer`
+  ③ 观看命令交付通道）+ 这三处与扩展 harness 的测试覆盖、断言强度
+- **场次**：`mv-mv-main-20260925-153113`（3 视角：效率 / 简单 / 铁律；真实 pi 讨论；
+  `forkMode=budget`、扩展策略 `mc-tools`（声明=生效）、`maxMeeting=15`；共识收敛，
+  墙钟 28m42s / 46 次唤醒 / provider error 38 次）
+- **判定**：三处机制**可以收下**（效率账：① <0.3s/场换掉 20–40 分钟重跑取数；
+  ② 一次命令调用省掉 LLM 的校验/重试回合；③ ~百 token/场换掉分钟级往返）
+- **本场抓到（多数在最新那批代码里，均属防静默失效）**：
+  - **①(c) 显示层失败会跳过清理**（最重要）：`cleanup_discussion` 的 print 在管道关闭时抛
+    `BrokenPipeError` → 逃逸 → **rmtree 被跳过**、目录残留、rc≠0。三处逃逸点：
+    banner print 在 try 外 / except 处理器自身再 print / 写盘失败处理器又 print。
+    修法 = `_print_best_effort`（全部 stdout 走它，函数内无裸 `print(`）+ `rmtree` 进
+    `finally` ⇒ **rmtree 必达**；唯一例外 = 产物留存真失败（result.md 权威位在待删目录内）
+    修后由 `51a4535` 落地，本仓复现脚本前后对照（逃逸+残留 → 无逃逸+已删+报告仍落盘）
+  - **② `--set-viewer` 半成功**：集合级校验在**写之后** → viewers/ 里预置坏文件时
+    "rc≠0 但新文件已写入"。修法 **B′**（校验前移到读 stdin/写之前，单一组合点
+    `spec_gen._viewer_set_errors`）；另 `exists` → `lexists`
+  - **③ 通道模型修正**：从"三个出口（缺一不可）"收敛为**四通道角色模型**；并指出
+    `custom_message` **随 fork 进入每场分析上下文**（~2 行/场，有界）——此前只说"主 session"
+  - 文档描述簇（三处"不持久化"复述只同步了一处）、断言偏弱（"落盘≡打印"未锁）、
+    prompt 里 README 三要点的第二处复述、fail-open 宽窄不对称（Exception vs OSError）
+- **落地**：`51a4535`（475 python 测试 + 48 harness 断言全绿；净增 ≈11 行生产代码、
+  零运行时行为变化）。报告另记录"明确不做"（fork 过滤 / `ctx.mode` 分支 / 符号链接测试矩阵）
+  与已知限（widget 仅运行期常驻）
+
+# 0.8.2 复验 · 三方共识结果
+
+参与者：效率 / 简单 / 铁律（3 视角，真实 pi 讨论；`forkMode=budget`、`mc-tools`、`maxMeeting=15`）。
+主题：复验 0.8.2 新上线的三处机制（① `--cleanup` 落盘报告 ② `mv.sh --set-viewer` ③ 观看命令交付通道）+ 测试覆盖与断言强度。**只提意见，不改代码、不跑测试**。
+
+## 0. 结论摘要
+
+1. **三处机制方向正确、净收益为正**（效率账：① 用 <0.3s/场换掉 20–40 分钟重跑取数；② 用一次命令调用省掉 LLM 的校验/重试回合；③ 用 ~百 token/场换掉分钟级往返）。
+2. ① ② 的实现基本符合设计，但有**一处文档描述缺口簇、一处测试断言弱、一处职责边界含糊**；③ 在讨论**进行中**因真实观察新增了第四个交付通道（`setWidget`，HEAD `0b28256`），审查基准随之推进，结论按版本分段。
+3. **本批必须落地**（三方一致，零运行时变化）：
+   - ① **显示层失败可跳过清理**的修补（`_print_best_effort` + `rmtree` 必达；唯一例外=产物留存真失败）——本轮最重要行为修复；
+   - ① 落盘内容 ≡ 打印内容 的等值断言 + 写失败 fail-open 分支用例 + 三处"不持久化"复述改引用 + 两处新能力文案；
+   - ② **B′**：集合校验前移到写之前（单点 `_viewer_set_errors` + `if names:` 守卫），消掉"写成功但 rc≠0"的半成功；
+   - ② prompt 删去 README 三要点复述与命名括注；
+   - ③ `index.ts:19`/`:96` 的"三个出口"改四通道角色表述；决策 22 收敛为角色表 + 三注记（fork 复制事实、widget「（运行期）」、why-not-appendEntry）；
+   - harness **单一日志**（sendMessage 入 `calls`、删 `sent`、失败路径精确 kinds）+ ① 三断言用例——**净删代码、覆盖变强**。
+4. **一句话**：三处机制可以收下；本批做的是"让清理必定发生、让校验先于副作用、让文档按实际写"——全部是防静默失效类的修复，生产代码净增 ≈11 行（显示层 ~6 + B′ ~5），其余为断言与文档。
+
+---
+
+## 1. 审查基准与版本口径（一个动态事实，先钉死）
+
+| 项 | 事实 |
+|---|---|
+| 0.8.2 | tag `v0.8.2` = `81c8820`（内容：`e06bceb` 报告落盘 + `--set-viewer` + 归档脚本；`81c8820` 发版） |
+| ③ 的历史 | `sendMessage` 第三出口 ∈ **0.8.1**（`e92eacc`，见 `v0.8.0..v0.8.1`）；④ `setWidget` ∈ **`0b28256`**（讨论进行中落地，未发版） |
+| 本场 HEAD | `0b28256`（"观看命令加常驻面板出口"）——③ 按**四通道**审，① ② 与 v0.8.2 一致 |
+| 引用口径 | 复验结论**按版本分段**：①② 对 v0.8.2；③ 对 0.8.1（sendMessage）/ `0b28256`（widget）——避免被读成"0.8.2 已复验"而重复检查 |
+| 数字校准 | harness **48** 条断言（0b28256 后）；口径见 `docs/design.md:106`（`build_report` 实测 50–150ms/次、×3 出口 <0.3s/场，单点数字非承诺） |
+| 行号校准 | setup prompt：命名括注 `:19`、三要点复述 `:33-34`、复核义务 `:55-56`；README 三要点 `:129-133` |
+
+讨论中审查对象发生变化（`0b28256` 在 15:34 落地），**结论绑定 revision**——执行时以当时 HEAD 为准。
+
+## 2. ① `--cleanup` 落盘报告（`meeting_fs.report_path` + fail-open）
+
+### 2.1 复验判定
+
+- **实现正确**：`cleanup_discussion` 只调一次 `build_report`，同一份 `lines` 既打印又落盘（无二次遍历）；落盘在 `shutil.rmtree` 之前；路径声明 `meeting_fs.report_path` 与 `result_path` 同家（各一行，未过度参数化）。`<base>-report.txt` 已在 `.gitignore:8`（`check-ignore` 实测命中）。
+- **职责边界**：落盘点选在 cleanup（"cleanup 是唯一清理点"，design.md:202）正确；观测数字从"只在终端出现一次"变为"可复查"。
+
+### 2.2 发现（按类别）
+
+**(a) 文档描述簇（两个方向）**：
+- 旧话未删：`observability.py:5`（模块头）与 `:217`（`build_report` docstring）仍写"**不持久化**……视图不占'数字的家'"，`docs/design.md:204` 仍写"报告不自动落固定位（视图不占'家'）"——同一提交只更新了 design.md:167-171（观测面契约），留下三处相反复述。
+- 新话未加：`start_discussion.py:436`（cleanup docstring）与扩展收尾弹窗 `index.ts:180-181`（"清理时还会打印一次分析报告"）都未提报告已**落盘**——用户事后只找 result，不知道有 report.txt，① 的"可复查"收益在**发现性**上打折。
+- 改法（按仓库纪律"删复述引权威 > 最短准确陈述"）：`build_report` 处改为"函数自身不写文件；唯一落盘点在 `cleanup_discussion`"；design.md:204 补"（cleanup 删除前例外）"；弹窗/docstring 加一句"报告落盘到 `<分析目录>-report.txt`"。
+
+**(b) fail-open 宽窄不对称**：生成段 `except Exception`（:454-459）与写盘段 `except OSError`（:465-470）——统一为两段同捕 `Exception`（对称、免推理；`join` 抛非 `OSError` 会阻断 rmtree 的自述矛盾一并消失）。
+
+**(c) 显示层失败可跳过清理（本场最重要的行为发现，3/3 决定本批修）**：
+- 现状三处逃逸点：banner print 在 `try` 之外（:452）；`try` 内 handler 自身 `print`（:459）→ 再次 flush 时重抛；写盘段把 BrokenPipe 当 `OSError` 捕获后**也再 print**（:469-470）。此外 `_preserve_result_md` 的 print（:432）在报告段之前，也在保护之外。
+- 结果**随缓冲而定**：整份输出留在缓冲区（管道 ≈8KB）→ 异常只在解释器退出时出现、清理已完成；报告超过缓冲或未缓冲 → 循环中途炸、**rmtree 被跳过**（目录残留 + rc≠0）。
+- **修补形态（冻结）**：
+  - 新增 `_print_best_effort`；契约 = **`cleanup_discussion` 的全部 stdout 输出都走它**（含早退 `:446` 与 `_preserve_result_md` 的 `:432`）——按"出口"定义、可 `grep` 校验（函数内无裸 `print(`）；
+  - 不变量：**`rmtree` 必达，唯一例外 = 产物留存真失败（I/O）**；显示层失败永不算留存失败；
+  - `_preserve_result_md(base)` 调用**留在 `try` 之外**——它真失败（`meeting_fs.py:1255` 的 `open(dest,"w")` 不吞）时冒泡、**不删目录**（result.md 权威位置 `<base>/repo.git` 在待删目录内，删了就永久丢失）；
+  - `try/finally`（`rmtree` + 末行提示）只从**报告段**起；rmtree 自身失败仍冒泡；清理成功 **rc 0**。
+
+**(d) 测试缺口**：
+- 落盘内容 ≡ 打印内容**未断言**（现只 `assertIn("配额：meeting", report)`，tests/test_main_paths.py:319-323；落盘只写前 3 行也能过）——提交信息所称"内容与打印一致"未被锁；
+- **写失败 fail-open 分支零覆盖**（`[cleanup] 报告保存失败（不影响清理）`，tests/ 无命中）。
+
+### 2.3 冻结清单（①）
+
+- [ ] `start_discussion.py`：`_print_best_effort` 助手 + 全部 stdout 走它 + `cleanup_discussion` 重排（`try/finally` 只包报告段、`rmtree` 在 `finally`；`_preserve_result_md` 在 try 外；统一捕 `Exception`；清理成功 rc 0）
+- [ ] `observability.py:5`/`:217`、`design.md:204`：改为引用落盘点，不复述"不持久化"
+- [ ] `start_discussion.py:436` docstring + `extensions/multi-viewers/index.ts:180-181` 弹窗：补"报告落盘 `<分析目录>-report.txt`"
+- [ ] 测试：`assertEqual(落盘, 打印)`（print 已 mock，可直接重建）+ 写失败分支用例 + **三断言新用例**（目录已删 + rc 0 + `<base>-report.txt` 存在）
+
+## 3. ② `mv.sh --set-viewer`
+
+### 3.1 复验判定
+
+- **四条保证确由机制保证**（逐条核对，判据复用 `spec_gen` 单一实现）：命名合法（`check_agent_name`，写前）；不覆盖（`os.path.exists` 写前拒绝 + 测试断言原文件未动）；空正文拒绝（且不建目录）；写完校验并回显（`_validate_and_print_viewers`）。
+- **prompt 义务已下移**：第 3 步明确"四条由命令保证，不需要你另外检查"；内容经 stdin 传命令（不直接写文件）。LLM 只负责内容——职责分工正确。
+- 复杂度：`--viewers` 与 `--set-viewer` 共用同一校验实现（净简化，无第二套规则）；守卫扁平、无 `--force`。
+
+### 3.2 发现与裁定
+
+- **半成功（职责边界含糊）**：`cmd_set_viewer` 先写文件、后调集合级校验；若 viewers/ 里**预先**有坏文件（空文件/非法名），命令 rc≠0 **但新文件已写入**。可复现：`viewers/` 放一个空 `甲.md` → `--set-viewer 乙` → `乙.md` 已写、rc=1。
+  **裁定（3/3）：采纳 B′**（最小形态）：
+  - 抽 `_viewer_set_errors(names, empty) = validate_participants(names) or (viewer_set_error(names, empty) if empty else None)`——**唯一组合点**（`if empty` 保护：否则建第 2 个视角会被 ≥2 判据误判为错误）；
+  - `_validate_and_print_viewers` 改调它（判据组合不再有第二份）；
+  - 前置检查放 `exists` 检查后、**读 stdin 前**（错误路径不消费输入），**只留 `if names:` 守卫**（去掉冗余 `os.path.isdir`——`_discover_viewers` 对目录缺失/空/无 md 一律返回 `(None,None,[])`；不守卫则 `validate_participants(None)` 抛 TypeError，**首次建视角即命中**）；
+  - 组合用例：预置坏视角 → 断言 **rc≠0 且新文件不存在**；「已写入 `<path>`」仅出现在成功路径。
+  - 回退 A（零改动）：保留半成功，但契约行必须写**双义**（"rc≠0 = 未写入，或已写入但目录整体不合规——以「已写入」行区分"），且用一条用例钉住；A/B′ 的断言不可共用。
+- **prompt 残留（3/3 同意删）**：
+  - `prompts/multi-viewers-setup.md:33-34`：三要点是 README:129-133 的**第二处完整复述**（该 prompt `:30` 已声明 README 为唯一事实源）→ 删复述、留指针（删后零额外读取）；
+  - `:19` 命名括注是 `check_agent_name` 的部分抄写（漏 ≤32/human）→ 删；
+  - `:55-56` "编辑后跑 `--viewers` 复核"是 LLM 义务（有 prepare/start 硬 gate 兜底）→ 在决策 22 记为**有 backstop 的有意残留**，不新增编辑命令。
+- `os.path.exists` → `os.path.lexists`（一字收紧"绝不覆盖"，悬空符号链接是目前唯一破口）；**不**铺符号链接测试矩阵。
+
+## 4. ③ 观看命令交付通道（0.8.1 的 sendMessage + `0b28256` 的 widget）
+
+### 4.1 事实核验
+
+- 投递已实证：`sendMessage` 写入会话成功；**本场三个 fork 源各含恰好 1 条** `customType=multi-viewers` 的 `custom_message`（逐文件解析：481/550/555 条目中各 1）——**说明它进入每场分析各视角的上下文**（fork 源在**首唤**构建，`meeting_loop._prepare_fork_session`），不是"只在主 session"。
+- 显示端：pi-web 把 `custom_message` 渲染为**折叠块**（需点击/重载）→ 用户实测"看不见"；`notify` 弹窗关闭即消失；`setWidget` 面板为**一眼可见、不需点击**（pi-web 注释 "Persistent widget panel … Not a popup"）。
+
+### 4.2 角色模型（替代"缺一不可/三个出口"的说法）
+
+| 通道 | 作用域 | 上下文成本 | 必需性/角色 |
+|---|---|---|---|
+| `setEditorText` 预填 | 仅 TUI | 0 | TUI 便利（能直接跑） |
+| `notify` | 全模式 | 0 | 即时反馈（会消失） |
+| `pi.sendMessage` | 全模式 | ~100–200 token/回合（主 session）+ 每场 fork 3×~100–200（一次性、有界） | **持久留痕**（折叠；跨重启仍在） |
+| `ctx.ui.setWidget` | 全模式（pi-web 已验证） | 0（纯 UI） | **运行期常驻可见** |
+
+### 4.3 冻结清单（③）
+
+- [ ] `extensions/multi-viewers/index.ts:19` 与 **`:96`**（第二处，枚举漏 widget）→ 改四通道角色表述（与决策 22 一致）；
+- [ ] 决策 22 的 UI 通道段**收敛为 4 行角色表 + 三注记**：① fork 复制事实（`design.md:589` 现只写"参与 LLM 上下文的一行"，须补"随 fork 进每场分析"）；② widget「**（运行期）**」（fire-and-forget UI 状态、非会话条目，跨重启不恢复）；③ why-not-appendEntry（零上下文留痕档存在但渲染 TUI-only，pi-web 不可见）；
+- [ ] 文档可如实写"显示层失败也不阻断清理"（①(c) 修完后）；
+- **不做**：fork 过滤（`build_fork_source` 不按 customType 过滤；新增黑名单=构造层获得扩展类型知识，跨层耦合换 ~2 行噪音，不配）；`ctx.mode` 分支（把客户端差异搬进扩展）；"瘦身" sendMessage（收益 <50 token/回合，不配 churn）。
+
+### 4.4 display-only 口径（写准，防未来翻案）
+
+`sendMessage` **无** excludeFromContext 选项（options 仅 `{triggerTurn, deliverAs}`；`excludeFromContext` 属 bashExecution）；**零上下文留痕档存在**——`pi.appendEntry` + `registerEntryRenderer`（"do NOT participate in LLM context"），但渲染器是 TUI 组件、pi-web 无渲染路径 ⇒ **可见 ∩ 零上下文 = 空集**，跨模式成本不可归零、接受现值。widget 的零上下文已覆盖"面板可见"需求。
+
+## 5. 测试与断言（冻结清单）
+
+- **harness 单一日志（第一优先简化）**：mock 的 `sendMessage` 也 push 进 `calls`（kind="sendMessage"）；删 `sent` 数组与两段特判；成功后精确 `eq(kinds(calls), [...])` 一次覆盖四通道；取消/失败路径精确 `eq(kinds(calls), ["notify:error"])`（现失败路径只 `includes("notify:error") && !includes("setEditorText")`，四通道下只挡一个）；content 用**语义包含**（`includes(dir)`/`includes(watch)`），不锁排版；D2 负断言改**正向**（"含 TUI 限定词"）。
+- ①：等值断言 + 写失败分支 + 显示层三断言用例（目录已删 + rc 0 + report.txt 存在）。
+- ②：组合用例（rc≠0 且文件不存在）；两条 None 路径已由现有首建用例覆盖（`test_creates_and_validates` / `test_creates_viewers_dir_when_missing`），无需新装置。
+- 数字：harness 现 **48** 条；本批预计 +4~6 条断言、删 `sent` 相关代码——**净减代码**。
+
+## 6. 文档同步清单
+
+1. **报告出口描述**：`design.md:139` 第 2 项（`--cleanup`）补"打印 + **落盘快照**"，**计数保持三**（比加第四出口少一个概念；`design.md:106`、`meeting_fs.py:57` 不动）。
+2. **术语拆分**：观看命令 = 「**四个交付通道**」；报告保留「出口」（全仓"三个出口"5 处属两个机制，改 `:19`/`:96` 时勿误伤报告三处）。
+3. 决策 22：角色表 + 三注记（见 4.3）；观测面契约处（:167-171）已更新，保持。
+4. `AGENTS.md`：如无引用冲突无需改（版本号唯一事实源 = package.json；本批若发版按"修复+文档"升第三位）。
+5. 版本引用按 §1 分段。
+
+## 7. 明确不做 / 已知限 / 回退口径
+
+- **不做**：fork 过滤、`ctx.mode` 分支、符号链接测试矩阵、② 的 C 方案（改为"创建成功即 rc0、集合问题仅提示"——属产品行为变更）、为 prompt 的"复核义务"新增编辑命令。
+- **回退口径**：② 若取 A，契约行写双义（§3.2）；①(c) 若本批不修（不推荐，已 3/3 支持修），则须双落点——`cleanup_discussion` 代码注释（主防线）+ 结论一行，且**不得**声称"fail-open 覆盖显示层"。
+- **已知限**（记录在案）：widget 仅运行期常驻（pi 重启/reload 后不恢复，持久记录靠折叠的 custom_message）；手动 `mv.sh --cleanup` 或外部删除后，面板会短暂指向已删目录（下次运行同 key 覆盖）；`sendMessage` 内容参与每场 fork 上下文（~2 行/场，预算窗口内，有界）。
+
+## 8. 收敛过程（消息索引）
+
+- **开题（效率/0001、简单/0001、铁律/0001）**：效率给运行开销账（三处净收益为正）+ 两问（report.txt 是否 ignore、display-only 档）；简单给简洁性复验（① 哨兵可省/两文案未同步、② 最干净、③ 头注释三出口矛盾）+ harness 失败路径断言弱于取消路径；铁律按三铁律逐条核（① 三处"不持久化"只同步一处、断言强度、fail-open 宽窄；② 校验在写之后 + prompt 复述；③"缺一不可"强于设计 + fork 下游效应 + 版本归属修正）。
+- **交错与澄清**：挂账两项由简单/铁律独立结清（`.gitignore:8` 命中；零上下文档存在但 TUI-only）；效率两次撤回（"viewer 看不到"被 fork 源证据证伪；"零成本前置"被组合复制论证撤回）；简单撤回哨兵建议（BrokenPipe 反例成立）；铁律更正自身（fork 在首唤构建，本场即已进入；0009 的"受保护块从留存开始"按字面会丢产物，由简单/0007 修正、铁律/0015 确认）。
+- **关键分歧裁定**：① 显示层项——效率先降级 → 铁律/0007 代码验证（三逃逸点、缓冲而定）→ 效率/0008 收回、支持本批修 → 简单/0006 站修 → **3/3 修**；② 半成功——效率 A→B′、简单 A→B′、铁律 B′，**最终三方一致 B′**（A 回退写双义）；③ 通道——从"三个出口（缺一不可）"收敛为四通道角色模型（保留、不加过滤）。
+- **RR 表态**：效率/0015、简单/0011、铁律/0015 均 `pass`，无异议——共识闭合。
+
+## 9. 一句话结论
+
+**三处机制可以收下；本批修复的全部是"防静默失效"类问题——清理必达（唯一例外=产物留存真失败）、校验先于副作用、文档按实际写；生产代码净增 ≈11 行、断言净增 ≈4~6 条（并删 `sent` 相关代码），运行时零变化。**

package/docs/reviews/README.md

@@ -37,6 +37,7 @@
 | `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` 第三交付出口） |
+| `2026-09-25-extension-mechanisms-review.md` | 复验 0.8.2 三处机制（报告落盘 / `--set-viewer` / 观看命令通道）+ 测试覆盖与断言强度 | **① 显示层失败会跳过清理**（BrokenPipe 逃逸 → rmtree 被跳过、目录残留；修法 `_print_best_effort` + rmtree 进 finally ⇒ 清理必达）；**② `--set-viewer` 半成功**（校验在写之后 → rc≠0 但文件已写入；改 B′ 校验前移）；③ 通道模型由「三出口」收敛为四通道角色表，并证实 custom_message 随 fork 进每场上下文；文档三处「不持久化」复述、断言偏弱、prompt 复述、fail-open 宽窄不对称 | `51a4535` |
 
 ## 环境口径（读报告时的背景）
 

package/extensions/multi-viewers/index.ts

@@ -16,11 +16,13 @@
  *
  * 与 CLI 的契约（标记行/退出码）与全部原语见 ./shared.ts。
  *
- * 观看命令交付 = **三个出口**（缺一不可，都是实测暴露的）：
- * ① `ctx.ui.setEditorText` 预填输入框（按 Enter 即执行；**仅 TUI**，pi-web 忽略）
- * ② `notify` 带一份（即时可见；但 pi-web 上关掉弹窗即消失）
- * ③ `pi.sendMessage` 写一条 custom_message 进消息流（**持久可回滚复制**；
- *    代价 = 参与 LLM 上下文的一行）
+ * 观看命令交付 = **四个通道，各司其职**（每一个都是实测逼出来的，见 docs/design.md 决策 22）：
+ * ① `ctx.ui.setEditorText` 预填输入框——TUI 便利（能直接回车跑）；pi-web 忽略
+ * ② `notify`——即时反馈；pi-web 上关掉弹窗即消失
+ * ③ `pi.sendMessage`（custom_message）——**持久留痕**，跨重启仍在；但 pi-web 渲染为
+ *    **折叠的** `multi-viewers (click to expand)`，需点击展开（pi-web 0.5.19 起**实时出现**，
+ *    此前只在重载后可见）；且随 fork 进入每场分析上下文
+ * ④ `ctx.ui.setWidget`——**运行期常驻可见**（一眼看到、不需点击；MC 待办用的同一通道）
  */
 
 import {
@@ -91,7 +93,8 @@ export default function register(pi: any) {
         return;
       }
 
-      // ④ 观看命令：三个出口（见文件头）——预填（仅 TUI）+ notify（即时）+ 消息流（持久）
+      // ④ 观看命令：四个通道各司其职（见文件头与决策 22）——预填（TUI）/ notify（即时）/
+      //    custom_message（留痕）/ widget（常驻可见）
       ctx.ui.setEditorText(watch);
       // 消息流里留一条持久记录：用户实测 pi-web 的 notify 会随弹窗关闭而消失，
       // 关了窗口就再也找不到这行命令。custom_message 进会话（**参与 LLM 上下文**，
@@ -102,6 +105,15 @@ export default function register(pi: any) {
         content: `多视角分析已启动：${dir}\n观看命令（复制执行，不进 LLM）：\n${watch}`,
         display: true,
       });
+      // 常驻面板：custom_message 在 pi-web 是**折叠块**（要点击才展开；0.5.19 起实时出现）
+      // → 观看命令还需要一条**一眼可见、不需点击**的常驻出口。
+      // setWidget 正是这个语义（pi-web 注释："Persistent widget panel … Not a popup"；
+      // 主 pi 的 magic-context 待办面板用的就是它）。
+      ctx.ui.setWidget("multi-viewers", [
+        `多视角分析进行中：${dir}`,
+        `观看（复制执行，不进 LLM）：${watch}`,
+        `插话 /multi-viewers-say <文本>　收尾 /multi-viewers-finish`,
+      ]);
       ctx.ui.notify(
         `分析已启动：${dir}\n` +
           "观看（复制执行；TUI 下已预填进输入框）:\n" +
@@ -167,7 +179,7 @@ export default function register(pi: any) {
       const ok = await ctx.ui.confirm(
         "确认收尾？",
         "将清理分析目录；结果会保存到 `<分析目录>-result.md`，" +
-          "清理时还会打印一次分析报告。",
+          "清理时还会打印并落盘一份报告（<分析目录>-report.txt）。",
       );
       if (!ok) {
         ctx.ui.notify("已取消收尾（分析目录保留）。", "info");
@@ -178,6 +190,8 @@ export default function register(pi: any) {
         ctx.ui.notify(`收尾失败：\n${clean.output}`, "error");
         return;
       }
+      // 收尾成功 → 清掉常驻面板（否则留下一行指向已删除目录的观看命令）。
+      ctx.ui.setWidget("multi-viewers", undefined);
       ctx.ui.notify(
         `${clean.output}\n\n要摘要就在对话里说一声（主 pi 读该 result.md 即可）。`,
         "success",

package/meeting_fs.py

@@ -126,32 +126,24 @@ def _package_dir(source, agent_dir):
     return cand if os.path.isdir(cand) else None
 
 
-def resolve_mc_tools_entry(agent_dir=None):
-    """解析 MC 的**只读工具入口**（`dist/subagent-entry.js`）——"mc-tools" 档用。
-
-    为什么这样解析而不硬编码路径：MC 自己就是用"主入口的**兄弟文件**"
-    （其源码 `resolveSiblingEntryPath("subagent-entry.js")`）定位它。我们的
-    等价做法 = 从 pi 的注册表（settings.json.packages）找到 MC 包目录 → 读它
-    package.json 声明的扩展入口（`pi.extensions[0]`）→ 取同目录下的
-    subagent-entry.js。
+def _packages_of(pkg_name, agent_dir=None):
+    """在 pi 的 packages 里找声明了 `pkg_name` 的包：返回 (candidates, err)。
 
-    **失败语义**：任一步缺失返回 `(None, 原因)`——**由调用方按策略决定**：
-    loop 在生产态做**可见降级**（打印一行说明后按零扩展运行 ✓ 无静默），
-    在严格态（`MV_MC_TOOLS_STRICT=1`，测试/探针保真）直接报错。
+    candidates = [(source, pkg_dir)]，按注册顺序（可能有多个候选——包名相同但
+    来源不同）；err = 读注册表失败的原因（此时 candidates 为空）。
 
-    依赖边界（决策 20）：mc-tools **允许而非要求** MC——缺 MC 即降级为零扩展；
-    `none` 档零依赖（无 MC 的机器/CI 显式选它）。
+    **匹配按裸包名精确相等**（F5）：不能用子串——`in` 会把
+    `@cortexkit/pi-magic-context-legacy` 也命中。npm 源直接比裸名；路径源读
+    它的 package.json.name。**遍历全部候选**（F6：首个匹配不可解析时继续看
+    后面的候选，否则"装着也报没装"，文案误导）。
     """
     agent_dir = agent_dir or pi_agent_dir()
     try:
         with open(os.path.join(agent_dir, "settings.json"), encoding="utf-8") as f:
             pkgs = json.load(f).get("packages") or []
     except (OSError, ValueError) as e:
-        return None, f"读不到 pi 的 packages（{agent_dir}/settings.json）: {e}"
-    # F5：按**裸包名精确相等**识别（npm 源直接比；路径源读其 package.json.name）；
-    # F6：遍历**全部**候选、取首个可解析（此前首个匹配失败即停，装着 MC 也会
-    #     报"没装"，文案误导）
-    seen = []          # 候选（source 字符串）——用于错误文案，说明"试过哪些"
+        return [], f"读不到 pi 的 packages（{agent_dir}/settings.json）: {e}"
+    out = []
     for entry in pkgs:
         source = _entry_source(entry)
         if not source:
@@ -167,32 +159,80 @@ def resolve_mc_tools_entry(agent_dir=None):
                     name = json.load(f).get("name") or ""
             except (OSError, ValueError):
                 name = ""
-        if name != MC_PACKAGE:
-            continue
-        seen.append(source)
+        if name == pkg_name:
+            out.append((source, pkg_dir))
+    return out, ""
+
+
+def _declared_extensions(pkg_name, agent_dir=None):
+    """包名 → (pkg_dir, exts, err)：包目录 + 它自己声明的扩展入口（已归一为列表）。
+
+    exts 来自包 package.json 的 `pi.extensions`（判据**由上游声明**，不硬编码布局）；
+    字符串形态归一为单元素列表（F7：直接取首字符会解析出错误路径）。
+    """
+    cands, err = _packages_of(pkg_name, agent_dir)
+    if err:
+        return None, [], err
+    if not cands:
+        return None, [], f"packages 里没有 {pkg_name}（pi install npm:{pkg_name}）"
+    last = ""
+    for source, pkg_dir in cands:
         try:
             with open(os.path.join(pkg_dir, "package.json"), encoding="utf-8") as f:
                 man = json.load(f)
         except (OSError, ValueError) as e:
-            return None, f"读不到 {MC_PACKAGE} 的 package.json: {e}"
+            last = f"读不到 {pkg_name} 的 package.json: {e}"
+            continue
         exts = (man.get("pi") or {}).get("extensions")
-        if isinstance(exts, str):          # F7：字符串形态（取首字符会解析错路径）
+        if isinstance(exts, str):
             exts = [exts]
         if not isinstance(exts, list) or not exts or not all(
                 isinstance(x, str) and x for x in exts):
-            return None, f"{MC_PACKAGE} 的 pi.extensions 形态不可用（版本不兼容？）"
-        cand = os.path.normpath(
-            os.path.join(pkg_dir, os.path.dirname(exts[0]), "subagent-entry.js"))
-        if os.path.isfile(cand):
-            return cand, ""
-        # 该候选不可解析 → 继续看后面的候选（F6）
-        last_missing = os.path.relpath(cand, pkg_dir)
-    if seen:
-        return None, (f"{MC_PACKAGE} 的只读工具入口不存在（{last_missing}）"
-                      f"——上游版本可能改了布局")
-    return None, (f"packages 里没有可解析的 {MC_PACKAGE}——装它"
-                  f"（pi install npm:{MC_PACKAGE}），或改用零扩展档："
-                  f"--extension-policy none")
+            last = f"{pkg_name} 的 pi.extensions 形态不可用（版本不兼容？）"
+            continue
+        return pkg_dir, exts, ""
+    return None, [], (last or f"{pkg_name} 的扩展入口不可用")
+
+
+def resolve_mc_tools_entry(agent_dir=None):
+    """解析 MC 的**只读工具入口**（`dist/subagent-entry.js`）——"mc-tools" 档用。
+
+    路径推理：MC 自己就是用"主入口的**兄弟文件**"（其源码
+    `resolveSiblingEntryPath("subagent-entry.js")`）定位它；我们等价地读它声明的
+    扩展入口（`pi.extensions[0]`），再取同目录下的 subagent-entry.js。
+
+    失败语义（与 resolve_mcp_adapter_entry 同）：任一步缺失返回 `(None, 原因)`
+    ——**由调用方按策略决定**：loop 生产态做**可见降级**，严格态
+    （`MV_MC_TOOLS_STRICT=1`）直接报错。
+    """
+    pkg_dir, exts, err = _declared_extensions(MC_PACKAGE, agent_dir)
+    if err:
+        return None, err
+    cand = os.path.normpath(
+        os.path.join(pkg_dir, os.path.dirname(exts[0]), "subagent-entry.js"))
+    if os.path.isfile(cand):
+        return cand, ""
+    return None, (f"{MC_PACKAGE} 的只读工具入口不存在"
+                  f"（{os.path.relpath(cand, pkg_dir)}）——上游版本可能改了布局")
+
+
+def resolve_mcp_adapter_entry(agent_dir=None):
+    """解析 MCP adapter 的扩展入口（它声明的 `pi.extensions[0]`）——mc-tools 第二份。
+
+    为什么需要：MCP 工具（web_search / web_reader / zread…）由 pi-mcp-adapter
+    提供，而 `--no-extensions` 关掉的是**扩展发现**——显式 `-e` 路径照常生效
+    （pi --help 原文）。不显式加载 = agents 完全没有联网检索能力。
+
+    与 MC 的差别：这里要的**就是主入口本身**（它注册 MCP 工具），不取兄弟文件。
+    """
+    pkg_dir, exts, err = _declared_extensions(MCP_ADAPTER_PACKAGE, agent_dir)
+    if err:
+        return None, err
+    cand = os.path.normpath(os.path.join(pkg_dir, exts[0]))
+    if os.path.isfile(cand):
+        return cand, ""
+    return None, (f"{MCP_ADAPTER_PACKAGE} 声明的入口不存在"
+                  f"（{os.path.relpath(cand, pkg_dir)}）")
 
 
 def pi_agent_dir():
@@ -778,6 +818,10 @@ def mc_tools_strict():
 # 入口是它的内部文件，路径解析见 resolve_mc_tools_entry 的 docstring）
 MC_PACKAGE = "@cortexkit/pi-magic-context"
 
+# MCP 工具（web_search / web_reader / zread…）的提供者——mc-tools 档的第二份入口。
+# 名字**由 pi 的注册表给**（settings.json.packages），这里只做精确匹配用。
+MCP_ADAPTER_PACKAGE = "pi-mcp-adapter"
+
 FORK_MODES = ("budget", "compaction", "full")
 DEFAULT_FORK_MODE = "budget"
 #

package/meeting_loop.py

@@ -330,19 +330,36 @@ def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
     if extension_policy == "none":
         cmd += no_ext
     elif extension_policy == "mc-tools":
-        entry, err = meeting_fs.resolve_mc_tools_entry()
-        if entry:
-            cmd += no_ext + ["-e", entry]
-        elif meeting_fs.mc_tools_strict():
-            # 严格模式（测试/探针保真）：缺 MC 即响，不降级——否则测试可能在
-            # "没装 MC"的环境里通过，而 ctx_search 从未生效
-            log(agent, f"[fatal] mc-tools 档入口解析失败（严格模式）：{err}")
-            raise RuntimeError(f"mc-tools 档不可用: {err}")
-        else:
-            # mc-tools **允许**而非要求 MC：缺 MC → 降级零扩展，但**可见**
-            effective_policy = "none"
-            downgrade_reason = err
-            cmd += no_ext
+        # mc-tools = 零扩展 + 显式加载**两份只读工具入口**（2026-09-25 用户裁定 B：
+        # 并入默认档，不再新增档位——保持简单）：
+        #   ① MC 的 subagent-entry（只注册工具、不装 hook）→ ctx_search
+        #   ② MCP adapter（web_search / web_reader / zread 等 MCP 工具）
+        # 为什么必须显式 -e：`--no-extensions` 关的是**发现**，显式路径照常生效
+        # （pi --help 原文）；MCP 工具此前因发现被关而对 agents 完全不可用。
+        # 两份入口**各自独立**降级（允许而非要求）——缺哪个就少哪个，都**可见**。
+        resolved = []          # [(label, entry)]
+        missing = []           # [(label, err)]
+        for label, resolver in (
+                ("ctx_search（MC 只读检索）", meeting_fs.resolve_mc_tools_entry),
+                ("MCP 工具（web_search 等）", meeting_fs.resolve_mcp_adapter_entry)):
+            entry, err = resolver()
+            if entry:
+                resolved.append((label, entry))
+            else:
+                missing.append((label, err))
+        cmd += no_ext
+        for _label, entry in resolved:
+            cmd += ["-e", entry]
+        if missing:
+            reason = "；".join(f"{label} 不可用（{err}）" for label, err in missing)
+            if meeting_fs.mc_tools_strict():
+                # 严格模式（测试/探针保真）：缺入口即响，不降级——否则测试可能在
+                # "没装某入口"的环境里通过，而该工具从未生效
+                log(agent, f"[fatal] mc-tools 档入口解析失败（严格模式）：{reason}")
+                raise RuntimeError(f"mc-tools 档不可用: {reason}")
+            # 允许而非要求：缺入口 → 少一份 -e，但**可见**
+            downgrade_reason = reason
+            effective_policy = ("mc-tools" if resolved else "none")
     # "all"：不加任何 --no-*（走 pi 默认发现）
     if first_wake:
         # 登记行（观测面的稳定字段；报告据此给"声明 vs 生效"）。只在首唤打：
@@ -351,8 +368,10 @@ def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
                    f" strict={int(meeting_fs.mc_tools_strict())}"
                    + (f" 降级原因={downgrade_reason}" if downgrade_reason else ""))
         if downgrade_reason:
-            log(agent, f"mc-tools 档未生效（{downgrade_reason}）——本次按零扩展"
-                       f"运行：ctx_search 不可用")
+              log(agent, f"mc-tools 档{'部分' if resolved else '完全'}未生效"
+                         f"（{downgrade_reason}）——本次按"
+                         f"{'已解析的入口' if resolved else '零扩展'}运行："
+                         f"缺失的工具在本次分析中不可用")
     model = cfg.get("model") or ""
     if model:
         cmd += ["--model", model]

package/mv_cli.py

@@ -186,11 +186,9 @@ def _validate_and_print_viewers(vdir):
             notes.append("空：没有视角内容")
         suffix = f"（{'；'.join(notes)}）" if notes else ""
         print(f"  {n}.md{suffix}")
-    err = spec_gen.validate_participants(names)
+    err = spec_gen._viewer_set_errors(names, empty)
     if err:
         fail_verbatim(err)
-    if empty:
-        fail_verbatim(spec_gen.viewer_set_error(names, empty))
     gap = spec_gen.viewers_count_gap(names)
     if gap:
         print(f"  校验：{gap}（建 1 个是合法的中间状态）")
@@ -217,8 +215,19 @@ def cmd_set_viewer(args):
         fail(f"非法视角名（{err}）：{name}")
     vdir = os.path.join(os.getcwd(), "viewers")
     target = os.path.join(vdir, f"{name}.md")
-    if os.path.exists(target):
+    # lexists（不是 exists）：悬空符号链接在 exists 下为假 → 会被"覆盖"写入，
+    # 违背"绝不覆盖"的承诺（悬空链接是这条承诺目前的唯一破口）。
+    if os.path.lexists(target):
         fail(f"视角已存在，不覆盖: {target}（改名，或直接编辑该文件）")
+    # **写前**做集合级校验（评审 ② B′）：否则 viewers/ 里已有坏文件时，本命令
+    # 会"先写成功、再以 rc≠0 退出"——副作用已发生却报失败（半成功）。
+    # 用 if names 守卫：names 为 None 表示目录还不存在/还没有视角，那是合法起点
+    # （不守卫会让 validate_participants(None) 抛 TypeError——首次建视角即命中）。
+    names, _briefs, empty = spec_gen._discover_viewers(vdir)
+    if names:
+        err = spec_gen._viewer_set_errors(names, empty)
+        if err:
+            fail_verbatim(f"{err}\n（修正 viewers/ 后再建新视角——本次未写入任何文件）")
     body = sys.stdin.read().strip()
     if not body:
         fail(f"视角内容为空（{name}）——正文从 stdin 传入；空视角没有 lenses，"

package/observability.py

@@ -1,8 +1,9 @@
 """观测层——状态判定 / --report / --wait（从 start_discussion 拆出，S2）。
 
 职责：**运行期只读观测**——check_status 状态机、--report 观测面聚合、
---wait 阻塞观察、loop 进程存活检测。不写任何产物（报告不落盘——
-观测面契约：冷路径一次性，不持久化）。
+--wait 阻塞观察、loop 进程存活检测。本层**不写任何文件**：报告的唯一落点
+在 `start_discussion.cleanup_discussion`（删目录前打印并落盘一份
+`<base>-report.txt`，观测数字可复查）——本模块只生成行、不负责落地。
 
 依赖方向：只准 import meeting_core / meeting_fs / meeting_engine /
 human_viewer（observability 是"读"侧，human_viewer.incremental 是它
@@ -214,8 +215,9 @@ def build_report(base):
 
     契约（design.md 观测面契约节）：
     - **冷路径一次性**：不常驻、不被轮询；调用方（人/主 pi）按需触发。
-    - **不持久化**：视图不占"数字的家"——数字的家是 bare（判定域）、
+    - **本函数不落盘**：视图不占"数字的家"——数字的家是 bare（判定域）、
       loop log 的登记字段、pi session 的文档化字段；报告只是它们的一次投影。
+      唯一的落盘点是 `cleanup_discussion`（删目录前写 `<base>-report.txt`）。
     - **fail-open**：任何一段读不出（缺目录/缺文件/格式变）→ 该段显示 n/a，
       不报错、不改判定、不阻塞。
     - **跨度分标**：进程跨度（elapsed_ms）≠ per-response 跨度（session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-viewers",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "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

@@ -16,7 +16,6 @@ description: 建立多视角分析的 viewers/ 视角文件（交互式：先建
 
 - 这一步**只提议**：不建文件、不改任何东西
 - 建几个**由用户决定**（只建 1 个也行）
-- 名字规则由第 3 步的命令强制（顺带一提：中文、短、不含空白与路径分隔符）
 
 **然后结束本回合，等用户输入。**
 
@@ -27,14 +26,7 @@ description: 建立多视角分析的 viewers/ 视角文件（交互式：先建
 
 ## 第 3 步：用命令建文件（内容经 stdin 传给命令，不要直接写文件）
 
-先读 `README.md` 的「视角文件写什么」节（唯一事实源：三个要点 + 正误对照）。要点：
-
-- 纯内容、无 frontmatter、无标题——**文件名就是全部元数据**
-- 必含三条：① **单一 lenses**（所有观点必须从该视角出发）② **不越界**（其它视角由
-  别的参与者负责；**不要**列举是哪几个——参与者会变，列举会过期）③ **交锋义务**
-  （对其它视角的观点可认同或反驳，但要用本视角的论据）
-- **只写视角本身**：身份（"你是 X"）、参与者名单、消息格式、独立参与者纪律都由脚本
-  生成，**不要写进文件**
+先读 `README.md` 的「视角文件写什么」节——那是唯一事实源（三个要点、正误对照、命名规范）。
 
 每个视角调用一次（正文经 stdin；**命名合法性、不覆盖已有、空正文拒绝、写完校验并
 回显**都由命令保证，不需要你另外检查）：

package/spec_gen.py

@@ -478,6 +478,21 @@ def viewer_set_error(names, empty, where="viewers/"):
     return f"错误: {gap}" if gap else None
 
 
+def _viewer_set_errors(names, empty, where="viewers/"):
+    """集合级校验的**唯一组合点**：整组名字 + 空正文 + 数量 ≥2。
+
+    为什么单独存在：`--viewers`（只读检查）与 `--set-viewer`（写前校验）必须
+    用**同一套**判据——同一套规则曾在两处漂移过（文案与检查项不一致）。
+    `if empty` 是必要保护：否则 viewers/ 里只有一个**合法**视角时，
+    `viewer_set_error` 会因为数量不足而报错，把"建第 2 个视角"判成非法。
+    `names` 为空（目录缺失/无 .md）返回 None——那是"还没有视角"，不是错误。
+    """
+    if not names:
+        return None
+    return (validate_participants(names)
+            or (viewer_set_error(names, empty, where) if empty else None))
+
+
 def _discover_viewers(viewers_dir):
     """发现 viewers 目录（多视角产品约定）：*.md 文件名即 agent 名。
 

package/start_discussion.py

@@ -424,52 +424,85 @@ def setup_environment(args, participants, base, spec_dir=None,
           f"extensionPolicy={args.extension_policy}")
 
 
+def _print_best_effort(*args, **kwargs):
+    """打印，但**绝不让显示层失败影响主职责**（清理 / 产物留存）。
+
+    为什么需要：`cleanup_discussion` 的输出可能在管道关闭时抛
+    `BrokenPipeError`（`| head`、终端断开、CI 截断）——实测复现：异常从 print
+    逃逸 → **`rmtree` 被跳过**，目录残留且 rc≠0，即"该清理的没清理"
+    （2026-09-25 评审批 ①(c)）。显示层从来不是主职责，失败只能被忽略。
+
+    契约：`cleanup_discussion` 的**全部 stdout 都走本函数**（该函数内不得出现
+    裸 `print(`，可 grep 校验）；于是不变量成立——**rmtree 必达**，唯一例外
+    是产物留存真失败（那在 `_preserve_result_md` 里冒泡，见其注释）。
+    """
+    try:
+        print(*args, **kwargs)
+    except Exception:                            # noqa: BLE001（显示层失败永不上抛）
+        pass
+
+
 def _preserve_result_md(base):
     """清理前保存 result.md（薄包装 → meeting_fs.preserve_result_md，
-    T2 合并：与 loop 退出路径共享同一实现）。"""
+    T2 合并：与 loop 退出路径共享同一实现）。
+
+    这里的失败**必须冒泡**（不吞）：result.md 的权威位置在 `<base>/repo.git`，
+    即**待删目录之内**——留存失败还继续删 = 永久丢失产物。所以它不包在
+    报告段的 try/finally 里（评审批 ①(c)：唯一允许阻断清理的失败）。
+    """
     dest = meeting_fs.preserve_result_md(base)
     if dest:
-        print(f"[cleanup] 已保存 result.md → {dest}")
+        _print_best_effort(f"[cleanup] 已保存 result.md → {dest}")
 
 
 def cleanup_discussion(base):
-    """清理一次讨论：保存 result.md（若存在）→ 删目录。
+    """清理一次讨论：保存 result.md（若存在）→ 打印并落盘报告 → 删目录。
 
     result.md 是讨论唯一产物（审核报告等）——清理前先从 bare git 历史
     复制到父级目录（<base名>-result.md），避免清理丢产物（用户建议）。
+    报告在本步**打印并落盘**到 `<base>-report.txt`（原先只在终端出现一次，
+    目录删掉后无法复查——复盘时长口径时踩到）：观测数字应当可复查。
     Pi 的 session 文件存放在 <base>/pi-sessions，随目录一起删除，无需
     额外清理全局 DB。
     不负责终止 loop 进程（职责边界，用户 2026-08-31 定）——loop 每轮
     检测到 repo.git 消失即自行退出（meeting_engine.agent_loop）。
+
+    失败语义（评审批 ①(c) 冻结）：**rmtree 必达**；报告生成 / 打印 / 落盘
+    失败都不阻断清理（fail-open，捕 `Exception` 而非只捕 `OSError`——两段
+    对称，不依赖"这些代码只可能抛 OSError"的脆弱推理）；唯一例外是
+    `_preserve_result_md` 真失败（I/O）→ 冒泡且**不删目录**。
+    清理成功返回 0（显示层失败不算失败）。
     """
     if not os.path.isdir(base):
-        print(f"[cleanup] 目录不存在: {base}")
+        _print_best_effort(f"[cleanup] 目录不存在: {base}")
         return
     _preserve_result_md(base)
-    # 报告（**删目录前最后一次可读**——目录删后 --report 不可用）。
-    # 报告是附加信息、清理是主职责：报告生成失败**不阻断**清理
-    # （fail-open 只在这一层兜底——build_report 内部各段已各自 fail-open）。
-    print("[cleanup] —— 本次分析报告（删除目录前最后一次可读）——")
-    lines = None
     try:
-        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)
+        # 报告（**删目录前最后一次可读**——目录删后 --report 不可用）。
+        # 报告是附加信息、清理是主职责：报告生成失败**不阻断**清理
+        # （fail-open 只在这一层兜底——build_report 内部各段已各自 fail-open）。
+        _print_best_effort("[cleanup] —— 本次分析报告（删除目录前最后一次可读）——")
+        lines = None
         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）")
+            lines = list(build_report(base))
+            for line in lines:
+                _print_best_effort(line)
+        except Exception as e:                   # noqa: BLE001（兜底不吞：打印）
+            _print_best_effort(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_best_effort(f"[cleanup] 报告已保存 → {rp}")
+            except Exception as e:               # noqa: BLE001（同生成段：对称）
+                _print_best_effort(f"[cleanup] 报告保存失败（不影响清理）: {e!r}")
+    finally:
+        shutil.rmtree(base)                      # 必达（唯一例外见 docstring）
+    _print_best_effort(f"[cleanup] 已删除目录 {base}（含 pi-sessions）")