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/）等诊断项。

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

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

几个值得注意的设计：

• 🛡️路由强制执行：模型尝试内联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_statsMCP 工具还能输出更详细的跨会话统计报告（事件分类、压缩次数、会话时长），配合上面两张图可以直观看到上下文节省效果。

常见问题自查清单

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

小结

context-mode 对 Pi Coding Agent 的接入是"零手工钩子"体验：扩展方式一次性接住 9 类生命周期事件，MCP 桥让 11 个ctx_*工具真正可达，路由拦截、记忆持久化与压缩恢复开箱即用。装完 4 步之后，你就拥有了一个上下文更省、记忆更牢的 Pi 编码代理。

【免费下载链接】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