context-mode Pi Coding Agent安装指南：扩展方式接入全生命周期事件-开发者社区

context-mode Pi Coding Agent安装指南：扩展方式接入全生命周期事件

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

context-mode 是一款面向 AI 编码代理的上下文窗口优化工具，通过扩展方式接入 Pi Coding Agent，捕获会话启动、工具调用、工具结果、上下文压缩等全生命周期事件。它能将工具输出沙盒化（上下文削减 98%）、把会话记忆持久化到 SQLite，并通过 MCP + 钩子在 17 个平台上强制执行路由策略。本文带你用 4 步完成安装、配置与验证。

为什么 Pi 要用「扩展方式」接入

与 Claude Code 等平台走 JSON stdin/stdout 钩子不同，Pi 没有传统钩子通道，它暴露的是 JS 回调式运行时 API（如pi.on("session_start", fn)、pi.on("tool_call", fn)）。因此：

context-mode 的 Pi 适配器（src/adapters/pi/index.ts）刻意声明mcp-only能力，不做任何 JSON-stdio 钩子注册；
全部生命周期事件由扩展src/adapters/pi/extension.ts直接接线；
Pi 0.73.x 没有原生 MCP 支持，context-mode 通过 MCP-stdio 桥（src/adapters/pi/mcp-bridge.ts）拉起内置 MCP 服务器子进程，完成协议握手后，把 11 个ctx_*工具（ctx_execute、ctx_search、ctx_stats等）经pi.registerTool()注册进 Pi，模型才能真正调用它们。

🔑 这就是"扩展方式"的核心：一次安装，路由拦截 + 记忆持久化 + 压缩恢复全自动。

四步安装：从 0 到完整接入

第 1 步：全局安装 context-mode

前提：Node.js ≥ 22.5（或 Bun）、已安装 Pi Coding Agent。

npm install -g context-mode

第 2 步：把扩展装入 Pi

pi install npm:context-mode

也可以手动编辑~/.pi/agent/settings.json（项目级为.pi/settings.json），在packages中加入"npm:context-mode"。

第 3 步：注册 MCP 服务器

编辑~/.pi/agent/mcp.json（项目级为.pi/mcp.json）：

{ "mcpServers": { "context-mode": { "command": "context-mode" } } }

第 4 步：重启 Pi 并验证

重启后在会话中输入ctx stats，ctx_*工具应出现并正常响应；再运行/ctx-doctor可检查扩展注册路径（~/.pi/extensions/context-mode/）等诊断项。

全生命周期事件：扩展到底接入了什么

安装完成后，扩展会注册以下事件，构成从"会话开始"到"会话结束"的完整闭环：

生命周期事件	作用
`session_start`	生成稳定会话 ID、初始化会话数据库、清理 7 天前过期会话
`before_agent_start`	惰性启动 MCP 桥、捕获用户提示事件、注入路由锚点与 active_memory
`tool_call`	工具调用前路由拦截：阻止内联 HTTP 客户端
`tool_result`	工具调用后事件捕获：文件读写、git 操作、错误等写入会话数据库
`context`	以消息形式注入记忆与恢复快照，不改动 system prompt（保前缀缓存）
`before_provider_response`	记录模型、延迟、token 用量等元数据
`turn_end`	逐轮汇总 token 消耗与美元成本
`session_before_compact`	压缩前生成恢复快照
`session_compact`/`session_shutdown`	更新压缩计数、清理过期数据、安全关停 MCP 子进程

几个值得注意的设计：

🛡️路由强制执行：模型尝试内联fetch、requests或无文件输出的curl/wget时，tool_call钩子会直接拦截并引导改用ctx_*工具，避免原始响应体灌爆上下文窗口；仅放行"静默 + 输出到文件"的安全形式作为 MCP 故障逃生通道。
🧠会话记忆：高优先级事件（决策、任务、错误等）构建为 active_memory（500 token 上限），每轮自动注入，模型无需重复探索。
📸压缩后恢复：session_before_compact触发快照生成，压缩发生后在下一轮自动注入，长任务被压缩后模型仍"记得做到哪了"。
💰成本核算：turn_end事件逐轮记录 token 与原生美元成本，无需本地维护价格表。

数据存储在哪里、有哪些日常命令

📁 全部会话数据存于~/.pi/context-mode/sessions/，按项目生成规范哈希命名的数据库文件，与~/.claude/等平台目录完全隔离；
📝 指令文件遵循 Pi 约定，读取项目中的AGENTS.md。

在 Pi 会话内可用的快捷命令：

命令	作用
`/ctx-stats`	查看本会话事件数、压缩次数与分类统计
`/ctx-doctor`	诊断数据库路径、会话 ID、插件目录、注册状态

ctx_statsMCP 工具还能输出更详细的跨会话统计报告（事件分类、压缩次数、会话时长），配合上面两张图可以直观看到上下文节省效果。

常见问题自查清单

ctx_* 工具不出现：确认全局安装成功且mcp.json已保存，运行ctx doctor查看扩展注册状态；桥接失败时诊断会写入 Pi 文件日志而非终端。
会话数据写错目录：若发现 Pi 数据落在~/.claude/下，通常是与其他 AI 平台共存时的环境变量串扰，清理环境后重启 Pi 即可。
清理索引内容：在会话中让模型调用ctx_purge，可清空知识库中的全部索引内容。