Grape 使用指导文档

Grape 是一个多 Agent 协作的 DevOps 平台，通过 VOD/Issue/Coding/QA/SRE 五类 Agent 覆盖从需求分析到部署运维的全生命周期。平台对接 GitCode 代码托管，通过 Webhook 自动触发流水线，由 AI Agent 自主完成任务并提交 PR。

核心概念

仓库（Repo）：GitCode 上的代码仓库，是所有任务的工作空间
Agent：AI 驱动的自主代理，按职责分为 VOD/Issue/Coding/QA/SRE 五类
技能（Skill）：Agent 的能力包，定义了执行特定任务的指令和工具
运行时（Runtime）：执行 Agent 的引擎实例（opencode/hermes/codearts），部署在 Worker 机器上
流水线（Pipeline）：Issue 从创建到关闭的全流程，Agent 按 VOD→Issue→Coding→QA→SRE 链路协作

2. 快速上手

2.1 登录与仓库选择

使用 GitCode 账号登录（OAuth 自动授权）
登录后在左侧选择已授权的仓库
选择仓库后进入工作台，顶部显示仓库名

2.2 创建第一个 Issue

在 GitCode 仓库中创建一个 Issue（如"开发一个 Hello World 页面"）
Grape 通过 Webhook 自动接收 Issue 事件并启动流水线
在 Grape 控制台的 流水线 页面可以看到 Issue 的处理进度
VOD Agent 首先分析需求，然后 Issue Agent 细化任务，Coding Agent 编写代码并提交 PR

提示

也可以在 Grape 控制台的 VOD Agent 页面直接输入需求，手动触发处理流程。VOD Agent 会分析需求并自动路由到合适的下游 Agent。

2.3 查看任务进度

任务中心：查看所有任务的执行状态（排队/运行中/已完成/失败）
流水线：按 Issue 查看全链路进度，包含每个 Agent 的执行状态和结果
系统监控：查看 Worker 负载、引擎健康状态、探活延迟
点击任意任务可查看详细执行日志（Agent 每一步的思考过程和工具调用）

2.4 评审与合并 PR

Coding Agent 完成代码编写后会自动在 GitCode 创建 PR。你可以：

在 GitCode 上查看 PR 的代码变更
QA Agent 会自动审查 PR 并给出评审意见
确认无误后在 GitCode 合并 PR
Grape 会感知 PR 合并事件并更新 Issue 状态

3. DevOps Agent 详解

VOD VOD Agent — 需求分析

职责：接收用户需求（Issue 评论或直接输入），分析需求类型，路由到合适的下游 Agent。

触发方式：GitCode Issue 创建/评论事件，或控制台手动输入

典型场景：

用户创建 Issue "优化前端UI样式" → VOD 分析为开发类需求 → 路由到 Issue Agent
用户创建 Issue "销毁云资源" → VOD 分析为运维类需求 → 路由到 SRE Agent
用户在评论区补充需求 → VOD 重新分析并路由

ISSUE Issue Agent — 任务拆解

职责：将 VOD 分析后的需求细化为可执行的 Spec 文档，打标签、分配负责人，交办给 Coding/QA/SRE Agent。

输出：Issue 评论中的 Spec 文档（含技术方案、文件清单、验收标准）

CODING Coding Agent — 代码实现

职责：根据 Spec 文档编写代码，本地构建验证，自审查后提交 PR。

引擎：opencode 或 hermes（在 Worker 上执行）

工作目录：/root/grape-workspaces/<owner>/<repo>/issues/<n>/coding

典型流程：克隆仓库 → 阅读项目知识基线 → 按需求编码 → 构建+测试 → 代码自审查 → 推送分支 → 创建 PR

QA QA Agent — 质量审查

职责：审查 Coding Agent 提交的 PR，检查代码质量、安全性、测试覆盖，给出 Approve/Request Changes 意见。

触发：PR 创建事件自动触发，或 Coding Agent 完成后 A2A 交办

SRE SRE Agent — 运维部署

职责：云资源管理（创建/查询/销毁）、CI/CD 配置、部署执行、故障排查。

能力：华为云 ECS/VPC/EIP/安全组/RDS/OBS 管理，Terraform IaC，部署脚本执行

安全机制：销毁类操作需用户在 Issue 评论区确认后才执行

4. 流水线机制

4.1 自动流水线

当 GitCode Issue 被创建时，Grape 自动启动流水线：

Issue 创建
  → VOD Agent 分析需求、判断类型
    → Issue Agent 细化 Spec、打标签
      → Coding Agent 编写代码、提交 PR
        → QA Agent 审查 PR
          → 等待维护者合并 PR
            → Issue 关闭（流水线完成）

4.2 A2A（Agent-to-Agent）通信

Agent 之间通过 A2A 事件传递上下文。例如 Issue Agent 完成后会产生 a2a_event，携带 Spec 上下文交给 Coding Agent。每次 A2A 交接都会在流水线中显示为一个节点。

4.3 手动触发

在 VOD Agent 页面输入需求文本，手动触发分析
在 流水线 页面点击"重试"可重新执行失败的节点
在 Issue 评论区 @bot 可以触发特定 Agent

5. 技能管理

5.1 官方技能

Grape 内置 60+ 官方技能（SKILL.md），涵盖代码审查、部署、监控、文档生成等场景。在 DevOps 技能 页面查看所有技能。

5.2 自定义技能

用户可以为仓库创建自定义技能：

在 DevOps 技能 页面点击"创建技能"
编写 SKILL.md（包含触发条件、执行步骤、工具列表）
技能作用域：仓库级（仅当前仓库可用）或全局（所有仓库可用）

技能分发机制

技能文件存储在主服务器的 skills/ 目录（OBS 模式下同步到 OBS 桶）。Worker 执行任务时，技能文件随任务下发到工作区的 .skills/ 目录——Worker 不需要本地维护技能文件。

6. 运行时与引擎

6.1 引擎类型

引擎	说明	适用场景
opencode	OpenCode CLI，AI 编码助手	Coding/Issue/QA Agent
hermes	Hermes Agent，支持 ACP 协议	VOD/Chat/SRE Agent
codearts	华为云 CodeArts CLI	特定 CI/CD 场景

6.2 Worker 管理

在 Agent 运行时 页面查看所有 Worker 设备和引擎状态
每个 Worker 可以运行多个引擎实例（如同时运行 opencode + hermes + codearts）
Worker 自动注册并定期心跳上报（CPU/内存/磁盘/探活结果）
系统监控页面展示每个引擎的探活状态（CLI 测试对话延迟）

7. 系统监控

7.1 运维概览

系统监控 页面提供实时运维数据：

任务队列深度（排队/运行中/已完成/失败）
卡住检测（运行超过 22 分钟的任务预警）
Runtime 引擎负载（运行任务数/最大并发数）
引擎探活（每 10 分钟 CLI 测试，显示延迟和状态）
Worker 设备健康（CPU/内存/磁盘/tmp 使用率）

7.2 引擎探活

系统每 10 分钟对每个引擎发起测试对话（如 opencode run "hello"），记录响应延迟和成功/失败状态。探活结果在 Runtime 引擎表格中以图标显示：

✅ ok + 延迟（秒）— 引擎正常
❌ fail + 错误信息 — 引擎异常
⏳ pending — 等待首次探活
⏭ skip — 引擎未安装

8. 项目知识库

Grape 为每个仓库自动维护项目知识基线（Project Graph），包含：

项目结构和技术栈分析
代码能力和依赖关系
历史 Issue 和 PR 的处理记录

在 项目知识库 页面查看和编辑。知识基线在 Agent 执行任务时作为上下文注入，帮助 Agent 更准确地理解项目。

OBS 存储模式下，知识基线文件自动同步到 OBS 桶，支持多节点共享。

9. 常见问题 (FAQ)

Q0: 创建任务前需要做什么准备？为什么任务报"无可用引擎"？

创建任务前必须先在场景中心配置并应用场景

新建 Issue 触发流水线之前，必须先完成以下步骤，否则 Agent 会报 engine_unavailable（无可用引擎） 导致任务失败：

进入场景中心：选择仓库后，点击左侧导航栏的 场景中心
选择场景：在下拉框中选择一个场景（默认场景 default 已预置 VOD→Issue→Coding→QA→SRE 全链路 Agent 节点）
配置引擎：点击 配置引擎 按钮，为每个 Agent 节点选择要使用的引擎实例（从已注册的 Worker 引擎中选择）：
- VOD Agent → 选择 hermes 引擎实例
- Issue Agent → 选择 opencode 引擎实例
- Coding Agent → 选择 opencode 引擎实例
- QA Agent → 选择 opencode 引擎实例
- SRE Agent → 选择 hermes 引擎实例
保存引擎配置：配置完成后点击 保存引擎 按钮
应用场景：点击应用按钮，将场景配置绑定到当前仓库

注意事项

如果没有点击"应用"，场景配置不会生效，Webhook 事件仍使用默认配置
如果引擎未配置（engine_runtime_ids 为空），Agent 会报"无可用引擎"并失败
新增 Worker 后需要回到场景中心重新配置引擎，将新引擎分配给 Agent
不同仓库可以应用不同场景（如开发仓库用 default 场景，运维仓库用自定义 SRE 场景）
自定义场景：在下拉框选择"创建自定义场景"，配置每个 Agent 的技能（skill）、触发模式（mode）、下游路由（next）等

Q1: Issue 创建后没有触发流水线？

可能原因及排查：

Webhook 未配置：检查 GitCode 仓库的 Webhook 设置，确认已配置指向 Grape 的 webhook URL（https://webhook.grapedev.topxtopx.com/webhook/gitcode）
仓库未授权：在 Grape 控制台"GitCode 仓库"页面确认仓库已导入
Webhook Secret 不匹配：在 GitCode Webhook 设置中确认 Secret 与 Grape 配置一致
事件类型未勾选：GitCode Webhook 需勾选 Issue 和 PR 相关事件
查看 webhook 日志：在 GitCode Webhook 管理页面查看推送结果（HTTP 200 表示成功）

Q2: 任务状态显示"失败"，如何排查？

在 任务中心 或 流水线 页面点击失败的任务，查看详细日志
常见失败原因：
- exit_code=-1, duration=30s：引擎启动失败（如 Hermes ACP 依赖缺失、CLI 路径错误）
- exit_code=-15：任务被信号终止（服务重启、超时 kill）
- exit_code=1：Agent 执行出错（代码编译失败、API 调用失败）
- "无可用引擎"：没有在线的 Worker 运行所需引擎，检查 Agent 运行时页面
在 系统监控 页面检查对应 Worker 的引擎探活状态
SSH 到对应 Worker 查看 journalctl -u runtime-agent 日志

Q3: 控制台页面显示"加载中..."不消失？

排查步骤：

强制刷新：按 Ctrl+Shift+R 强制刷新页面，清除浏览器缓存的旧版 JS
检查网络：确认能访问 Grape 域名（如 grapedev.topxtopx.com）
检查登录状态：如果 token 过期，页面会跳转到登录页
检查后端服务：直接访问 https://<域名>/health 确认服务在线
查看浏览器控制台：F12 打开开发者工具，查看 Network 标签中是否有请求超时

Q4: Agent 执行的任务一直卡在"运行中"？

任务超时：Worker 默认任务超时 30 分钟，超时后自动标记失败
Worker 离线：检查系统监控中对应 Worker 是否在线（心跳是否正常）
引擎卡死：可能是 AI 模型 API 限流或网络中断，检查 Worker 日志
手动处理：在流水线页面点击"重试"重新执行，或在 Issue 评论区重新触发
清理僵尸任务：联系管理员在数据库中执行 UPDATE events SET status='failed', exit_code=-15 WHERE status='running' AND started_at < ...

Q5: 如何添加新的 Worker 机器？

在目标机器上安装 Python 3.10+ 和所需 AI CLI（opencode/hermes/codearts）
在 Grape 控制台 Agent 运行时 → 通用设置 中创建新的 Worker 凭据

在目标机器执行一键安装命令：

curl -fsSL https://<grape域名>/api/runtime/install | bash -s -- --token <rta_...> --server https://<grape域名>

安装完成后 Worker 自动注册，在运行时页面可见
确认引擎探活状态为 ✅

Q6: 引擎探活显示"pending"或"fail"？

pending（等待）：引擎刚注册，等待首次探活（每 10 分钟执行一次）。等待几分钟后刷新即可。

fail（失败）：

检查引擎 CLI 是否已安装：which opencode / which hermes
手动测试：opencode run "hello" 或 hermes chat -q "hello" --yolo
检查 AI 模型 API Key 是否配置正确（/etc/grape/grape.env 或 ~/.hermes/.env）
如果使用 hermes 引擎，确认已安装 ACP 依赖：hermes acp 应输出 "ACP client connected"

Q7: SRE Agent 销毁云资源时需要注意什么？

⚠️ 安全提示

SRE Agent 执行资源销毁前必须经过用户确认。流程如下：

用户创建 Issue 要求销毁资源
SRE Agent 查询并列出所有待销毁资源清单，在 Issue 评论区发布
用户在评论区回复"全部销毁"或指定资源确认
SRE Agent 确认后执行销毁操作
销毁完成后在 Issue 评论区发布验证结果

如果需要中止销毁，在确认前关闭 Issue 或在评论区回复"取消"即可。

Q8: 如何查看 Agent 的详细执行日志？

控制台：在任务中心/流水线页面点击任务行，弹出日志详情弹窗，显示每一步的思考和工具调用
Worker 日志：SSH 到 Worker 机器执行 journalctl -u runtime-agent -n 100 --no-pager
服务端日志：在系统监控页面查看错误日志来源，或 SSH 到主服务器查看 /root/grape/data/main.log
数据库：事件的 result 字段包含 Agent 的最终输出摘要

Q9: Coding Agent 提交的 PR 需要手动合并吗？

是的。Coding Agent 提交 PR 后，QA Agent 会自动审查并给出意见，但PR 合并需要仓库维护者手动操作。这是设计上的安全机制——AI 可以编写代码和提交 PR，但代码合入主线需要人工确认。

在 GitCode 的 PR 页面可以查看 QA Agent 的审查意见和代码变更，确认后点击"合并"即可。

Q10: 如何配置 AI 模型的 API Key？

AI 模型配置在以下位置：

主服务器：/etc/grape/grape.env 中的 HERMES_CUSTOM_API_DEEPSEEK_COM_API_KEY
Worker：~/.hermes/.env 中的 HERMES_CUSTOM_OPENGW_CLOUDDEVELOPER_CLUB_API_KEY
opencode：~/.config/opencode/opencode.json 中的 apiKey

修改后需重启对应服务（主服务器：grape-main/grape-webhook；Worker：runtime-agent）。

Q11: 如何为仓库配置自定义技能？

在 DevOps 技能 页面点击"创建技能"
选择作用域：仓库级（选择目标仓库）或全局
编写 SKILL.md：包含 name、description（触发条件）、steps（执行步骤）
可选：添加 references/（参考文档）、scripts/（脚本）、templates/（模板）
保存后技能自动分发到 OBS（如已启用），Worker 执行时自动下载

Q12: 系统监控中 Worker 的 tmp 百分比很高怎么办？

Worker 的 /tmp 目录可能被 AI 引擎运行时生成的 JIT 缓存文件（隐藏 .so 文件）占满。症状：scp 传输文件报 "No space left on device"，但 Worker 运行正常。

清理方法（在 Worker 上执行）：

find /tmp -maxdepth 1 -name ".*.so" -delete

建议定期清理所有 Worker 的 /tmp 目录。如果频繁占满，可以在 crontab 中添加定时清理任务。