update-llmdoc

update-llmdoc

根据目标分支最近的代码变更，自动更新 llmdoc 文档。

概览

• 作用: 保持 llmdoc/ 项目文档与代码实现同步，减少人工维护成本
• 触发方式: GitHub Actions schedule（每天北京时间 5:00）或 workflow_dispatch 手动触发
• 时间窗口: 默认检查过去 24 小时内的提交，手动触发时可自定义 since_period 参数
• 输出: 结构化 JSON（包含 description、total_files_updated、pr_url），同时通过飞书 Webhook 通知结果，附带 PR 链接

仓库模式自动检测

执行前先检测当前仓库类型：

# 检查是否有 .gitmodules 文件（聚合仓库的标志）
if [ -f .gitmodules ]; then
  # 聚合仓库模式：遍历子模块
else
  # 单仓库模式：直接在当前仓库操作
fi

聚合仓库模式

适用于包含 git submodule 的仓库（如 tipsy-collect-repo）。遍历所有子模块，逐个检查变更并更新文档。

单仓库模式

适用于独立仓库（如 tipsy-backend）。直接在仓库根目录检查变更并更新 llmdoc/ 文档。

执行流程

1. 收集变更

聚合仓库模式 — 对每个子模块执行：

git submodule foreach 'echo $name'  # 获取子模块列表
cd {submodule}
git fetch origin {target_branch}
git log --since="{since_period}" origin/{target_branch} --oneline

单仓库模式 — 直接在根目录执行：

git fetch origin {target_branch}
git log --since="{since_period}" origin/{target_branch} --oneline

{target_branch} 从 prompt 中获取，默认为 dev。

2. 分析变更

对有新提交的仓库/子模块：

1. 读取提交记录: git log --since="{since_period}" origin/{target_branch} --pretty=format:"- %h %s (%an)"
2. 读取合并 PR 信息: git log --since="{since_period}" origin/{target_branch} --merges --pretty=format:"%s"
3. 读取变更统计: git diff {first_commit}^..{last_commit} --stat
4. 读取代码 diff: git diff {first_commit}^..{last_commit} (关注核心逻辑变更)
5. 读取当前 llmdoc: 阅读 llmdoc/index.md 和所有相关文档

3. 判断是否需要更新

以下变更需要更新文档：

• 新增功能或模块
• 修改现有功能的行为或接口
• API 变更（新增/修改/删除端点）
• 架构调整
• 重要的配置变更

以下变更不需要更新文档：

• 纯 bug 修复（不改变接口或行为）
• 代码重构（不改变外部行为）
• 依赖版本升级
• 测试代码变更
• CI/CD 配置变更
• 注释或日志修改

4. 更新文档

• 只更新确实受影响的文档，不做不必要的修改
• 保持与现有文档一致的风格和结构（中文）
• 新功能 → 在对应 architecture/ 或 guides/ 文档中添加说明
• 行为变更 → 更新对应文档的描述
• 重大变更 → 更新 index.md 导航

5. 创建 PR

文档更新完成后，不直接推送到 {target_branch}，而是创建新分支并提 PR：

分支命名规则：

docs/llmdoc-update-{YYYYMMDD}

例如：docs/llmdoc-update-20240315

聚合仓库模式 — 对每个有文档更新的子模块：

cd {submodule}
DATE=$(date +%Y%m%d)
BRANCH="docs/llmdoc-update-${DATE}"

# 基于 target_branch 创建新分支
git checkout -b "${BRANCH}" "origin/{target_branch}"

git add llmdoc/
git commit -m "docs: 自动更新 llmdoc 文档

基于过去 {since_period} {target_branch} 分支的代码变更自动生成
Auto-updated by GitHub Actions"
git push origin "${BRANCH}"

# 创建 PR（目标分支为 target_branch）
gh pr create \
  --title "docs: 自动更新 llmdoc 文档 ($(date +%Y-%m-%d))" \
  --body "## llmdoc 文档自动更新

由 GitHub Actions 定时任务自动生成，基于过去 {since_period} 合并到 \`{target_branch}\` 分支的代码变更。

**请检查文档内容是否准确后合并。**" \
  --base "{target_branch}" \
  --head "${BRANCH}"

单仓库模式 — 直接在根目录：

DATE=$(date +%Y%m%d)
BRANCH="docs/llmdoc-update-${DATE}"

git checkout -b "${BRANCH}" "origin/{target_branch}"

git add llmdoc/
git commit -m "docs: 自动更新 llmdoc 文档

基于过去 {since_period} {target_branch} 分支的代码变更自动生成
Auto-updated by GitHub Actions"
git push origin "${BRANCH}"

# 创建 PR（目标分支为 target_branch）
PR_URL=$(gh pr create \
  --title "docs: 自动更新 llmdoc 文档 ($(date +%Y-%m-%d))" \
  --body "## llmdoc 文档自动更新

由 GitHub Actions 定时任务自动生成，基于过去 {since_period} 合并到 \`{target_branch}\` 分支的代码变更。

**请检查文档内容是否准确后合并。**" \
  --base "{target_branch}" \
  --head "${BRANCH}")
echo "PR created: ${PR_URL}"

如果当天已存在同名分支（重复触发时），先尝试复用：

git checkout "${BRANCH}" 2>/dev/null || git checkout -b "${BRANCH}" "origin/{target_branch}"
# 如果 PR 已存在则跳过创建，直接追加提交推送
git push origin "${BRANCH}"

输出的结构化 JSON 中，pr_url 字段填入 gh pr create 返回的 PR 链接。若无文档更新，pr_url 为空字符串。

6. 输出报告

用 echo 输出处理结果（不需要发 GitHub 评论）。结构化输出中必须包含 pr_url 字段，飞书通知将自动附带 PR 跳转链接。

特殊规则

• 聚合仓库: 每个子模块在自己的 git 仓库内操作，不修改父仓库
• 无 llmdoc 跳过: 如果仓库/子模块没有 llmdoc/ 目录，跳过
• 无变更跳过: 如果无提交或变更不需要更新文档，跳过
• diff 过大截断: 如果 diff 超过 500 行，聚焦于 --stat 和提交信息来理解变更
• 保守更新: 宁可少更新，也不要错误更新。不确定时不更新
• 必须创建 PR: 更新文档后必须创建新分支并通过 gh pr create 提 PR，不直接推送到 {target_branch}
• PR URL 必须输出: 结构化 JSON 的 pr_url 字段必须填入实际 PR 链接，以便飞书通知附带跳转