- TECHNICAL_ARCHITECTURE: §2.2 exec_error/背压/硬截止数据流、§3.3 action union、 §4.4 连接池重写(busy 计数+在途去重)、§4.5 MCP ACL fail-closed、§5 超时矩阵 15s - TESTING: journeys 24→26、unit 31 入册、§5.1 mock helpers v2.1.4 契约、 映射表补 25/26 行、整改清单补 v2.1.2–v2.1.4 行 - DESIGN: roadmap 补 v2.1.1–v2.1.4 四行 - METHODOLOGY: 修复双重「## 三」编号冲突(ADR→§4,清单→§5,参考文献→§6; 2.5–2.8→3.5–3.8);新增 ADR-4.4(KB ACL fail-closed vs SDB fail-open, 按可逆性定方向)+ ADR-4.5(连接池去重/硬截止/背压) - 交叉引用修正: README §3→§4 ADR、AGENTS §2.2→§3.2、checklist §4 24项→§5 17项 - README 徽章 400+→540+(实际 546 passed / 3 skipped)
42 KiB
DGAgent 设计需求文档
生成时间:2026-07-28 | 状态:需求分析阶段
一、项目概述
DGAgent 是一个围绕地瓜机器人(D-Robotics)RDK 平台的全栈开发 Agent,以 Pi Extension 包形式发布,仅部署在开发者主机端。
一句话定位: 机器人开发者的 AI 搭档——理解 RDK 生态,连接闭源知识,调度专家模型,直达开发板。
二、四大核心需求
需求 1:闭源知识库 MCP 查询 + 鉴权
| 维度 | 描述 |
|---|---|
| 问题 | RDK 的部分文档/算法/配置属于闭源或内部资料,不能直接喂给通用 LLM |
| 方案 | Agent 内置 MCP Client,通过 MCP 协议查询闭源知识库 |
| 鉴权 | 知识库子项级别访问控制,不同用户/角色可见不同内容 |
| 职责 | Agent 负责 MCP Client 对接层,MCP Server + 知识库后续建设 |
关键设计:
- MCP Server URL 和认证 Token 通过环境变量配置
- Agent 工具
dg_kb_search封装 MCP 查询,返回鉴权过滤后的结果 - 支持语义搜索和关键词搜索两种模式
需求 2:地瓜垂类模型路由
| 维度 | 描述 |
|---|---|
| 问题 | 通用模型不擅长机器人开发的長链条任务(硬件配置→驱动适配→算法部署→调试) |
| 方案 | 接入地瓜专用垂类模型,按任务类型智能路由 |
| Key 管理 | 环境变量注入 $DG_API_KEY,Agent 提供 setup 引导用户获取 Key |
路由策略:
| 任务类型 | 路由目标 | 判断依据 |
|---|---|---|
| 通用编程/问答 | 用户默认模型 | 非 RDK 特定任务 |
| RDK 硬件配置 | 地瓜垂类模型 | 涉及 BPU、外设、引脚 |
| 模型编译部署 | 地瓜垂类模型 | OE 工具链、BPU 算子 |
| ROS2 开发调试 | 地瓜垂类模型 | TogetheROS.Bot、topic |
| 长链条端到端任务 | 地瓜垂类模型 | 跨 3+ 子领域的任务 |
实现方式:
extensions/provider.ts通过pi.registerProvider()注册地瓜模型- Agent 的 Skill 中内置路由规则,在任务开始时判断并提示切换模型
- 用户也可通过
/model手动切换
需求 3:嵌入式设备远程调试(SSH 透传)
| 维度 | 描述 |
|---|---|
| 问题 | 代码在主机上写,但运行在 RDK 板卡上,调试需要来回切换 |
| 方案 | Agent 通过 SSH 连接板卡,在板上执行命令、抓取日志、迭代调试 |
| 部署 | 仅主机端安装 DGAgent,板端只需 SSH Server + RDK 标准环境 |
交互模式:
用户: "帮我在 RDK X5 上部署 YOLO 检测,看看摄像头能不能用"
Agent:
┌─ SSH 连接板卡 ──────────────────────────┐
│ 1. $ dmesg | grep video → 检测到 /dev/video0
│ 2. $ ros2 topic list → /camera/image_raw 不存在
│ 3. $ colcon build --packages-select camera_driver
│ 4. $ ros2 launch camera_driver start.launch.py
│ 5. $ ros2 topic echo /camera/image_raw → 有数据! │
└──────────────────────────────────────────┘
→ "摄像头已就绪,YOLO 节点可以订阅 /camera/image_raw"
关键设计:
rdk_board_list— 扫描局域网内的 RDK 设备rdk_ssh_exec— 在指定板卡上执行命令并返回输出rdk_ssh_session— 建立持久会话,支持多轮交互rdk_file_sync— 主机↔板卡文件传输- 命令执行前需用户确认(安全审批)
需求 4:多专家 Agent + 多专家模型调度
| 维度 | 描述 |
|---|---|
| 问题 | 机器人开发横跨感知、控制、部署等多个专业领域,单一 Agent 难以全栈覆盖 |
| 方案 | 主 Agent 作为编排器,将复杂任务拆解后分派给对应专家 Agent + 专家模型 |
专家矩阵(示例):
| 专家类型 | 擅长领域 | 绑定模型 | 触发场景 |
|---|---|---|---|
| 感知专家 | 摄像头、激光雷达、SLAM、目标检测 | 视觉垂类模型 | 传感器配置、模型推理 |
| 控制专家 | 运动规划、PID、IMU、电机驱动 | 控制垂类模型 | 底盘调试、轨迹规划 |
| 部署专家 | OE 编译、模型量化、BPU 部署 | 地瓜垂类模型 | 模型转换、板卡部署 |
| 通用专家 | 代码生成、文档查询、架构设计 | 通用模型 | 非特定领域任务 |
调度流程:
用户输入复杂任务
│
▼
┌──────────────────┐
│ 主 Agent 拆解 │ → 分析任务,拆分为子任务
└──────┬───────────┘
│
├──→ 子任务 A (感知) → 感知专家 + 视觉模型 → 结果 A
├──→ 子任务 B (控制) → 控制专家 + 控制模型 → 结果 B
├──→ 子任务 C (部署) → 部署专家 + 地瓜模型 → 结果 C
│
▼
┌──────────────────┐
│ 主 Agent 汇总 │ → 整合子结果,输出完整方案
└──────────────────┘
实现方式:
- Pi Tool
dg_dispatch_expert(expertType, task)负责调度 - 专家通过不同的 System Prompt + 模型组合实现
- 支持串行(依赖型子任务)和并行(独立型子任务)两种调度模式
三、整体架构
┌─────────────────────────────────────────────────────────┐
│ DGAgent (Pi Extension) │
│ 仅部署在开发者主机 │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Skills(领域知识 SOP) │ │
│ │ rdk-project-init / rdk-model-workflow / │ │
│ │ rdk-sensor-integration / rdk-debug-workflow │ │
│ └────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌────────────────────┴─────────────────────────────┐ │
│ │ Orchestrator(编排调度核心) │ │
│ │ · 任务分解 · 专家匹配 · 模型路由 · 汇总 │ │
│ └───┬──────────┬──────────┬──────────┬─────────────┘ │
│ │ │ │ │ │
│ ┌───┴───┐ ┌───┴───┐ ┌───┴───┐ ┌───┴──────┐ │
│ │ MCP │ │ Model │ │ SSH │ │ Expert │ │
│ │Client │ │Router │ │Tools │ │Dispatcher│ │
│ └───┬───┘ └───┬───┘ └───┬───┘ └────┬─────┘ │
│ │ │ │ │ │
└──────┼─────────┼─────────┼───────────┼──────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────┐ ┌────────┐ ┌────────┐ ┌──────────┐
│ MCP Server│ │ DG API │ │RDK 板卡│ │ 专家模型 │
│ (闭源知识库)│ │(垂类模型)│ │(SSH) │ │ API │
└───────────┘ └────────┘ └────────┘ └──────────┘
四、项目结构
dgagent/
├── package.json # Pi 扩展包元数据
├── tsconfig.json # TypeScript 配置
├── extensions/
│ ├── provider.ts # 地瓜垂类模型 Provider 注册
│ ├── tools/
│ │ ├── mcp-client.ts # MCP 知识库查询工具
│ │ ├── ssh-executor.ts # SSH 远程执行工具
│ │ └── expert-dispatcher.ts # 专家调度工具
│ └── system-prompt.ts # 领域身份注入
├── skills/
│ ├── rdk-project-init/ # 项目初始化工作流
│ ├── rdk-model-workflow/ # 模型部署工作流
│ ├── rdk-sensor-integration/ # 传感器集成工作流
│ └── rdk-debug-workflow/ # 调试诊断工作流
├── prompts/
│ ├── requirements.md # 原始需求记录
│ └── rdk-setup.md # /rdk-setup 初始化命令
└── DESGIN.md # 本文档
五、需求确认结论
| # | 问题 | 结论 |
|---|---|---|
| 1 | MCP Server 规格 | Wikihub — LLM Wiki + 原生 MCP + glob 文件级 ACL,支持 public/partner/internal 分层对外开放 |
| 2 | 地瓜模型 API | 开发中,同时兼容 OpenAI 和 Anthropic 协议。通过 pi.registerProvider() 注册,端点 + model ID 通过 $DG_* 环境变量注入 |
| 3 | 专家模型 | 地瓜统一 API 管理体系,不同 model ID 区分专家(dg-perception / dg-control / dg-deploy / dg-general) |
| 4 | SSH 安全审批 | 高风险命令(sudo/rm/systemctl/apt 等)逐条确认,读操作和普通命令放行 |
| 5 | 板卡发现 | 纳入初始化子 Agent,自动扫描(mDNS)+ 手动 IP 双模式 |
| 🆕 | 初始化子 Agent | /dg-setup 一键引导:板卡发现 → Key 申请 → MCP 接入 → SSH 初始化 → 环境校验 |
六、Unix 设计原则审视
Unix 审视最终结论(2026-07-28)
核心洞察:Agent 层才是单一职责的正确粒度
- ❌ "单 Agent MVP" 在此项目不适用——初始化、SSH 调试、模型部署、感知调试是本质不同的能力域,不是同一流程的微步骤
- ✅ 每个 Agent 一个职责 = Unix "Do One Thing Well" 在 Agent 层面的最彻底贯彻
- ✅ Orchestrator 只做路由,不干活——同样是一个职责
- ✅ Agent 内部的工具链本身也是原子化的小工具
架构定型:Orchestrator-Worker + 专家 Agent 矩阵
用户(唯一入口)
│
"我想在 RDK X5 上部署 YOLO"
│
▼
主路由 Agent (Orchestrator)
· 理解用户意图
· 分解为子任务
· 按依赖编排执行
· 汇总结果返回
│
┌──────────────┼──────────────┐
▼ ▼ ▼
初始化 Agent SSH 调试 Agent 模型部署 Agent
"让系统就绪" "板卡远程执行" "编译→部署"
│ │ │
内部工具链: 内部工具: 内部工具:
· board-discover · ssh-exec · oe-compile
· key-setup · log-capture · bpu-deploy
· mcp-connect · file-sync · model-verify
· ssh-init
· env-check
│ │ │
└──────────────┼──────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
感知 Agent 控制 Agent 通用 Agent
"传感器/视觉" "运动/执行器" "代码/文档/知识"
关键设计原则:用户只需描述目标,不需要知道 Agent 矩阵
- 用户面对的是一个对话入口(主路由)
- 用户说"部署 YOLO"→ Orchestrator 自动编排:初始化 → SSH → 模型部署
- 用户不需要知道有几个 Agent、每个 Agent 能做什么
- 复杂度对内暴露(Agent 矩阵),对外隐藏(单一对话界面)
- 对齐 "Control Plane as a Tool" 模式:Agent 只看到控制面,实现细节透明
User Journey 设计
安装与首次启动
$ pi install @yusen/dgagent
✓ DGAgent 已安装。下次启动 pi 时自动加载。
── 下次启动 pi ──
[Agent] 你好!我是 DGAgent,地瓜机器人开发助手。
检测到:
• 地瓜 API Key — 未配置(部分功能暂不可用)
• 知识库 — 未连接(搜索受限)
板卡连接会在部署时按需检查,现在可以先开始设计。
→ 🧭 新手引导 — 一步步带你完成配置,再试试示例项目
→ 💻 自由模式 — 跳过引导,直接开始(适合有经验的开发者)
设计原则:板卡连接按需触发,不是初始化步骤
开发流程天然是先设计编码后部署调试。板卡在"编译→部署"环节才需要,不应作为首次启动的前置条件。Agent 在 SSH 操作前做连接诊断即可。
新手模式 vs 自由模式
本质是两套 System Prompt:
| 新手 Prompt | 自由 Prompt | |
|---|---|---|
| 指导密度 | 高——每个步骤解释 why | 低——只输出结果 |
| 主动程度 | 主动引导、推荐下一步并展开说明 | 完成后给出 2-3 个轻量下一步选项,不展开 |
| 容错处理 | 宽容 + 教学式解释 | 简洁报错 + 等指令 |
| 示例展示 | 推荐示例项目 | 不主动推荐 |
新手模式的核心定位:不是教会 RDK,是教会嵌入式工程方法
新手模式不只是教"怎么用 RDK",更是把嵌入式开发的一般工程原则通过 RDK 这个载体教给用户:
- 生成代码时解释为什么这样分层(
hal/→drivers/→app/) - 写代码前先讨论数据流("摄像头产生什么?谁消费它?怎么通信?")
- 当用户想走捷径时,温和地解释为什么这是坏习惯("你可以把检测逻辑直接写在 camera_driver 里,但这违反 SRP——以后换摄像头型号时你要改两个地方")
- 编译失败时不只报错,还要教怎么排查("先检查 CMakeLists.txt 的依赖声明,再看头文件路径,嵌入式开发里这种问题 80% 是路径不对")
- 主动引入工程概念:SRP、DRY、HAL、数据驱动、先 Profile 再优化——但不灌输术语,而是展示行为
新手 Prompt 的额外约束:
- 每生成一次代码,至少解释一个工程决策的理由
- 用户做不规范操作时,不禁止但提醒,并说明"等你熟练后再回头看会觉得这是个好习惯"
- 不预设用户懂任何术语,第一次提到 SRP/HAL/DRY 时附带一句话解释
动态模式切换
- Agent 始终在角落显示当前模式:
🧭 新手模式 | [切换到 💻] - Agent 自动评估用户问题质量——如果是基础/教学性问题,主动建议切到新手模式
- 用户可随时手动切换
- 模式不是一次选择,是持续状态
自由模式下的连接诊断
- 嵌入式环境不可靠——板卡可能断电、USB 松了、IP 变了
- 任何 SSH 操作前必须做连通性检查
- 失败时主动排查:
- 板卡是否在线?(ping)
- SSH 服务是否运行?(port scan)
- 密钥是否过期?
- 诊断结果呈现给用户,由用户决定下一步
嵌入式高危操作分级确认
| 风险等级 | 操作 | 后果 | 确认要求 |
|---|---|---|---|
| 🔴 致命 | 刷机/烧录固件(dd、flashcp、fastboot flash) |
变砖,不可逆 | 双重确认 + 显示目标设备 |
| 🔴 致命 | 修改 bootloader / 分区表 | 无法启动 | 双重确认 |
| 🔴 致命 | 擦除 eMMC/NAND(flash_erase) |
数据全丢 | 双重确认 |
| 🟠 严重 | 修改内核启动参数(cmdline) |
系统不稳定 | 单次确认 + 显示修改内容 |
| 🟠 严重 | 修改设备树(.dtb/.dts) |
硬件不工作 | 单次确认 |
| 🟠 严重 | GPIO/引脚状态改写 | 外设短路/损坏 | 单次确认 |
| 🟠 严重 | BPU 频率/电压调整 | 芯片过热 | 单次确认 |
| 🟡 警告 | rm -rf 关键路径、systemctl disable、网络配置、reboot/shutdown |
功能缺失/断连 | 提示确认 |
确认交互示例:
🔴 致命操作 → 双重确认:
[Agent] ⚠️ 高危操作:刷写固件
目标:RDK X5 @ 192.168.1.105
命令:dd if=firmware.bin of=/dev/mmcblk0
后果:不可逆。请输入 "yes, I understand the risk"
🟠 严重操作 → 显示修改内容后确认
🟡 警告操作 → 提示确认即可
#### 新手模式示例项目 [TODO]
- 具体示例列表待后续设计
#### 部署到板卡场景 [TODO]
- 板卡连接按需触发时的交互流程待设计
### Workflow/Agent 编排逻辑
#### 嵌入式开发也是软件开发
DGAgent 帮助用户开发的是嵌入式软件。**在板卡交互之前,99% 的工作是标准软件开发。** Agent 必须内建以下工程原则。
**通用软件工程原则(Agent 生成代码时必须遵循):**
| 原则 | 含义 | DGAgent 中的应用 |
|------|------|-----------------|
| SRP | 单一职责——一个模块只做一件事 | 生成的每个 ROS2 节点一个职责 |
| OCP | 对扩展开放,对修改关闭 | 生成可继承的基类,不直接改核心逻辑 |
| DRY | 不重复自己 | 公共逻辑抽取为库,不复制粘贴 |
| KISS | 保持简单 | 默认方案选最简单的,不引入过度抽象 |
| YAGNI | 你不会需要它 | 不生成"将来可能用到"的代码 |
| LoD | 最少知识原则 | 模块之间只通过接口通信 |
**嵌入式特有工程原则(Agent 指导项目结构时必须遵循):**
| 原则 | 含义 | DGAgent 中的应用 |
|------|------|-----------------|
| HAL | 硬件抽象层——应用代码不直接操作硬件寄存器 | 生成的代码必须分 `hal/` 和 `app/` 层 |
| 数据驱动 | "没有硬件,只有数据流"——先设计数据,再设计处理 | 项目结构以数据流为中心,不以上电顺序为中心 |
| 桌面先行 | 能在桌面测试的先在桌面测,硬件只在最终验证 | CI 在桌面上跑单元测试,HIL 在板卡上夜间跑 |
| 早集成 | 不要等到最后才上板——尽早、频繁集成 | 每次编译后提示"要部署到板卡验证吗?" |
| 先 Profile 再优化 | 用数据说话,不靠直觉优化 | 提示用户先用 `perf`/`top` 定位瓶颈 |
| 自动化 | 烧录、调试、重置等重复操作全部脚本化 | Agent 自动生成部署脚本,不让人工重复操作 |
**Agent 的行为约束:**
- 生成的代码必须有清晰的分层:`hal/`(硬件相关)→ `drivers/`(驱动)→ `app/`(业务逻辑)
- 生成后主动检查:`colcon build` 是否通过?`ros2 run` 是否正常?
- 部署前提示"先在桌面验证?还是直接上板?"
- 不生成过度抽象的代码——嵌入式资源有限,KISS 优先于 DRY
#### 路由策略:三层递进
用户任务 │ ▼ ① 规则匹配 ──命中──→ 直接路由到专家列表 │ 未命中 ▼ ② 知识库检索 ──置信度高──→ 基于历史相似任务路由 │ 低置信度 / 无结果 ▼ ③ LLM 推理 ──→ 分析意图,匹配专家
| 层 | 方式 | 速度 | 可靠性 | 适用 |
|---|---|---|---|---|
| ① | 确定性规则 | 最快 | 最高 | 已知任务模式("部署YOLO"→初始化+SSH+部署) |
| ② | MCP 知识库 | 快 | 高 | 知识库中有相似案例 |
| ③ | LLM 推理 | 慢 | 中 | 全新/复杂/模糊任务 |
**规则示例:**
```python
ROUTING_RULES = {
"部署": ["初始化", "SSH", "模型部署"],
"编译模型": ["模型部署"],
"调试摄像头": ["SSH", "感知"],
"调试电机": ["SSH", "控制"],
"创建项目": ["通用"],
# ...
}
数据传递:混合模式
| 方式 | 描述 | 适用 |
|---|---|---|
| A. 文件系统直通 | Agent 直接读写项目目录,Orchestrator 只传路径 | 代码文件、编译产物 |
| C. 共享上下文 | Orchestrator 维护元数据对象(路径、状态、配置) | 板卡 IP、模型路径、阶段状态 |
- 代码和编译产物走文件系统——Agent 产出到约定目录,下游 Agent 从该目录读取
- 环境信息走共享上下文——板卡 IP、模型 ID、配置变量由 Orchestrator 注入
专家调用机制:三种方式混合
| 机制 | 适用场景 | 判断条件 | 示例 |
|---|---|---|---|
| 工具调用(Pi Tool) | 单步操作,确定性,不需要推理 | 操作 < 1 秒,输入输出明确 | 刷机、colcon build、读 sensor |
| 子会话(独立 Agent) | 多步推理,需要专注,产出代码 | 需要多轮思考,产出 >= 代码文件 | 写驱动、设计架构、调试 |
| Prompt 切换 | 用户中途改变方向,模式切换 | 任务上下文变更 | "不写驱动了,先查摄像头" |
SDB Gate 设计
每个 LLM→系统边界必须插入 Gate。Gate 是确定性代码,不依赖 LLM 判断。
| Gate | 边界 | 设计 | 依据 |
|---|---|---|---|
| 路由 Gate | 用户 NL → 专家列表 | 三层递进(规则优先),LLM 路由需验证专家 ID 在白名单 | SDB 规则优先 |
| 输出 Gate | 专家输出 → Orchestrator | 输出必须符合预定义 schema,缺失/格式错误 → 拒绝采纳 | 12-Factor #8 |
| 参数 Gate | LLM → 工具调用 | TypeBox 强类型 + 路径白名单 + 参数范围校验 | Tool Poka-yoke |
| 代码 Gate | LLM 生成 → 写入文件 | colcon build + 静态分析,跑不过不交付 |
桌面先行原则 |
| 鉴权 Gate | MCP 查询 → Agent | 结果过滤(剔除无权限内容)+ token 截断 | Context Engineering |
| 编译 Gate | 构建输出 → 成功/失败判定 | 正则匹配 exit code,不靠 LLM 判断 | KISS 确定性 |
| 确认 Gate | 用户回复 → Agent 行动 | 明确字符串匹配("yes" / "好"),非模糊判断 | Least Surprise |
| 模式 Gate | 问题评估 → 模式切换建议 | 信心阈值 > 0.8 才主动建议 | — |
| 高危 Gate | 命令 → 板卡执行 | 三级确认(致命/严重/警告) | ✅ 已设计 |
可观测性设计
行业标准:OpenTelemetry GenAI Semantic Conventions
DGAgent 采纳 OpenTelemetry + OpenInference 语义约定,不绑定特定厂商。
Span 层级:
Session(一次对话,session.id)
└── Trace(一个任务,"部署摄像头检测")
├── Agent Span(general-agent)
│ ├── LLM Span(调用 dg-general-v1)
│ │ ├── input_messages, output, token_count
│ │ └── model, temperature, cost
│ ├── Tool Span(create_ros2_package)
│ │ └── tool.name, args, result, latency
│ └── Tool Span(write_file)
├── Guardrail Span(高危命令审批 Gate)
│ └── check_result: pass/fail
├── Agent Span(ssh-agent)
│ ├── Tool Span(ssh_exec)
│ └── LLM Span
└── Chain Span("阶段 1:开发")
└── 包裹上方的 general-agent 子树
每类 Span 的关键属性:
| Span 类型 | 标准属性(OpenInference) | DGAgent 示例值 |
|---|---|---|
| Session | session.id |
conv_20260728_001 |
| Trace | trace.name |
"部署摄像头检测到 RDK X5" |
| Agent | agent.name、agent.id |
general-agent、ssh-agent |
| LLM | llm.model、llm.input_messages、llm.output、llm.token_count |
dg-general-v1、1200 tokens |
| Tool | tool.name、tool.args、tool.result、tool.latency |
ssh_exec、"colcon build"、35ms |
| Chain | chain.name |
"阶段 1:开发"、"阶段 2:部署" |
| Guardrail | guardrail.check_result |
pass / fail / user_confirmed |
实现方案:
- Pi Extension 中嵌入 OpenTelemetry SDK
- Agent/Tool/LLM 调用点自动创建对应 span
- 后端可选 Phoenix(开源免费)或 Langfuse(更多功能)
- 每条 trace 可在 UI 中回放,定位失败步骤
混合编排示例:
任务: "部署摄像头检测"
阶段 1:开发(子会话)
通用 Agent ──→ 子会话,写 camera_driver 代码
模型部署 Agent ──→ 子会话,OE 编译
阶段 2:部署(工具调用 + 子会话)
初始化 Agent ──→ 工具调用:板卡发现
SSH Agent ──→ 子会话:上传 + 编译 + 启动
中途切换(Prompt 切换):
[用户] "等等,先检查 SPI 总线"
[Agent] 保存 camera_driver 进度 → 切换到感知 Prompt
七、Agent 设计最佳实践(方法论参考)
来源:Anthropic "Building Effective Agents"、Anthropic "Context Engineering"、Anthropic "Multi-Agent Research System"、Anthropic "Writing Effective Tools"、OpenAI "Practical Guide to Building Agents"、Google Cloud "Agent Design Patterns"、12-Factor Agent、Stanford SDB、Control Plane as a Tool、Production-Grade Agentic AI Workflows
方法论 1:Start Simple — 先从最简单方案开始
来源: Anthropic + OpenAI + Google Cloud(三方共识)
"Success isn't about building the most sophisticated system. Start with simple prompts, add multi-step only when simpler solutions fall short."
核心主张: 能用单次 LLM 调用解决的就不要上 Agent Loop,能单 Agent 的就不要上多 Agent。每加一层复杂度都需要明确的性能提升来 justify。
对 DGAgent 的启示:
- ✅ 我们的整体方向是对的多 Agent 编排,因为机器人开发天然跨多个子领域
- ⚠️ 但第一版应该只做一个 Agent + 全量工具,验证单 Agent 能否完成典型任务后,再考虑拆分专家
- ⚠️ 不需要一开始就把 5 个专家都建出来——从最痛的一个场景开始
方法论 2:Workflow vs Agent 区分
来源: Anthropic(最核心的架构区分)
| Workflow | Agent | |
|---|---|---|
| 控制流 | 预定义代码路径 | LLM 自主决定 |
| 适合场景 | 步骤可预测的固定流程 | 开放性任务,步数不可预知 |
| 成本 | 低(少 LLM 调用) | 高(多轮推理) |
| DGAgent 示例 | 模型编译部署流水线 | 开发板故障诊断 |
对 DGAgent 的启示:
- 模型 OE 编译 → 部署这条链是固定步骤,应该走 Workflow(确定性),而非让 LLM 自己探索
- 板卡故障诊断是开放性问题,走 Agent Loop
- 应该混合使用:确定性 Workflow 处理已知流程,Agent 处理探索性任务
方法论 3:工具设计 = Agent 能力的上限
来源: Anthropic "Writing Effective Tools"(花在工具优化上的时间比 prompt 还多)
核心原则:
- 工具描述比工具名字重要得多——像给初级工程师写 docstring
- 一个概念一个工具,不要重叠(两个工具都能回答同一个问题 = 错误调用)
- 返回值只包含高信号信息,去掉 uuid/mime_type 等技术噪声
- 用
response_format枚举让 Agent 控制输出详细程度 - Poka-yoke(防呆设计): 修改参数让错误更难发生(如强制绝对路径)
对 DGAgent 的启示:
rdk_ssh_exec的工具描述必须非常详细,包括示例命令和常见错误- 板卡发现和 SSH 执行不应有功能重叠
- 每个工具的输出应该先过一遍精简——板卡信息不需要返回完整的
lshw
方法论 4:SDB — 随机-确定性边界
来源: Stanford 论文(71% 的 Agent 故障发生在这个边界)
核心概念: LLM 的随机输出 → 确定性系统动作之间的接口,是最高风险区域,必须作为一等架构元素设计。
六种运行时架构模式:
- P1 层级委派(Orchestrator → Specialist)
- P2 Scatter-Gather + Saga(并行 + 补偿回滚)
- P3 事件驱动(append-only log)
- P4 Supervisor + Gate(监督 + 策略门)
- P5 共享状态机(compare-and-swap)
- P6 Human in the Loop
对 DGAgent 的启示:
- ✅ SSH 命令执行已经有 P6(高风险命令人工确认)和 P4(审批门)
- ⚠️ 专家调度的输出需要 P4 Gate——专家返回的结果在被主 Agent 采纳前,应过一层验证
- ⚠️ 模型路由决策本身也是一个 SDB——应该让确定性路由规则而非 LLM 自己判断
方法论 5:上下文工程(Context Engineering)
来源: Anthropic + Andrej Karpathy
"Context engineering = curating the smallest set of high-signal tokens that maximize desired outcomes."
关键策略:
- 渐进式披露(progressive disclosure):Agent 逐步探索,每次只加载需要的上下文
- Compaction:超长对话压缩摘要后重置上下文窗口
- 结构化笔记(agentic memory):Agent 主动写 NOTES.md 跨轮持久化
- 子 Agent 架构:子 Agent 深入探索后只返回 1000-2000 token 的浓缩摘要
对 DGAgent 的启示:
- ✅ SSH 会话输出天然需要 compaction——板卡日志可能很长,需要 Agent 主动总结而非全部塞进上下文
- ⚠️ MCP 知识库查询后应让 Agent 记录笔记,而非每次重新搜
- ✅ 子 Agent 架构和我们的专家调度完全吻合——专家深入工作后返回摘要
方法论 6:12-Factor Agent
来源: 12-Factor App 向 Agent 的延伸
最相关的几条:
| # | Factor | 含义 | DGAgent 适用性 |
|---|---|---|---|
| 1 | NL → Tool Calls | Agent 的职责是把意图翻译成函数调用,不是聊天 | ✅ 核心设计 |
| 4 | Tools as Structured Outputs | 工具参数必须强类型(Zod/JSON Schema) | ✅ Pi TypeBox |
| 7 | Contact Humans via Tools | "请求人类帮助"应该是一个工具 | ⚠️ SSH 审批已有,但应该通用化 |
| 8 | Own Your Control Flow | 不要让 LLM 决定控制流,用状态机 | ⚠️ 模型路由、高危命令拦截应该走确定性代码 |
| 9 | Compact Errors into Context | 错误是信息,喂回 LLM 自纠正 | ✅ SSH 命令失败后自动重试 |
| 10 | Small, Focused Agents | 不要 God Agent | ✅ 专家拆分方向正确 |
| 12 | Stateless Reducer | (State, Event) → NewState |
⚠️ Pi Agent 天然有状态,但工具应尽量无状态 |
方法论 7:Multi-Agent Orchestrator-Worker
来源: Anthropic Research System + OpenAI Manager Pattern
核心经验(来自 Anthropic 构建多 Agent 研究系统的教训):
- 教 Orchestrator 如何委派——每个子 Agent 需要明确的目标、输出格式、工具指导和任务边界
- 按查询复杂度伸缩投入——简单任务 1 Agent + 3-10 次工具调用,复杂研究 10+ Agent
- 工具设计和选择是关键——Agent 用错工具比用错模型更致命
- 让 Agent 自我改进——用 Agent 测试和重写工具描述,降低了 40% 任务完成时间
- 先广后窄——搜索策略:先短宽查询探索,再逐步收窄
- 并行工具调用——3-5 个子 Agent 并行 + 每个子 Agent 内 3+ 工具并行,复杂查询时间降低 90%
对 DGAgent 的启示:
- ⚠️ 我们的专家调度目前是黑盒——应该让主 Agent 显式描述每个子任务的目标和边界
- ✅ 感知/控制等专家天然适合并行
- ⚠️ 需要给 Agent 明确的"伸缩规则"——感知任务不需要部署专家参与
方法论 8:Control Plane as a Tool
来源: 学术论文(将工具编排封装为单一工具接口)
核心思想: Agent 只看到一个 control_plane 工具,后端的路由、验证、工具选择对 Agent 透明。
对 DGAgent 的启示:
- ⚠️ 我们目前的设计是 Agent 直接看到所有工具。是否应该引入 Control Plane 层?
- 适用场景:当工具数量 > 15 或工具间存在大量重叠时
八、综合评估:DGAgent 当前设计 vs 业界最佳实践
| 维度 | 当前设计 | 业界共识 | 状态 |
|---|---|---|---|
| 复杂度起点 | 多 Agent 编排 | "Start Simple" → 单 Agent MVP | ✅ 已决议:DGAgent 的子领域天然独立,多 Agent 是其正确粒度,非过度设计 |
| Workflow/Agent 混合 | 全部走 Agent Loop | 确定性流程走 Workflow | ⚠️ 模型部署链应改为确定性 |
| 工具设计 | 还没开始 | 工具描述是最高杠杆 | 🔴 下一阶段重点 |
| SDB 防护 | 仅 SSH 有审批 | 每个 LLM→系统边界都应有 Gate | ⚠️ 专家输出、模型路由需要 Gate |
| 上下文管理 | 未设计 | Compaction + 子 Agent 摘要 | ⚠️ 长 SSH 会话需要 compaction |
| 控制流 | LLM 自主 | 关键路径代码控制 | ⚠️ 路由决策应走确定性规则 |
| 可观测性 | 未设计 | 从 Day 1 开始 | 🔴 需要 tracing |
| 用户接口 | 多 Agent 暴露 | 单一入口,隐藏复杂度 | ✅ 已决议:Orchestrator 是唯一用户入口 |
核心结论:三个最需要改进的方向——
- 工具描述投入 > Prompt 投入(花更多时间打磨工具接口,这是最高杠杆)
- 关键控制流走确定性代码(模型路由、高危命令拦截、输出验证不靠 LLM 决定)
- 从 Day 1 建立可观测性(tracing、per-tool-call logging)
九、架构演进方向
9.1 核心洞察
DGAgent 目前的工具体系本质上是"一个刚入职的工程师"——有基本技能(SSH、SFTP、板卡发现、风险判断),但每次遇到任务都要从零开始推理"先调哪个工具、再调哪个工具"。
脚本化自进化的定义:让 Agent 把重复使用的工具调用序列凝固为确定性脚本,从"每次都要 LLM 推理多步"变为"LLM 调一次复合工具"。
9.2 核心类比:工程师的脚本工具箱
一个人类嵌入式工程师的成长: dgagent 的对应层:
刚入职:每次手动 ssh → 查 topic LLM 原始工具调用
→ 解析输出 → 再 ssh (3-5 轮工具调用,LLM 推理每一步)
做了 5 次以后:写成 check_camera.sh lib/workflows/camera-check.ts
下次 ./check_camera.sh 下次调 dg_workflow_camera_check
(1 秒 vs 30 秒,零失误) (1 轮 vs 3 轮,零推理错误)
脚本越来越多:积累了个工具箱 lib/workflows/ 工具库
~/scripts/ 拷给新人就能用 其他 Agent 框架可通过 MCP 调用
最好的脚本:写成团队工具了 注册为一级复合工具
make dev-setup LLM 不再需要知道内部步骤
关键洞察: 脚本不是"为更快"——是因为做多了就忘了细节,脚本是外化的记忆。对 Agent 也一样:Session N 能正确地走完 3 步,Session N+10 可能漏掉中间的 ros2 topic echo --once。脚本化 = 防止退步。
9.3 四层架构模型
Layer 0: 基础能力(原子操作)—— v0.3 ✅
lib/ssh.ts → 工程师会 ssh
lib/sftp.ts → 工程师会传文件
lib/discovery.ts → 工程师知道板卡在哪
lib/risk.ts → 工程师知道什么命令危险
↑ "刚毕业的工程师",有基本技能但没有经验
Layer 1: 工作流(固化的经验)—— v0.4 启动
lib/workflows/ → 工程师的脚本工具箱
├── camera-check.ts
├── push-and-verify.ts
├── safe-exec.ts
└── board-health.ts
↑ "干了三年的工程师",常见任务不需要查文档
Layer 2: 接入层(能力暴露方式)—— v0.4 同步
tools.ts → 和其他工程师协作(LLM → 工具)
cli/ → 自己在终端快速操作
mcp/ → 被其他团队的系统调用
↑ 同一个能力,不同场景用不同方式调用
Layer 3: 自进化(学习能力)—— v1.0
observer/ → 观测自己的行为(通用工具调用日志)
detector/ → 识别重复模式(序列模式挖掘)
generator/ → 生成新脚本(代码生成)
9.4 成长的阶段路线
| 版本 | 做什么 | 类比 |
|---|---|---|
| v0.3 ✅ | 有基本技能(lib/),全靠 LLM 现场推理 | 刚入职的新人 |
| v0.4 | 手写 3-5 个最高频 workflow,跑通闭环。提取 lib/ | 新人的前三个脚本 |
| v0.5 | 脚本增多,引入观测层——统计哪个 workflow 被用得最多 | 开始整理工具箱 |
| v0.6 | 从观测数据中识别新脚本候选。生成靠人工拍板 | 师傅建议"你这个也可以脚本化" |
| v1.0 | 全自动闭环:检测 → 生成 → 注册。但生成的脚本标记为 auto(信任等级最低) | 会自己总结经验的工程师 |
9.5 信任分级(关键设计)
不所有脚本平等。安全相关的决策必须可审计:
| 等级 | 标记 | 来源 | 行为 |
|---|---|---|---|
| trusted | 人工编写 + review 过 | 手写 workflow | 直接执行,无额外确认 |
| observed | 自动生成,已安全执行 N 次 | detector → generator | LLM 调用无需确认,但日志标注 auto |
| auto | 自动生成,未经过安全验证 | detector → generator | LLM 调用前需确认关键步骤 |
这与 DESIGN.md §嵌入式高危操作分级确认(SDB Gate)对齐——fatal 命令无论脚本等级如何都不可跳过。
9.6 与设计原则的对应
| 原则 | 如何体现 |
|---|---|
| SDB 边界(METHODOLOGY §3.3) | 脚本化 = 把 LLM 的随机行为迁移到确定性代码 |
| Workflow vs Agent(METHODOLOGY §3.1) | 自进化 = 自动判断"Agent 行为应变成 Workflow" |
| Tool Design First | 生成的脚本也是工具,要满足同样的 7 条设计原则 |
| 12-Factor #8(Own Your Control Flow) | 逐步从 LLM 手里拿回控制流 |
| Composability(Unix) | 脚本 = lib/ 基础组件的组合 |
| Poka-yoke(Shingo) | 信任分级 + SDB Gate 双重保险 |
十、下一步
路线标签(v0.x/v1.0)与包版本(v1.x)已错位:从 v1.2 起以包版本为执行主线,DESIGN 标签仅作设计对齐参考。本表为 2026-08-14 评审确定的扩展路线图。
已完成的路线项
- v0.4 ✅:提取
lib/(extensions/utils.ts的业务逻辑独立为可编程库),手写 3-5 个高频 workflow - v0.4 ✅:接入 MCP Client(Wikihub),
dg_kb_search真实化 - v0.5 ✅:引入观测层 + 模型路由规则表(观测层 = v1.2.0
/dg-usage;规则表 = v0.5/v0.6 三层路由) - v0.6 ✅(部分):专家调度真实化(v0.6.0);模式检测→人工拍板(= 下方 v1.4 Detector,未完成)
- v1.0 ✅:Full SDB Gates 9/9(v1.0/v1.1)+ OpenTelemetry(v1.0)+ 全自动闭环(= v2.0/v2.1,执行载体跑通)
扩展路线图(包版本,2026-08-14)
| 版本 | 主题 | 对齐 | 关键交付 |
|---|---|---|---|
| v1.3 ✅ | 观测层进阶 | §9.4 v0.5 延伸 | /dg-usage 维度过滤(board/since)+ 失败率 + 趋势 + --json 导出(detector 数据源) |
| v1.4 ✅ | Detector:脚本候选识别 | §9.4 v0.6 | lib/detector.ts 序列模式挖掘(A→B→C ≥3 次)+ 候选评分(频率×长度,失败率仅展示——v2.1.1 起失败不再加分,走 KB 草稿)+ /dg-suggest 人工拍板 + dgagent-candidates.json |
| v1.5 ✅ | Generator:脚本生成 + 信任分级 | §9.5 | 从候选生成 workflow 骨架(lib/workflows + 工具注册 + 单测模板);trusted/observed/auto 注册表;auto 需确认关键步骤、observed 安全执行 N 次升级;生成脚本过 typecheck+模板单测才注册(代码 Gate 前置) |
| v1.6 ✅ | Layer 2 接入层:CLI + MCP 服务端 | §9.3 Layer 2 | cli/ 终端命令(无需 Pi);mcp/ workflow 暴露为 JSON-RPC over HTTP 服务端(与 dg_kb_search MCP client 对称) |
| v2.0 ✅ | 全自动闭环 | §9.4 v1.0 + §9.6 | observer→detector→generator 自动串联;自动生成→模板测试→注册 auto;观测驱动 KB 沉淀(失败经验 → Wikihub 文章候选) |
| v2.1 ✅ | 执行载体 + 信任阶梯跑通 | §9.5 | lib/runner.ts runRegisteredWorkflow + dg_workflow_run:注册 workflow 真实执行,安全执行自动推进 auto→observed→trusted(补 v2.0 死路);logCommandIo 命令输出落 session log(§3.4 不变量) |
| v2.1.1 ✅ | review 调整 | — | Detector 评分失败率不再加分(失败经验走 KB 草稿);参数解析收进 lib(命令/CLI 共用);测试弱断言升级(smoke/auditLogId/telemetry);死代码清除 |
| v2.1.2 ✅ | 项目 review 批次一 | — | MCP 服务回环绑定 127.0.0.1;sftpPush 流式化(大文件不整体驻留内存);路由 provenance 修正(M2);engines/CLI 版本守卫(M5);Detector 语义标注(M4) |
| v2.1.3 ✅ | 项目 review 批次二 | — | 确认审计诚实化 attestedBy(H1);severe 正则写上下文匹配(M1);执行后日志失败不再吞结果(M3) |
| v2.1.4 ✅ | 二轮加固批次 | — | 连接池并发安全(busy 引用计数 + 同板卡在途去重);exec SIGTERM→SIGKILL 硬截止 + 输出背压(50KB cap);build-verify 注入防护(unicode 同形字 + 包名白名单);MCP ACL fail-closed(MCP_ERR_ACL_UNKNOWN);路由 ASCII 词边界(CJK 安全);runner 逐命令 SDB 审计 + board_id 一致性守卫;exec_error 审计动作;--since 共享校验 SinceParseError;模式恢复容错 |
| v2.1+ | 平台化(远景) | §9 之外 | 多板卡批量编排;交付闭环(推送→build-verify→自动回滚);workflow 共享市场;生成脚本沙箱 + 签名 |
贯穿原则:每版本 = 功能 + 测试(journey→test 一一对应)+ 文档(AGENTS/SESSION/README)+ typecheck/npm test 双绿 + 确定性优先(detector/generator 用规则+模板,LLM 仅在评分辅助可选)。
执行顺序说明:v1.3 是 v1.4 Detector 的数据源(维度过滤 + 失败率 + JSON 导出),v1.4 产出 v1.5 生成器的输入——按顺序做,闭环最顺。