GitHub 集成
一次性连接 GitHub App，之后 PR 的分支名、标题或正文里写了 issue 编号（例如 AAC-123），就会自动挂到那个 issue 上——PR 合并时 issue 自动转 Done。
在 Settings → GitHub 里一次性连一个 GitHub 账号或组织。之后任何 PR 只要分支名、标题或正文里出现 issue 编号（例如 AAC-123），就会自动关联到那个 issue，出现在 issue 详情页右侧的 Pull requests 区块里——PR 合并时，issue 自动转 Done。
没有 per-issue 的配置，整个流程是「编号驱动」的。
集成做了什么
| 出现位置 | 行为 |
|---|---|
| Settings → GitHub | 工作区 owner / admin 看到 GitHub 这个 tab，里面有主开关、Connect GitHub 按钮，以及功能开关（PR 侧栏、Co-authored-by、auto-link）。点 Connect 会打开 GitHub 的 App 安装页；装好后跳回 GitHub tab。 |
| Issue 详情侧栏 → Pull requests | 列出所有自动关联到该 issue 的 PR，含标题、仓库、状态（Open / Draft / Merged / Closed）和作者。点一行跳到 GitHub。 |
| Webhook（后台） | 每次 pull_request 事件触发：upsert PR 行 → 扫描里面的 issue 编号 →（重新）建立 link。幂等——重投 delivery 不会产生重复记录。 |
| Merge 自动改 status | PR 转 merged 时，所有已关联且状态不是 Done / Cancelled 的 issue 会被推到 Done。时间线里以 source 为 github_pr_merged 记录。 |
只镜像 PR 本身。Commit、没开 PR 的分支、CI 检查状态都不入库——集成有意保持窄边界。
多个工作区
同一个 GitHub App installation 可以同时连接到多个工作区——比如同一组织下不同团队各自用独立工作区。此时每个已连接的工作区都会各自独立收到每个仓库的 pull_request 事件：
- 每个工作区各自镜像 PR，并按自己的 issue 前缀 和 GitHub 功能开关做自动关联。一个同时引用
AAC-1和ENG-2的 PR，会在前缀为AAC的工作区关联AAC-1、在前缀为ENG的工作区关联ENG-2，两边互不可见对方的 issue。 - 从某个工作区断开连接，只会让该工作区停止接收事件，其它工作区照常工作。
仓库范围由你授予 GitHub App 的权限决定（全部仓库或指定子集）。在工作区连接这个 installation 本身就是一次订阅——AACWorkflow 里不需要再单独逐仓库勾选。
事件投递以 GitHub 连接为准，而不是工作区的代码仓库列表。 如果某个工作区之前是在没有连接 GitHub 的情况下、仅靠代码仓库列表里登记该仓库来接收 PR 事件，它将不会收到事件。要恢复投递，需在该工作区的 Settings → GitHub 里连接同一个 GitHub installation。
编号是怎么匹配的
Webhook 从三个字段抽取编号，顺序是：PR head 分支 → PR 标题 → PR 正文。匹配规则：
- 大小写不敏感——
aac-123、AAC-123、Mul-123都能匹配 - 有边界——左侧
\b、右侧只接数字，避免误抓v1.2-3、email 地址等 - 限定到本工作区——只匹配本工作区的 issue prefix。前缀是
AAC的工作区里，PR 出现FOO-1不会匹配，即使数字撞另一个 issue 也不会 - 自动去重——
Closes AAC-1, AAC-1只关联一次
一个 PR 里可以同时引用多个 issue。比如 Closes AAC-1, AAC-2：PR 同时关联两个 issue，合并时两个 issue 都会转 Done。
Merge 自动转 Done 的规则
PR 的 merged 字段翻成 true 时，逐个评估关联的 issue：
| Issue 当前状态 | 结果 |
|---|---|
done | 不变（已经是终态） |
cancelled | 不变——cancelled 是用户明确放弃工作的信号，集成不覆盖 |
其他（todo / in_progress / in_review / blocked / backlog） | 转成 done |
PR 关闭但没合并——只更新 PR 卡片的状态为 Closed，issue 状态不变。"关闭但不合并"语义因团队而异，AACWorkflow 不替用户做决定。
状态变更的 actor 是 system。订阅了该 issue 的成员会收到 inbox 通知，和成员手动改状态时一致。
哪些情况不会自动关联
- Commit message 里的编号——只扫 PR 的分支 / 标题 / 正文。一个 commit message 写
AAC-123: fix login不会触发关联，除非同样的字符串也出现在 PR 标题或正文里 - PR 评论里的编号——只扫 PR 自己的元数据，后续的 GitHub comment 不读
- App 没安装的仓库里的 PR——没 App，AACWorkflow 收不到 webhook
- 手动把 PR 关联到 issue——暂时没有这个 UI。如果你们的约定把编号放到 AACWorkflow 不扫的地方，请改放到 PR 标题或正文里
断开连接
Settings → GitHub 里没有 installation 列表——现有 installation 直接到 GitHub 上管理：
- 从 GitHub 卸载 —— 个人在
https://github.com/settings/installations、组织在https://github.com/organizations/<org>/settings/installations卸载 AACWorkflow App。AACWorkflow 收到installation.deletedwebhook 后立刻删行；任何已打开的 Settings tab 实时更新，不用刷新 - AACWorkflow 这边的断开是 admin only —— GitHub tab 上的 Disconnect 控件对非 admin 不显示；主开关关掉时 Disconnect 仍然可用，方便 admin 一键关闭功能后再单独清理已连接的 installation
断开之后，已经镜像的 PR 行保留在数据库里——历史 issue 侧栏仍能显示当时关联的 PR，但来自这个 installation 的新 webhook 事件不再被接受。
权限和可见性
- Connect / Disconnect 需要工作区 owner 或 admin。普通成员能看到卡片描述但看不到 Connect 按钮
- Pull requests 侧栏对所有能看到该 issue 的成员可见——和 issue 详情页其他部分权限一致
- GitHub App 申请的是 PR 和 Metadata 的 只读 权限。AACWorkflow 从不向 GitHub 推 commit、评论或 status check
AACWorkflow Cloud 集成
GitHub 集成在 AACWorkflow Cloud 上已经配置好了。打开 Settings → GitHub，点 Connect GitHub 就能关联你的账号或组织，选好要授权的仓库，走完安装流程即可。
安装完成后，任何仓库里分支 / 标题 / 正文带本工作区 issue 编号的 PR，几秒内就会自动关联到对应 issue。当 agent 为某个绑定 issue 的任务检出仓库时，worktree 分支会自动以该 issue 命名——agent/<issue-key>/<short-task-id>（例如 agent/aac-123/01234567）。因为 issue key 已经在分支名里，从这个分支开的 PR 不需要额外操作就能关联回 issue。
已知限制
目前还没做的几个边界：
- 手动 link UI 暂未提供——关联 PR 的唯一方法是把 issue 编号写到 PR 分支 / 标题 / 正文
- 不读 CI / check 状态——只镜像 PR 本身，构建状态、reviewer 评论、reviewer 列表都没接进 AACWorkflow
- 没有工作区级别的 merge → status 映射配置——默认固定是
merged → done（cancelled 除外）。可配置映射是后续迭代 - 同 issue 多 PR 时，merge 行为偏激进——两个 PR 都引用
AAC-123时，第一个 merge 就把 issue 转 Done。"等所有关联 PR 都解决再推进 issue 状态"的优化已经在做了