GitHub PR 评论同步

GitHub PR 评论同步功能保持 GitHub pull request 和 AACWorkflow 间的评论同步，使团队讨论在两侧保持统一和最新。

工作原理

同步方向

GitHub → AACWorkflow: 当有人在 GitHub PR 上发表评论时，AACWorkflow 将其镜像到关联的 issue（若存在）。评论归属于 GitHub 用户并标记 GitHub 徽章。

AACWorkflow → GitHub: 当有人评论有关联 GitHub PR 的 AACWorkflow issue 时，AACWorkflow 将评论发表到 PR 讨论线程（若配置）。

评论同步按 issue 可选。你可为不应跨平台的敏感讨论禁用它。

示例流程

你创建 PR：#123 Add OAuth support
PR 标题匹配 AACWorkflow issue：AAC-42
Issue 页面显示：Pull requests → #123 Add OAuth support
审查者在 PR 上发表评论：「Good approach, but let's add type safety to the token handler」
AACWorkflow 自动将评论镜像到 issue 讨论线程
团队成员在两个地方看到相同反馈

评论元数据

同步的评论带有元数据，让你知道其来源：

徽章	来源	同步方向
🐙 GitHub	评论发表在 GitHub PR 上	GitHub → AACWorkflow
✅ AACWorkflow	评论发表在 AACWorkflow	AACWorkflow → GitHub

查看评论时，你将看到：

原作者 — GitHub 用户名或 AACWorkflow 用户
原始时间戳 — 评论首次发表时间
原始链接 — 点击跳转到源头（GitHub PR 或 AACWorkflow 线程）

控制同步行为

按 issue 同步设置

转到有关联 PR 的 issue。在Pull requests部分，点击 PR 行打开 PR 面板。切换：

同步评论 → 开/关

当开启时，PR 上的新评论镜像到 AACWorkflow。现有评论不会被回溯同步。

当关闭时，链接保留（供参考）但新评论不镜像。

工作区范围同步政策

转到设置 → GitHub → 评论同步政策设置默认值：

政策	行为
始终同步 (默认)	所有 PR 评论自动镜像
按 PR 选择加入	仅对用户明确启用的 PR 同步
永不同步	所有同步禁用；链接仅供参考

各 issue 可覆盖工作区政策。

评论去重

若同时在 GitHub 和 AACWorkflow 上发表评论（罕见），AACWorkflow 使用幂等性密钥避免重复。系统检查：

作者 + 时间戳 + 前 100 字符内容 = 唯一身份
10 秒内的重复发表 → 去重

编辑和隐私

评论中的敏感信息不自动编辑。若评论含有密钥（API 密钥、令牌、凭证）：

立即删除源头（GitHub 或 AACWorkflow）
删除不同步 — 你必须手动删除两个副本
考虑使用 pre-commit hook 在密钥到达任一平台前捕获

勿在评论中发表密钥、API 密钥或凭证。它们可能镜像到两个平台。

线程与上下文

PR 评论同步为 AACWorkflow issue 上的线程回复：

GitHub PR: 特定行/文件的审查评论
AACWorkflow: 内联评论收集到 issue 时间线的 PR 评论部分

GitHub PR 线程内的回复同步为 AACWorkflow 中的嵌套回复。

限制

不同步： PR 审查事件（批准/请求更改）、提交评论、特定文件的审查评论仅映射到 PR 级线程
某些事件单向： GitHub PR「准备审查」状态不映射到 AACWorkflow 状态变化
评论编辑： GitHub 上的编辑同步（显示更新时间戳）；AACWorkflow 上的编辑不同步到 GitHub（GitHub API 限制）
评论删除： 任一侧的删除不同步；你必须手动删除两个副本

API

为 PR 同步评论

POST /api/issues/{issue_id}/github/pr/{pr_number}/sync-comments

手动触发此 PR 的评论同步。返回：

{
  "synced_count": 5,
  "new_comments": 3,
  "updated_comments": 2,
  "skipped": 0
}

列出 issue 的同步评论

GET /api/issues/{issue_id}/github/pr-comments

{
  "comments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pr_number": 123,
      "github_comment_id": "1234567890",
      "author": "jane-smith",
      "author_type": "github",
      "body": "Good approach, but let's add type safety...",
      "created_at": "2025-06-22T15:30:00Z",
      "synced_at": "2025-06-22T15:30:05Z",
      "url": "https://github.com/org/repo/pull/123#discussion_r1234567890"
    }
  ]
}

为 issue 禁用同步

PATCH /api/issues/{issue_id}/github/sync

Body：

{
  "sync_pr_comments": false
}

故障排除

「来自 GitHub 的评论未出现」

检查 PR 面板中同步评论已启用
检查工作区同步政策（设置 → GitHub）
等待 30 秒 — 同步在后台工作线程上运行
若仍缺失，点击立即同步强制刷新

「评论出现在 GitHub 但不在 AACWorkflow」

验证 GitHub PR 已链接到 AACWorkflow issue
检查 issue 页面 → Pull requests 部分
若 PR 未列出，重新运行 GitHub issue/PR 导入（设置 → GitHub）

「我在 AACWorkflow 中发表了评论但未出现在 GitHub」

验证此 PR 的同步评论已启用
检查你对 GitHub 仓库有写入权限
查看 issue 审计日志（设置 → 审计）以查看同步错误

「相同评论出现多次」

若同步被手动触发（/sync-comments）而后台工作线程也在运行时可能发生。点击重复项上的删除，它将从两侧移除（一键清理）。

最佳实践

使用 GitHub 做代码审查 — 详细的逐行反馈
使用 AACWorkflow 做任务上下文 — PR 创建的原因、它依赖什么
早期链接 PR — 在分支名或 PR 标题中提及 issue ID 使链接自动检测
不要手动跨发 — 不要在两个地方粘贴相同评论；让同步处理
大 PR 前检查设置 — 在大团队 PR 前设置同步政策以避免重复