用途
project-sync-issues 是一个用于配置 GitHub Issue/PR 状态与 GitHub Project Status 字段自动同步的技能。它通过生成 GitHub Actions 工作流文件，把 Issue/PR 的状态变化自动写入项目 Status 字段，并提供手动批量补正模式以修正现有不一致。
主要能力
技能提供两种执行模式。模式 A 为自动同步设置，生成 .github/workflows/project-sync.yml，使用 Fandhe-AI/actions/project-sync Composite Action。模式 B 为手动批量校正，对比项目与 Issue/PR 当前状态，批量修正不匹配项，并可检测仓库中尚未加入项目的 Issue/PR。
默认状态映射：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。可按用户需求自定义映射，也可通过 inputs 指定自定义的 Status 选项名（如 status-todo、status-in-progress、status-in-review、status-done）。
使用方式
前提条件：目标 GitHub Project 已链接到仓库；已安装并认证 gh CLI（带 project 作用域）。
模式 A 流程：确认执行模式；用 gh repo view 获取 owner、用 gh project list 获取项目编号；配置认证秘密；生成工作流文件并放置到 .github/workflows/project-sync.yml；确认状态映射；提示用户提交与推送。
认证方式有两种。方法 1 使用 Personal Access Token（fine-grained token），需要 project（读写）、issues（读写）、pull_requests（读写）作用域，注册为仓库 Secret PROJECT_TOKEN。方法 2 使用 GitHub App 令牌（面向 Organization，推荐），创建 GitHub App 并授予 Projects: Read and write 权限，工作流内使用 actions/create-github-app-token 生成令牌。
工作流触发事件为 issues 的 opened、closed、reopened，以及 pull_request 的 opened、closed、ready_for_review、review_requested。工作流权限在 workflow 级别仅声明 contents: read。
模式 B 流程：用 gh project item-list 获取项目条目；用 gh issue view / gh pr view 确认当前状态；检测不一致（如 Issue 已关闭但 Status 非 Done、PR 已合并但 Status 非 Done、PR 有评审请求但 Status 非 In Review、Issue 重新打开但 Status 仍为 Done）；用 gh issue list / gh pr list 检测未加入项目的 Issue/PR；向用户展示同步内容并确认；用 gh project field-list 获取字段元数据，用 gh project item-edit 更新状态，用 gh project item-add 添加新条目；最后报告操作结果（状态更新数、新增加数、无变更数）。
引用方式与安全约束
内制 action（Fandhe-AI/actions/*）使用 @latest 引用；第三方 action 必须固定为经过审查的 40 位十六进制提交 SHA，不使用 @main / @vN 等可动引用。资料给出 actions/create-github-app-token 的固定 SHA：fee1f7d63c2ff003460e3d139729b119787bc349（v2.2.2）。SHA 仅在需要更新时手动执行 gh api 获取候选 SHA、对比差分补丁并审查 action.yml 及引用脚本后再更新，不在每次生成时动态获取最新 SHA。
验证
模式 A 完成后需检查：.github/workflows/project-sync.yml 存在且 YAML 正确；uses: 行的引用方式正确（Fandhe-AI/actions/* 为 @latest，其余为 40 位 SHA 固定），资料提供了对应的 grep 校验脚本，期望输出 OK；permissions 已显式声明（grep -c 'permissions:' 结果≥1）；sync 作业设置了 timeout-minutes（缺失属于 CI 工作流规约违规·P1）。提交推送后在 GitHub Actions 运行历史中确认首次触发即完成。
模式 B 完成后需在结果表中显示无变更计数，并可用 gh project item-list 确认最终状态。
适用场景
需要让 Issue/PR 生命周期自动驱动项目看板 Status 的仓库；已有项目但状态与 Issue/PR 实际状态不一致、需要一次性批量补正；需要补录尚未加入项目的 Issue/PR。
限制
从 GitHub Actions 访问 Projects API 时 GITHUB_TOKEN 权限不足，必须使用 PAT 或 GitHub App 令牌。fine-grained PAT 有效期最长 1 年，建议定期轮换。若 project-init 已启用内置工作流（closed→Done、merged→Done），与 Actions 工作流会双重触发，但更新为相同值故无实际影响。内置工作流仅支持 closed/merged；opened→In Progress、review_requested→In Review 只能通过 Actions 自动化。私有仓库需在 org 的 Settings → Actions → General 中允许从私有仓库共享 Action。手动补正模式必须在同步前获得用户确认。DraftIssue 类型条目不纳入同步（不存在实际 Issue）。需要网络，相关命令需按命令单位禁用 sandbox 执行；无法解除网络阻断的环境无法运行。