GitHub Issue 导入与导出

GitHub Issue 导入与导出功能让团队把现有 GitHub issue 引入 AACWorkflow 并保持同步。这对于已在 GitHub Issues 跟踪工作但想采用 AACWorkflow AI 智能体而不丢失积压项的团队必不可少。

概览

此功能提供：

• 一次性导入 — 将开放的 GitHub issue 拉入 AACWorkflow 作为积压项
• 反向链接记录 — 每个导入的 issue 有返回其 GitHub URL 的引用
• 双向字段同步 — 标题、描述和状态在两侧保持同步
• 冲突解决 — 双方修改时，应用可配置策略（最后写入、AACWorkflow 优先、GitHub 优先）
• 暂停/恢复 — 停止特定 issue 同步而不断开集成

支持的字段

注意： 仅同步第一个 GitHub 分配者。AACWorkflow 中的智能体分配者永远不会导出到 GitHub。

导入工作流

步骤 1：触发导入

导航到设置 → GitHub 并点击导入 Issue。你会看到一个表单：

导入自： owner/repo 过滤器：

• 状态：open、closed 或两者
• 标签：可选过滤器（如 bug、feature）
• 开始于：可选日期过滤器

点击导入。AACWorkflow：

1. 通过 GitHub App token 从 GitHub 获取匹配的 issue
2. 对于每个没有现有映射的 issue，创建一个 AACWorkflow issue
3. 在 external_issue 表中记录映射
4. 返回 { imported: 42, skipped: 0, mappings: [...] }

步骤 2：审查映射

转到设置 → GitHub → Issue 映射。你会看到所有已同步 issue 的表格：

点击任何行可以：

• 查看返回 GitHub issue 的反向链接
• 暂停/恢复该 issue 的同步
• 手动立即触发同步

双向同步

同步方向

GitHub → AACWorkflow (webhook): 当 GitHub issue 被编辑时，GitHub 发送 webhook。AACWorkflow 将改变的字段（标题、描述、状态）应用于映射的 AACWorkflow issue。

AACWorkflow → GitHub (worker): 当 AACWorkflow issue 被更新时，后台工作线程去抖动该更改并 PATCH GitHub issue。

定期协调： 每 30 分钟，AACWorkflow 检查最近未同步的 issue（如错过的 webhook）并进行协调。

冲突解决

如果 GitHub 和 AACWorkflow 自上次同步后都有更改，冲突使用工作区的同步策略解决：

重要： 当冲突解决时，失败值不会丢失 — 它被记录在 AACWorkflow issue 的审计评论中：

从 GitHub 同步：标题从「添加 OAuth」改为「添加 OAuth 2.1」
(AACWorkflow 版本：「添加 OAuth」在 2025-06-22 15:30 UTC 被 GitHub 覆盖)

例：同时编辑

场景： 你在 AACWorkflow 中编辑标题，同时团队成员在 GitHub 上编辑同一 issue。

1. AACWorkflow 标题：「修复登录超时」→「修复身份验证超时」(你改的)
2. GitHub 标题：「修复登录超时」→「修复登录会话错误」(团队成员改的)
3. 两个更改在协调窗口内到达

解决 (假设 newest_wins):

• GitHub updated_at: 2025-06-22 15:30:00
• AACWorkflow updated_at: 2025-06-22 15:29:45
• 结果： GitHub 版本赢 → AACWorkflow 标题变为「修复登录会话错误」
• 审计轨迹： 审计评论记录冲突和被覆盖内容

暂停 / 恢复同步

要停止特定 issue 的同步（如你在 AACWorkflow 中做详细工作且不想 GitHub 更改干扰）：

1. 转到设置 → GitHub → Issue 映射
2. 点击 issue 行
3. 切换同步启用 → 关闭

该 issue 的同步被暂停。其他 issue 继续正常同步。

要恢复：

1. 切换同步启用 → 开启
2. 点击立即同步立即协调

断开工作流

如果你从工作区断开 GitHub App：

1. 所有 external_issue 映射级联删除
2. AACWorkflow issue 保留（不被删除）
3. 反向链接从 issue 页面移除
4. 历史审计轨迹保留以用于合规

如果稍后重新连接，你需要重新导入以重建映射。

API

示例：通过 API 导入

curl -X POST https://aacworkflow.example.com/api/workspaces/my-ws/github/issues/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_owner": "my-org",
    "repo_name": "my-repo",
    "filters": {
      "state": "open",
      "labels": ["bug"],
      "since": "2025-01-01T00:00:00Z"
    }
  }'

返回：

{
  "imported": 12,
  "skipped": 0,
  "mappings": [
    {
      "external_issue_id": "...",
      "issue_id": "...",
      "gh_issue_number": 123,
      "html_url": "https://github.com/my-org/my-repo/issues/123",
      "sync_enabled": true
    }
  ]
}

安全

• 所有查询按 workspace_id 过滤 — 无跨工作区数据泄漏
• Webhook 签名在处理前验证
• 安装令牌永不暴露给客户端
• 分配者同步仅映射已验证工作区成员（永不创建邀请）

非目标 (未来版本)

以下在 v1 中被有意不支持：

• 导入 GitHub Projects (boards)、milestones 或 labels 作为一类对象
• 实时评论同步（独立规格：github-pr-comments-sync.md）
• 从 AACWorkflow 创建全新 GitHub issue（导出仅限于被导入的 issue）

故障排除

「导入失败：权限被拒绝」

你可能在工作区中没有管理权限。仅工作区管理员可触发导入。

「部分 issue 被跳过 (synced 40, skipped 2)」

被跳过的 issue 已有映射。在同一仓库上重新导入是幂等的 — 之前导入的 issue 不会重新创建。

「标题改变但未同步到 GitHub」

同步工作线程每 30 秒运行一次（去抖动）。如果更改在 5 分钟内未同步：

1. 转到设置 → GitHub → Issue 映射
2. 点击 issue 行
3. 点击立即同步强制立即协调
4. 检查审计日志以查看错误

「同一 issue 不断发生冲突」

你可能经常在两侧编辑 issue。考虑：

1. 将同步策略设置为 aac_wins 以优先选择 AACWorkflow
2. 在大量编辑时暂停同步，然后恢复
3. 在集成稳定前仅在一侧进行编辑