Context Mode for Pi Coding Agent（中文）

English README

本文档专门说明 Pi Coding Agent 插件 的安装、配置和功能。

这是什么

Context Mode 是一个 MCP server，同时也是一个给 Pi Coding Agent 使用的插件。它把大型命令输出、文件、网页和会话历史保存在本地，需要时再检索，避免一次性塞进模型上下文。插件提供 Pi 原生工具桥接、生命周期恢复、可选的 Bash/Read 替换、工具可见性设置和 Pi 专用显示。

Pi 插件入口是 build/adapters/pi/host-entry.js，由 package.json 的 pi.extensions 声明。插件会按需启动 server.bundle.mjs，完成 MCP 握手，并通过 Pi 自己的工具注册表注册 ctx_* 工具。使用这个 Pi 插件不需要再添加第二个 MCP 配置。

安装

**要求：**已安装 Pi Coding Agent，Node.js >=22.5；运行时也支持 Bun。

npm install -g pi-context-mode
pi install npm:pi-context-mode

安装后重启 Pi。源码开发使用：

pnpm install
pnpm build

Pi 配置文件

Context Mode 只读取以下两个位置：

• 全局：~/.pi/agent/context-mode/settings.json
• 项目：<project>/.pi/context-mode/settings.json

原来： Pi 的 context-mode 配置和权限读取会复用 Claude Code 配置以及 Pi 通用的 ~/.pi/settings.json，并保留较宽的回退路径。因此，原本给其他 host 使用的配置可能影响 Pi，或者被 Pi 意外读到。

**现在：**这些 Pi 功能只读取上面列出的两个 context-mode 专用配置文件。项目配置覆盖全局配置，并且不再回退到 Claude Code 配置或 Pi 通用配置。

**好处：**Pi 配置与其他 host 隔离，优先级明确，用户只需要管理一个项目配置路径和一个全局配置路径。

完整示例：

{
  "toolReplacements": {
    "bash": { "enabled": true },
    "read": { "enabled": true, "maxLines": 300, "maxBytes": 10240 }
  },
  "tidyToolDisplay": { "enabled": true },
  "disabledBuiltinFeatures": [
    "ctx_stats",
    "ctx_doctor",
    "ctx_upgrade",
    "ctx_purge",
    "ctx_insight"
  ],
  "extensionAdapters": {
    "blackhole": { "enabled": true }
  }
}

所有配置段都是可选的。无效配置会安全关闭对应功能并发出警告，不会阻止 Pi 启动。修改后要重新加载插件或重启 Pi；不支持运行中切换。

Pi 功能

1. Pi 原生提示词元数据

原来： Pi 适配器会在 before_agent_start 阶段组装一段静态路由提示，再通过 Pi 的 context hook 作为额外消息追加给模型。这段消息会告诉模型工具层级，以及什么时候选择 ctx_execute、ctx_execute_file、ctx_batch_execute、ctx_search 等工具。

现在： Pi 适配器在注册工具时，把稳定的工具选择说明放进 Pi 原生的 promptSnippet / promptGuidelines 元数据中。MCP bridge 会在 session_start 阶段启动并等待完成，所以首轮模型请求已经拥有 ctx 工具及其说明；只执行 CLI 命令时不会启动它。before_agent_start 只保留 active memory、resume data 等动态会话上下文，不再追加静态路由提示。

好处： 路由说明会直接附着在相关工具上，不必每轮重复发送；稳定的提示词前缀更容易被 provider 缓存；动态会话信息也不会再和静态工具说明混在同一条消息里。

2. Bash 和 Read 原生替换（默认关闭）

• **Bash：**启用后把 shell 工作路由到 ctx_execute；原生 Bash 仍保留为故障恢复通道，但从 Pi 的文字工具摘要中隐藏。只有在替换真正生效时，才移除 Pi 那条会和 ctx_execute 冲突的 Bash 文件探索提示。
• **Read：**保留原生 read(path, offset?, limit?) 形式，同时把文本限制为 maxLines 和 maxBytes；默认是 300 行和 10,240 个 UTF-8 字节。图片保持原样，续读偏移单独返回。
• 通过 Pi 当前实际工具注册表判断所有权。如果其他插件拥有 bash 或 read，就跳过替换，也不宣传更强的路由规则。
• 两个替换互相独立；明确写错一个配置只关闭对应替换，配置文件损坏或不可读时安全关闭两者。

3. Tidy 风格工具显示（默认关闭）

这项显示功能参照 pi-tidy-tools 插件（@mobrienv/pi-tidy-tools）的显示方式实现，但由本插件独立实现，不导入或依赖该插件。开启 tidyToolDisplay.enabled 后，Context Mode 的 Pi 工具会使用这一显示风格；这个开关本身不会启用 Bash 或 Read 原生替换。

如果同时开启 toolReplacements.bash.enabled 和／或 toolReplacements.read.enabled，对应工具在替换实际生效后，也会按照 pi-tidy-tools 的风格显示。

两个插件一起使用时： 如果安装了 pi-tidy-tools，需要将准备交给 Context Mode 替换的原生 bash、read 工具设为直通，也就是让 pi-tidy-tools 不替换这些工具。否则，两个插件会争用同一个工具，产生冲突。Context Mode 检测到工具已被其他插件接管时，会跳过对应替换并发出警告，不会自动组合两套替换。其他工具仍可由 pi-tidy-tools 负责显示。

打开后，Pi 侧的 schema 会增加仅用于显示的 reasoning 字段，执行前会删除它。工具调用显示为两行：分类图标、用途或目标、整行背景、耗时、结果数量和错误状态。窗口窄时保留末尾统计并用 … 缩短目标；展开时保留两行标题再显示结果。

read 和 ctx_execute_file 显示行数；shell 工具显示耗时；ctx_batch_execute 显示命令数；ctx_search 显示命中数；索引工具显示 section 数；其他工具显示简短的 done。

4. 工具可见性和压缩恢复

disabledBuiltinFeatures 是完整替换列表，不是逐项合并。它接受 11 个 ctx_* 工具名和 compactRecovery。

• 默认隐藏 ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight，因为这些工具主要供人使用，没有必要注册到 Pi 的工具列表中，避免浪费上下文空间。
• 写入空数组会恢复全部 11 个工具在 Pi 中的可见性。
• 隐藏工具只从 Pi 的注册表和提示词元数据中移除，命令行和其他 host 仍保留处理器。
• 禁用 compactRecovery 后，Context Mode 不再准备或发送自己的压缩恢复消息，也不再写退休标记；运行时事件采集、原生 transcript、压缩计数和显式重载恢复不受影响。
• 无效列表回退到安全默认值：隐藏五个管理工具，开启压缩恢复。
• 共享 MCP 工具目录保持完整；Pi 只过滤自己的 agent 工具注册表，其他 host 可以使用各自的可见性策略。

5. Pi-Blackhole 压缩恢复适配

这个 Pi 适配层支持与 pi-blackhole 一起运行。压缩后，pi-blackhole 可以注入压缩前快照，Context Mode 也会发布自己的隐藏恢复消息。适配层会协调两条消息，使它们互相补充而不是重复注入相同内容。

• 开启 extensionAdapters.blackhole.enabled 后，Context Mode 会从自己的压缩恢复内容中去除重复信息：goal、prompt、file、error、skill、mcp，以及类型为 git_commit 的 git 事件。
• 只会过滤 Context Mode 自己的恢复消息，不会修改 pi-blackhole 的消息或 Pi 原生 transcript。过滤只用于压缩恢复，不会通过此开关过滤 resume 恢复内容。
• 会话事件使用 Pi 原生 session ID 和按项目划分的标准 SessionDB 路径。恢复消息绑定当前分支和压缩片段，并拒绝重复回调、过期身份和其他分支。
• 普通启动和恢复会信任 Pi 原生 transcript，不再重复注入历史 SessionDB 事件。

这样，pi-blackhole 负责提供压缩前快照，Context Mode 只补充剩余的恢复上下文，从而减少重复 token，避免恢复信息重复。

6. 工具说明和校验

• 当 git、rg、fd、jq、gh、yq、uv 等现成命令更清楚可靠时，优先使用它们；只有 shell 不合适或逻辑复杂时才写自定义代码。
• ctx_search 会先拒绝缺失、空值和无效字符串查询，再判断索引是否为空。
• 对外 JSON Schema 不再宣传误导性的反斜杠查询模式，但处理器仍要求非空查询。
• 工具描述、ctx_index、ctx_batch_execute、获取网址的输入、结果统计和恢复路由说明均与实际运行行为对齐。

7. BUG 修复

• **桥接启动：**父 Pi 进程可能继承 CONTEXT_MODE_BRIDGE_DEPTH，被误认为桥接子进程，导致自身工具被禁用。修复后只给真正启动的桥接子进程设置 CONTEXT_MODE_BRIDGE_CHILD，并要求同时存在该标记和正数深度才停止桥接启动。
• **数据库清理：**内容数据库可能仅因 WAL 长时间没有变化就被删除，即使数据库仍在使用。现在按照主数据库的保留期限清理，不再单独依据 WAL 是否安静，从而保留仍在使用的数据库及其 WAL。

开发和验证

pnpm install
pnpm typecheck
pnpm build
pnpm test
git diff --check

Pi 专用测试覆盖配置优先级和隔离、工具所有权、Read 限制、Bash 路由、提示词过滤、生命周期恢复、Tidy 显示、桥接注册和真实 host 冒烟场景。许可证是 Elastic License 2.0，详见 LICENSE。