- 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)
13 KiB
13 KiB
DGAgent
地瓜机器人(D-Robotics)RDK 平台的 AI 开发搭档——连接板卡、查询知识、调度专家模型,直达嵌入式开发全流程。
Quickstart
前置:Pi >= 0.79.9 · Node.js >= 22 · RDK X3/X5/S100/S600/Ultra 板卡(SSH 可达)
# 1. 安装
pi install ./
# 2. 配置(交互式向导)
pi -e ./extensions
# 输入 /dg-setup,按提示填入 DG_API_KEY 和 DG_SSH_KEY
# 3. 注册板卡
cat > ~/.pi/agent/dgagent-boards.json << 'EOF'
{ "version": 1, "boards": [
{ "id": "my-x5", "host": "192.168.1.100", "username": "root" }
]}
EOF
# 4. 开始用
# "在板子上跑 ros2 topic list" → 真实 SSH 执行
# "把 ./build/model.bin 推到板卡 /opt/" → 真实 SFTP 同步
# /dg-mode beginner → 新手模式(更多引导)
能做什么
| 能力 | 工具 | 状态 | 说明 |
|---|---|---|---|
| SSH 命令执行 | dg_ssh_exec |
✅ 真实 | ssh2 连接池,TERM→KILL 超时,高危命令分级拦截 |
| 文件同步 | dg_file_sync |
✅ 真实 | SFTP push/pull,自动 mkdirp,绝对路径强制 |
| 板卡发现 | dg_board_list |
✅ 真实 | 配置文件 + mDNS(bonjour-service)双通道 |
| 相机检查 | dg_workflow_camera_check |
✅ 真实 | v4l2 设备枚举 + 格式查询 + ROS2 topic 发现 |
| 安全执行 | dg_workflow_safe_exec |
✅ 真实 | assessRisk + execOnBoard + 审计日志全链路 |
| 模式切换 | /dg-mode |
✅ 真实 | beginner/free,appendEntry 持久化,重启恢复 |
| 一键配置 | /dg-setup |
✅ 真实 | 写 settings.json + runtime provider 注册 |
| 使用观测 | /dg-usage |
✅ 真实 | v0.5 观测层:session log → 工具/workflow 使用频率统计(--board/--since/--json) |
| 脚本候选 | /dg-suggest |
✅ 真实 | v1.4 Detector:重复工具序列挖掘 + 评分 + 人工拍板(候选持久化供生成器) |
| 生成工作流 | /dg-accept |
✅ 真实 | v1.5 Generator:候选 → workflow 骨架(trust=auto)+ 信任分级注册 |
| 信任注册表 | /dg-registry |
✅ 真实 | v1.5 信任分级 trusted/observed/auto,promote/safe-run |
| 全自动闭环 | /dg-autoloop |
✅ 真实 | v2.0 observer→detector→generator 一次跑完(幂等 + KB 草稿 + --dry-run) |
| 执行工作流 | dg_workflow_run |
✅ 真实 | v2.1 执行载体:注册 workflow 真实执行,安全执行自动推进信任阶梯 auto→observed→trusted |
| 知识库查询 | dg_kb_search |
✅ 真实 | MCP client(Wikihub),JSON-RPC over HTTP,15s 超时 |
| 模型路由 | dg_model_route |
✅ 真实 | 规则表 → KB → LLM 三层路由(确定性优先) |
| 专家调度 | dg_dispatch_expert |
✅ 真实 | 垂类模型直接调用(complete()),降级模板兜底 |
安全门:所有 SSH 命令穿过 SDB Gate——fatal 永远拒绝(rm -rf /、dd),severe/warning 需用户确认,safe 直接执行。每条命令写入审计日志。
Slash 命令:/dg-help /dg-status /dg-mode [beginner|free] /dg-setup /dg-usage /dg-suggest /dg-accept <候选id> /dg-registry [list|promote|safe-run] /dg-autoloop [--dry-run]
CLI(v1.6,无需 Pi):dg usage|suggest|registry|accept|serve-mcp — 直接读 session log / 候选 / 注册表(Node ≥ 23.6)。MCP 服务端:dg serve-mcp 暴露 workflow_list / usage_stats / candidate_list 三个 JSON-RPC 工具。
架构
开发者(唯一入口:Pi 对话)
│
▼
┌─────────────────────────────────┐
│ DGAgent Extension (host) │
│ │
│ system-prompt.ts │
│ · RDK 域知识注入 │
│ · beginner/free 模式 │
│ · /dg-setup, /dg-mode │
│ │
│ tools.ts (13 tools) │
│ · dg_ssh_exec ──→ ssh2 ──→ 板卡 │
│ · dg_file_sync ──→ SFTP ──→ 板卡 │
│ · dg_board_list ──→ mDNS+cfg │
│ · dg_workflow_camera_check │
│ · dg_workflow_safe_exec │
│ · dg_workflow_push_and_verify │
│ · dg_workflow_board_health │
│ · dg_workflow_build_verify │
│ · dg_mode_evaluate │
│ · dg_kb_search ──→ MCP client │
│ · dg_model_route (rules→KB→LLM)│
│ · dg_dispatch_expert ──→ complete()│
│ · dg_workflow_run (v2.1) │
│ │
│ provider.ts │
│ · dg-robot + 4 专家模型 │
│ │
│ utils.ts (re-export + Pi helpers)│
│ · lib/ re-exports │
│ · provider registration │
│ · settings.json writer │
│ │
│ lib/ (pure business logic) │
│ · risk.ts (SDB Gate + audit) │
│ · ssh.ts (pool + exec + SFTP) │
│ · discovery.ts (mDNS + config)│
│ · routing.ts (rules→KB→LLM, │
│ dispatch + fallback) │
│ · mode-gate.ts (#8 模式阈值) │
│ · tros-env.ts (TROS setup) │
│ · mcp-client.ts (Wikihub) │
│ · render.ts + telemetry.ts │
│ · compact/debug/observability │
│ · detector/generator/registry │
│ · autoloop/runner (v2.x) │
│ · workflows/ (camera-check, │
│ safe-exec, push-and-verify, │
│ board-health, build-verify) │
└─────────────────────────────────┘
│ SSH
▼
┌──────────────┐
│ RDK 板卡 │
│ (ROS2 / OE) │
└──────────────┘
开发
npm run typecheck # TypeScript strict(exit 0 才算通过)
npm test # vitest(540+ tests,journey→test 一一对应)
npm run test:watch # watch 模式
代码结构:
extensions/
├── provider.ts # dg-robot provider + 4 models(委托 utils)
├── tools.ts # 13 个 dg_* 工具注册
├── system-prompt.ts # RDK 上下文 + mode + 7 runtime slash commands
├── telemetry.ts # pi.on tool_execution span hooks
└── utils.ts # re-export from lib/ + Pi helpers
lib/ # pure business logic(无 Pi 依赖)
├── env.ts # process.env helpers
├── types.ts # Board / RiskAssessment / ExecResult / details interfaces
├── risk.ts # GuardChain + assessRisk + writeAuditLog + appendSessionLog + freezeResult(SDB Gate + 会话日志)
├── ssh.ts # BoardConnectionPool + execOnBoard + sftpPush/Pull
├── discovery.ts # loadBoardConfig + discoverBoards + mDNS
├── routing.ts # ROUTING_RULES + routeByRules/routeByKb + modelRoute + dispatchExpert + templateDispatch
├── schemas.ts # validateExpertType / isValidExpertResponse(白名单 Gate)
├── mode-gate.ts # 模式 Gate #8:evaluateModeSwitch(信心 ≥ 0.8 才建议切换)
├── tros-env.ts # TROS_SETUP_CANDIDATES + sourceTrosEnvCommand(workflow 共享)
├── mcp-client.ts # McpHttpClient(Wikihub,JSON-RPC over HTTP)
├── mcp-server.ts # v1.6 MCP 服务端:handleMcpJsonRpc/handleMcpHttpBody(JSON-RPC over HTTP)
├── debug.ts # DG_DEBUG stderr 调试日志(isDebugEnabled/debugLog,关闭时零分配 no-op)
├── compact.ts # v1.2 Context Engineering 输出压缩:maybeCompact 确定性启发式(头 + error/warning + 尾 + 摘要)
├── observability.ts # v0.5 观测层:readSessionLogEntries + aggregateUsage(使用统计/失败率/趋势)
├── detector.ts # v1.4 Detector:detectCandidates 序列模式挖掘 + 候选持久化
├── generator.ts # v1.5 Generator:候选 → workflow 骨架 + 结构验证 + 落盘
├── registry.ts # v1.5 信任分级:trusted/observed/auto 注册表 + 升级规则
├── autoloop.ts # v2.0 全自动闭环:runAutoLoop(observer→detector→generator)+ KB 草稿
├── runner.ts # v2.1 执行载体:runRegisteredWorkflow(安全执行自动推进信任阶梯)
├── render.ts # render*() 纯展示函数(数据/呈现分离)
├── telemetry.ts # initTelemetry / getTracer / JsonlSpanExporter(OTel)
├── index.ts # barrel exports
└── workflows/
├── camera-check.ts # v4l2 枚举 + ROS2 topic 发现
├── safe-exec.ts # assessRisk → execOnBoard + 审计日志
├── push-and-verify.ts # sftpPush → md5 校验完整性
├── board-health.ts # uptime/负载/内存/磁盘/温度 只读体检
└── build-verify.ts # colcon build 确定性判定(编译 Gate #6 + 代码 Gate #4)
tests/ # 540+ tests,journey→test 一一对应
深入阅读:
| 想了解 | 读这个 |
|---|---|
| 做什么(需求) | DESIGN.md |
| 为什么(设计决策) | METHODOLOGY.md §4 ADR |
| 怎么实现(接口契约) | TECHNICAL_ARCHITECTURE.md |
| 怎么写测试 | TESTING.md §五 实操指南 |
| 代码规范 + 入门 | AGENTS.md |
| 当前进度 | SESSION.md |
Roadmap
| 版本 | 目标 | 状态 |
|---|---|---|
| v0.3 | SSH/SFTP/discovery 真实化 + mode 持久化 + /dg-setup | ✅ |
| v0.4 | MCP client(Wikihub)→ dg_kb_search 真实化 + Fail-closed + Monotonic Guard |
✅ |
| v0.5 | 模型路由规则表 → dg_model_route 真实化(规则表 → KB → LLM) |
✅ |
| v0.6 | 专家调度 → dg_dispatch_expert 真实化(complete() 直调) |
✅ |
| v1.0 | Full SDB Gates(6/9)+ OpenTelemetry tracing + E2E test suite(mock + 真实硬件) | ✅ |
| v1.1 | SDB Gates 9/9(代码 Gate + 编译 Gate + 模式 Gate)+ 工具 12 个 | ✅ |
| v1.2 | 观测层(/dg-usage 使用频率统计)+ Context Engineering 输出压缩 + poka-yoke 加固 |
✅ |
| v1.3 | 观测层进阶(--board/--since 过滤 + 失败率 + 趋势 + --json 导出) |
✅ |
| v1.4 | Detector 脚本候选(/dg-suggest 序列模式挖掘 + 人工拍板 + 候选持久化) |
✅ |
| v1.5 | Generator + 信任分级(/dg-accept 生成骨架 + /dg-registry trusted/observed/auto) |
✅ |
| v1.6 | Layer 2 接入层(bin/dg.mjs CLI + MCP JSON-RPC over HTTP 服务端) |
✅ |
| v2.0 | 全自动闭环(/dg-autoloop observer→detector→generator + KB 草稿 + $DG_AUTOLOOP 自动触发) |
✅ |
| v2.1 | 执行载体 + 信任阶梯跑通(dg_workflow_run + lib/runner.ts)+ 命令日志(logCommandIo) |
✅ |
| v2.1.1 | review 调整:Detector 评分失败率不再加分 + 参数解析收进 lib + 弱断言升级 | ✅ |
| v2.1.2 | 项目 review 批次一:MCP 服务回环绑定 + sftpPush 流式化 + 路由 provenance 修正 + 版本守卫 | ✅ |
| v2.1.3 | 项目 review 批次二:确认审计诚实化(attestedBy)+ severe 正则写上下文匹配 + 执行后日志容错 |
✅ |
| v2.1.4 | 二轮加固批次:连接池并发安全、exec 硬截止与背压、build-verify 注入防护、MCP ACL fail-closed、路由词边界、runner 逐命令审计、exec_error 审计动作、--since 校验、模式恢复容错 | ✅ |
环境变量
| 变量 | 用途 | 必需 |
|---|---|---|
DG_API_KEY |
地瓜 API Key | provider 注册 |
DG_API_BASE_URL |
API endpoint(默认 https://api.d-robotics.com/v1) |
否 |
DG_API_PROTOCOL |
openai-completions(默认)或 anthropic-messages |
否 |
DG_SSH_KEY |
SSH 私钥路径(默认 ~/.ssh/id_rsa) |
SSH 工具 |
DG_MCP_URL |
MCP server URL | v0.4 |
DG_MCP_TOKEN |
MCP bearer token | v0.4 |
DG_DEBUG |
1/true/yes/on 时开启 stderr 调试日志(ssh/discovery/mcp/routing) |
调试 |
DG_SSH_TIMEOUT_MS |
SSH 命令超时毫秒(默认 60000,范围 [1000, 600000]) |
否 |
DG_OTEL_ENDPOINT |
OTLP exporter endpoint(设置时切换 OTLP/HTTP) | 否 |
DG_OTEL_ENABLED |
0 时全局禁用 OpenTelemetry(no-op tracer) |
否 |
DG_AUTOLOOP |
1/true/yes/on 时 session_start 自动触发 /dg-autoloop |
否 |
/dg-setup 自动配置并持久化到 ~/.pi/agent/settings.json。
MIT License · Author: yusen