pi-multi-viewers 0.2.0 → 0.2.2

package/AGENTS.md

@@ -176,7 +176,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
   extension × 1（multi-viewers-say 插话：零 LLM，直接 spawn human_sayer.py；
   目录发现 = `<cwd>/mv-<sessionId>-*` 最新，兜底 `mv-*`（排除
   `mv-spec-*`）并警告）
-  + wrapper。**npm 已发布 0.2.0（2026-09-11）**。
+  + wrapper。**npm 已发布 0.2.2（2026-09-11）**。
 - **开发机安装（两步，缺一不可；2026-09-10 实测）**：
   ① `pi install /root/pi-multi-viewers`——**注册包**（写
   `~/.pi/agent/settings.json` 的 `packages` 数组）；pi 不是"扫 node_modules

package/README.md

@@ -74,6 +74,12 @@ ls ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh
 两个 pi 命令入口（视角/主题走 prompt，插话走 extension——插话是"本地命令
 执行"，不需要经过 LLM）。
 
+**目录可以省略**：`--view`/`--say`/`--status`/`--report`/`--wait`/`--cleanup`
+不带目录时自动定位"本 session 当前分析"（`mv-<sessionId>-*` 最新；找不到
+则取最新 `mv-*` 并警告；判据 = 含 `repo.git`）。传目录仍支持（显式优先）。
+这样路径不需要经过任何 LLM 记忆——此前命令都要求绝对路径，等于让主 pi
+把长路径记在上下文里复用。
+
 或命令行：
 
 ```bash
@@ -88,15 +94,16 @@ scripts/mv.sh --start <spec目录>              # 启动（自动挂载主 sessi
 #  高级：--agents "a,b" 起一次性视角（不建 viewers/ 时用；prompt 入口不传它）
 
 # 观看：--start 会输出可直接执行的 !! 流式观看命令（复制执行）
-scripts/mv.sh --view <dir>                    # 或一次性增量查看（主 pi 记录 HEAD 作下轮 --since）
+scripts/mv.sh --view                          # 一次性增量查看（主 pi 记录 HEAD 作下轮 --since）
 #  --follow 会打印【状态】(meeting/all-freezing/round-robin/concluded)
 #         与【进度】(meeting 消耗/上限 ｜ freezing 集合 ｜ rr → 下一位)
+#         结束时自动附【分析报告】（消息/墙钟/配额/进程跨度/LLM 用量）
 
-# 插话 / 状态 / 收尾
-scripts/mv.sh --say <dir> "<文本>"             # 插话（命令行形态；pi 内用 /multi-viewers-say）
-scripts/mv.sh --status <dir>                  # running / done / stalled / stopped
-scripts/mv.sh --report <dir>                  # 只读报告（流程/配额/进程/LLM；冷路径，不持久化）
-scripts/mv.sh --cleanup <dir>                 # 收尾（result.md 自动留存到 <dir>-result.md）
+# 插话 / 状态 / 收尾（目录可省略——自动定位本 session 当前分析）
+scripts/mv.sh --say "<文本>"                   # 插话（命令行形态；pi 内用 /multi-viewers-say）
+scripts/mv.sh --status                        # running / done / stalled / stopped（done 时附 [result] 路径）
+scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM；冷路径，不持久化）
+scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存到 <dir>-result.md）
 ```
 
 ## 视角文件写什么（`viewers/<视角名>.md`）

package/docs/design.md

@@ -100,7 +100,18 @@ compaction 的 `firstKeptEntryId` 起 + 其后的条目"——窗口内含 compa
 | `status-<agent>.json` | loop | `{"sessionID": ...}` | 流程（崩溃恢复） | 是（恢复用） | O(1) |
 | `pi-sessions/fork-src-*.jsonl` | pi | 文档化 session schema | fork 构建 + `--report` | 否（报告用） | O(MB) 全量 → **禁轮询** |
 | `result.md`（固定位） | resultWriter loop | 结论文档 | 人 | 是（收尾判据） | — |
-| `--report`（视图） | start_discussion | 文本行 | 人/主 pi | **否**（不得升级为验收 gate） | 冷路径一次性 |
+| `--report`（视图） | observability | 文本行 | 人（**三个出口**，见下） | **否**（不得升级为验收 gate） | 冷路径一次性 —— **O(session 大小)**：每 agent 读整个 fork-src jsonl（实测 3 × 789KB ≈ 2.4MB/次、50–150ms/次，×3 出口 <0.3s/次分析），**不得进入任何轮询路径**（e2e16 评审量化） |
+
+**报告的三个出口**（同一 `build_report`，同一份内容）：
+1. **`--follow` 结束**——viewer 在 done 分支自动附报告（`human_viewer._print_report`）。
+   这是**用户通道自带**：用户执行 `!!` 命令就在结束时直接看到，**零 LLM 参与**
+   （此前只靠 prompt 要求主 pi"记得转述"——那是 LLM 依赖，会漏；机制化后
+   用户必然看到）。
+2. **`--cleanup`**——删目录前最后一次可读（结果与 1 重复出现是刻意的：
+   不同时点各看一次，且清理后现场已不存在）。
+3. **`--report`**——独立入口（中途查看 / 脚本消费）。
+`--view --since`（主 pi 增量轮询通道）**不附报告**——它面向 LLM，
+输出进 context，报告对模型无用且占 token。
 
 ### 本轮边界（`mv.analysis-start`）
 
@@ -265,7 +276,39 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     `start_discussion.check_status` 与定义处同址，拆后 mock re-export
     不生效——本轮 4 处测试因此假绿/失败，已改到 `spec_gen` /
     `observability`）。
-14. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
+14. **报告附在 `--follow` 输出末尾（机制化，不依赖 LLM）**：`--follow` 是
+    用户直接执行的通道（`!!`），done 时自动打印报告——用户零操作看到运行
+    事实。**为什么不能只靠 prompt**：让主 pi"记得跑 `--report` 并转述"是
+    流程依赖 LLM（会漏、不可验收），正是本项目一贯要消除的形态；报告既然
+    是给用户的，就该长在用户直接看的通道上。`--view --since` 不附（主 pi
+    通道，进 context 且对模型无用）。
+15. **消费命令的目录可省略（自动发现，仅精确 sid 匹配）**：`--view/--say/
+    --status/--report/--wait/--cleanup` 不带目录 → 按 cwd + `PI_SESSION_ID`
+    发现当前分析（`mv-<sid>-*` 最新；判据 = 含 `repo.git`，同 engine
+    "bare 是分析存在的唯一标志"；`mv-spec-*` 不在前缀内）。
+    **无降级兜底**（e2e16 评审 2:0:1 裁定）：曾有"无 sid 匹配 → 取项目下
+    最新 `mv-*`"的兜底，三宗罪——①破坏性操作（`--cleanup`/`--say`）会作用
+    于**猜测目录**；②降级只能靠 stderr 中文文案识别（extension 曾用
+    `includes("警告")` 还原布尔，文案一改静默失效，与"判据用退出码"自相
+    矛盾）；③"最新"按整名排序，跨 sid 时**系统性取旧**。核查确认**不存在
+    "必须无目录且必然无 sid"的设计内场景**（pi 两条通道都有 sid，终端主路径
+    本就显式带目录）→ 未匹配 = rc 1 报错请显式传目录。
+    **动机**：唯一知道路径的是 `--start` 的输出，此前每个消费命令都要求
+    传它 → 主 pi 必须把长绝对路径记在 LLM 上下文里复用（改错/截断/相对
+    路径都出过）。发现逻辑下沉后**路径不经过 LLM**。
+    实现单点 = `observability.find_current_dir`（wrapper 的 `resolve_dir`
+    与 extension 同走 `observability.py --find-dir`——此前只有 extension
+    里一份 TS 实现，wrapper 侧完全没有，两份口径会漂移）。
+    `--say` 两形态**按参数个数区分**（1 个 = 文本+自动发现；2 个 = 目录+
+    文本）——不是按值猜语义。
+    配套：`--status` 在 done 时打印 `[result] <路径>`（目录可省略后调用方
+    无法自己拼 `<目录>-result.md`，路径必须由机制给出）。
+16. **prompt 里的失败判据用退出码，不用报错文本匹配**：原 prompt 要求
+    "若报错含'未找到 viewers/ 目录'…" —— 匹配 stderr 文案，wrapper 文案
+    一改就静默失配（LLM 会以为没报错而继续）。改为"命令非零退出 → 停下来
+    读报错原文问用户"：判据降为退出码（wrapper 的 `fail()` 保证 `exit 1`），
+    原因解释交还给输出原文。
+17. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
    注入于 spawn）；主项目仓库不在守卫范围（agent 的 cwd 就是主项目，其
    约束归指令层 + 主项目 `.gitignore`）。要拦主仓库需换机制类（沙箱/钩子），
    经评估收益不支撑扩面。

package/docs/reviews/2026-09-11-e2e16-mechanization-review.md

@@ -0,0 +1,177 @@
+> **存档说明**：2026-09-11 真实多视角分析（性能 / 简单 / 铁律）的 result.md
+> 原文，主题为「审阅本项目最近两项机制化改动（消费命令目录可省略 + 报告
+> 机制化）的实现质量与遗漏」——即对 `be958ec` 与 `d20fc46` 的自审。
+> **抓到 1 个真回归（F5：`--view` 显式目录被静默丢弃）与 1 个高危设计缺陷
+> （降级兜底：破坏性操作可作用于猜测目录）**，另有 5 条中低问题与 7 项
+> "确认符合设计"。修复见后续 commit。
+> 报告编号（F1–F8 等）为**当次讨论内部编号**，不可跨文档核验；引用的行号与
+> 实测数字均对应当时工作区状态。
+
+# 多视角分析结论：两项机制化改动的审阅
+
+**主题**：审阅 `be958ec`（消费命令目录可省略）与 `d20fc46`（报告机制化）的实现质量与遗漏
+**分析目录**：`mv-mv-main-20260911-225616`
+**参与者**：性能 / 简单 / 铁律（+ human 插话 1 条）
+**收敛**：全员 pass，本文件为收敛结论的唯一权威版本
+**方法**：只审代码与 git 历史，不修改、不运行测试；产出意见清单并对清单达成一致
+
+---
+
+## 一、结论摘要
+
+**总体判断**：两项改动的主体符合设计意图，方向正确；但 **目录可省略在 wrapper 层
+引入了一个真回归（高危）**，且其"降级兜底"分支是四类症状的共同根因——**三方推荐
+整个删除**。报告机制化通过（唯一要求：约束成文）。
+
+**问题清单 8 条**：高 2 / 中 1 / 低 3 / 观察 2。
+
+| # | 严重度 | 问题 | 处置 |
+|---|---|---|---|
+| 1 | **高** | `--view` 显式目录被静默丢弃（回归） | **修**（参数规则统一 + 补测试） |
+| 2 | **高** | 降级发现可作用于破坏性操作（`--cleanup` 删猜测目录） | **删降级兜底**（推荐，2:0:1） |
+| 3 | 中 | 降级信号经 stderr 中文文案解析（`err.includes("警告")`） | 随 #2 一并消失 |
+| 4 | 中 | 降级"最新"按全名排序（跨 sid 取旧目录，与 docstring 不符） | 随 #2 一并消失 |
+| 5 | 中 | 报告 = O(session) 冷路径 × 3 出口，护栏仅存于隐含前提 | **约束成文**（禁入轮询） |
+| 6 | 低 | `result_path` 越界在 viewer（拼路径+组合层为拼串 import） | 移 `meeting_fs` |
+| 7 | 低 | 未找到目录两条错误文案（python + wrapper 各一条） | 留 python 一处 |
+| 8 | 低 | 流程段口径未说明（消息数含流程信号 vs 配额只计 meeting） | 口径行补半句 |
+| — | 观察 | viewer ↔ observability 环（本次新增反向边） | 不 callback 化，不再加边 |
+
+---
+
+## 二、逐条结论与依据
+
+### F5【高】`--view` 显式目录被静默丢弃
+
+- **位置**：`scripts/mv.sh:113-119`。shift 吃掉首参后**总是**走
+  `resolve_dir ""`（自动发现），显式目录被丢弃。
+- **性质**：相对改动前的**行为回退**（改前 `normalize_dir "$1"` 显式生效）；
+  且是**静默**的——多 `mv-*` 并存或跨目录调用时会看错对象且无提示。
+- **测试缺口（根因）**：`tests/test_wrapper.py:195` 仅有无参形态 `["--view"]`，
+  显式目录零覆盖——测试全绿（395）没挡住的直接原因。
+- **修复**（三方一致）：
+  ```bash
+  # 首参非空且非 --since → 显式目录；否则自动发现
+  if [ -n "${1:-}" ] && [ "${1:-}" != "--since" ]; then
+      dir="$(resolve_dir "$1")"; shift
+  else
+      dir="$(resolve_dir "")"
+  fi
+  ```
+  与 `status/report/wait/cleanup` 的 `resolve_dir "${1:-}"` 同一判据；
+  `--say` 保持"按参数个数"（文本可含空格/以 `--` 开头，**不能**按值判形）。
+- **性能补证**（性能视角）：显式目录**反而省一次 find-dir spawn**——修 F5
+  是恢复更快的路径，不是"加回功能付性能代价"。
+- **验收**：补显式目录形态测试；这是"全绿没挡住"的教训，不只是修一行。
+
+### F1/F2/F7 + 简单#2【高】降级兜底 = 一个概念，推荐整体删除
+
+四类症状同一根因（"无 sid 匹配 → 取项目下最新 `mv-*`"的降级兜底）：
+
+| 症状 | 后果 |
+|---|---|
+| **F1** 降级无机器判据（退出码仍 0，仅 stderr 文案） | `mv.sh --cleanup`（无参）**可删除不是本次分析的目录**；`--say` 可写错分析 |
+| **F2** extension 靠 `err.includes("警告")` 还原布尔 | 文案一改，降级判断**静默**失效（同仓库内与"判据改退出码"的最新修正相矛盾） |
+| **F7** `sorted(os.listdir)[-1]` 在降级路径比较整名（含 sid） | `mv-zzz-2025…` 排在 `mv-aaa-2026…` 后 → **系统性选旧目录**（与 docstring"取最新"不符） |
+| 简单#2 | 同一概念的第四面 |
+
+- **收敛（2:0:1）**：简单 + 铁律支持**删除**；性能中性（"不构成支持或反对理由"）。
+- **删除依据（关键事实，经三方核查）**：**不存在"必须无目录且必然无 sid"的设计内
+  场景**——pi 内两条通道都有 sid（bash 注入 / extension `ctx.sessionManager`）；
+  终端主路径是 `--start` 输出的观看命令（本就显式带目录）；代码里兜底的原始动机是
+  "PI 环境变量未注入时 wrapper 拿不到 sid"，属 pi 流程自身降级，不是给人用的便利。
+  → 兜底不对任何设计流程构成负载。且**破坏性操作不应由工具猜目标**：
+  最坏失败从"静默删错目录"变为"响亮报错要求显式目录"。
+- **删除方案**：仅精确匹配 `mv-<sid>-*`（同 sid 时间戳可比 → F7 消失）；
+  未匹配 → rc 1 报错，请调用方显式传目录 → F1/F2/简单#2 同时消失。
+- **执行收尾三条**（简单视角提出，三方确认）：
+  1. **`degraded` 概念删净**：`find_current_dir` 返回值收为一元（`path | None`）；
+     `--find-dir` 退出码只留 0/1（**不留 rc 2 语义**）；extension 的
+     `includes("警告")` 与 notify 警告分支一并删——不留无人消费的死代码。
+  2. **错误文案留一处**：留 python 的（工具层贴近原因）；wrapper `resolve_dir`
+     在 spawn 失败/rc=1 时透传 python stderr 后 `exit`，不另打一条。
+  3. **测试变更**：删降级用例；加"无 sid 匹配 → rc 1"；**保留并新增显式目录用例**
+     （F5 验收）。
+- **备选（若最终选择保留）**：**必须三件套齐做**——rc 契约（0 精确/2 降级/1 未找到）
+  + 写操作（`--cleanup`/`--say`）降级时 fail 且**列出候选目录** + F7 时间戳排序。
+  **半保留不可接受**（只做 rc 不修 F7 = 警告之后仍系统性读错对象）。
+  删/留方案应记入本文件为**分歧项与备选**，非一致意见。
+
+### F-报告【中】报告 = O(session) 冷路径 × 3 出口 → 约束成文
+
+- **实测（性能视角）**：每 agent 读整个 fork-src jsonl，本次 3 × 789KB = **2.4MB/次**；
+  `iter_after_boundary` 逐行扫到边界（本次边界在 777 行中第 772 行 → **99.4% 读取
+  用于跳过前缀**）；量化 **50–150ms/次**，×2 出口 ≈ **<0.3s/次分析**。冷路径可接受。
+- **处置**：把"报告是 O(session 大小) 的冷路径、**不得进入任何轮询路径**"
+  写入既有观测面契约（design.md 契约表"冷路径一次性"行后补半句，**不新开节**）。
+- **不做**尾部 seek 优化（为省 <50ms 引入行/字节边界复杂性——复杂度不匹配）。
+- 出口应为 3 个（`--report` / `--cleanup` / `--follow` 结束）；`--view --since`
+  不附报告（进 LLM context，无用且占 token）——符合职责归属。
+
+### F3【低】`result_path` 不在常量家
+
+- `human_viewer.py:49-56` 定义 `f"{base}-result.md"`；S1 已把 "文件叫什么/多大算
+  有效" 收进 `meeting_fs`（`RESULT_MD` / `RESULT_MD_MIN_BYTES`），但拼路径留在
+  viewer → 组合层（`start_discussion.py:610`）为拼字符串 import 展示模块。
+- 处置：移 `meeting_fs`（与 `RESULT_MD` 同家），viewer re-export 兼容。
+
+### F4【观察】viewer ↔ observability 环
+
+- `observability → human_viewer` 是既有边（`--wait` 用 incremental/is_finished）；
+  `human_viewer → observability`（`_print_report` 延迟 import）是**本次新增的反向边**。
+- 处置：**不 callback 化**（2 行延迟 import 换接口变化 + 两处调用方改动 = 净增）；
+  保持现状 + **不再往环上加第三条边**。`observability.py:156` 函数内重复
+  `import human_viewer`（顶层已有）为纯清理项，可延后。
+
+### F8【低】流程段口径行
+
+- "消息 N（含流程信号）" = 消息文件数（含 freezing/pass/concluded + human），
+  与配额段（仅 `mode=meeting` 且 `type=message`）并列时同一 agent 两个数字。
+- 处置：末尾口径行补半句"消息数含流程信号；配额只计 meeting 发言"。
+
+---
+
+## 三、经检查确认符合设计（不构成问题）
+
+1. **流程段弃用 commit subject 正则、改消息文件计数**（`observability.py:241`）：
+   去掉自由文本耦合（格式一改就静默归零），并与配额/冻结/RR 共用同一次
+   `each_agent_messages` 读取——一次读取派生四段，本轮最大的简化净收益。
+2. **extension 删除 TS 版重复发现实现**，改调 python 同一入口——单一实现方向正确
+   （问题只在信号通道，不在归并本身）。
+3. **`_print_report` 延迟 import + fail-open 宽捕获**：两行成本消化模块环，
+   保住"报告异常不阻断观看退出"契约；延迟 import 的用法正确（冷路径一次）。
+4. **`--status` 在 done 时打印 `[result]` 路径**：目录可省略后调用方无法自己拼路径，
+   由机制给出的机器通道——符合单一来源收口方向。
+5. **`--say` 按参数个数区分双形态**（不按值猜语义）——与既有约定一致，保持。
+6. **`find_current_dir` 同 sid 匹配**：目录名尾缀 `YYYYMMDD-HHMMSS` 可比；
+   `repo.git` 判据与 engine 一致（"bare 是讨论存在的唯一标志"）；发现逻辑下沉
+   python、wrapper/extension 不各写一份——符合单一事实源。
+7. **报告附 `--follow`（用户通道）而非 `--view --since`（主 pi 通道）**：职责归属正确。
+
+---
+
+## 四、分歧与备选项（如实记录）
+
+| 议题 | 立场 | 结论 |
+|---|---|---|
+| 降级兜底：删除 vs 保留 | 简单：删除；铁律：**更正后支持删除**（0005）；性能：中性 | **推荐删除**（净删四症状）；保留 + 三件套齐做为备选 |
+| 铁律 0002–0004 曾主张保留 | 理由："PI_SESSION_ID 缺失在 pi 外是常态" | 经简单视角反问"给不出必须无 sid 的场景"后，铁律核查确认场景不存在，**0005 更正**——留档说明立场演化 |
+| 删兜底后无 sid 形态 | 简单建议的"选项 2" | 不是分歧：degraded 概念消失后，无 sid = 报错要求显式目录 |
+
+---
+
+## 五、过程与统计
+
+- **讨论消息**：23 条（性能 5 / 简单 9 / 铁律 8 / human 1）——其中含协议信号
+  all-freezing ×3、pass ×3，其余为实质发言
+- **human 插话 1 条**：要求简要叙述（后续发言均从简）
+- **消息统计口径注**：本文件的"消息 N"均指消息文件数（含流程信号）；
+  配额口径只计 `mode=meeting` 且 `type=message` 的发言
+
+## 六、建议执行顺序（供实施参考）
+
+1. **F5**（回归，含显式目录测试）——纯实现 bug，任何多分析场景都会静默看错对象
+2. **降级兜底删除**（F1/F2/F7 一次消除）——含执行收尾三条与文档同步
+   （design.md 的 `find_current_dir` 决策记录改为"仅精确 sid 匹配、无兜底"）
+3. **报告约束成文**（零代码，仅契约补半句）
+4. F3 / F8 / F4 清理项（低风险，可顺手）

package/docs/reviews/README.md

@@ -21,6 +21,7 @@
 |---|---|---|---|
 | `2026-09-10-e2e10-fork-source-modes-review.md` | fork 源模式描述与实现一致性（`docs/design.md` / README / AGENTS.md vs 代码） | 非法 `forkMode` 无 fail-fast（静默走"边界后全量"混合分支 → 930k tokens 超窗）；wrapper 静默丢弃 `--fork-mode`；文档数字混源无锚；三处"完整上下文"与有损默认矛盾 | `732fdff`（P0/P1/P2）、`fe1955d`（方法论 11–14） |
 | `2026-09-10-e2e11-forkmode-guards-review.md` | forkMode 四层守卫与默认值单一源（含文档口径与方法论条目） | compaction 模式产物含**重复** compaction 条目；budget 窗口含 compaction 时 pi replay **静默丢弃前缀（含 preface）**；台账 `dropped` **双重计数**；`FORK_MODES` 与分派**非结构耦合** | `9412e32`（P1–P3 + I1–I5 不变量 + 台账） |
+| `2026-09-11-e2e16-mechanization-review.md` | 机制化改动自审（消费命令目录可省略 + 报告机制化） | **`--view` 显式目录被静默丢弃（回归，测试只覆盖无目录形态）**；降级兜底可作用于破坏性操作（`--cleanup` 删猜测目录）+ extension 靠中文文案还原布尔 + 排序取最新在跨 sid 时系统性取旧；报告 O(session) 冷路径需约束成文 | 「机制化 1+2 修复」提交 |
 | `2026-09-11-e2e14-observability-review.md` | 本项目可观测性自审（日志系统是否合理 + 如何监控讨论有效性） | 失败/重试不可见（provider error 零记录，实测占墙钟 11%）；耗时不可度量；token 无出口；**`--wait` 用 `glob(loop-*.log)` 兼任判定输入**；viewer 与 check_status 的 done 判据分叉；两份逐字相同的 `log()`；观测面契约在文档零命中 | 见「e2e14 修复」提交（第一批 §3.1–§3.5） |
 | `2026-09-11-e2e13-code-review.md` | 全项目代码合理性评审（第二轮，含时间流实测） | `--agents` 非法名在 spec-gen 路径炸出 traceback + 半成品；viewers/agents 校验与列举多实现（隐藏文件静默入场）；wrapper 越界检查第三方扩展配置；`--start` 静默删 spec；session 文件两套查找规则；切换叙事拼 agent 定义正文 | `fe3aa09`（R1–R8） |
 | `2026-09-10-e2e12-code-review.md` | 全项目代码合理性评审（性能 / 简单 / 铁律） | `_lock_git` 守卫 **fail-open**（锁态下 git 上溯到主项目仓库）；`pgrep -f` 自匹配；`protocol.json` 读取散落 6 处 / 3 种失败语义（含 `result_writer` 默认值求值缺陷）；`check_status` 用 `git grep` 全文误报 done；engine 直做 fs I/O；两处 git 入口加固不一致 | 见「e2e12 修复」提交（批 A/B/C） |

package/docs/test-methodology.md

@@ -256,3 +256,64 @@ python 时被"顺手改写"为含斜杠则不拼——**移植不是重写**：
 3. 删除函数区间用"下一个函数名"作终点前，先 `grep` 确认区间内没有别的定义；
 4. 提交前跑**真实调用路径**：`python3 -c "import <mod>"`（抓未定义/未导入名）
    + 相关测试。两次失误都是真实路径抓到的——静态阅读与"看起来对"都不够。
+
+### 19. 验证分层：测试挂在"代码改动"上，不挂在"发版"上（2026-09-11 发版冗余）
+
+**背景**：发版时顺手跑全量测试（382 测试 / 5 分钟）看起来"更稳妥"，实为冗余
+——发版动作本身只改 `package.json` 的版本号与文档文案，**零代码改动**；而区间
+内的代码改动在其**实现提交时**已经跑过全量测试。
+
+**判据**：「这段区间内有没有**未被验证**的代码改动？」——有则跑，没有则不跑。
+不是「是否在发版」「是否要推送」「是否重要」。
+
+**分层**：
+
+| 时点 | 验证内容 |
+|---|---|
+| 实现提交 | **全量测试**（代码改了；这是唯一的测试时机） |
+| 发版 | **打包验证**：`npm pack --dry-run` 核清单 + 真实安装后跑 CLI 冒烟 |
+| 推送 | 无需测试（提交时已验）——只核 `git status` 干净 + 本地/远程一致 |
+
+**例外**（唯一合理场景）：发版区间累积了多个提交、且距上次全量测试较久
+（如跨天），此时补跑一次合理——因为"区间内改动已被验证"这个前提可能不成立。
+
+**成本视角**：冗余测试不只是耗时——它稀释了"全绿"的信号价值（每次发版都全绿
+时，人不再区分"这次真的验了代码"与"这次只 bump 了版本号"）。
+
+### 20. LLM 测试的判据 = **时长**，不是"是否用 LLM"（2026-09-11 用户澄清）
+
+**规则**（用户原话）：
+
+> 我要求 llm 测试必须经过我同意的原因是 llm 测试会消耗大量时间，会影响我
+> 后继的操作。因此如果能确保短时间结束的测试是没有关系的，比如仅仅测试
+> 一下启动是没有问题的。
+
+**判据**：
+
+| 情形 | 是否需要事先同意 |
+|---|---|
+| 完整 e2e 讨论、多轮真实唤醒、分钟级以上占用 | **需要**（且用户在场） |
+| 几秒内结束的链路验证（只验证启动、单次冒烟、构造即停） | 不需要 |
+| spawn 了 pi/loop 但立即终止的测试 | 不需要，但要**主动报告**（说明起过、已停、有无真实请求发出） |
+
+**配套纪律**：`mv.sh --start` 会 spawn loop → spawn pi（真实请求）——短测试
+也要**想好怎么停**（构造完立即 cleanup + `check-residue` 复核）。
+
+### 21. `mv.sh --start` 会真实启动分析（spawn loop + pi）——冒烟别用它
+
+**背景**：`cmd_start` 做两件事：创建环境 + **启动 loop**。后者会立刻 spawn
+`meeting_loop.py`，而 loop 首轮就 spawn `pi --mode json --print`——**真实 LLM
+请求**。在 pi session 内跑（`PI_SESSION_ID`/`PI_SESSION_FILE` 都在）时没有任何
+保护会阻止它。
+
+**实测代价**（2026-09-11 两次，同一坑）：
+- ① 验证"目录名构造"时跑 `mv.sh --start` → 真起了 2 个 loop + 2 个 pi 进程；
+- ② 验证"目录可省略"时同样跑 `--start` → 同样起来（20 秒后 cleanup 删目录，
+  loop 因 repo.git 消失自退出，但 pi 进程已 spawn → 请求可能已发出）。
+
+**方法**：
+1. **只创建不启动** → 用 python 侧 `start_discussion.py --dir <d> --spec <s>`
+   （不带 `--start`）；wrapper 无此形态（`--start` 永远启动）。
+2. 需要走 wrapper 链路时，验证完**立即**：停 loop（`pkill` 按目录精确匹配）
+   → `--cleanup` → `check-residue.sh` 复核。
+3. 判据："这次验证会不会 spawn pi/loop？"——会，就必须先想好怎么停。

package/extensions/multi-viewers-say/index.ts

@@ -6,14 +6,13 @@
  * 不经过 LLM——命令 handler 直接 spawn human_sayer.py（一次调用一次返回），
  * 结果用 ctx.ui.notify 反馈。
  *
- * 讨论目录发现（零状态文件）：
- *   wrapper --start 的目录名 = mv-<PI_SESSION_ID>-<时间戳>
- *   （aft 不再替换 bash 后 PI_SESSION_ID 注入可用）；
- *   handler 用 ctx.sessionManager.getSessionId() 取本 session id，
- *   glob ctx.cwd/mv-<sid>-* 取最新目录——session 隔离（同目录多
- *   session 并发分析也互不干扰），无状态文件、无 cleanup 比对。
- *   兜底：无 sid 目录（PI 环境变量未注入时 wrapper 拿不到 sid）→ 项目下
- *   最新的 mv-*，并警告降级（宁可提示也不要静默插错分析）。
+ * 讨论目录发现（零状态文件）：目录名 = mv-<sid>-<时间戳>；
+ *   handler 取 ctx.sessionManager.getSessionId() + ctx.cwd，**调用
+ *   observability.py --find-dir**（python 单一实现——wrapper 的消费命令
+ *   走同一入口；本扩展不再自持一份发现逻辑，两边口径不会漂移）。
+ *   **只精确匹配同 sid 的目录，无降级兜底**（e2e16 F1/F2：降级时插话可能
+ *   写错分析，且判据曾是"stderr 是否含中文'警告'"——文案一改静默失效）；
+ *   未找到 → 报错提示。
  *
  * 前缀 mv- 与 pi-agents-helper 的 discuss-* 命名空间隔离（两个系统的
  * 插话命令都按"同 sid 最新目录"发现目标，共用前缀会互相插错）。
@@ -55,43 +54,36 @@ const PACKAGE_ROOT = findPackageRoot(__dirname, PKG_NAME);
 const SAYER = PACKAGE_ROOT
   ? path.join(PACKAGE_ROOT, "human_sayer.py")
   : "/root/pi-multi-viewers/human_sayer.py"; // 复制安装退化（开发机）
+const OBSERVABILITY = PACKAGE_ROOT
+  ? path.join(PACKAGE_ROOT, "observability.py")
+  : "/root/pi-multi-viewers/observability.py"; // 复制安装退化（开发机）
 
-/** 按 (cwd, sessionId) 推导当前分析目录：优先 mv-<sid>-<stamp>
- *  （session 隔离），找不到回退 mv-<stamp>（无 sid 目录——PI 环境
- *  变量缺失时 wrapper 拿不到 sid，降级为项目下最新分析，警告提示）。 */
-function findCurrentDir(
-  cwd: string,
-  sid: string,
-): { dir: string | null; degraded: boolean } {
-  try {
-    const names = fs.readdirSync(cwd, { withFileTypes: true });
-    const bySid = names
-      .filter((e) => e.isDirectory() && e.name.startsWith(`mv-${sid}-`))
-      .map((e) => e.name)
-      .sort();
-    if (bySid.length > 0) {
-      const dir = path.join(cwd, bySid[bySid.length - 1]);
-      return { dir: fs.existsSync(dir) ? dir : null, degraded: false };
-    }
-    const any = names
-      .filter(
-        (e) =>
-          e.isDirectory() &&
-          e.name.startsWith("mv-") &&
-          // 排除 mv-spec-*：那是尚未被 --start 消费的 spec 目录，不是分析
-          // 目录（否则会选中它并报出误导性的"分析不存在"）
-          !e.name.startsWith("mv-spec-"),
-      )
-      .map((e) => e.name)
-      .sort();
-    if (any.length > 0) {
-      const dir = path.join(cwd, any[any.length - 1]);
-      return { dir: fs.existsSync(dir) ? dir : null, degraded: true };
+/** 定位当前分析目录：调用 observability.py --find-dir（**python 单一实现**
+ *  ——wrapper 消费命令同一入口）。
+ *
+ *  判据 = **退出码**（不是 stderr 文案——中文提示一改就静默失配，
+ *  e2e16 F2）：rc 0 → stdout 是绝对路径；rc 1 → 未找到（无同 sid 分析）。
+ *  无降级通道（不会回退到"项目下最新"——那会插错分析，e2e16 F1）。 */
+function findCurrentDir(cwd: string, sid: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    if (!OBSERVABILITY) {
+      resolve(null);
+      return;
     }
-    return { dir: null, degraded: false };
-  } catch {
-    return { dir: null, degraded: false };
-  }
+    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));
+  });
 }
 
 /** 执行 human_sayer.py 一次插话。返回 { ok, output }。 */
@@ -126,23 +118,16 @@ export default function register(pi: any) {
         return;
       }
       const sid = ctx.sessionManager.getSessionId();
-      const found = findCurrentDir(ctx.cwd, sid);
-      const dir = found.dir;
+      const dir = await findCurrentDir(ctx.cwd, sid);
       if (!dir) {
         ctx.ui.notify(
-          "没有正在进行的多视角分析（cwd 下无 mv-* 目录）。" +
-            "先用 /multi-viewers 启动分析。",
+          "本 session 没有正在进行的多视角分析（cwd 下无 " +
+            `mv-${sid}-* 分析环境）。先用 /multi-viewers 启动，` +
+            "或改用 mv.sh --say <目录> \"<文本>\" 显式指定。",
           "error",
         );
         return;
       }
-      if (found.degraded) {
-        ctx.ui.notify(
-          `未找到本 session 的分析目录（目录名不含 session id——` +
-            `PI 环境变量可能未注入）——插话指向项目下最新分析: ${dir}`,
-          "warning",
-        );
-      }
       const { ok, output } = await runSayer(dir, text);
       if (ok && output) {
         ctx.ui.notify(output, "success");

package/human_viewer.py

@@ -46,14 +46,9 @@ def participants_from_bare(bare):
     return meeting_fs.read_protocol(bare).get("participants") or None
 
 
-def result_path(base):
-    """result.md 的固定位（`<分析目录>-result.md`，与 --wait / prompt 一致）。
-
-    resultWriter 的 loop 退出（concluded）时保存到该位置，cleanup 兜底再存
-    一次；权威单一事实源是 bare 的 `HEAD:result.md`。调用方**无需**推
-    resultWriter 是谁、也不必进 work 子目录——分析目录删除后该文件仍在。
-    """
-    return f"{base}-result.md"
+# result_path 的实现已迁 meeting_fs（与 RESULT_MD 同家，e2e16 F3）；
+# 本模块保留同名引用，既有的 `human_viewer.result_path` 调用方零改动。
+result_path = meeting_fs.result_path
 
 
 def new_messages(bare, since):
@@ -231,10 +226,37 @@ def follow(base, bare, agents, max_meeting=None,
         if done:
             print(f"【分析已结束】result.md: {result_path(base)}",
                   flush=True)
+            _print_report(base)
             return
         time.sleep(poll_interval)
 
 
+def _print_report(base):
+    """分析结束时打印观测报告（**用户通道自带**，不依赖任何 LLM 动作）。
+
+    为什么在这里：`--follow` 是用户直接执行的通道（`!!` 命令），结束时
+    自动附报告 = 用户零操作看到运行事实（提交/墙钟/配额/进程/LLM 用量），
+    而不是指望主 pi 记得去跑 `--report` 再转述（LLM 依赖，可能漏）。
+    `--report` 独立入口与 `--cleanup` 的打印保持不变（不同场景各看一次）。
+
+    **延迟 import observability**：该模块顶层 import 本模块
+    （wait_for_completion 用 incremental），顶层反向 import 会成环。本函数
+    只在 done 分支执行一次（冷路径），函数内 import 是标准解法。
+
+    fail-open：报告是附加信息，生成失败绝不阻断观看退出（契约同
+    observability.build_report——任何一段读不出显示 n/a）。
+    """
+    try:
+        from observability import build_report
+        print("【分析报告】", flush=True)
+        for line in build_report(base):
+            print(line, flush=True)
+    except Exception as e:                      # noqa: BLE001
+        # 宽捕获是刻意的：报告在观看主循环的退出路径上，任何异常
+        # （含未预期）都不该让用户失去"分析已结束"这个关键信息
+        print(f"【分析报告】生成失败（不影响观看）：{e}", flush=True)
+
+
 def main():
     parser = argparse.ArgumentParser(description="human 分析展示（只读）")
     parser.add_argument("base", help="分析目录（含 repo.git）")

package/meeting_fs.py

@@ -31,6 +31,21 @@ RESULT_MD = "result.md"
 # 写空文件/仅 frontmatter——只查存在性会退化为空提交，审核 A2）。
 RESULT_MD_MIN_BYTES = 50
 
+
+def result_path(base):
+    """result.md 的固定位（`<分析目录>-result.md`）。
+
+    **与 RESULT_MD 同家**（e2e16 F3）：S1 把"文件叫什么/多大算有效"收进本
+    模块，但拼路径留在 viewer —— 组合层（start_discussion 的 `--status`
+    打印 `[result]`）为拼字符串 import 展示模块，职责颠倒。路径规则是
+    产物契约的一部分，归 fs。
+
+    resultWriter 的 loop 退出（concluded）时保存到该位置，cleanup 兜底再存
+    一次；权威单一事实源是 bare 的 `HEAD:result.md`。调用方**无需**推
+    resultWriter 是谁、也不必进 work 子目录——分析目录删除后该文件仍在。
+    """
+    return f"{base}-{RESULT_MD}"
+
 # 无进展超时兜底（秒）——协议参数的默认值（gen_protocol 固化进
 # protocol.json；engine/fake_agent 的签名默认与 CLI default 同源于此）。
 DEFAULT_STALL_TIMEOUT = 600

package/observability.py

@@ -55,6 +55,50 @@ def _loops_alive(base):
     return bool(_loop_pids(base))
 
 
+def find_current_dir(cwd=None, sid=None):
+    """发现"本 session 当前的分析目录"——**单一实现**（wrapper 与 extension
+    共用；此前只有 extension 里一份 TS 实现，wrapper 侧完全没有）。
+
+    为什么需要：消费命令（--status/--cleanup/--view/--say…）此前都要求调用方
+    传绝对路径，而唯一知道路径的是 `--start` 的输出——主 pi 得把它记在
+    LLM 上下文里再原样复用（改错/截断/相对路径都出过）。发现逻辑下沉后，
+    命令可以不带目录，**路径不需要经过任何 LLM 记忆**。
+
+    **只做精确匹配**（`mv-<sid>-*` 中时间戳最新者）：
+
+    为什么**没有**"取项目下最新 `mv-*`"的兜底（e2e16 评审 2:0:1 裁定删除）：
+    1. **破坏性操作不应由工具猜目标**——`--cleanup`/`--say` 作用于发现结果，
+       兜底意味着"猜一个目录然后删它/写它"；最坏失败应是响亮报错而非静默
+       操作错对象；
+    2. 兜底需要机器可判的"这是降级"信号，而 rc 0 + stderr 中文文案不是可靠
+       信号（extension 曾用 `err.includes("警告")` 还原——文案一改就静默失效）；
+    3. 兜底的"最新"按整名排序（含 sid 段）→ 跨 sid 时**系统性取旧**（与
+       "取最新"的语义相反）；
+    4. **不存在"必须无目录且必然无 sid"的设计内场景**：pi 内两条通道都有 sid
+       （bash 注入 `PI_SESSION_ID` / extension `ctx.sessionManager`），终端主
+       路径本就用 `--start` 输出的显式目录。无 sid 时应当报错请调用方显式传目录。
+
+    判别 = 目录含 `repo.git`（同 engine："bare 是讨论存在的唯一标志"——光看
+    名字会命中残留/无关目录）；`mv-spec-*` 不在匹配前缀内（那是尚未被
+    `--start` 消费的 spec 目录）。
+
+    返回绝对路径 | None。
+    """
+    cwd = cwd or os.getcwd()
+    sid = sid if sid is not None else os.environ.get("PI_SESSION_ID", "")
+    if not sid:
+        return None
+    try:
+        names = sorted(os.listdir(cwd))
+    except OSError:
+        return None
+    # 同 sid 的目录名尾缀 `YYYYMMDD-HHMMSS` 定长可比 → 排序即时间序
+    cands = [n for n in names
+             if n.startswith(f"mv-{sid}-")
+             and os.path.isdir(os.path.join(cwd, n, "repo.git"))]
+    return os.path.join(cwd, cands[-1]) if cands else None
+
+
 def check_status(base):
     """讨论状态（单值；状态全集显式于此，T3/#7 修复 e2e7 评审）：
 
@@ -110,7 +154,7 @@ def wait_for_completion(base):
     # （原内联 65 行自行 git log 全量 + 手工解析 frontmatter——与
     # viewer 两套输出格式、非增量、概念丢失）。incremental 走
     # since..HEAD 增量 + 统一 format_message。
-    import human_viewer
+    # （函数内重复 import human_viewer 已删——顶层已有；e2e16 F4 清理项）
     sys.stdout.reconfigure(line_buffering=True)
     print(f"[wait] 等待讨论完成: {base}")
     bare = meeting_fs.bare_of_base(base)
@@ -194,7 +238,20 @@ def build_report(base):
         return out
     proto = meeting_fs.read_protocol(bare)
 
-    # ---- 流程时间线（bare = 判定域，现场派生） ----
+    # ---- 一次读取（消息文件 = 权威口径），供流程/配额/冻结/RR 四段共用 ----
+    msgs = meeting_engine.each_agent_messages(bare, agents)
+    per_agent = {a: len(msgs.get(a, [])) for a in agents}
+    # human 消息不在 participants 里（视而不见原则）——单独数 human/ 目录的
+    # 消息文件。**不用 commit subject 统计**：那是自由文本（`discuss: X/NNNN`），
+    # 格式一改/手写就静默归零（2026-09-11 实测：构造环境 subject 不同 → "提交 0"
+    # 而实际有 3 条消息）；消息文件是判定域的事实，格式由本仓控制。
+    r_h = meeting_fs.run_git(bare, "ls-tree", "-r", "-z", "--name-only",
+                             "HEAD", check=False)
+    human_n = sum(1 for f in r_h.stdout.rstrip("\0").split("\0")
+                  if f and f.startswith("human/")
+                  and meeting_fs.is_message_file(f))
+
+    # ---- 流程时间线（时间戳来自 commit——消息文件不带墙钟） ----
     r = meeting_fs.run_git(bare, "log", "--reverse", "--format=%ct%x09%s",
                            "HEAD", check=False)
     rows = []
@@ -203,23 +260,15 @@ def build_report(base):
             continue
         ts, subj = line.split("\t", 1)
         rows.append((int(ts), subj))
-    per_agent = {a: 0 for a in agents}
-    human_n = 0
-    for _, subj in rows:
-        m = re.match(r"discuss:\s*(.+?)/(\d+)$", subj)
-        if not m:
-            continue
-        who = m.group(1)
-        if who == "human" or who not in per_agent:
-            human_n += 1
-        else:
-            per_agent[who] += 1
     if rows:
         span = rows[-1][0] - rows[0][0]
-        out.append(f"流程：{len(agents)} agents | 提交 "
-                   f"{sum(per_agent.values())}（含流程信号；"
-                   + " / ".join(f"{a} {n}" for a, n in per_agent.items())
-                   + f"）| 墙钟跨度 {_dur(span)}（首末 commit 差）")
+        detail = " / ".join(f"{a} {n}" for a, n in per_agent.items())
+        if human_n:      # human 单列明细（它不是参与者），但计入合计
+            detail += f" / human {human_n}"
+        out.append(f"流程：{len(agents)} agents | 消息 "
+                   f"{sum(per_agent.values()) + human_n}"
+                   f"（含流程信号；{detail}）| 墙钟跨度 {_dur(span)}"
+                   f"（首末 commit 差）")
     # 最长无进展间隔（相邻 commit 间隔的最大值）
     gaps = [(rows[i + 1][0] - rows[i][0], rows[i][0], rows[i + 1][0])
             for i in range(len(rows) - 1)]
@@ -233,7 +282,7 @@ def build_report(base):
     # 不是"该 agent 的消息总数"——上限约束的是 meeting 发言轮次，而一个
     # agent 的消息里还有 freezing/all-freezing/pass/concluded 等流程信号。
     # 两者混算会出现"meeting 6/2"这种超限假象（口径错误，2026-09-11 实测）。
-    msgs = meeting_engine.each_agent_messages(bare, agents)
+    # msgs 由上方流程段一次读取提供（同一读取派生四段）。
     lasts = {a: (msgs[a][-1] if msgs[a] else None) for a in agents}
     types = {a: (lasts[a].get("type") if lasts[a] else None) for a in agents}
     quota_meeting = proto.get("maxMeetingRounds", 10)
@@ -290,9 +339,11 @@ def build_report(base):
                    f"{u['responses']} 次 | error {u['errors']} 次")
     if not any_usage:
         out.append("  n/a（session 缺失，或无本轮数据——边界条目自 2026-09-11 "
-                   "起写入，此前的老分析不适用）」")
+                   "起写入，此前的老分析不适用）")
     out.append("（口径：进程跨度=pi 进程生命周期；输出=prompt 分段合计；"
-               "墙钟=commit 时间差——三者不可互替）")
+               "墙钟=commit 时间差——三者不可互替；"
+               "消息数含流程信号（freezing/pass/concluded）与 human，"
+               "配额只计 meeting 发言）")
     return out
 
 
@@ -390,3 +441,36 @@ def _num(n):
     if n >= 1_000:
         return f"{n / 1_000:.1f}k"
     return str(n)
+
+
+def _main(argv=None):
+    """观测层 CLI——目前只有一个子命令：`--find-dir`（供 wrapper 与
+    extension 在"不带目录"时定位当前分析；逻辑单点，两个调用方不各写一份）。
+
+    输出契约（二元，无中间态——降级语义已删除，e2e16 F1/F2/F7）：
+      stdout = 绝对路径（找到时）；stderr = 原因（未找到）；
+      退出码 0 = 找到，1 = 未找到（调用方应据此报错请用户显式传目录）。
+    """
+    import argparse
+    ap = argparse.ArgumentParser(description="多视角分析：观测层工具")
+    ap.add_argument("--find-dir", action="store_true",
+                    help="定位当前分析目录（按 cwd + PI_SESSION_ID）")
+    ap.add_argument("--cwd", default=None, help="项目目录（默认 $PWD）")
+    ap.add_argument("--sid", default=None,
+                    help="session id（默认 $PI_SESSION_ID）")
+    args = ap.parse_args(argv)
+    if not args.find_dir:
+        ap.print_help()
+        return 2
+    d = find_current_dir(args.cwd, args.sid)
+    if not d:
+        print("错误: 未找到本 session 的分析目录（cwd 下无 "
+              "mv-<PI_SESSION_ID>-* 环境）——请显式传目录参数",
+              file=sys.stderr)
+        return 1
+    print(d)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-viewers",
-  "version": "0.2.0",
+  "version": "0.2.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.md

@@ -26,9 +26,10 @@ argument-hint: '"<主题>"'
 ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --prepare "<主题>"
 ```
 
-**若报错含"未找到 viewers/ 目录"、"仅发现 1 个视角"或"视角任务书不能为空"**：
-说明项目缺可用视角。此时**停下来问用户**，不要自己选——建议帮他按
-下面的"视角设计原则"写 `viewers/<视角名>.md`（建好后再重跑本步骤）。
+**这条命令非零退出 → 说明 spec 生成失败**（通常是项目缺可用视角：未建
+`viewers/`、视角少于 2 个、或视角文件为空）。此时**停下来问用户**，不要
+自己选——读报错原文搞清原因，建议他按下面的"视角设计原则"补
+`viewers/<视角名>.md`（建好后再重跑本步骤）。
 
 ### 2. 编辑并请用户审核 spec
 
@@ -68,13 +69,16 @@ argument-hint: '"<主题>"'
 ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --start <spec目录绝对路径>
 ```
 
-记录 wrapper 输出的**分析目录**，并**原样完整展示**观看命令。
+**原样完整展示** wrapper 输出的观看命令（它是可复制执行的完整命令行——
+不要改写、截断或转述）。
 
 ### 4. 结束回合
 
 告知用户：
-- 观看：复制上一步的 `!!` 命令执行（实时流式，结束时自动退出）
-- 插话：随时 `/multi-viewers-say <文本>`（自动定位当前分析；也可用 wrapper `--say <目录> "<文本>"`）
+- 观看：复制上一步的 `!!` 命令执行（实时流式，结束时自动退出并**附本次
+  分析报告**——消息数/墙钟/配额/冻结/进程跨度/LLM 用量；用户无需任何
+  额外操作即可看到）
+- 插话：随时 `/multi-viewers-say <文本>`（自动定位当前分析）
 - 完成时告诉主 pi，主 pi 会收尾
 
 **然后结束当前回合。**
@@ -82,13 +86,12 @@ argument-hint: '"<主题>"'
 ## 收尾（用户驱动）
 
 ```bash
-mv.sh --status <分析目录绝对路径>   # done/stopped/running
+mv.sh --status      # done/stopped/running（目录可省略——自动定位当前分析）
 ```
 
-- `done`：读 `<分析目录>-result.md`（与目录同级的固定位）→ 向用户给
-  **摘要** → `mv.sh --cleanup <分析目录绝对路径>`
-  - cleanup 会打印**本次分析报告**（提交数 / 墙钟 / 进程跨度 / 配额 / LLM
-    用量 / rc≠0）——这是删目录前最后一次可读，**把其中的关键数字一并
-    转述给用户**（运行成本与健康度的一手信息）
+- `done`：读上一步打印的 `[result]` 路径（产物固定位；**路径由命令给出，
+  不要自己拼**）→ 向用户给**摘要** → `mv.sh --cleanup`（同样可省略目录）
+  - cleanup 会再打印一次**分析报告**（删目录前最后一次可读）。报告在
+    观看输出末尾已自动出现过，**不必重复转述**——用户问起数字时按需引用
 - `stopped`：报告"分析已结束但未生成结果"，不要继续等待
 - `running`：告知还在进行，继续等用户通知

package/scripts/mv.sh

@@ -17,6 +17,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(dirname "$SCRIPT_DIR")"
 PYTHON="${PYTHON:-python3}"
 START_DISCUSSION="$ROOT_DIR/start_discussion.py"
+OBSERVABILITY="$ROOT_DIR/observability.py"
 HUMAN_VIEWER="$ROOT_DIR/human_viewer.py"
 HUMAN_SAYER="$ROOT_DIR/human_sayer.py"
 
@@ -26,12 +27,15 @@ usage() {
 用法:
   $0 --prepare "<问题>" [--background "<背景>"] [--agents "a,b,c"|4]
   $0 --start <spec目录> [--fork-mode compaction|budget|full]
-  $0 --status <dir>
-  $0 --report <dir>
-  $0 --wait <dir>
-  $0 --cleanup <dir>
-  $0 --view <dir> [--since <ref>]
-  $0 --say <dir> "<文本>"
+  $0 --status  [dir]
+  $0 --report  [dir]
+  $0 --wait    [dir]
+  $0 --cleanup [dir]
+  $0 --view    [dir] [--since <ref>]
+  $0 --say     [dir] "<文本>"
+
+消费命令的 <dir> 可省略（自动发现本 session 当前分析——按 cwd 下
+mv-<PI_SESSION_ID>-* 最新；找不到则取最新 mv-* 并警告）
 
 默认参数:
   agents=a,b,c  max-meeting=10  max-rr=7   # 配额默认值的权威在 python argparse（wrapper 不传）
@@ -58,6 +62,24 @@ require_dir() {
     [ -d "$dir" ] || fail "目录不存在: $dir"
 }
 
+# 目录解析：显式参数优先；**省略则自动发现**（python observability
+# --find-dir——单一实现，extension 同一入口）。为什么允许省略：唯一知道
+# 路径的是 --start 的输出，此前消费命令都要求把它传给每个命令，等于让
+# 调用方（主 pi）把长绝对路径记在 LLM 上下文里再复用——改错/截断/相对
+# 路径都出过（参数形态标准化就是为此）。发现逻辑下沉后路径不经 LLM 记忆。
+# **调用方必须 `|| exit $?`**：本函数的 exit 发生在命令替换的子 shell 里，
+# 不检查返回值会让空结果继续往下走（表现为双重错误消息：python 的原因 +
+# require_dir 的"缺少目录参数"——实测踩到）。
+resolve_dir() {
+    local dir="${1:-}"
+    if [ -z "$dir" ]; then
+        # 省略 = 自动发现；**失败原因由 python 给出**（错误文案留一处——
+        # e2e16 F7：两条文案没有信息增益，只用工具层那条更贴近原因）。
+        dir="$("$PYTHON" "$OBSERVABILITY" --find-dir)" || exit 1
+    fi
+    normalize_dir "$dir"
+}
+
 # 目录参数规范化：裸名（无路径符）会被 start_discussion 加 discussion-
 # 前缀导致找错目录（实测 2026-09-03）——所有消费命令入口统一转绝对路径
 normalize_dir() {
@@ -66,36 +88,45 @@ normalize_dir() {
 
 cmd_status() {
     local dir
-    dir="$(normalize_dir "$1")"
+    dir="$(resolve_dir "${1:-}")" || exit $?
     require_dir "$dir"
     "$PYTHON" "$START_DISCUSSION" --dir "$dir" --status
 }
 
 cmd_report() {
     local dir
-    dir="$(normalize_dir "$1")"
+    dir="$(resolve_dir "${1:-}")" || exit $?
     require_dir "$dir"
     "$PYTHON" "$START_DISCUSSION" --dir "$dir" --report
 }
 
 cmd_wait() {
     local dir
-    dir="$(normalize_dir "$1")"
+    dir="$(resolve_dir "${1:-}")" || exit $?
     require_dir "$dir"
     "$PYTHON" "$START_DISCUSSION" --dir "$dir" --wait
 }
 
 cmd_cleanup() {
     local dir
-    dir="$(normalize_dir "$1")"
+    dir="$(resolve_dir "${1:-}")" || exit $?
     require_dir "$dir"
     "$PYTHON" "$START_DISCUSSION" --dir "$dir" --cleanup
 }
 
 cmd_view() {
     local dir since=""
-    dir="$(normalize_dir "$1")"
-    shift
+    # 首参：非空且非 --since → 显式目录（**F5 回归修复**：此前无条件 shift
+    # 后总走自动发现，显式目录被静默丢弃——多分析并存/跨目录调用会看错对象）。
+    # 判据与 status/report/wait/cleanup 的 `resolve_dir "${1:-}"` 一致。
+    # 注意与 --say 的区别：--say 按**参数个数**区分（文本可含空格/以 -- 开头，
+    # 不能按值判形）；--view 的 --since 是本命令自己的选项名，可以判形。
+    if [ -n "${1:-}" ] && [ "${1:-}" != "--since" ]; then
+        dir="$(resolve_dir "$1")" || exit $?
+        shift
+    else
+        dir="$(resolve_dir "")" || exit $?
+    fi
     while [ "$#" -gt 0 ]; do
         case "$1" in
             --since)
@@ -121,8 +152,17 @@ cmd_view() {
 }
 
 cmd_say() {
-    local dir text="${2:-}"
-    dir="$(normalize_dir "$1")"
+    # 两种形态（**按参数个数区分，不是按值猜语义**）：
+    #   --say <dir> "<文本>"   显式目录（兼容原有调用）
+    #   --say "<文本>"         目录自动发现（本 session 当前分析）
+    local dir text
+    if [ "$#" -ge 2 ]; then
+        dir="$(resolve_dir "$1")" || exit $?
+        text="$2"
+    else
+        dir="$(resolve_dir "")" || exit $?
+        text="${1:-}"
+    fi
     require_dir "$dir"
     [ -d "$dir/work-human" ] || fail "分析缺少 work-human: $dir"
     [ -n "$text" ] || fail "插话文本不能为空"
@@ -284,34 +324,33 @@ if [ "$#" -ge 1 ]; then
             exit $?
             ;;
         --status)
-            [ "$#" -ge 2 ] || fail "--status 需要分析目录参数"
-            cmd_status "$2"
+            shift
+            cmd_status "${1:-}"
             exit $?
             ;;
         --report)
-            [ "$#" -ge 2 ] || fail "--report 需要分析目录参数"
-            cmd_report "$2"
+            shift
+            cmd_report "${1:-}"
             exit $?
             ;;
         --wait)
-            [ "$#" -ge 2 ] || fail "--wait 需要分析目录参数"
-            cmd_wait "$2"
+            shift
+            cmd_wait "${1:-}"
             exit $?
             ;;
         --cleanup)
-            [ "$#" -ge 2 ] || fail "--cleanup 需要分析目录参数"
-            cmd_cleanup "$2"
+            shift
+            cmd_cleanup "${1:-}"
             exit $?
             ;;
         --view)
-            [ "$#" -ge 2 ] || fail "--view 需要分析目录参数"
             shift
             cmd_view "$@"
             exit $?
             ;;
         --say)
-            [ "$#" -ge 3 ] || fail "--say 需要分析目录和文本参数"
-            cmd_say "$2" "$3"
+            shift
+            cmd_say "$@"
             exit $?
             ;;
         -h|--help)

package/start_discussion.py

@@ -33,6 +33,7 @@ import subprocess
 import sys
 import time
 
+import human_viewer
 import meeting_fs
 import observability
 import spec_gen
@@ -601,7 +602,12 @@ def main():
         cleanup_discussion(base)
         return
     if args.status:
-        print(f"[status] {check_status(base)}")
+        st = check_status(base)
+        print(f"[status] {st}")
+        if st == "done":
+            # 产物路径一并给出：目录可省略后（自动发现），调用方**无法**
+            # 自己拼出 `<目录>-result.md`——路径由机制提供，不经 LLM 记忆
+            print(f"[result] {meeting_fs.result_path(base)}")
         return
     if args.report:
         for line in build_report(base):