@liuxincuit/pi-codegraph 0.1.1 → 0.1.3

package/CONTEXT.md

@@ -1,21 +1,21 @@
-# pi-codegraph
-
-A pi extension that gives the agent access to a CodeGraph index of the current project.
-
-## Language
-
-**Project**:
-The directory the pi session runs in (`ctx.cwd`). The unit that CodeGraph indexes and the default scope of every query.
-_Avoid_: workspace, repository, repo
-
-**Index**:
-The `.codegraph/` directory at the project root, holding the SQLite knowledge graph of the project's symbols, edges, and files. Built by `codegraph init`, updated by `codegraph sync`.
-_Avoid_: database, cache, graph (ambiguous with the data structure)
-
-**Explore**:
-The single agent-facing query operation: a natural-language or symbol question answered with the relevant symbols' verbatim source plus the call paths between them.
-_Avoid_: search, query, lookup
-
-**Sync**:
-An incremental update of the Index to match the files currently on disk. Cheap when nothing changed.
-_Avoid_: refresh, rebuild (that's a full re-index)
+# pi-codegraph
+
+A pi extension that gives the agent access to a CodeGraph index of the current project.
+
+## Language
+
+**Project**:
+The directory the pi session runs in (`ctx.cwd`). The unit that CodeGraph indexes and the default scope of every query.
+_Avoid_: workspace, repository, repo
+
+**Index**:
+The `.codegraph/` directory at the project root, holding the SQLite knowledge graph of the project's symbols, edges, and files. Built by `codegraph init`, updated by `codegraph sync`.
+_Avoid_: database, cache, graph (ambiguous with the data structure)
+
+**Explore**:
+The single agent-facing query operation: a natural-language or symbol question answered with the relevant symbols' verbatim source plus the call paths between them.
+_Avoid_: search, query, lookup
+
+**Sync**:
+An incremental update of the Index to match the files currently on disk. Cheap when nothing changed.
+_Avoid_: refresh, rebuild (that's a full re-index)

package/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2025 izhimu
-Copyright (c) 2026 liuxincuit
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 izhimu
+Copyright (c) 2026 liuxincuit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,7 +49,9 @@ pi -e ./extensions/codegraph.ts
 
 ## 功能一览
 
-- **`codegraph_explore` 工具** — 面向智能体的核心代码智能工具。输入符号名或自然语言问题即可查询；可选传 `path` 查询其他已建索引的项目，传 `maxFiles` 限制返回的源码行数。
+- **`codegraph_*` 工具集** — 面向智能体的代码智能工具，均支持 `path` 参数查询其他已建索引的项目：
+  - `codegraph_explore`（**默认注册**）— 一揽子探索：相关符号逐字源码 + 调用路径 + 影响范围（`maxFiles` 限制返回行数）
+  - `codegraph_query` / `codegraph_node` / `codegraph_callers` / `codegraph_callees` / `codegraph_impact` / `codegraph_files`（**默认隐藏**，见下方配置）
 - **`/codegraph-init [path]`** — 为项目建立索引（`codegraph init`）。
 - **`/codegraph-sync [path]`** — 手动同步自上次索引以来的改动（`codegraph sync`）。
 - **`/codegraph-status [path]`** — 查看索引状态与统计信息（`codegraph status`）。
@@ -71,6 +73,18 @@ pi -e ./extensions/codegraph.ts
 
 索引构建始终由你显式触发——智能体自身不会运行 `codegraph init`（见 `docs/adr/0002`）。
 
+## 细粒度工具（可选开启）
+
+`codegraph_explore` 能覆盖绝大多数结构化查询，因此另外 6 个细粒度工具默认**不注册**，避免过多工具增加智能体的决策负担（见 `docs/adr/0003`）。需要时在全局 `~/.pi/agent/extensions/pi-codegraph/config.json` 或项目 `.pi/extensions/pi-codegraph/config.json` 中配置 `extraTools` 开启（项目配置覆盖全局）：
+
+```json
+{
+  "extraTools": ["query", "node", "impact"]
+}
+```
+
+短名（`node`、`impact`）与完整工具名（`codegraph_node`）均可用，`"all"` 开启全部。配置在下一个会话生效（`/reload` 或重启 pi）。
+
 ## 工作原理
 
 pi 原生不支持 MCP，因此本扩展通过执行 CLI 来桥接 CodeGraph——`codegraph explore` 产生与 `codegraph_explore` MCP 工具相同的输出（见 `docs/adr/0001`）。每次工具调用仅需一次 `pi.exec`：没有守护进程、没有 JSON-RPC，没有可泄漏或需要恢复的状态。

package/extensions/codegraph.ts

@@ -1,298 +1,596 @@
-// pi-codegraph — pi extension
-//
-// CodeGraph support for pi: codegraph_explore tool, /codegraph-init,
-// /codegraph-sync, /codegraph-status, and /codegraph-unlock commands.
-//
-// Bridges to CodeGraph by executing the CLI (see docs/adr/0001). Requires the
-// codegraph CLI on PATH: npm i -g @colbymchenry/codegraph
-// Upstream: https://github.com/colbymchenry/codegraph
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const INSTALL_HINT =
-	"未检测到 codegraph CLI（PATH 中无 codegraph 命令），本插件未注入任何工具、命令或技能。" +
-	"安装：npm i -g @colbymchenry/codegraph，然后 /reload 或重启 pi 生效。";
-
-// Whole-process dedup for the missing-CLI hint: extensions re-run per session and
-// per subagent (separate jiti module copies), so gate on globalThis.
-const MISSING_CLI_HINTED = Symbol.for("pi-codegraph.missing-cli-hinted");
-
-// Result of `codegraph version` this session — null until first check.
-let cliAvailable: boolean | null = null;
-
-async function execCg(
-	pi: ExtensionAPI,
-	args: string[],
-	options: { signal?: AbortSignal; timeout?: number; cwd?: string } = {},
-) {
-	if (process.platform === "win32") {
-		return await pi.exec("cmd.exe", ["/d", "/s", "/c", "codegraph", ...args], options);
-	}
-	return await pi.exec("codegraph", args, options);
-}
-
-async function ensureCli(pi: ExtensionAPI): Promise<boolean> {
-	if (cliAvailable !== null) return cliAvailable;
-	try {
-		const result = await execCg(pi, ["version"], { timeout: 10_000 });
-		cliAvailable = result.code === 0;
-	} catch {
-		cliAvailable = false;
-	}
-	return cliAvailable;
-}
-
-function textResult(text: string) {
-	return { content: [{ type: "text" as const, text }], details: undefined };
-}
-
-function outputOf(result: { stdout: string; stderr: string; code: number }): string {
-	return (result.stdout + result.stderr).trim() || `exit ${result.code}`;
-}
-
-async function isIndexed(cwd: string): Promise<boolean> {
-	try {
-		await fs.access(path.join(cwd, ".codegraph", "codegraph.db"));
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-type StatusState = "index" | "sync" | "init" | boolean | undefined;
-
-function updateStatusBar(ctx: ExtensionContext, state: StatusState) {
-	if (!ctx.hasUI) return;
-	const label = state === true ? "index" : state === false ? undefined : state;
-	if (label) {
-		const text = ctx.ui.theme?.fg
-			? `${ctx.ui.theme.fg("accent", "⬡")} ${label}`
-			: `⬡ ${label}`;
-		ctx.ui.setStatus("codegraph", text);
-	} else {
-		ctx.ui.setStatus("codegraph", undefined);
-	}
-}
-
-// Modeled on upstream's MCP SERVER_INSTRUCTIONS (src/mcp/server-instructions.ts):
-// lead the agent to codegraph_explore BEFORE grep/read, plus anti-patterns and staleness handling.
-const INDEX_HINT = `# CodeGraph — this project is indexed
-
-A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). ONE \`codegraph_explore\` call returns the relevant symbols' verbatim line-numbered source (treat it as already Read — safe to Edit from) PLUS call paths between them and a blast-radius summary of what depends on them.
-
-- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), call \`codegraph_explore\` INSTEAD of grep + read — usually ONE call answers the whole question.
-- Call it BEFORE and WHILE writing or editing code: it puts the blast radius in view before you touch a symbol you can name.
-- Flow tracing: name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface the path across dynamic-dispatch hops.
-- Anti-patterns: don't grep or Read first; don't re-verify codegraph output with grep (AST-derived, more accurate than grep); don't reconstruct a flow by hand.
-- "Already sent earlier in this conversation": pointer means content is already in context — do not re-fetch or Read.
-- Staleness: if tool output contains "⚠️ Some files referenced below were edited since the last index sync", read only those flagged files directly.
-- Multi-project / Monorepo: pass \`path\` to query any indexed sub-project directory.
-- If a project has no \`.codegraph/\`, use built-in tools there; indexing is the user's decision — suggest /codegraph-init if it comes up.`;
-
-// When the CLI is absent, register nothing but a one-shot hint handler: no
-// tools, no commands, no resources_discover (so no skill injection), no sync.
-export function registerMissingCliHint(pi: ExtensionAPI) {
-	pi.on("session_start", async (_event, ctx) => {
-		if ((globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED]) return;
-		(globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED] = true;
-		if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "warning");
-	});
-}
-
-export default async function codegraphExtension(pi: ExtensionAPI) {
-	if (!(await ensureCli(pi))) {
-		registerMissingCliHint(pi);
-		return;
-	}
-	// ── codegraph_explore tool ─────────────────────────────────────────────
-	pi.registerTool({
-		name: "codegraph_explore",
-		label: "CodeGraph Explore",
-		description:
-			"PRIMARY tool for code questions — call it BEFORE grep/read when the project has a .codegraph/ index. " +
-			"One query returns the relevant symbols' verbatim line-numbered source plus the call paths between them and a blast-radius summary. " +
-			"If the project is not indexed the output says so: continue with built-in tools and suggest the user run /codegraph-init.",
-		promptSnippet:
-			"codegraph_explore: symbol source + call paths in one shot from the project's CodeGraph index",
-		promptGuidelines: [
-			"For structural code questions (how does X work, where is X, what breaks if I change X), prefer codegraph_explore over grep when the project has a .codegraph/ index.",
-			"Indexing is the user's decision — never run codegraph init yourself; suggest /codegraph-init instead.",
-		],
-		parameters: Type.Object({
-			query: Type.String({
-				description: "Symbol names or a natural-language question about the code",
-			}),
-			path: Type.Optional(
-				Type.String({
-					description: "Project path to query; defaults to the current working directory",
-				}),
-			),
-			maxFiles: Type.Optional(
-				Type.Integer({
-					description: "Maximum number of files to include source from",
-				}),
-			),
-		}),
-		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
-			if (!(await ensureCli(pi))) return textResult(INSTALL_HINT);
-			const cwd = params.path ?? ctx.cwd;
-			const args = ["explore", params.query, "-p", cwd];
-			if (typeof params.maxFiles === "number" && params.maxFiles > 0) {
-				args.push("--max-files", String(params.maxFiles));
-			}
-			const result = await execCg(pi, args, {
-				signal,
-				timeout: 120_000,
-			});
-			if (result.killed) return textResult("codegraph explore timed out (120s)");
-			// Non-zero exits carry upstream's agent-friendly guidance (e.g. the
-			// "not initialized" message) — pass it through verbatim.
-			if (result.code !== 0) return textResult(outputOf(result));
-			return textResult(result.stdout.trim());
-		},
-	});
-
-	// ── /codegraph-init ────────────────────────────────────────────────────
-	pi.registerCommand("codegraph-init", {
-		description: "Build the CodeGraph index for the current project (codegraph init)",
-		handler: async (args, ctx) => {
-			if (!(await ensureCli(pi))) {
-				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
-				return;
-			}
-			const target = args?.trim() || ctx.cwd;
-			if (ctx.hasUI) {
-				ctx.ui.notify(`Indexing ${target} — can take minutes on a large repo…`, "info");
-			}
-			updateStatusBar(ctx, "init");
-			try {
-				const result = await execCg(pi, ["init", target], { timeout: 1_800_000 });
-				const out = outputOf(result);
-				const success = result.code === 0;
-				if (ctx.hasUI) {
-					ctx.ui.notify(
-						success ? "CodeGraph index built." : `codegraph init failed (exit ${result.code})`,
-						success ? "info" : "error",
-					);
-				}
-				pi.sendMessage(
-					{ customType: "codegraph-init", content: out, display: true },
-					{ triggerTurn: false },
-				);
-			} finally {
-				updateStatusBar(ctx, await isIndexed(ctx.cwd));
-			}
-		},
-	});
-
-	// ── /codegraph-sync ────────────────────────────────────────────────────
-	pi.registerCommand("codegraph-sync", {
-		description: "Sync CodeGraph changes since last index (codegraph sync)",
-		handler: async (args, ctx) => {
-			if (!(await ensureCli(pi))) {
-				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
-				return;
-			}
-			const target = args?.trim() || ctx.cwd;
-			if (ctx.hasUI) {
-				ctx.ui.notify(`Syncing CodeGraph for ${target}…`, "info");
-			}
-			updateStatusBar(ctx, "sync");
-			try {
-				const result = await execCg(pi, ["sync", target], { timeout: 300_000 });
-				const out = outputOf(result);
-				if (ctx.hasUI) {
-					ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
-				}
-				pi.sendMessage(
-					{ customType: "codegraph-sync", content: out, display: true },
-					{ triggerTurn: false },
-				);
-			} finally {
-				updateStatusBar(ctx, await isIndexed(ctx.cwd));
-			}
-		},
-	});
-
-	// ── /codegraph-status ──────────────────────────────────────────────────
-	pi.registerCommand("codegraph-status", {
-		description: "Show CodeGraph index status and statistics",
-		handler: async (args, ctx) => {
-			if (!(await ensureCli(pi))) {
-				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
-				return;
-			}
-			const target = args?.trim() || ctx.cwd;
-			const result = await execCg(pi, ["status", target], { timeout: 30_000 });
-			const out = outputOf(result);
-			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
-			updateStatusBar(ctx, await isIndexed(ctx.cwd));
-			pi.sendMessage(
-				{ customType: "codegraph-status", content: out, display: true },
-				{ triggerTurn: false },
-			);
-		},
-	});
-
-	// ── /codegraph-unlock ──────────────────────────────────────────────────
-	pi.registerCommand("codegraph-unlock", {
-		description: "Release stale CodeGraph database lock (codegraph unlock)",
-		handler: async (args, ctx) => {
-			if (!(await ensureCli(pi))) {
-				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
-				return;
-			}
-			const target = args?.trim() || ctx.cwd;
-			const result = await execCg(pi, ["unlock", target], { timeout: 10_000 });
-			const out = outputOf(result);
-			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
-			pi.sendMessage(
-				{ customType: "codegraph-unlock", content: out, display: true },
-				{ triggerTurn: false },
-			);
-		},
-	});
-
-	// ── resources_discover: contribute the skill only when the CLI exists ──
-	pi.on("resources_discover", async () => {
-		return {
-			skillPaths: [fileURLToPath(new URL("../skills/codegraph/SKILL.md", import.meta.url))],
-		};
-	});
-
-	// ── session_start: incremental sync + context hint ────────────────────
-	pi.on("session_start", async (event, ctx) => {
-		const indexed = await isIndexed(ctx.cwd);
-		if (indexed) {
-			updateStatusBar(ctx, "sync");
-			// Incremental sync; near-zero cost when nothing changed.
-			void execCg(pi, ["sync", "-q", ctx.cwd], { timeout: 300_000 })
-				.catch(() => {})
-				.finally(async () => {
-					updateStatusBar(ctx, await isIndexed(ctx.cwd));
-				});
-		} else {
-			updateStatusBar(ctx, false);
-		}
-
-		// Inject the agent playbook once per process when the project IS
-		// indexed (upstream does this via MCP initialize instructions). Skip
-		// "reload": extensions rebind in place and the message would duplicate.
-		if (event.reason !== "reload" && indexed) {
-			pi.sendMessage(
-				{ customType: "codegraph-context", content: INDEX_HINT, display: false },
-				{ triggerTurn: false },
-			);
-		}
-	});
-
-	pi.on("session_shutdown", async (_event, ctx) => {
-		if (ctx.hasUI) {
-			ctx.ui.setStatus("codegraph", undefined);
-		}
-	});
-}
+// pi-codegraph — pi extension
+//
+// CodeGraph support for pi: codegraph_explore tool, /codegraph-init,
+// /codegraph-sync, /codegraph-status, and /codegraph-unlock commands.
+//
+// Bridges to CodeGraph by executing the CLI (see docs/adr/0001). Requires the
+// codegraph CLI on PATH: npm i -g @colbymchenry/codegraph
+// Upstream: https://github.com/colbymchenry/codegraph
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { TSchema, Type } from "typebox";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const INSTALL_HINT =
+	"未检测到 codegraph CLI（PATH 中无 codegraph 命令），本插件未注入任何工具、命令或技能。" +
+	"安装：npm i -g @colbymchenry/codegraph，然后 /reload 或重启 pi 生效。";
+
+// Whole-process dedup for the missing-CLI hint: extensions re-run per session and
+// per subagent (separate jiti module copies), so gate on globalThis.
+const MISSING_CLI_HINTED = Symbol.for("pi-codegraph.missing-cli-hinted");
+
+// Result of `codegraph version` this session — null until first check.
+let cliAvailable: boolean | null = null;
+
+async function execCg(
+	pi: ExtensionAPI,
+	args: string[],
+	options: { signal?: AbortSignal; timeout?: number; cwd?: string } = {},
+) {
+	if (process.platform === "win32") {
+		return await pi.exec("cmd.exe", ["/d", "/s", "/c", "codegraph", ...args], options);
+	}
+	return await pi.exec("codegraph", args, options);
+}
+
+async function ensureCli(pi: ExtensionAPI): Promise<boolean> {
+	if (cliAvailable !== null) return cliAvailable;
+	try {
+		const result = await execCg(pi, ["version"], { timeout: 10_000 });
+		cliAvailable = result.code === 0;
+	} catch {
+		cliAvailable = false;
+	}
+	return cliAvailable;
+}
+
+function textResult(text: string) {
+	return { content: [{ type: "text" as const, text }], details: undefined };
+}
+
+function outputOf(result: { stdout: string; stderr: string; code: number }): string {
+	return (result.stdout + result.stderr).trim() || `exit ${result.code}`;
+}
+
+async function isIndexed(cwd: string): Promise<boolean> {
+	try {
+		await fs.access(path.join(cwd, ".codegraph", "codegraph.db"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+type StatusState = "index" | "sync" | "init" | boolean | undefined;
+
+function updateStatusBar(ctx: ExtensionContext, state: StatusState) {
+	if (!ctx.hasUI) return;
+	const label = state === true ? "index" : state === false ? undefined : state;
+	if (label) {
+		const text = ctx.ui.theme?.fg
+			? `${ctx.ui.theme.fg("accent", "⬡")} ${label}`
+			: `⬡ ${label}`;
+		ctx.ui.setStatus("codegraph", text);
+	} else {
+		ctx.ui.setStatus("codegraph", undefined);
+	}
+}
+
+// 仿照上游 MCP SERVER_INSTRUCTIONS（src/mcp/server-instructions.ts）编写：引导智能体
+// 在 grep/read 之前优先使用 codegraph 工具，并给出反模式与过期处理。提示内容按实际
+// 启用的工具集生成：未开启的工具绝不被宣传（见 docs/adr/0003），避免智能体调用
+// 不存在的工具。
+const EXPLORE_HINT_LINE =
+	"`codegraph_explore` — 一次调用完成广泛探索：相关符号的源码 + 调用路径。" +
+	"可以点名端点符号（如 `mutateElement renderScene`）以跨越动态分派跳转揭示调用路径。";
+
+const EXTRA_TOOL_HINT_LINES: Record<string, string> = {
+	codegraph_query: "`codegraph_query` — 定位符号：位置 + 签名，不含源码。",
+	codegraph_node:
+		"`codegraph_node` — 单个符号的源码 + 调用/被调轨迹（可链式追踪调用图）。",
+	codegraph_callers: "`codegraph_callers` — 谁调用了某符号。",
+	codegraph_callees: "`codegraph_callees` — 某符号调用了什么。",
+	codegraph_impact: "`codegraph_impact` — 修改某符号的影响范围（编辑前调用）。",
+	codegraph_files: "`codegraph_files` — 已建索引的文件树（tree/flat/grouped 按语言分组）。",
+};
+
+const HIDDEN_TOOLS_NOTE =
+	"细粒度工具（`codegraph_query` `codegraph_node` `codegraph_callers` `codegraph_callees` " +
+	"`codegraph_impact` `codegraph_files`）默认隐藏以保持工具列表精简，只有用户通过配置开启后才会注册" +
+	"（全局 `~/.pi/agent/extensions/pi-codegraph/config.json` 或项目 `.pi/extensions/pi-codegraph/config.json` 的 " +
+	"`extraTools`）——当前会话请勿调用它们。";
+
+function buildIndexHint(enabled: Set<string>): string {
+	const lines = [
+		"# CodeGraph — 本项目已建立索引",
+		"",
+		"这里存在 `.codegraph/` 索引：项目每个符号、边、文件构成的 SQLite 知识图谱（支持 30+ 语言）。" +
+			"它可以回答结构性问题，并给出逐字、带行号的源码（把 codegraph 输出视为已经 Read 过的内容，可直接据此编辑）。",
+		"",
+		"- 对于结构性问题（X 如何工作 / X 在哪里 / 谁调用 Y / 修改 Z 会破坏什么），应使用 codegraph 工具" +
+			"而不是 grep + read——通常一次调用即可完整回答。",
+		`- ${EXPLORE_HINT_LINE}`,
+	];
+	for (const name of Object.keys(EXTRA_TOOL_HINT_LINES)) {
+		if (enabled.has(name)) lines.push(`- ${EXTRA_TOOL_HINT_LINES[name]}`);
+	}
+	lines.push(
+		enabled.size === 0
+			? `- ${HIDDEN_TOOLS_NOTE}`
+			: "- 以上细粒度工具已通过 `extraTools` 配置开启。",
+	);
+	lines.push(
+		"- 反模式：不要先用 grep 或 Read；不要用 grep 重复验证 codegraph 输出（基于 AST，比 grep 更准确）；不要手工重建调用流程。",
+		'- "Already sent earlier in this conversation"：该提示表示内容已在会话上下文中——不要重新获取或 Read。',
+		'- 过期提示：如果工具输出包含 "⚠️ Some files referenced below were edited since the last index sync"，只直接读取其中被标记的文件。',
+		"- 多项目 / Monorepo：传入 `path` 查询任意已建索引的子项目目录。",
+		"- 项目没有 `.codegraph/` 时，在该项目使用内置工具；是否建索引由用户决定——必要时建议 /codegraph-init。",
+	);
+	return lines.join("\n");
+}
+
+// ── 配置：细粒度工具 opt-in（docs/adr/0003）───────────────────────────
+// 全局配置在 ~/.pi/agent/extensions/pi-codegraph/config.json，项目配置在
+// .pi/extensions/pi-codegraph/config.json（覆盖全局，仅对受信任项目生效）。
+// 结构为扁平 JSON：{ "extraTools": ["node", "impact"] }。pi 没有第三方
+// 扩展配置 API，故由扩展自行读取这两个文件。
+type CgConfig = { extraTools?: string[] | "all" };
+
+const CONFIG_REL_PATH = path.join("extensions", "pi-codegraph", "config.json");
+
+async function readConfigFile<T>(file: string): Promise<T | undefined> {
+	try {
+		const raw = await fs.readFile(file, "utf8");
+		return JSON.parse(raw) as T;
+	} catch {
+		return undefined;
+	}
+}
+
+async function loadCgConfig(ctx: ExtensionContext): Promise<CgConfig> {
+	const global = await readConfigFile<CgConfig>(path.join(getAgentDir(), CONFIG_REL_PATH));
+	let project: CgConfig | undefined;
+	if (ctx.isProjectTrusted()) {
+		project = await readConfigFile<CgConfig>(path.join(ctx.cwd, CONFIG_DIR_NAME, CONFIG_REL_PATH));
+	}
+	return { ...(global ?? {}), ...(project ?? {}) };
+}
+
+// When the CLI is absent, register nothing but a one-shot hint handler: no
+// tools, no commands, no resources_discover (so no skill injection), no sync.
+export function registerMissingCliHint(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		if ((globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED]) return;
+		(globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED] = true;
+		if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "warning");
+	});
+}
+
+export default async function codegraphExtension(pi: ExtensionAPI) {
+	if (!(await ensureCli(pi))) {
+		registerMissingCliHint(pi);
+		return;
+	}
+	// ── codegraph_explore tool ─────────────────────────────────────────────
+	pi.registerTool({
+		name: "codegraph_explore",
+		label: "CodeGraph Explore",
+		description:
+			"Broad code exploration in one shot: relevant symbols' verbatim line-numbered source, call paths between them, and a blast-radius summary.",
+		promptSnippet:
+			"codegraph_explore: symbol source + call paths in one shot from the project's CodeGraph index",
+		promptGuidelines: [
+			"For structural code questions (how does X work, where is X, what breaks if I change X), prefer codegraph_explore over grep when the project has a .codegraph/ index.",
+			"Indexing is the user's decision — never run codegraph init yourself; suggest /codegraph-init instead.",
+		],
+		parameters: Type.Object({
+			query: Type.String({
+				description: "Symbol names or a natural-language question about the code",
+			}),
+			path: Type.Optional(
+				Type.String({
+					description: "Project path (default: cwd)",
+				}),
+			),
+			maxFiles: Type.Optional(
+				Type.Integer({
+					description: "Maximum number of files to include source from",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+			if (!(await ensureCli(pi))) return textResult(INSTALL_HINT);
+			const cwd = params.path ?? ctx.cwd;
+			const args = ["explore", params.query, "-p", cwd];
+			if (typeof params.maxFiles === "number" && params.maxFiles > 0) {
+				args.push("--max-files", String(params.maxFiles));
+			}
+			const result = await execCg(pi, args, {
+				signal,
+				timeout: 120_000,
+			});
+			if (result.killed) return textResult("codegraph explore timed out (120s)");
+			// Non-zero exits carry upstream's agent-friendly guidance (e.g. the
+			// "not initialized" message) — pass it through verbatim.
+			if (result.code !== 0) return textResult(outputOf(result));
+			return textResult(result.stdout.trim());
+		},
+	});
+
+	// ── codegraph_* fine-grained tools (CLI parity with the MCP tools) ────
+	// Each maps 1:1 to a codegraph CLI subcommand; `path` selects the project,
+	// defaults to the session cwd (same convention as codegraph_explore).
+	const projectPath = () =>
+		Type.Optional(
+			Type.String({
+				description: "Project path (default: cwd)",
+			}),
+		);
+
+	type CliToolDef = {
+		name: string;
+		label: string;
+		description: string;
+		snippet: string;
+		guidelines: string[];
+		subcommand: string;
+		parameters: TSchema;
+		positional?: (p: Record<string, unknown>) => string[];
+		flags?: (p: Record<string, unknown>) => string[];
+		timeout?: number;
+	};
+
+	function registerCliTool(pi: ExtensionAPI, def: CliToolDef) {
+		pi.registerTool({
+			name: def.name,
+			label: def.label,
+			description: def.description,
+			promptSnippet: def.snippet,
+			promptGuidelines: def.guidelines,
+			parameters: def.parameters,
+			execute: async (_toolCallId, params: Record<string, unknown>, signal, _onUpdate, ctx) => {
+				const cwd = (params.path as string | undefined) ?? ctx.cwd;
+				const args = [
+					def.subcommand,
+					...(def.positional?.(params) ?? []),
+					"-p",
+					cwd,
+					...(def.flags?.(params) ?? []),
+				];
+				const result = await execCg(pi, args, {
+					signal,
+					timeout: def.timeout ?? 60_000,
+				});
+				if (result.killed) return textResult(`codegraph ${def.subcommand} timed out`);
+				// Non-zero exits carry upstream's agent-friendly guidance — pass it through.
+				if (result.code !== 0) return textResult(outputOf(result));
+				return textResult(result.stdout.trim());
+			},
+		});
+	}
+
+	const cliTools: CliToolDef[] = [
+		{
+			name: "codegraph_query",
+			label: "CodeGraph Query",
+			description:
+				"Search symbols by name. Returns locations and signatures only (no source). Use to locate where a symbol is declared.",
+			snippet: "codegraph_query: symbol locations + signatures by name",
+			guidelines: [
+				"To locate where a symbol is declared (kind, file, line), use codegraph_query before grep.",
+			],
+			subcommand: "query",
+			parameters: Type.Object({
+				search: Type.String({ description: "Symbol name or partial name to search" }),
+				kind: Type.Optional(
+					Type.String({
+						description:
+							"Filter by node kind: function, method, class, interface, type, variable, route, component",
+					}),
+				),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 10)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.search as string],
+			flags: (p) => [
+				...(p.kind ? ["--kind", p.kind as string] : []),
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_node",
+			label: "CodeGraph Node",
+			description:
+				"One symbol's source plus its caller/callee trail. Chain it to follow a call graph across files.",
+			snippet: "codegraph_node: a symbol's source + caller/callee trail",
+			guidelines: [
+				"To deep-dive one known symbol (verbatim source + who it calls / is called by), use codegraph_node.",
+			],
+			subcommand: "node",
+			parameters: Type.Object({
+				name: Type.String({ description: "Symbol name to inspect" }),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.name as string],
+		},
+		{
+			name: "codegraph_callers",
+			label: "CodeGraph Callers",
+			description: "Find all functions or methods that call a specific symbol.",
+			snippet: "codegraph_callers: who calls a symbol",
+			guidelines: [
+				"To find what calls a symbol (reverse dependencies), use codegraph_callers.",
+			],
+			subcommand: "callers",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callers to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_callees",
+			label: "CodeGraph Callees",
+			description: "Find all functions or methods that a specific symbol calls.",
+			snippet: "codegraph_callees: what a symbol calls",
+			guidelines: [
+				"To find what a symbol calls (its outgoing edges), use codegraph_callees.",
+			],
+			subcommand: "callees",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callees to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_impact",
+			label: "CodeGraph Impact",
+			description: "Analyze what code is affected by changing a symbol (blast radius).",
+			snippet: "codegraph_impact: blast radius of changing a symbol",
+			guidelines: [
+				"Before editing a symbol, use codegraph_impact to see what depends on it.",
+			],
+			subcommand: "impact",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name to analyze impact of changing" }),
+				depth: Type.Optional(Type.Integer({ description: "Traversal depth (default 2)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.depth === "number" && p.depth > 0 ? ["--depth", String(p.depth)] : []),
+			],
+		},
+		{
+			name: "codegraph_files",
+			label: "CodeGraph Files",
+			description:
+				"Show the indexed project's file structure (tree, flat, or grouped by language), with per-file symbol counts.",
+			snippet: "codegraph_files: indexed file tree with symbol counts",
+			guidelines: [
+				"To get a structured view of the project files, use codegraph_files.",
+			],
+			subcommand: "files",
+			parameters: Type.Object({
+				dir: Type.Optional(Type.String({ description: "Subdirectory within the project to show" })),
+				pattern: Type.Optional(Type.String({ description: "Glob pattern to filter files" })),
+				format: Type.Optional(
+					Type.Union([Type.Literal("tree"), Type.Literal("flat"), Type.Literal("grouped")]),
+				),
+				maxDepth: Type.Optional(Type.Integer({ description: "Maximum directory depth for tree format" })),
+				path: projectPath(),
+			}),
+			positional: (p) => (p.dir ? [p.dir as string] : []),
+			flags: (p) => [
+				...(p.pattern ? ["--pattern", p.pattern as string] : []),
+				...(p.format ? ["--format", p.format as string] : []),
+				...(typeof p.maxDepth === "number" && p.maxDepth > 0
+					? ["--max-depth", String(p.maxDepth)]
+					: []),
+			],
+		},
+	];
+
+	// 细粒度工具为 opt-in：仅当配置开启时才注册，保证默认工具列表精简（见
+	// docs/adr/0003）。`registeredExtraTools` 防止同一进程内重复注册；
+	// `enabledExtraTools` 同时驱动活动工具集与注入的提示内容。
+	const registeredExtraTools = new Set<string>();
+	let enabledExtraTools = new Set<string>();
+
+	const extraToolKey = (def: CliToolDef) => def.name.replace(/^codegraph_/, "");
+
+	function resolveExtraTools(cfg: CgConfig, ctx: ExtensionContext): Set<string> {
+		const enabled = new Set<string>();
+		const wanted = cfg.extraTools ?? [];
+		const names = wanted === "all" ? cliTools.map((d) => d.name) : wanted;
+		for (const item of names) {
+			const key = typeof item === "string" ? item.trim() : "";
+			const def = cliTools.find((d) => d.name === key || extraToolKey(d) === key);
+			if (def) {
+				enabled.add(def.name);
+			} else if (key && ctx.hasUI) {
+				ctx.ui.notify(`codegraph: unknown extra tool "${item}" (ignored)`, "warning");
+			}
+		}
+		return enabled;
+	}
+
+	function applyExtraTools(pi: ExtensionAPI, cfg: CgConfig, ctx: ExtensionContext) {
+		enabledExtraTools = resolveExtraTools(cfg, ctx);
+		for (const def of cliTools) {
+			if (enabledExtraTools.has(def.name) && !registeredExtraTools.has(def.name)) {
+				registerCliTool(pi, def);
+				registeredExtraTools.add(def.name);
+			}
+		}
+		// 将活动工具集与配置对齐：此前已注册但当前未启用的工具（例如切换项目后）
+		// 不得再出现在系统提示中。
+		const active = new Set(pi.getActiveTools());
+		const extraNames = new Set(cliTools.map((d) => d.name));
+		let changed = false;
+		for (const name of extraNames) {
+			if (enabledExtraTools.has(name) && !active.has(name)) {
+				active.add(name);
+				changed = true;
+			} else if (!enabledExtraTools.has(name) && active.has(name)) {
+				active.delete(name);
+				changed = true;
+			}
+		}
+		if (changed) pi.setActiveTools([...active]);
+	}
+
+	// ── /codegraph-init ────────────────────────────────────────────────────
+	pi.registerCommand("codegraph-init", {
+		description: "Build the CodeGraph index for the current project (codegraph init)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Indexing ${target} — can take minutes on a large repo…`, "info");
+			}
+			updateStatusBar(ctx, "init");
+			try {
+				const result = await execCg(pi, ["init", target], { timeout: 1_800_000 });
+				const out = outputOf(result);
+				const success = result.code === 0;
+				if (ctx.hasUI) {
+					ctx.ui.notify(
+						success ? "CodeGraph index built." : `codegraph init failed (exit ${result.code})`,
+						success ? "info" : "error",
+					);
+				}
+				pi.sendMessage(
+					{ customType: "codegraph-init", content: out, display: true },
+					{ triggerTurn: false },
+				);
+			} finally {
+				updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			}
+		},
+	});
+
+	// ── /codegraph-sync ────────────────────────────────────────────────────
+	pi.registerCommand("codegraph-sync", {
+		description: "Sync CodeGraph changes since last index (codegraph sync)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Syncing CodeGraph for ${target}…`, "info");
+			}
+			updateStatusBar(ctx, "sync");
+			try {
+				const result = await execCg(pi, ["sync", target], { timeout: 300_000 });
+				const out = outputOf(result);
+				if (ctx.hasUI) {
+					ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+				}
+				pi.sendMessage(
+					{ customType: "codegraph-sync", content: out, display: true },
+					{ triggerTurn: false },
+				);
+			} finally {
+				updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			}
+		},
+	});
+
+	// ── /codegraph-status ──────────────────────────────────────────────────
+	pi.registerCommand("codegraph-status", {
+		description: "Show CodeGraph index status and statistics",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			const result = await execCg(pi, ["status", target], { timeout: 30_000 });
+			const out = outputOf(result);
+			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+			updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			pi.sendMessage(
+				{ customType: "codegraph-status", content: out, display: true },
+				{ triggerTurn: false },
+			);
+		},
+	});
+
+	// ── /codegraph-unlock ──────────────────────────────────────────────────
+	pi.registerCommand("codegraph-unlock", {
+		description: "Release stale CodeGraph database lock (codegraph unlock)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			const result = await execCg(pi, ["unlock", target], { timeout: 10_000 });
+			const out = outputOf(result);
+			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+			pi.sendMessage(
+				{ customType: "codegraph-unlock", content: out, display: true },
+				{ triggerTurn: false },
+			);
+		},
+	});
+
+	// ── resources_discover: contribute the skill only when the CLI exists ──
+	pi.on("resources_discover", async () => {
+		return {
+			skillPaths: [fileURLToPath(new URL("../skills/codegraph/SKILL.md", import.meta.url))],
+		};
+	});
+
+	// ── session_start：opt-in 工具 + 增量同步 + 上下文提示 ───────────────
+	pi.on("session_start", async (event, ctx) => {
+		const cfg = await loadCgConfig(ctx);
+		applyExtraTools(pi, cfg, ctx);
+		const indexed = await isIndexed(ctx.cwd);
+		if (indexed) {
+			updateStatusBar(ctx, "sync");
+			// Incremental sync; near-zero cost when nothing changed.
+			void execCg(pi, ["sync", "-q", ctx.cwd], { timeout: 300_000 })
+				.catch(() => {})
+				.finally(async () => {
+					updateStatusBar(ctx, await isIndexed(ctx.cwd));
+				});
+		} else {
+			updateStatusBar(ctx, false);
+		}
+
+		// Inject the agent playbook once per process when the project IS
+		// indexed (upstream does this via MCP initialize instructions). Skip
+		// "reload": extensions rebind in place and the message would duplicate.
+		if (event.reason !== "reload" && indexed) {
+			pi.sendMessage(
+				{ customType: "codegraph-context", content: buildIndexHint(enabledExtraTools), display: false },
+				{ triggerTurn: false },
+			);
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx.hasUI) {
+			ctx.ui.setStatus("codegraph", undefined);
+		}
+	});
+}

package/package.json

@@ -1,43 +1,43 @@
-{
-	"name": "@liuxincuit/pi-codegraph",
-	"version": "0.1.1",
-	"description": "CodeGraph support for pi — symbol source + call paths via the codegraph CLI",
-	"type": "module",
-	"keywords": [
-		"pi-package",
-		"codegraph",
-		"code-intelligence",
-		"knowledge-graph"
-	],
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/liuxincuit/pi-codegraph.git"
-	},
-	"author": "liuxincuit",
-	"license": "MIT",
-	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*"
-	},
-	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
-		"@types/node": "^22.0.0",
-		"typebox": "^1.3.7",
-		"typescript": "^5.5.0"
-	},
-	"scripts": {
-		"typecheck": "tsc --noEmit",
-		"smoke": "tsc extensions/codegraph.ts --outDir .smoke-build --module esnext --target es2022 --moduleResolution bundler --skipLibCheck --noEmit false && node smoke.mjs"
-	},
-	"pi": {
-		"extensions": [
-			"./extensions"
-		]
-	},
-	"files": [
-		"extensions/",
-		"skills/",
-		"CONTEXT.md",
-		"README.md",
-		"LICENSE"
-	]
-}
+{
+	"name": "@liuxincuit/pi-codegraph",
+	"version": "0.1.3",
+	"description": "CodeGraph support for pi — symbol source + call paths via the codegraph CLI",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"codegraph",
+		"code-intelligence",
+		"knowledge-graph"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/liuxincuit/pi-codegraph.git"
+	},
+	"author": "liuxincuit",
+	"license": "MIT",
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@types/node": "^22.0.0",
+		"typebox": "^1.3.7",
+		"typescript": "^5.5.0"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"smoke": "tsc extensions/codegraph.ts --outDir .smoke-build --module esnext --target es2022 --moduleResolution bundler --skipLibCheck --noEmit false && node smoke.mjs"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions"
+		]
+	},
+	"files": [
+		"extensions/",
+		"skills/",
+		"CONTEXT.md",
+		"README.md",
+		"LICENSE"
+	]
+}

package/skills/codegraph/SKILL.md

@@ -1,27 +1,43 @@
----
-name: codegraph
-description: Query the project's CodeGraph index (symbol source + call paths) via the codegraph_explore tool. Use when answering structural code questions — how X works, where X is, what a change affects — in a project that has a .codegraph/ index.
----
-
-# CodeGraph
-
-The `codegraph_explore` tool answers structural code questions in one shot: the relevant symbols' verbatim line-numbered source, the call paths between them, and a blast-radius summary. It reads the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI.
-
-## When to use
-
-- "How does X work?" / "Where is X?" / "What calls Y?" / "What breaks if I change Z?"
-- Before an edit, to map the symbols you are about to touch and inspect the blast radius.
-- Prefer it over grep/read for structural exploration **when the project has a `.codegraph/` index**.
-
-## How to query
-
-- `query`: symbol names (`CodeGraph open`, `MCPSession`), endpoint flows (`mutateElement renderScene`), or a natural-language question. Naming a file or symbol returns its current line-numbered source.
-- `path`: optional project path. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
-- `maxFiles`: optional integer to limit how many file sources are returned.
-
-## Anti-patterns & Guidance
-
-- **Trust AST results.** Don't re-verify codegraph output with grep.
-- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
-- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
-- **No index, no tool.** If the output says the project isn't indexed, stop calling `codegraph_explore` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.
+---
+name: codegraph
+description: 通过 codegraph_explore 工具查询项目的 CodeGraph 索引（符号源码、调用路径、影响范围）。当回答结构化代码问题——X 如何工作、X 在哪里、谁调用 Y、修改某处会影响什么——且项目存在 .codegraph/ 索引时使用。
+---
+
+# CodeGraph
+
+`codegraph_explore` 工具从项目的 CodeGraph 索引（`.codegraph/`，由 `codegraph` CLI 建立与维护）回答结构化代码问题。**当项目存在 `.codegraph/` 索引时**，应优先使用它而不是 grep/read。
+
+## 默认工具
+
+- `codegraph_explore` — 一次调用完成广泛探索：相关符号的源码 + 调用路径。可以点名端点符号（`mutateElement renderScene`）以跨越动态分派跳转揭示调用路径。参数：`query`（符号名或自然语言问题）、可选 `maxFiles`（限制返回源码行数）。
+
+绝大多数结构化问题只需 `codegraph_explore` 即可解决。该工具始终注册。
+
+## 细粒度工具（可选开启）
+
+以下细粒度工具**默认隐藏**，以保持工具列表精简。它们只有在用户通过配置 `extraTools` 开启后才会注册；开启之前调用会报 "tool not found"。除非能在 `Available tools` 中看到它们，否则不要调用。
+
+- `codegraph_query` — 定位符号：位置 + 签名，不含源码。
+- `codegraph_node` — 单个已知符号的逐字源码 + 调用/被调轨迹，可链式追踪调用图。
+- `codegraph_callers` / `codegraph_callees` — 谁调用了某符号 / 某符号调用了什么。
+- `codegraph_impact` — 修改某符号的影响范围；编辑前调用。
+- `codegraph_files` — 已建索引的文件树（tree/flat/grouped 按语言分组）与符号数量。
+
+开启方式：在 `~/.pi/agent/extensions/pi-codegraph/config.json`（全局）或 `.pi/extensions/pi-codegraph/config.json`（项目，覆盖全局）中配置：
+
+```json
+{ "extraTools": ["query", "node", "impact"] }
+```
+
+短名（`node`、`impact`）与完整工具名（`codegraph_node`）均可，`"extraTools": "all"` 开启全部。配置在下一个会话生效（`/reload` 或重启 pi）。如果反复需要某个隐藏工具，可以向用户建议此配置。
+
+## 如何查询
+
+- `codegraph_explore` 接受 `path` 参数：要查询的项目目录，默认为当前工作目录。在 monorepo 中，传入包含 `.codegraph/` 的子项目目录。
+
+## 反模式与指导
+
+- **信任 AST 结果。** 不要用 grep 重复验证 codegraph 输出。
+- **Already sent earlier in this conversation。** 当出现该提示时，内容已在会话上下文中——回看上下文，不要重新获取或 Read。
+- **过期提示。** 如果输出警告 `⚠️ Some files referenced below were edited since the last index sync`，只直接读取其中被标记的文件；其余内容仍然新鲜。
+- **无索引不可用。** 如果输出提示项目未建索引，本会话内停止对该项目调用 `codegraph_explore`，改用内置工具。是否建索引由用户决定——适当时建议用户运行 `/codegraph-init`。