document-writer

为 $ARGUMENTS 指定的目标项目编写或更新技术文档。

前提条件

以 <skill-dir> 开头的路径相对于此技能的基础目录；该目录会在技能加载时告知。请替换为该字面路径；它不是环境变量。

1. 如果 $ARGUMENTS 为空，请报告：Error: Please provide the target path and the documentation task (for example: './docs/api.md update the payment API docs' or './src/utils.ts add JSDoc for the public helpers').
2. 起草前阅读 <skill-dir>/references/WORKFLOW.md、<skill-dir>/references/DOCUMENT_TYPES.md 和 <skill-dir>/references/VERIFICATION_CHECKLIST.md。
3. 如果请求使用中文、输出文件为中文，或用户希望润色／改写为中文，也要阅读 <skill-dir>/references/CHINESE_TECH_WRITING.md。

执行流程

1. 对任务分类

写作前确定最接近的文档类型：

• README.md 或概览文档
• API 参考或端点文档
• 架构或设计说明
• 用户指南、运维指南、故障排除、常见问题
• CONTRIBUTING、维护、迁移或发行说明
• JSDoc、文档字符串或代码注释

根据请求的文件、目标路径和用户请求推断文档类型。只有在不同文档类型会导致输出存在实质差异时才提问。

2. 从代码库收集依据

以项目实际文件为准：

1. 先阅读现有文档，以保留项目术语并避免重复过时错误。
2. 检查目录结构、入口点、配置、公共接口、示例和测试。
3. 编写行为说明时，沿着重要流程从输入追踪到输出，不要只看文件名。
4. 编写 API 或架构文档时，对照代码核实路由、配置键、环境变量和默认值。
5. 编写 JSDoc 或注释前，先阅读具体符号的实现。

3. 确定语言、读者和输出位置

1. 使用用户指定的语言，或与周边文档现有语言保持一致。
2. 如果任务是改写为中文，请遵循中文写作参考，而非逐行翻译。
3. 优先直接更新明确指定的文件。
4. 如果没有指定具体文件，请使用惯例位置：
   • README.md、CONTRIBUTING.md、MIGRATION.md 放在仓库根目录
   • 用户、API 或架构文档放在 docs/
   • JSDoc 或代码注释放在源文件中
5. 如果检查代码库后位置仍不明确，请提出一个有针对性的问题。

4. 按正确结构起草

1. 应用 DOCUMENT_TYPES.md 中匹配的模板和必需章节。
2. 根据实际范围调整细节：
   • 小型实用工具或模块：文档更简短、章节更少
   • 多组件流程或公共 API：采用完整结构，并提供示例和失败情形
3. 围绕读者任务、公共接口或数据流组织内容，而非机械照搬目录树。
4. 对包含多个组件的架构文档，加入 Mermaid 图，除非仓库已明确采用其他格式。

5. 编写可通过核验的内容

1. 命令、代码片段、函数签名、环境变量和配置值均以真实文件为依据。
2. 如果行业标准的英文术语比生硬的翻译更清晰，请保留该术语。
3. 中文文档应优先采用自然的中文表达，而不是字面翻译。
4. 只有在无法从代码库推导出事实且该事实对文档完整性必不可少时，才使用 TODO:。
5. 对于注释和 JSDoc，应说明公共约定、副作用、不变量、错误或非显而易见的行为。不要添加只是重复代码内容的模板化注释。

6. 交付前验证

按照 VERIFICATION_CHECKLIST.md 逐项检查并确认：

• 每项重要声明都有代码、配置、测试或现有维护中的文档作为依据
• 示例和命令与项目目录结构一致
• 链接和文件路径均有效
• 未泄露机密、令牌、私有端点或仅供内部使用的备注
• 如适用，中文输出符合中文写作参考

规则

• 不得编造 API、CLI 标志、配置默认值、性能数据或实现细节。
• 复制旧文档中的过时措辞前，务必检查代码是否仍与之相符。
• 常见技术术语在英文形式更自然时，不要生硬地翻译成中文。
• 保持语气简洁、直接、专业。
• 只输出文档内容。除非用户明确要求，否则避免额外的对话式说明。