资源描述
一款面向前端/全栈开发团队的 GitHub PR 驱动技术文档自动化工作流，支持在 PR 合并后自动提取变更代码与 JSDoc/TypeDoc 注释，调用 LLM（如 Claude 或本地 Ollama 模型）生成结构化 API 参考文档与语义化变更日志，并自动提交至 docs/ 目录触发 Docusaurus 构建。显著降低文档维护成本，保障文档与代码同步，适用于 TypeScript 项目与 CI/CD 标准化流程。
详细内容
# GitHub PR → Technical Documentation Auto-Generation Workflow
本工作流实现「代码即文档」的闭环：当 Pull Request 合并至 `main` 分支时，自动触发文档生成流水线，确保 API 文档、变更说明与源码严格一致。
## 工作流概述
1. **触发**：GitHub Actions 监听 `pull_request` 事件（`types: [closed]` + `branches: [main]` + `pull_request.merged == true`）
2. **提取**：检出最新代码，使用 `typedoc` 或自定义 AST 解析器提取变更文件中的 JSDoc/TypeDoc 块及导出接口签名
3. **增强理解**：结合 Git diff 分析影响范围（新增/修改/删除的模块、函数、类型），生成上下文提示词（Prompt）
4. **生成**：调用 LLM（推荐 Claude-3-haiku 或本地部署的 Qwen2.5-Coder-7B）生成符合 Docusaurus MDX 格式的 API 文档页 + `CHANGELOG.md` 片段
5. **发布**：将生成的 `.mdx` 文件写入 `docs/api/` 目录，提交至仓库（跳过 CI：`git commit --no-verify -m "docs: auto-generate API docs [skip ci]"`），并触发 `docusaurus build` 部署
## 分步骤操作说明
### 步骤 1：配置 GitHub Actions 工作流文件
在 `.github/workflows/docs-auto-gen.yml` 中定义：
```yaml
name: Auto-generate Technical Docs
on:
pull_request:
types: [closed]
branches: [main]
jobs:
generate-docs:
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
```
### 步骤 2：安装依赖并提取变更元数据
添加步骤解析 PR 影响范围：
```yaml
- name: Extract changed files and exports
id: diff
run: |
# 获取合并后 main 分支上本次 PR 引入的变更文件（仅 src/ 和 packages/ 下的 .ts/.tsx）
git diff HEAD^ HEAD --name-only --diff-filter=AM | grep -E '\.(ts|tsx)$' | grep -E '^(src|packages)/' > changed_files.txt
echo "CHANGED_FILES=$(cat changed_files.txt | tr '\n' ' ')" >> $GITHUB_ENV
# 使用 ts-morph 或 typedoc --json 提取接口摘要（需提前配置 typedoc.json）
npx typedoc --json ./typedoc-output.json --excludePrivate --ignoreCompilerErrors ./src/index.ts
```
### 步骤 3：构造 LLM 输入并调用文档生成脚本
编写 `scripts/generate-docs.mjs`（Node.js ESM）：
- 读取 `typedoc-output.json` 和 `changed_files.txt`
- 构建 Prompt：包含「角色设定（Technical Writer for TypeScript SDK）、输入格式（JSON 接口摘要+diff 摘要）、输出要求（MDX 格式、含 @site/docs/api/ 路径前缀、含 `---` frontmatter、含 `changelog-entry` 注释块）」
- 调用 LLM API（如 Anthropic 或 Ollama）或本地模型服务，超时设为 120s，重试 2 次
- 验证输出是否符合 MDX 语法（使用 `remark-parse` 简单校验）
### 步骤 4：写入文档并提交
```yaml
- name: Run doc generation script
run: node scripts/generate-docs.mjs
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# 或使用 OLLAMA_HOST: http://localhost:11434
- name: Commit generated docs
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add docs/api/
git status --porcelain | grep '^M\|^A' && \
git commit -m "docs: auto-generate API docs from PR #${{ github.event.pull_request.number }} [skip ci]" || echo "No docs changes to commit."
- name: Push to origin
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: ${{ github.head_ref }}
force: false
```
### 步骤 5：触发 Docusaurus 构建（可选独立 workflow）
在 `docs/` 目录提交后，通过 `repository_dispatch` 触发另一 workflow：
```yaml
- name: Trigger Docusaurus build
uses: peter-evans/repository-dispatch@v3
with:
token: ${{ secrets.PAT_FOR_DISPATCH }} # 需预配 Personal Access Token（含 public_repo 权限）
repository: ${{ github.repository }}
event-type: 'docs-updated'
client-payload: '{"ref":"main"}'
```
并在 `.github/workflows/docusaurus-deploy.yml` 中监听该事件，执行 `npm run build && npm run deploy`。
## 注意事项与最佳实践
- ✅ **安全前提**：LLM 输入必须过滤敏感信息（如正则移除 `API_KEY`、`SECRET` 字符串），禁止传入 `.env` 或配置文件内容
- ✅ **版本控制友好**：生成的文档应保留 `@generated-by: github-actions/docs-auto-gen@v1` 注释，便于审计来源
- ✅ **增量更新**：优先复用已有文档页的 frontmatter（如 `sidebar_position`），仅更新 `content` 区域，避免 sidebar 错乱
- ⚠️ **LLM 可控性**：建议使用 `temperature=0.1` + `top_p=0.9` 保证稳定性；对核心接口添加 `@docgen: strict` JSDoc 标签强制启用生成
- ⚠️ **回滚机制**：在提交前运行 `docusaurus start --no-open` 预览生成效果（轻量模式），失败则 `exit 1` 中断流程
## 常见问题提示
- **Q：PR 合并后未触发工作流？**
A：检查 `pull_request.closed` 事件是否被分支保护规则拦截；确认 `github.event.pull_request.merged` 在 `types: [closed]` 下为 `true`（非 `synchronize`）
- **Q：生成的文档缺少参数说明？**
A：确认 JSDoc 中已为函数参数添加 `@param {string} name - 描述`；TypeDoc 默认不解析 `@param` 若未启用 `--readme none --includeDeclarations` 等选项
- **Q：Docusaurus 构建失败，提示找不到新文档？**
A：检查提交是否包含 `docs/api/xxx.mdx` 文件且路径在 `sidebars.js` 中注册；建议在 `generate-docs.mjs` 中自动追加 sidebar 条目（需解析并更新 `sidebars.js`）
- **Q：如何适配非 TypeScript 项目？**
A：替换 `typedoc` 为 `jsdoc` + `jsdoc-to-markdown`，或使用 `pyright` 提取 Python 类型注解；LLM Prompt 需同步调整语言描述（如将 “interface” 改为 “class” 或 “function signature”）