docs: complete Chinese proofreading and generated reference pairing

2026-08-09 11:02:16 +08:00
parent 0543a6f79d
commit 7ff0cbcb7e
565 changed files with 10606 additions and 2171 deletions
@@ -6,13 +6,13 @@ Status: implemented

 ## 问题

-`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 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[]` 编译 `ParameterSchemaSpec`，并委托共享的 `validateJsonSchemaValue()` 遍历器，对格式正确的声明返回可读的违规列表。`defineTool` 在定义时对编译后的参数 schema 创建快照，并在调用类型化函数体之前执行校验；存在违规时会抛出 `ToolArgsError`（`INVALID_ARGS`），注册表将其作为模型可据以修正的错误结果返回。

-校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。原始注册的工具自行负责输入校验。
+校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。直接注册的工具自行负责输入校验。

 ## 后果