pi-multi-viewers 0.1.0

package/prompts/multi-viewers.md

@@ -0,0 +1,94 @@
+---
+description: 多视角协同分析——N 个视角 agent 携带主会话上下文（按预算裁剪+折叠）评审主题
+argument-hint: '"<主题>"'
+---
+
+# Multi-Viewers（多视角协同分析）
+
+**分析主题：$1**（视角来自项目 `viewers/`，不在命令行指定）
+
+这是用户手动触发的流程命令，不是分析内容。**严格按以下步骤执行**，
+完成第 3 步后**结束当前回合**（不等待、不轮询、不转述全文）。
+
+## 视角从哪来
+
+**唯一来源：项目 cwd 下的 `viewers/*.md`**（稳定视角资产——文件名即视角名，
+写好长期复用；wrapper 会把它们快照进 spec，可按场微调）。这类资产属于
+用户的项目，你**不要**擅自新建或改写它们。
+
+`viewers/` 还没建 → 见步骤 1 的失败分支。**不要**在命令行指定视角。
+
+## 步骤
+
+### 1. 生成 spec
+
+```bash
+~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --prepare "<主题>"
+```
+
+**若报错含"未找到 viewers/ 目录"、"仅发现 1 个视角"或"视角任务书不能为空"**：
+说明项目缺可用视角。此时**停下来问用户**，不要自己选——建议帮他按
+下面的"视角设计原则"写 `viewers/<视角名>.md`（建好后再重跑本步骤）。
+
+### 2. 编辑并请用户审核 spec
+
+编辑 spec 目录：
+
+- `question.md`（第二行起）：**任务类型与产出形态**（审阅→提意见；
+  改进建议→说建议；修改→说明可改/需改范围）、分析对象、是否需要达成一致。
+  写得越明确，agent 越不会跑偏去做上下文里的其它事（它们的上下文里有
+  发起分析的完整对话历史）
+- `agents/X.md`（第二行起）：**默认已是 viewers 的快照**——只在用户要求
+  按场微调时才改（如"这一场某视角更关注安全"）
+- `background.md`（可选）：只写**显式约定的边界**（如"不讨论 API 设计"）。
+  **不要**复述对话内容——fork 已让每个 agent 携带主会话上下文
+  （默认 budget 模式：按预算裁剪+折叠）
+- `models.md`：一般不动（默认继承本机配置）
+
+然后**展示 spec 路径，明确请用户查看/编辑**——用户确认"继续"才执行第 3 步。
+
+## 视角设计原则（建 viewers/*.md 或临时 agents/X.md 时必读）
+
+视角之间**互补或对立都可以**——对立产生的分歧正是多视角分析的价值。
+每个视角任务书必须包含：
+
+1. **单一 lenses**：明确该 agent 用什么角度看（性能/简单化/安全/……），
+   要求"所有观点必须从该视角出发"
+2. **不越界**："其它视角由别的参与者负责，你不要越界展开"（**不要**列举
+   具体是哪几个视角——参与者会变，列举会过期）
+3. **交锋义务**："对其它视角的观点可以认同或反驳，但要用本视角的论据"
+
+**只写视角本身**：身份（"你是 X"）、参与者名单、消息格式、独立参与者
+纪律都由脚本生成（agent 名 = 文件名，单一来源）——任务书里**不要写**，
+否则重复且易漂移。
+
+### 3. 启动分析
+
+```bash
+~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --start <spec目录绝对路径>
+```
+
+记录 wrapper 输出的**分析目录**，并**原样完整展示**观看命令。
+
+### 4. 结束回合
+
+告知用户：
+- 观看：复制上一步的 `!!` 命令执行（实时流式，结束时自动退出）
+- 插话：随时 `/multi-viewers-say <文本>`（自动定位当前分析；也可用 wrapper `--say <目录> "<文本>"`）
+- 完成时告诉主 pi，主 pi 会收尾
+
+**然后结束当前回合。**
+
+## 收尾（用户驱动）
+
+```bash
+mv.sh --status <分析目录绝对路径>   # done/stopped/running
+```
+
+- `done`：读 `<分析目录>-result.md`（与目录同级的固定位）→ 向用户给
+  **摘要** → `mv.sh --cleanup <分析目录绝对路径>`
+  - cleanup 会打印**本次分析报告**（提交数 / 墙钟 / 进程跨度 / 配额 / LLM
+    用量 / rc≠0）——这是删目录前最后一次可读，**把其中的关键数字一并
+    转述给用户**（运行成本与健康度的一手信息）
+- `stopped`：报告"分析已结束但未生成结果"，不要继续等待
+- `running`：告知还在进行，继续等用户通知

package/scripts/check-residue.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# 残留检查器——测试/验证结束后的清理验收（一条命令代替人工逐项记忆）
+#
+# 用法: ./scripts/check-residue.sh [--verbose]
+# 退出码: 0 = 干净；1 = 有残留（列出清单）
+#
+# 检查三类测试残留形态（2026-09-09 建立——此前靠人工记忆逐项检查，
+# 反复漏检：afk-e2e 引导 session 漏删即反例）：
+#   1. 主 pi 侧 session：~/.pi/agent/sessions/<编码目录>/*.jsonl 中
+#      近 24h 创建且 cwd 不在白名单（真实项目）的——测试引导 session
+#      散落形态（--tmp-xxx-- 等）
+#   2. 讨论进程：meeting_loop（argv 判据）/ pi（comm + PPID 判据）
+#   3. 分析环境目录：$PWD 下 mv-* 残留（另有 gitignore 兜底不入库）
+#      + 结构识别（2026-09-10 补）：含 repo.git/ 与 pi-sessions/ 的目录
+#      ——测试脚手架常用 /tmp/mv-*/disc 等非 mv-<sid>-* 命名，纯命名匹配
+#      会漏检（e2e8 残留即此盲区），改为按环境结构识别
+#
+# 白名单：cwd 为真实项目目录的 session 不算残留（mv-main 等长期会话）。
+WHITELIST=(
+    "/root/pi-multi-viewers"
+    "/root/pi-agents-helper"
+    "/root/pi-agents-meeting-discuss"
+    "/root/research"
+    "/root/book"
+    "/root/.dsh"
+)
+
+# 测试引导 session 登记日志（meeting_fs.build_bootstrap 每次创建追加）：
+# 报告对照此日志标注归属——已登记 = 本流程测试产物（可删）；未登记 =
+# 非本流程创建（真实会话，勿删）。不靠人猜（2026-09-09 用户：建立时
+# 记录 log 才方便回查，人工确认是推卸责任）。
+REGISTRY="$HOME/.pi/pi-multi-viewers-test-sessions.log"
+is_registered() {
+    # $1 = session 文件路径；按 header 的 session_id 对照登记日志
+    # （build_bootstrap 登记 id；文件路径会因 --session 续写/复制变化，
+    # id 才是稳定标识）。登记过 = 本流程测试产物。
+    local sid
+    sid=$(head -1 "$1" | python3 -c "import json,sys; print(json.loads(sys.stdin.readline()).get('id',''))" 2>/dev/null)
+    [ -n "$sid" ] && grep -q "\"session_id\": \"$sid\"" "$REGISTRY" 2>/dev/null
+}
+
+RESIDUE=0
+
+say() { [ "$1" = "--verbose" ] || [ -n "$VERBOSE" ] && echo "$2"; }
+
+# --- 1. 主 pi 侧近期 session（非白名单 cwd） ---
+SESS_DIR="$HOME/.pi/agent/sessions"
+NOW=$(date +%s)
+for d in "$SESS_DIR"/*/; do
+    [ -d "$d" ] || continue
+    # 编码目录名还原 cwd 近似判断（--tmp-xxx-- / --root-xxx-- 形态）
+    enc=$(basename "$d")
+    for f in "$d"*.jsonl; do
+        [ -f "$f" ] || continue
+        age=$((NOW - $(stat -c %Y "$f")))
+        if [ "$age" -gt 86400 ]; then
+            continue  # 超过 24h，不是本次测试产物
+        fi
+        # 解析 header cwd（第一行 JSON 的 cwd 字段）
+        cwd=$(head -1 "$f" | python3 -c "import json,sys; print(json.loads(sys.stdin.readline()).get('cwd',''))" 2>/dev/null)
+        whitelisted=0
+        for w in "${WHITELIST[@]}"; do
+            case "$cwd" in
+                "$w"*|"$w") whitelisted=1 ;;
+            esac
+        done
+        if [ "$whitelisted" = "0" ]; then
+            # 归属判定（2026-09-09）：登记日志回查——已登记=测试产物
+            # （可删），未登记=非本流程创建（勿删，提示加白名单）。
+            # 首条消息摘要仅作补充信息（不再作为删除判断依据）。
+            if is_registered "$f"; then
+                owner="[已登记-测试产物，可删]"
+            else
+                owner="[未登记-非本流程创建，勿删]"
+                RESIDUE=1
+            fi
+            first_user=$(python3 -c "
+import json, sys
+try:
+    for l in open('$f'):
+        e = json.loads(l)
+        if e.get('type') == 'message' and e.get('message', {}).get('role') == 'user':
+            c = e['message'].get('content')
+            t = c if isinstance(c, str) else ''.join(x.get('text','') for x in (c or []) if isinstance(x, dict) and x.get('type') == 'text')
+            print((t or '')[:60].replace('\\n', ' '))
+            break
+except Exception:
+    print('')
+" 2>/dev/null)
+            echo "[残留-1] session（24h 内 cwd=$cwd，创建 $(stat -c %y "$f" | cut -d. -f1)）$owner"
+            echo "        首条消息: ${first_user:-（无 user 消息）}"
+            echo "        路径: $f"
+        fi
+    done
+done
+
+# --- 2. 讨论/pi 进程 ---
+# 两种进程用**两种判据**（它们的可观测形态不同）：
+#
+# (a) meeting_loop：**argv 逐项精确匹配**（读 /proc/<pid>/cmdline）。文本匹配
+#     会把"命令行里恰好提到 meeting_loop.py"的调用者自身算进来（bash -c / grep
+#     都在此列），再靠 grep -v 白名单过滤又会漏检（任何命令行含 "bash -c" 的
+#     真实进程）。argv 精确匹配无此二难：`python3 .../meeting_loop.py <work>
+#     <agent>` 的 argv[1] 恰是脚本路径；调用者的 -c 脚本只是**一个** argv 元素。
+#     与 start_discussion._loop_pids 同一技术（判据范围不同：这里查任意讨论的
+#     loop——残留检查语义；python 侧查指定 base——存活语义）。
+#
+# (b) pi：**名称 + PPID 双判据**——pi 启动后**重写进程标题**（`/proc/<pid>/cmdline`
+#     变成单个 "pi" + NUL 填充，2026-09-11 实测：2255 字节里只有开头 "pi"），
+#     所以按 argv 找 pi（含旧的 `grep "pi --mode json"`）**从来找不到**。
+#     可用信号是 /proc/<pid>/comm（node 改写的进程名 = "pi"）与其 PPID（父进程
+#     必是 meeting_loop——由 loop 直接 spawn）。名称单独用会误认用户自己开的
+#     pi TUI；PPID 单独用会在 loop 已死（pi 被 init 收养）时漏检——两者并用
+#     并对"未关联"单独标注，既不误报也不漏报。
+_proc_argv_has() {   # $1=pid 目录，$2=精确参数
+    local d="$1" arg
+    while IFS= read -r -d '' arg; do
+        [ "$arg" = "$2" ] && return 0
+    done < "$d/cmdline" 2>/dev/null
+    return 1
+}
+LOOP_PIDS=""          # 第一遍收集，供第二遍做 PPID 关联
+for d in /proc/[0-9]*; do
+    [ -r "$d/cmdline" ] || continue
+    pid="${d#/proc/}"
+    while IFS= read -r -d '' arg; do
+        case "$arg" in
+            */meeting_loop.py)
+                echo "[残留-2] meeting_loop 进程 PID=$pid: $(ps -p "$pid" -o cmd= 2>/dev/null)"
+                RESIDUE=1
+                LOOP_PIDS="$LOOP_PIDS $pid"
+                break
+                ;;
+        esac
+    done < "$d/cmdline" 2>/dev/null
+done
+for d in /proc/[0-9]*; do
+    [ -r "$d/comm" ] || continue
+    pid="${d#/proc/}"
+    [ "$(cat "$d/comm" 2>/dev/null)" = "pi" ] || continue
+    ppid="$(awk '{print $4}' "$d/stat" 2>/dev/null)"
+    if [ "$ppid" = "1" ]; then
+        # loop 已退出、pi 被 init 收养（PPID=1）——孤儿残留
+        echo "[残留-2] pi 进程 PID=$pid（孤儿：PPID=1，其 loop 已退出）"
+        RESIDUE=1
+        continue
+    fi
+    case " $LOOP_PIDS " in
+        *" $ppid "*)
+            echo "[残留-2] pi 进程 PID=$pid（父 meeting_loop PID=$ppid）"
+            RESIDUE=1
+            ;;
+        # 其余 comm=pi 的进程不报：用户自己正在用的 pi 会话（PPID 是
+        # pi-web/shell 等）不是残留——"名称 + PPID"两个条件同时成立才判定
+    esac
+done
+
+# --- 3. 分析环境目录残留 ---
+# 3a. 命名形态：$PWD 下 mv-*（兜底：半创建、尚无 repo.git 的环境）。
+#     排除 mv-spec-*——那是用户尚未消费的 spec 目录（正常存在，非残留）
+for d in mv-*/; do
+    [ -d "$d" ] || continue
+    case "$(basename "$d")" in
+        mv-spec-*) continue ;;
+    esac
+    echo "[残留-3] 分析目录: $PWD/$d"
+    RESIDUE=1
+done
+
+# 3b. 结构形态：任何含 repo.git/ + pi-sessions/ 的目录 = 讨论环境
+#（扫描 $PWD 与 /tmp，深度 ≤3；与 3a 去重）
+# 去重用空格包裹的字符串匹配（不用 declare -A：避免 bash 4+ 依赖，
+# 路径不含空格——本仓库路径约定）
+SEEN_ENVS=""
+for base in "$PWD" "${TMPDIR:-/tmp}"; do
+    [ -d "$base" ] || continue
+    while IFS= read -r g; do
+        d=$(dirname "$g")
+        [ -d "$d/pi-sessions" ] || continue
+        case " $SEEN_ENVS " in *" $d "*) continue ;; esac
+        SEEN_ENVS="$SEEN_ENVS $d"
+        echo "[残留-3] 讨论环境: $d（$(du -sh "$d" 2>/dev/null | cut -f1)）"
+        RESIDUE=1
+    done < <(find "$base" -maxdepth 3 -type d -name repo.git 2>/dev/null)
+done
+
+if [ "$RESIDUE" = "0" ]; then
+    echo "干净：无测试残留"
+fi
+exit "$RESIDUE"

package/scripts/mv.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+#
+# pi-multi-viewers wrapper——多视角协同分析（fork 主 session + meeting 协议）
+#
+# 用法：
+#   ./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 封装
+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"
+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> "<文本>"
+
+默认参数:
+  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"
+}
+
+# 目录参数规范化：裸名（无路径符）会被 start_discussion 加 discussion-
+# 前缀导致找错目录（实测 2026-09-03）——所有消费命令入口统一转绝对路径
+normalize_dir() {
+    readlink -f "$1"
+}
+
+cmd_status() {
+    local dir
+    dir="$(normalize_dir "$1")"
+    require_dir "$dir"
+    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --status
+}
+
+cmd_report() {
+    local dir
+    dir="$(normalize_dir "$1")"
+    require_dir "$dir"
+    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --report
+}
+
+cmd_wait() {
+    local dir
+    dir="$(normalize_dir "$1")"
+    require_dir "$dir"
+    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --wait
+}
+
+cmd_cleanup() {
+    local dir
+    dir="$(normalize_dir "$1")"
+    require_dir "$dir"
+    "$PYTHON" "$START_DISCUSSION" --dir "$dir" --cleanup
+}
+
+cmd_view() {
+    local dir since=""
+    dir="$(normalize_dir "$1")"
+    shift
+    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() {
+    local dir text="${2:-}"
+    dir="$(normalize_dir "$1")"
+    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)
+            [ "$#" -ge 2 ] || fail "--status 需要分析目录参数"
+            cmd_status "$2"
+            exit $?
+            ;;
+        --report)
+            [ "$#" -ge 2 ] || fail "--report 需要分析目录参数"
+            cmd_report "$2"
+            exit $?
+            ;;
+        --wait)
+            [ "$#" -ge 2 ] || fail "--wait 需要分析目录参数"
+            cmd_wait "$2"
+            exit $?
+            ;;
+        --cleanup)
+            [ "$#" -ge 2 ] || fail "--cleanup 需要分析目录参数"
+            cmd_cleanup "$2"
+            exit $?
+            ;;
+        --view)
+            [ "$#" -ge 2 ] || fail "--view 需要分析目录参数"
+            shift
+            cmd_view "$@"
+            exit $?
+            ;;
+        --say)
+            [ "$#" -ge 3 ] || fail "--say 需要分析目录和文本参数"
+            cmd_say "$2" "$3"
+            exit $?
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+    esac
+fi
+
+usage >&2
+exit 2