pi-multi-viewers 0.10.2 → 0.10.3

package/AGENTS.md

@@ -69,7 +69,7 @@ tests/               测试（unittest discover tests）
 
 | 档 | 唤醒命令 | 用途 |
 |---|---|---|
-| **mc-tools**（默认） | 四个 `--no-*` + `-e <MC 的 subagent-entry.js>` + `-e builtin:mcp`（pi **内置** MCP，零第三方依赖） | 给 agents **按需检索**（`ctx_search` 查项目历史、web_search 等查外部）——协议模板里带一句「需要项目历史时用 ctx_search」的条件指引（仅在工具真到位时出现）。**降级/严格/生效值语义见 docs/design.md 决策 20 的语义清单**（唯一权威段） |
+| **mc-tools**（默认） | 四个 `--no-*` + `-e builtin:mcp` + `-e builtin:codemode` + `-e <MC 的 subagent-entry.js>`（两份内置常量 + 一份可失败入口，零第三方依赖） | 给 agents **按需检索**（`ctx_search` 查项目历史、web_search 等查外部）——协议模板里带一句「需要项目历史时用 ctx_search」的条件指引（仅在工具真到位时出现）。**降级/严格/生效值语义见 docs/design.md 决策 20 的语义清单**（唯一权威段） |
 | **none** | 四个 `--no-*` | 零扩展、**零依赖**（无 MC 的机器/CI 用这档） |
 | **all** | 不加任何 `--no-*`（pi 默认发现）| A/B 实验与显式 opt-in |
 

package/docs/design.md

@@ -510,7 +510,7 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
 
     | 档 | 唤醒命令 | 语义 |
     |---|---|---|
-    | `mc-tools`（默认） | 四个 `--no-*` + `-e <MC subagent-entry.js>` + `-e builtin:mcp`（MC 入口缺 → 可见降级：少它那份 `-e`、生效=none；内置 MCP 恒在）
+    | `mc-tools`（默认） | 四个 `--no-*` + `-e builtin:mcp` + `-e builtin:codemode` + `-e <MC subagent-entry.js>`（MC 入口缺 → 可见降级：少它那份 `-e`、生效=none；**两份内置常量恒在**）
     | `none` | 四个 `--no-*` | 零扩展：最快、**零依赖** |
     | `all` | 不加任何 `--no-*` | pi 默认发现（A/B 与显式 opt-in）|
 
@@ -573,22 +573,41 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
        **唯一"可失败"的入口**；内置 MCP 是常量入口、恒在（无第三方、无解析）。
     ② `MV_MC_TOOLS_STRICT=1`（测试/探针保真）→ MC 入口缺失即报错退出
        （否则测试可能在"没装 MC"的环境里通过，而 `ctx_search` 从未生效）；
-       内置 MCP 不参与该判定（名字由 pi 注册、无需解析）。
+       两份**内置常量**入口（`builtin:mcp` / `builtin:codemode`）不参与该判定
+       （名字由 pi 注册、无需解析、不会失败）。
     ③ 生效值语义：**以本档核心能力为准** —— MC 入口解析成功 → `生效=mc-tools`；失败 →
        `生效=none`（本档核心 `ctx_search` 缺失）；原因字段 = **入口层失败原因**（不写
        工具可用性——那件事本档观测不到，见下方「平台能力的可见性」）。
        *（旧措辞「部分降级仍生效=mc-tools」出自「两份入口都会被解析」的时代，已随第二份
        改为常量入口而失效。）*
     ④ 为什么必须显式 `-e`：`--no-extensions` 关的是"扩展发现**与内置扩展**"
-       （pi `--help` 原文）——内置 MCP 也在关停范围，不显式加载 = agents 完全没有
-       MCP 工具；`-e <path>` 接受 `builtin:<name>`（同一份 help）。上游证据：
+       （pi `--help` 原文）——内置 MCP **与 codemode** 都在关停范围，不显式加载 =
+       agents 完全没有 MCP 工具（或被注册但调不到，见 ⑤）；`-e <path>` 接受
+       `builtin:<name>`（同一份 help）。上游证据：
        `core/extensions/index.ts` 里 `{ name: "mcp", builtin: true }`，
        `core/resource-loader.ts` 在 `noExtensions` 时只保留 CLI 显式 `-e` 的扩展。
-    ⑤ **exposure 是配置层的事**（不属于本档）：`mcp.json` 里每个 server 的
-       `exposure` 默认 `codemode`（工具**不声明给模型**，只能从 codemode 脚本调用）；
-       要让 agents 直接调用（= 先前 adapter 的体验）需在 `mcp.json` 写
-       `"exposure": "direct"`——**该文件是用户级配置、也影响主 pi**（2026-09-30 用户裁
-       决选 direct）。
+    ⑤ **exposure 回到 pi 默认（`codemode`）**，agents 也走**原生调用方式**（2026-09-30 用户裁决；
+    此前一天曾短暂改成 `direct`，理由 = "更贴合 pi 的原生设计"）：
+       - `codemode` = 工具**不声明**给模型，列在 **codemode 工具的描述**里，模型**写脚本**调用
+         （`tools` / `ALL_TOOLS` / `text()` / `return` …）；pi 在 server 连上时**自动激活**
+         codemode 工具。好处：大工具面不进模型声明、脚本内可**并行调多个工具**、大结果先筛后回
+         （直调 >20KB 会被掐中间）。
+       - **代价**：脚本比直调多一步；且**必须显式加载 codemode 扩展**（见 ④）——`codemode` 是
+         独立的内置扩展，`--no-extensions` 会关掉它；少了它，MCP 扩展只发一条
+         `ui.notify("…they cannot be called.")`，而我们的非交互模式里 notify 是 **no-op**
+         ⇒ 工具注册了却调不到、且**静默**（2026-09-30 读 `extensions/mcp/index.ts:336-359`
+         + `core/extensions/runner.ts` 的 `noOpUIContext`）。**这是本档必须同时 `-e builtin:codemode`
+         的全部理由。**
+       - 该设置住在 `~/.pi/agent/mcp.json`（**用户级、也影响主 pi**）；项目级 `.pi/mcp.json`
+         只按 **server 同名覆盖**且需 cwd 被 trust。**没有 env 覆盖**（2026-09-30 读 `config.ts`）。
+       - **已实测（2026-09-30 探针，n=2，生产形态源与命令）**：agents 走 codemode 路径**真调通**
+         MCP —— 工具调用 = `codemode`，脚本里 `await tools.mcp__web_search_prime__web_search_prime({…})`，
+         两次都取回真实搜索结果，墙钟 **25–26s**（同款任务 direct 时代 16–31s，同量级）。
+         *口径*：只验"能调通"（不验多工具并行 / 大结果过滤）；token **未做配对测量**——
+         direct 那笔 +1,025 是同源配对所得，两轮之间 fork 源已变大，**数字不可跨轮比**。
+    - 命令形状（三档都只是 `-e` 的有无）：
+      `none` = 四个 `--no-*`；`mc-tools` = 四个 `--no-*` + 两份**内置常量**入口 + MC 入口；
+      `all` = 不加任何 `--no-*`、也不加 `-e`（pi 默认发现）。
     不新增档位（保持简单）。`none` 零依赖（无 MC 的机器/CI 显式选它）。
     **实测（2026-09-30 真场，38 次唤醒）**：内置 MCP 的**每唤醒成本 ≈ 0**——逐唤醒「启
     动前」中位 **−1.3s**（测量偏置）、三 agent 合计 −2s / −5s / +19s、收尾中位 1.1s；
@@ -619,9 +638,11 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
       **cwd = fork_cwd** 启动（项目级 `.pi/mcp.json` + trust 会改变 agents 所见，别把近似当事实）、
       文档写明只覆盖**持续性**失效（不覆盖"启动正常、中途断"）。**两条已证伪的错路**：成功路径
       stderr（notify 是 no-op）与 session 文件（工具集不上盘）——别再捡。
-    - **exposure 的成本与口径**：`direct` 的代价实测 = **+1,025 tok/请求**（差值口径；n=2，
-      配置 = 3 server / 5 工具全 direct；人口 = agent 侧探针会话；**机制外推**：主 pi 每请求同量级
-      ≈ +1k，**未测**）。数字随 server 数 / exposure 变化而作废；写**差值**不写绝对值。
+    - **exposure 的成本与口径**：`direct` 时代实测 **+1,025 tok/请求**（差值口径；n=2；配置 =
+      3 server / 5 工具全 direct；人口 = agent 侧探针会话）——该配置**已于 2026-09-30 回退**为
+      pi 默认 `codemode`（见语义清单 ⑤），所以这笔数字**只作历史对照**，不代表现行成本；
+      `codemode` 的现行成本（工具描述 + 脚本往返）**未测**。数字随 server 数 / exposure 变化而
+      作废；写**差值**不写绝对值。
     - **三档边界**（可复用的判据）：① 上游**文档化结构接口**（`pi mcp list --json` 字段、
       session 条目）→ **可作机器判据**，字段缺失/形状变 ⇒ 记"未知"；② 上游**人类 prose**
       （stderr / notify 文案）→ **只落盘留痕、不做分支**；③ 上游**内部布局**（第三方包

package/meeting_fs.py

@@ -902,6 +902,18 @@ MC_PACKAGE = "@cortexkit/pi-magic-context"
 # 只保留 CLI 显式 `-e` 的扩展（2026-09-30 读源码核实）。
 BUILTIN_MCP_ENTRY = "builtin:mcp"
 
+# mc-tools 档的**第三份**入口 = pi 的 `codemode` 工具（同样是内置扩展）。
+# 为什么必需：MCP server 若用 pi 默认的 `exposure: codemode`，其工具**不声明**给模型，
+# 只能从 codemode 脚本里调用（pi 在 server 连上时会自动激活 codemode 工具）；而
+# `codemode` 是**独立的内置扩展**（上游 `core/extensions/index.ts` 的
+# `{ name: "codemode", builtin: true }`），`--no-extensions` 会一并关掉它 —— 于是
+# MCP 扩展的 `ensureDiscoveryActive` 找不到 codemode 工具，只发一条 `ui.notify`
+# 警告（"MCP tools are only reachable from the codemode or tool_search tool…
+# they cannot be called."），而我们的非交互模式里 notify 是 no-op ⇒ 工具注册了却
+# 调不到、且**静默**（2026-09-30 读源码 + 用户裁决走 pi 原生方式）。
+# 同样是常量：名字由 pi 注册，无需解析（零第三方依赖）。
+BUILTIN_CODEMODE_ENTRY = "builtin:codemode"
+
 FORK_MODES = ("budget", "compaction", "full")
 DEFAULT_FORK_MODE = "budget"
 #

package/meeting_loop.py

@@ -330,19 +330,23 @@ def _build_wake_cmd(workdir, agent, sid, cfg, fork_source, fork_cwd,
     if extension_policy == "none":
         cmd += no_ext
     elif extension_policy == "mc-tools":
-        # mc-tools = 零扩展 + 显式加载**两份能力**（零第三方依赖）：
-        #   ① MC 的 subagent-entry（工具注册 + 生命周期钩子，无 historian）→ ctx_search
-        #   ② pi **内置** MCP 扩展 → web_search / web_reader / zread 等
-        # 为什么必须显式 -e：`--no-extensions` 关的是"扩展发现**与内置扩展**"
-        # （pi --help 原文）——内置 MCP 也在关停范围，不显式加载 agents 就没有
-        # MCP 工具；`-e <path>` 同时接受 `builtin:<name>`（pi --help 原文）。
-        # 为什么用内置而不再用第三方 adapter：pi 0.99+ 自带，少一个外部依赖
-        # （用户 2026-09-30 定）；此前的 adapter 入口解析机制随之删除。
-        # 降级语义：唯一"可失败"的入口是 MC（解析第三方包的内部文件）——
-        # 失败则**本档核心能力（ctx_search）不到位** → 生效=none，原因里点名；
-        # 内置 MCP 是常量入口、恒在，故降级不影响它（原因字段会说明这一点）。
+          # mc-tools = 零扩展 + 显式加载**三份能力**（零第三方依赖）：
+          #   ① MC 的 subagent-entry（工具注册 + 生命周期钩子，无 historian）→ ctx_search
+          #   ② pi **内置** MCP 扩展 → web_search / web_reader / zread 等
+          #   ③ pi **内置** codemode 扩展 → 让 ② 的工具真正可达（见下方“为什么 ③ 必需”）
+          # 为什么必须显式 -e：`--no-extensions` 关的是"扩展发现**与内置扩展**"
+          # （pi --help 原文）——内置 MCP 与 codemode 都在关停范围；`-e <path>` 同时
+          # 接受 `builtin:<name>`（pi --help 原文）。
+          # 为什么 ③ 必需：server 用 pi 默认 `exposure: codemode` 时，其工具不声明给
+          # 模型、只能从 codemode 脚本调用；少了 ③，MCP 扩展的 ensureDiscoveryActive
+          # 找不到 codemode 工具，只发一条 ui.notify 警告（而我们的非交互模式里 notify
+          # 是 no-op）⇒ 工具注册了却调不到、且静默（2026-09-30 读源码 + 用户裁决走原生）。
+          # 降级语义：唯一"可失败"的入口是 MC（解析第三方包的内部文件）——失败则
+          # **本档核心能力（ctx_search）不到位** → 生效=none，原因里点名；②③ 是常量
+          # 入口、恒在，故降级不涉及它们（原因字段只写入口层事实）。
         cmd += no_ext
         cmd += ["-e", meeting_fs.BUILTIN_MCP_ENTRY]
+        cmd += ["-e", meeting_fs.BUILTIN_CODEMODE_ENTRY]
         entry, err = meeting_fs.resolve_mc_tools_entry()
         if entry:
             cmd += ["-e", entry]

package/package.json

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