GitHub Projects 的 Issue/PR…

需要在 GitHub 仓库中把 Issue/PR 状态变更自动映射到 Project Status，或批量修正已有不一致时使用。

适用场景

解决思路

1. 先向用户确认执行模式：自动同步设置（生成 GitHub Actions workflow，首次推荐）或手动批量校正（当前不一致一次性修正，临时执行用）。
2. 模式 A-1：获取 owner：`gh repo view --json owner -q '.owner.login'`；查看项目列表：`gh project list --owner <owner> --format json`；向用户确认目标项目编号。
3. 模式 A-2：说明 Actions 访问 Projects API 时 `GITHUB_TOKEN` 不足，需 PAT 或 GitHub App 令牌。方法 1 PAT：在 GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens 创建；所需 scope：`project` 读写、`issues` 读写、`pull_requests` 读写；在仓库 Settings → Secrets and variables → Actions 注册为 `PROJECT_TOKEN`。方法 2 GitHub App（组织推荐）：创建 GitHub App 并给 Organization 授予 `Projects: Read and write` 权限；在 workflow 中用 `actions/create-github-app-token` 生成令牌。
4. 模式 A-3：使用 `Fandhe-AI/actions/project-sync` Composite Action，生成 `.github/workflows/project-sync.yml`。参照方式：`Fandhe-AI/actions/*`（本技能中为 `project-sync`）是组织内管理/评审的内制 action，因此用 `@latest` 标签（SHA pin 已废止，owner 决定）；第三方 action（如 `actions/create-github-app-token`）必须用已验证的提交 SHA 固定，不使用 `@main`/`@vN` 等可动参照。生成时不要动态获取最新 SHA，以避免上游被侵害/意外改动直接传播到引入方；使用已评审固定 SHA 常量。
5. 模式 A-3 固定 SHA 表：`actions/create-github-app-token` 固定 SHA `fee1f7d63c2ff003460e3d139729b119787bc349`，对应 v2.2.2。该 SHA 是引入时实际获取并精查 `action.yml` 与引用脚本全文后固定的。
6. 模式 A-3 SHA 更新（仅在需要更新时执行，不是每次生成都做；只针对第三方 action；`Fandhe-AI/actions/project-sync` 因 `@latest` 不适用）：获取候选最新 SHA：`gh api repos/actions/create-github-app-token/commits/main --jq '.sha'`；获取旧 SHA 到新 SHA 的差分补丁并精查：`gh api repos/actions/create-github-app-token/compare/<旧SHA>...<新SHA> --jq '.files[] | {filename, patch}'`；获取新 SHA 时点的 `action.yml` 并解码阅读：`gh api repos/actions/create-github-app-token/contents/action.yml?ref=<新SHA> --jq '.content' | base64 -d`；还要获取并阅读被引用的全部脚本。确认无意图外改动/可疑命令追加；可能的话用 `gh attestation verify` 等确认签名/发布 provenance。确认后才更新固定 SHA 表和后续 workflow 示例 `uses:` 行注释（对应版本）。
7. 模式 A-3 PAT 版 workflow（完整生成）： ```yaml name: Project Sync on: issues: types: [opened, closed, reopened] pull_request: types: [opened, closed, ready_for_review, review_requested] permissions: contents: read jobs: sync: runs-on: ubuntu-latest timeout-minutes: 10 steps: - name: Sync project status uses: Fandhe-AI/actions/project-sync@latest with: project-number: '<number>' project-owner: '<owner>' token: ${{ secrets.PROJECT_TOKEN }} ```
8. 模式 A-3 GitHub App 版 workflow（推荐）： ```yaml name: Project Sync on: issues: types: [opened, closed, reopened] pull_request: types: [opened, closed, ready_for_review, review_requested] permissions: contents: read jobs: sync: runs-on: ubuntu-latest timeout-minutes: 10 steps: - name: Generate token id: token uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2 with: app-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} owner: '<owner>' - name: Sync project status uses: Fandhe-AI/actions/project-sync@latest with: project-number: '<number>' project-owner: '<owner>' token: ${{ steps.token.outputs.token }} ```
9. 模式 A-3 自定义 Status 选项名：当 Status 选项名不是默认 Todo / In Progress / In Review / Done 时，在 inputs 中指定： ```yaml - name: Sync project status uses: Fandhe-AI/actions/project-sync@latest with: project-number: '<number>' project-owner: '<owner>' token: ${{ secrets.PROJECT_TOKEN }} status-todo: 'バックログ' status-in-progress: '作業中' status-in-review: 'レビュー中' status-done: '完了' ```
10. 模式 A-4：确认默认状态映射：Issue opened→Todo，Issue closed→Done，Issue reopened→Todo，PR opened→In Progress，PR ready_for_review→In Review，PR review_requested→In Review，PR closed (merged)→Done，PR closed (not merged)→Todo。按用户要求定制映射。
11. 模式 A-5：放置文件：`mkdir -p .github/workflows`；将 workflow 写入 `.github/workflows/project-sync.yml`；引导用户 commit & push。
12. 模式 B-1：获取项目 items：`gh project item-list <number> --owner <owner> --format json --limit 999`。
13. 模式 B-2：确认 Issue/PR 当前状态。对 Issue/PR 类型 item：`gh issue view <issue-url> --json state,labels,assignees`；`gh pr view <pr-url> --json state,isDraft,reviewRequests,merged`。
14. 模式 B-3：检测不一致：Issue closed 但 Status 非 Done→更新为 Done；Issue open 但 Status 为 Done→Todo；PR 已 merge 但 Status 非 Done→Done；PR 有 review request 但 Status 非 In Review→In Review。
15. 模式 B-4：检测仓库中未添加的 Issue/PR：`gh issue list --state open --json number,url,title --limit 999`；`gh pr list --state open --json number,url,title --limit 999`；与项目 item URL 比较找出未添加项。
16. 模式 B-5：向用户确认同步内容。按以下格式显示，并询问是否执行： ``` ## 同期内容 ### ステータス更新（N 件） - #42: ソーシャルログイン — Status: In Progress → Done（Issue closed） - #45: バグ修正 — Status: Done → Todo（Issue reopened） - #50: リファクタリング PR — Status: In Progress → In Review（レビュー依頼済み） ### 新規追加（M 件） - #55: 新機能リクエスト (Issue) - #56: ドキュメント更新 PR 実行しますか？ ```
17. 模式 B-6：执行同步： ```bash gh project field-list <number> --owner <owner> --format json gh project item-edit \ --id <item-id> \ --field-id <status-field-id> \ --project-id <project-id> \ --single-select-option-id <option-id> gh project item-add <number> \ --owner <owner> \ --url <issue-or-pr-url> \ --format json ```
18. 模式 B-7：报告同步结果表：状态更新 N 件，新建添加 M 件，无变化 K 件。
19. 注意事项：认证。Actions 访问 Projects API 时 `GITHUB_TOKEN` 不足，必须用 PAT 或 GitHub App 令牌。
20. 注意事项：PAT 有效期。fine-grained PAT 最长 1 年，建议定期轮换。
21. 注意事项：与内建 workflow 并用。若已通过 `project-init` 启用内建 workflow（closed→Done, merged→Done），Actions workflow 会双重触发，但更新为相同值，因此无实际危害。
22. 注意事项：PR 生命周期。内建 workflow 只支持 closed/merged；opened→In Progress、review_requested→In Review 只能由 Actions 自动化。
23. 注意事项：私有仓库。需在 org 的 Settings → Actions → General 允许从私有仓库共享 Action。
24. 注意事项：手动校正模式在同步前必须得到用户确认。
25. 注意事项：DraftIssue 类型 item 不是同步对象（不存在真实 Issue）。
26. 注意事项：需要网络（主要经 API；见 sandbox 环境执行）。
27. 注意事项：第三方 action 必须以提交 SHA 固定，`@main`/`@vN` 等可动参照不要生成，以防标签改绑/分支篡改的上游供应链风险；SHA 更新时先看差分。`Fandhe-AI/actions/*`（内制）用 `@latest`。
28. 注意事项：权限最小化。workflow 级别显式 `contents: read`；同步处理本身用 `PROJECT_TOKEN`/GitHub App 令牌权限运行，不需要给 `GITHUB_TOKEN` 额外权限。
29. 验证模式 A 完成后：`.github/workflows/project-sync.yml` 存在且 YAML 正确。检查 uses 引用方式：`Fandhe-AI/actions/*` 用 `@latest`，其他第三方用 40 位十六进制 SHA；还要积极验证第三方没有 `@main`/`@v2.2.2`/`@master`/任意分支名等可动参照。运行以下脚本，输出 `OK`（uses 行至少 1 条、Fandhe-AI 行全部 @latest、其他行全部 40 位 SHA）。若输出 `NG:` 则重新检查 workflow 生成内容： ```bash f=.github/workflows/project-sync.yml total=$(grep -c 'uses:' "$f") fandhe_total=$(grep -cE 'uses:\s*Fandhe-AI/actions/' "$f") fandhe_ok=$(grep -cE 'uses:\s*Fandhe-AI/actions/[^@[:space:]]+@latest([[:space:]]|#|$)' "$f") other_total=$((total - fandhe_total)) other_pinned=$(grep -E 'uses:' "$f" | grep -vE 'Fandhe-AI/actions/' | grep -cE 'uses:\s*[^@[:space:]]+@[0-9a-f]{40}([[:space:]]|#|$)' || true) if [ "$total" -eq 0 ]; then echo "NG: 検証対象の uses: 行が見つからない（workflow 生成に失敗している可能性）" >&2 exit 1 elif [ "$fandhe_total" -eq "$fandhe_ok" ] && [ "$other_total" -eq "$other_pinned" ]; then echo OK else echo "NG: 参照方式が不正な uses: 行がある（fandhe_total=${fandhe_total}, fandhe_ok=${fandhe_ok}, other_total=${other_total}, other_pinned=${other_pinned}）" >&2 exit 1 fi ```
30. 验证模式 A：`permissions` 明示：`grep -c 'permissions:' .github/workflows/project-sync.yml` 结果 ≥1。
31. 验证模式 A：`sync` job 设置 `timeout-minutes`：`grep -n 'timeout-minutes' .github/workflows/project-sync.yml` 至少 1 行（缺失是 CI workflow 规约违反/P1）。
32. 验证模式 A：commit/push 后在 GitHub Actions 执行历史确认首次触发即完成。
33. 验证模式 B 完成后：Step B-7 结果表中显示“变更なし: 0 件以上”。用 `gh project item-list <number> --owner <owner> --format json --limit 999` 确认最终状态。
34. sandbox 环境执行：该技能必须通过网络执行 GitHub 操作（同步 workflow 的 commit/push、`gh project item-edit` 等手动校正）。这些命令按命令单位禁用 sandbox 后执行。无法解除网络阻断的环境不能执行。

适用边界 · 注意事项

• 対象 GitHub Project 未链接到仓库，或 gh CLI 未安装/未以 project scope 认证，或无法配置 PAT/GitHub App 令牌时，不要执行该流程。
• 运行环境无法按命令解除 sandbox 网络隔离，无法访问 GitHub API 或推送 workflow 时不可执行。
• 若要同步 DraftIssue（无真实 Issue）则不应处理；该技能只处理真实 Issue/PR。