AgentScope CodingAgent 项目总结

一、项目定位与作用

agentscope-codingagent 是一个 自治代码工程 Agent——你把它部署在组织内部，它就能自动帮你写代码、改代码、审查代码。

核心能力一句话概括：你提需求，它写代码；你请求审查，它审 PR。

具体来说，它做三件事：

场景	触发方式	Agent 行为
Issue → PR	在 GitHub Issue 里评论一个需求	Coding Agent 克隆仓库 → 创建分支 → 实现功能 → 推送代码 → 开 PR
PR Review	在 PR 上把 CodingAgent 加为 Reviewer	Reviewer Agent 读 diff → 记录结构化 Findings → 发布 GitHub Review
PR 线程迭代	在 PR 某一行留评论	Coding Agent 读评论 → 编辑同一分支 → 回复在线程中

与 sibling 项目对比：

项目	定位	用户
claw	单用户自演化 Agent，跑在你的 shell 上	个人
builder	多租户 Agent 托管平台，UI 构建 Agent	团队/公司
codingagent	专门写代码的自治机器人，每个会话跑在 Docker 沙箱里	组织内代码团队

---

二、它是如何工作的

整体架构

GitHub Webhook · CLI · DingTalk · Feishu
                │
                ▼
     ┌───────────────────────────┐
     │ Channel 适配层             │  HMAC 验证 · 去重 · 自评论过滤
     └─────────┬─────────────────┘
               ▼
     ┌───────────────────────────┐
     │ ThreadIdFactory           │  github:issue:owner/repo#42 → SHA-256 → UUID
     └─────────┬─────────────────┘
               ▼
     ┌───────────────────────────┐
     │ RunDispatcher             │  立即派发 或 入队等待(busy thread)
     │   ├ MessageQueueMiddleware│
     │   ├ ThreadBudgetMiddleware│
     │   └ ModelCallLimitMiddleware│
     └─────────┬─────────────────┘
               ▼
     ┌───────────────────────────────────┐
     │ HarnessGateway                     │
     │   ├ CodingAgent  (issue/PR 循环)  │
     │   └ ReviewerAgent (review请求)    │
     └─────────┬─────────────────────────┘
               ▼
     ┌───────────────────────────────────┐
     │ SandboxFilesystem (per-session Docker)│
     │   git · shell · build tools       │
     │   运行时自动管理生命周期             │
     └─────────┬─────────────────────────┘
               ▼
         GitHub API · 目标仓库

工作流程详解（以 GitHub Issue 为例）

1. 用户触发：在某个 Issue 下评论「请帮我实现这个功能」

2. GitHub Webhook 到达：

• GitHub 向 POST /webhooks/github 推送 issue_comment.created 事件
• GitHubWebhookHandler 用 HMAC 签名验证请求真实性
• 去重：通过 SqliteBaseStore 的 delivery-log 命名空间检查是否重复投递
• 过滤自评论：如果评论者是 Agent 自己的 GitHub 账号，跳过（避免循环）

3. Thread 路由：

• ThreadIdFactory 将 owner/repo#42 映射为确定性 UUID
• 同一个 Issue 的所有后续评论都路由到同一个 thread → 同一个 Session

4. 派发调度：

• RunDispatcher 检查该 thread 是否正在执行
• 空闲 → 立即启动 CodingAgent
• 忙碌 → 将事件入队到 SQLite（namespace ["queue", thread_id]）
• 下一次 Agent 推理前，MessageQueueMiddleware 会把队列中的消息注入到系统提示中

5. Agent 执行（CodingAgent）：

• 系统提示：16 段指令组成的 CodingSystemPrompt，包含 OpenSWE 工作模式（todo_write 规划、验证循环、安全编辑规则）
• 工具集：execute(shell)、edit_file(安全编辑)、git_commit_push、github_api、fetch_url、web_search 等
• 沙箱：每个 Session 在独立的 Docker 容器中运行（SandboxFilesystem），git clone、npm install、mvn test、git push 全在沙箱内执行
• FallbackModel：主模型（DashScope/OpenAI/Anthropic 三选一）如果触发限流，自动透明切换到备用模型

6. 中间件栈保障安全：

• ThreadBudgetMiddleware：每个 thread 最多 N 次 model 调用，防止无限循环
• ModelCallLimitMiddleware：全局 model 调用上限，防止资源耗尽
• MessageQueueMiddleware：排队消息注入，保证不丢失

7. 结果回写：

• Agent 通过 github_api 工具将 PR URL / 评论回写到 GitHub
• 用户在 Issue/PR 上看到 Agent 的回复

Reviewer Agent 工作流程

与 Coding Agent 类似但安全设计不同：

特性	Coding Agent	Reviewer Agent
工具	execute, edit_file, git_* 等执行类工具	仅 add_finding + publish_review（无执行工具）
目的	写代码、改文件	只读 diff + 发布审查结果
输出	PR + 评论	结构化 Findings + GitHub Review

这确保 Reviewer Agent 不能执行任何代码，只会审查和报告。

两种运行模式

模式	入口类	用途	交互方式
Webhook 服务	CodingAgentApplication.java	生产部署	GitHub/钉钉/飞书推送事件
CLI REPL	CodingChatCli.java	本地开发测试	终端 You> 提示符对话

CLI REPL 模式下可用 /review <pr_url> 手动触发 Reviewer Agent。

沙箱安全机制

这是 CodingAgent 最重要的设计决策：Agent 永远不碰宿主机文件系统。

• 每个 Session 独立 Docker 容器（agentscope/coding-sandbox:latest）
• 运行时自动管理容器生命周期：首次使用时创建，同一 Session 跨 Turn 复用，Session 结束销毁
• 网络可选 none（无外网）或受限模式
• CPU/内存可设上限

数据持久化

• 使用 SQLite（SqliteBaseStore），而非 H2/JPA
• 三类命名空间：
  • delivery-log — Webhook 事件去重
  • ["queue", thread_id] — 消息排队
  • session-* — Session 状态
• 乐观锁 CAS 保证并发安全

Token 加密

• GitHub Webhook Secret 用 HMAC-SHA256 验证
• API Key 存储用 Google Tink AEAD（AES-256-GCM）加密，密钥文件在 ~/.agentscope/codingagent/tink-aead-key.json

---

三、一句话总结

CodingAgent = 代码工程自动化机器人：接收 GitHub/IM 事件 → 在 Docker 沙箱中自治编码/审查 → 结果回写平台。它比 claw 更安全（沙箱隔离），比 builder 更专注（只做代码任务），是组织内部部署自治编码 Agent 的首选方案。