07 · 模型可见输出

日志即事实源，从模型视角写契约

关键文件AGENTS.mdpackages/preset/agent-preset/skills/agent-experience/snapshots/docs/cookbook/adding-a-package.mdscripts/verify-client-ui-i18n.ts

dsh 本身就是一个 Agent 框架，所以它还要约束"运行时交给模型的内容"。这部分规则同样可以用于任何调用 LLM 的系统。

模型可见 ⟺ 已记录。任何进入模型请求的内容都必须能从 Session 日志重建；新增一种模型可见输入，就要新增一种 Session 事件。这样每次请求都能复现，录制的会话可以在不调用 API 的情况下回放比对。

从模型的视角写

packages/AGENTS.md 要求 prompt、工具 schema、工具结果和诊断信息只包含与任务相关的概念，不出现 UI、传输或实现层的术语。稳定的模型可见文本逐字固定在 snapshot 里；动态行为由 snapshot 或端到端测试覆盖。dsh-code-review 有一项专门的"模型视角"检查：查看模型在各模式下实际收到的 prompt、schema、结果和诊断。

agent-experience：工具与 skill 的设计原则

这个 skill 随产品发布给运行时的模型，用于编写工具定义和设计 skill。它的六条原则是：

• 先给最小上下文：用途、可用动作、约束；详细说明按需加载。
• 发现要显式：每个延迟加载的资源都要有清楚的描述和可靠的获取方式。
• 关键约束要可见：权限、破坏性效果和必要的校验出现在相关动作之前。
• 输出有界：返回精简结果和可用于取详情的标识或路径，不倾倒整份日志。
• 利用局部性：附带少量很可能用到的相邻上下文，明确标出截断，并提供取更多的方法。
• 评估总工作量：节省上下文只有在不引起更多搜索、重复读取或错误时才有价值。

其他配套要求

• 包 README 写 Model Experience：按固定格式说明本包对模型、token 和 KV cache 的影响，由 verify-package-readme-model-experience 检查。
• 两个 SDK 都要更新：agent loop、会话生命周期和 SessionEventMap 的改动，要在同一 PR 里更新 TypeScript 和 Python SDK 的预期输出。
• UI 文案归 locale：界面文字走类型化字典和 t，verify-client-ui-i18n 拒绝硬编码文案。
• 录制会话 snapshot：任何非平凡的、模型、协议或用户可见的变化，都要在同一 PR 里新增或更新一个无 key 的录制会话场景。