@trim21/personal-pi-extensions 0.1.683 → 0.1.684

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.683",
+  "version": "0.1.684",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/aft/schemas.ts

@@ -0,0 +1,246 @@
+/**
+ * AFT 感知工具的结构化结果 schema。
+ *
+ * 载荷就是引擎自己的响应字段（去掉 envelope 的 request id），外加一个 `text`——我们自己
+ * 渲染（或引擎渲染）的文本，与工具输出一致。字段名与类型来自三处证据：
+ *
+ * - 本仓库对真引擎的实测响应（outline 两种模式、zoom，见 `test/fixtures/aft/`）；
+ * - `@cortexkit/aft-bridge` 自己的格式化器读哪些字段（callgraph 各 op、zoom 的注解）；
+ * - 引擎的 `ListEnvelope` / 截断字段（walk_truncated、collection_truncated、truncated）。
+ *
+ * 两条刻意的宽松：
+ *
+ * 1. 所有引擎字段都是可选、且允许额外字段（`additionalProperties: true`）。引擎不归我们
+ *    管，它的响应会加字段、换字段名；声明成必需会让版本一升级就把工具调用变成失败。
+ * 2. 嵌套条目（callgraph 的调用点、搜索命中等）把已知字段列全但全部可选——引擎自己也用
+ *    `?? "(unknown)"` 兜底，说明这些字段并非永远在场。
+ *
+ * 载荷只经总线 `Value.Parse` 复核一次（见 `src/lib/tool-bus.ts`），因此「宽松」不等于
+ * 不校验：`text` 必需，列出的字段类型必须对得上。
+ */
+
+import { Type } from "typebox";
+
+/** 引擎渲染的文本，与工具输出一致。 */
+const text = Type.String({ description: "引擎渲染的文本，与工具输出一致" });
+
+/** 行号区间（zoom）：引擎的 Range 序列化时行号从 1 开始。 */
+const rangeSchema = Type.Object(
+  {
+    start_line: Type.Number(),
+    end_line: Type.Number(),
+    start_col: Type.Optional(Type.Number()),
+    end_col: Type.Optional(Type.Number()),
+  },
+  { additionalProperties: true },
+);
+
+/** 调用图注解里的一条引用（zoom 的 calls_out / called_by）。 */
+const callRefSchema = Type.Object(
+  {
+    name: Type.String(),
+    line: Type.Number(),
+    /** 同一行上还有多少条同类引用被折叠。 */
+    extra_count: Type.Optional(Type.Number()),
+  },
+  { additionalProperties: true },
+);
+
+/** `aft_outline`：单文件模式只有 text（引擎不返回符号树），files 模式带文件条目。 */
+export const aftOutlineStructuredSchema = Type.Object(
+  {
+    text,
+    /** 引擎是否确定给全了结果。 */
+    complete: Type.Optional(Type.Boolean()),
+    /** files 模式（目录 + files: true）的文件条目。 */
+    files: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            path: Type.String(),
+            language: Type.String(),
+            /** 顶层符号数；未知时引擎省略该字段。 */
+            symbols: Type.Optional(Type.Number()),
+            /** 行数；null 表示不在索引里（line_count_gaps 列出这些文件）。 */
+            lines: Type.Union([Type.Number(), Type.Null()]),
+          },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    /** 目录遍历触到上限。 */
+    walk_truncated: Type.Optional(Type.Boolean()),
+    /** 条目收集触到上限。 */
+    collection_truncated: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: true },
+);
+
+/** `aft_zoom`：单符号源码 + 行号区间 + 同文件调用注解。 */
+export const aftZoomStructuredSchema = Type.Object(
+  {
+    text,
+    /** 符号名；行范围模式是 "lines X-Y"，符号歧义时缺省。 */
+    name: Type.Optional(Type.String()),
+    /** function / class / method / lines / ambiguous_symbol … */
+    kind: Type.Optional(Type.String()),
+    range: Type.Optional(rangeSchema),
+    /** 符号源码（不含上下文行）。 */
+    content: Type.Optional(Type.String()),
+    context_before: Type.Optional(Type.Array(Type.String())),
+    context_after: Type.Optional(Type.Array(Type.String())),
+    annotations: Type.Optional(
+      Type.Object(
+        {
+          calls_out: Type.Optional(Type.Array(callRefSchema)),
+          called_by: Type.Optional(Type.Array(callRefSchema)),
+        },
+        { additionalProperties: true },
+      ),
+    ),
+  },
+  { additionalProperties: true },
+);
+
+/** 调用图上的一条位置（callers 的调用点、impact 的受害点）。 */
+const callgraphSiteSchema = Type.Object(
+  {
+    file: Type.Optional(Type.String()),
+    line: Type.Optional(Type.Number()),
+    /** callers 分组的调用符号名。 */
+    symbol: Type.Optional(Type.String()),
+    /** impact 的调用点符号名（与 caller_file 成对）。 */
+    caller_symbol: Type.Optional(Type.String()),
+    caller_file: Type.Optional(Type.String()),
+    /** impact：该调用点自身是入口（脚本常据此过滤）。 */
+    is_entry_point: Type.Optional(Type.Boolean()),
+    /** 仅按名字解析出来的边（可能指向同名符号）。 */
+    approximate: Type.Optional(Type.Boolean()),
+    /** "name_match" 等解析来源。 */
+    resolved_by: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+/** 调用链上的一跳（trace_to / trace_to_symbol）。 */
+const callgraphHopSchema = Type.Object(
+  {
+    symbol: Type.Optional(Type.String()),
+    file: Type.Optional(Type.String()),
+    line: Type.Optional(Type.Number()),
+    is_entry_point: Type.Optional(Type.Boolean()),
+    /** trace_data：该跳流转的变量名与流向。 */
+    variable: Type.Optional(Type.String()),
+    flow_type: Type.Optional(Type.String()),
+    approximate: Type.Optional(Type.Boolean()),
+    resolved_by: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+/**
+ * `aft_callgraph`：一个工具名下 6 个 op，响应形状各不同（callers 是分组列表、call_tree 是
+ * 树、impact 是扁平调用点、trace_to 是路径列表、trace_to_symbol 是单条路径、trace_data 是
+ * 数据流跳）。这里把各 op 的锚点与列表都列为可选字段，脚本按 op 取用。
+ */
+export const aftCallgraphStructuredSchema = Type.Object(
+  {
+    text,
+    /** 被查询的符号（callers / impact 的锚点）。 */
+    symbol: Type.Optional(Type.String()),
+    file: Type.Optional(Type.String()),
+    /** call_tree 根节点的锚点。 */
+    name: Type.Optional(Type.String()),
+    line: Type.Optional(Type.Number()),
+    signature: Type.Optional(Type.String()),
+    /** callers：按文件分组的调用点。 */
+    callers: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            file: Type.Optional(Type.String()),
+            callers: Type.Optional(Type.Array(callgraphSiteSchema)),
+          },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    /** call_tree 根节点的直接子节点（整棵树在 payload 里，这里只标出形状）。 */
+    children: Type.Optional(Type.Array(Type.Unknown())),
+    /** call_tree 节点是否解析到定义；false 且无子节点 = 未解析的叶子。 */
+    resolved: Type.Optional(Type.Boolean()),
+    total_callers: Type.Optional(Type.Number()),
+    total_affected: Type.Optional(Type.Number()),
+    affected_files: Type.Optional(Type.Number()),
+    /** impact 的参数表（改签名时要知道）。 */
+    parameters: Type.Optional(Type.Array(Type.String())),
+    /** trace_to：到目标符号的路径，每条路径是一串跳。 */
+    paths: Type.Optional(
+      Type.Array(
+        Type.Object(
+          { hops: Type.Optional(Type.Array(callgraphHopSchema)) },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    total_paths: Type.Optional(Type.Number()),
+    /** trace_to_symbol：单条最短路径（没有路径时为 null）。 */
+    path: Type.Optional(Type.Union([Type.Array(callgraphHopSchema), Type.Null()])),
+    /** trace_data：值在赋值/参数/返回间的流转。 */
+    hops: Type.Optional(Type.Array(callgraphHopSchema)),
+    depth_limited: Type.Optional(Type.Boolean()),
+    /** 因结果上限被折叠的条目数（引擎给的是数字，不是布尔）。 */
+    truncated: Type.Optional(Type.Number()),
+    /** 软失败（symbol_not_found / callgraph_building …）的错误码。 */
+    code: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+/** 搜索命中：常规 ranking 条目（symbol）与降级时的 grep 行共用一份宽条目。 */
+const searchHitSchema = Type.Object(
+  {
+    file: Type.Optional(Type.String()),
+    name: Type.Optional(Type.String()),
+    kind: Type.Optional(Type.String()),
+    start_line: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+    end_line: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+    /** "matching line" / "line range" / "[file summary]" / "GrepLine"。 */
+    location: Type.Optional(Type.String()),
+    score: Type.Optional(Type.Number()),
+    source: Type.Optional(Type.String()),
+    semantic_score: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+    lexical_score: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+    exact: Type.Optional(Type.Boolean()),
+    snippet: Type.Optional(Type.String()),
+    /** grep 行条目：行号、列号与命中文本。 */
+    line: Type.Optional(Type.Number()),
+    column: Type.Optional(Type.Number()),
+    line_text: Type.Optional(Type.String()),
+    match_text: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+/** `aft_search`：查询解释 + 命中列表 + 截断/降级状态。 */
+export const aftSearchStructuredSchema = Type.Object(
+  {
+    text,
+    query: Type.Optional(Type.String()),
+    /** 引擎对查询的最终解释（regex / literal / semantic / hybrid）。 */
+    interpreted_as: Type.Optional(Type.String()),
+    result_count: Type.Optional(Type.Number()),
+    complete: Type.Optional(Type.Boolean()),
+    /** 还有更多命中没给（与分页上限的区别由引擎的 envelope 说明）。 */
+    more_available: Type.Optional(Type.Boolean()),
+    engine_capped: Type.Optional(Type.Boolean()),
+    /** 语义索引状态：ready / building / disabled / unavailable / external。 */
+    semantic_status: Type.Optional(Type.String()),
+    results: Type.Optional(Type.Array(searchHitSchema)),
+    /** 引擎给出的警告（索引降级等），原样转发。 */
+    warnings: Type.Optional(Type.Array(Type.String())),
+    /** 软失败（search_lanes_unavailable …）的错误码。 */
+    code: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);

package/src/aft/tools.ts

@@ -20,18 +20,24 @@ import {
   type StatusSnapshot,
 } from "@cortexkit/aft-bridge";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
+import { type Static, type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { formatDisplayPath, formatSubtitlePath, resolvePathArg } from "../lib/path.js";
 import { type ToolPendant } from "../lib/pendant.js";
-import type { ToolBus } from "../lib/tool-bus.js";
+import { defineStructuredTool, type StructuredResult, type ToolBus } from "../lib/tool-bus.js";
 import {
   type AftState,
   callAftTool,
   resolveSessionId,
   SEMANTIC_INDEX_WAIT_TIMEOUT_MS,
 } from "./bridge.js";
+import {
+  aftCallgraphStructuredSchema,
+  aftOutlineStructuredSchema,
+  aftSearchStructuredSchema,
+  aftZoomStructuredSchema,
+} from "./schemas.js";
 
 /** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
 const OUTLINE_PROMPT = readFileSync(
@@ -79,6 +85,24 @@ export function compactArgs(args: Record<string, unknown>): Record<string, unkno
   );
 }
 
+/**
+ * 结构化载荷：引擎自己的响应字段（去掉 envelope 的 request id）原样给脚本，外加我们
+ * 渲染的文本。引擎的 `success` / `code` 保留在载荷里——软失败（symbol_not_found、
+ * callgraph_building、search_lanes_unavailable）是「工具跑成了、引擎给出否定答案」，
+ * 脚本据 `code` 分支，而不是被当成调用异常。
+ */
+function aftPayload<TOutput extends TSchema>(
+  response: Record<string, unknown>,
+  text: string,
+): StructuredResult<Static<TOutput>> {
+  const value: Record<string, unknown> = { ...response, text };
+  // envelope 的 request id 是传输层的事，不进载荷
+  delete value.id;
+  // 载荷是引擎响应的原样透传（schema 只声明我们确证过的字段，其余允许通过），所以
+  // 编译期只能断言；类型正确性由脚本侧的声明与总线运行期的 Value.Parse 复核共同保证。
+  return { ok: true, value: value as Static<TOutput> };
+}
+
 /** 人类视角的调用记录：input params + 与 LLM 相同的输出结果。 */
 function buildPendantMarkdown(params: {
   title: string;
@@ -127,60 +151,64 @@ const OutlineParams = Type.Object(
 );
 
 export function registerOutlineTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_outline",
-    label: "aft_outline",
-    description: [
-      "输出代码文件、目录的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
-      "用它在读取具体内容之前先了解文件结构。",
-      "深入了解某个符号用 aft_zoom；看跨文件调用关系用 aft_callgraph。",
-      "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）。只接受单个 target。",
-      "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
-    ].join("\n"),
-    promptSnippet: "Output structural outline of a file/directory",
-    promptGuidelines: [OUTLINE_PROMPT, AFT_GUIDELINES],
-    parameters: OutlineParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const target = coerceTargetParam(params.target);
-      if (typeof target !== "string" || target.length === 0) {
-        throw new Error("'target' must be a single path (array targets are not supported)");
-      }
-      const resolved = resolvePathArg(extCtx.cwd, target);
-      let filesMode = coerceBoolean(params.files);
-      if (params.files === undefined) {
-        const stats = await stat(resolved).catch(() => null);
-        filesMode = stats?.isDirectory() ?? false;
-      }
-      const rawArgs = compactArgs({
-        target: resolved,
-        files: filesMode || undefined,
-        includeTests: params.includeTests,
-      });
-
-      const subtitle = buildOutlineSubtitle(extCtx.cwd, target);
-
-      const { text, response } = await callAftTool(
-        bridgeFor(ctx),
-        "outline",
-        rawArgs,
-        resolveSessionId(extCtx),
-        undefined,
-        undefined,
-        signal,
-      );
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          params,
-          pendant: {
-            subtitle,
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_outline",
+      label: "aft_outline",
+      description: [
+        "输出代码文件、目录的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
+        "用它在读取具体内容之前先了解文件结构。",
+        "深入了解某个符号用 aft_zoom；看跨文件调用关系用 aft_callgraph。",
+        "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）。只接受单个 target。",
+        "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
+      ].join("\n"),
+      promptSnippet: "Output structural outline of a file/directory",
+      promptGuidelines: [OUTLINE_PROMPT, AFT_GUIDELINES],
+      parameters: OutlineParams,
+      structuredSchema: aftOutlineStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const target = coerceTargetParam(params.target);
+        if (typeof target !== "string" || target.length === 0) {
+          throw new Error("'target' must be a single path (array targets are not supported)");
+        }
+        const resolved = resolvePathArg(extCtx.cwd, target);
+        let filesMode = coerceBoolean(params.files);
+        if (params.files === undefined) {
+          const stats = await stat(resolved).catch(() => null);
+          filesMode = stats?.isDirectory() ?? false;
+        }
+        const rawArgs = compactArgs({
+          target: resolved,
+          files: filesMode || undefined,
+          includeTests: params.includeTests,
+        });
+
+        const subtitle = buildOutlineSubtitle(extCtx.cwd, target);
+
+        const { text, response } = await callAftTool(
+          bridgeFor(ctx),
+          "outline",
+          rawArgs,
+          resolveSessionId(extCtx),
+          undefined,
+          undefined,
+          signal,
+        );
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            params,
+            pendant: {
+              subtitle,
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftOutlineStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }
 
 /** 构建 aft_outline pendant 的 subtitle：`target="…"`（路径过长时显示上一级目录加文件名）。 */
@@ -211,61 +239,65 @@ const ZoomParams = Type.Object(
 );
 
 export function registerZoomTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_zoom",
-    label: "aft_zoom",
-    description: [
-      "查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 的标题段落内容。",
-      "需要理解某个具体符号时用它（读整个文件用 read）。",
-      "callgraph: true 时附带同文件内的调用关系标注。",
-      "同文件多符号用 `symbols` 数组。",
-    ].join("\n"),
-    promptSnippet: "Inspect the full source of a named symbol",
-    promptGuidelines: [ZOOM_PROMPT],
-    parameters: ZoomParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const rawArgs = compactArgs({
-        filePath: resolvePathArg(extCtx.cwd, params.path),
-        symbols: params.symbols,
-        contextLines: coerceOptionalInt(
-          params.contextLines,
-          "contextLines",
-          1,
-          Number.MAX_SAFE_INTEGER,
-        ),
-        callgraph: coerceBoolean(params.callgraph) || undefined,
-      });
-
-      const subtitle = buildZoomSubtitle(extCtx.cwd, params);
-
-      const { text, response } = await callAftTool(
-        bridgeFor(ctx),
-        "zoom",
-        rawArgs,
-        resolveSessionId(extCtx),
-        undefined,
-        undefined,
-        signal,
-      );
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          params,
-          pendant: {
-            subtitle,
-            markdown: buildPendantMarkdown({
-              title: "aft_zoom",
-              input: params,
-              output: text,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_zoom",
+      label: "aft_zoom",
+      description: [
+        "查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 的标题段落内容。",
+        "需要理解某个具体符号时用它（读整个文件用 read）。",
+        "callgraph: true 时附带同文件内的调用关系标注。",
+        "同文件多符号用 `symbols` 数组。",
+      ].join("\n"),
+      promptSnippet: "Inspect the full source of a named symbol",
+      promptGuidelines: [ZOOM_PROMPT],
+      parameters: ZoomParams,
+      structuredSchema: aftZoomStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const rawArgs = compactArgs({
+          filePath: resolvePathArg(extCtx.cwd, params.path),
+          symbols: params.symbols,
+          contextLines: coerceOptionalInt(
+            params.contextLines,
+            "contextLines",
+            1,
+            Number.MAX_SAFE_INTEGER,
+          ),
+          callgraph: coerceBoolean(params.callgraph) || undefined,
+        });
+
+        const subtitle = buildZoomSubtitle(extCtx.cwd, params);
+
+        const { text, response } = await callAftTool(
+          bridgeFor(ctx),
+          "zoom",
+          rawArgs,
+          resolveSessionId(extCtx),
+          undefined,
+          undefined,
+          signal,
+        );
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            params,
+            pendant: {
+              subtitle,
+              markdown: buildPendantMarkdown({
+                title: "aft_zoom",
+                input: params,
+                output: text,
+                truncated,
+              }),
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftZoomStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }
 
 /** 构建 aft_zoom pendant 的 subtitle：`path="…" symbol="…"`。 */
@@ -363,60 +395,64 @@ export async function callCallgraphWithBuildRetry(
 }
 
 export function registerCallgraphTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_callgraph",
-    label: "aft_callgraph",
-    description: [
-      "基于真实调用图回答代码关系问题（谁调用我、影响面、调用链），替代 grep + read 的链条式排查。",
-      "op 语义：callers=调用点（改名/改签名前用）；impact=影响面（改一个符号会波及谁）；",
-      "call_tree=该函数调用了什么；trace_to=从入口如何执行到某符号；",
-      "trace_to_symbol=两符号间最短路径（需 toSymbol，歧义时需 toPath）；trace_data=追踪值在参数/赋值间的流转（需 expression）。",
-      "标记：~ = 仅按名字解析的边（可能指向同名符号）；[unresolved] = 未解析到定义的调用点。",
-    ].join("\n"),
-    promptSnippet: "Call graph and data-flow navigation",
-    promptGuidelines: [CALLGRAPH_PROMPT],
-    parameters: CallgraphParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const rawArgs = compactArgs({
-        op: params.op,
-        filePath: resolvePathArg(extCtx.cwd, params.path),
-        symbol: params.symbol,
-        depth: coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER),
-        expression: params.expression,
-        toSymbol: params.toSymbol,
-        toFile: params.toPath ? resolvePathArg(extCtx.cwd, params.toPath) : undefined,
-        includeTests: params.includeTests,
-        includeUnresolved: params.includeUnresolved,
-      });
-
-      const { text, response } = await callCallgraphWithBuildRetry(
-        bridgeFor(ctx),
-        rawArgs,
-        extCtx,
-        signal,
-      );
-      const out =
-        text ||
-        formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {
-          includeUnresolved: coerceBoolean(params.includeUnresolved),
-        }).join("\n");
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text: out }],
-        details: {
-          truncated,
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "aft_callgraph",
-              input: params,
-              output: out,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_callgraph",
+      label: "aft_callgraph",
+      description: [
+        "基于真实调用图回答代码关系问题（谁调用我、影响面、调用链），替代 grep + read 的链条式排查。",
+        "op 语义：callers=调用点（改名/改签名前用）；impact=影响面（改一个符号会波及谁）；",
+        "call_tree=该函数调用了什么；trace_to=从入口如何执行到某符号；",
+        "trace_to_symbol=两符号间最短路径（需 toSymbol，歧义时需 toPath）；trace_data=追踪值在参数/赋值间的流转（需 expression）。",
+        "标记：~ = 仅按名字解析的边（可能指向同名符号）；[unresolved] = 未解析到定义的调用点。",
+      ].join("\n"),
+      promptSnippet: "Call graph and data-flow navigation",
+      promptGuidelines: [CALLGRAPH_PROMPT],
+      parameters: CallgraphParams,
+      structuredSchema: aftCallgraphStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const rawArgs = compactArgs({
+          op: params.op,
+          filePath: resolvePathArg(extCtx.cwd, params.path),
+          symbol: params.symbol,
+          depth: coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER),
+          expression: params.expression,
+          toSymbol: params.toSymbol,
+          toFile: params.toPath ? resolvePathArg(extCtx.cwd, params.toPath) : undefined,
+          includeTests: params.includeTests,
+          includeUnresolved: params.includeUnresolved,
+        });
+
+        const { text, response } = await callCallgraphWithBuildRetry(
+          bridgeFor(ctx),
+          rawArgs,
+          extCtx,
+          signal,
+        );
+        const out =
+          text ||
+          formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {
+            includeUnresolved: coerceBoolean(params.includeUnresolved),
+          }).join("\n");
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text: out }],
+          details: {
+            truncated,
+            pendant: {
+              markdown: buildPendantMarkdown({
+                title: "aft_callgraph",
+                input: params,
+                output: out,
+                truncated,
+              }),
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftCallgraphStructuredSchema>(response, out),
+        };
+      },
+    }),
+  );
 }
 
 /**
@@ -612,75 +648,79 @@ const SearchParams = Type.Object(
 );
 
 export function registerSearchTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_search",
-    label: "aft_search",
-    description: [
-      "一个工具完成代码搜索：概念、标识符、错误串、正则、字面量、文件名自动路由到合适的引擎并按相关度排序。",
-      "概念类查询（'ORM 如何构建并执行查询'）用自然语言整句——语义通道理解意图并匹配 docstring 和注释；",
-      "精确名字、字符串、正则保持简短（'^export'、'Cargo.lock'）。",
-      "索引首次构建时本调用会阻塞到构建完成，避免返回部分结果。",
-    ].join("\n"),
-    promptSnippet: "Search code by meaning or exact text",
-    promptGuidelines: [SEARCH_PROMPT],
-    parameters: SearchParams,
-    async execute(_id, params, signal, onUpdate, extCtx) {
-      if (typeof params.query !== "string" || params.query.trim().length === 0) {
-        throw new Error("'query' must be a non-empty string");
-      }
-      const rawArgs = compactArgs({
-        query: params.query,
-        topK: params.topK,
-        includeTests: params.includeTests,
-      });
-
-      const bridge = bridgeFor(ctx);
-      const formatProgress = createSemanticIndexProgressFormatter();
-      const stopProgress =
-        onUpdate === undefined
-          ? undefined
-          : subscribeBridgeStatus(bridge, (snapshot) => {
-              const text = formatProgress(snapshot);
-              if (text !== undefined) {
-                onUpdate({ content: [{ type: "text", text }], details: undefined });
-              }
-            });
-      let response: Record<string, unknown>;
-      let text: string;
-      try {
-        ({ text, response } = await callAftTool(
-          bridge,
-          "search",
-          rawArgs,
-          resolveSessionId(extCtx),
-          {
-            // 默认 search 传输超时仅 60s，会早于索引等待（600s）触发；覆盖为等待
-            // 上限 + 常规执行预算。超时只说明响应被挤掉而非 bridge 挂死，保留
-            // 常驻的语义索引/LSP 状态。
-            transportTimeoutMs: SEMANTIC_INDEX_WAIT_TIMEOUT_MS + 60_000,
-            keepBridgeOnTimeout: true,
+  bus.register(
+    defineStructuredTool({
+      name: "aft_search",
+      label: "aft_search",
+      description: [
+        "一个工具完成代码搜索：概念、标识符、错误串、正则、字面量、文件名自动路由到合适的引擎并按相关度排序。",
+        "概念类查询（'ORM 如何构建并执行查询'）用自然语言整句——语义通道理解意图并匹配 docstring 和注释；",
+        "精确名字、字符串、正则保持简短（'^export'、'Cargo.lock'）。",
+        "索引首次构建时本调用会阻塞到构建完成，避免返回部分结果。",
+      ].join("\n"),
+      promptSnippet: "Search code by meaning or exact text",
+      promptGuidelines: [SEARCH_PROMPT],
+      parameters: SearchParams,
+      structuredSchema: aftSearchStructuredSchema,
+      async execute(_id, params, signal, onUpdate, extCtx) {
+        if (typeof params.query !== "string" || params.query.trim().length === 0) {
+          throw new Error("'query' must be a non-empty string");
+        }
+        const rawArgs = compactArgs({
+          query: params.query,
+          topK: params.topK,
+          includeTests: params.includeTests,
+        });
+
+        const bridge = bridgeFor(ctx);
+        const formatProgress = createSemanticIndexProgressFormatter();
+        const stopProgress =
+          onUpdate === undefined
+            ? undefined
+            : subscribeBridgeStatus(bridge, (snapshot) => {
+                const text = formatProgress(snapshot);
+                if (text !== undefined) {
+                  onUpdate({ content: [{ type: "text", text }], details: undefined });
+                }
+              });
+        let response: Record<string, unknown>;
+        let text: string;
+        try {
+          ({ text, response } = await callAftTool(
+            bridge,
+            "search",
+            rawArgs,
+            resolveSessionId(extCtx),
+            {
+              // 默认 search 传输超时仅 60s，会早于索引等待（600s）触发；覆盖为等待
+              // 上限 + 常规执行预算。超时只说明响应被挤掉而非 bridge 挂死，保留
+              // 常驻的语义索引/LSP 状态。
+              transportTimeoutMs: SEMANTIC_INDEX_WAIT_TIMEOUT_MS + 60_000,
+              keepBridgeOnTimeout: true,
+            },
+            undefined,
+            signal,
+          ));
+        } finally {
+          stopProgress?.();
+        }
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            pendant: {
+              markdown: buildPendantMarkdown({
+                title: "aft_search",
+                input: params,
+                output: text,
+                truncated,
+              }),
+            } satisfies ToolPendant,
           },
-          undefined,
-          signal,
-        ));
-      } finally {
-        stopProgress?.();
-      }
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "aft_search",
-              input: params,
-              output: text,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+          structuredResult: aftPayload<typeof aftSearchStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }