34 lines
5.2 KiB
Markdown
34 lines
5.2 KiB
Markdown
|
# RFC：包（package）模型体验契约
|
||
|
|
|
||
|
|
Status: implemented
|
||
|
|
|
||
|
|
[English](2026-07-12-package-model-experience-contract.md) | 中文
|
||
|
|
|
||
|
|
## 问题
|
||
|
|
|
||
|
|
一个包的 README 可以解释 API 和运行时机制，却不回答主导 agent harness（智能体框架）行为与成本的核心问题：这个包中有什么内容会进入模型请求、在什么条件下进入、以及这些 token 会保留多久。在插件架构中，这一缺失尤其难以审计。消费方可能把后端结果转为工具消息，策略插件可能把成功替换为错误，压缩（compaction）可能移除旧历史，agent 作用域的注册可能改变某个 agent 的提示词或 schema 而对其他 agent 毫无影响。因此只阅读名义上面向模型的包会遗漏真实的上下文影响，而逐依赖阅读源码对于日常评审又过于昂贵。
|
||
|
|
|
||
|
|
## 决策
|
||
|
|
|
||
|
|
每个具有面向模型或模型相邻契约的 workspace 包 README，都以规范的 [Model Experience 章节](../../../cookbook/adding-a-package.md#4-write-the-package-readme)结尾，紧接在 `## Known Limitations and Deferred Work` 之前；如果包在 no-limitations 允许列表上，则以 Model Experience 本身结尾。经审计确认为模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
|
||
|
|
|
||
|
|
具有直接、条件性、有上限、生命周期性、多表面或辅助模型效应的包，每个上下文表面使用一个 H3。每个 H3 说明相关模型接收到什么内容、何时接收，并对 token 效应进行分类。包所拥有的稳定文本逐字引用：系统提示词及其他长文本使用嵌套 H4 加 `markdown` 围栏，短文本则以行内形式保留，带命名的插值占位符。工具 schema 表面链接到生成的[工具目录](../../../tool-catalog.md)中对应的锚点章节，只陈述组合或配置差异；仅在运行时定义的则说明目录为何未收录。数据依赖和提供方拥有的文本以摘要形式呈现。agent 作用域的可见性须显式标注；当作用域可以隐藏提示词而不隐藏 schema（或反之）时，提示词和 schema 表面保持分开记录。
|
||
|
|
|
||
|
|
没有模型上下文效应的包，或其路径完全由另一个包渲染的包，使用验证器审计过的单句形式：`None, as ` 或 `Indirectly, through `。纯传输和无 ctx key 的测试支持包在不产生模型绑定内容时使用 none 形式。提供方后端即使会截断或过滤数据，也使用 indirect 形式；组装 bundle 在所有效应由具名子包拥有时同样使用 indirect 形式。这些句子定位贡献所在，而不重述消费方的内容。结构化章节同样只记录包自身拥有的输入、转换和差异。
|
||
|
|
|
||
|
|
`verify-package-readme-model-experience` 发现包的 manifest 并验证三种分类、规范的末尾章节顺序、必填字段、具体的文本证据、嵌套的逐字块以及锚定的工具目录链接。它在 `doc-sync` 和并行门禁运行器中运行。覆盖面、链接相关性和事实准确性仍由评审把关。
|
||
|
|
|
||
|
|
## 曾考虑的替代方案
|
||
|
|
|
||
|
|
- **只记录注册了提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
|
||
|
|
- **从源码生成一份中央上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，例如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的契约；中央副本会增加又一个漂移面。
|
||
|
|
- **要求给出数值 token 计数**：否决。精确计数取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形态：每请求固定、每调用条件性、保留、替换、有上限或零直接。
|
||
|
|
- **使用三列表格**：否决。精确的源文本和条件性结果形态使单元格过于密集、难以扫读。重复的子章节为每个上下文表面提供可读的纵向空间，同时保留相同的字段。
|
||
|
|
- **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘了写文档」之间是歧义的。省略仅限于在验证器中以理由具名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
|
||
|
|
- **要求经审计的零影响或简单间接包也使用完整结构化形式**：否决。围绕一个事实重复标签没有意义。一句受门禁约束的句子在保持显式覆盖的同时免去了仪式感。
|
||
|
|
- **只有约定、没有门禁**：否决。仓库级契约必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
|
||
|
|
|
||
|
|
## 后果
|
||
|
|
|
||
|
|
评审者可以从任何面向模型或模型相邻的包出发，看到它对会话模型、子模型和辅助调用的贡献，而无需重建完整的插件图。token 预算工作可以区分每次请求的重复开销与数据依赖的历史，agent 作用域的变更有了显式的文档检查点。包作者在模型可见行为变化时维护一个或多个紧凑的上下文表面块，或一句经分类的句子；经审计的通用包不带无关的模型样板文字。结构化字段不承诺提供方精确的 token 计数；测量仍然是模型和负载特定的，而文档化的增长形态与可见性契约保持稳定。
|