@trim21/personal-pi-extensions 0.1.681 → 0.1.684

package/README.md

@@ -36,10 +36,12 @@
 - **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
   `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
   不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
-- **可调用集合** = 总线上实际注册的工具减去排除名单（`codemode` 自身、`spawn-agent`、
-  以及两套文件工具集的 `Read`/`Edit`/`Write` 与 `read`/`edit`/`write`），执行时再与当前
-  active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
-  `--tools`、子代理的工具白名单都同样约束脚本。
+- **可调用集合** = 总线上实际注册的工具减去排除名单，执行时再与当前 active 列表求交，
+  所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、子代理的工具
+  白名单都同样约束脚本。排除名单：`codemode` 自身与 `spawn-agent`；两套文件工具集的
+  读写工具（`Read`/`Edit`/`Write` 与 `read`/`edit`/`write`）；两套工具集的搜索工具
+  （`Grep`/`Glob` 与 `grep`/`glob`）——脚本搜文件用 `call("Bash", { command: "rg …" })`，
+  走同一个沙箱、拿得到退出码，还能拼管道，而那两个工具是给模型看结果的。
 - **文件读写只有 `fs` 一条路**：`fs.read(path)` 返回文件全文的原始 UTF-8 文本（不加行号、
   不截断、不设大小上限，只有内容不是合法 UTF-8 时报错），`fs.write(path, content)` 整体写入并自动创建
   父目录，相对路径相对当前 cwd。`fs.write` 与写类工具共用同一套保护：写前要求「已读且读后
@@ -49,10 +51,12 @@
   直接改，不进脚本）。
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
-- **返回值**：声明了 `structuredSchema` 的工具（如 gh-readonly 的读类工具）把结果放在
-  `structuredResult` 里，`call()` 解包成对象给脚本；`{ ok: false, error }` 会 reject 成
-  `CallFailedError`（脚本可按 `instanceof CallFailedError` 区分调用失败与自身运行期错误）。
-  没有声明输出结构的工具回退成工具输出的文本。
+- **返回值**：声明了 `structuredSchema` 的工具把结果放在 `structuredResult` 里，`call()`
+  解包成对象给脚本——gh-readonly 的读类工具给解析后的 JSON，`Bash` / `bash` 给
+  `{ exitCode, output }`（`exitCode` 为 `null` 表示命令被超时/中止杀掉；命令非零退出是正常
+  结果，直接读 `exitCode` 分支即可）。`{ ok: false, error }` 会 reject 成 `CallFailedError`
+  （脚本可按 `instanceof CallFailedError` 区分调用失败与自身运行期错误）。没有声明输出
+  结构的工具回退成工具输出的文本。
 - **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `fs.read` / `fs.write` /
   `text` / `image` / `exit` / `console.*` / `store.set` / `store.get` / `store.list`
   （会话内持久的键值表）；首行可选 `// @options: {"max_output_tokens": 10000}`。
@@ -425,7 +429,7 @@ Claude Code 风格工具集：`Read` / `Edit` / `Write` / `Grep` / `Glob` / `Bas
 
 - **`Read` / `Edit` / `Write`**：与 opencode 风格共享 read-before-write 记账与文案（`File has not been read yet...` / `File has been modified since read...`），差异是三者都要求先 `Read`（`Edit` 用空 `old_string` 创建新文件、`Write` 创建新文件例外）。`Read` 支持 offset / limit 分页与 PDF `pages`
 - **`Grep` / `Glob`**：ripgrep 实现，行为跟随 Claude Code（`Glob` 带 `--no-ignore` / `--hidden` / `--sort=modified`，与 opencode 风格 `glob` 的差异是各自跟随上游）
-- **`Bash`**：与 opencode 风格 `bash` 共享 bwrap 运行时与 `dangerouslyDisableSandbox` 提权，默认超时 120 秒，只支持同步执行
+- **`Bash`**：与 opencode 风格 `bash` 共享 bwrap 运行时与 `dangerouslyDisableSandbox` 提权，默认超时 120 秒，只支持同步执行。结构化结果给 `{ exitCode, output }`：`output` 是命令的**完整**输出（文本该截断还截断，载荷里是全文），`exitCode` 为 `null` 表示被超时/中止杀掉；命令非零退出不是失败，脚本直接读 `exitCode` 分支
 - **`TodoWrite`**：任务列表工具（`merge` 语义），与 opencode 风格 `todowrite` 的完整替换语义不同，不要混用
 - **`AskUserQuestion`**：阻塞式向用户提问
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.681",
+  "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 },
+);