accelint-ts-documentation 是一个面向 JavaScript/TypeScript 代码文档改进的技能，涵盖 JSDoc 注释、注释标记和一般注释质量。
用途
该技能在任务涉及以下内容时激活：
- JSDoc 文档：为导出的函数、类型、接口或类添加 JSDoc 注释；校验 JSDoc 完整性（缺失的 @param、@returns、@template 标签）；确保 @example 标签使用正确的代码围栏；用点号记法记录使用解构的对象参数。
- 注释质量：识别并归类注释，使用合适的标记（TODO、FIXME、HACK、NOTE、PERF、REVIEW、DEBUG、REMARK）；删除不必要的注释（被注释掉的代码、编辑历史、显而易见的陈述）；保留重要注释（标记、linter 指令、业务逻辑）；改进注释位置（把行尾注释移到代码上方）。
- 文档审计：审查代码的文档完整性；确保导出代码有完整文档；校验内部代码具备最低必要文档。
不适用于：通用代码质量问题、性能优化、类型安全改进、框架专属文档（如 React PropTypes、Vue props 等）。
主要能力
技能提供专家判断框架，审计前先思考三个问题：读者是谁（API 消费者缺少实现上下文，需完整文档；团队成员有代码库上下文，只记录非显而易见的行为；未来的自己会遗忘细节决策，记录理由）；不透明还是复杂（意图隐藏必须文档化，实现复杂则用实现注释而非 JSDoc）；维护成本权衡（高变更代码少文档，稳定的 API 完整文档，内部工具简要文档）。
基于此形成两级决策规则：导出（公共 API）必须完整文档，包含 @param、@returns、@template、@throws、@example，即使看起来“显而易见”，因为消费者缺少上下文；内部代码按判断记录函数名、类型签名、参数名和类型、代码库标准模式之外的非自明内容。判断准则：若称职的团队成员会问“为什么”或“边界情况是什么”，就写文档；若会觉得“显而易见”，则跳过。
文档充分性决策树：第一步确定可见性层级（导出为第一级，完整文档；非导出为第二级，基于判断的最小文档）；第二步应用实体专属要求。第一级始终需要：描述（目的、使用上下文、“何时使用”）、所有 @param（对象需有属性文档）、@returns（void 除外）、泛型的 @template 及约束说明、@throws 及触发条件、至少一个真实 @example。第二级按判断：一行简要描述、仅对非显而易见参数写 @param、非显而易见时写 @returns、泛型写 @template、仅在行为复杂时写 @example。实体专属补充：类（构造函数文档、公共方法文档、实例化示例）、类型/接口（所有公共属性的属性描述）、常量/变量（适用时注明单位/约束，如“毫秒”“必须为正”）。
充分性检查清单：所有导出的条目都有完整文档；所有 @param 描述参数的作用（不只是类型信息）；所有 @returns 描述不同场景下的返回值；所有 @example 使用带语言标识符的正确代码围栏；void 函数不写 @returns；泛型函数的每个类型参数都有 @template；对象参数用点号记法描述属性；描述聚焦 WHAT/WHY 而非 HOW。
使用方式
-
根据任务类型加载参考资料：添加/校验 JSDoc 时，必须完整阅读 jsdoc.md，其中包含 @example 代码围栏语法（此处常见失败）、对象参数点号记法、@template 要求、边界情况；除非任务明确提到注释标记或注释质量问题，否则不加载 comments.md。进行注释质量审计时，必须完整阅读 comments.md，其中包含注释标记标准、删除与保留的界限、位置规则；除非任务明确提到 JSDoc 标签或函数/类型文档，否则不加载 jsdoc.md。仅回答疑问（不实施更改）或任务属于通用代码质量时，不加载任何参考资料。
-
应用专家判断框架评估文档。
-
评估文档充分性（见上文决策树与检查清单）。
-
当参考资料不足时：以两级规则为基础；优先清晰而非完整，宁可记录已知内容也不要猜测语法；使用 TypeScript/JSDoc 官方标准约定；用 NOTE 标记记录不确定处，如
// NOTE: JSDoc syntax may need review for [specific case]；若确实含糊，向用户澄清而不是假设。常见未覆盖场景包括奇异 TypeScript 特性（映射类型、条件类型、模板字面量类型）、框架专属模式（带泛型的 React hooks、Vue composables）、多个重载的复杂回调签名，这些情况下默认使用自然语言清晰描述，而非不完整的 JSDoc 标签。 -
对于显式审计请求，使用标准化报告模板 assets/output-report-template.md，提供带清晰前后对比的编号发现项、分类（缺失、不完整、语法错误、质量、内部）、对详细指南的引用、汇总表。在通过
/accelint-ts-documentation <path>直接调用技能、用户明确请求“文档审计”、用户要求“审查所有文档”时使用审计模板；在用户要求“给这个函数加 JSDoc”、问“这条注释有什么问题”、请求具体修复时，不使用审计模板。
适用场景
适用于为导出函数、类型、接口、类补充或校验 JSDoc；整理项目中的注释标记；删除无意义注释并保留重要注释；对代码库进行文档完整性审计并输出结构化报告。
限制
不处理通用代码质量、性能优化、类型安全及框架专属文档。具体价格、平台支持细节、安装命令等资料中暂未提供。文档审计中应避免的常见反模式包括：过度文档化内部代码（内部文档比公共 API 文档腐坏更快，因为紧邻频繁变更的实现）、在 JSDoc 中描述 HOW 而非 WHAT/WHY（JSDoc 会出现在 IDE 自动补全中，暴露实现细节会增加重构面并导致文档漂移）、使用含糊的注释标记（如“TODO: fix this”造成责任扩散，数月后无人知道是否仍相关、该由谁修复、指的是什么）。正确做法是：内部工具写最小文档，公共 API 即使“显而易见”也写完整文档；描述目的和行为而非实现；使用具体标记并注明归属与上下文，如 // TODO(username): Replace with binary search for O(log n) lookup、// FIXME(username): Throws error on empty array, add guard clause。
冲突解决原则：一致性优先于完美（遵循现有代码库模式）、消费者优先于维护者（公共 API 文档服务于缺少上下文的用户，要完整）、意图优先于实现（记录 WHAT/WHY）、稳定优先于变化（稳定代码完整文档，高变更代码最小文档）、未来清晰度测试（“这会在 6 个月后帮到我吗？”若否，删除）。