代码注释助手

它解决什么问题

接手别人的项目，或者回看几个月前自己写的代码时，你往往会把大量时间花在「读懂这段代码在干什么」上，而不是真正动手修改。一个函数读十分钟，还搞不清参数含义和返回值格式；复杂逻辑块没有任何解释，改动时生怕踩雷。手动补注释当然可以，但代码量一旦上来，时间成本陡增，一致性也难以保证——刚写完的注释可能和代码实际行为不符，反而比没有注释更误导人。

它如何工作

这个技能会读取你指定的代码文件，逐段分析逻辑，并生成一份带中文注释的副本。整个过程一句话即可触发，比如「给这段代码加注释」或「给 XXX 路径下的文件加注释」。

具体来说，它会做这些事：

• 格式校验：先确认文件存在且属于支持的类型，目前覆盖 .py、.js、.ts、.java、.c、.cpp、.h、.hpp、.go、.rs、.rb、.php、.sh 等主流语言。
• 分段注释：按代码结构分层添加注释：

- 函数/方法：补充功能说明、参数说明、返回值说明；
- 类：说明类的职责与属性含义；
- 复杂逻辑块：给出执行逻辑的解释；
- 关键变量声明：按需补充说明。

• 非破坏性输出：默认完全不改动原文件，而是在原文件名后加 _commented 后缀生成新副本，保存在同一目录下，例如 main.py 会得到 main_commented.py。这样你可以随时对照原版与注释版的diff，决定是否合入项目。

适用边界与注意点

使用前有几点需要留意：

• 技能只负责加注释，不重构代码，不改变任何逻辑。如果代码本身有问题，仍需自行修复。
• 注释语言固定为中文，风格会与原代码保持一致。如果你的项目要求英文注释，需要生成后自行转换。
• 路径无效或文件不存在时，技能会给出提示并终止，建议提供绝对路径以减少歧义。
• 对于超长文件，逐段分析可能需要一些时间，可以先拆分成更小的文件再逐个处理。