【AI应用实战-WorkBuddy】技术文档自动生成：README/API 文档/代码注释（九）

1. 为什么文档自动化总在真实项目里翻车WorkBuddy 这类 AI 编码助手在真实项目里最容易被低估的能力不是写业务代码而是把「代码仓库里已经存在的信息」重新组织成 README、API 文档、代码注释和 Changelog。原因很直接文档的原料其实都在仓库里函数签名、路由定义、类型声明、提交记录这些是结构化的、可提取的AI 做的是翻译和排版而不是凭空创作。适合谁适合那些代码已经跑起来、但文档还停留在「TODO」状态的团队尤其是接口数量超过二十个、每周都在发版、新成员入职要花两天问东问西的项目。我见过太多团队的文档维护流程是这样的发版前夜某个人打开 README手动改几行API 文档停留在三个月前Changelog 靠回忆拼凑。问题不在于懒而在于手工维护文档的边际成本太高每加一个接口就要同步改三处改漏一处就产生误导。WorkBuddy 的价值是把这件事变成可重复执行的工程动作从仓库提取注释与接口定义批量产出文档再跑一次校验确认没有遗漏。这篇是系列第九篇聚焦落地。我会给出可复制的config.toml骨架、TaoToken 统一 Key 的配置方式然后完整走一遍「提取 → 生成 → 校验」的流程。你不需要重写项目只需要在现有仓库上加一个文档生成目录。2. TaoToken 前置统一 Key 与 WorkBuddy 的接入位置WorkBuddy 在生成文档时需要调用大模型来完成「理解代码结构 → 输出 Markdown」这一步。如果你的项目里同时有多个 AI 工具编码补全、文档生成、代码审查每个工具各配一套 Key 会很快失控额度分散、账单混乱、换模型要改多处。TaoToken 在这里的角色是统一入口一个 Key 覆盖多个模型文档生成、代码补全、对话调试走同一个地址。接入点有两个按你的使用方式选如果你在 WorkBuddy 的图形界面里配置模型走模型对话入口把 Base URL 和 Key 填进去即可。如果你用脚本或 CI 批量生成文档走 API 入口在环境变量里注入 Key。具体地址官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocs_autoAPI 基址https://taotoken.net/api模型对话配置页https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_autoAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_auto接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_auto注意Key 只放在环境变量或本地配置文件里不要提交进仓库。下面给的config.toml骨架里Key 字段留空用${TAOTOKEN_API_KEY}占位。如果你还没建 Key先去 API Keys 页面创建一个复制出来备用。这一步不涉及任何网络工具就是普通的网页操作。3. 可复制配置config.toml 骨架与目录结构WorkBuddy 的文档生成任务建议单独放一个目录不要和业务代码混在一起。推荐结构your-project/ ├── src/ # 业务代码 ├── docs/ # 生成的文档输出 │ ├── README.md │ ├── api.md │ └── CHANGELOG.md ├── .workbuddy/ │ ├── config.toml # 文档生成配置 │ └── prompts/ # 提示词模板 └── scripts/ └── gen_docs.sh # 一键执行脚本config.toml骨架如下字段含义我写在注释里# .workbuddy/config.toml [provider] # TaoToken 统一入口所有模型请求走这里 base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 文档生成建议用长上下文模型能一次读进多个文件 model claude-sonnet-4-20250514 timeout_seconds 120 [project] name user-service language python framework flask source_dirs [src] entry_file src/app.py [extract] # 从哪些文件提取接口定义 api_patterns [src/routes/*.py, src/api/*.py] # 从哪些文件提取函数注释 comment_patterns [src/**/*.py] # 忽略的目录 exclude [tests, migrations, __pycache__] [generate] # 每个文档类型的输出路径 readme_output docs/README.md api_output docs/api.md changelog_output docs/CHANGELOG.md # 注释风格pep257 / jsdoc / godoc comment_style pep257 # 文档语言 doc_language zh [changelog] # 从 git 提交记录生成 git_log_range last_tag..HEAD group_by [feat, fix, refactor, docs, chore] [validate] # 生成后校验接口数量是否匹配 check_api_count true # 校验 README 是否包含必需章节 required_sections [安装, 使用, API, 许可证]环境变量注入方式在scripts/gen_docs.sh里#!/usr/bin/env bash set -euo pipefail # 从本地 .env 读取不要硬编码 export TAOTOKEN_API_KEY$(grep TAOTOKEN_API_KEY .env | cut -d -f2) # 执行文档生成 workbuddy docs generate --config .workbuddy/config.toml # 执行校验 workbuddy docs validate --config .workbuddy/config.toml.env文件加进.gitignore只保留.env.example给团队参考。4. 完整生成流程从提取到校验配置就绪后走一遍完整流程。我把它拆成四步每步都有可观察的输出。4.1 提取接口定义与注释WorkBuddy 先扫描api_patterns匹配的文件把路由定义、请求方法、参数、返回结构抽出来。以 Flask 为例源文件长这样# src/routes/user.py from flask import Blueprint, request, jsonify from src.services.user_service import create_user, get_user bp Blueprint(user, __name__, url_prefix/api/users) bp.route(, methods[POST]) def create_user_route(): 创建新用户。 请求体: username (str): 用户名 email (str): 邮箱 password (str): 明文密码 返回: 201: 用户信息与 Token 400: 参数缺失或格式错误 data request.get_json() user create_user(data[username], data[email], data[password]) return jsonify(user.to_dict()), 201提取阶段会输出一份中间结构类似{ endpoints: [ { path: /api/users, method: POST, handler: create_user_route, docstring: 创建新用户。..., params: [username, email, password], responses: {201: 用户信息与 Token, 400: 参数缺失或格式错误} } ] }这一步不调用模型纯静态解析速度快适合放进 pre-commit 钩子。4.2 生成 README 与 API 文档提取完成后WorkBuddy 把中间结构 提示词模板一起发给模型。提示词模板放在.workbuddy/prompts/api.md你是一个技术文档工程师。根据以下接口定义生成 API 文档。 要求 1. 每个接口包含接口描述、请求路径与方法、请求参数Path/Query/Body、返回格式、错误码、请求与返回示例。 2. 使用 Markdown 表格展示参数。 3. 示例代码用 curl 和 Python requests 各写一份。 4. 语言简洁不要客套话。 接口定义 {{endpoints_json}}执行生成workbuddy docs generate --config .workbuddy/config.toml --type api输出到docs/api.md片段示例### POST /api/users 创建新用户。 **请求参数** | 参数 | 位置 | 类型 | 必填 | 说明 | |------|------|------|------|------| | username | body | string | 是 | 用户名 | | email | body | string | 是 | 邮箱 | | password | body | string | 是 | 明文密码 | **返回示例** json { id: 1, username: alice, email: aliceexample.com, token: eyJhbGciOi... }错误码状态码说明400参数缺失或格式错误409用户名或邮箱已存在README 生成走另一套模板重点是把项目简介、安装步骤、快速开始、目录结构拼出来。这里的关键是让模型读 entry_file 和 source_dirs 的顶层结构而不是逐行读代码否则 token 消耗会失控。 ### 4.3 生成 Changelog Changelog 的原料是 git 提交记录。WorkBuddy 读取 git_log_range 指定的范围按 group_by 分类 bash git log --prettyformat:%s|%h|%an v1.1.0..HEAD输出经过模型整理后## [1.2.0] - 2024-01-15 ### 新增 - 支持用户批量导入#234 - 新增 /api/users/batch 接口#241 ### 修复 - 修复 Token 过期后未正确返回 401 的问题#238 ### 重构 - 用户服务拆分为独立模块#240提示提交信息规范feat/fix/refactor 前缀直接决定 Changelog 质量。如果团队提交信息混乱先花一周统一格式再上自动化。4.4 校验接口数量与章节完整性生成完不算完要校验。validate阶段做两件事第一对比提取到的接口数量和文档里出现的接口数量。如果源文件有 18 个路由文档里只写了 15 个说明模型漏了直接报错[ERROR] API count mismatch: extracted18, documented15 Missing: POST /api/users/batch, DELETE /api/users/{id}, GET /api/health第二检查 README 是否包含required_sections里的章节。缺哪个补哪个或者调整提示词模板。校验通过后把docs/目录提交进仓库CI 里加一步workbuddy docs validate文档过期就阻断合并。5. 本篇常见错排查5.1 生成结果里接口漏了或重复最常见的原因是api_patterns没覆盖全。比如路由定义分散在src/routes/和src/api/两个目录配置里只写了一个。排查方法先跑提取阶段看输出的endpoints数量是否等于grep -r bp.route src/ | wc -l。不相等就补 pattern。另一个原因是模型上下文截断。接口超过 30 个时一次请求塞不下模型会「忘记」后面的。解决办法是分批按文件分组每个文件单独生成最后合并。5.2 注释风格不统一comment_style设成pep257但项目里混了 Google 风格和 NumPy 风格模型会跟着混。建议先统一存量注释或者在校验阶段加一条规则检查生成的注释是否包含Args:/Returns:字段缺了就报 warning。5.3 Changelog 分类错乱提交信息写成「update code」「fix bug」这种模型没法分类全塞进「其他」。这不是模型的问题是提交规范的问题。可以在 CI 里加 commitlint强制前缀。5.4 Key 报 401 或 403先确认环境变量有没有正确注入echo $TAOTOKEN_API_KEY | head -c 8如果输出为空说明.env没加载。如果输出正常但还报错去 API Keys 页面确认 Key 没过期、额度没用完。Base URL 要写https://taotoken.net/api不要多加路径。5.5 生成速度慢或超时文档生成是长上下文任务单次请求可能几十秒。timeout_seconds设 120 起步。如果还是超时把source_dirs缩小只提取接口文件不要全仓库扫描。6. 把文档生成接进日常流程配置跑通之后下一步是让它变成习惯。我的做法是在Makefile里加两个目标docs-gen: workbuddy docs generate --config .workbuddy/config.toml docs-check: workbuddy docs validate --config .workbuddy/config.toml发版前跑make docs-genCI 里跑make docs-check。文档不再是「有空再补」的事而是和测试一样是合并前的必过项。如果你还在手工维护 API 文档建议先从接口数量最多的那个模块开始只生成 API 文档跑通校验再扩展到 README 和 Changelog。一步一步来比一次性全上要稳。需要长期在编码和 Agent 场景里用统一 Key 的可以看 Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_auto模型对话调试走https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_autoKey 管理和接入文档分别在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_auto 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdocs_auto先把config.toml复制过去改掉project段的字段跑一次提取看看接口数量对不对。对上了再往下走生成和校验。