dsh-prose-standard
散文标准：注释、JSDoc、README、prompt、诊断信息分别必须覆盖什么，以及什么时候该删、什么时候反而要补。
这是 .agents/skills/dsh-prose-standard/SKILL.md 的中文精读。它是这套仓库的散文总编辑：哪里必须有文档、哪里必须删、删到什么程度算过。
什么时候触发
在仓库里写、review、恢复、裁剪或审计散文时使用——覆盖 Markdown、JSDoc、代码与测试注释、prompt、描述、诊断、CLI/UI 字符串。核心立场：
契约指调用方、被调方、实现者、生产者或消费者依赖的义务、不变量、前置/后置条件或兼容承诺。本 skill 拥有编辑判断与必备散文覆盖；位置、预算、双语对、文档门禁归 dsh-doc-standards；猎杀推理记录泄漏归 dsh-trim-cot-leakage。
contract、boundary、shape、surface、seam、gate、vocabulary 是「用前检查」而不是「禁用」的词：先问确切的规则、API、字段集、类型、校验、时机、组件切分或失败是否陈述得更准。注释描述代码表达不了的非显而易见契约或理由，不复述代码已经隐含的东西。
输入与排除
- 要求显式
scope。没有就报出所需输入并停止——不推测全仓范围，也不开始盘问。 - 接受
mode: automatic | interactive，默认 automatic。只有用户明确要问答或校准时才进交互模式。mode 控制的是提问，不是写权限：review/审计任务只报不动；明确授权的写/修/裁任务才动手。 - 永远排除
vendor/——即使要求的范围是全仓，也不跟随符号链接进去。排除要放在包含 glob 之后：ripgrep 末尾加--glob '!vendor/**'，Git 用显式:(exclude)vendor/**pathspec。范围内只剩 vendor/ 就如实汇报。 .agents/notes/archived/同样排除——归档 note 是冻结快照，只能为理解某条历史入站引用而读，绝不为「现代化」它的散文而动它。- 生成的目录、快照、fixture 是衍生物：先改属主源头，再重新生成。生成器从属主散文里抽摘要时，让被抽出的句子在那个面上能独立成立。双语对没有永久属主：哪边都可以是某次更新的写作侧，走轻量例行路径，最小化更新对侧并重录配对。
保住完整命题
动手前，先列出段落里的每个命题。以下元素一个都不能丢：
- 行为者与动作；
- 条件、时机、顺序；
- 情态：必须 / 可以 / 永不；
- 负面保证与例外；
- 所有权、副作用、失败模式与后果。
只有在每个事实子句都存活、且结果更清晰的前提下，才删形容词、重复和叙述。单纯字数变少不算改进。
使用点保留完整的局部契约：调用方或维护者在当下需要的行为、失败、所有权、后果。架构、理由、算法、历史、长例子则激进地链接到属主文档。一个解释只有一个家；必要的契约事实允许在局部重复。省略某个非显而易见的理由可能合理导致误用或错误简化时，就保留它；否则只写后果、链接理由。
按散文位置的必备覆盖
这不是单向的「缩短」pass：当代码、类型和结构表达不了下列契约时，要补写或恢复散文；这些事实在局部已经显而易见时，也不要硬加注释。
| 位置 | 必须覆盖什么 |
|---|---|
| 公开 JSDoc | 调用方可见的返回值区分、throw/reject、副作用、所有权、时机、取消、耐久性 |
| 内部注释 | 非局部结构与明显复杂的局部结构：不变量、竞态顺序、所有权、安全边界、意外失败行为。删掉控制流叙述和代码复述 |
| 模块注释 | 模块的角色、依赖、职责、非显而易见的架构选择（链接到属主解释） |
| 测试 | 只解释非显而易见的测试设计：为什么需要这个 fixture / 断言 / 平台适配 / 真实入口路径 / 间接观察。删掉走读和清单 |
| Cookbook | 前置条件、必需动作、真实入口路径、可观察的验证、简明警告 |
| README | 消费者契约：配置、语义、失败、限制、扩展点、模型可见效果。引用包自有的稳定模型可见文本；链接生成目录与跨包属主。保留耐久的坑，不留日常清理清单 |
| Agent Note | 保留独有理由、机制、备选、后果、shipped 验证证据、具名覆盖空洞。implemented 状态用现在时陈述已落地现实；删规划清单，不删钉住决策的证据 |
| Postmortem | 保留事件序列、证据、因果链、影响、预防。删掉重复的说服和与因果无关的实现细节 |
| Skill 与 agent 指令 | 写明行为护栏与显式范围限制（如「这是引导，不是脚本/清单」），工作流保持简洁并链接其事实来源 |
| 示例与配置注释 | 解释访问限制、非显而易见的接线或加载顺序、安全姿态、回放行为、例外、可能的误用。不复述配置本身已展示的条目 |
| Prompt 与可见字符串 | 措辞即行为。检查生成的输出，跑行为验证或说明为什么没有快照适用 |
| 诊断信息 | 点出失败的主体或路径、被违反的规则、非显而易见时的修复方法。删掉内部执行叙述 |
保留可搜索的机制名，以及有意义的情态、时间、否定强调；只规范化装饰性的强调。
工作流
- 确认 scope、mode、当前分支或 PR base、适用的 AGENTS.md。不看无关分支。
- 评判一段散文前，先读文档标准（docs/AGENTS.md）和它的属主代码或文档；校准或陌生案例读蒸馏样例（references/examples.md）。
- 检查被要求的整个范围，不只看最大的文件。用搜索和字数找候选，然后逐段做语义判断。
- 每个候选分类为：保留 / 补写 / 裁剪 / 恢复 / 重构 / 推迟。任务授权了编辑才动手；不要为凑删除指标而制造编辑。
- 先改属主，再更新衍生物。学到新规则后回头重查同类段落。
- 跑相关的窄检查、文档门禁、
git diff --check，可见字符串要跑行为测试。验证最终 diff 里没有vendor/路径；有意外混入就如实报，不要声称干净的排除史。 - 汇报：检查过的范围、明确的改动、刻意的保留、推迟的案例、实际跑过的检查。
边缘案例怎么判
一个案例仅当至少两个版本都满足完整命题规则、但各自牺牲了某条公认原则，且本 skill 没有现成裁决时，才算边缘。只有一种保命题写法的改写不是边缘案例。
automatic 模式：授权范围内应用明确的编辑，报告真正的边缘案例但不提问；不为推进度而削弱命题。interactive 模式：把同类段落归到管辖原则下，给出两三個可行版本、推荐一个、说清事实或结构差异——不提供凑数的劣选项。用户拍板后，把原则与版本蒸馏进 references/examples.md（不带 PR 历史与 reviewer 叙述），并把学到的规则应用到范围内所有同类段落。