document

用途

document 是 han-core 技能集中的一个文档技能，名称与用法为 han-core:document，命令形式 /document [arguments]。它用于为代码、API 或系统生成或更新文档，核心原则是「为读者而写，而不是为自己而写」。当用户提出「为这个项目写 README」「记录这个 API 端点」「为这段复杂函数添加注释说明」「创建开发环境搭建指南」「更新文档以反映新的认证流程」等请求时，该技能适用。

覆盖的文档类型

README 文件：帮助用户了解项目做什么、如何使用。受众是新用户与潜在贡献者。关键章节包括：项目做什么（一段话）、安装说明、快速上手示例、常见用例、完整文档链接、如何贡献、许可证。
API 文档：帮助开发者正确使用 API。受众是集成该代码的其他开发者。关键信息包括：端点/函数签名、参数与类型、返回值、错误情形、认证要求、示例。
行内注释：解释非显而易见的决策与复杂逻辑。受众是未来的开发者（包括未来的自己）。添加时机包括：非显而易见决策（解释「为什么」而非「做什么」）、复杂算法、临时绕过方案、边界情况、性能考量、安全考量。
技术指南：教授如何完成特定任务。受众是使用该系统的开发者。类型包括操作指南（分步骤）、架构概览（系统结构）、集成指南（连接系统）、故障排查指南（调试帮助）。
架构决策记录（ADR）：记录重要技术决策及其理由。受众是当前与未来的团队成员。关键信息包括：上下文（存在什么问题）、决策（选择了什么）、考虑过的备选方案、后果（权衡）。

文档原则

资料中给出的「好文档」标准：为读者而写（符合其水平与需求）、清晰（除非必要不用术语）、具体（示例优于抽象描述）、完整（回答关键问题）、可维护（代码变更时同步更新）。「坏文档」特征：解释「做什么」而非「为什么」、假设读者懂太多、没有示例、过时、过于冗长或过于简略。

主要模板与示例

技能提供了多套模板：

README 模板：包含项目名、一段简介、Features、Installation（如 npm install project-name）、Quick Start（import 与使用示例）、Usage（基础与进阶用法）、API Reference（函数签名、参数、返回值、抛出错误、示例）、Configuration、Troubleshooting、Contributing、License。
REST API 模板：以 POST /api/users 为例，涵盖认证（Authorization 头中需管理员访问令牌）、请求头与请求体 JSON、请求体参数（email 必填且唯一、name 必填 2-100 字符、role 可选，取值 user/admin，默认 user）、成功响应（201 Created 及返回 JSON）、错误响应（400、401、403、409、429 及对应 JSON）、cURL 与 JavaScript 调用示例、速率限制说明（每分钟每 API key 100 次请求，超限返回 429，查看 X-RateLimit-Remaining 头）。
函数/方法文档模板：以 TypeScript 的 calculateTotal 为例，展示 JSDoc/TSDoc 风格注释，说明税额基于小计计算（不含运费）、超过 50 美元免运费、@param、@returns、@throws（items 为空或价格/数量非法时抛错）与 @example 用法。
技术指南模板：包含标题（How to [Task Name]）、简介、Prerequisites、Overview、分步骤指令（每步含命令与预期结果、出错怎么办）、完整示例、Common Issues（现象、原因、解决方案）、Related Documentation、Next Steps。
ADR 模板：包含 ADR 编号与标题、状态（Proposed | Accepted | Deprecated | Superseded）、日期、决策者、Context、Decision、Alternatives Considered（每个方案的描述、优点、缺点、未选原因）、Consequences（正面、负面、中性）、Implementation Notes、References。

行内注释规范

应注释：为什么（非显而易见决策的理由）、权衡（刻意选择）、临时方案（临时解决办法）、复杂逻辑（难懂算法）、边界情况、性能（优化选择）、安全（安全考量）。不应注释：做什么（代码已自解释）、冗余（重复代码）、显而易见的内容。

资料给出了正反例对比，例如：坏注释「// Loop through users」与好注释「// Process in creation order to maintain referential integrity（较新记录可能引用较旧记录）」；坏注释「// Add 1 to counter」与好注释「// +1 offset because API uses 1-based indexing (not 0-based)」；以及用 Number.toFixed(2) 防止浮点误差的说明。还指出不要保留被注释掉的代码，临时方案应写成带上下文与负责人的 TODO（如 // TODO: Remove when new tax API is deployed (JIRA-123)）。

注释格式约定：单行注释 // 用于简短说明；多行注释 /* / 用于较长解释；文档注释 /* */（JSDoc/TSDoc）用于 API 文档，可被文档生成器解析；特殊标记包括 TODO(username)、FIXME、HACK、NOTE。

最佳实践与常见错误

最佳实践包括：针对不同受众写不同文档（新用户看快速上手与常见用例，API 使用者看完整参考与示例，贡献者看架构与开发环境，维护者看设计决策与权衡）；用示例展示而非仅文字描述；保持示例可运行（复制粘贴可用、包含全部 import、展示完整代码、验证确实能跑）；维护文档（代码变更时更新、PR 中包含文档更新、定期审查、明确标记过时内容）；使用清晰语言（避免术语、具体量化、使用主动语态）。

常见错误包括：没有示例、信息过时、假设读者有背景知识、示例不完整、文档过多（逐行注释）。资料提供了文档检查清单，分别覆盖 README、API 文档、行内注释、技术指南四类。

与其他技能的配合与备注

资料提到可配合 explain 技能创建清晰解释、用 proof-of-work 技能验证示例确实可用、参考 architect 技能编写架构文档、参考 technical-planning 技能编写实现指南。备注建议：使用 TaskCreate 跟踪文档任务；让文档贴近代码（行内注释、同目录 README）；代码变更时更新文档并纳入 PR 审查；示例胜千言；测试示例确保可用；考虑用 JSDoc/TSDoc 编写行内 API 文档。

限制

资料未提供该技能的收费、价格、支持平台、安装方式等具体信息，暂未提供。