---
name: musepi-prose-standard
description: 编写或评审 MusePi 注释、JSDoc、prompt、文档、i18n、GUI 文案和 CHANGELOG；保留契约、删除重复和装饰，并确定唯一事实归属。
---

# MusePi 文案标准

写得足以保住契约，然后删除推理过程、重复和装饰。文档结构与双语机制由 `.agents/rules/documentation.md` 持有；历史叙述和评审对白由 `skill://musepi-trim-cot-leakage` 清理。本技能负责语义完整性与编辑判断，不是机械缩字脚本。

## 保留完整命题

改动前列出每个命题：行为者与动作、条件与时序、情态、否定与例外、所有权、副作用、失败模式和后果。只有这些事实都存活且表达更清楚时才删减；字数减少本身不是改进。

在使用处保留调用方需要的本地契约。架构、算法和历史链接到唯一归属文档；关键契约可以重复，理由和流程不要复制。非显然理由若省略会导致误用，应保留或写清后果。

## 各位置的必需内容

- **公开 JSDoc**：调用方可见的返回区分、抛错/拒绝、副作用、所有权、时序、取消和持久性；函数导出带 `@param` / `@returns`。
- **内部注释**：非本地或明显复杂结构的不变量、竞态次序、所有权、安全边界和意外失败行为。代码已表达的事实不再复述。
- **Prompt**：静态 `.md` + Handlebars；措辞变化是模型行为变化，需要 snapshot 或行为验证。
- **i18n 与可见字符串**：按 `docs/i18n.md` 的域归属修改，zh/en 同步；插件文案走 `registerTranslations`。key 是契约，不擅自改变语义；可见文案变化需要对应行为证据。
- **测试**：只解释非显然 fixture、断言、平台迁就或真实入口设计；不写走查和测试清单复述。
- **CHANGELOG**：遵循 `.agents/rules/release.md`。标题写用户得到什么，正文可以写机制、兼容和迁移；不写参考来源、内部编号或评审过程。
- **Docs**：遵循 `.agents/rules/documentation.md`。GUI、扩展 API 和公开契约在同一改动中更新 owning docs 及双语。
- **诊断**：点名失败主体或路径、被违反的规则和非显然纠正；删除内部执行叙述。

优先使用具体词：`响应字段`、`JSON 校验`、`ESM 导出`，而不是泛化的“形状/边界/缝”。调用方契约、安全边界和进程边界本身仍是准确术语。

## 复用与排除

写 helper 或文案前查中央工具和相邻领域模块；已有事实只链接，不另建一份。生成文件、vendor、node_modules、录制产物和快照不由文案清理手改；生成物应改生成源并重跑生成命令。