| name | update-llmdoc |
| description | 定时自动维护 llmdoc 项目文档的 Skill。支持两种模式：聚合仓库模式（遍历子模块）和 单仓库模式（直接在当前仓库操作）。每天北京时间 5:00（UTC 21:00）由 GitHub Actions schedule 触发，也支持 workflow_dispatch 手动触发。收集指定时间范围内（默认过去 24 小时） 合并到目标分支的提交记录和 PR 内容，分析代码变更是否涉及功能新增、接口变更或架构调整， 如果需要则自动更新 llmdoc/ 下的对应文档并推送到目标分支。不改变外部行为的变更 （bug 修复、重构、依赖升级等）会被跳过。更新完成后输出结构化 JSON 结果并通过飞书通知。
|
update-llmdoc
根据目标分支最近的代码变更，自动更新 llmdoc 文档。
概览
- 作用: 保持
llmdoc/ 项目文档与代码实现同步，减少人工维护成本
- 触发方式: GitHub Actions
schedule（每天北京时间 5:00）或 workflow_dispatch 手动触发
- 时间窗口: 默认检查过去 24 小时内的提交，手动触发时可自定义
since_period 参数
- 输出: 结构化 JSON（包含
description、total_files_updated、pr_url），同时通过飞书 Webhook 通知结果，附带 PR 链接
仓库模式自动检测
执行前先检测当前仓库类型：
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. 分析变更
对有新提交的仓库/子模块：
- 读取提交记录:
git log --since="{since_period}" origin/{target_branch} --pretty=format:"- %h %s (%an)"
- 读取合并 PR 信息:
git log --since="{since_period}" origin/{target_branch} --merges --pretty=format:"%s"
- 读取变更统计:
git diff {first_commit}^..{last_commit} --stat
- 读取代码 diff:
git diff {first_commit}^..{last_commit} (关注核心逻辑变更)
- 读取当前 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}"
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}"
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_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}"
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 链接，以便飞书通知附带跳转
