feat: add context-mode CodeGraph MCP integration

AGENTS.md

@@ -9,6 +9,8 @@
 - 初始导入快照：`d155d253cb2f1358e34e717d47a82ebccb08cb8e`（2026-07-03，`0.9.0`）。
 - 该目录已纳入本仓库直接维护，不是 submodule，也不保留嵌套 `.git`。
 - `extensions/fff-override.ts`：强制使用 FFF 官方 `override` 模式，统一接管 `find`、`grep`、`multi_grep` 和 FFF 的 `@` 补全；显式 CLI flag 仍遵循 FFF 官方优先级。
+- `context-mode`：加载上游 Pi adapter 与 skills，提供 `ctx_*` 工具、隔离式大输出处理和会话连续性。
+- `extensions/codegraph.ts`：通过隔离的 `pi-mcp-adapter` 配置连接机器现有的 `codegraph serve --mcp`，只暴露 `codegraph_explore`。
 - `extensions/permission-system.ts`：在权限扩展注册前，将 `config/pi-permission-system.json` 同步为全局权威配置。
 - 根包还固定安装 `pi-context-view`、`@firstpick/pi-extension-codex-fast-mode` 和 `@gotgenes/pi-permission-system`。
 
@@ -19,6 +21,9 @@
 - `commandRewritingEnabled` 默认 `false`。默认安装不依赖系统 `rtk` CLI；只有用户主动开启命令改写时才需要 `rtk rewrite`。
 - `readCompaction.enabled`、`sourceCodeFilteringEnabled` 和 `smartTruncate.enabled` 当前均默认 `false`，源码读取保持原样。未经用户明确决定，不因节省上下文而改变这些默认值。
 - 若以后开启 read 压缩，优先考虑 `readCompaction + smartTruncate`，源码过滤仍独立评估；必须保留精确 `offset/limit` 读取、短文件和行锚点的完整性。
+- Context Mode 负责避免批量读取、命令研究和网页原始内容直接撑大上下文；FFF 仍负责精确字面搜索，RTK 仍处理未走 Context Mode 的普通输出。
+- CodeGraph 只配置 Pi 到外部 `codegraph` 命令的 MCP 连接。组合包不安装 CodeGraph，不执行 `codegraph init`，不创建或管理 `.codegraph/`，也不改动索引、更新或遥测设置。
+- CodeGraph MCP 使用 `keep-alive` 并只直接暴露 `codegraph_explore`；命令缺失、项目未初始化或连接失败时不得阻止其他扩展加载。
 - `pi-context-view` 只观察上下文占用，不参与压缩策略。
 - Codex fast mode 只为符合条件的 `openai-codex-responses` 请求设置 priority service tier，由 `/fast-mode` 在会话内控制。
 - 权限策略默认允许常规工具，允许 FFF 工具；拒绝 Bash 直搜，敏感凭据路径拒绝，外部目录、Git 写操作、破坏性系统操作、网络和安装操作询问。

README.md

@@ -4,6 +4,8 @@
 
 - `@ff-labs/pi-fff@0.10.5`：使用官方 `override` 模式接管 `find`、`grep` 和 `multi_grep`。
 - 本仓库维护的 `pi-rtk-optimizer`：只处理 Bash/read 等输出压缩，默认不改写命令，也不处理搜索工具结果。
+- `context-mode@1.0.169`：通过 Pi adapter 提供 `ctx_*` 工具、上下文隔离和会话连续性。
+- `pi-mcp-adapter@2.26.0`：只用于把机器现有的 CodeGraph MCP Server 接入为 `codegraph_explore`。
 - `pi-context-view@0.4.2`：查看上下文占用。
 - `@firstpick/pi-extension-codex-fast-mode@0.1.1`：为 Codex provider 提供会话级 `/fast-mode`。
 - `@gotgenes/pi-permission-system@26.2.1`：加载组合包自带的权限基线。
@@ -22,6 +24,10 @@ pi install git:git@bitbucket.org:siakitem/my-pi.git
 默认配置不需要系统 `rtk` CLI。只有以后在 `/rtk` 中主动开启
 `RTK command rewriting` 时，才需要另外安装 `rtk` 可执行文件。
 
+CodeGraph 本体不由组合包安装。需要使用 CodeGraph 的机器应自行确保 `codegraph` 在
+启动 Pi 的 `PATH` 中，并在目标项目执行过 `codegraph init`。组合包不会创建或维护
+`.codegraph/`，也不会修改 CodeGraph 的索引、更新或遥测设置。
+
 ## 组合行为
 
 ### 搜索归 FFF
@@ -37,6 +43,30 @@ RTK 保留 Bash、read、build、test、lint 和 Git 输出压缩。默认 `read
 仍关闭；可用 `/rtk` 查看或调整。旧机器已有的 RTK 配置若没有
 `commandRewritingEnabled` 字段，也会按 `false` 归一化，不需要迁移配置。
 
+### 大输出归 Context Mode
+
+Context Mode 直接加载 npm 包内置的 Pi adapter 和 skills，不需要额外写入
+`~/.pi/agent/mcp.json`，也不需要全局安装 `context-mode` 命令。它提供 `ctx_*` 工具，
+将批量读取、命令研究和网页内容先在隔离进程中处理，再把收敛后的结果送入上下文。
+
+FFF 仍负责精确字面搜索；RTK 继续压缩未走 Context Mode 的 Bash、build、test、lint
+和 Git 输出。Context Mode 不替换这两个扩展的现有配置。
+
+### CodeGraph 只负责连接
+
+`extensions/codegraph.ts` 使用隔离的 `pi-mcp-adapter` 配置启动
+`codegraph serve --mcp`，不会读取或覆盖用户已有的 MCP 配置。连接采用
+`keep-alive`，并只把官方当前主工具 `codegraph_explore` 作为同名 Pi 工具暴露；
+CodeGraph 的文件 watcher 由该 MCP 进程自身维护。
+
+若机器没有 `codegraph`，或当前项目尚未建立索引，CodeGraph 会报告连接/初始化错误，
+其他扩展仍可正常工作。安装与索引状态可在机器上自行检查：
+
+```bash
+codegraph --version
+codegraph status
+```
+
 ### 权限基线自动部署
 
 `extensions/permission-system.ts` 在权限扩展注册前，把仓库中的

extensions/codegraph.ts

@@ -0,0 +1,23 @@
+import { createMcpAdapter } from "pi-mcp-adapter";
+
+/** Connect Pi to the CodeGraph MCP server provided by the host machine. */
+export default createMcpAdapter({
+	config: {
+		settings: {
+			disableProxyTool: true,
+			scriptMode: false,
+		},
+		mcpServers: {
+			codegraph: {
+				command: "codegraph",
+				args: ["serve", "--mcp"],
+				lifecycle: "keep-alive",
+				directTools: ["codegraph_explore"],
+				includeTools: ["codegraph_explore"],
+				toolPrefix: "none",
+				approveTools: false,
+				exposeResources: false,
+			},
+		},
+	},
+});

package.json

@@ -19,15 +19,22 @@
     "extensions": [
       "./extensions/fff-override.ts",
       "./pi-rtk-optimizer/index.ts",
+      "./node_modules/context-mode/build/adapters/pi/extension.js",
+      "./extensions/codegraph.ts",
       "./node_modules/pi-context-view/src/index.ts",
       "./node_modules/@firstpick/pi-extension-codex-fast-mode/index.ts",
       "./extensions/permission-system.ts"
+    ],
+    "skills": [
+      "./node_modules/context-mode/skills"
     ]
   },
   "dependencies": {
     "@ff-labs/pi-fff": "0.10.5",
     "@firstpick/pi-extension-codex-fast-mode": "0.1.1",
     "@gotgenes/pi-permission-system": "26.2.1",
+    "context-mode": "1.0.169",
+    "pi-mcp-adapter": "2.26.0",
     "pi-context-view": "0.4.2"
   },
   "peerDependencies": {