pi-multi-viewers 0.3.0 → 0.5.0

package/scripts/pi-probe.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+#
+# pi-probe.sh —— LLM 探针（把临时 pi 运行变成**可追溯、经同意的测试产物**）
+#
+# 它管三件事（都是吃过的教训）：
+#
+# 1. **闸门：没有当次同意就不跑**（2026-09-13 教训）
+#    我在未征得用户同意的情况下连跑 6 个真实 pi 进程（合计 ~9.5 分钟，其中一个
+#    458s），理由是"在后台跑、不占用户终端"。判据本应是**预估时长**（用户规则：
+#    秒级冒烟免批；分钟级/多轮必须当次确认），且**不因后台运行而豁免**。
+#    现在：不带 `--approved "<凭据>"` 直接**拒绝执行**并提示先去问。
+#
+# 2. **登记：跑过的 LLM 运行留下账本**
+#    `~/.pi/pi-multi-viewers-llm-runs.log` 每行一次运行：起止时间、时长、退出码、
+#    凭据、命令摘要。汇报时给账本，不靠记忆。
+#
+# 3. **收尾提醒：跑完先汇报，再决定下一步**
+#    结束时打印一行显式提醒——2026-09-13 的第二个错误正是"跑完没汇报就接着跑
+#    第二批实验"。
+#
+# 另外它把新建的 session 登记进 `~/.pi/pi-multi-viewers-test-sessions.log`
+# （与 build_bootstrap 同一份），使 check-residue 能判定归属（否则白名单 cwd
+# 下的探针 session 完全不可见）。
+#
+# 用法:
+#   ./scripts/pi-probe.sh --approved "用户 2026-09-13 15:20 同意跑 AFT 隔离实验" \
+#       --print "ok"
+#   ./scripts/pi-probe.sh --approved "..." --no-extensions --print "ok"
+#
+# 退出码 = pi 的退出码（闸门拒绝时为 2）。
+set -u
+
+SESS_DIR="$HOME/.pi/agent/sessions"
+REGISTRY="$HOME/.pi/pi-multi-viewers-test-sessions.log"
+LEDGER="$HOME/.pi/pi-multi-viewers-llm-runs.log"
+
+usage() {
+    cat >&2 <<'EOS'
+用法: pi-probe.sh --approved "<凭据>" [pi 参数...]
+
+  --approved "<凭据>"   必填：用户**当次**同意的凭据（原话/时间/授权范围）。
+                        没有它就说明还没问——先去问，不要绕过这里直接调 pi。
+
+判据（用户规则）：预估**时长**——秒级冒烟免批；预计 ≥30s、多轮唤醒、
+整场分析一律**当次**确认，且不因"后台跑、不占用户终端"豁免。
+EOS
+}
+
+APPROVED=""
+if [ "$#" -gt 0 ] && [ "$1" = "--approved" ]; then
+    APPROVED="${2:-}"
+    shift 2 2>/dev/null || true
+fi
+if [ -z "$APPROVED" ]; then
+    echo "拒绝执行：没有 --approved（= 未取得用户当次同意）。" >&2
+    usage
+    exit 2
+fi
+if [ "$#" -eq 0 ]; then
+    echo "拒绝执行：缺少 pi 参数。" >&2
+    usage
+    exit 2
+fi
+
+cmd_brief="pi $*"
+
+BEFORE="$(mktemp)"
+AFTER="$(mktemp)"
+trap 'rm -f "$BEFORE" "$AFTER"' EXIT
+find "$SESS_DIR" -name '*.jsonl' -print 2>/dev/null | sort > "$BEFORE"
+
+T0=$(date +%s)
+pi "$@"
+rc=$?
+T1=$(date +%s)
+
+# 账本（运行即登记：时长 / 退出码 / 凭据 / 命令摘要）
+python3 - "$LEDGER" "$T0" "$T1" "$rc" "$APPROVED" "$cmd_brief" <<'PYEOF'
+import json, sys
+from datetime import datetime, timezone
+ledger, t0, t1, rc, approved, cmd = sys.argv[1:7]
+rec = {
+    "started": datetime.fromtimestamp(int(t0), timezone.utc).isoformat(),
+    "seconds": int(t1) - int(t0),
+    "rc": int(rc),
+    "approved": approved,
+    "cmd": cmd[:400],
+}
+with open(ledger, "a", encoding="utf-8") as f:
+    f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+print(f"[pi-probe] 账本已记：{rec['seconds']}s rc={rec['rc']} | 同意凭据：{approved[:60]}")
+PYEOF
+
+# session 登记（归属判定用）
+find "$SESS_DIR" -name '*.jsonl' -print 2>/dev/null | sort > "$AFTER"
+NEW=$(comm -13 "$BEFORE" "$AFTER")
+if [ -n "$NEW" ]; then
+    echo "$NEW" | while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        python3 - "$f" "$REGISTRY" <<'PYEOF'
+import json, os, sys
+from datetime import datetime, timezone
+path, registry = sys.argv[1], sys.argv[2]
+sid = cwd = ""
+with open(path, encoding="utf-8") as f:
+    for line in f:
+        try:
+            ev = json.loads(line)
+        except ValueError:
+            continue
+        if ev.get("type") == "session":
+            sid = ev.get("id") or ""
+            cwd = ev.get("cwd") or ""
+            break
+rec = {
+    "created": datetime.now(timezone.utc).isoformat(),
+    "session_id": sid,
+    "path": os.path.abspath(path),
+    "cwd": cwd,
+    "origin": "pi-probe",
+}
+with open(registry, "a", encoding="utf-8") as f:
+    f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+print(f"[pi-probe] session 已登记: {path}")
+print(f"[pi-probe]   session_id={sid} cwd={cwd}（用完删掉该文件）")
+PYEOF
+    done
+else
+    echo "[pi-probe] 未新建 session（用了 --session/--session-id 续接既有会话？）"
+fi
+
+# 收尾提醒（2026-09-13 教训：跑完先汇报，别接着跑下一批）
+echo "[pi-probe] ⚠ 先把本次结果汇报给用户并停下等他指示——不要连续追加第二批实验。"
+exit "$rc"

package/spec_gen.py

@@ -17,12 +17,11 @@ import sys
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 TPL_DIR = os.path.join(HERE, "templates")
-PI_AGENT_DIR = os.environ.get("PI_CODING_AGENT_DIR",
-                             os.path.expanduser("~/.pi/agent"))
+# pi agent 目录的**单一实现**在 meeting_fs.pi_agent_dir()（F9：此前两处各拼一次）
 MAX_AGENT_NAME_LEN = 32
 
 import meeting_fs
-from meeting_fs import run_git, DEFAULT_STALL_TIMEOUT
+from meeting_fs import run_git, DEFAULT_STALL_TIMEOUT, DEFAULT_THINKING
 
 
 def _join_model_ref(provider, model_id):
@@ -56,7 +55,7 @@ def _default_model():
     获取失败（pi 不可用/无 settings）→ 返回 None。
     """
     try:
-        with open(os.path.join(PI_AGENT_DIR, "settings.json")) as f:
+        with open(os.path.join(meeting_fs.pi_agent_dir(), "settings.json")) as f:
             cfg = json.load(f)
         provider = cfg.get("defaultProvider") or ""
         model = cfg.get("defaultModel") or ""
@@ -123,7 +122,7 @@ def pi_sessions_dir(cwd):
     AGENTS.md 明言"编码错一根横线 = 静默解析不到"——风险点不应复制。
     """
     enc = "--" + cwd.strip("/").replace("/", "-") + "--"
-    return os.path.join(PI_AGENT_DIR, "sessions", enc)
+    return os.path.join(meeting_fs.pi_agent_dir(), "sessions", enc)
 
 
 def current_session_file():
@@ -276,24 +275,27 @@ def gen_spec_skeleton(spec_dir, participants, topic=None, background=None,
                 "本行是说明行，不会注入。\n\n")
         if background:
             f.write(background + "\n")
-    # models.md（用户 8024/9204/9271：预列各 agent，每行 agent名: model，
-    # variant 默认 max 隐式——只有非 max 才写 `, variant`，日常更简洁；
-    # model/thinking 预填主 pi 当前值，用户少改一个文件）
+    # models.md（用户 8024/9204/9271：预列各 agent，每行 agent名: model,
+    # variant；model/thinking 预填主 pi 当前值，用户少改一个文件）
+    # **两个槽都永远显式写出**（含探测失败的路径）：variant 槽留空会静默落到
+    # DEFAULT_THINKING，而 spec 文件表面完全正常（甚至更"干净"）——意图与
+    # 生效值之间没有留痕（e2e17 评审 §7.3）。探测失败另打一行可见提示。
     pm, pt = _detect_pi_model_thinking()
+    variant = pt or DEFAULT_THINKING
     with open(os.path.join(spec_dir, "models.md"), "w") as f:
-        lines = ["# models.md——模型配置（可选）。每行：agent名: model[, variant]。"
-                 "model 默认 default，variant 默认 max（只有不用 max 才写 variant）。"
+        lines = ["# models.md——模型配置（可选）。每行：agent名: model, variant。"
+                 "model 写 default = 继承本机默认；variant 不写 = "
+                 f"{DEFAULT_THINKING}（**两个槽都显式写出**，一眼可见）。"
                  "本行是说明行，不会注入。"]
         for p in participants:
-            if pm and pt:
-                lines.append(f"{p}: {pm}, {pt}")
-            elif pm:
-                lines.append(f"{p}: {pm}")
-            elif pt:
-                lines.append(f"{p}: default, {pt}")
-            else:
-                lines.append(f"{p}: default")
+            lines.append(f"{p}: {pm or 'default'}, {variant}")
         f.write("\n".join(lines) + "\n")
+    if not pt:
+        # 探测失败**可见**（不是静默取档）：打印在使用者能看到的地方，
+        # 不阻断（终端直用时 PI_* 环境变量本就不存在，报错会断掉合法路径）。
+        print(f"[spec-gen] 未探测到主 pi 的 thinking 档位——models.md 用默认 "
+              f"{DEFAULT_THINKING}（如需其它档位请直接编辑该文件）",
+              file=sys.stderr)
     # agents/X.md 占位 + .order（仅显式 --agents 时；快照路径的 .order
     # 由 _snapshot_viewers 写入，此处不得重写）
     if participants and not viewers_dir:
@@ -367,7 +369,8 @@ def gen_question(topic, stances, background, questions):
     return "\n".join(lines)
 
 
-def gen_protocol(topic, participants, max_meeting, max_rr, pure=False,
+def gen_protocol(topic, participants, max_meeting, max_rr,
+                 extension_policy=meeting_fs.DEFAULT_EXTENSION_POLICY,
                  result_writer=None,
                  stall_timeout=DEFAULT_STALL_TIMEOUT,
                  fork_source=None, fork_cwd=None,
@@ -385,8 +388,12 @@ def gen_protocol(topic, participants, max_meeting, max_rr, pure=False,
         "stallTimeoutSeconds": stall_timeout,
         "commitPolicy": "one-message-per-commit",
     }
-    if pure:
-        proto["pure"] = True
+    # 显式写出扩展策略（值域与默认值的家在 meeting_fs；此处只写选定值）。
+    # 非法值就地报错（不落盘半成品）——与 forkMode 同款：配置错误不进运行时
+    if extension_policy not in meeting_fs.EXTENSION_POLICIES:
+        raise ValueError(f"非法 extension_policy: {extension_policy!r}"
+                         f"（合法值: {'/'.join(meeting_fs.EXTENSION_POLICIES)}）")
+    proto["extensionPolicy"] = extension_policy
     if fork_source:
         # fork 模式（多视角）：首唤挂载主 session + cwd=主项目
         # forkMode 取值域与默认值的定义在 meeting_fs（FORK_MODES /

package/start_discussion.py

@@ -3,7 +3,8 @@
 
 用法：
   python3 start_discussion.py --dir mymeet --topic "主题" --agents a,b \
-      [--stances '{"a": "立场1", "b": "立场2"}'] [--start] [--pure] \
+      [--stances '{"a": "立场1", "b": "立场2"}'] [--start] \
+      [--extension-policy none|mc-tools|all] \
       [--models '{"a": "provider/model"}'] [--max-meeting 10] [--max-rr 7]
 
 复杂内容用 spec 规格目录（设计 16，与 CLI 内容参数互斥）：
@@ -70,8 +71,11 @@ def _spec_models(spec_dir, participants):
     """解析 models.md（容错，用户 8024/9204 定）：返回 {agent: (model, variant)}。
 
     每行格式：`agent名: model, variant`（model 与 variant 逗号分隔）。
-    - model 缺省/'default' → None（创建时填本机默认模型）
-    - variant 缺省/'default'/'max' → 'max'（默认档，专业用户才改）
+    - model 缺省/'default' → None（创建时填本机默认模型）——`default`
+      这个别名**只在 model 槽有意义**
+    - variant 缺省 → DEFAULT_THINKING；**没有 `default` 别名**（同词在相邻
+      两行反义会让读者必错；且空已是缺省，别名不增加表达力）——写了 `default`
+      就按原值透传给 pi（可见失败，而非静默重解释）
     容错：空行/无 ':'/agent 不在 participants → 跳过；单字段行只有 model。
     规则：第一行说明跳过（_spec_read）。
     """
@@ -93,8 +97,13 @@ def _spec_models(spec_dir, participants):
         parts = [p.strip() for p in rest.split(",")]
         model = parts[0] if parts and parts[0] else ""
         variant = parts[1] if len(parts) > 1 else ""
+        # `default` **只在 model 槽有意义**（= 继承本机）。variant 槽不做
+        # 同名别名（e2e17 评审 §7.2：相邻两行同词反义——model 的 default
+        # = 继承，variant 的 default = max，按上一行直觉读下一行必错）；
+        # 且别名并不增加表达力：空 = max 已是缺省。写 `default` 不再是
+        # 别名 → 原值传给 pi（可见的失败，而不是静默重解释成 max）。
         m = None if (not model or model == "default") else model
-        v = "max" if (not variant or variant == "default") else variant
+        v = variant or meeting_fs.DEFAULT_THINKING
         out[agent] = (m, v)
     return out
 
@@ -303,21 +312,23 @@ def setup_environment(args, participants, base, spec_dir=None,
                    for p in participants}
     agent_extra = {k: v for k, v in agent_extra.items() if v}
     # models：spec 模式从 models.md 读（自包含，{agent: (model, variant)}），
-    # CLI --models 已互斥（{agent: model} 旧格式——variant 用默认 max）
+    # CLI --models 已互斥（{agent: model} 旧格式——variant 用默认档）
     if spec_dir:
         models = _spec_models(spec_dir, participants)
     else:
-        models = {p: (m, "max") for p, m in (args.models or {}).items()}
-    # default 模型 → 创建时实时获取 Pi 默认模型填入：
-    # pi-agent.json 带 model 后，meeting_loop 才会传 --model；
-    # 骨架期 models.md 仍写 default（--spec-gen 不获取），创建时（--spec）
-    # 才解析。运行期固化不变（环境自包含）。
-    if spec_dir:
-        dm = _default_model()
-        if dm:
-            for p in participants:
-                if p not in models or models[p][0] is None:
-                    models[p] = (dm, models.get(p, (None, "max"))[1])
+        models = {p: (m, meeting_fs.DEFAULT_THINKING)
+                  for p, m in (args.models or {}).items()}
+    # 归一：每个 participant 都有 (model, variant) 条目，**此后只读**——
+    # 此前 :320 补默认模型与 :384 写 pi-agent.json 各自再写一遍
+    # `models.get(p, (None, "max"))`（同层同义重复，值两处声明，e2e17
+    # 评审 §7.10）。
+    # default 模型 → 创建时实时获取 Pi 默认模型填入：pi-agent.json 带
+    # model 后，meeting_loop 才会传 --model；骨架期 models.md 仍写 default
+    # （--spec-gen 不获取），创建时（--spec）才解析。运行期固化不变。
+    dm = _default_model() if spec_dir else None
+    for p in participants:
+        m, v = models.get(p, (None, meeting_fs.DEFAULT_THINKING))
+        models[p] = (m or dm, v)
     # stance_ref（agent 定义"立场见 question.md"提示）：spec 模式一律保留
     # （设计 16.6：无法程序判断 question.md 有无立场节 → 一律提示；
     # 互斥下 CLI stances 必为 None，传占位 dict 触发生成）
@@ -340,7 +351,7 @@ def setup_environment(args, participants, base, spec_dir=None,
     # 共享配置（work-a 提交，setup commit 进 bare）
     with open(os.path.join(wa, "protocol.json"), "w") as f:
         json.dump(gen_protocol(spec_topic or args.topic, participants, args.max_meeting,
-                               args.max_rr, args.pure, args.result_writer,
+                               args.max_rr, args.extension_policy, args.result_writer,
                                args.stall_timeout,
                                fork_source=getattr(args, "fork_source", None),
                                fork_cwd=os.getcwd(),
@@ -381,14 +392,14 @@ def setup_environment(args, participants, base, spec_dir=None,
         with open(os.path.join(workdir, "AGENTS.md"), "w") as f:
             f.write(gen_agents_md(args, p, participants, spec_background,
                                  main_pi_cwd=os.getcwd()))
-        mv = models.get(p, (None, "max"))
+        mv = models[p]        # 归一后必有条目（见上方归一循环）
         with open(os.path.join(workdir, ".pi/agent", f"{p}.md"), "w") as f:
             f.write(gen_agent_def(p, participants, {p: mv[0]} if mv[0] else None,
                                   stances_arg, agent_extra.get(p)))
         with open(os.path.join(workdir, "pi-agent.json"), "w") as f:
             json.dump({
                 "model": mv[0] or "",
-                "thinking": mv[1] if mv[1] else "max",
+                "thinking": mv[1] or meeting_fs.DEFAULT_THINKING,
                 "prompt_file": f".pi/agent/{p}.md",
             }, f, indent=2, ensure_ascii=False)
 
@@ -409,7 +420,8 @@ def setup_environment(args, participants, base, spec_dir=None,
     rw = args.result_writer or participants[-1]
     print(f"[setup] 环境就绪: {base}（{len(participants)} agents: {', '.join(participants)}）")
     print(f"[setup] resultWriter={rw}, maxMeeting={args.max_meeting}, maxRR={args.max_rr}, "
-          f"立场={'有' if (args.stances or spec_dir) else '无'}, pure={args.pure}")
+          f"立场={'有' if (args.stances or spec_dir) else '无'}, "
+          f"extensionPolicy={args.extension_policy}")
 
 
 def _preserve_result_md(base):
@@ -501,7 +513,7 @@ from spec_gen import (  # noqa: F401
     viewer_set_error, gen_agents_md, gen_protocol,
     pi_sessions_dir, current_session_file, _join_model_ref,
     _default_model, _detect_pi_model_thinking, resolve_fork_source,
-    PI_AGENT_DIR, MAX_AGENT_NAME_LEN,
+    MAX_AGENT_NAME_LEN,
 )
 from observability import (  # noqa: F401
     _loop_pids, _loops_alive, check_status, build_report,
@@ -539,7 +551,13 @@ def main():
                              "protocol.json，各 agent 首唤由本地生成 fork "
                              "源挂载主上下文；不传 = 从主 pi 环境自动解析"
                              "（PI_SESSION_ID；解析失败明确报错）")
-    parser.add_argument("--pure", action="store_true", help="--pure 模式（禁外部插件）")
+    parser.add_argument(
+        "--extension-policy",
+        choices=list(meeting_fs.EXTENSION_POLICIES),
+        default=meeting_fs.DEFAULT_EXTENSION_POLICY,
+        help="agents 的扩展策略：mc-tools=默认，只要 MC 的只读检索工具 "
+             "ctx_search（缺 MC 时可见降级为零扩展）；none=零扩展（零依赖）；"
+             "all=走 pi 默认发现")
     parser.add_argument("--start", action="store_true", help="创建后启动讨论")
     parser.add_argument("--skip-setup", action="store_true",
                         help="跳过环境生成，只启动已有环境（需 --dir）")
@@ -691,12 +709,13 @@ def main():
             workdir = os.path.join(base, f"work-{p}")
             cmd = [sys.executable, os.path.join(base, "meeting_loop.py"),
                    workdir, p]
-            if args.pure:
-                cmd.append("--pure")
+            # 扩展策略**不转发**：协议字段（gen_protocol 恒写）是唯一权威，
+            # 转发只会多一条通道（S3）。例外语义已写进 decision 20：旧协议
+            # 目录（无该字段）按默认档启动。
             # 配额（max-meeting/max-rr/stall-timeout）是环境属性：创建时
             # 固化在 protocol.json，启动继承（loop 读 protocol 优先）。
             # 不传 CLI —— 避免无条件覆盖 protocol.json 的固化值
-            # （审核 C1：配额单一事实源；与 pure 处理一致）
+            # （审核 C1：配额单一事实源；与 extension-policy 处理一致）
             with open(os.path.join(base, f"loop-{p}.log"), "w") as f:
                 procs.append(subprocess.Popen(cmd, stdout=f,
                                               stderr=subprocess.STDOUT,

package/templates/spec-readme.md.tpl

@@ -42,14 +42,19 @@ fork 机制已让每个 agent 携带发起分析时的对话上下文（默认 b
 
 - 分析只聚焦某些方面（"不讨论 API 设计"）
 - 已知的硬约束（"必须保持向后兼容"）
-- 用户指定的优先级（"性能问题优先级最高"）
+- 用户指定的优先级（"效率问题优先级最高"）
 
 没有就留空。
 
 ## models.md —— 模型配置（可选）
 
-每行：`agent名: model[, variant]`。model 默认 default（继承本机默认），
-variant 默认 max。只有不用默认/-max 时才需要改。
+每行：`agent名: model, variant`（**两个槽都显式写出**，一眼可见本场跑在
+什么模型/档位上）。model 写 `default` = 继承本机默认；variant 不写 =
+`max`。想换档位（如 `high`）改这一行即可——**逐 agent 一行**，可以只改
+某一个视角。
+
+> 这里写的就是**声明值**；实际生效值由 pi 解析（它自己的优先级链）。
+> `--report` 会把声明值与 session 里的生效值对照列出。
 
 ## agents/X.md —— 视角任务书（每个 agent 一个）
 
@@ -64,7 +69,7 @@ variant 默认 max。只有不用默认/-max 时才需要改。
 
 写好视角任务书的要点（实测有效的措辞模式）：
 
-1. **单一视角**：明确写出这个 agent 用什么 lenses 看（性能/简单化/
+1. **单一视角**：明确写出这个 agent 用什么 lenses 看（效率/简单化/
    安全/成本/用户体验/……），并要求"所有观点必须从该视角出发"
 2. **不越界**：写明"其它视角由别的参与者负责，你不要越界展开"——
    实验证明这句能避免视角串味（不要列举具体是哪几个视角——
@@ -72,10 +77,15 @@ variant 默认 max。只有不用默认/-max 时才需要改。
 3. **交锋义务**：写明"对其它视角的观点可以认同或反驳，但要用本视角
    的论据"——防止附和式讨论
 
-范例（agents/性能.md 全文——身份那句由脚本加，不在正文里）：
+范例（agents/效率.md 全文——身份那句由脚本加，不在正文里；本例内容较长，
+要点是"把该视角盯住的东西逐项写明"）：
+
+    你的所有观点必须从运行效率角度出发：时间效率（一次分析从开始到收尾要
+    多久、哪些环节在吃时间、哪些等待可消除）与运行效率（不必要的计算与
+    等待、可并行而串行的部分、随规模增长的代价）。
+    能用已有数据说出"省多少、占多少比例"就说；拿不到数据就写明需要什么
+    数据，不要凭感觉下结论。
 
-    你的所有观点必须从性能角度出发：复杂度、热点、不必要的计算、扩展性。
-    如果其它视角的优化建议会显著损害性能，你应该明确反对并说明理由。
     其它视角由别的参与者负责，你不要越界展开。
     对其它视角的观点可以认同或反驳，但要用本视角的论据。