docs(i18n): refresh Agent Notes after parent merge

2026-07-23 19:48:00 +08:00
parent 3b390334d3
commit 86940da524
30 changed files with 73 additions and 71 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-06-11-custom-schema-dsl.md: 9cef4175e4c4a2e6d2ea034d3522d8a8ddd1f5cb
-2026-06-11-custom-schema-dsl.zh.md: 8b1241edea4c591e428fbaa15916437a3de42061
+2026-06-11-custom-schema-dsl.md: 947d53555df078bfa9f3dac48eab4b8c0074007c
+2026-06-11-custom-schema-dsl.zh.md: 7317e950a4d9822edfca190ccfc22b65809f078a
@@ -10,7 +10,7 @@ Status: implemented

 ## 决策

-在 dsh-tools 中实现一个小型自定义 DSL：`SchemaSpec`（逐属性规格，带 `required: true` 布尔值）；类型层面的 `InferArgs<S>` 将规格映射为参数类型（required 键为必选，其余通过 `?` 标记为真正可选）；运行时的 `schemaSpecToJsonSchema()` 转换器；以及将三者串联的 `defineTool()`。`ToolRegistry.register()` 仍然接受原始 JSON Schema 的 `ToolDefinition`——MCP 来源的工具正是以此方式注册。
+该决策已由[统一 JSON 值 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)取代；新设计保留小型编写接口，同时让参数与类型化值共享一套词汇。`ParameterSchemaSpec` 保留逐属性的 `required: true`；`InferArgs<S>` 将必需键映射为非可选属性；`parameterSchemaSpecToJsonSchema()` 编译隐式开放的对象根；`defineTool()` 则将类型推导、编译与校验串联起来。原始 JSON Schema 的 `ToolDefinition` 仍是 `ToolRegistry.register()` 接受的输入，供 MCP 和其他外部工具使用。

 ## 曾考虑的替代方案

@@ -19,5 +19,5 @@ Status: implemented
 ## 后果

 - 第一方工具作者获得零类型断言的类型化参数；类型体操的成本留在核心包内部（符合 AGENTS.md 的类型安全策略）。
- DSL 有意保持小巧（string/number/boolean/object/array、enum、default、嵌套 properties/items）。相对完整 JSON Schema 的缺口（union、format、constraint）在真实工具提出需求之前暂不补齐。
+- 当前节点、字面量约束、联合类型、JSON 值边界与对象开放性规则均由上述统一说明定义。
 - `InferArgs` 映射在类型层面有回归测试，源于早期一个可选性 bug。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-06-11-runtime-arg-validation.md: 6ac2a2ab475c9813dbfbb09e45da71821489d6cd
-2026-06-11-runtime-arg-validation.zh.md: 119f738dbb3aaee4786aa58d5495ab5e012e206e
+2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
+2026-06-11-runtime-arg-validation.zh.md: 09958147766b4015d6bebf786c4947b9d2941f74
@@ -6,13 +6,13 @@ Status: implemented

 ## 问题

-`defineTool`（[自定义 schema DSL](2026-06-11-custom-schema-dsl.md)）通过 `InferArgs<S>` 映射为工具作者提供了类型化的 `execute(args)`。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串、枚举值超出集合）会以「仅名义类型化」的状态到达 `execute`。工具函数体要么在错误形状上崩溃（产生模型无法据以自我修正的通用堆栈跟踪），要么更糟——静默地行为异常。与此同时，转换器已经编码了校验器遍历所需的完整结构。
+`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串，或字面量超出声明的集合）会以「仅名义类型化」的状态到达 `execute`。工具函数体随后要么在错误形状上崩溃，要么静默地行为异常。

 ## 决策

-`validateArgs(spec, args): string[]` 对运行时值解释一个 `SchemaSpec`，返回可读的违规列表（空数组 = 合法），且是全函数（永不抛出异常）。`defineTool` 在调用类型化函数体之前运行它；存在违规时抛出 `ToolArgsError`（`code: 'INVALID_ARGS'`，消息中列出违规项），注册表既有的 execute-waterfall（瀑布式事件）catch 将其转为模型可读取并据以自我修正的 `isError` 结果。
+`validateArgs(spec, args): string[]` 编译 `ParameterSchemaSpec`，并委托共享的 `validateJsonSchemaValue()` 遍历器，对格式正确的声明返回可读的违规列表。`defineTool` 在定义时对编译后的参数 schema 创建快照，并在调用类型化函数体之前执行校验；存在违规时会抛出 `ToolArgsError`（`INVALID_ARGS`），注册表将其作为模型可据以修正的错误结果返回。

-校验器严格镜像 `schemaSpecToJsonSchema` 的语义——遍历相同结构、执行相同规则：顶层必须是非数组对象；必需键仅来自 `required: true`；允许额外键（不设 `additionalProperties: false`）；不应用 `default`；没有 `properties`/`items` 的 `object`/`array` 属性仅做类型检查；`enum` 是成员资格检查。原始注册的（MCP）工具不受影响——它们自行校验输入。
+校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。原始注册的工具自行负责输入校验。

 ## 后果

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-06-17-filesystem-capability-seam.md: cd8f8572730b1833ed1d7dbe1861d516c2d32925
-2026-06-17-filesystem-capability-seam.zh.md: fa06ecc4538258163ae17cd403d9e856c4d2911f
+2026-06-17-filesystem-capability-seam.md: 08e8d52b314eb10e2c7ec444dd61a96d8621e032
+2026-06-17-filesystem-capability-seam.zh.md: 8ad3b55b6887a2951211a6756670764bb8e820f5
@@ -124,7 +124,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`

 ## 测试

-测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，而非信任返回的 `ContentBlock[]`。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
+测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。

 本仓库曾踩过的防御性模式类别被直接固定：

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-06-20-generic-long-running-tool-runtime.md: c28236d194ae839f88d900f0fc52707b2c9e53e2
-2026-06-20-generic-long-running-tool-runtime.zh.md: 911c4288fff6e4235b9c88efeaaa882910e559b0
+2026-06-20-generic-long-running-tool-runtime.md: 272cdaf91b35b30c125aee391d5e09238155463a
+2026-06-20-generic-long-running-tool-runtime.zh.md: 9a427199dfd1bafc4bfe6d7db5b84efc66b24ceb
@@ -25,6 +25,8 @@ Status: implemented

 字面类型见[任务数据结构目录](../../../../docs/core-data-structures/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。

+面向模型的生产方会在规范成功值中暴露已提交的 id，通常为 `{ kind: 'background', taskId }`；Native 渲染仍可保留便于人类阅读的行文。预先被中止的后台调用会失败，而不是返回空操作，因为不存在可履行所承诺句柄的任务。一旦注册过程发布 id，取消就归任务自身的控制器与任务运行时所有：随后取消生产工具调用不得终止已发布的任务。`task_kill`、所有者资源释放和服务拆除会请求取消；前台执行仍与调用的 `exec.signal` 耦合。
+
 生产方钩子定义三项职责：

 - `cancel(reason?)` 同步请求终止，具备幂等性，并且必须使 `done` 完成。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-02-result-time-applied-hunk-diffs.md: b1e1884f2264f17f6fff17569d79d8352e3fc709
-2026-07-02-result-time-applied-hunk-diffs.zh.md: f64d984df524f25f041a56b1f0bc287e1e4b77a6
+2026-07-02-result-time-applied-hunk-diffs.md: fe163484ad56858fabd55dacace1d56814bd93e4
+2026-07-02-result-time-applied-hunk-diffs.zh.md: e8283a40d96c031a84e2627117801b3043eb8904
@@ -16,24 +16,20 @@ Status: implemented

 添加一个**持久化的、工具私有的展示通道**，使工具的 `execute` 能附加一个结果时刻的渲染载荷并在回放中存活，并用它来携带 applied-hunk diff。

-### 1. 工具结果上的 `meta` 通道（core）
+### 1. 规范工具输出上的可回放展示投影（core）

-`ToolDefinition.execute` 现在可以返回其面向模型的 `ContentBlock[]`（不变，常见情况）或 `{ content: ContentBlock[]; meta?: unknown }`：
+原始实现允许 `execute` 返回 `{ content, meta }`。[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)取代了这种编写形态：每个工具如今返回一个由 schema 声明的 JSON 值，`output.render(args, value)` 从中派生面向模型的内容块，可选的 `output.presentationMeta(args, value)` 则派生可回放的 UI 数据。

-```ts ignore-check
-type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
-```
+`presentationMeta` 是工具自有的 `JsonValue`，core 会持久化它，但不解释其中的字段。`Session.append` 将它与事件的其余部分一并校验，回放再把存储的载荷传回 `presentResult`；因此展示无需 I/O 或重新计算即可复现。规范值本身只存在于执行期间，不会加入会话格式。

-`meta` 是工具自有的 `unknown`，core 持久化但不解释。`Session.append` 拒绝非 JSON 值，回放时将存储的载荷回传给 `presentResult`；因此展示无需 I/O 或重新计算即可复现。运行时校验避免了向 tools core 添加共享的 serializable-value 依赖。
-
-这是通用形态（「工具附加持久化的结果展示」），而非 fs 特有的——任何工具都可以使用。
+这仍是通用形态（「工具投影持久化的结果展示」），而非 fs 特有；任何工具都可以使用。

 ### 2. 工具计算 hunk；后端返回 before/after（fs）

 按照 [capability-seam 拆分](2026-06-13-capability-seams.md)，存储后端只返回**存储事实**，面向模型的工具拥有**展示**：

 - `dsh-fs` 将 `FsEditOutcome` 扩展为包含 `{ before: string; after: string }`，将 `FsWriteOutcome` 扩展为包含 `{ before: string | null; after: string }`（`before: null` 表示创建，或已存在但不可 diff 的二进制/非 UTF-8 文件）。本地后端在写入时已持有两份文本；它以原始 LF 规范化文本返回，**不让任何 diff/UI 概念进入 seam**。
- `dsh-tool-fs` 将上下文 hunk 存入 `meta: { diffs: FileDiff[] }`。成功的变更始终以 diff 卡片完成，因为 ACP 结果内容会替换待定卡片：创建或无变化的覆写回退到由参数推导的整文件 diff，而编辑使用 applied hunk。失败的变更不携带 diff 元数据，正常渲染其错误信息。
+- `dsh-tool-fs` 返回规范的变更前／后事实，并将上下文 hunk 投影为 `meta: { diffs: FileDiff[] }`。成功的变更始终以 diff 卡片完成，因为 ACP 结果内容会替换待定卡片：创建或无变化的覆写回退到由参数推导的整文件 diff，而编辑使用 applied hunk。失败的变更不携带 diff 元数据，正常渲染其错误信息。

 ### 3. Bridge 渲染 `diff` 结果卡片

@@ -45,7 +41,7 @@ type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unkn

 ## 后果

-`tool/result` 事件现在可以携带工具私有的 `meta` 载荷——属于磁盘格式词汇的一部分，由 `Session.append` 在运行时限制为 JSON——任何工具都可以附加持久化的结果展示而无需再改 core。diff 卡片在会话重载和快照回放时免费复现：它从日志中读回，从不重新计算。代价：覆写操作在内存中同时持有旧文本和新文本以计算仅用于 UI 的 hunk（`TODO(overwrite-diff-bound)`），且 `dsh-tool-fs` 引入了一个小型、知名的运行时依赖。
+`tool/result` 事件携带工具私有的 `meta` 载荷；它属于磁盘格式词汇的一部分，由 `Session.append` 在运行时限制为 JSON。任何工具都可以投影持久化的结果展示，无需再改 core。diff 卡片在会话重载和快照回放时免费复现：它从日志中读回，从不重新计算。代价：覆写操作在内存中同时持有旧文本和新文本以计算仅用于 UI 的 hunk（`TODO(overwrite-diff-bound)`），且 `dsh-tool-fs` 引入了一个小型、知名的运行时依赖。

 ## 非目标

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-07-tool-call-timeout-policy.md: 538225b197f7dd62b4798c037b72bf3cfc40648a
-2026-07-07-tool-call-timeout-policy.zh.md: e37c8099a7780a8aa44f3154ceaf7ffa772f1e3b
+2026-07-07-tool-call-timeout-policy.md: 69fd1ee721de69621d3b57c10d960da0651b94dd
+2026-07-07-tool-call-timeout-policy.zh.md: 8a92236b1b240e92785e2e7107bf9c7786906627
@@ -63,7 +63,10 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
  return {
    content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }],
    isError: true,
-    error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    error: {
+      message: `tool call timed out after ${timeoutMs}ms`,
+      info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
+    },
  }
 }
 ```