docs(i18n): align Agent Note terminology

2026-07-24 13:57:16 +08:00
parent d46471e11f
commit c0eacae2ba
228 changed files with 584 additions and 584 deletions
@@ -15,20 +15,20 @@ Status: implemented

 ## 决策

- 从 `GenerateOptions` 中移除 `prefill`，同时移除两个 adapter 的 UNSUPPORTED 守卫、固定抛错行为的测试、[core.md](../../../../docs/core-data-structures/core.md) 中的粘贴行，以及记录该拒绝行为的 adapter README 表格行。cookbook 中的 UNSUPPORTED 指导（[adding-an-llm-adapter.md](../../../../docs/cookbook/adding-an-llm-adapter.md)）改为通用表述规则——provider 无法遵守的 `GenerateOptions` 字段应抛出 `LlmError(..., 'UNSUPPORTED')`——而不再以 prefill 为例。[内容块词汇 Agent Note（agent 决策记录）](../architecture/2026-06-11-content-block-vocabulary.md)的后果按照 [implemented/AGENTS.md](../AGENTS.md)，将 prefill 记录为由生产者门控，而不是已有归属。
- 从 `ToolSchema`、`DefineToolOptions`、`defineTool`、`schemas()` 允许列表、deepseek 序列化分支及其 wire-type 字段，以及 tool-catalog 渲染器的 `Strict:` 行中移除 `strict`。pi-ai 的 payload 修补逻辑简化为对 pi-ai 自身逐工具 strict 默认值的无条件清除（pi-ai 在每个序列化的工具上打 `strict: false`；手写的孪生适配器不发送此字段，因此清除逻辑为保持协议格式对等而保留，由其序列化器测试固定）。setter 测试和 core.md 粘贴行已移除；`GenerateOptions` 与 `ToolSchema` 在 `scripts/type-equiv.manifest.json` 中保留各自的行，因为两个类型只是少了一个字段，本身仍然存在。
+- 从 `GenerateOptions` 中移除 `prefill`，同时移除两个适配器的 UNSUPPORTED 守卫、固定抛错行为的测试、[core.md](../../../../docs/core-data-structures/core.md) 中的粘贴行，以及记录该拒绝行为的适配器 README 表格行。实操手册中的 UNSUPPORTED 指导（[adding-an-llm-adapter.md](../../../../docs/cookbook/adding-an-llm-adapter.md)）改为通用表述规则——提供方无法遵守的 `GenerateOptions` 字段应抛出 `LlmError(..., 'UNSUPPORTED')`——而不再以 prefill 为例。[内容块词汇 Agent Note（agent 决策记录）](../architecture/2026-06-11-content-block-vocabulary.md)的后果按照 [implemented/AGENTS.md](../AGENTS.md)，将 prefill 记录为由生产者门控，而不是已有归属。
+- 从 `ToolSchema`、`DefineToolOptions`、`defineTool`、`schemas()` 允许列表、deepseek 序列化分支及其 wire-type 字段，以及工具目录渲染器的 `Strict:` 行中移除 `strict`。pi-ai 的 payload 修补逻辑简化为对 pi-ai 自身逐工具 strict 默认值的无条件清除（pi-ai 在每个序列化的工具上打 `strict: false`；手写的孪生适配器不发送此字段，因此清除逻辑为保持协议格式对等而保留，由其序列化器测试固定）。setter 测试和 core.md 粘贴行已移除；`GenerateOptions` 与 `ToolSchema` 在 `scripts/type-equiv.manifest.json` 中保留各自的行，因为两个类型只是少了一个字段，本身仍然存在。

-本 Agent Note 刻意不触及 `temperature`、`stop` 或 `maxTokens`：两个 adapter 都会端到端遵守它们，而且它们自然是 `agent/request` 上修改请求的 hook 插件首批目标。
+本 Agent Note 刻意不触及 `temperature`、`stop` 或 `maxTokens`：两个适配器都会端到端遵守它们，而且它们自然是 `agent/request` 上修改请求的钩子插件首批目标。

 ## 曾考虑的替代方案

 ### 为什么不保留？

-「显式的 UNSUPPORTED throw 是诚实的契约行为」——但一个在两个孪生适配器中唯一的实现就是拒绝的旋钮，什么也没承诺；删除它反而升级了失败模式：意外的 setter 变成编译错误而非运行时 throw。「Strict schema 遵循是官方文档记载的 provider 功能，且管道完整」——但一个旋钮在有已发布的工具设置它并且有端点兑现它之前，不构成产品表面；今天两者都不成立。它们各自随首个真实 producer 回归：`prefill` 随实现了 chat-prefix completion 的适配器（以及对不支持该功能的适配器的明确策略）一起回来；`strict` 随需要它的工具和 beta 端点方案一起回来。
+「显式的 UNSUPPORTED throw 是诚实的契约行为」——但一个在两个孪生适配器中唯一的实现就是拒绝的旋钮，什么也没承诺；删除它反而升级了失败模式：意外的 setter 变成编译错误而非运行时 throw。「Strict schema 遵循是官方文档记载的提供方功能，且管道完整」——但一个旋钮在有已发布的工具设置它并且有端点兑现它之前，不构成产品表面；今天两者都不成立。它们各自随首个真实 producer 回归：`prefill` 随实现了 chat-prefix completion 的适配器（以及对不支持该功能的适配器的明确策略）一起回来；`strict` 随需要它的工具和 beta 端点方案一起回来。

 ## 验证

-`rg prefill` 只返回 Agent Note 记录（本文及[内容块词汇 Agent Note](../architecture/2026-06-11-content-block-vocabulary.md)中由生产者门控的后果）；限定在工具 schema 范围内的 `rg strict` 只返回本 Agent Note、保留下来的 pi-ai 清理逻辑，以及 `strictEqual` 等无关正文。两个 adapter 的契约测试都能在没有守卫的情况下通过，pi-ai 修正仍会清理库的 strict 默认值——其 serializer 测试固定了线协议一致性。
+`rg prefill` 只返回 Agent Note 记录（本文及[内容块词汇 Agent Note](../architecture/2026-06-11-content-block-vocabulary.md)中由生产者门控的后果）；限定在工具 schema 范围内的 `rg strict` 只返回本 Agent Note、保留下来的 pi-ai 清理逻辑，以及 `strictEqual` 等无关正文。两个适配器的契约测试都能在没有守卫的情况下通过，pi-ai 修正仍会清理库的 strict 默认值——其 serializer 测试固定了线协议一致性。

 ## 后果