pi-multi-viewers 0.5.1 → 0.6.0

package/AGENTS.md

@@ -28,8 +28,9 @@ human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
 scripts/mv.sh        稳定入口 shim（exec mv_cli.py；路径被 prompt/README 引用）
 scripts/pi-probe.sh  LLM 探针（跑 pi + 登记新 session → 残留检查器可追溯）
 scripts/check-residue.sh  残留检查（session/进程/目录三类；增删 scripts/ 时同步本节）
-mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say）
-prompts/multi-viewers.md  /multi-viewers 入口（视角设计三原则 + 审核闸门）
+mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say/viewers）
+prompts/multi-viewers.md  /multi-viewers 分析入口（审核闸门；视角原则引 README，不复述）
+prompts/multi-viewers-setup.md  /multi-viewers-setup 建视角入口（建议→你定→落盘→给审）
 extensions/multi-viewers-say/  /multi-viewers-say 插话（registerCommand，零 LLM）
 docs/design.md       设计文档（fork 源模式与规模口径 + 决策记录）
 package.json         npm 包 pi-multi-viewers（pi.prompts 注册；**版本号唯一事实源**）
@@ -229,7 +230,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 
 ## 安装/发版状态（2026-09-11）
 
-- **当前形态**：prompt × 1（multi-viewers，开发机已注册可用）+
+- **当前形态**：prompt × 2（multi-viewers 分析 / multi-viewers-setup 建视角）+
   extension × 1（multi-viewers-say 插话：零 LLM，直接 spawn human_sayer.py；
   目录发现 = `<cwd>/mv-<sessionId>-*` 最新——**无兜底**：未匹配即报错
   rc 1，需显式传目录）

package/README.md

@@ -68,11 +68,12 @@ ls ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh
 ## 用法
 
 ```
-/multi-viewers "<主题>"        # prompt 入口（推荐；视角来自 viewers/）
+/multi-viewers "<主题>"        # 分析入口（推荐；视角来自 viewers/）
+/multi-viewers-setup          # 建视角入口（交互式：先建议 → 你定 → 落盘 → 给你审）
 /multi-viewers-say "<文本>"    # 插话（extension：零 LLM 直接写入 human 消息）
 ```
 
-两个 pi 命令入口（视角/主题走 prompt，插话走 extension——插话是"本地命令
+三个 pi 命令入口（分析/建视角走 prompt，插话走 extension——插话是"本地命令
 执行"，不需要经过 LLM）。
 
 **目录可以省略**：`--view`/`--say`/`--status`/`--report`/`--wait`/`--cleanup`
@@ -108,10 +109,15 @@ scripts/mv.sh --say "<文本>"                   # 插话（命令行形态；pi
 scripts/mv.sh --status                        # 状态 + 路径（取值与含义以该命令输出为准）
 scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM/档位对照；冷路径，不持久化）
 scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存到 <dir>-result.md）
+scripts/mv.sh --viewers                       # 列出+校验当前项目 viewers/（只读；建视角时用）
 ```
 
 ## 视角文件写什么（`viewers/<视角名>.md`）
 
+建视角**推荐**走 `/multi-viewers-setup`（交互式：先给候选建议 → 你定建哪几个 →
+落盘 → 展示给你审）；也可以手写。写完用 `scripts/mv.sh --viewers` 自查（列出并
+用代码判据校验名字与空正文）。
+
 一个视角文件 = **一份视角说明**，纯内容、无格式要求（无 frontmatter、
 无需标题，**文件名就是全部元数据**）。三个要点（措辞经实验验证）：
 

package/mv_cli.py

@@ -28,6 +28,8 @@ import subprocess
 import sys
 from datetime import datetime
 
+import spec_gen  # --viewers 复用其单一判据（列举/名字/集合校验）
+
 HERE = os.path.dirname(os.path.abspath(__file__))
 PYTHON = os.environ.get("PYTHON") or "python3"
 START_DISCUSSION = os.path.join(HERE, "start_discussion.py")
@@ -49,6 +51,7 @@ USAGE = f"""用法:
   {PROG} --cleanup [dir]
   {PROG} --view    [dir] [--since <ref>]
   {PROG} --say     [dir] "<文本>"
+  {PROG} --viewers                           # 列出并校验当前项目的 viewers/（只读；建视角时用）
 
 消费命令的 <dir> 可省略（自动发现本 session 当前分析——按 cwd 下
 mv-<PI_SESSION_ID>-* 最新；无匹配则报错要求显式传目录）
@@ -67,10 +70,23 @@ human 通道:
 
 def fail(msg):
     """错误出口（沿用 bash 约定：`错误: ` 前缀 + stderr + rc 1）。"""
+    sys.stdout.flush()  # 已打印的正常输出先落地（stderr 无缓冲，否则会插到前面）
     print(f"错误: {msg}", file=sys.stderr)
     raise SystemExit(1)
 
 
+def fail_verbatim(msg):
+    """错误文本**自带 `错误: ` 前缀**（来自 spec_gen 的单一判据）→ 原样输出。
+
+    与 fail() 的差别只是前缀归属：判据的实现方（spec_gen）负责文案与前缀
+    （`start_discussion` 同样 `print(err)` 原样输出）；再包一层会变成
+    "错误: 错误: …"（实测踩过）。
+    """
+    sys.stdout.flush()
+    print(msg, file=sys.stderr)
+    raise SystemExit(1)
+
+
 # ---------------------------------------------------------------
 # 目录参数：解析（显式优先 / 省略则自动发现）与校验
 # ---------------------------------------------------------------
@@ -127,6 +143,50 @@ def _call(cmd):
 # 消费命令
 # ---------------------------------------------------------------
 
+def cmd_viewers(args):
+    """列出并校验**当前项目**的 `viewers/`（只读）。
+
+    为什么需要它：视角是**长期资产**，创建/检查它的时刻通常**还没有任何分析
+    目录**（消费命令的目录自动发现对此不适用——它找的是 mv-<sid>-*）。判据全部
+    复用 `spec_gen` 的单一实现（列举 `list_agent_md` / 名字 `check_agent_name` /
+    集合 `viewer_set_error`），这一层不另写一套规则。
+
+    数量不足（<2）在这里是**提示**不是错误：建 1 个是合法的中间状态，只有启动
+    一次分析时才要求 ≥2（那条判据仍由 `viewer_set_error` 独占）。
+    """
+    if args:
+        fail(f"未知参数: {' '.join(args)}（--viewers 不接受参数——只检查项目 cwd 的 viewers/）")
+    vdir = os.path.join(os.getcwd(), "viewers")
+    if not os.path.isdir(vdir):
+        fail(f"未找到 {vdir}——视角文件放在项目 cwd 的 viewers/<视角名>.md"
+             f"（文件名即视角名；可跑 /multi-viewers-setup 交互式建立）")
+    names, _briefs, empty = spec_gen._discover_viewers(vdir)
+    if not names:
+        fail(f"{vdir} 下没有 *.md——文件名即视角名（如 viewers/效率.md）")
+    empty_names = {n for n, _why in empty}
+    print(f"[viewers] {vdir}", flush=True)  # 与 stderr 的错误行保序（管道下也如此）
+    for n in names:
+        notes = []
+        name_err = spec_gen.check_agent_name(n)
+        if name_err:
+            notes.append(f"文件名非法：{name_err}")
+        if n in empty_names:
+            notes.append("空：没有视角内容")
+        suffix = f"（{'；'.join(notes)}）" if notes else ""
+        print(f"  {n}.md{suffix}")
+    err = spec_gen.validate_participants(names)
+    if err:
+        fail_verbatim(err)
+    if empty:
+        fail_verbatim(spec_gen.viewer_set_error(names, empty))
+    gap = spec_gen.viewers_count_gap(names)
+    if gap:
+        print(f"  校验：{gap}（建 1 个是合法的中间状态）")
+        return 0
+    print(f"  校验：通过（{len(names)} 个视角，名字与内容均合法）")
+    return 0
+
+
 def cmd_status(args):
     d = _dir_only("--status", args)
     return _call([PYTHON, START_DISCUSSION, "--dir", d, "--status"])
@@ -341,6 +401,8 @@ def main(argv=None):
         if not rest:
             fail("--start 需要 spec 目录参数")
         return cmd_start(rest[0], rest[1:])
+    if cmd == "--viewers":
+        return cmd_viewers(rest)
     if cmd == "--status":
         return cmd_status(rest)
     if cmd == "--report":

package/package.json

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

package/prompts/multi-viewers-setup.md

@@ -0,0 +1,55 @@
+---
+description: 建立多视角分析的 viewers/ 视角文件（交互式：先建议 → 你定 → 落盘 → 给你审）
+---
+
+# Multi-Viewers Setup（建立视角文件）
+
+这是**建立视角资产**的流程命令，不是分析内容。`viewers/<视角名>.md` 是**长期资产**
+（写好长期复用）。本命令**只新建、不修改已有视角**。
+
+## 第 1 步：先看项目，再提**建议**（不落盘）
+
+机械地读项目（`README.md` / `AGENTS.md` / 代码结构）——据此给出 **3–5 个候选视角**，
+每个一行：
+
+    1. <名字> —— <一行镜头>（与其它候选怎样互补/对立）
+
+- 这一步**只提议**：不建文件、不改任何东西
+- 名字：中文、短（≤32 字符）、不含空白与路径分隔符、**不要用 `human`**（保留名）
+- 建几个**由用户决定**（只建 1 个也行）
+
+**然后结束本回合，等用户输入。**
+
+## 第 2 步：等用户决定
+
+用户会告诉你建哪几个（可能只有一个、也可能点名不在候选里的）。**以用户输入为准**；
+若某个视角该用什么镜头没说清 → **问一句**，不要替他定。
+
+## 第 3 步：按用户输入建文件（只新建）
+
+写之前**先读 `README.md` 的「视角文件写什么」节**（唯一事实源：三个要点 + 正误对照 +
+命名规则）。要点：
+
+- 纯内容、无 frontmatter、无标题——**文件名就是全部元数据**
+- 必含三条：① **单一 lenses**（所有观点必须从该视角出发）② **不越界**（其它视角由
+  别的参与者负责；**不要**列举是哪几个——参与者会变，列举会过期）③ **交锋义务**
+  （对其它视角的观点可认同或反驳，但要用本视角的论据）
+- **只写视角本身**：身份（"你是 X"）、参与者名单、消息格式、独立参与者纪律都由脚本
+  生成，**不要写进文件**
+
+写完跑一次只读检查（会列出视角并用代码判据校验名字与空正文）：
+
+```bash
+~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh --viewers
+```
+
+**已有同名文件 → 不覆盖**：告诉用户"该视角已存在"，停下等他决定（改名，或他明确
+要求改动）。
+
+## 第 4 步：展示，等审阅
+
+把每个新建文件的**路径 + 全文**展示给用户，请他提修改意见或确认：
+
+- 有意见 → 改 → **再展示**（反复直到他确认）
+- 确认后一行交接：视角已建好（启动一次分析至少需要 2 个视角），接下来
+  `/multi-viewers "<主题>"` 即可

package/prompts/multi-viewers.md

@@ -28,8 +28,8 @@ argument-hint: '"<主题>"'
 
 **这条命令非零退出 → 说明 spec 生成失败**（通常是项目缺可用视角：未建
 `viewers/`、视角少于 2 个、或视角文件为空）。此时**停下来问用户**，不要
-自己选——读报错原文搞清原因，建议他按下面的"视角设计原则"补
-`viewers/<视角名>.md`（建好后再重跑本步骤）。
+自己选——读报错原文搞清原因，让他跑 `/multi-viewers-setup`（交互式建视角），
+建好后再重跑本步骤。
 
 ### 2. 编辑并请用户审核 spec
 
@@ -48,20 +48,11 @@ argument-hint: '"<主题>"'
 
 然后**展示 spec 路径，明确请用户查看/编辑**——用户确认"继续"才执行第 3 步。
 
-## 视角设计原则（建 viewers/*.md 或临时 agents/X.md 时必读）
+## 视角设计原则
 
-视角之间**互补或对立都可以**——对立产生的分歧正是多视角分析的价值。
-每个视角任务书必须包含：
-
-1. **单一 lenses**：明确该 agent 用什么角度看（效率/简单化/安全/……），
-   要求"所有观点必须从该视角出发"
-2. **不越界**："其它视角由别的参与者负责，你不要越界展开"（**不要**列举
-   具体是哪几个视角——参与者会变，列举会过期）
-3. **交锋义务**："对其它视角的观点可以认同或反驳，但要用本视角的论据"
-
-**只写视角本身**：身份（"你是 X"）、参与者名单、消息格式、独立参与者
-纪律都由脚本生成（agent 名 = 文件名，单一来源）——任务书里**不要写**，
-否则重复且易漂移。
+要建或按场微调 `viewers/*.md`、`agents/X.md` 时，**先读 `README.md` 的
+「视角文件写什么」节**（三个要点 + 正误对照 + 命名规则）——那里是唯一事实源，
+本节不再复述以免漂移。
 
 ### 3. 启动分析
 

package/spec_gen.py

@@ -447,6 +447,19 @@ def validate_participants(participants):
     return None
 
 
+def viewers_count_gap(names, where="viewers/"):
+    """视角数量不足的**事实句**（不带"错误:"前缀）→ 或 None。
+
+    与 viewer_set_error 共用同一句话（那里把它包成错误）：差别只在**场景语义**——
+    prepare/start 时数量不足 = 不能启动（错误）；建视角时 1 个是**合法中间状态**
+    （只读检查 `mv.sh --viewers` 把它当提示，不判错）。
+    """
+    if len(names) < 2:
+        return (f"{where} 下仅发现 {len(names)} 个视角"
+                f"（{', '.join(names)}）——多视角分析至少需要 2 个")
+    return None
+
+
 def viewer_set_error(names, empty, where="viewers/"):
     """viewers 集合级校验（**唯一实现**）：空正文视角 + 至少 2 个。
 
@@ -461,10 +474,8 @@ def viewer_set_error(names, empty, where="viewers/"):
         detail = "、".join(f"{where}{n}.md（{why}）" for n, why in empty)
         return (f"错误: {detail}——视角任务书不能为空"
                 f"（写清该视角用什么 lenses 看分析对象）")
-    if len(names) < 2:
-        return (f"错误: {where} 下仅发现 {len(names)} 个视角"
-                f"（{', '.join(names)}）——多视角分析至少需要 2 个")
-    return None
+    gap = viewers_count_gap(names, where)
+    return f"错误: {gap}" if gap else None
 
 
 def _discover_viewers(viewers_dir):