pi-multi-viewers 0.3.0 → 0.4.0

package/docs/reviews/README.md

@@ -6,8 +6,8 @@
 
 ## 为什么存档
 
-1. **机制有效性的证据**：这些报告不是模拟，是三个视角 agent（性能 / 可读性 /
-   铁律）真实读代码、交叉引用、交锋收敛的产物——报告里的问题清单确实抓到了
+1. **机制有效性的证据**：这些报告不是模拟，是三个视角 agent 真实读代码、交叉引用、
+   交锋收敛的产物（视角名随项目演化：早期 性能/可读性/铁律，2026-09-13 起 效率/简单/铁律）——报告里的问题清单确实抓到了
    真实缺陷（见下）。
 2. **决策溯源**：修复批次（commit）常引用报告中的编号（如"P0/P1/P2"），
    保留原文才能核对当时的事实与推理。
@@ -25,6 +25,11 @@
 | `2026-09-11-e2e14-observability-review.md` | 本项目可观测性自审（日志系统是否合理 + 如何监控讨论有效性） | 失败/重试不可见（provider error 零记录，实测占墙钟 11%）；耗时不可度量；token 无出口；**`--wait` 用 `glob(loop-*.log)` 兼任判定输入**；viewer 与 check_status 的 done 判据分叉；两份逐字相同的 `log()`；观测面契约在文档零命中 | 见「e2e14 修复」提交（第一批 §3.1–§3.5） |
 | `2026-09-11-e2e13-code-review.md` | 全项目代码合理性评审（第二轮，含时间流实测） | `--agents` 非法名在 spec-gen 路径炸出 traceback + 半成品；viewers/agents 校验与列举多实现（隐藏文件静默入场）；wrapper 越界检查第三方扩展配置；`--start` 静默删 spec；session 文件两套查找规则；切换叙事拼 agent 定义正文 | `fe3aa09`（R1–R8） |
 | `2026-09-10-e2e12-code-review.md` | 全项目代码合理性评审（性能 / 简单 / 铁律） | `_lock_git` 守卫 **fail-open**（锁态下 git 上溯到主项目仓库）；`pgrep -f` 自匹配；`protocol.json` 读取散落 6 处 / 3 种失败语义（含 `result_writer` 默认值求值缺陷）；`check_status` 用 `git grep` 全文误报 done；engine 直做 fs I/O；两处 git 入口加固不一致 | 见「e2e12 修复」提交（批 A/B/C） |
+| `2026-09-12-e2e17-thinking-level-analysis.md` | thinking 档位降到 `high` 对速度与质量的影响（成本模型 `d = f×S`） | 质量**无任何判据**（全仓无落点）；真杠杆是**请求数**（每请求固定成本占 47%）与 provider 失败重试（11–19%）；报告缺按谓词分组字段 | `3c49d90` |
+| `2026-09-13-e2e19-scoped-config-review.md` | 审阅「agent 进程作用域配置」（关 AFT 语义搜索） | 键名方向写反（恒写旧名 → 上游移除即静默回吐 57s）；`_strip_jsonc` **改写字符串值**；条件与副作用未文档化 | `c2be72d` |
+| `2026-09-13-e2e20-pure-run-review.md` | 审阅 `c2be72d` 的 9 条修复（**该场 agents 零扩展**） | 边界**子串**误判把 fork 历史算进本轮（报告虚高 4–8 倍，也是"Δ 合计 > 墙钟"之谜根因）；单趟 strip 让注释含引号的输入解析失败（功能回归）；Δ 口径 B 归因被证伪 | `5e02a67` |
+| `2026-09-13-e2e21-postfix-review.md` | 审阅 `5e02a67`（并验证报告口径修复） | AFT legacy 检测 4 组路径**多一层 `aft/`**（死检查 + 静默假阴性）；子串预筛是对设计的错误陈述；`n`/`sec` 分母不一致导致均值低估 | `5cc0b5e` 之后的批 |
+| `2026-09-13-e2e23-time-breakdown-analysis.md` | 一次分析的**时间构成**（哪些必要、哪些可省） | AFT / MC historian 两笔分钟级开销都不在报告里；反对"不等退出就推进"与"新增常驻机制" | `98786d6` + `c46d996` / `9deefac` |
 
 ## 环境口径（读报告时的背景）
 

package/docs/test-methodology.md

@@ -365,3 +365,55 @@ meeting 阶段有 35% 概率写 freezing，而"全员首轮 freezing"概率 = 0.
 3. **确定性优先于概率**：修复后该断言成为**不变式**（P = 0 不可能失败），
    不再依赖运气——这比"多跑几次都绿"才是证据（10 次全绿对 1.5% 概率的
    事件的置信度很低）。
+
+### 24. 探针必须经脚本跑（创建即登记），检查器输出不得过滤（2026-09-12）
+
+**背景**：一天里裸跑了 ~20 次 `pi --print`/`pi --mode json` 探针（AFT 性能
+隔离实验），清理时只清了**当前项目** session 目录，漏掉另外 3 个 cwd 的 4 个
+session。用户先发现的（"我看到不少 pi 的 session 的残留"）。
+
+**两层原因（都不是"运气差"）**：
+1. **检查器盲区**：`check-residue.sh` 的归属判定是"登记日志里有没有"，而
+   白名单（真实项目 cwd）**优先于**登记判定 → 探针跑在白名单目录时整块被
+   跳过，连报都不报（本次 4 个里就有 1 个）。
+2. **调用方式错误**（更根本）：我调用时 `grep -E "残留-2|残留-3"` —— 把
+   `[残留-1]` 整类滤掉，也不看退出码，于是"有残留"被跑成"看起来干净"。
+
+**方法（已落地）**：
+- **探针经 `scripts/pi-probe.sh` 跑**：跑完把新 session 登记进
+  `~/.pi/pi-multi-viewers-test-sessions.log`（与 `build_bootstrap` 同一份）
+  → 归属是**显式事实**，不靠 cwd 猜；跑完会打印路径（用完即删）。
+- **检查器**：登记判定**优先于白名单**；"已登记"也计入残留（验收语义 =
+  清理完毕，归属标记只决定谁来删）；末行输出
+  `[residue] session=N 进程=N 目录=N → 干净|有残留` + 退出码——**结论只在这一行**。
+- **调用纪律**：看退出码 + 那行汇总。**不得只 grep 某一类残留**（过滤一类
+  会把别的整块藏掉）；要压缩输出就 `tail -1`。
+
+**为什么不用启发式**（按文件大小/首条消息猜"是不是探针"）：与"不得用运行
+时长或粗略时间窗猜测"同一禁令——归属必须来自确定性标识（登记日志）。
+
+### 25. LLM 运行两条纪律：当次确认 + 跑完先汇报（2026-09-13）
+
+**事故**（同一天两件，都发生在我身上）：
+1. **未获同意就连跑真实 LLM**：e2e21 结束后，我为定位"收尾段占 66–78% 进程时间"
+   的目标方，直接跑了 6 个真实 pi 进程（合计 ~9.5 分钟，单个最长 **458s**），
+   理由是"在后台跑、不占用户终端"。**判据本应是预估时长**（用户规则：秒级冒烟
+   免批；分钟级/多轮/整场必须当次确认），且**"后台运行"不是豁免理由**——它照样
+   消耗用户的时间与额度预算，也照样会产生我可能据以行动的错误结论。
+2. **跑完没有先汇报就接着跑第二批**：用户明确"测试完成后须先把结果报告用户、
+   等用户看完再继续"。我却连跑两批实验，直到用户叫停。
+
+**制度（机制落点，不靠记忆）**：
+- **闸门**：`scripts/pi-probe.sh --approved "<凭据>"` —— 不带 `--approved` 直接
+  **拒绝执行**（退出码 2）并提示"先去问"。凭据写用户原话/时间/授权范围，
+  逼出"当次"这个语义（不是"之前同意过某类测试"）。
+- **账本**：每次运行落 `~/.pi/pi-multi-viewers-llm-runs.log`（起止/时长/退出码/
+  凭据/命令摘要）；汇报时**给账本**，不靠记忆。违规也可事后补记（留痕比干净重要）。
+- **收尾提醒**：脚本结束时打印"先把本次结果汇报给用户并停下等他指示——不要连续
+  追加第二批实验"——提醒落在**犯错的那个时刻**，而不是靠我事后想起来。
+- **判据（写进 AGENTS.md）**：按**预估时长**分类，不按"是否调用 LLM"；≥30s 或
+  多轮/整场 → 当次问；单次冒烟（秒级）可免批但要事后说明。e2e 讨论走 spec 审阅
+  闸门（那条路径天然经过用户确认）。
+
+**边界（诚实）**：闸门只挡 `pi-probe.sh` 这条路径——直接调 `pi` 仍可绕过。
+它的价值是让"绕过"成为**显式动作**（要故意跳过提示），而不是顺手。

package/meeting_fs.py

@@ -12,6 +12,7 @@
 
 import json
 import os
+import shutil
 import uuid
 import re
 import subprocess
@@ -50,6 +51,24 @@ def result_path(base):
 # protocol.json；engine/fake_agent 的签名默认与 CLI default 同源于此）。
 DEFAULT_STALL_TIMEOUT = 600
 
+# thinking 档位缺省值——**唯一声明点**：models.md 的 variant 槽（缺省）
+# 、CLI --models 路径、pi-agent.json 的写入与兑底都引用它。
+# 为什么是 max 而不是最便宜的档：兑底值是"没探测到就按主 pi 默认"的
+# 产物，翻到便宜侧会让"探测失败"以另一种姿态静默（e2e17 评审 §7.3）；
+# 正确的处方是**让失败可见**（探测失败时 spec_gen 打提示、spec 永远写
+# 显式档位），不是把默认值挪到便宜侧。
+DEFAULT_THINKING = "max"
+
+
+def pi_agent_dir():
+    """pi 的 agent 目录（`$PI_CODING_AGENT_DIR` 或 `~/.pi/agent`）——**单一实现**。
+
+    与 spec_gen.PI_AGENT_DIR 同规则；本模块需要它的地方（会话登记日志、
+    扩展入口解析）都走本函数，避免两处各拼一次。
+    """
+    return os.environ.get("PI_CODING_AGENT_DIR") or os.path.expanduser("~/.pi/agent")
+
+
 # ---------------------------------------------------------------
 # git 基础操作
 # ---------------------------------------------------------------
@@ -114,6 +133,12 @@ def iter_after_boundary(session_file):
     append_handoff_turns 写）。未找到边界（老产物/手工 session）→ 返回
     空迭代：**调用方按"无本轮数据"处理（n/a），不得退回全文扫描**——
     那正是修掉的口径错误（把 fork 携带的历史算成本轮）。
+    **边界按字段判定**（`type == custom_message` 且 `customType ==
+    BOUNDARY_TYPE`）——不能只看子串：主 session 历史里**可能有含该字面量的
+    普通条目**（例如引用它的 fixture 文本、讨论它的 assistant 消息），子串
+    命中即早退会让其后全部历史被当成"本轮"（e2e20 评审批实测：误判起点早
+    约 490 行 → 报告的数字虚高 ~4 倍；也是 e2e19"Δ 合计 > 进程跨度"之谜的
+    根因）。子串仅作**便宜预筛**（命中才解析 JSON），既有性能也有正确性。
     fail-open：文件不可读/JSON 坏行跳过。
     """
     seen = False
@@ -121,9 +146,16 @@ def iter_after_boundary(session_file):
         with open(session_file, encoding="utf-8", errors="replace") as f:
             for line in f:
                 if not seen:
-                    if BOUNDARY_TYPE in line:
-                        # 边界行本身不产出（它没有 message 字段）
-                        seen = True
+                    # 预筛：不含字面量的行不可能是边界（省一次 json.loads）
+                    if BOUNDARY_TYPE not in line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except ValueError:
+                        continue
+                    if (ev.get("type") == "custom_message"
+                            and ev.get("customType") == BOUNDARY_TYPE):
+                        seen = True        # 边界行本身不产出（无 message 字段）
                     continue
                 try:
                     yield json.loads(line)
@@ -534,7 +566,7 @@ def new_messages_with_meta(workdir, since_ref, me=None):
 def is_message_file(path):
     """判断路径是否为消息文件（作者/NNNN.md）。
 
-    作者目录不限 ASCII：viewers 中文视角名是产品核心（可读性/性能/…）。
+    作者目录不限 ASCII：viewers 中文视角名是产品核心（可读性/效率/…）。
     约束对齐 agent 名校验（禁 / 与空白；目录名不匹配即非消息文件——
     human/、protocol.json 等天然排除）。
     """
@@ -950,6 +982,18 @@ def build_fork_source(src_session, out_path, new_id, new_cwd,
     else:                                   # pragma: no cover
         # 值域守卫之后仍可达的只剩“新值已入 FORK_MODES 但分派未跟上”
         return 0, f"forkMode {mode!r} 尚未实现分派"
+    # **不携带旧会话的 thinking 档位条目**（三种模式统一，e2e17 评审后的
+    # 实现修正）：本场档位由 CLI 显式传入（`--thinking` 来自
+    # pi-agent.json，缺省也有 DEFAULT_THINKING 兜底 → 恒非空），旧条目
+    # 既不是本场生效值，又会让 pi **跳过**写自己的 `thinking_level_change`
+    # （pi 侧：`if (!hasThinkingEntry) append`）——于是 session 里没有"本场
+    # 生效档位"这个事实，报告无法把「声明值 vs 生效值」并列（只有旧会话的
+    # 值，在边界之前、按口径不可读）。剔除后 pi 会在边界之后补写。
+    # model_change **不剔除**：无 models.md 的路径（CLI 直用）不传 --model，
+    # pi 靠它回填主 pi 的模型——那是活配置，不是陈旧副本。
+    # 记账：配置条目**不计入** dropped（那不是上下文内容；dropped 的口径
+    # = 预算丢弃 + 规范化移除）。
+    body = [e for e in body if e.get("type") != "thinking_level_change"]
     new_header = {
         "type": "session",
         "version": header.get("version", 3),
@@ -977,7 +1021,7 @@ def build_fork_source(src_session, out_path, new_id, new_cwd,
 # 才删，未登记 = 非本流程创建（真实会话），不得删。路径与
 # scripts/check-residue.sh 的对照逻辑共享。
 SESSION_REGISTRY = os.path.join(
-    os.path.expanduser("~/.pi"), "pi-multi-viewers-test-sessions.log")
+    pi_agent_dir(), "..", "pi-multi-viewers-test-sessions.log")
 
 
 def _registry_log(session_id, out_path, cwd):

package/meeting_loop.py

@@ -4,7 +4,7 @@
 复用 meeting_engine 的唯一状态机，只注入"唤醒 pi"的 responder。
 协议逻辑（锁/配额/级联/信号）全在引擎，此处只做 LLM 交互。
 
-用法：python3 meeting_loop.py <workdir> <agent> [--pure]
+用法：python3 meeting_loop.py <workdir> <agent> [--extensions]
 （配额/超时从 protocol.json 读——单一事实源；无 CLI 覆盖）
 """
 
@@ -289,7 +289,7 @@ def _prepare_fork_session(workdir, agent, sid, fork_source, fork_cwd,
 
 
 def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
-                    session_dir, first_wake, pure, prompt,
+                    session_dir, first_wake, with_extensions, prompt,
                     fork_mode=meeting_fs.DEFAULT_FORK_MODE, topic=""):
     """组装唤醒命令（#3 拆分，e2e7 评审）：返回 (cmd, spawn_cwd)。
 
@@ -309,9 +309,17 @@ def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
     else:
         cmd = ["pi", "--mode", "json", "--session-id", sid,
                "--session-dir", session_dir]
-    if pure:
-        # Pi 的 pure 近似：关闭外部扩展/技能/prompt-template/主题加载，
-        # 保留内置工具（read/bash/edit/write）与项目内 AGENTS.md。
+    # ---- agent 进程的扩展策略（design.md 决策 20）----
+    # **默认 = 零扩展**（关扩展/技能/prompt-template/主题；保留内置工具与项目内
+    # AGENTS.md）。为什么：两类插件在**我们这种 session 形态**上都是分钟级负担，
+    # 且都在关键路径上（loop 等进程退出才继续）——
+    #   · AFT：大 session 上进程退出前多活数分钟（受控对照 445.9s → 0.5s）；
+    #   · MC：它的 historian 对"带着大段未处理历史"的 session **每次必失败并立刻
+    #     重试**（受控对照：同输入 447s → 10.3s，43 倍）。
+    # 零扩展实测（真场）：墙钟 12m31s / 每次唤醒 48.1s / 收尾≈0% / historian 0 次。
+    # 加回扩展属**显式 opt-in**（`--extensions`，协议字段 `extensions: true`），
+    # 且应有净收益账（见 design.md 决策 20 的门槛条款）。
+    if not with_extensions:
         cmd += ["--no-extensions", "--no-skills", "--no-prompt-templates",
                 "--no-themes"]
     model = cfg.get("model") or ""
@@ -333,6 +341,22 @@ def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
     return cmd, (fork_cwd or workdir)
 
 
+def _spawn_env(workdir):
+    """agent 进程的环境（Popen 的 env 是**整体替换** → 必须合并 os.environ，
+    否则丢 PATH）。
+
+    只注入 `GIT_CEILING_DIRECTORIES=<讨论目录>`：**git 上溯防护**（实现 A1）。
+    为什么需要：`_lock_git` 把 work-<agent>/.git 改名后，git 的默认行为是
+    **向上继续找仓库**——fork 模式下 cwd = 主项目，实测锁态下
+    `git rev-parse --git-dir` 从 workdir 发起会命中主项目 .git（rc=0），守卫
+    形同虚设（见 `_lock_git` docstring 的范围说明）。本进程的 argv 就是 agent
+    会话里 bash 工具所继承的环境来源。
+    （此前还注入 XDG_CONFIG_HOME 做作用域配置——随"屏蔽 AFT"整块退役。）
+    """
+    env = {**os.environ, "GIT_CEILING_DIRECTORIES": os.path.dirname(workdir)}
+    return env
+
+
 def _run_wake_proc(cmd, spawn_cwd, workdir, agent):
     """spawn + 分片等待（#3 拆分）：返回 CompletedProcess。
 
@@ -348,17 +372,12 @@ def _run_wake_proc(cmd, spawn_cwd, workdir, agent):
     # 成功）。性能实测 ≈150-200 KB/唤醒、峰值亚 MB（不构成风险）；
     # 若改为流式读取，必须让"谁读 session 头"同样显式可见（可读性保留票）。
     #
-    # GIT_CEILING_DIRECTORIES=<讨论目录>：**git 上溯防护**（实现 A1）。
-    # 本进程的 argv 就是 agent 会话里 bash 工具所继承的环境来源——
-    # 注入后，从 work-<agent> 发起的 git 不会上溯到主项目仓库。
-    # 为什么需要：_lock_git 把 work-<agent>/.git 改名后，git 的默认行为是
-    # **向上继续找仓库**——fork 模式下 cwd=主项目，实测锁态下
-    # `git rev-parse --git-dir` 从 workdir 发起会命中主项目 .git（rc=0），
-    # 守卫形同虚设（见 _lock_git docstring 的范围说明）。
-    # 注：Popen 的 env 是**整体替换**，必须合并 os.environ（否则丢 PATH）。
+    # 环境构造统一在 _spawn_env（GIT_CEILING_DIRECTORIES 的 git 上溯防护
+    # 理由见该函数；brief：本进程的 argv 就是 agent 会话里 bash 工具所继承的
+    # 环境来源，而 _lock_git 只锁 work-<agent>/.git、git 默认会向上找仓库）。
     proc = subprocess.Popen(cmd, cwd=spawn_cwd, stdout=subprocess.PIPE,
                             stderr=subprocess.PIPE, text=True,
-                            env={**os.environ, "GIT_CEILING_DIRECTORIES": base})
+                            env=_spawn_env(workdir))
     _current_proc = proc
     try:
         # 分片等待：每片检查讨论目录是否被清理（cleanup 删目录）——
@@ -387,7 +406,8 @@ def _run_wake_proc(cmd, spawn_cwd, workdir, agent):
                                        err or "")
 
 
-def wake_llm(workdir, agent, prompt, pure=False, fork_source=None, fork_cwd=None,
+def wake_llm(workdir, agent, prompt, with_extensions=False, fork_source=None,
+             fork_cwd=None,
              fork_mode=meeting_fs.DEFAULT_FORK_MODE, topic=""):
     """唤醒 pi（fork-only：首唤由本地生成 fork 源 + `--session` 打开，
     后续 `--session-id` 续接）。返回 (sessionID, returncode)。
@@ -412,7 +432,7 @@ def wake_llm(workdir, agent, prompt, pure=False, fork_source=None, fork_cwd=None
         sid = str(uuid.uuid4())
     cmd, spawn_cwd = _build_wake_cmd(workdir, agent, sid, cfg, fork_source,
                                      fork_cwd, session_dir, first_wake,
-                                     pure, prompt, fork_mode, topic)
+                                     with_extensions, prompt, fork_mode, topic)
 
     log_dir = os.path.join(base, "wake-logs")
     os.makedirs(log_dir, exist_ok=True)
@@ -489,7 +509,7 @@ def _read_perspective_brief(workdir, agent):
     return brief or None
 
 
-def make_responder(pure, fork_source=None, fork_cwd=None,
+def make_responder(with_extensions, fork_source=None, fork_cwd=None,
                    fork_mode=meeting_fs.DEFAULT_FORK_MODE, topic=""):
     """构造真实 LLM responder：唤醒 pi，LLM 写内容文件。
 
@@ -514,7 +534,7 @@ def make_responder(pure, fork_source=None, fork_cwd=None,
             if mem_available_mb() < MIN_MEM_MB:
                 log(agent, "内存不足——抛可恢复异常（不代写 freezing，下轮重试）")
                 raise RecoverableWakeError("内存不足")
-            wake_llm(workdir, agent, prompt, pure,
+            wake_llm(workdir, agent, prompt, with_extensions,
                      fork_source=fork_source, fork_cwd=fork_cwd)
             return True
         if rr_turn:
@@ -534,7 +554,7 @@ def make_responder(pure, fork_source=None, fork_cwd=None,
         if mem_available_mb() < MIN_MEM_MB:
             log(agent, "内存不足——抛可恢复异常（不代写 freezing，下轮重试）")
             raise RecoverableWakeError("内存不足")
-        wake_llm(workdir, agent, prompt, pure,
+        wake_llm(workdir, agent, prompt, with_extensions,
                  fork_source=fork_source, fork_cwd=fork_cwd,
                  fork_mode=fork_mode, topic=topic)
         return True
@@ -553,11 +573,13 @@ def _preserve_result_md(workdir):
 if __name__ == "__main__":
     if len(sys.argv) < 3:
         print("用法: python3 meeting_loop.py <workdir> <agent> "
-              "[--max-meeting N] [--max-rr N] [--stall-timeout S] [--pure]")
+              "[--max-meeting N] [--max-rr N] [--stall-timeout S]"
+              " [--extensions]")
         sys.exit(1)
     workdir, agent = sys.argv[1], sys.argv[2]
     recover_git_lock(workdir, agent)
-    pure = "--pure" in sys.argv
+    # 默认零扩展；`--extensions` 显式 opt-in（协议字段优先）
+    with_extensions = "--extensions" in sys.argv
     mm, mr, st = 10, 7, 600
     # 协议从 **bare HEAD** 读（单一来源 = 共享事实；本地副本 LLM 可改）——
     # 与 engine participants()/check_status 同一原语
@@ -567,8 +589,8 @@ if __name__ == "__main__":
         print(f"[fatal] protocol.json 读取失败（bare HEAD 无有效内容）: {bare}",
               flush=True)
         sys.exit(1)
-    if proto.get("pure"):
-        pure = True
+    if proto.get("extensions"):
+        with_extensions = True
     if proto.get("maxMeetingRounds"):
         mm = proto["maxMeetingRounds"]
     if proto.get("maxRRRounds"):
@@ -593,7 +615,7 @@ if __name__ == "__main__":
         sys.exit(1)
     try:
         agent_loop(workdir, agent,
-                   make_responder(pure,
+                   make_responder(with_extensions,
                                   fork_source=fork_source,
                                   fork_cwd=proto.get("forkCwd") or "",
                                   fork_mode=fork_mode_cfg,