#GOAI大赛 #阿里云 #Agent Infra #Datawhale 作者：TOPGO

写在前面

参加 GOAI 世界人工智能开源大赛「Agent Infra 新智基座」赛道，最大的体感是：官方说的"技术必选基线"其实并不高——AgentTeams 作设计基点 + Skill 必选 + ≥3 个职能 Agent 的完整闭环 + RAG/可观测至少 2 项，初赛甚至不强制交代码。但真正动手时会发现，坑都在细节里。

这篇文章融合两条实战线：

• 方向一（AgentTeams 技术实践）：用 opspilot-zero-demo 这个"零人工运维"Demo，讲清楚 AgentTeams 怎么落地一个 4-Agent 协同闭环。
• 方向二（赛道通用经验）：用 zhiyi 知易企业技能系统（发票报销 + 办公三件套）的开发踩坑，复盘工程化里的真实教训。

希望给同赛道同学省下几天排坑时间。

---

一、AgentTeams 上手：一个能跑的 4-Agent 闭环长什么样

1.1 为什么是 AgentTeams

赛道明确要求多 Agent 协同框架 AgentTeams（原名 Hiclaw）必须作为设计基点。它的核心心智模型是：

• Manager 房间：负责创建和管理 Worker（agent）。
• Team 房间：用户通过 @<team_leader_name> 给 TeamLeader 派任务。
• TeamLeader Worker：创建 Team 时由 manager 生成的独立 Worker，负责调度。
• 业务 Worker：职责明确的专业 Agent，用 qwenpow（copow / QwenPaw）运行时。

关键设计点：TeamLeader 必须是独立新建的 Worker，不能把某个业务 Worker 直接指定为 leader。这一点官方文档反复强调，也是评审会重点核验的。

1.2 我们的 Agent 分工（满足"≥3 个职能 Agent"）

OpsPilot Zero Demo 设计了 4 个业务 Worker + 1 个 TeamLeader，对应"零人工运维"场景：

Agent	职能	关键 Skill	工具契约
Alert Intake	聚合客诉/告警/指标，输出事故候选与影响面	alert-fusion, impact-mapping	mock_ticket, mock_monitoring
RCA Analyst	关联日志/Trace/配置/慢SQL/Runbook，排根因	log-trace-rca, data-advisor	mock_logs, mock_traces, mock_config, mock_database, mock_runbook
Remediation Planner	生成修复/验证/回滚计划 + 风险分级	remediation-plan, risk-guard	mock_config, mock_database, mock_ticket
Recovery Verifier	执行低风险动作语义、验证恢复	recovery-verify, data-advisor	mock_probe, mock_monitoring, mock_config

闭环链路：故障现象 → Alert Intake 归并 → RCA Analyst 取证 → Remediation Planner 出计划（L0/L1 自动执行，L2/L3 只生成审批）→ Recovery Verifier 验证 → TeamLeader 汇总报告。这正是评审维度里"任务拆解 → 上下文传递 → 工具调用 → 验证 → 证据沉淀 → 审批/回滚"的完整闭环。

1.3 工具集成：没接真实 MCP 怎么办

官方说 MCP 是推荐项，但没用 MCP 必须给等价集成契约。我们用一个 HTTP mock 工具网关（python3 tools/mock_tool_server.py --port 18089）替代真实 MCP Server，统一协议：

POST http://<GATEWAY>:18089/tools/{scenario_id}/{tool_name}.{function_name}

并且提供了 MCP_MAPPING.md，把每个 mock 工具映射到真实 MCP 方法名（如 mock_traces.query_traces → trace.query、mock_runbook.search → knowledge.runbook_search）。这样评审时能清楚证明"这是 MCP 的等价契约，随时可替换"。

1.4 RAG / 可观测：我们怎么凑满 2 项

评审要求"记忆/知识库/共享状态/轨迹可观测 至少实现 2 项"。我们的覆盖：

• ✅ 轨迹可观测：工具网关在每次调用时记录完整 tool-call trace（self.trace），并提供 GET /trace 端点；data-advisor skill 专门分析可观测缺口。
• ✅ 共享状态 + 知识库：事故上下文（incident_id / scenario_id / 证据链）由 TeamLeader 在 Worker 间传递，工具网关按 scenario_id 共享数据；Runbook 以 mock_runbook 形式作为知识库项。

两项稳稳达标。

---

二、真实踩坑复盘（方向二：通用经验）

下面这些坑来自 zhiyi 知易系统（企业技能系统，含发票报销、Excel/PPT/Word 办公三件套、OCR）的实打实开发。它们对"把 Demo 推向 Production"有普适价值。

坑 1：前端悬空 import 让 vite 直接挂掉

症状：[plugin:vite:import-analysis] Failed to resolve import "@/services/bookshelfService" from "src/pages/PDFViewer.tsx"。

根因：项目用 @/ 别名，但 bookshelfService.ts 等十几个模块根本没创建，路由文件里却已经 import 了。vite 在构建期就会失败，不只是运行时白屏。

解法：用脚本扫全仓 import 语句，找出所有"被引用但文件不存在"的模块，逐个补齐（bookshelfService、invoiceApi、InvoiceStatusBadge、TagManager、KanbanBoard、SidecarChat 等）。注意 SidecarChat 既有 export default 又被命名导入 { SidecarChat }，漏掉命名导出会让 vite 报 findVariable 错误——补一个 export { SidecarChat } 即可。

经验：别名 @/ 和相对路径的悬空引用要一次性清零，否则构建永远 EXIT≠0。

坑 2：后端缺依赖，FastAPI 启动即崩

invoice_routes.py 依赖 constants.py、middleware/auth.py、middleware/audit.py、conf/model.py，但这些文件最初不存在。结果：后端一启动就 ImportError，路由根本没注册。

补法很标准：constants.py 实现 REIMBURSEMENT_STATUS_VALUES、parse_tags()、serialize_tags()；middleware 补 JWTAuthMiddleware 占位与 AuditLogMiddleware；conf/model.py 补 ModelRegistryConfig。补齐后路由正常注册。

经验：先让后端能 import、能启动，再谈业务逻辑。用 python main.py 前先 python -c "import routes" 验证依赖链。

坑 3：数据库缺列，list 接口 KeyError

发票表 invoices 最初没有 reimbursement_status、tags 列，前端列表一拉就 500。

解法：ALTER TABLE invoices ADD COLUMN reimbursement_status TEXT、ADD COLUMN tags TEXT，并插示例数据。

经验：Schema 演进要有 migration 脚本，不能靠"第一次跑应该会自动建"的侥幸。SQLite 改列尤其容易忘。

坑 4：视觉模型选错，OCR 一直 400

这是最隐蔽的一个。我们想用 Agnes 的视觉模型做发票 OCR，凭证里给的 AGNES_IMAGE_MODEL=agnes-image-2.1-flash。结果调用 /v1/chat/completions 带 image_url 一直返回 400。

排查后发现：agnes-image-2.1-flash 是图像生成模型，不是多模态识别模型。能接收图片做 OCR 的是多模态模型 agnes-2.0-flash。改环境变量 AGNES_IMAGE_MODEL=agnes-2.0-flash 后，发票图片识别一次成功，字段（发票号/金额/税号）准确入库。

经验："image" 模型名 ≠ 能看图"。生成模型和视觉理解模型是两回事，接 OCR 前先在少量样本上验证一次。

坑 5：本地无 OCR 模型，必须借远程视觉 API

赛道鼓励"数据不出域"，但中小团队本地常没有可用的 OCR/VL 模型。我们的做法是：把视觉识别抽象成 _call_agnes_vl()，凭证走环境变量注入（AGNES_BASE_URL / APIMART_API_KEY），本地不可用时回退到远程视觉 API。这样模型能力可插拔，也符合"Skill 工程体系与生态复用"的评审导向。

还好最后终于跑通了

---

三、给参赛同学的 3 条上分建议

1. 先对齐基线，再卷创新。AgentTeams + Skill + ≥3 Agent 闭环 + RAG/可观测 2 项，初赛不交代码也能过。把"设计思路讲清楚"比堆功能重要。
2. 工具契约要可替换。用 mock 网关没问题，但一定要留 MCP_MAPPING.md 证明"这是 MCP 等价物"，评审才认。
3. 踩坑即内容。复赛要交可运行 Demo/视频，把上面的坑变成"运行验证与失败处理"的证据，正好命中评审维度"Skill 需核验失败处理"。

---

四、结语

Agent Infra 赛道考的不是"谁的 Agent 最多"，而是"谁的闭环最真实、最可审计、最可复用"。AgentTeams 帮我们把多 Agent 编排的脏活标准化了，剩下的精力应该放在场景价值和工程落地证据上——这也是 25% + 25% + 20% 权重真正所在。

真实实战经验就是最好的内容。祝同赛道同学上分顺利。

#GOAI大赛 #阿里云 #Agent Infra #Datawhale