pi-multi-viewers 0.2.2 → 0.3.0

package/AGENTS.md

@@ -23,7 +23,8 @@ spec_gen.py          spec 生成层（question/骨架/viewers 校验与快照/ag
 observability.py     观测层（check_status / --report / --wait / loop 存活检测）
 human_viewer.py      【human 通道】只读展示（增量/--follow/游标）
 human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
-scripts/mv.sh        wrapper（prepare/start/status/wait/cleanup/view/say）
+scripts/mv.sh        稳定入口 shim（exec mv_cli.py；路径被 prompt/README 引用）
+mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say）
 prompts/multi-viewers.md  /multi-viewers 入口（视角设计三原则 + 审核闸门）
 extensions/multi-viewers-say/  /multi-viewers-say 插话（registerCommand，零 LLM）
 docs/design.md       设计文档（fork 源模式与规模口径 + 决策记录）
@@ -176,7 +177,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.2（2026-09-11）**。
+  + wrapper。**npm 已发布 0.3.0（2026-09-12）**。
 - **开发机安装（两步，缺一不可；2026-09-10 实测）**：
   ① `pi install /root/pi-multi-viewers`——**注册包**（写
   `~/.pi/agent/settings.json` 的 `packages` 数组）；pi 不是"扫 node_modules

package/docs/design.md

@@ -308,7 +308,21 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     一改就静默失配（LLM 会以为没报错而继续）。改为"命令非零退出 → 停下来
     读报错原文问用户"：判据降为退出码（wrapper 的 `fail()` 保证 `exit 1`），
     原因解释交还给输出原文。
-17. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
+17. **CLI 层 = Python（bash 只留 shim）**：`scripts/mv.sh` 是 5 行 shim
+    （找到仓库根 → `exec python3 mv_cli.py "$@"`），解析/决议/调用/展示全在
+    `mv_cli.py`。**路径 `scripts/mv.sh` 不变**（prompt/README/用户习惯引用
+    它）。收敛依据不是"更整洁"，而是这层产出的真实 bug **全部出自 bash
+    陷阱**（`shift` 吃掉显式目录 = F5 回归、`local` 重复声明清空变量、命令
+    替换里的 `exit` 不进父 shell 致双重错误消息、参数静默丢弃 = P0），且
+    bash 在本项目工具链里**零行覆盖**（Python 覆盖率看不到它）——缺口只能靠
+    真实 e2e 或评审暴露。收敛后逻辑进入覆盖率与进程内单测
+    （tests/test_mv_cli.py），解析统一出口。子进程边界不变：start_discussion
+    / human_viewer / human_sayer 仍以子进程调用（各自是 CLI 入口）。
+    顺带三处"无静默"加固（bash 版是静默的）：status/report/wait/cleanup 的
+    多余参数响亮失败、`--say` 多于 2 个参数响亮失败（未加引号文本会被当成
+    目录）、`--view` 的 viewer 失败透传 rc 且**不打印 HEAD 游标**（给失败的
+    一轮发游标会让下一次 `--since` 静默跳过消息）。
+18. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
    注入于 spawn）；主项目仓库不在守卫范围（agent 的 cwd 就是主项目，其
    约束归指令层 + 主项目 `.gitignore`）。要拦主仓库需换机制类（沙箱/钩子），
    经评估收益不支撑扩面。

package/docs/test-methodology.md

@@ -317,3 +317,51 @@ python 时被"顺手改写"为含斜杠则不拼——**移植不是重写**：
 2. 需要走 wrapper 链路时，验证完**立即**：停 loop（`pkill` 按目录精确匹配）
    → `--cleanup` → `check-residue.sh` 复核。
 3. 判据："这次验证会不会 spawn pi/loop？"——会，就必须先想好怎么停。
+
+### 22. 契约写成矩阵表：命令 × 形态 × 判别力（2026-09-11 e2e16 F5）
+
+**背景（F5 回归）**：改 `cmd_view` 时只测"新形态"（目录可省略），
+`--view <dir>` 的显式形态**改动前后都没有测试**（旧测试测的是"无参 → 报错"
+的错误分支）；395 个测试全绿没挡住——真实多视角评审（e2e16）才抓出。
+
+**诊断（不是"漏写一条用例"，是结构性缺口）**：
+1. wrapper 测试按功能增量堆叠，没有"命令 × 形态"的系统性盘点；
+2. **bash 层无行覆盖工具**——缺口不出现在覆盖率里（实测 Python 层 96%，
+   wrapper 测不到一行）；`--wait` 零测试、`--cleanup` 省略形态零测试；
+3. 旧测试用**弱断言**（仅 `assertNotEqual(rc, 0)`）——契约废除后静默变
+   空洞：`test_view_requires_dir` 的"目录必传"契约已不存在，它只因测试
+   cwd 里没有分析环境才继续绿，看起来在覆盖 `--view` 实则什么都没测。
+
+**方法**：
+1. **契约 = 一张表**（`tests/test_wrapper.py::TestCommandFormMatrix`）：
+   每行一个形态单元格 = `(args, 前置条件, 期望 rc, 输出须含, 副作用)`。
+   新增命令/形态必须补行——**结构性强制，不靠记忆**。
+2. **每格三件事**：退出码 + **输出内容** + **副作用/文件效果**；
+   禁止仅断言退出码（弱断言是僵尸测试的温床）。
+3. **判别力优先于覆盖率**：显式参数格子必须能区分"用了显式值"与"恰好
+   自动发现同一个"。做法：加**诱饵**（更晚时间戳 + 状态不同 `done` vs
+   `stopped` + 独有标记）——两个同构环境的 HEAD/输出完全相同，无诱饵时
+   F5 类 bug 照样绿（本次实测：加诱饵后重引入 F5，矩阵立即失败并报
+   "走了自动发现（选到诱饵环境）"）。
+4. **改写旧测试 ≠ 补充**：契约变更时先问"它测的是哪条既有契约、那条契约
+   还有效吗"——有效则必须补等价用例；无效则删除并在表里补新形态格。
+
+### 23. 概率性断言 = 测试设计缺陷（2026-09-12 test_n_agents 随机红）
+
+**背景**：`test_four_agent_cascade` 断言"N=4 应有 message 发言"。FakeAgent 在
+meeting 阶段有 35% 概率写 freezing，而"全员首轮 freezing"概率 = 0.35⁴ =
+**1.50%**——此时测试必失败（N=5 时 0.53%）。实测约每 10 次全量跑红一次。
+
+**定性**：**测试装置问题，不是产品问题**——全员首轮 freezing 是合法协议路径
+（引擎照常走完 af → RR → pass → concluded）。但断言把"典型路径"当成不变式了。
+
+**方法**：
+1. **测试可以断言不变式，不可以断言分布尾部**：写断言前先问"这个结论在
+   装置的随机性下是否恒成立"。不成立 → 断言错，或装置要改。
+2. **修装置优于挑种子**：本次修法是让 FakeAgent **首轮必写 message**——
+   理由是**装置对齐生产**（真实 wake prompt 对首位发言者的指令就是"直接产出
+   你的第一条视角分析"），而不是"把概率调到能过"。挑 seed 只治一次，改对齐
+   治一类。
+3. **确定性优先于概率**：修复后该断言成为**不变式**（P = 0 不可能失败），
+   不再依赖运气——这比"多跑几次都绿"才是证据（10 次全绿对 1.5% 概率的
+   事件的置信度很低）。

package/fake_agent.py

@@ -88,9 +88,17 @@ def make_responder(min_sleep, max_sleep, crash_rate):
             # RR 阶段：单向流，只写 pass（无异议回退，留待以后）
             decision = meeting_core.T_PASS
         else:
-            # meeting 阶段：有内容 → message；无话可说 → freezing
-            decision = meeting_core.T_MESSAGE if random.random() < 0.65 \
-                else meeting_core.T_FREEZING
+            # meeting 阶段：有内容 → message；无话可说 → freezing。
+            # **首轮例外 = 必写 message**（装置对齐生产，2026-09-12）：真实
+            # wake prompt 对首位发言者的指令是"你是第一位发言者——直接产出
+            # 你的第一条视角分析"，fake 首轮却可能 freezing——语义不符，且
+            # 使"全员首轮 freezing"有 0.35^N 的概率（N=4 时 1.5%）撞上
+            # cascade 测试的 "应有 message" 断言 → 随机红（实测 ~2%/全量跑）。
+            if is_first:
+                decision = meeting_core.T_MESSAGE
+            else:
+                decision = meeting_core.T_MESSAGE if random.random() < 0.65 \
+                    else meeting_core.T_FREEZING
 
         time.sleep(random.uniform(min_sleep, max_sleep))
         if random.random() < crash_rate:

package/mv_cli.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""mv_cli.py —— 多视角分析命令行（wrapper 的实际实现）。
+
+**为什么这层是 Python**（原来是 364 行 bash，2026-09-12 收敛）：
+它曾住着参数解析（--prepare/--view/--say 三处）、目录名构造、spec 删除策略、
+路径规范化与约 60 行用户文案。这层产出的真实 bug **全部出自 bash 陷阱**——
+`shift` 吃掉显式目录（F5 回归）、`local` 重复声明清空变量、命令替换里的
+`exit` 不进父 shell（双重错误消息）、参数静默丢弃（P0）；而 bash 在本项目
+工具链里**零行覆盖**（Python 覆盖率看不到它），缺口只能靠真实 e2e 或评审
+暴露。收敛后：逻辑进入覆盖率与单测，解析用统一出口，不再有
+shift/subshell/local 类陷阱。
+
+`scripts/mv.sh` 保留为稳定入口 shim（prompt/README 引用该路径，不能变）。
+
+**子进程边界**：环境创建/启动（start_discussion.py）、观看（human_viewer.py）、
+插话（human_sayer.py）仍以子进程调用——它们是各自的 CLI 入口（argparse +
+main），行为与 bash 版逐字一致；本模块只做「解析 → 决议 → 调用 → 展示」。
+
+**退出码约定**（沿用 bash 版）：无参数/参数不足 → usage + rc 2；
+--help → usage + rc 0；其余错误 → `错误: ...` 到 stderr + rc 1；
+子命令的业务退出码原样透传。
+"""
+
+import fnmatch
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+PYTHON = os.environ.get("PYTHON") or "python3"
+START_DISCUSSION = os.path.join(HERE, "start_discussion.py")
+OBSERVABILITY = os.path.join(HERE, "observability.py")
+HUMAN_VIEWER = os.path.join(HERE, "human_viewer.py")
+HUMAN_SAYER = os.path.join(HERE, "human_sayer.py")
+
+# 展示名：shim 传入调用路径（沿用 bash 的 `$0` 语义——usage 与启动块里显示
+# 用户实际敲的那条命令）；直接跑 mv_cli.py 时退回默认名。
+PROG = os.environ.get("MV_INVOKED_AS") or "scripts/mv.sh"
+
+USAGE = f"""用法:
+  {PROG} --prepare "<问题>" [--background "<背景>"] [--agents "a,b,c"|4]
+  {PROG} --start <spec目录> [--fork-mode compaction|budget|full]
+  {PROG} --status  [dir]
+  {PROG} --report  [dir]
+  {PROG} --wait    [dir]
+  {PROG} --cleanup [dir]
+  {PROG} --view    [dir] [--since <ref>]
+  {PROG} --say     [dir] "<文本>"
+
+消费命令的 <dir> 可省略（自动发现本 session 当前分析——按 cwd 下
+mv-<PI_SESSION_ID>-* 最新；无匹配则报错要求显式传目录）
+
+默认参数:
+  agents=a,b,c  max-meeting=10  max-rr=7   # 配额默认值的权威在 python argparse（本层不传）
+
+--agents: 逗号分隔名称列表（如 "x,y"）或纯数字（如 4 → 生成 a..d）；
+          human 是保留名，不能作为参与者
+
+human 通道:
+  --view: 增量查看分析进展（--since 之后的新消息+状态；末尾输出 HEAD=<hash>，主 pi 记录作下轮 --since）
+  --say:  插话（写一条 human 消息，agents 可见并可回应）
+"""
+
+
+def fail(msg):
+    """错误出口（沿用 bash 约定：`错误: ` 前缀 + stderr + rc 1）。"""
+    print(f"错误: {msg}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+# ---------------------------------------------------------------
+# 目录参数：解析（显式优先 / 省略则自动发现）与校验
+# ---------------------------------------------------------------
+
+def normalize_dir(path):
+    """目录参数规范化：裸名（无路径符）会被 start_discussion 当成相对路径
+    找错目录（实测 2026-09-03）——所有消费命令入口统一转绝对路径。"""
+    return os.path.realpath(path)
+
+
+def resolve_dir(arg):
+    """显式参数优先；**省略则自动发现**（observability `--find-dir` 单一实现，
+    extension 同入口）。失败原因由那个 python 进程给出（错误文案留一处，
+    e2e16 F7）：stderr 直通、退出码原样透传。
+
+    为什么允许省略：唯一知道路径的是 `--start` 的输出，此前消费命令都要求
+    把它传给每个命令，等于让调用方（主 pi）把长绝对路径记在 LLM 上下文里
+    再复用——改错/截断/相对路径都出过。
+    """
+    if arg:
+        return normalize_dir(arg)
+    r = subprocess.run([PYTHON, OBSERVABILITY, "--find-dir"],
+                       stdout=subprocess.PIPE, text=True)
+    if r.returncode != 0:
+        raise SystemExit(r.returncode)
+    return normalize_dir(r.stdout.strip())
+
+
+def require_dir(d):
+    if not d:
+        fail("缺少目录参数")
+    if not os.path.isdir(d):
+        fail(f"目录不存在: {d}")
+    return d
+
+
+def _dir_only(command, args):
+    """status/report/wait/cleanup 的公共入口：只接受 `[dir]`。
+
+    多余参数**响亮失败**而非静默忽略（无静默铁律 / P0：wrapper 不得静默
+    丢弃参数）。
+    """
+    if len(args) > 1:
+        fail(f"未知参数: {' '.join(args[1:])}（{command} 只接受 [dir]）")
+    return require_dir(resolve_dir(args[0] if args else ""))
+
+
+def _call(cmd):
+    """子进程透传（stdout/stderr 直通，退出码原样返回）。"""
+    return subprocess.run(cmd).returncode
+
+
+# ---------------------------------------------------------------
+# 消费命令
+# ---------------------------------------------------------------
+
+def cmd_status(args):
+    d = _dir_only("--status", args)
+    return _call([PYTHON, START_DISCUSSION, "--dir", d, "--status"])
+
+
+def cmd_report(args):
+    d = _dir_only("--report", args)
+    return _call([PYTHON, START_DISCUSSION, "--dir", d, "--report"])
+
+
+def cmd_wait(args):
+    d = _dir_only("--wait", args)
+    return _call([PYTHON, START_DISCUSSION, "--dir", d, "--wait"])
+
+
+def cmd_cleanup(args):
+    d = _dir_only("--cleanup", args)
+    return _call([PYTHON, START_DISCUSSION, "--dir", d, "--cleanup"])
+
+
+def cmd_view(args):
+    """增量查看 + 输出 HEAD 游标。
+
+    首参判形：非空且非 `--since` → 显式目录（与 status/report/wait/cleanup
+    的 `resolve_dir(arg)` 同一判据；F5 回归教训：无条件 shift 会让显式目录
+    被静默丢弃）。与 `--say` 的区别：`--say` 按**参数个数**区分（文本可含
+    空格或以 `--` 开头，不能按值判形）；`--view` 的 `--since` 是本命令自己
+    的选项名，可以按值判形。
+    """
+    since = None
+    if args and args[0] != "--since":
+        d = require_dir(resolve_dir(args[0]))
+        args = args[1:]
+    else:
+        d = require_dir(resolve_dir(""))
+    i = 0
+    while i < len(args):
+        if args[i] == "--since":
+            if i + 1 >= len(args):
+                fail("--since 需要一个值")
+            since = args[i + 1]
+            i += 2
+        else:
+            fail(f"未知参数: {args[i]}（--view 只接受 --since）")
+    if not os.path.isdir(os.path.join(d, "repo.git")):
+        fail(f"分析不存在: {d}（无 repo.git）")
+    cmd = [PYTHON, HUMAN_VIEWER, d] + (["--since", since] if since else [])
+    rc = _call(cmd)
+    if rc:
+        # viewer 失败（坏 ref / 仓库异常）→ **不打印游标**：失败时给出 HEAD
+        # 会让下一次 --since 静默跳过消息（bash 版把 rc 吞成 0 且照打游标，
+        # 属"静默失败"一类；此处改为响亮失败）
+        return rc
+    head = subprocess.run(["git", "-C", os.path.join(d, "repo.git"),
+                           "rev-parse", "HEAD"],
+                          stdout=subprocess.PIPE, text=True,
+                          stderr=subprocess.DEVNULL).stdout.strip()
+    print(f"HEAD={head}")
+    return 0
+
+
+def cmd_say(args):
+    """插话。两种形态**按参数个数**区分（不按值猜语义）：
+
+      `--say <dir> "<文本>"`   显式目录
+      `--say "<文本>"`         目录自动发现
+
+    多于 2 个参数**响亮失败**（bash 版静默忽略多余参数——未加引号的文本
+    会被当成目录，行为不可预期；此处直接报错并提示加引号）。
+    """
+    if len(args) > 2:
+        fail("--say 接受 1 个参数（文本）或 2 个（目录 文本）——"
+             "文本含空格请加引号")
+    if len(args) == 2:
+        d = require_dir(resolve_dir(args[0]))
+        text = args[1]
+    else:
+        d = require_dir(resolve_dir(""))
+        text = args[0] if args else ""
+    if not os.path.isdir(os.path.join(d, "work-human")):
+        fail(f"分析缺少 work-human: {d}")
+    if not text:
+        fail("插话文本不能为空")
+    return _call([PYTHON, HUMAN_SAYER, d, text])
+
+
+# ---------------------------------------------------------------
+# 创建类命令
+# ---------------------------------------------------------------
+
+def cmd_prepare(args):
+    """生成 spec 骨架（`--spec-gen` 是唯一实现，本层只解析参数 + 展示）。"""
+    if not args:
+        print(USAGE, file=sys.stderr)
+        return 2
+    topic = args[0]
+    background = None
+    agents_list = None
+    i = 1
+    while i < len(args):
+        a = args[i]
+        if a == "--background":
+            if i + 1 >= len(args):
+                fail("--background 需要一个值")
+            background = args[i + 1]
+            i += 2
+        elif a == "--agents":
+            if i + 1 >= len(args):
+                fail("--agents 需要一个值（逗号分隔名称列表或数字）")
+            agents_list = args[i + 1]
+            i += 2
+        elif a in ("-h", "--help"):
+            print(USAGE)
+            return 0
+        else:
+            fail(f"未知参数: {a}（--prepare 只接受 <问题>、--background、--agents）")
+    if not topic:
+        fail("问题不能为空")
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    spec_dir = os.path.join(os.getcwd(), f"mv-spec-{stamp}")
+    # 目录不预创建——python 侧校验失败 = 零产物（预创建会让"不合规零产物"
+    # 失效，实测 2026-09-09；成功时 gen_spec_skeleton 自建）。
+    # agents 缺省 = viewers 快照模式：校验与快照都在 python 侧
+    # （_snapshot_viewers；不合规根本不应该开始 spec-gen）。
+    cmd = [PYTHON, START_DISCUSSION, "--spec-gen", spec_dir, "--topic", topic]
+    if background:
+        cmd += ["--background", background]
+    if agents_list:
+        cmd += ["--agents", agents_list]
+    if _call(cmd):
+        fail("spec 骨架生成失败（start_discussion --spec-gen，见上方错误）")
+    print(f"""已生成分析 spec:
+  {spec_dir}
+
+请查看/编辑该目录，补充背景、各 agent 视角等。
+编辑完成后，告诉我"继续"，我会自动启动分析。""")
+    return 0
+
+
+def cmd_start(spec_dir, extra):
+    """创建分析环境 + 启动：两段调用 start_discussion（创建 → --start）。
+
+    中间夹一步 spec 处理：**只删本工具生成的形态**（`mv-spec-*`），用户自建
+    的 spec 目录不动（可能是有价值的视角快照）。删除前提示一行——spec 是
+    视角任务书/背景/models 在用户侧的唯一副本，删了不可恢复。
+    """
+    require_dir(spec_dir)
+    if not os.path.isfile(os.path.join(spec_dir, "question.md")):
+        fail(f"spec 缺少 question.md: {spec_dir}")
+
+    session_id = os.environ.get("PI_SESSION_ID", "")
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    # 目录前缀 mv-：与 pi-agents-helper 的 discuss-<sid>-* **命名空间隔离**
+    # ——两个系统的 extension 都按"同 sid 最新目录"发现目标，共用前缀会在
+    # 同 session 并发两套时互相插错（且 human 消息格式兼容 → 静默写错）。
+    dir_name = "mv" + (f"-{session_id}" if session_id else "") + f"-{stamp}"
+    dir_path = os.path.join(os.getcwd(), dir_name)
+
+    # 第 1 步：创建分析环境（不启动；fork 源由 python 侧 resolve_fork_source
+    # 自动解析）。余参原样转发（--fork-mode 等）：值识别与默认值的唯一家在
+    # python argparse，本层不解析、不丢弃。
+    if _call([PYTHON, START_DISCUSSION, "--dir", dir_path,
+              "--spec", spec_dir] + extra):
+        fail("环境创建失败，请查看上方输出")
+
+    if fnmatch.fnmatch(os.path.basename(os.path.normpath(spec_dir)),
+                       "mv-spec-*"):
+        print(f"[start] spec 已消费，删除（本工具生成形态）: {spec_dir}")
+        shutil.rmtree(spec_dir, ignore_errors=True)
+    else:
+        print(f"[start] spec 已消费（保留未删——非 mv-spec-* 形态）: {spec_dir}")
+
+    # 第 2 步：启动已有环境
+    if _call([PYTHON, START_DISCUSSION, "--dir", dir_path,
+              "--skip-setup", "--start"]):
+        fail("启动失败，请查看上方输出")
+
+    print(f"""多视角分析已启动
+目录: {dir_path}
+
+观看分析（复制执行，不进 LLM；Ctrl-C 中断后可插话再续看）:
+!!python3 "{HUMAN_VIEWER}" {dir_path} --follow
+
+查看进展: {PROG} --view {dir_path}
+插话: {PROG} --say {dir_path} "<文本>"
+查看状态: {PROG} --status {dir_path}
+等待完成: {PROG} --wait {dir_path}
+清理: {PROG} --cleanup {dir_path}
+
+说明:
+- human 通道：--view 增量查看（主 pi 记录末尾 HEAD 作下轮 --since）；
+  --say 插话（agents 可见并可回应；已冻结 agent 不响应）
+- 完成后 result.md 自动保存到固定位置：{dir_path}-result.md（与分析目录同级——resultWriter loop 退出时保存；cleanup 也会保存）
+- 读取 result.md 摘要后请执行 --cleanup 清理分析目录""")
+    return 0
+
+
+# ---------------------------------------------------------------
+# 分发
+# ---------------------------------------------------------------
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if not argv:
+        print(USAGE, file=sys.stderr)
+        return 2
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "--prepare":
+        return cmd_prepare(rest)
+    if cmd == "--start":
+        if not rest:
+            fail("--start 需要 spec 目录参数")
+        return cmd_start(rest[0], rest[1:])
+    if cmd == "--status":
+        return cmd_status(rest)
+    if cmd == "--report":
+        return cmd_report(rest)
+    if cmd == "--wait":
+        return cmd_wait(rest)
+    if cmd == "--cleanup":
+        return cmd_cleanup(rest)
+    if cmd == "--view":
+        return cmd_view(rest)
+    if cmd == "--say":
+        return cmd_say(rest)
+    if cmd in ("-h", "--help"):
+        print(USAGE)
+        return 0
+    print(USAGE, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

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

package/scripts/mv.sh

@@ -1,364 +1,17 @@
 #!/usr/bin/env bash
 #
-# pi-multi-viewers wrapper——多视角协同分析（fork 主 session + meeting 协议）
+# mv.sh —— 多视角协同分析的**稳定入口**（shim）。
 #
-# 用法：
-#   ./scripts/mv.sh --prepare "<主题>" [--agents "a,b,c"|4]
-#   ./scripts/mv.sh --start <spec目录>   # 可选 --fork-mode compaction|budget|full
-#   ./scripts/mv.sh --status <dir>
-#   ./scripts/mv.sh --report <dir>
-#   ./scripts/mv.sh --wait <dir>
-#   ./scripts/mv.sh --cleanup <dir>
-#   ./scripts/mv.sh --view <dir> [--since <ref>]     # human-viewer 封装
-#   ./scripts/mv.sh --say <dir> "<文本>"              # human-sayer 封装
+# 逻辑在 mv_cli.py（见该文件首注释：为什么这层从 364 行 bash 收敛为 Python——
+# bash 陷阱产出的真实 bug 与"零行覆盖"的盲区）。本文件只做一件事：找到仓库
+# 根、把展示名（$0 语义）与参数交给 mv_cli.py。
+#
+# **路径不能变**：prompt / README / 用户习惯都引用 scripts/mv.sh。
 set -u
-
 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"
-
-
-usage() {
-    cat <<'USAGE_EOF'
-用法:
-  $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] "<文本>"
-
-消费命令的 <dir> 可省略（自动发现本 session 当前分析——按 cwd 下
-mv-<PI_SESSION_ID>-* 最新；找不到则取最新 mv-* 并警告）
-
-默认参数:
-  agents=a,b,c  max-meeting=10  max-rr=7   # 配额默认值的权威在 python argparse（wrapper 不传）
-
---agents: 逗号分隔名称列表（如 "x,y"）或纯数字（如 4 → 生成 a..d）；
-          human 是保留名，不能作为参与者
-
-human 通道:
-  --view: 增量查看分析进展（--since 之后的新消息+状态；末尾输出 HEAD=<hash>，主 pi 记录作下轮 --since）
-  --say:  插话（写一条 human 消息，agents 可见并可回应）
-USAGE_EOF
-}
-
-fail() {
-    echo "错误: $*" >&2
-    exit 1
-}
-
-
-
-require_dir() {
-    local dir="$1"
-    [ -n "$dir" ] || fail "缺少目录参数"
-    [ -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() {
-    readlink -f "$1"
-}
-
-cmd_status() {
-    local dir
-    dir="$(resolve_dir "${1:-}")" || exit $?
-    require_dir "$dir"
-    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --status
-}
-
-cmd_report() {
-    local dir
-    dir="$(resolve_dir "${1:-}")" || exit $?
-    require_dir "$dir"
-    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --report
-}
-
-cmd_wait() {
-    local dir
-    dir="$(resolve_dir "${1:-}")" || exit $?
-    require_dir "$dir"
-    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --wait
-}
-
-cmd_cleanup() {
-    local dir
-    dir="$(resolve_dir "${1:-}")" || exit $?
-    require_dir "$dir"
-    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --cleanup
-}
-
-cmd_view() {
-    local dir since=""
-    # 首参：非空且非 --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)
-                [ "$#" -ge 2 ] || fail "--since 需要一个值"
-                since="$2"
-                shift 2
-                ;;
-            *)
-                fail "未知参数: $1（--view 只接受 --since）"
-                ;;
-        esac
-    done
-    require_dir "$dir"
-    [ -d "$dir/repo.git" ] || fail "分析不存在: $dir（无 repo.git）"
-    if [ -n "$since" ]; then
-        "$PYTHON" "$HUMAN_VIEWER" "$dir" --since "$since"
-    else
-        "$PYTHON" "$HUMAN_VIEWER" "$dir"
-    fi
-    # HEAD 游标（主 pi 记录作下轮 --since；无状态，不写游标文件——
-    # 与 --follow 的 .viewer-cursor 互不干扰）
-    echo "HEAD=$(git -C "$dir/repo.git" rev-parse HEAD)"
-}
-
-cmd_say() {
-    # 两种形态（**按参数个数区分，不是按值猜语义**）：
-    #   --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 "插话文本不能为空"
-    "$PYTHON" "$HUMAN_SAYER" "$dir" "$text"
-}
-
-# 定位主 pi 的 session 文件：优先 PI_SESSION_FILE，否则用当前 cwd 编码路径查找
-# 读取主 pi 的 model/thinking（用户 2026-08-31：aft 不再替换 bash 后
-# 环境变量可用且是当前生效值——优先环境变量，session 文件解析仅为兜底）
-cmd_prepare() {
-    local topic="" background="" agents_list=""
-    if [ "$#" -lt 1 ]; then
-        usage >&2
-        exit 2
-    fi
-    topic="$1"
-    shift
-    while [ "$#" -gt 0 ]; do
-        case "$1" in
-            --background)
-                [ "$#" -ge 2 ] || fail "--background 需要一个值"
-                background="$2"
-                shift 2
-                ;;
-            --agents)
-                [ "$#" -ge 2 ] || fail "--agents 需要一个值（逗号分隔名称列表或数字）"
-                agents_list="$2"
-                shift 2
-                ;;
-            -h|--help)
-                usage
-                exit 0
-                ;;
-            *)
-                fail "未知参数: $1（--prepare 只接受 <问题>、--background、--agents）"
-                ;;
-        esac
-    done
-    [ -n "$topic" ] || fail "问题不能为空"
-
-    # agents 解析（数字展开/human/名字校验）全部收归 python
-    # _parse_agents（2026-09-09 结构收敛：bash = 调度与展示）
-    # viewers 模式（无 --agents）：校验 + 快照已全部移入 python
-    # _snapshot_viewers（铁律 1 职责边界；用户 2026-09-09：不合规根本
-    # 不应该开始 spec-gen，校验在骨架生成之前失败）
-    local snapshot_mode=0
-    [ -z "$agents_list" ] && snapshot_mode=1
-
-    local stamp
-    stamp="$(date +%Y%m%d-%H%M%S)"
-    local spec_dir="$PWD/mv-spec-${stamp}"
-    # （目录不预创建——python 校验失败 = 零产物：预创建会让"不合规
-    # 零产物"失效，实测 2026-09-09；成功时 gen_spec_skeleton 自建）
-
-    # 骨架生成 = start_discussion --spec-gen（唯一实现）：agents/ 三态
-    # （显式占位骨架 / viewers 校验+快照 / 无）全部在 python 侧，bash
-    # 与 CLI 直用产出一致；viewers 校验失败时 python 退出非 0（不合规
-    # 根本不应该开始 spec-gen）
-    local skeleton_args=(--spec-gen "$spec_dir" --topic "$topic")
-    [ -n "$background" ] && skeleton_args+=(--background "$background")
-    if [ "$snapshot_mode" -eq 0 ]; then
-        skeleton_args+=(--agents "$agents_list")
-    fi
-    "$PYTHON" "$START_DISCUSSION" "${skeleton_args[@]}" || {
-        fail "spec 骨架生成失败（start_discussion --spec-gen，见上方错误）"
-    }
-
-    cat <<OUTPUT_EOF
-已生成分析 spec:
-  $spec_dir
-
-请查看/编辑该目录，补充背景、各 agent 视角等。
-编辑完成后，告诉我"继续"，我会自动启动分析。
-OUTPUT_EOF
-}
-
-cmd_start() {
-    local spec_dir="$1"
-    shift                      # 余参 = 透传给 python 的选项（如 --fork-mode X）
-    require_dir "$spec_dir"
-    [ -f "$spec_dir/question.md" ] || fail "spec 缺少 question.md: $spec_dir"
-
-    local session_id="${PI_SESSION_ID:-}"
-    local stamp
-    stamp="$(date +%Y%m%d-%H%M%S)"
-    # 目录前缀 mv-：与 pi-agents-helper 的 discuss-<sid>-* **命名空间隔离**
-    # ——两个系统的 extension 都按"同 sid 最新目录"发现目标，共用前缀会
-    # 在同 session 并发两套时互相插错（且 human 消息格式兼容 → 静默写错）。
-    # 前缀也是产品语言的统一（本项目用"分析"，不再沿用"discuss"）。
-    local dir_name="mv"
-    if [ -n "$session_id" ]; then
-        dir_name="${dir_name}-${session_id}"
-    fi
-    dir_name="${dir_name}-${stamp}"
-    local dir_path="$PWD/$dir_name"
-
-    # fork 源解析已收归 python（resolve_fork_source：env + sessions 编码
-    # glob，2026-09-09 结构收敛；解析失败 python 内部报错退出）
-    # 第 1 步：创建分析环境（不启动；fork 源自动解析）
-    # 配额（max-meeting/max-rr）是环境属性：唯一默认在 python argparse
-    # （10/7），创建时固化 protocol.json——wrapper 不传（W1 双源分叉修复：
-    # 此前 wrapper 5 与 python 7 不一致，两条入口 RR 上限差 40%）
-    # 余参哑转发（P0，e2e10 评审：wrapper 不得静默丢弃参数——值识别/默认值
-    # 的唯一家在 python；本层只转发）
-    if ! "$PYTHON" "$START_DISCUSSION" --dir "$dir_path" --spec "$spec_dir" "$@"; then
-        fail "环境创建失败，请查看上方输出"
-    fi
-
-    # spec 已被消费：只删**本工具生成的形态**（mv-spec-*）——用户自建的
-    # spec 目录不动（可能是有价值的视角快照）。删除前提示一行（此前静默
-    # 删除：spec 是视角任务书/背景/models 在用户侧的唯一副本，删了不可恢复）
-    case "$(basename "$spec_dir")" in
-        mv-spec-*)
-            echo "[start] spec 已消费，删除（本工具生成形态）: $spec_dir"
-            rm -rf "$spec_dir"
-            ;;
-        *)
-            echo "[start] spec 已消费（保留未删——非 mv-spec-* 形态）: $spec_dir"
-            ;;
-    esac
-
-    # 第 3 步：启动已有环境
-    if ! "$PYTHON" "$START_DISCUSSION" --dir "$dir_path" --skip-setup --start; then
-        fail "启动失败，请查看上方输出"
-    fi
-
-    cat <<OUTPUT_EOF
-多视角分析已启动
-目录: $dir_path
-
-观看分析（复制执行，不进 LLM；Ctrl-C 中断后可插话再续看）:
-!!python3 "$ROOT_DIR/human_viewer.py" $dir_path --follow
-
-查看进展: $0 --view $dir_path
-插话: $0 --say $dir_path "<文本>"
-查看状态: $0 --status $dir_path
-等待完成: $0 --wait $dir_path
-清理: $0 --cleanup $dir_path
-
-说明:
-- human 通道：--view 增量查看（主 pi 记录末尾 HEAD 作下轮 --since）；
-  --say 插话（agents 可见并可回应；已冻结 agent 不响应）
-- 完成后 result.md 自动保存到固定位置：$dir_path-result.md（与分析目录同级——resultWriter loop 退出时保存；cleanup 也会保存）
-- 读取 result.md 摘要后请执行 --cleanup 清理分析目录
-OUTPUT_EOF
-}
-
-if [ "$#" -ge 1 ]; then
-    case "$1" in
-        --prepare)
-            shift
-            cmd_prepare "$@"
-            exit $?
-            ;;
-        --start)
-            [ "$#" -ge 2 ] || fail "--start 需要 spec 目录参数"
-            shift
-            cmd_start "$@"
-            exit $?
-            ;;
-        --status)
-            shift
-            cmd_status "${1:-}"
-            exit $?
-            ;;
-        --report)
-            shift
-            cmd_report "${1:-}"
-            exit $?
-            ;;
-        --wait)
-            shift
-            cmd_wait "${1:-}"
-            exit $?
-            ;;
-        --cleanup)
-            shift
-            cmd_cleanup "${1:-}"
-            exit $?
-            ;;
-        --view)
-            shift
-            cmd_view "$@"
-            exit $?
-            ;;
-        --say)
-            shift
-            cmd_say "$@"
-            exit $?
-            ;;
-        -h|--help)
-            usage
-            exit 0
-            ;;
-    esac
-fi
 
-usage >&2
-exit 2
+# MV_INVOKED_AS：usage 与启动块里展示用户实际敲的那条命令（沿用 bash 的
+# $0 语义；直接跑 mv_cli.py 时它会退回默认名）
+MV_INVOKED_AS="${MV_INVOKED_AS:-$0}" \
+exec "${PYTHON:-python3}" "$ROOT_DIR/mv_cli.py" "$@"