dsh-prose-standard

DeepSeek Harness 文案标准

先写足以保留契约的内容，再删去推理记录、重复内容和修饰。契约是调用方、被调用方、实现者、生产者或消费者所依赖的义务、不变量、前置条件、后置条件或兼容性承诺。本技能负责编辑判断和必需的文案覆盖范围；有关放置位置、篇幅预算、双语配对和文档门禁，请使用 dsh-doc；有关查找并修复推理记录泄漏，请使用 dsh-trim-cot-leakage。这些是指导原则，不是脚本。

将 contract、boundary、shape、surface、seam、gate 和 vocabulary 视为使用前需要检查的术语，而非禁用词。先判断具体规则、API、字段集、类型、验证、时间点、组件划分或故障状态是否能更准确地表达事实。若某个术语指代确切的技术对象，包括调用方/被调用方契约和安全/流程边界，则保留它。

注释应描述代码无法表达的非显而易见的契约或理由；不要复述代码已隐含的内容。

输入和排除项

必须明确提供 scope。如果缺少该项，报告所需输入并停止；不要推断整个代码库的范围，也不要开始提问。

接受 mode: automatic | interactive；默认为 automatic。只有用户明确要求提问或校准时，才进入交互模式。

mode 控制是否提问，不控制写入权限。审查和审计任务只报告发现的问题，不做编辑；明确要求写入、修复或精简的任务则应用明确的修改。

发现、审查和编辑时始终排除 vendor/，即使请求的范围是整个代码库也不例外。不要跟随符号链接进入该目录。将排除项放在包含模式之后，避免后续包含模式重新纳入这些路径：例如，让 ripgrep 命令以 --glob '!vendor/**' 结尾，并为 Git 命令提供显式的 :(exclude)vendor/** 路径规格。如果请求范围仅包含 vendor/，则报告没有符合条件的文件。

文案审查和编辑时也排除 .agents/notes/archived/。已归档的 Agent Notes 是冻结的快照；只有为了解历史上的入站引用时，才检查特定目标，不要更新其文案或出站链接。

将生成的目录、快照和测试夹具视为衍生内容。编辑前追踪所有使用方：源代码 JSDoc 也可能会生成供模型读取的目录。先编辑所属源文件或场景，再重新生成所有衍生内容。如果生成器从所属文案中提取摘要，该摘要必须是完整、适用于相应界面的句子。双语配对没有固定的主语言：更新时任一语言都可以作为撰写端。遵循轻量流程，以最小改动更新对应语言，并重新记录配对。

保留完整命题

编辑前，找出段落中的每个命题。保留每项相关内容：

• 行为主体和动作；
• 条件、时机和顺序；
• 必要性、许可性或绝对禁止等情态；
• 否定保证和例外；
• 所有权、副作用、故障模式及后果。

只有在所有事实分句均得到保留且结果更清晰时，才删除形容词、重复内容和叙述。单纯减少字数并不算改进。

在使用点保留完整的局部契约：调用方或维护者在此处所需的行为、故障、所有权和后果。对于架构、理由、算法、历史或扩展示例，尽量链接到所属文档。每项解释只应有一个归属位置；必要的契约事实可以在本地重复。

如果省略非显而易见的理由可能导致误用或错误简化，则保留该理由。否则，说明后果并链接到理由的归属文档。

按文本位置划分的必要覆盖范围

这不是单向精简流程。如果代码、类型和结构未能传达以下必要约定，请补充或恢复说明。当这些事实在局部已一目了然时，不要添加注释。

• 公共 JSDoc： 说明调用方可见的返回值差异、抛出或拒绝的情况、副作用、所有权、时机、取消和持久性。
• 内部注释： 说明非局部结构以及显然复杂的局部结构，包括不变量、竞态顺序、所有权、安全边界和意外的失败行为。删除对控制流的叙述和对代码的复述。
• 模块注释： 说明模块的作用、依赖项、职责和不明显的架构选择；将架构选择链接到相应的说明文档。
• 测试： 只解释不明显的测试设计——说明为何需要某个测试夹具、断言、平台适配、真实入口路径或间接观测。删除流程讲解和清单。
• 操作指南： 包含前置条件、必要操作、真实入口路径、可观测的验证方式，以及简明警告。
• README： 包含使用者约定：配置、语义、失败情况、限制、扩展点和模型可见的效果。引用由程序包定义且稳定的模型可见文本；链接到生成的目录和跨程序包的所有者。保留持久存在的缺口和维护者易踩的陷阱，不要罗列常规清理事项。遵循程序包 README 要求。
• Agent Notes： 保留独有的理由、机制、替代方案、后果、已发布的验证证据和明确指出的覆盖缺口。描述已实现内容时使用现在时；删除计划清单，但保留能够说明决策依据的证据。
• 事后分析： 保留事件顺序、证据、因果链、影响和预防措施。删除重复说服性内容或与因果关系无关的实现细节。
• 技能和 Agent 指令： 说明行为约束和明确的范围限制，例如“提供指导，而非脚本或检查清单”。保持工作流简洁，并链接到权威信息源。
• 示例和配置注释： 说明访问限制、不明显的接线或加载顺序、安全立场、重放行为、例外情况和可能的误用。不要复述配置中已经清楚展示的条目。
• 提示词和可见字符串： 将措辞视为行为。客户端 UI 文案应放在类型化的本地化字典中，并作为显式本地化属性传递给不依赖 Cordis 的基础组件；检查文本、无障碍名称、工具提示、占位符和格式模板时，应一并检查，然后运行 verify-client-ui-i18n。英文 UI 文案（包括插件的 meta.title 和 meta.description）使用句首字母大写：仅首词、专有名词和产品名称（例如 Chrome DevTools、Git 或 MCP）首字母大写（使用 Git worktrees，而非 Git Worktrees）。中文文案遵循中文规范。更新模型可见文本对应的所有者可运行快照，以及仓库要求的 GUI 证据。如果授权范围内没有对应场景的所有者，请保持措辞不变，并报告延期处理；不要悄悄将其并入纯文案编辑。
• 诊断信息： 当问题不明显时，指出失败对象或路径、违反的规则以及修正方法。删除对内部执行过程的叙述。

保留可搜索的机制名称以及有意义的情态、时间或否定强调。仅规范化装饰性强调。

工作流

1. 确认范围、模式、当前分支或 PR 基准，以及适用的 AGENTS.md 文件。不要检查无关分支。
2. 在判断某段内容之前，先阅读文档规范以及对应的代码或文档。对于校准或不熟悉的情况，请阅读精简示例。
3. 检查所请求的范围，而不只是最大的文件。使用搜索和字数统计寻找候选内容，然后从语义角度进行判断。
4. 将每个候选项归类为保留、添加、删减、恢复、重组或延期。只有在任务授权编辑时才应用明确的更改；不要为了达到删除目标而凭空制造更改。
5. 先更新源文件，再更新派生文件。学到新规则后，重新检查类似段落。
6. 运行范围最小的相关检查、文档检查门禁、git diff --check，以及针对可见字符串的行为测试。确认最终差异中没有 vendor/ 路径；如果意外匹配到 vendor，请报告，而不要声称已通过干净的排除历史确认。
7. 报告检查范围、明确的更改、有意保留的内容、延期事项，以及实际运行的检查。

边界情况的判断

只有当至少两个版本都符合完整命题规则、却需要权衡已接受的原则，且本技能尚未解决这种权衡时，才属于边界情况。若存在保留命题且唯一的改写方案，则不属于边界情况。

在自动模式下，若获准编辑，则应用明确的更改，并报告真正的边界情况，不要提问。不要为了推进工作而弱化命题。

在交互模式下，按适用原则将类似段落归为一组。提供两到三个可行版本，推荐其中一个，并说明事实或结构上的差异。不要提供较差的干扰选项。使用用户要求的渠道；如果通过行内评论校准 PR，请将推荐的临时版本放入差异中，并将备选方案附在对应的确切行上。

用户作出决定后，将原则和版本提炼到示例中，不要包含 PR 历史或审阅者的叙述，然后将学到的规则应用于范围内的所有类似段落。