AI Docstring 生成器横评：Copilot 免费版胜出，独立创业公司几乎团灭

每个 Python 开发者都经历过这种时刻：打开一个文件，看到一个叫 process() 的函数带三个参数、没有一行 docstring，然后默默诅咒写下它的人。到了 2026 年，那个人通常是一个 AI Agent。

没人提前警告我们的是：文档债并没有随着编码助手的普及而消失，它只是改变了形态。代码交付速度前所未有地快，没有文档的代码交付得同样快——因为 Agent 写函数的方式，和写购物清单差不多。

一位开发者在过去几周里，把当前一代 AI docstring 生成器放进了同一套测试流程：一个继承来的 60 模块 Flask API、一个带清晰类型提示的中型 FastAPI 服务，以及一个几乎没有类型标注的小型 CLI 工具。同一批测试函数、三种 docstring 风格（Google、NumPy、Sphinx），每款工具只问一个问题：这段输出，我会不改一个字直接合并吗？

AI Docstring 生成器横评

Copilot 仍是默认选项，免费版真的够用

Copilot 是 2026 年部署最广的 docstring 工具，原因不是有人为文档而造它，而是文档只是它的副作用。选中一个函数、要求生成 docstring，它会输出 Google 或 NumPy 风格的文档，并且内容真正反映代码行为——因为它已经读过同一文件的其他部分、你的测试，甚至相邻模块。

GitHub 官方定价页显示：免费版 $0，每月 2000 次补全与有限对话；Pro $10/月；Pro+ $39/月；Max $100/月。

最让人意外的结论是：对大多数独立开发者的 docstring 工作来说，免费版已经足够。每月两千次补全听起来不多，但文档一个函数只消耗一次补全，而不是每个按键一次。在类型良好的代码上输出质量稳定；在动态遗留代码上表现一般——付费档位同样如此。

缺点也很明确：Copilot 只文档你面前这个函数，没有“扫描整个仓库、补齐缺口”的模式，没有覆盖率百分比，无法阻止无文档代码进入主分支。它是一个出色的写作工具，却是一个不存在的执行工具。

什么是 docstring？ docstring 是 Python 中写在模块、函数、类或方法定义第一行的字符串字面量，通过 __doc__ 属性暴露，并可被 help()、pydoc、Sphinx、IDE 悬停提示等工具自动提取。它和普通注释有本质区别：注释是给读源码的人看的，会被解释器忽略；而 docstring 是可被程序读取的结构化元数据，因此能驱动文档站点生成、类型检查器（如 mypy 的 --strict 会检查 docstring 风格）、以及 pytest 的测试发现。Google、NumPy、Sphinx 是三种主流风格，区别主要在于参数与返回值的排版约定：Google 风格用 Args:/Returns:/Raises: 缩进块，NumPy 风格用下划线段落标题，Sphinx 风格用 :param:/:return:/:raises: 字段。风格选择本身不影响功能，但会影响下游工具链的解析结果，所以团队一致性比选哪种更重要。

Claude Code：批量文档化的最佳选择

如果你的真实问题是“这个仓库有 400 个没有文档的函数”，Copilot 的一次一个节奏就是错的形状。Claude Code 会读取整棵目录树。指向一个目录，要求它在保留已有 docstring 的前提下补齐全部文档，它一口气啃完整个积压。

这是测试中输出质量最高的工具：它能捕获 Raises 子句，理解 transfer_funds() 是一个账户扣款、另一个账户入账，并写出真正能跑的用法示例。

定价方面，Anthropic 官方显示 Claude Code 包含在 Claude Pro $17/月（年付，一次性 $200；月付则 $20）中，Max 5x $100/月、Max 20x $200/月。也可以走 API 按 token 付费，小型仓库的批量运行每次只需几美元。

代价在于：它不是 docstring 工具，而是一个有主见的 Agent。在一个遗留模块上，它顺手“修复”了一个细微 bug。修复本身是对的，但没人要求它这么做——审阅一个 80% 是 docstring、20% 是未经请求的重构的 diff，本身也是一种工作。文档任务想要的恰恰是可预测的一条命令行为，而自主 Agent 恰恰不是这个。

为什么 Agent 式工具会产生“未经请求的修改”？ 像 Claude Code 这类基于大语言模型的自主 Agent，其工作循环是“读取上下文 → 推理 → 调用工具 → 观察结果 → 继续”，而不是“执行一条固定命令”。当它在补 docstring 时读到一段它认为有 bug 的代码，模型的“帮助性”倾向会驱使它顺手修复——因为从它的视角看，修复缺陷也是让代码变好的一部分。这与传统的批处理脚本有根本差异：脚本只会做你让它做的事，Agent 会做它认为你该做的事。这就是为什么在文档任务中，“可预测性”往往比“能力上限”更被看重。控制手段包括：明确在 prompt 中限定“只添加 docstring，不要修改任何逻辑代码”、使用只读权限或 git diff 审阅、以及在 CI 中配置需要人工批准的 PR 门禁。理解这一行为模式，有助于区分“工具不好用”和“工具用错了场景”。

Devin（原 Codeium/Windsurf）：内联不错，但买它的理由不对

Codeium → Windsurf → Devin 的合并已经完成：windsurf.com/pricing 现在跳转到 Devin 的页面。当前档位是 免费 $0（轻量 Agent 配额、无限 Tab 补全与内联编辑）、Pro $20/月、Max $200/月、Teams $80/月外加每席位 $40。

内联 docstring 质量不错——Python 上大致和 Copilot 持平，TypeScript 风格代码上偶尔更好。但真正的反对理由是：你花 $20/月买的是一个自主 Agent 平台，docstring 只是其功能集中一个可忽略的零头。如果目标是文档，这是通往 Copilot 免费版同样输出的最贵路径。

开源 CLI 路线：docstring-ai 与离线单文件方案

在 PyPI 这边，最受好评的是 docstring-ai：MIT 许可、2026 年 4 月发布、由一位开发者维护。pip install docstring-ai，指向文件或目录，选择 google、numpy 或 sphinx 风格，它会批量生成并跳过已有文档的函数。Dry-run 模式在动任何文件前打印摘要——“Generated: 8 / Already had: 3 / Skipped: 2”，并且开箱即用支持 CI。

工具本身 $0，运行成本取决于你的 ANTHROPIC_API_KEY 账单——因为它需要一个 key。一次性补全只是零钱；把它接到每次 push 的 CI 上，API 账单就变成了一份你从没签过的订阅。尽管如此，在这个价位里，没有别的批量方案能接近它。

另一个路线是离线优先的单文件 CLI：scan 找出代码库中所有无文档函数，generate --apply 原地插入 docstring 并保留原有格式，check --fail-below 80 在文档覆盖率跌破阈值时让 CI 失败。默认离线运行、无需 API key，可选的 --llm 标志用于模型生成文本，另外支持 README 风格的 API 参考生成与 JSON 导出。它是一次性 $49，没有席位、没有月度计费——唯一在这里表现得像个产品、而不是计费表的选项。（注：原文作者披露该工具为其自有产品，并包含联盟链接。）

那些消失的 docstring 创业公司

两年前，这篇文章大概会以 docstring.io 和 PyDoc AI 开头。但这两个站点本月都已无法访问，PyDoc AI 的搜索结果已经什么都查不到。Stenography——那个“保存即自动文档”的宠儿——被第三方追踪器列为可能已死亡，域名也无法加载。这些工具加入了 docstring 墓地，而它们的商业模式活该死在那里：一家独立创业公司按席位收费，去做每个通用编码助手现在免费就能做的事。

甚至连 Sourcegraph Cody——“向你的代码库提问任何问题”的旗手——也已不再提供个人选项。2026 年 Sourcegraph 的定价页只剩企业级：联系销售、信用额度分配、没有自助档位。如果你的 docstring 策略依赖 Cody，那它现在依赖的是一通销售电话。

另一个免费选项也变了：Gemini Code Assist

两年来，Google 的免费档位一直是向个人推荐的“免费胜过一切”。随后，根据 Google 自己的横幅通知，面向未付费用户的 Gemini CLI 与 Gemini Code Assist IDE 扩展已于 6 月 18 日被 Antigravity 取代，用户被要求迁移，否则将面临功能中断。付费版 Gemini Code Assist Standard 为 $22.80/月（月付）或 $19/月（年付承诺）；Enterprise 为 $54 或 $45。教训是：一个由会在一夜之间重塑整个开发者栈的公司拥有的免费档位，是一份到期日不由你控制的免费档位。

对比表

工具	工作方式	价格	输出质量	最适合
GitHub Copilot	VS Code/JetBrains 内联生成，无仓库级扫描	免费（2000 次补全/月）；Pro $10/月	类型化代码上很好；动态遗留代码上一般	边写边文档——测试中最佳免费选项
Claude Code	Agent 式整目录批量文档；保留已有文档	含于 Claude Pro $17–20/月；Max $100–200/月；或 API 按 token	优秀——Raises 子句、可运行示例、真实业务语境	一次性补齐大型遗留仓库
Devin（原 Codeium/Windsurf）	自主 Agent 平台内的内联编辑与 Tab 补全	免费（轻配额）；Pro $20/月；Teams $80/月 + $40/席位	良好，Python 上与 Copilot 持平	已因其他原因购买 Agent 平台的团队
docstring-ai（PyPI 开源）	批量 CLI：文件/目录扫描、三种风格、dry-run、CI 就绪	工具免费（MIT）；自付 Anthropic API 账单	良好且一致；风格严格	零席位成本的 CI 管线与脚本化补全
Gemini Code Assist → Antigravity	IDE 补全与对话；免费档位已被 Antigravity 取代	Standard $19–22.80/月	良好；历史上免费额度慷慨	已在 GCP 上的 Google 技术栈团队
离线单文件 CLI（作者自有）	离线优先：scan、generate --apply、CI 覆盖率门禁、README 导出	$49 一次性	结构化且一致；可选 LLM 模式	不订阅也能在 CI 中强制执行文档覆盖

这些工具不适合谁

需要公开文档站点的人。 这些工具都不发布可托管的、可浏览的 API 文档——那是 Mintlify、ReadMe 或 Swimm 的地盘。docstring 是原材料，不是网站。
高度动态的代码库。 在重度依赖装饰器、元类、getattr 技巧或 ORM 魔法的代码上，测试的每个 AI 工具都产出了自信、貌似合理但错误的描述。如果这些文字不可信，docstring 就只是装饰。
想要文档始终同步的人。 Copilot、Devin 和 Gemini 都只对某个时间点做文档，之后再也不看。只有 CI 覆盖率门禁（或 Swimm 这类与代码耦合的工具）能捕获漂移，而百分比门禁只告诉你文档存在，不告诉你它是真的。
把工具当作评审替代品的团队。 AI docstring 仍需要人工略读。在混乱的遗留代码上，大约每 50 条生成的 docstring 就有一条事实错误——数字很小，但会累积成自信的错误文档。

什么是文档漂移与覆盖率门禁？ 文档漂移（documentation drift）指代码演进后 docstring 未同步更新，导致文档描述与实际行为不符。AI 生成工具尤其容易造成漂移，因为它们只在被调用那一刻阅读代码，之后既不会监控改动，也不会主动失效旧文档。覆盖率门禁（coverage gate）是一种 CI 机制：统计带 docstring 的函数占比，低于阈值就令构建失败，例如文中的 check --fail-below 80。它能在“文档是否存在”这一维度上强制约束，但无法验证文档是否正确——一个函数可能顶着 80% 覆盖率、却有一半 docstring 在说谎。要对付漂移，需要把文档与代码耦合的工具（如 Swimm）或人工评审。因此实践中通常组合使用：门禁防遗漏，抽查防错误。理解这一点，才能理解文中“百分比门禁只告诉你文档存在，不告诉你它是真的”这句话的分量。

诚实的结论

如果你边写边文档，Copilot 的免费档位确实胜过大多数付费选项——在 2026 年说出这句话，作者自己也没料到。每月两千次补全覆盖了大多数独立开发者，而且在测试模块上，$0 档位的输出质量与 $10 档位无法区分。

如果你在补全旧仓库，Claude Pro 是性价比最高的选择（前提是你已经付费）——一个下午的 Agent 时间加上几美元的 API 用量，换来数百条 docstring。如果你拒绝按席位订阅，批量 CLI 是诚实的答案：开源 docstring-ai 除了 API token 之外不要钱，而一次性 $49 的工具是这里唯一表现得像产品、而非计费表的选项。

如果有人还在团队里提议做 docstring 专用创业公司：先检查它的官网能不能打开。这个品类输给了通用助手，而幸存者正是那些助手。

一个不太舒服的总结：在 2026 年，几乎没有人应该专门为 docstring 生成付费。为你本来就会用的助手付费、让它顺手文档，或者为 CI 中的强制执行一次性付费。除此之外的一切，都是租一把锤子。