GitHub 技能

代理指令

这些是必须遵守的行为规则。在涉及代码、项目或任务的任何情况下都需遵循。

在技能安装时

当此技能首次加载时，向用户进行介绍：

• 说明所有项目工作将遵循专业的 GitHub 工作流程
• 提及：分支策略、工作日志、CI 检查、语义化版本控制、安全规则
• 提问：“您是否有现有项目，还是我们从新项目开始？”

在创建新项目时

如果这是用户第一次创建项目：

• 检查 gh auth status — 如果未认证，需先运行 gh auth login --web
• 提供创建新仓库的选项：名称、可见性（公开/私有）、许可证、.gitignore 文件
• 立即设置 main 和 develop 分支的保护规则
• 克隆至 ~/workspace/projects/<仓库名>/
• 创建初始的 develop 分支
• 在开始任何工作前，确认设置已完成

如果用户已有项目：

• 询问希望在哪个仓库上工作，或根据上下文自动判断
• 若尚未克隆，则将其克隆至 ~/workspace/projects/<仓库名>/
• 验证分支保护规则是否已启用 — 如未启用，提供设置建议
• 直接进入任务工作流

在继续已有工作时

当用户返回一个已克隆的项目时 — 在进行任何更改前，执行会话启动检查清单（参见下方代理工作流）。

在每个任务中

• 首先评估任务规模（参见代理工作流中的任务规模表）。
• 小型任务：创建分支 → 提交 → 快速记录 → 创建 PR → 用户确认 → 合并。
• 正常/重要任务：在分支前必须创建 Issue 并建立工作日志。
• 永远不要直接提交到 main 或 develop 分支。
• 永远不要跳过正常/重要任务的合并前检查清单。
• 永远不要在命令或输出中暴露令牌、密钥或凭据。
• 若操作不可逆（删除、合并、发布、强制推送）—— 必须先征得用户确认。

在使用此技能时

• 本文件（SKILL.md）始终在上下文中 — 使用它来获取工作流程、分支规则、工作日志规范。
• 参考文件仅在需要时加载 — 任务所需时才读取，而非预先加载。
• 工作日志不是可选的 — 它是每个任务从开始到结束的必要组成部分。
• 对 GitHub 操作不确定时 — 在执行前查阅相关参考文件。

安全性（始终）

• 所有操作通过 gh CLI 进行。在非 git 目录中操作时，始终使用 --repo owner/repo。
• 认证方式：gh auth login --web 或 GITHUB_TOKEN 环境变量。
• 密钥管理：gh secret set NAME --repo owner/repo（交互式设置，绝不使用 --body）。
• 永不打印或记录令牌。使用 gh auth status 来验证状态。

快速参考

只读查询。所有写入操作均需用户明确确认 — 参见参考文件中的 ⚠️ 标记。

分支模型

main       ← 生产环境，受保护
develop    ← 集成分支
feature/*  ← 从 develop 分支创建
fix/*      ← 从 develop 分支创建（关联 Issue：fix/123-desc）
hotfix/*   ← 从 main 分支创建（紧急修复）
release/*  ← 从 develop 分支创建（发布准备）
chore/*    ← 从 develop 分支创建（依赖、工具链、CI — 无产品变更）

提交规范：feat: 描述 (#42) / fix: 描述 (#42)

PR 合并方式：功能类使用 --squash，发布类使用 --merge。

语义化版本：MAJOR.MINOR.PATCH — 破坏性变更 / 新功能 / 修复。

代理工作流

工作区布局

始终将项目克隆至 ~/workspace/projects/<仓库名>/。不在 /tmp 中工作 — 该目录在会话间不会持久保留。

mkdir -p ~/workspace/projects
gh repo clone owner/repo ~/workspace/projects/repo-name
cd ~/workspace/projects/repo-name

会话启动（每次都会执行）

gh auth status                   # 1. 验证认证状态
git checkout develop && git pull # 2. 同步最新代码
git branch                       # 3. 确认当前所在分支正确
# 4. 打开 work/<issue>-<desc>.md 并阅读 Status.next 内容

任务规模

在开始任何任务前，评估其规模 — 这决定了工作流程的严格程度。

如有疑问 — 按重要任务处理。

明确需求（仅限重要任务）

在创建 Issue 或分支前，持续提问直至需求清晰：

• 具体需要修改什么？原因是什么？
• 影响哪些组件、API 或依赖？
• 是否存在约束条件 — 性能、向后兼容性、截止时间？
• “完成”状态应如何定义？

在获得明确答复前不得开始实现。 小型/正常任务可跳过此步骤，根据上下文推断即可。

任务流程

小型任务：

1. 从 develop 分支创建新分支 → git checkout -b fix/short-desc
2. 原子化提交 → "fix: 描述"
3. 追加至 quick-log.md → 添加日期和一行变更说明
4. ⚠️ 征得用户确认 — 通过 PR 合并 → gh pr merge --squash --delete-branch

常规/重要任务：

1. 创建或查找 Issue                → gh issue create / gh issue list
2. 创建工作日志文件                    → work/<issue>-<desc>.md（参见下方“工作日志”部分）
3. 从 develop 分支创建新分支             → git checkout -b feature/42-short-desc
4. 进行小而原子化的提交               → 每次提交只包含一个变更
5. 提交信息中引用 Issue              → "feat: 描述 (#42)"
6. 在首次提交后打开草稿 PR           → gh pr create --draft（尽早表明正在进行中的工作）
7. 监控 CI 状态                      → gh run watch
   若 CI 失败：
   - 下载失败的日志                  → gh run view <id> --log-failed
   - 在工作日志中记录原因              → Status.blocked 或 Notes
   - 修复并提交（"fix: 修复 CI 失败"），推送
   - 等待通过绿色状态后再继续
8. 前提检查清单（参见下方）
9. 标记为就绪并请求审查             → gh pr ready / gh pr review
10. 审核通过后合并                 → gh pr merge --squash --delete-branch
11. 关闭 Issue 并整理工作日志       → gh issue close 42

PR 前检查清单

在标记 PR 为就绪前，请确认：

• 本地运行测试通过
• git diff origin/develop — 确保无调试代码、密钥或临时文件
• CI 绿色（gh pr checks <n>）
• PR 描述符合下方模板
• 自我审查： 再次阅读自己的代码差异 — 检查硬编码值、残留的调试语句、缺失的错误处理。完成后再请求人工审查。

PR 描述模板：

## 什么
对变更的简要描述。

## 为什么
关闭 #<issue>

## 变更
- 变更 1
- 变更 2

## 测试
- [ ] 本地测试通过
- [ ] CI 绿色
- [ ] 手动检查已完成（如涉及 UI）

会话间中断

若任务未在会话结束时完成：

git stash push -m "wip: 当前进行中的内容描述"

更新工作日志中的 Status 和 next，然后停止。下次会话开始时：先阅读 next，再执行 git stash pop。

合并冲突处理

当合并或变基过程中出现冲突时：

git status                         # 查看冲突文件
# 打开每个文件 — 手动解决，保留正确代码
git add <已解决的文件>
git rebase --continue              # 或 git merge --continue

# 若冲突过于复杂 — 中止并询问用户
git rebase --abort
git merge --abort

规则：

• 不要盲目接受 --ours 或 --theirs，必须理解差异
• 若不确定哪个更改正确 — 立即停止并询问用户
• 解决后，在推送前重新运行测试

范围蔓延

在实现过程中发现原 Issue 之外的额外需求：

• 不得扩展当前任务范围
• 按原始范围完成当前任务
• 为新增内容创建新的 Issue
• 在当前工作日志的 Notes 部分添加说明

紧急修复流程（Hotfix）

紧急修复需从 main 分支创建。合并到 main 后，必须将相同修复合并回 develop — 否则该问题将在下个版本中重现。

1. 从 main 分支创建修复分支         → git checkout main && git pull
                                             git checkout -b hotfix/short-desc
2. 修复并提交                       → "fix: 描述"
3. 创建 PR 到 main                   → gh pr create --base main --head hotfix/...
4. 审核通过后合并到 main            → gh pr merge --squash --delete-branch
5. ⚠️ 必须与用户确认 — 也合并到 develop → git checkout develop && git pull
                                                    git merge main
                                                    git push origin develop
6. 发布版本标签                     → gh release create vX.Y.Z --target main
7. 记录在工作日志中                 → 说明哪里出错、如何修复、原因

绝不能跳过第 5 步 — 未同步的 develop 将导致问题在下次发布时再次出现。

工作日志

每个任务都应有对应的日志条目。格式根据任务规模决定。

快速日志（仅限小型任务）

每项目共享一个文件：work/quick-log.md

## 2026-05-08
- 修复列表卡片间距（components/Card.css）
- 更新解析器超时设置（config/parser.yml）
- 修正格鲁吉亚语翻译（locales/ka.json）

每项小型任务追加一行。无需结构、状态或决策记录。创建一次，永不压缩。

完整日志（常规/重要任务）

每个重要任务应拥有独立的日志文件。它是代理的记忆库 — 用于定位、决策和状态追踪。

设置

mkdir -p work
# 每个项目只需执行一次
echo "work/" >> .gitignore

文件路径：work/<issue-number>-<short-desc>.md

结构

# 任务： <标题> (#<issue>)
目标： <一句话描述 — “完成”的标准>

## 状态
当前： <代理正在执行的内容>
下一步： <计划中的下一步操作>
阻塞： <阻塞原因或 —>

## 已完成
- [x] 已创建分支 feature/42-user-auth
- [x] 已添加 JWT 中间件（src/auth.js）
- [ ] PR 审查待处理

## 决策
- 使用 HS256 — 本项目无密钥基础设施
- 跳过刷新令牌 — 依据 Issue 评论不在范围内

## 注意事项
- src/auth.js:84 — token 刚好过期的边界情况，需关注
- AUTH_SECRET 环境变量必须在部署前加入 secrets

写入时机

压缩整理

当文件超过约 80 行，或任务完成后，进行压缩：

• 已完成 — 保留未勾选项 + 最近 3 项已完成，其余删除
• 决策 — 保留全部，永不删除
• 注意事项 — 已解决的删除，保留未解决的
• 状态 — 重写为全新内容

规则

• 每次会话结束前务必更新 next —— 它是重新进入的入口点
• 永远不要删除 Decisions —— 它们可防止已解决的问题被重复争论
• 永远不要在工作日志中存储密钥、令牌或凭据
• 主动压缩内容 —— 日志过大会削弱其使用价值

何时查阅参考文件

仅加载当前任务所需的文件：