[讨论] Webhook 触发：监听 GitHub Issue 事件实现自动调度

[JiGuangWorker]

背景

目前 code-bee 需要手动执行 CLI 命令来触发任务调度：

code-bee --repo your-org/your-repo --issue 42

路线图中已规划 "Webhook 触发" 功能，目标是：当 Issue 发生特定事件时（如新建、编辑、打标签等），自动触发 code-bee 解析并调度智能体，无需人工干预。

---

讨论重点

1. GitHub Webhook 的 Issue 事件有哪些？

GitHub 提供了 issues 事件类型，包含以下 action：

Action	触发时机	是否适合自动调度？
opened	新建 Issue	✅ 核心场景
edited	编辑 Issue 标题/正文	✅ 可能更新了任务描述
labeled	添加标签	⚠️ 可能用于触发特定 Agent
assigned	分配负责人	❓ 视场景而定
closed / reopened	关闭/重开	❌ 通常不需要
deleted	删除 Issue	❌ 不需要

另外还有 issue_comment 事件（评论的 created/edited/deleted），这在后续可能用于"在评论中 @agent 补充指令"。

2. 主要讨论点

2.1 应该监听哪些事件？

• 最小可行方案：只监听 issues.opened（新建 Issue 时触发）
• 完整方案：同时监听 issues.opened + issues.edited + issue_comment.created
• 是否需要通过特定标签（如 @agent-name 或 bee:trigger）来控制触发？

2.2 Webhook 接收端如何设计？

• 方案 A：在 code-bee 项目内增加一个 HTTP server（cmd/webhook/ 或类似）

  • 优点：自包含，部署简单
  • 缺点：需要公网可达的服务器

• 方案 B：使用 GitHub Actions 的 workflow_dispatch 或 repository_dispatch

  • 优点：无需自建服务器，在 GitHub 内闭环
  • 缺点：延迟较高，复杂逻辑受限

• 方案 C：利用现有平台（如 Cloudflare Workers / AWS Lambda） 做轻量转发

  • 优点：低成本、免运维
  • 缺点：引入外部依赖

2.3 安全性

• Webhook Secret 签名验证（HMAC-SHA256）
• 如何防止重复触发（同一 Issue 短时间内多次事件）
• 是否需要白名单仓库/组织？

2.4 与现有架构的集成

• 当前 code-bee 是 CLI 工具，Webhook 触发后如何复用现有逻辑？
• 是否需要将核心逻辑抽离为 internal/engine/ 或类似包，供 CLI 和 Webhook 共用？
• 异步执行如何管理（goroutine pool？消息队列？）

---

相关参考

• GitHub Webhooks 文档
• GitHub Issue Events API
• GitHub Webhook 签名验证

---

期望产出

通过讨论，希望确定：

1. 第一版 Webhook 触发的最小可行范围（MVP）
2. 技术方案选型（自建 Server vs GitHub Actions vs Serverless）
3. 实现路线图与分工

欢迎大家畅所欲言！🚀

[JiGuangWorker]

最小蜂群调度链路思考

以下整理自 @JiGuangWorker 的初步构想，并做了补充扩展。

---

一、核心定位

code-bee 的本质是 Agent 调度器，不是编码器本身。它像一个"蜂巢信号中转站"，接收外部刺激（Issue），翻译成任务指令，分发给工蜂（Agent），回收成果（PR）。

---

二、最小调度链路

┌─────────────────────────────────────────────────────────────┐
│                      GitHub Issue                            │
│  @agent-frontend 请重构 UserProfile 组件                      │
│  (用户创建 Issue，@agent 下达任务)                             │
└──────────────────────┬──────────────────────────────────────┘
                       │  Webhook: issues.opened
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    code-bee (边缘计算节点)                     │
│                                                              │
│  ① Webhook Receiver  ← 接收并验证 GitHub 签名                 │
│  ② Issue Parser      ← 解析 @agent-name、任务描述、验收标准    │
│  ③ Task Queue        ← 入队，管理并发与优先级                  │
│  ④ Agent Dispatcher  ← 出队，匹配 Agent，发送任务指令          │
│  ⑤ Result Collector  ← 接收 Agent 执行结果，回复 Issue          │
└──────────────────────┬──────────────────────────────────────┘
                       │  调度指令 (API / CLI)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    🧠 编码智能体 (Reasonix + DeepSeek)         │
│                                                              │
│  fork → clone → 编码 → commit → push → create PR             │
└──────────────────────┬──────────────────────────────────────┘
                       │  PR 链接 + 执行摘要
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                      GitHub Issue                            │
│  ✅ 任务完成！PR: #123  感谢 @agent-frontend                   │
│  (code-bee 回复 Issue，闭环)                                  │
└─────────────────────────────────────────────────────────────┘

---

三、关键问题：任务队列

当多个 Issue 同时触发时，确实需要一个任务队列来管理：

3.1 为什么需要队列？

场景	风险
5 个 Issue 同时 opened	5 个 Agent 同时 fork → 竞态、资源耗尽
Agent 正在执行中，又来新 Issue	本地资源（CPU/内存/磁盘）被打满
同一仓库 2 个 Issue 并发	分支冲突、PR 冲突

3.2 队列方案对比

方案	复杂度	适用场景
内存 Channel（Go chan）	⭐ 低	单节点、轻量场景，进程重启丢任务
本地持久化（SQLite / BoltDB）	⭐⭐ 中	单节点、需持久化，重启可恢复
Redis 队列	⭐⭐⭐ 中高	多节点部署、高可用
消息队列（NATS / RabbitMQ）	⭐⭐⭐⭐ 高	企业级、多消费者、复杂路由

建议 MVP 阶段：Go chan + 可选的 SQLite 持久化，简单够用。

3.3 队列策略

• FIFO 顺序执行：同一仓库的任务串行，避免分支冲突
• 仓库级隔离：不同仓库的任务可并行
• 去重：同一 Issue 不重复入队（基于 Issue ID + 事件类型）
• 超时与重试：Agent 执行超时自动重试或标记失败

---

四、补充思考

4.1 边缘计算节点的含义

你提到的"边缘计算节点"这个定位很有意思。code-bee 不需要部署在云端：

你的开发机 / NAS / 树莓派 / 小 VPS
         │
         │  ngrok / frp / Cloudflare Tunnel 暴露公网端点
         │
         ▼
   GitHub Webhook ──→ https://bee.your-domain.com/webhook

这样 code-bee 就是一个私有调度节点，Agent 在你本机执行，代码不过第三方。

4.2 Webhook 签名验证（安全）

// 伪代码：验证 GitHub Webhook 签名
func VerifySignature(secret string, body []byte, signatureHeader string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

4.3 事件过滤

不是所有 Issue 都需要触发 code-bee，需要过滤：

• ✅ Issue body 中包含 @agent-xxx 才触发
• ❌ 没有 @agent 的普通 Issue 忽略
• ⚠️ 防止自己回复的 Issue 再次触发（机器人自循环）

4.4 状态机

每个任务应有明确的状态流转：

pending → queued → running → success/failed
                            ↘ timeout → retry → success/failed

---

五、MVP 建议

第一版最小可行实现：

1. cmd/webhook/main.go  ← HTTP server，接收 Webhook
2. internal/queue/       ← 内存 channel 任务队列
3. internal/parser/      ← 已有，解析 @agent
4. internal/dispatcher/  ← 调度 Agent 执行

不需要：Redis、消息队列、多节点部署。先跑通"Issue → Webhook → 解析 → 调度 → PR → 回复"这条链路。

---

以上是对初步构想的整理和补充，欢迎大家继续讨论，特别是关于 任务队列策略 和 边缘节点部署方式 这两个方向。🐝

[JiGuangWorker]

补充：平台无关的信号输入架构

以下整理自 @JiGuangWorker 的补充思考，并做了架构层面的展开。

---

核心原则

code-bee 不应绑定任何特定代码托管平台。信号输入 → 指令输出，平台只是输入源的一种实现。

当前基于 GitHub Issues，未来可能扩展到：

平台	信号来源
GitHub	Issue / PR Comment / Discussion
GitLab	Issue / Merge Request
Gitee	Issue / PR
Gitea / Gogs	Issue
飞书 / 钉钉 / Slack	机器人消息（更远的未来）

---

架构抽象：Platform Adapter 模式

                          ┌──────────────────────┐
                          │     code-bee Core     │
                          │                       │
                          │  • Issue Parser       │
                          │  • Task Queue         │
                          │  • Agent Dispatcher   │
                          │  • Result Collector   │
                          └──────────┬────────────┘
                                     │ 依赖接口，不依赖实现
                                     │
                          ┌──────────┴────────────┐
                          │  PlatformAdapter      │  ← 接口（interface）
                          │  (internal/platform/) │
                          ├───────────────────────┤
                          │ + ParseWebhook()      │
                          │ + GetIssue()          │
                          │ + PostComment()       │
                          │ + VerifySignature()   │
                          │ + ListLabels()        │
                          └──────────┬────────────┘
                                     │
              ┌──────────────────────┼──────────────────────┐
              │                      │                      │
              ▼                      ▼                      ▼
    ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
    │ GitHubAdapter   │  │ GitLabAdapter   │  │ GiteeAdapter    │
    │                 │  │                 │  │                 │
    │ API: gh CLI     │  │ API: glab CLI   │  │ API: REST       │
    │ 或 REST/GraphQL │  │ 或 REST API     │  │                 │
    └─────────────────┘  └─────────────────┘  └─────────────────┘

---

接口定义草案

// internal/platform/adapter.go

// TriggerEvent 标准化的触发事件（平台无关）
type TriggerEvent struct {
    Platform    string            // "github" | "gitlab" | "gitee"
    Action      string            // "opened" | "edited" | "labeled"
    Repository  Repository        // 标准化仓库信息
    Issue       Issue             // 标准化 Issue 信息
    Sender      User              // 触发者
    RawPayload  json.RawMessage   // 原始 payload（平台特定字段）
}

// Repository 标准化仓库模型
type Repository struct {
    Owner       string
    Name        string
    FullName    string // "owner/name"
    CloneURL    string
    DefaultBranch string
}

// Issue 标准化 Issue 模型
type Issue struct {
    Number      int
    Title       string
    Body        string
    Labels      []string
    Assignees   []string
    State       string // "open" | "closed"
    URL         string
}

// PlatformAdapter 平台适配器接口
// 所有平台都必须实现此接口，code-bee 核心只依赖此接口
type PlatformAdapter interface {
    // ParseWebhook 解析 webhook 原始 payload，返回标准化事件
    // 不同平台的 payload 结构不同，由各自实现负责转换
    ParseWebhook(payload []byte) (*TriggerEvent, error)

    // VerifySignature 验证 webhook 签名
    // GitHub: HMAC-SHA256，GitLab: 自定义 token header
    VerifySignature(secret string, body []byte, headers map[string]string) bool

    // GetIssue 获取 Issue 详情
    GetIssue(owner, repo string, number int) (*Issue, error)

    // PostComment 回复 Issue 评论
    PostComment(owner, repo string, number int, body string) error

    // AddLabel 添加标签
    AddLabel(owner, repo string, number int, label string) error

    // PlatformName 返回平台标识
    PlatformName() string
}

---

这个设计的好处

收益	说明
解耦	code-bee 核心不 import 任何 GitHub/GitLab 特定 SDK
可测试	单元测试注入 MockAdapter，不依赖真实平台
可扩展	新增平台只需实现 PlatformAdapter 接口，核心零改动
渐进式	第一版只实现 GitHubAdapter，后续按需加 GitLabAdapter
配置驱动	通过配置文件或环境变量切换平台适配器

---

与现有项目结构的对应

当前项目已有 internal/platform/ 目录（目前为空），正好作为这个接口的落地位置：

internal/platform/
├── adapter.go           ← PlatformAdapter 接口定义 + 标准模型
├── github/
│   └── github.go        ← GitHubAdapter 实现
├── gitlab/
│   └── gitlab.go        ← GitLabAdapter 实现（未来）
└── adapter_test.go      ← 接口兼容性测试

---

更新后的完整链路图

GitHub Issue ──Webhook──→ GitHubAdapter ──→ TriggerEvent ──→ code-bee Core
GitLab Issue ──Webhook──→ GitLabAdapter ──→ TriggerEvent ──→ code-bee Core
Gitee Issue ──Webhook──→ GiteeAdapter  ──→ TriggerEvent ──→ code-bee Core
                                                              │
                                          ┌───────────────────┘
                                          │ 标准化事件
                                          ▼
                              ┌─────────────────────┐
                              │  Parser  →  Queue   │
                              │    ↓          ↓     │
                              │  Dispatcher  →  Agent│
                              └──────────┬──────────┘
                                         │
                              ┌──────────▼──────────┐
                              │  PlatformAdapter     │
                              │  .PostComment()      │
                              │  .AddLabel()         │
                              └──────────────────────┘
                                         │
                                         ▼
                              GitHub / GitLab / Gitee
                              (回复 Issue，闭环)

这样整个架构的核心约束就是：输入一个标准化事件，输出一个标准化回复，中间的平台差异完全由适配器吸收。

---

MVP 建议

第一版只实现 GitHubAdapter，但 接口先行定义——即使只有一个实现，也把接口写好。这样未来加 GitLab 时，真的就是"加一个文件"的事情。🐝