开站第一篇说了这个站要写什么，今天进入正题。第一期写自己手搓的小工具——ai-comment-gen，一个 VSCode 插件：选中代码 → 右键 → AI 自动生成注释。掘金上发过开发记录，这篇是站在博客视角的完整版介绍。

为什么做这个

写注释这件事，做了 10 年前端，从来没真正喜欢过。不是不会写，是不想写——特别是接手别人的烂代码，每行都要猜"这到底在干嘛"；也写过太多"以后补注释"然后永远没补的代码。

AI 出来后我一直在想：能不能让它把这事干了？试过的已有方案都不解渴：在线工具要复制粘贴，ChatGPT 手动对话更麻烦，现成插件要么太慢要么质量不行。所以干脆自己做一个——1 天时间，做出来了。

效果长什么样

最直接，看一段代码改造前后：

// 之前：盯半天
const a = items.filter(x => x.status === 'active')
  .sort((a, b) => b.priority - a.priority)
  .slice(0, 5);

选中 → 右键 →「AI 生成注释」之后：

// 从活跃项目中按优先级排序，取前5条
const a = items.filter(x => x.status === 'active')
  .sort((a, b) => b.priority - a.priority)
  .slice(0, 5);

舒服了。

三种使用方式

  1. 选中生成：右键「AI 生成注释」出简洁一句话；「AI 生成详细注释」出 JSDoc / docstring
  2. 整文件批量：右键「AI 为整个文件添加注释」，自动扫描未注释的函数逐个生成，一次最多 5 个（可配），防止手滑烧穿配额
  3. 保存时自动补：设置里勾 autoCommentOnSave，每次保存自动补全未注释的函数——懒人专属

语言上自动匹配注释风格：JS/TS 用 // 和 /** */、CSS/SCSS/Less 用 /* */、HTML/Vue 模板用 <!-- -->、Python/Ruby 用 # 和 """docstring"""；中英文在设置里一切换就行。

技术实现（主体代码 200 行）

技术栈简单到寒酸：Node.js + 官方脚手架 + DeepSeek API（速度快、便宜，百万 token 几块钱）。核心流程就三步：

// 1. 用户选中代码 → 右键点击
// 2. 调用 AI API 生成注释
// 3. 把注释插入到代码上方

真正花时间的地方：

  • Prompt 是灵魂。要注释"不啰嗦也不废话"，试了十几种 Prompt 才找到平衡点，大意是：
你是一个资深前端工程师，请为以下代码生成简洁的中文注释。
只返回注释内容，不要多余的解释。
  • temperature: 0.3 + max_tokens: 1024。温度越低输出越稳不跑偏，限长防止 AI 开始抒情。
  • API 走 OpenAI 兼容格式，apiUrl 和 model 都是配置项，默认 DeepSeek，想换任何兼容端点都行。
  • 注释插回编辑器走 WorkspaceEdit——选区行号会动态变，直接改文本必崩，这是 VSCode 扩展 API 给的第一课。

效果实测

拿公司项目测的：

代码类型生成速度注释质量
简单函数< 1 秒⭐⭐⭐⭐⭐ 直接可用
React 组件1-2 秒⭐⭐⭐⭐ 偶尔调几个字
复杂逻辑2-3 秒⭐⭐⭐⭐ 基本能用
CSS/样式< 1 秒⭐⭐⭐⭐⭐ 完美

90% 的场景生成的注释直接可用，改几个字就行，比从零写省 90% 时间。

但要泼一句冷水

AI 只配写"是什么"，“为什么"必须你自己写——它不知道这段 workaround 在绕哪个坑、那个魔法数字是谁拍板的。也别贪多开全文件模式量产 i++ // i 自增 1 式噪音：错的注释比没注释更毒，它会以"文档的权威"误导下一个读代码的人，包括半年后的你。我自己的用法：只对"接手区"选择性生成，what 收下，why 自己补。

回头看这 1 天

  • AI 写注释是真的香——不是花架子，是实实在在省时间的工具
  • 小工具也能有大价值——解决一个具体小痛点，比做大而全的产品更有用
  • VSCode 插件开发比想象中简单——官方文档完善，脚手架一键生成

安装

开源、免费，两个渠道：

  • VSCode 插件商店：搜 AI 注释生成器 或 ai-comment-gen（已上架）
  • GitHub：kunjingzhu/ai-comment-gen（MIT），Releases 下载 .vsix → 扩展 → 右上角 ... → 从 VSIX 安装

⚠️ 需要自备 DeepSeek API Key（platform.deepseek.com 注册，新用户送 500 万 token 额度，够写几万行注释）

后续计划：更多语言（Go、Rust、Java）、自定义注释风格模板、纯离线模式（本地模型）。觉得有用，去 GitHub 点个 Star ⭐ 让更多人看到。

本文属于「AI 开发工具」系列。开发过程的完整记录见掘金同名文章，这个博客之后会放更细的实现拆解。