comment-keeperlisted

# comment-keeper 统一存量代码的注释风格，使其符合 TS 注释规范。核心原则：**代码行为永不改变**——只调整注释，以及必要的、行为严格等价的代码结构调整。 ## 参考规范（开始前必须加载） 按顺序读取以下两份文档，作为本次调整的唯一依据： 1. `~/.claude/rules/ts-comments.md` —— 强制规则（精简版） 2. `~/.claude/docs/ts-comments-guide.md` —— 注释规范详细指南（标签大全、JSDoc 格式、反模式、审查清单） 若第二份缺失，提示用户先运行 `lab deploy docs/ts-code-guide`，不跳过规范直接动手。 ## 确定改动范围 ### 模式一：默认（git diff 变更文件） ```bash git diff --name-only HEAD # 已暂存 + 未暂存的修改 git status --porcelain # 检出 untracked 新增文件 ``` 合并结果，过滤出 `.ts` / `.tsx` / `.d.ts` 文件（含 `.test.ts` / `.spec.ts`），排除 `node_modules/`、构建产物目录。无 TS 文件时告知用户并结束。 ### 模式二：手动指定 | 参数 | 处理方式 | | --- | --- | | 函数名 | Grep 定位定义所在文件，只处理该函数及其直接上下文（函数定义到下一个顶层声明之间），不动文件头/���入区等无关部分 | | 文件路径 | 只处理该文件 | | 目录路径 | 递归处理目录下所有 `.ts` / `.tsx` / `.d.ts`（排除 `node_modules/`、构建产物） | ## 逐文件调整流程 对每个文件按以下顺序执行（对照指南逐节核对）： ### 1. 文件头（指南第八章） 满足任一硬性条件时必须补文件头 JSDoc：含 export 公共 API、含 main 入口或顶级 async 调用、超过 500 行。已有文件头的检查是否过时。 ### 2. 公共 API 的 JSDoc（指南第五章） - 对外暴露的类、函数、接口检查 `@param` / `@returns` / `@throws` - 判断豁免：参数/返回值类型完全自解释且无副作用 → 仅保留一句话业务意图 - 统一多行格式（`/**` 与 `*/` 各占一行，第二行起 ` * ` 前缀） ### 3. 标签体系核对（指南第三章） - 非标准写法（`! 重要`、`[安全]`、`======>` 箭头、emoji、`NOTE : ` 等）→ 转换为标准 `标签: 内容` 格式 - TODO/FIXME 无负责人 → **保留原样**，记入交付摘要待用户补充——绝不虚构负责人 - `@ts-expect-error` 无说明 → 补 `FIXME` 原因��`@ts-ignore` / `@ts-nocheck` → **不擅自删除**（可能掩盖类型错误），记入摘要并建议替换 ### 4. 层次标记（指南第四章） - 类内方法分组用对称分隔符 `// =============== 分组名 ================` - 函数内主要步骤用 `// # 步骤名` - 出现子分隔符（`----`）→ 评估是否提取为独立函数（见"结构调整"） ### 5. 内容质量问题（指南第九、十章） - **删除**：废话注释