@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/github/github-pr-workflow/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: github-pr-workflow
+description: "GitHub PR 生命周期：分支、提交、开启、CI、合并。"
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Pull-Requests, CI/CD, Git, Automation, Merge]
+    related_skills: [github-auth, github-code-review]
+---
+
+# GitHub Pull Request 工作流
+
+管理 PR 生命周期的完整指南。每一节首先展示使用 `gh` 的方法，然后针对未安装 `gh` 的机器提供 `git` + `curl` 的后备方案。
+
+## 前置条件
+
+- 已通过 GitHub 身份验证（参见 `github-auth` 技能）
+- 位于带有 GitHub remote 的 git repository 内部
+
+### 快速身份验证检测
+
+```bash
+# 确定在整个工作流中使用哪种方法
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  # 确保我们有用于 API 调用的 token
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+echo "Using: $AUTH"
+```
+
+### 从 Git Remote 提取 Owner/Repo
+
+许多 `curl` 命令需要 `owner/repo`。从 git remote 中提取它：
+
+```bash
+# 适用于 HTTPS 和 SSH remote URL
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+echo "Owner: $OWNER, Repo: $REPO"
+```
+
+---
+
+## 1. 创建分支
+
+这部分纯粹是 `git` 操作——无论使用哪种方式都是一样的：
+
+```bash
+# 确保你是最新状态
+git fetch origin
+git checkout main && git pull origin main
+
+# 创建并切换到新分支
+git checkout -b feat/add-user-authentication
+```
+
+分支命名规范：
+- `feat/description` — 新功能
+- `fix/description` — bug 修复
+- `refactor/description` — 代码重构
+- `docs/description` — 文档
+- `ci/description` — CI/CD 变更
+
+## 2. 进行提交
+
+使用 agent 的文件工具（`write_file`、`patch`）进行修改，然后提交：
+
+```bash
+# 暂存特定文件
+git add src/auth.py src/models/user.py tests/test_auth.py
+
+# 使用 Conventional Commits 消息格式提交
+git commit -m "feat: add JWT-based user authentication
+
+- Add login/register endpoints
+- Add User model with password hashing
+- Add auth middleware for protected routes
+- Add unit tests for auth flow"
+```
+
+提交消息格式（Conventional Commits）：
+```
+type(scope): short description
+
+Longer explanation if needed. Wrap at 72 characters.
+```
+
+类型：`feat`、`fix`、`refactor`、`docs`、`test`、`ci`、`chore`、`perf`
+
+## 3. 推送并创建 PR
+
+### 推送分支（两种方式相同）
+
+```bash
+git push -u origin HEAD
+```
+
+### 创建 PR
+
+**使用 gh：**
+
+```bash
+gh pr create \
+  --title "feat: add JWT-based user authentication" \
+  --body "## Summary
+- Adds login and register API endpoints
+- JWT token generation and validation
+
+## Test Plan
+- [ ] Unit tests pass
+
+Closes #42"
+```
+
+选项：`--draft`、`--reviewer user1,user2`、`--label "enhancement"`、`--base develop`
+
+**使用 git + curl：**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.v3+json" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls \
+  -d "{
+    \"title\": \"feat: add JWT-based user authentication\",
+    \"body\": \"## Summary\nAdds login and register API endpoints.\n\nCloses #42\",
+    \"head\": \"$BRANCH\",
+    \"base\": \"main\"
+  }"
+```
+
+响应的 JSON 包含 PR `number` ——将其保存以供后续命令使用。
+
+要作为 draft 创建，请在 JSON body 中添加 `"draft": true`。
+
+## 4. 监控 CI 状态
+
+### 检查 CI 状态
+
+**使用 gh：**
+
+```bash
+# 一次性检查
+gh pr checks
+
+# 持续监视直到所有检查完成（每 10 秒轮询一次）
+gh pr checks --watch
+```
+
+**使用 git + curl：**
+
+```bash
+# 获取当前分支上的最新 commit SHA
+SHA=$(git rev-parse HEAD)
+
+# 查询综合状态
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(f\"Overall: {data['state']}\")
+for s in data.get('statuses', []):
+    print(f\"  {s['context']}: {s['state']} - {s.get('description', '')}\")"
+
+# 同时检查 GitHub Actions check runs（单独的 endpoint）
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/check-runs \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for cr in data.get('check_runs', []):
+    print(f\"  {cr['name']}: {cr['status']} / {cr['conclusion'] or 'pending'}\")"
+```
+
+### 轮询直到完成（git + curl）
+
+```bash
+# 简单的轮询循环 —— 每 30 秒检查一次，最多 10 分钟
+SHA=$(git rev-parse HEAD)
+for i in $(seq 1 20); do
+  STATUS=$(curl -s \
+    -H "Authorization: token $GITHUB_TOKEN" \
+    https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+    | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])")
+  echo "Check $i: $STATUS"
+  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failure" ] || [ "$STATUS" = "error" ]; then
+    break
+  fi
+  sleep 30
+done
+```
+
+## 5. 自动修复 CI 失败
+
+当 CI 失败时，进行诊断和修复。此循环适用于任意身份验证方法。
+
+### 步骤 1：获取失败详情
+
+**使用 gh：**
+
+```bash
+# 列出此分支上的近期 workflow runs
+gh run list --branch $(git branch --show-current) --limit 5
+
+# 查看失败的日志
+gh run view <RUN_ID> --log-failed
+```
+
+**使用 git + curl：**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+# 列出此分支上的 workflow runs
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?branch=$BRANCH&per_page=5" \
+  | python3 -c "
+import sys, json
+runs = json.load(sys.stdin)['workflow_runs']
+for r in runs:
+    print(f\"Run {r['id']}: {r['name']} - {r['conclusion'] or r['status']}\")"
+
+# 获取失败的 job 日志（下载 zip，解压，读取）
+RUN_ID=<run_id>
+curl -s -L \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
+  -o /tmp/ci-logs.zip
+cd /tmp && unzip -o ci-logs.zip -d ci-logs && cat ci-logs/*.txt
+```
+
+### 步骤 2：修复并推送
+
+识别问题后，使用文件工具（`patch`、`write_file`）进行修复：
+
+```bash
+git add <fixed_files>
+git commit -m "fix: resolve CI failure in <check_name>"
+git push
+```
+
+### 步骤 3：验证
+
+使用上方第 4 节中的命令重新检查 CI 状态。
+
+### 自动修复循环模式
+
+当被要求自动修复 CI 时，遵循此循环：
+
+1. 检查 CI 状态 → 识别失败
+2. 读取失败日志 → 理解错误
+3. 使用 `read_file` + `patch`/`write_file` → 修复代码
+4. `git add . && git commit -m "fix: ..." && git push`
+5. 等待 CI → 重新检查状态
+6. 如果仍然失败则重复（最多尝试 3 次，然后向用户求助）
+
+## 6. 合并
+
+**使用 gh：**
+
+```bash
+# Squash merge + 删除分支（对于 feature 分支最干净）
+gh pr merge --squash --delete-branch
+
+# 启用自动合并（在所有检查通过后合并）
+gh pr merge --auto --squash --delete-branch
+```
+
+**使用 git + curl：**
+
+```bash
+PR_NUMBER=<number>
+
+# 通过 API 合并 PR (squash)
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge \
+  -d "{
+    \"merge_method\": \"squash\",
+    \"commit_title\": \"feat: add user authentication (#$PR_NUMBER)\"
+  }"
+
+# 合并后删除 remote 分支
+BRANCH=$(git branch --show-current)
+git push origin --delete $BRANCH
+
+# 在本地切换回 main
+git checkout main && git pull origin main
+git branch -d $BRANCH
+```
+
+合并方法：`"merge"`（merge commit）、`"squash"`、`"rebase"`
+
+### 启用自动合并
+
+```bash
+# 自动合并需要在仓库设置中启用它。
+# 这里使用 GraphQL API，因为 REST 不支持自动合并。
+PR_NODE_ID=$(curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['node_id'])")
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/graphql \
+  -d "{\"query\": \"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \\\"$PR_NODE_ID\\\", mergeMethod: SQUASH}) { clientMutationId } }\"}"
+```
+
+## 7. 完整工作流示例
+
+```bash
+# 1. 从干净的 main 开始
+git checkout main && git pull origin main
+
+# 2. 分支
+git checkout -b fix/login-redirect-bug
+
+# 3.（Agent 使用文件工具进行代码更改）
+
+# 4. 提交
+git add src/auth/login.py tests/test_login.py
+git commit -m "fix: correct redirect URL after login
+
+Preserves the ?next= parameter instead of always redirecting to /dashboard."
+
+# 5. 推送
+git push -u origin HEAD
+
+# 6. 创建 PR（根据可用内容选择 gh 或 curl）
+# ...（参见第 3 节）
+
+# 7. 监控 CI（参见第 4 节）
+
+# 8. 变绿后合并（参见第 6 节）
+```
+
+## 有用的 PR 命令参考
+
+| 操作 | gh | git + curl |
+|--------|-----|-----------|
+| 列出我的 PR | `gh pr list --author @me` | `curl -s -H "Authorization: token $GITHUB_TOKEN" "https://api.github.com/repos/$OWNER/$REPO/pulls?state=open"` |
+| 查看 PR diff | `gh pr diff` | `git diff main...HEAD`（本地）或 `curl -H "Accept: application/vnd.github.diff" ...` |
+| 添加评论 | `gh pr comment N --body "..."` | `curl -X POST .../issues/N/comments -d '{"body":"..."}'` |
+| 请求审查 | `gh pr edit N --add-reviewer user` | `curl -X POST .../pulls/N/requested_reviewers -d '{"reviewers":["user"]}'` |
+| 关闭 PR | `gh pr close N` | `curl -X PATCH .../pulls/N -d '{"state":"closed"}'` |
+| 检出他人的 PR | `gh pr checkout N` | `git fetch origin pull/N/head:pr-N && git checkout pr-N` |

package/extensions/skills/builtin/github/github-pr-workflow/references/ci-troubleshooting.md

@@ -0,0 +1,183 @@
+# CI 故障排查快速参考
+
+常见的 CI 失败模式以及如何通过日志进行诊断。
+
+## 阅读 CI 日志
+
+```bash
+# With gh
+gh run view <RUN_ID> --log-failed
+
+# With curl — download and extract
+curl -sL -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/actions/runs/<RUN_ID>/logs \
+  -o /tmp/ci-logs.zip && unzip -o /tmp/ci-logs.zip -d /tmp/ci-logs
+```
+
+## 常见失败模式
+
+### 测试失败
+
+**日志中的特征：**
+```
+FAILED tests/test_foo.py::test_bar - AssertionError
+E       assert 42 == 43
+ERROR tests/test_foo.py - ModuleNotFoundError
+```
+
+**诊断：**
+1. 从 traceback 中找到测试文件和行号
+2. 使用 `read_file` 读取失败的测试
+3. 检查是代码中的逻辑错误还是过时的测试断言
+4. 查找 `ModuleNotFoundError` — 通常是 CI 中缺少依赖项
+
+**常见修复方法：**
+- 更新断言以匹配新的预期行为
+- 将缺少的依赖项添加到 requirements.txt / pyproject.toml
+- 修复不稳定的测试（添加重试、模拟外部服务、修复竞态条件）
+
+---
+
+### Lint / 格式化失败
+
+**日志中的特征：**
+```
+src/auth.py:45:1: E302 expected 2 blank lines, got 1
+src/models.py:12:80: E501 line too long (95 > 88 characters)
+error: would reformat src/utils.py
+```
+
+**诊断：**
+1. 阅读提到的特定文件:行号
+2. 检查是哪个 linter 报错 (flake8, ruff, black, isort, mypy)
+
+**常见修复方法：**
+- 在本地运行格式化工具：`black .`, `isort .`, `ruff check --fix .`
+- 通过编辑文件修复特定的样式违规
+- 如果使用 `patch`，确保匹配现有的缩进风格
+
+---
+
+### 类型检查失败 (mypy / pyright)
+
+**日志中的特征：**
+```
+src/api.py:23: error: Argument 1 to "process" has incompatible type "str"; expected "int"
+src/models.py:45: error: Missing return statement
+```
+
+**诊断：**
+1. 阅读提到行号处的文件
+2. 检查函数签名以及传递的内容
+
+**常见修复方法：**
+- 添加类型转换或 conversion
+- 修复函数签名
+- 作为最后的手段，添加 `# type: ignore` 注释（附带说明）
+
+---
+
+### 构建 / 编译失败
+
+**日志中的特征：**
+```
+ModuleNotFoundError: No module named 'some_package'
+ERROR: Could not find a version that satisfies the requirement foo==1.2.3
+npm ERR! Could not resolve dependency
+```
+
+**诊断：**
+1. 检查 requirements.txt / package.json 中是否缺少或不兼容的依赖项
+2. 比较本地与 CI 的 Python/Node 版本
+
+**常见修复方法：**
+- 将缺少的依赖项添加到 requirements 文件
+- 固定兼容版本
+- 更新 lockfile (`pip freeze`, `npm install`)
+
+---
+
+### 权限 / 认证失败
+
+**日志中的特征：**
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+Error: Resource not accessible by integration
+403 Forbidden
+```
+
+**诊断：**
+1. 检查工作流是否需要特殊权限（token scopes）
+2. 检查是否配置了 secrets（缺少 `GITHUB_TOKEN` 或自定义 secrets）
+
+**常见修复方法：**
+- 在工作流 YAML 中添加 `permissions:` 块
+- 验证 secrets 是否存在：`gh secret list` 或检查仓库设置
+- 对于 fork PR：某些 secrets 被设计为默认不可用
+
+---
+
+### 超时失败
+
+**日志中的特征：**
+```
+Error: The operation was canceled.
+The job running on runner ... has exceeded the maximum execution time
+```
+
+**诊断：**
+1. 检查是哪个步骤超时
+2. 查找无限循环、挂起的进程或缓慢的网络调用
+
+**常见修复方法：**
+- 为特定步骤添加超时设置：`timeout-minutes: 10`
+- 修复底层的性能问题
+- 拆分为并行作业
+
+---
+
+### Docker / 容器失败
+
+**日志中的特征：**
+```
+docker: Error response from daemon
+failed to solve: ... not found
+COPY failed: file not found in build context
+```
+
+**诊断：**
+1. 检查 Dockerfile 中失败的步骤
+2. 验证引用的文件是否存在于仓库中
+
+**常见修复方法：**
+- 修复 COPY/ADD 命令中的路径
+- 更新基础 image tag
+- 将缺失的文件添加到 `.dockerignore` 排除项或从中移除
+
+---
+
+## 自动修复决策树
+
+```
+CI Failed
+├── Test failure
+│   ├── Assertion mismatch → update test or fix logic
+│   └── Import/module error → add dependency
+├── Lint failure → run formatter, fix style
+├── Type error → fix types
+├── Build failure
+│   ├── Missing dep → add to requirements
+│   └── Version conflict → update pins
+├── Permission error → update workflow permissions (needs user)
+└── Timeout → investigate perf (may need user input)
+```
+
+## 修复后重新运行
+
+```bash
+git add <fixed_files> && git commit -m "fix: resolve CI failure" && git push
+
+# Then monitor
+gh pr checks --watch 2>/dev/null || \
+  echo "Poll with: curl -s -H 'Authorization: token ...' https://api.github.com/repos/.../commits/$(git rev-parse HEAD)/status"
+```

package/extensions/skills/builtin/github/github-pr-workflow/references/conventional-commits.md

@@ -0,0 +1,71 @@
+# Conventional Commits 快速参考
+
+格式：`type(scope): description`
+
+## Types
+
+| Type | 何时使用 | 示例 |
+| ------ | ------------ | --------- |
+| `feat` | 新功能或新能力 | `feat(auth): add OAuth2 login flow` |
+| `fix` | Bug 修复 | `fix(api): handle null response from /users endpoint` |
+| `refactor` | 代码重构，不改变原有行为 | `refactor(db): extract query builder into separate module` |
+| `docs` | 仅修改文档 | `docs: update API usage examples in README` |
+| `test` | 添加或更新测试 | `test(auth): add integration tests for token refresh` |
+| `ci` | CI/CD 配置 | `ci: add Python 3.12 to test matrix` |
+| `chore` | 维护、依赖项、工具相关 | `chore: upgrade pytest to 8.x` |
+| `perf` | 性能优化 | `perf(search): add index on users.email column` |
+| `style` | 格式化、空格、分号等代码样式 | `style: run black formatter on src/` |
+| `build` | 构建系统或外部依赖 | `build: switch from setuptools to hatch` |
+| `revert` | 撤销之前的提交 | `revert: revert "feat(auth): add OAuth2 login flow"` |
+
+## Scope（可选）
+
+代码库模块的简短标识符：`auth`、`api`、`db`、`ui`、`cli` 等。
+
+## 破坏性变更 (Breaking Changes)
+
+在 type 后添加 `!`，或者在 footer 中添加 `BREAKING CHANGE:`：
+
+```
+feat(api)!: change authentication to use bearer tokens
+
+BREAKING CHANGE: API endpoints now require Bearer token instead of API key header.
+Migration guide: https://docs.example.com/migrate-auth
+```
+
+## 多行正文 (Multi-line Body)
+
+在 72 个字符处换行。如果有多个变更，请使用列表：
+
+```
+feat(auth): add JWT-based user authentication
+
+- Add login/register endpoints with input validation
+- Add User model with argon2 password hashing
+- Add auth middleware for protected routes
+- Add token refresh endpoint with rotation
+
+Closes #42
+```
+
+## 关联 Issue
+
+写在 commit 正文或 footer 中：
+
+```
+Closes #42          ← 合并后自动关闭 issue
+Fixes #42           ← 效果同上
+Refs #42            ← 仅引用，不关闭
+Co-authored-by: Name <email>
+```
+
+## 快速决策指南
+
+- 添加了新内容？ → `feat`
+- 修复了故障？ → `fix`
+- 改变了代码的组织方式，但没有改变其功能？ → `refactor`
+- 仅修改了测试？ → `test`
+- 仅修改了文档？ → `docs`
+- 更新了 CI/CD 流水线？ → `ci`
+- 更新了依赖项或工具？ → `chore`
+- 提升了运行速度？ → `perf`

package/extensions/skills/builtin/github/github-pr-workflow/templates/pr-body-bugfix.md

@@ -0,0 +1,35 @@
+## Bug 描述
+
+<!-- 发生了什么？ -->
+
+Fixes #
+
+## 根本原因
+
+<!-- 是什么导致了该 bug？ -->
+
+## 修复
+
+<!-- 这个 PR 做了哪些修改来修复它？ -->
+
+-
+
+## 如何验证
+
+<!-- 审查者可以按照以下步骤确认修复 -->
+
+1.
+2.
+3.
+
+## 测试计划
+
+- [ ] 针对此 bug 添加了回归测试
+- [ ] 现有测试仍然通过
+- [ ] 手动验证了修复效果
+
+## 风险评估
+
+<!-- 这个修复会破坏其他内容吗？影响范围有多大？ -->
+
+低 / 中 / 高 — <!-- 说明 -->

package/extensions/skills/builtin/github/github-pr-workflow/templates/pr-body-feature.md

@@ -0,0 +1,33 @@
+## 概述
+
+<!-- 1-3 个要点，描述此 PR 做了什么 -->
+
+-
+
+## 动机
+
+<!-- 为什么需要此更改？如有相关 issue 请附上链接 -->
+
+Closes #
+
+## 变更
+
+<!-- 所做变更的详细列表 -->
+
+-
+
+## 测试计划
+
+<!-- 这是如何测试的？验证步骤清单 -->
+
+- [ ] 单元测试通过 (`pytest`)
+- [ ] 新功能的手动测试
+- [ ] 现有行为无回归
+
+## 截图 / 示例
+
+<!-- 如果有 UI 变更或新输出，请展示前/后对比 -->
+
+## 给审查者的说明
+
+<!-- 审查者需要特别注意的任何事项 -->