DGAgent/DESIGN.md
qinyusen 94b55e65e0 docs: v2.1.4 — 文档漂移补齐:架构/测试/设计/方法论与代码对齐 + ADR 4.4/4.5 + 章节编号修复
- 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)
2026-08-18 10:46:24 +08:00

42 KiB
Raw Permalink Blame History

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 研究系统的教训):

  1. 教 Orchestrator 如何委派——每个子 Agent 需要明确的目标、输出格式、工具指导和任务边界
  2. 按查询复杂度伸缩投入——简单任务 1 Agent + 3-10 次工具调用,复杂研究 10+ Agent
  3. 工具设计和选择是关键——Agent 用错工具比用错模型更致命
  4. 让 Agent 自我改进——用 Agent 测试和重写工具描述,降低了 40% 任务完成时间
  5. 先广后窄——搜索策略:先短宽查询探索,再逐步收窄
  6. 并行工具调用——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 是唯一用户入口

核心结论:三个最需要改进的方向——

  1. 工具描述投入 > Prompt 投入(花更多时间打磨工具接口,这是最高杠杆)
  2. 关键控制流走确定性代码(模型路由、高危命令拦截、输出验证不靠 LLM 决定)
  3. 从 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 评审确定的扩展路线图。

已完成的路线项

  1. v0.4 ✅:提取 lib/(extensions/utils.ts 的业务逻辑独立为可编程库),手写 3-5 个高频 workflow
  2. v0.4 ✅:接入 MCP Client(Wikihub),dg_kb_search 真实化
  3. v0.5 ✅:引入观测层 + 模型路由规则表(观测层 = v1.2.0 /dg-usage;规则表 = v0.5/v0.6 三层路由)
  4. v0.6 ✅(部分):专家调度真实化(v0.6.0);模式检测→人工拍板(= 下方 v1.4 Detector,未完成)
  5. 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 生成器的输入——按顺序做,闭环最顺。