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

DGAgent

地瓜机器人(D-Robotics)RDK 平台的 AI 开发搭档——连接板卡、查询知识、调度专家模型,直达嵌入式开发全流程。

tests version


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

Description
No description provided
Readme 1.6 MiB
Languages
TypeScript 99.1%
JavaScript 0.9%