pi-multi-viewers 0.1.0

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

@@ -0,0 +1,156 @@
+/**
+ * multi-viewers-say —— 多视角分析插话命令（零 LLM 参与）
+ *
+ * 用户输入 `/multi-viewers-say <文本>` 时立即执行 human_sayer：
+ * 把文本作为 human 消息注入当前分析（各视角 agent 可见、可回应）。
+ * 不经过 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- 与 pi-agents-helper 的 discuss-* 命名空间隔离（两个系统的
+ * 插话命令都按"同 sid 最新目录"发现目标，共用前缀会互相插错）。
+ *
+ * 观看分析仍用 `!!` bash 流式（human_viewer --follow）——命令 API 无原生
+ * 流式通道（handler 返回 Promise<void>），且 bash 流式是平台原生能力。
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---- 自定位：import.meta.url 向上找包根（package.json name = 包名）----
+// 扩展从包内加载时（pi install / npm 安装 + symlink）零硬编码——
+// 包移到哪都能工作；复制安装（拆散包结构）时找不到包根 → 回退开发机路径。
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_NAME = "pi-multi-viewers";
+
+function findPackageRoot(start: string, pkgName: string): string | null {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(dir, "package.json"), "utf8"),
+      );
+      if (pkg.name === pkgName) return dir;
+    } catch {
+      // 继续向上
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+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"; // 复制安装退化（开发机）
+
+/** 按 (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 };
+    }
+    return { dir: null, degraded: false };
+  } catch {
+    return { dir: null, degraded: false };
+  }
+}
+
+/** 执行 human_sayer.py 一次插话。返回 { ok, output }。 */
+function runSayer(
+  dir: string,
+  text: string,
+): Promise<{ ok: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const proc = spawn("python3", [SAYER, dir, text], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    proc.stdout.on("data", (d) => (out += d.toString()));
+    proc.stderr.on("data", (d) => (out += d.toString()));
+    proc.on("close", (code) => resolve({ ok: code === 0, output: out.trim() }));
+    proc.on("error", (e) => resolve({ ok: false, output: String(e) }));
+  });
+}
+
+export default function register(pi: any) {
+  pi.registerCommand("multi-viewers-say", {
+    description: "向正在进行的多视角分析插话（human 消息，各视角可见可回应）",
+    argumentHint: "<插话内容>",
+    getArgumentCompletions: () => null,
+    handler: async (args: string, ctx: any) => {
+      const text = args.trim();
+      if (!text) {
+        ctx.ui.notify(
+          "插话内容为空——用法: /multi-viewers-say <文本>",
+          "warning",
+        );
+        return;
+      }
+      const sid = ctx.sessionManager.getSessionId();
+      const found = findCurrentDir(ctx.cwd, sid);
+      const dir = found.dir;
+      if (!dir) {
+        ctx.ui.notify(
+          "没有正在进行的多视角分析（cwd 下无 mv-* 目录）。" +
+            "先用 /multi-viewers 启动分析。",
+          "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");
+      } else if (ok) {
+        ctx.ui.notify("插话已发送", "success");
+      } else {
+        ctx.ui.notify(`插话失败: ${output || "未知错误"}`, "error");
+      }
+    },
+  });
+}

package/fake_agent.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""fake_agent.py —— FakeAgent（模拟"内容 LLM" + 引擎流程接管）。
+
+职责边界（设计确认 2026-08-09）：
+- responder（模拟 LLM）= 只做**内容决定**：写 type + 正文，
+  不写 next/mode/seen_at/from（真实 LLM 不知道这些协议字段）
+- 流程（补全字段/commit/push/触发/级联/收尾）= 全部由引擎（loop）接管
+
+之前的错误：FakeAgent 替 LLM 写 next/mode → 模拟的是"假想完美流程 LLM"，
+掩盖了真实路径缺陷（LLM 漏 next → 卡死）。现在与真实 LLM 职责一致。
+
+用法：python3 fake_agent.py <workdir> <agent> <min_sleep> <max_sleep> <crash_rate>
+       <max_meeting_rounds> <max_rr_rounds>
+"""
+
+import os
+import json
+import random
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from meeting_fs import next_msg_id, write_message
+from meeting_engine import agent_loop
+
+
+# 测试装置：记录每个 agent 处理过（收到 prompt 中）的消息文件。
+# 仅 FakeAgent（模拟 LLM）记录——正常流程不记录（用户 9988：这只是测试，
+# 验证 agent 完整处理了所有消息、无遗漏）。多进程子进程写文件，测试进程读。
+PROCESSED_DIR = "processed"   # 讨论根下的目录名
+
+
+def record_processed(workdir, agent, meta):
+    """记录本 agent 收到（prompt 包含）的消息文件路径，去重后落盘。
+
+    workdir: work-<agent>；记录写到讨论根 processed/<agent>.json。
+    meta: 新消息列表（含 path 字段）。
+    """
+    if not meta:
+        return
+    base = os.path.dirname(workdir)
+    pdir = os.path.join(base, PROCESSED_DIR)
+    os.makedirs(pdir, exist_ok=True)
+    pf = os.path.join(pdir, f"{agent}.json")
+    seen = set()
+    if os.path.exists(pf):
+        try:
+            seen = set(json.load(open(pf)))
+        except (OSError, ValueError):
+            seen = set()
+    seen.update(m["path"] for m in meta)
+    with open(pf, "w") as f:
+        json.dump(sorted(seen), f)
+
+
+def make_responder(min_sleep, max_sleep, crash_rate):
+    """构造"内容 LLM" responder：只写 type + 正文，不写协议字段。"""
+    def responder(workdir, agent, head, meta, is_first, rr_turn, retry,
+                  finalizing=False, finalize_reason="consensus"):
+        # --- 测试装置：记录收到（prompt 包含）的消息文件（用户 9960）---
+        # 模拟 LLM 的"感知"：meta = 本次唤醒读点之后的新消息。
+        # 正常流程不记录（仅 FakeAgent 测试用）。
+        record_processed(workdir, agent, meta)
+        # --- 内容决定（LLM 的判断）---
+        if finalizing:
+            # 收尾指令：resultWriter 写 result.md（双面约束：此时才允许写）
+            result_path = os.path.join(workdir, "result.md")
+            # 内容 >50 字节（_result_md_valid 阈值，审核#3）——否则恒走
+            # loop 兜底代写，正常收尾路径零验证（fake 与真实 responder 语义不一致）
+            # 文案三分支（review4 L12）：stall 不误标"配额耗尽"
+            if finalize_reason == "consensus":
+                rtxt = "全员 pass，共识达成"
+            elif finalize_reason == "quota":
+                rtxt = "配额耗尽，未完全共识"
+            else:
+                rtxt = "无进展超时（stall），未完全共识"
+            with open(result_path, "w") as f:
+                f.write(f"# 讨论结果\n\n{rtxt}。\n"
+                        f"三方结论一致，无遗留分歧。详细结论见讨论消息。\n")
+            return True
+        if retry:
+            # 被重试（上次没产出）：无静默铁律，强制表态
+            decision = "freezing" if not rr_turn else "pass"
+        elif rr_turn:
+            # RR 阶段：单向流，只写 pass（无异议回退，留待以后）
+            decision = "pass"
+        else:
+            # meeting 阶段：有内容 → message；无话可说 → freezing
+            decision = "message" if random.random() < 0.65 else "freezing"
+
+        time.sleep(random.uniform(min_sleep, max_sleep))
+        if random.random() < crash_rate:
+            print(f"[{agent}] 模拟崩溃（未写文件）", flush=True)
+            return False
+
+        # --- 只写内容文件（最小 frontmatter：只有 type，其他字段留给 loop 补全）---
+        msg_id = next_msg_id(workdir, agent)
+        os.makedirs(os.path.join(workdir, agent), exist_ok=True)
+        fm = {
+            "type": decision,
+        }
+        path = f"{agent}/{msg_id}.md"
+        write_message(workdir, path, fm, f"{decision} by {agent} (sim content)")
+        # 流程（补全/commit）由引擎的 respond_with_fallback 接管——
+        # responder 只负责写内容文件
+        return True
+    return responder
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 8:
+        print("用法: fake_agent.py <workdir> <agent> <min_sleep> <max_sleep> "
+              "<crash_rate> <max_meeting_rounds> <max_rr_rounds>")
+        sys.exit(1)
+    workdir, agent = sys.argv[1], sys.argv[2]
+    responder = make_responder(float(sys.argv[3]), float(sys.argv[4]),
+                               float(sys.argv[5]))
+    agent_loop(workdir, agent, responder,
+               max_meeting=int(sys.argv[6]), max_rr=int(sys.argv[7]))

package/human_sayer.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""human_sayer.py —— human 插话命令（pi-agents-helper 阶段 2）。
+
+human 通道的写入进程（docs/pi-helper-design.md §5.3）：写一条 human
+消息到 bare（经 work-human 提交通道），agents 下次轮询即可看到并可响应。
+
+用法:
+  python3 human_sayer.py <base> <文本>             # 文本参数（可多行）
+  echo "多行文本" | python3 human_sayer.py <base>  # 无文本参数时读 stdin
+
+frontmatter 由本命令**确定性补全**（人只提供正文，设计 §2.2）：
+  from: human / type: message（强制——人不写流程信号）/
+  mode: 写入时当前聚合 mode / seen_at: 写入时 HEAD / to: all /
+  summary: 正文首行截取（可选）
+
+并发容错（设计 §5.3）：
+  - flock work-human/.human.lock：两个 sayer 串行（主 pi + 手动插话）
+  - 写前 pull + git_push 容错重试：与 agents 并发写（push 非快进 →
+    pull --rebase → 重推）
+"""
+
+import argparse
+import fcntl
+import os
+import sys
+
+from meeting_fs import (
+    bare_of_base, bare_of_workdir, git_head, git_pull, git_commit, git_push,
+                        next_msg_id, write_message, commit_message)
+from meeting_engine import aggregate_mode, participants
+
+SUMMARY_MAX = 60          # summary 截取长度（frontmatter 值单行化后展示用）
+HUMAN = "human"           # 固定名（保留字，start_discussion 校验）
+
+
+def _summary(body):
+    """正文首行截取为 summary（frontmatter 值单行化前的摘要）。"""
+    first = next((l.strip() for l in body.splitlines() if l.strip()), "")
+    return first[:SUMMARY_MAX] if first else ""
+
+
+def say(workdir, body):
+    """写一条 human 消息（flock + pull + frontmatter + commit + push）。
+
+    workdir: work-human 路径
+    body: 正文（多行）
+    返回: (path, summary)——消息文件路径与摘要
+    """
+    bare = bare_of_workdir(workdir)
+    lock_path = os.path.join(workdir, ".human.lock")
+    with open(lock_path, "w") as lf:
+        fcntl.flock(lf, fcntl.LOCK_EX)
+        # 写前同步（对齐生产 commit_new_files：pull 后再写，防序号/HEAD 落后）
+        git_pull(workdir)
+        head = git_head(bare)
+        agents = participants(bare)
+        mode = aggregate_mode(bare, agents) if agents else "meeting"
+        mid = next_msg_id(workdir, HUMAN)
+        path = f"{HUMAN}/{mid}.md"
+        fm = {
+            "from": HUMAN,
+            "type": "message",        # 强制——人不写流程信号
+            "mode": mode,             # 写入时当前聚合 mode（不参与判定，仅信息）
+            "seen_at": head,          # 人看到了当前全部状态
+            "to": "all",
+        }
+        summ = _summary(body)
+        if summ:
+            fm["summary"] = summ
+        write_message(workdir, path, fm, body)
+        git_commit(workdir, [path], commit_message(HUMAN, mid))
+        git_push(workdir)             # 容错重试（与 agents 并发写）
+        fcntl.flock(lf, fcntl.LOCK_UN)
+    return path, summ
+
+
+def interactive(workdir):
+    """交互模式：逐行累积，空行提交（粘贴多行/打字统一语义）。
+
+    终端交互插话用法（实测 2026-08-30 用户反馈：shell 敲命令不直观）：
+      python3 human_sayer.py <base> -i
+    然后直接输入插话内容：
+      > 第一行
+      > 第二行（继续累积）
+      > （空行 Enter）→ 提交整块，已发送 human/NNNN.md
+    粘贴多行文本：粘贴的换行逐行进入累积，最后空行提交；
+    空行且无累积 → 忽略；Ctrl-D 退出。
+    """
+    print("输入插话内容（逐行累积，空行 Enter 提交；Ctrl-D 退出）",
+          flush=True)
+    lines = []
+    while True:
+        try:
+            line = input("> ")
+        except EOFError:
+            break
+        if line.strip():
+            lines.append(line)
+        elif lines:
+            body = "\n".join(lines)
+            lines = []
+            path, summ = say(workdir, body)
+            print(f"已发送 {path}" + (f"（摘要: {summ}）" if summ else ""),
+                  flush=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="human 插话（写一条消息）")
+    parser.add_argument("base", help="分析目录（含 repo.git 与 work-human）")
+    parser.add_argument("text", nargs="?", default=None,
+                        help="插话文本（可多行；不传则读 stdin）")
+    parser.add_argument("-i", "--interactive", action="store_true",
+                        help="交互模式：逐行输入，空行提交（终端手动插话）")
+    args = parser.parse_args()
+
+    base = os.path.abspath(os.path.expanduser(args.base))
+    workdir = os.path.join(base, "work-human")
+    bare = bare_of_base(base)
+    if not os.path.isdir(bare):
+        print(f"错误: 分析不存在: {base}", file=sys.stderr)
+        return 1
+    if not os.path.isdir(workdir):
+        print(f"错误: work-human 不存在: {workdir}（分析创建于 human 功能之前?）",
+              file=sys.stderr)
+        return 1
+
+    if args.interactive:
+        interactive(workdir)
+        return 0
+
+    body = args.text if args.text is not None else sys.stdin.read()
+    body = body.strip()
+    if not body:
+        print("错误: 插话内容为空（传 <文本> 参数或经 stdin 输入）",
+              file=sys.stderr)
+        return 1
+
+    path, summ = say(workdir, body)
+    print(f"已发送 {path}" + (f"（摘要: {summ}）" if summ else ""))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/human_viewer.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""human_viewer.py —— 只读展示分析进展。
+
+human 通道的展示进程（docs/pi-helper-design.md §5.2）：纯 bare 只读，
+无写路径。增量输出 `--since <ref>` 之后的新消息 + 状态变化（mode 切换）。
+
+用法:
+  python3 human_viewer.py <base>                  # 当前状态 + 全部消息
+  python3 human_viewer.py <base> --since <ref>    # 增量（ref 之后）
+  python3 human_viewer.py <base> --follow         # 循环展示直到分析结束
+
+输出契约（稳定文本，供壳/主 pi 消费）：
+  【状态】<mode>
+  [<path>] <from> (<type>): <summary 若有>
+  <正文>
+  ---
+
+--follow 模式：游标持久化 <base>/.viewer-cursor（记录的 ref），重启不丢；
+分析 done（mode == concluded）→ 打印 result.md 路径后退出。
+
+复用边界：frontmatter 解析/正文提取/消息文件判定/git log 输出解析全部
+来自 meeting_fs（单一实现）；本模块只做 bare 只读组装与展示格式。
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+import meeting_fs
+from meeting_fs import (run_git, git_show, git_head, is_message_file,
+                        parse_log_nameonly, extract_body, parse_frontmatter)
+from meeting_engine import aggregate_mode
+
+
+def participants_from_bare(bare):
+    """参与者列表（单一事实源 = bare HEAD 的 protocol.json）。"""
+    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"
+
+
+def new_messages(bare, since):
+    """since 之后的新消息文件（commit 拓扑序，旧→新）。
+
+    返回: list[(commit, path)]——只含消息文件（作者/NNNN.md，含 human/）。
+    since: git ref（""/None = 全部）
+    """
+    if since:
+        r = run_git(bare, "log", f"{since}..HEAD", "--name-only",
+                    "--format=%H", "--reverse", check=False)
+    else:
+        r = run_git(bare, "log", "HEAD", "--name-only",
+                    "--format=%H", "--reverse", check=False)
+    result = []
+    for commit, fls in parse_log_nameonly(r.stdout):
+        for f in fls:
+            if is_message_file(f):
+                result.append((commit, f))
+    return result
+
+
+def format_message(path, content):
+    """消息 → 展示行。返回 str | None（frontmatter 不可用）。"""
+    fm = parse_frontmatter(content)
+    if not fm:
+        return None
+    body = extract_body(content) or ""
+    header = f"[{path}] {fm.get('from', '?')} ({fm.get('type', '?')})"
+    if fm.get("summary"):
+        header += f": {fm['summary']}"
+    if body:
+        return f"{header}\n{body}\n---"
+    return f"{header}\n---"
+
+
+def is_finished(bare, agents, mode=None):
+    """分析是否**收尾完成**（`--wait`/viewer/`--status` 共用的唯一判据）。
+
+    定义 = `concluded`（状态机聚合）**且** result.md 已进 bare 且有效。
+
+    为什么两条件：`concluded` 是协议信号、result.md 是产物——只认 concluded
+    会在产物落盘前先报"已结束"并打印尚不存在的路径（§3.5-P5 实测分叉）；
+    只认 result.md 则无法区分"收尾进行中"与"收尾中断（stalled）"。
+    为什么落 viewer：它是唯一增量实现的持有者，也是观察端判据的家。
+    """
+    if mode is None:
+        mode = aggregate_mode(bare, agents)
+    if mode != "concluded":
+        return False
+    content = git_show(bare, "HEAD", "result.md")
+    return bool(content) and len(content) > 50
+
+
+def incremental(bare, agents, since):
+    """单次增量读取。
+
+    返回: (mode, lines: list[str], head, done)
+    - mode: 当前聚合 mode（meeting/all-freezing/round-robin/concluded）
+    - lines: 新消息展示行（旧→新）
+    - head: 当前 HEAD
+    - done: 分析是否已收尾（mode == concluded）
+    """
+    mode = aggregate_mode(bare, agents)
+    lines = []
+    for commit, path in new_messages(bare, since):
+        content = git_show(bare, commit, path)
+        if content is None:
+            continue
+        s = format_message(path, content)
+        if s:
+            lines.append(s)
+    head = git_head(bare)
+    return mode, lines, head, is_finished(bare, agents, mode)
+
+
+def _cursor_path(base):
+    return os.path.join(base, ".viewer-cursor")
+
+
+def _read_cursor(base):
+    try:
+        with open(_cursor_path(base)) as f:
+            return f.read().strip() or None
+    except OSError:
+        return None
+
+
+def _write_cursor(base, ref):
+    with open(_cursor_path(base), "w") as f:
+        f.write(ref + "\n")
+
+
+# 观察端刷新节奏（**有意独立于状态机的空闲重试节奏**）：
+# meeting_engine.POLL_INTERVAL 是 loop 的空闲轮询（与 API/CPU 成本相关），
+# 这里是"观察者多久看一眼"（与 UX 延迟相关）——共享值 ≠ 共享概念。
+# 若直接绑定 engine 的常量，将来调 loop 节奏会**静默改变观察契约**
+# （动作-远距离耦合）。两者当前同为 2.0s 只是巧合，改一个不影响另一个。
+# 下界 ≥1s：每次刷新 ≈3 个 git 子进程 + /proc 扫描；调到 0.1s 会变成
+# ~30% 单核的无谓开销。
+OBSERVER_POLL_INTERVAL = 2.0
+
+
+def follow(base, bare, agents, poll_interval=OBSERVER_POLL_INTERVAL):
+    """--follow：循环展示（tail -f 式）直到分析结束。"""
+    since = _read_cursor(base)
+    last_mode = None
+    while True:
+        mode, lines, head, done = incremental(bare, agents, since)
+        if mode != last_mode:
+            print(f"【状态】{mode}", flush=True)
+            last_mode = mode
+        for s in lines:
+            print(s, flush=True)
+        if head != since:
+            _write_cursor(base, head)
+            since = head
+        if done:
+            print(f"【分析已结束】result.md: {result_path(base)}",
+                  flush=True)
+            return
+        time.sleep(poll_interval)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="human 分析展示（只读）")
+    parser.add_argument("base", help="分析目录（含 repo.git）")
+    parser.add_argument("--since", default=None, help="增量起点 ref（git ref）")
+    parser.add_argument("--follow", action="store_true", help="循环展示直到结束")
+    args = parser.parse_args()
+
+    base = os.path.abspath(os.path.expanduser(args.base))
+    bare = meeting_fs.bare_of_base(base)
+    if not os.path.isdir(bare):
+        print(f"错误: 分析不存在: {base}", file=sys.stderr)
+        return 1
+
+    agents = participants_from_bare(bare)
+    if not agents:
+        print(f"错误: 无法读取 protocol.json（分析未初始化?）: {base}",
+              file=sys.stderr)
+        return 1
+
+    sys.stdout.reconfigure(line_buffering=True)
+    if args.follow:
+        follow(base, bare, agents)
+    else:
+        mode, lines, _, done = incremental(bare, agents, args.since)
+        print(f"【状态】{mode}", flush=True)
+        for s in lines:
+            print(s, flush=True)
+        if done:
+            print(f"【分析已结束】result.md: {result_path(base)}",
+                  flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        # 管道消费者提前关闭（如 `| head` 截断）：静默退出，不打印 traceback
+        # ——viewer 是工具，被主 pi/wrapper 管道消费时输出截断是正常场景。
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        sys.exit(0)