docs(i18n): refresh Agent Note translations after merge

2026-07-23 00:10:53 +08:00
parent cd17f8d23a
commit 744d65d63c
325 changed files with 1535 additions and 1321 deletions
@@ -1,4 +1,4 @@
-# RFC: Package Model Experience 契约
+# Agent Note: Package Model Experience 契约

 Status: implemented

@@ -6,28 +6,28 @@ Status: implemented

 ## 问题

-一个 package（包）的 README 可以解释 API 和运行时机制，却不回答那个主导 agent harness（智能体框架）行为与成本的问题：本 package 中有什么内容会进入模型请求、在什么条件下进入、以及这些 token 会保留多久。在插件架构中，这一缺失尤其难以审计。消费方可能把后端结果转为工具消息，策略插件可能把成功替换为错误，上下文压缩（context compaction）可能移除旧历史，agent 作用域的注册可能改变某个 agent 的提示词或 schema 而其他 agent 不受影响。因此，只阅读名义上面向模型的 package 会遗漏真实的上下文影响，而跨所有依赖阅读源码对日常评审来说又太昂贵。
+包 README 可以解释 API 和运行时机制，却不回答主导 agent harness（智能体框架）行为与成本的问题：该包的哪些内容会进入模型请求、在什么条件下进入、这些 token 会保留多久，以及后续请求是否会保留可复用的 KV cache 前缀。在插件架构中，这种遗漏尤其难以审计。消费者可能把后端结果转为工具消息，策略插件可能以错误取代成功结果，压缩可能移除旧历史，而 agent 范围的注册可能改变某个 agent 的 prompt 或 schema，却不影响其他 agent。因此，只阅读名义上面向模型的包会遗漏真实的上下文效应，而在每次常规评审中跨所有依赖阅读源码又成本过高。

 ## 决策

-每个具有面向模型或模型相邻契约的 workspace package README，在末尾、`## Known Limitations and Deferred Work` 之前放置规范的 [Model Experience 章节](../../../cookbook/adding-a-package.md#4-write-the-package-readme)；位于 no-limitations 允许列表上的 package 以 Model Experience 本身作为末尾章节。经审计确认为模型无关的通用 package 通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
+每个具有面向模型或邻近模型契约的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无限制项”允许列表中的包则以模型体验本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。

-具有直接、条件性、有上限、生命周期性、多表面或辅助模型效应的 package，每个上下文表面使用一个 H3。每个 H3 说明相关模型接收到什么内容以及何时接收，然后对 token 效应进行分类。由 package 拥有的稳定文本逐字引用：系统提示词行文和其他长字面量使用嵌套 H4 加 `markdown` 围栏，短字面量则以行内形式呈现并使用命名插值占位符。工具 schema 表面链接到生成的[工具目录](../../../tool-catalog.md)中对应的锚定章节，仅说明组合或配置差异；仅在运行时定义的工具则解释为何目录中未收录。数据依赖和提供方拥有的文本以摘要形式描述。agent 作用域的可见性须显式说明；当作用域可以隐藏其中一个而不影响另一个时，提示词表面与 schema 表面保持分开。
+具有直接、条件式、有上限、全生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。cache 字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、范围、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺 provider 一定命中 cache 或保留某段时间。由包拥有的稳定文本按原文精确引用：system prompt 正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成式[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由 provider 拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏 prompt 与 schema 中的一者而不影响另一者时，两种表面保持分离。

-没有模型上下文效应的 package，或其路径完全由另一个 package 渲染的 package，使用验证器审计过的单句形式：`None, as ` 或 `Indirectly, through `。纯传输和无密钥的测试支持 package 在不创建模型绑定内容时使用 none 形式。提供方后端即使对数据进行上限或过滤，也使用 indirect 形式；组装 bundle 在命名子 package 拥有全部效应时同样使用 indirect 形式。这些句子定位贡献所在，而不重述消费方的内容。结构化章节同样只记录 package 自身拥有的输入、变换和差异。
+没有模型上下文效应的包，或某条路径完全由另一个包渲染的包，使用验证器审计过的短格式：一句以 `None, as ` 或 `Indirectly, through ` 开头的句子，随后是一个 `KV Cache effect` H4 和一个正文段落。纯传输包和无密钥测试支持包若不创建任何进入模型的内容，就使用 none 格式。provider 后端即使会限制或过滤数据也使用 indirect 格式；具名子项拥有全部效应时，接线 bundle 也使用该格式。这些章节定位贡献并声明不会直接使 cache 失效，同时不重复陈述消费者。结构化章节同样只记录由包拥有的输入、变换和增量。

-`verify-package-readme-model-experience` 发现 package manifest（元数据清单）并验证三种分类、规范的末尾章节顺序、必填字段、具体字面量证据、嵌套逐字块和锚定的工具目录链接。它在 `doc-sync`（文档同步门禁）和并行门禁运行器中执行。覆盖面、链接相关性和事实准确性仍由评审把关。
+`verify-package-readme-model-experience` 发现包清单，并验证三种分类、规范末尾章节顺序、确切字段标题深度与顺序、非空字段段落、逐字块的 H5 归属、具体字面量证据，以及带锚点的工具目录链接。它在 `doc-sync` 和并行门禁 runner 中运行。评审仍负责覆盖面、链接相关性和事实准确性。

 ## 曾考虑的替代方案

 - **只记录注册提示词或工具的 package**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
 - **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。package README 是实现本地的契约；集中副本会增加又一个漂移面。
 - **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
- **使用三列表格**：否决。精确的源文本和条件性结果形状使单元格密集且难以扫读。重复的子章节为每个上下文表面提供可读的纵向空间，同时保留相同的字段。
+- **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
 - **允许所有零影响 package 省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用 package；模型相邻的零影响 package 保留一句显式说明。
- **对审计过的零影响或简单间接 package 也要求完整结构化形式**：否决。围绕一个事实重复标签没有意义。受门禁约束的单句保留了显式覆盖而无需繁文缛节。
+- **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
 - **只有约定而无门禁**：否决。仓库级契约必须覆盖未来的每个 package；评审者的记忆无法可靠地检测到遗漏的 README 章节。

 ## 后果

-评审者可以从任何面向模型或模型相邻的 package 出发，直接看到它对会话模型、子模型和辅助调用的贡献，无需重建完整的插件图。token 预算工作可以区分每次请求的重复开销与数据依赖的历史，agent 作用域的变更有了显式的文档检查点。package 作者在模型可见行为变更时维护一个或多个紧凑的上下文表面块或一句分类说明；经审计的通用 package 不承载无关的模型样板文字。结构化字段不承诺提供方精确的 token 数；测量仍然是模型和负载特定的，而文档化的增长与可见性契约保持稳定。
+评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起的前缀变更。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺 provider 精确的 token 数或 cache 命中；测量仍取决于模型、provider 和工作负载，而所记录的增长、可见性和前缀稳定性契约保持稳定。