- 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)
41 KiB
41 KiB
SESSION.md — DGAgent 会话恢复
最近更新:2026-08-17
当前 Session
- 版本:v2.1.4
- 状态:SDB Gates 9/9 + 观测层(v1.2/v1.3)+ Detector(v1.4)+ Generator+信任分级(v1.5)+ Layer 2 CLI/MCP(v1.6)+ 全自动闭环(v2.0)+ 执行载体+命令日志(v2.1)+ 二轮加固批次(v2.1.4) + 546 tests / 63 files + 工具 13 个
- 下一步:v2.1+ 平台化(多板卡批量编排、交付自动回滚、workflow 共享市场)——扩展路线图见 DESIGN.md §10
- 2026-08-17 项目 review:全库 review(typecheck/test 绿 + 架构/安全/正确性走查)产出 13 项待修复,分两批清完:批次一(v2.1.2,H2/H3/M2/M4/M5 + 4 low)、批次二(v2.1.3,H1/M1/M3 全部遗留项)、批次三(v2.1.4,二轮深挖 11 项 + 测试盲区 + 文档漂移)
已完成
v2.1.4 — 二轮加固批次(2026-08-17)
- ✅ H1 连接池在用连接被淘汰:
BoardConnectionPool引入busyCount引用计数(acquire 递增 / release 递减);空闲淘汰定时器只在busyCount === 0时调度,evict()遇 busy 条目跳过并重调度——长命令(>60s)执行中不再被 idle sweep 杀连接 - ✅ H2 并发冷启动重复 TCP:同板卡在途连接去重——
acquire()命中existing.connecting时 await 同一 connect Promise(并发 N 个调用者共享单一 TCP 连接);连接失败双路径清理(发起者 rethrow / 等待者回落冷启动) - ✅ M3 exec 硬截止:超时 SIGTERM 后追加 SIGKILL 宽限期(
KILL_GRACE_MS);channel 正常关闭时全量清理定时器(无泄漏 Timer 拖住事件循环) - ✅ M4 输出背压:exec stdout/stderr 累积超
TRUNCATE_LIMITS.maxBytes(50KB)停止缓冲后续 chunk 并置stdout_truncated/stderr_truncated标志(SshExecResult extends ExecResult,结构化类型向后兼容) - ✅ L1 mkdirp 失败显式拒绝:
sftpPush远端递归 mkdir 错误不再被吞(原来失败会延后成迷惑的 write 错误) - ✅ M2 build-verify 注入防护:
colconBuildCommand的workspaceDir走assertShellSafePath(强化:新增单引号/glob/unicode 同形字全角字符拒绝)、packagesSelect走assertSafePackageNames白名单([A-Za-z0-9_-]空格分隔,; rm -rf //反引号/$()/引号/换行/glob/同形字全拒);remoteVerifyCommand导出函数自防护(不依赖调用方先校验) - ✅ M6 MCP ACL fail-closed:
searchKnowledgeBase遇 ACL 标记缺失/无法解析抛McpError(MCP_ERR_ACL_UNKNOWN)(与"服务器明确无匹配"的空文本占位区分);工具层 catch 回落带标签 mock(绝不默认 public、不泄露原文);整响应畸形 →MCP_ERR_MALFORMEDtyped error - ✅ L2 路由词边界:KB 关键词匹配加 ASCII
\b(先escapeRegExp转义再嵌入)——"cat" 不再误命中 "category";CJK 不套边界(中文字符在 JS 默认正则非词字符,两侧 ASCII 视为边界) - ✅ M5 runner 逐命令审计:
runRegisteredWorkflow每个执行步骤产出 SDB 审计条目(复用assessRisk+writeAuditLog,与 dg_ssh_exec 同形状);审计写失败 try/catch 表面化(不吞结果) - ✅ board_id 一致性守卫:workflow 步骤 board_id 与 workflow 自身 board_id 不一致 → 任何步骤执行前显式失败(fail-closed,点名违规步骤)
- ✅ M1 exec_error 审计动作:
dg_ssh_exec失败路径(SSH 错误类/超时/channel 错误)落action:"exec_error"会话日志(best-effort,rethrow 原异常);lib/types.ts两处 action 联合类型加宽 - ✅ L3 workflow_run 日志补 board_id:
dg_workflow_run的logToolCall条目补齐 board_id(/dg-usage --board过滤恢复完整) - ✅ --since 共享校验:
parseSince非法值抛SinceParseError(带合法格式提示)——CLI 一行错误 + 非零退出(不打堆栈)、MCP JSON-RPC 错误、命令可读错误三端一致 - ✅ 模式恢复容错:
session_start恢复 mode 时损坏条目(非对象/data 形状异常/mode 非法)跳过 + debugLog,回落默认 free(不再崩溃或恢复出垃圾模式) - ✅ mock-ssh 契约面扩展(Wave 0 前置):
MockWriteStream.write返回 boolean、MockReadStream补pause/resume、pullError/pushErrorSFTP 错误注入(错误流不产数据,忠实 ssh2 行为)、clients[]注册 +triggerMockClientEvent("close"|"error")、setSshConnectBlocked/releaseSshConnect连接阻塞 - ✅ 文档漂移修复:README/TECHNICAL_ARCHITECTURE/AGENTS——lib 树补齐 v1.2+ 模块、工具数 12→13、slash 命令清单(static 2 + runtime 7)、roadmap 补 v2.1.1–v2.1.4、env 表补全
- ✅ 测试盲区补齐:9 个新测试文件——
ssh-pool(H1/H2/M3/M4/L1)、build-verify-security(注入矩阵)、mcp-client(ACL fail-closed)、routing-boundary(词边界 CJK 安全)、output-gate(降级路径 fail-closed)、runner-audit(逐命令审计 + board_id 守卫)、sftp-failures(SFTP 错误注入)、compact(边界:空/单行/超限/全 error 行/CJK/2000 字符截断)、cli-since(CLI 校验 e2e)+ journey 25(mode 恢复容错)/26(since 校验);546 passed / 3 skipped(63 files,+130 tests) - ✅ 执行方式:Plan Agent 验证方案 → W0 基线(mock 契约面先行)→ 8 agent 并行(文件所有权互斥)→ 集成(typecheck + 全量 test + gates.test 旧 fail-open 断言更新为新 M6 语义)
- ✅ 验证:
npm run typecheckexit 0;npm test546 passed / 3 skipped(63 files)
v2.1.3 — 项目 review 修复批次二(2026-08-17)
- ✅ H1 确认审计诚实化(安全/审计可信):
logUserConfirmation新增attestedBy: "user" | "agent"——force=true 路径是模型自证不是用户响应,审计responded_by如实区分;dg_ssh_exec/dg_workflow_safe_exec两条 force 路径的审计条目user_confirmed改为false(action 仍为executed_with_force,动作与确认来源分离);TDD——journey 05 新增 Red 测试断言 force 审计不含用户确认 - ✅ M1 severe 正则误伤修复(确认疲劳):
/\bcmdline\b.*=/和/\.(dtb|dts)\b/全匹配改为写上下文匹配——cmdline 认编辑器/sed -i/tee/重定向写入/fw_setenv;dtb/dts 认写动词(cp/mv/rm/install/dd/tee/scp/rsync/编辑器)+ fdtput/fdtdel/fdtapply +dtc -o(大小写敏感,-O输出格式不算)+ 重定向写入。cat /proc/cmdline、ls *.dtb、dtc -I dtb -O dts等只读操作回归 safe;echo x > /boot/cmdline.txt、fw_setenv回归 severe - ✅ M3 执行后日志失败不再吞结果(正确性):
dg_ssh_exec成功路径 + error 路径、safeExecpost-exec 路径的writeAuditLog/logToolCall全部 try/catch 包装——磁盘满/权限等日志故障时,已执行命令的 stdout/exit_code 如实返回并前置降级警告(无空 catch,失败原因进loggingWarnings);SshExecDetails.audit_log_id与SafeExecResult.auditLogId加宽string | null+auditWriteError字段;测试用"审计路径指向目录 → appendFileSync 必抛 EISDIR"确定性触发(journey 06 + unit safe-exec) - ✅ 验证:
npm run typecheckexit 0;npm test416 passed / 3 skipped(53 files,批次二新增 13 tests)
v2.1.2 — 项目 review 修复批次一(2026-08-17)
- ✅ H3 MCP 服务只听回环(安全):
dg serve-mcp显式绑定127.0.0.1(原server.listen(port)默认0.0.0.0,无鉴权暴露到局域网但日志谎称 localhost);TDD——新增 e2e 测试断言 loopback 可达 + LAN 地址拒连(Red→Green) - ✅ H2 sftpPush 流式化(防 OOM):
createReadStream分块ws.write,对齐 sftpPull 的流式实现(原来readFileSync整文件进内存,推大 BPU 模型会爆);mock-ssh WriteStream 补write()累积 +end(data|cb)双签名 - ✅ M2 路由 provenance 修正:
generalFallback.source"rules"→"fallback"(兜底不再伪装规则命中);routeByKb移除从未使用的task参数(签名routeByKb(kbResults?));schemas.tsDECISION_SOURCES 白名单 + types.ts 联合类型同步加"fallback"(否则兜底决策过不了输出 Gate) - ✅ M5 engines + CLI 版本守卫:package.json
engines.node >= 22;bin/dg.mjs 在 import lib/*.ts 前检查 Node ≥ 23.6(原生 type stripping),低版本得到明确报错而非隐晦语法错误 - ✅ M4 Detector 语义标注:
ScriptCandidate.occurrencesJSDoc 写明滑动窗口计数 + 严格连续断链语义 - ✅ Low 批:
.gitignore+.pnpm-store/;dg_board_listsource 三元表达式只算一次;extractJsonObject()抽公共(parseClassifierJson/parseModeEvaluationJson 去重,顺带收紧 Array 分支 fail-closed) - ✅ 验证:
npm run typecheckexit 0;npm test403 passed / 3 skipped(53 files)
v2.1.1 — review 调整 + 测试原则合规(2026-08-14)
- ✅ Detector 评分方向修正(should-fix #4):score = 次数 × 长度,失败率不再加分——脚本化=固化成功经验,恒失败序列走 KB 草稿;评分公式同步 DESIGN §10 / AGENTS
- ✅ isFailedPreview 词边界(nit #11):
\berror\b不再误判 errors/errorless 等正常文本 - ✅ 死代码清除(nit #7):
generatedIdFromSequence删除(含导出) - ✅ DRY(should-fix #3):parseUsageArgs/resolveSince/parseSuggestArgs/parseAutoLoopArgs 收进 lib,system-prompt 命令与 bin/dg.mjs CLI 共用,消除参数解析漂移风险
- ✅ 测试原则合规(TESTING.md 12 条复查):smoke
toBeTypeOf弱断言 →assessRisk真实行为断言(原则 #9/#12 📍 清零);safe-exectoBeTruthy→ UUID 断言;telemetrytoBeDefined→ trace/parent_span 格式断言;/dg-autoloop --json 补测(review nit #9);TESTING.md 整改清单 + 目录结构刷新 - ✅ 验证:
npm run typecheckexit 0;npm test402 passed / 3 skipped(53 files)
v2.1.0 — 执行载体 + 命令日志(方法论 review 欠账修复,2026-08-14)
- ✅
lib/runner.tsrunRegisteredWorkflow:把注册 workflow 真实执行——按注册序列校验(不匹配 fail-closed);支持板卡操作子集步骤(dg_ssh_exec / dg_file_sync / dg_board_list / 5 个 dg_workflow_*);SDB Gate 高危拒绝/确认;不支持的工具步骤(kb/route/dispatch/mode)显式失败不静默跳过;全部成功自动recordSafeRun推进 auto→observed→trusted(补上 v2.0 信任阶梯死路) - ✅
dg_workflow_run工具(13 号):auto 等级需force: true确认(§9.5);renderWorkflowRun渲染步骤结果 + 信任升级提示;TypeBox 参数 + promptGuidelines + logToolCall - ✅
logCommandIo:7 个 slash 命令(mode/setup/usage/suggest/accept/registry/autoloop)输出经notifyCommand写入 session log(event_typecommand+command_io,§3.4 Model-visible ⟺ Logged 不变量补齐) - ✅ 测试:unit runner 9(校验/阶梯/SDB Gate/不支持步骤/exit code/sftp)+ journey 24 4(auto 确认/安全执行/未知/fatal)+ journey 19 命令事件断言 +1;工具数断言 12→13
- ✅ 文档:AGENTS.md(lib 树 + status + roadmap + 12→13 tools)、DESIGN.md §10(v2.1 ✅ + 过期文案修复)、SESSION.md、TESTING.md、README
- ✅ 验证:
npm run typecheckexit 0;npm test399 passed / 3 skipped(53 files + 1 skipped)
v1.5.0 — Generator + 信任分级(DESIGN §9.5,2026-08-14)
- ✅
lib/generator.ts:generateWorkflowSkeleton(候选 →runGen<id>骨架:序列步骤 TODO + 配套单测模板 + 注册片段,trust=auto);verifyGeneratedWorkflow代码 Gate(缺 async 导出/缺单测/as any 拒绝注册);writeGeneratedWorkflow落盘~/.pi/agent/generated-workflows/;_setGeneratedWorkflowsDir路径注入 - ✅
lib/registry.ts信任分级注册表:trusted/observed/auto;registerWorkflow/listWorkflows(trusted→observed→auto 排序)/findWorkflow/recordSafeRun(observed 安全执行 ≥5 次自动升级 trusted,阈值可注入)/promoteWorkflow(人工升级);持久化~/.pi/agent/dgagent-workflows.json - ✅
/dg-accept <候选id>:从 candidates 文件取候选 → 生成 → 代码 Gate 验证(不通过拒绝注册)→ 落盘 → 注册 trust=auto → notify 文件路径 + 升级指引;非法 id / 未知候选友好提示 - ✅
/dg-registry [list|promote <名称>|safe-run <名称>]:注册表表格(trust/名称/序列/来源/安全执行)+ 人工升级 + 安全执行记录 - ✅
renderWorkflowRegistry纯渲染层;tmp-fs 扩展 workflowsPath + generatedDir - ✅ 测试:unit generator 12 + registry 10;journey 21(accept 3)+ 22(registry 5);journey 01 命令断言 4→6
- ✅ 文档:AGENTS.md、DESIGN.md §10(v1.5 ✅)、SESSION.md、TESTING.md、README(/dg-accept + /dg-registry + 353/356/46)
- ✅ 验证:
npm run typecheckexit 0;npm test353 passed / 3 skipped(46 files + 1 skipped)
v1.4.0 — Detector:脚本候选识别(DESIGN §9.4 v0.6,2026-08-14)
- ✅
lib/detector.ts:detectCandidates(entries, opts)— 按 session 分组 + timestamp 排序的序列模式挖掘(连续子序列长度 2..4,minOccurrences默认 3);最长序列优先(A→B→C→D 命中则剔除子序列 A→B→C);含dg_workflow_*的序列跳过(已脚本化);评分 = 次数 × 长度 × (1 + 失败率);candidateId(sha1 前 8 位稳定 id) - ✅ 候选持久化:
saveCandidates/loadCandidates→~/.pi/agent/dgagent-candidates.json(version/saved_at/candidates,v1.5 Generator 输入);_setCandidatesPath/getCandidatesPath(与 boards/settings/session/audit 路径注入对称) - ✅
/dg-suggest命令:读 session log → 挖掘候选 → 渲染排行表(#/id/序列/次数/会话数/失败率/评分)→ notify + 持久化;--top <N>/--min <N>/--json;日志缺失/无候选友好提示 - ✅
renderCandidates纯渲染层(render.ts) - ✅ 测试:unit detector 10(挖掘/阈值/最长优先/跳过 workflow/评分排序/timestamp 排序/持久化 roundtrip)+ journey 20 4(候选列表+持久化 / --min / --json / 无日志)+ journey 01 命令断言更新(4 命令)
- ✅ 文档:AGENTS.md、DESIGN.md §10(v1.4 ✅)、SESSION.md、TESTING.md、README(/dg-suggest + 323/326/42)
- ✅ 验证:
npm run typecheckexit 0;npm test323 passed / 3 skipped(42 files + 1 skipped)
v1.3.0 — 观测层进阶:过滤 / 失败率 / 趋势 / JSON(2026-08-14)
- ✅ 维度过滤:
aggregateUsage(entries, filter)支持boardId(顶层entry.board_id或tool_io.params.board_id,v1.3 起logToolCall自动把 params.board_id 提升到条目顶层)+since(ISO 时间戳);filtered_entries计数 - ✅ 失败率:
isFailedPreview确定性标记启发式(❌/失败/error/fatal/failed/拒绝/超时/exception/panic/timeout/非零 exit code);ToolUsage.failures+failure_rate(1 位小数) - ✅ 趋势:按天聚合(timestamp 前 10 位),
trend升序数组;renderUsageReport展示近 14 天 - ✅ /dg-usage 参数:
--board <id>、--since <Nd|Nh|ISO>、--json(原始统计导出,v1.4 detector 数据源);parseUsageArgs/resolveSinceKISS 解析 - ✅ 渲染:工具表加失败率列;
renderUsageReport增强 - ✅ 测试:unit observability 10→17(isFailedPreview 2 + 过滤/失败率/趋势 5);journey 19 3→6(--board/--json/--since)
- ✅ 文档:AGENTS.md、DESIGN.md §10(v1.3 ✅)、SESSION.md、TESTING.md、README(310/313/40)
- ✅ 验证:
npm run typecheckexit 0;npm test310 passed / 3 skipped(40 files + 1 skipped)
v1.2.0 — v0.5 观测层:/dg-usage 使用频率统计(2026-08-14)
- ✅ 观测层核心(DESIGN.md §9.4「统计哪个 workflow 被用得最多」落地,KISS 确定性无 LLM):
lib/observability.ts:readSessionLogEntries(JSONL 解析,坏行 fail-closed 跳过计数不抛异常)+aggregateUsage(只统计 tool_io 事件;按调用次数降序;share 占比 + 非空 duration 均值;dg_workflow_*子集单独排行;top_tool)lib/render.tsrenderUsageReport(纯渲染:总览 + 工具排行表 + workflow 排行表;空数据友好提示)lib/risk.ts新增getSessionLogPath()公开 getter(与_setSessionLogPath对称)/dg-usage命令(system-prompt.ts runtime 注册):读 session log → 解析 → 聚合 → notify 展示;日志缺失/为空给友好提示;坏行数附注- 导出:
lib/index.ts+extensions/utils.ts(observability + renderUsageReport + getSessionLogPath)
- ✅ 测试:unit observability 10(解析 4 + 聚合 6)+ journey 19 3(排行表 / 日志缺失提示 / 无 tool_io 空态)+ journey 01 命令注册断言更新(dg-mode/dg-setup/dg-usage)
- ✅ 文档:AGENTS.md(lib 树 + Current Status + roadmap v1.2)、TESTING.md 映射表 +1 行、README(/dg-usage 行 + 命令列表 + 测试数 300/303/40)
- ✅ 验证:
npm run typecheckexit 0;npm test300 passed / 3 skipped(40 files + 1 skipped)
v1.1.1 — 上下文工程输出压缩 + poka-yoke 加固(2026-08-14)
- ✅ Context Engineering 输出压缩(DESIGN.md §2.4 落地):
lib/compact.tsmaybeCompact— 确定性启发式(KISS 非 LLM):超阈值(4000 字符 / 500 行)时提取头部(5 行)+ error/warning 关键行(去重、上限 20)+ 尾部(1500 字符)+ 一句话摘要;未超阈值原样返回(compacted=false)dg_ssh_exec/dg_kb_search新增response_format: concise|detailed参数(StringEnum,默认 detailed)- ssh_exec concise 模式:stdout+stderr 一并压缩(失败命令错误行不丢),末尾附加 exit code / signal / duration 元信息
lib/render.tsrenderCompactedOutput(UI 投影分离);lib/index.ts+extensions/utils.ts导出
- ✅ push-and-verify poka-yoke:
assertShellSafePath拒绝含"`$\;|&<>()换行的路径(防remoteVerifyCommand双引号逃逸 → 远程命令注入),SSH 调用前拦截 - ✅ board-health 并发探测:5 条只读命令
Promise.all并行(ssh2 多路复用单连接),最坏延迟 5×timeout → 1×timeout - ✅ 渲染层修复:
renderBoardHealth磁盘单位 KB→GB 换算(之前错除 1024 一次显示 MB,实为 GB 级);renderModeEvaluate格式瑕疵 - ✅ 测试:unit compact 5 + push-and-verify poka-yoke 3;journey 06(ssh concise 压缩+退出码)、journey 14(kb concise 摘要+关键行)各 1;工具注册断言不变(12 tools)
- ✅ 验证:
npm run typecheckexit 0;npm test287 passed / 3 skipped(38 files + 1 skipped)
v1.1.0 — SDB Gates 9/9:代码 Gate + 编译 Gate + 模式 Gate(2026-08-14)
- ✅ 编译 Gate (#6) 核心:
lib/workflows/build-verify.tsparseBuildResult— colcon build 输出确定性正则解析(packages finished/failed、error 行、warning 不算 error、20 行 error 上限、无 Summary 保守判定);colconBuildCommand(source TROS + cd workspace + --packages-select) - ✅ 代码 Gate (#4) 载体:
dg_workflow_build_verify工具 — 上板编译验证,失败返回 failedPackages/errorLines,promptGuidelines 强制"交付前必须调用、失败不得声称编译通过" - ✅ 模式 Gate (#8):
lib/mode-gate.ts—evaluateModeSwitch确定性阈值(信心 ≥ 0.8 才建议切换)+isValidModeEvaluation输出 Gate(mode 白名单 + confidence ∈ [0,1])+ModeEvaluator注入接口;dg_mode_evaluate工具(complete() 直调,LLM 不可用 fail-closed 不打扰);getCurrentMode()从 system-prompt 导出供工具读当前模式 - ✅ DRY 重构:
lib/tros-env.ts提取 TROS_SETUP_CANDIDATES + sourceTrosEnvCommand,camera-check 与 build-verify 共享(消除命令字符串漂移) - ✅ 测试:unit 22(build-verify 13 + mode-gate 9)+ journey 17/18(6);工具注册断言 10→12
- ✅ 验证:
npm run typecheckexit 0;npm test277 passed / 3 skipped(36 files + 1 skipped)
v1.0.5 — workflow journey 补全(2026-08-14)
- ✅ journey 15/16 补全(v1.0.4 新增的两个 workflow 缺 journey 级覆盖,违反 TESTING.md journey→test 一一对应原则):
tests/journeys/15-push-and-verify.test.ts(3 tests):真实 tools 工厂 + mock-ssh,验证成功(本地写文件 → 真实 md5 → mock 远端一致)/ md5 不匹配 / 未知 board_idtests/journeys/16-board-health.test.ts(3 tests):全指标收集(mock 5 条只读命令)/ uptime 失败只置空对应字段 + errors / 未知 board_id- 命令 key 复用
remoteVerifyCommand()builder(沿用 v1.0.2 B3 的防命令漂移做法)
- ✅ TESTING.md journey→test 映射表补 2 行
- ✅ 验证:
npm run typecheckexit 0;npm test249 passed / 3 skipped(32 files + 1 skipped)
v1.0.4 — workflow 工具箱补全(2026-08-14)
- ✅ push-and-verify(
lib/workflows/push-and-verify.ts+dg_workflow_push_and_verify):- sftpPush → 本地 md5(流式计算)→ 远端
md5sum; stat -c %s→ 比对,verified布尔返回 - 校验不匹配/远端失败不抛异常,落入 result(errors 数组),由调用方决策重试
md5OfFile/parseMd5Sum/remoteVerifyCommand纯函数导出,独立单测
- sftpPush → 本地 md5(流式计算)→ 远端
- ✅ board-health(
lib/workflows/board-health.ts+dg_workflow_board_health):- 只读体检:uptime(含 load average)/ nproc / free -m / df -k / / thermal_zone0(℃)
- 单条命令失败只置空对应字段 + 记 errors,不影响其他指标;非零退出码也算 soft error
parseLoadAvg/parseFreeMem/parseDf/parseTemp纯解析函数独立单测
- ✅ 工具数 8 → 10:DESIGN.md §9.3 Layer 1 工具箱 4/4 完成(camera-check / safe-exec / push-and-verify / board-health)
- ✅ 文档同步:AGENTS.md(8→10、lib 树、命名空间、移除过时"日志轮转未实现")、README.md(架构图/工具表/测试数 243)、TECH_ARCHITECTURE.md(8→10)、tests/e2e/README.md;package.json + README 徽章 → 1.0.4
- ✅ 测试:
tests/unit/push-and-verify.test.ts(11)+tests/unit/board-health.test.ts(8);工具注册断言 8→10(tool-exec / 01-install) - ✅ 验证:
npm run typecheckexit 0;npm test243 passed / 3 skipped(30 files + 1 skipped)
v1.0.3 — DG_DEBUG 调试输出(2026-08-14)
- ✅ DG_DEBUG 落地(评审遗留项,TECH_ARCHITECTURE.md §6.3 从"未实现"转"已实现"):
lib/debug.ts:isDebugEnabled()(DG_DEBUG∈ {1,true,yes,on} 大小写不敏感)+debugLog(scope, message, details?)+_setDebugEnabled(@internal 测试钩子)- 关闭时零分配 no-op;输出走 stderr(格式
[dg-debug] <scope>: <message> {json}),绝不污染工具 stdout - 接线 4 个 lib 模块:
ssh(连接池/exec/SFTP)、discovery(配置/mDNS)、mcp(JSON-RPC 请求响应)、routing(路由各层 + dispatch) lib/index.ts+extensions/utils.ts导出;AGENTS.md env 表 + TECH_ARCHITECTURE.md 附录 A 更新
- ✅ 测试:
tests/unit/debug.test.ts(10 tests)— 开关解析 / stderr 写入格式 / 循环引用不抛 / discovery 接线(缺失配置回退 + 有效配置板卡数) - ✅ 验证:
npm run typecheckexit 0;npm test224 passed / 3 skipped(28 files + 1 skipped)
v1.0.2 — 日志轮转 + 评审遗留修复(2026-08-14)
- ✅ A2 日志轮转(TECH_ARCHITECTURE.md §6.1 落地):
lib/risk.tsmaybeRotateLog:session log 与 audit log 超 10MB 时重命名<path>.1,新建空文件继续追加- 阈值默认 10MB,
_setSessionLogRotateBytes可覆盖(@internal,测试用);lib/index.ts+extensions/utils.ts导出 - 测试:
tests/unit/log-rotation.test.ts(4 tests)— 未超限不轮转 / 超限快照轮转 / 轮转后继续追加 / audit 双写同步轮转
- ✅ B1 safe-exec 去除 "unknown" 假值:
sessionId/agentInvocationId未提供时为null(不再伪造占位符污染 trace 关联);SdbAuditEntry.session_id/agent_invocation_id与SessionLogEntry.session_id放宽为string | null - ✅ B2 sftpPull 流式化:
lib/ssh.ts由"整文件读入内存再 writeFileSync"改为createWriteStream增量写入,消除大文件 OOM 风险 - ✅ B3 camera-check 多路径探测:新增
TROS_SETUP_CANDIDATES+ros2TopicListCommand()(探测/opt/tros、/opt/tros/humble、/opt/ros/humble、/opt/tros/robot的 setup.bash); journey 12 改为引用同一 builder,消除命令字符串漂移 - ✅ 验证:
npm run typecheckexit 0;npm test214 passed / 3 skipped(27 files + 1 skipped)
v1.0.1 — 测试日志路径隔离修复(2026-08-14)
- ✅ 修复测试写真实 home 目录的隔离漏洞:
appendSessionLog/writeAuditLog默认写~/.pi/agent/dgagent-{session,audit}.log,测试环境(沙箱/CI)无 home 写权限时 45 个测试全挂 - ✅
lib/risk.ts新增_setAuditLogPath(与_setSessionLogPath对称);lib/index.ts+extensions/utils.ts同步导出 - ✅
tests/helpers/tmp-fs.ts:TmpFs 新增sessionLogPath/auditLogPath,apply()统一重定向 四个路径(boards/settings/session/audit)→ 所有走getToolExecute的 journey/e2e/unit 自动隔离 - ✅
tests/unit/safe-exec.test.ts:risk mock 中重定向日志到 tmpDir(beforeEach 建 tmp + afterEach 清理) - ✅ 验证:
npm run typecheckexit 0;npm test210 passed / 3 skipped(26 files + 1 skipped)
v1.0 — Full SDB Gates + OpenTelemetry + E2E(2026-08-13)
- ✅ Full SDB Gates(DESIGN.md §六 9 门,6 门实现):
- 路由 Gate 白名单:
lib/schemas.tsvalidateExpertType/isExpertType— modelRoute LLM 路径(routing.ts L223)非法 task_type 回退 generalFallback - 输出 Gate:
isValidExpertResponse/isValidRouteDecision运行时校验 — dispatchExpert 非法 invoker 输出降级 template - 鉴权 Gate:
searchKnowledgeBase(query, mode, allowedAcl)— 解析真实 ACL,不在白名单返回"无权限访问"(mcp-client.ts) - 参数 Gate:
assertBoardId确定性 board_id 校验(tools.ts L74) - 确认 Gate:
matchesConfirmation+logUserConfirmation(user_confirmation session 日志事件) - 代码/编译/模式 Gate 延后:需 colcon build tooling + LLM 置信度评估(ADR 记录于 AGENTS.md)→ v1.1.0 ✅ 已实现(9/9)
- 路由 Gate 白名单:
- ✅ OpenTelemetry tracing(METHODOLOGY.md §五 全勾选):
lib/telemetry.ts:NodeTracerProvider + SimpleSpanProcessor +JsonlSpanExporter(JSONL 默认);DG_OTEL_ENDPOINT→ OTLP/HTTP;DG_OTEL_ENABLED=0no-op;guarded(不覆盖宿主 provider)extensions/telemetry.ts:pi.on("tool_execution_start"/"end")span 钩子(fail-open)SessionLogEntry加trace_id/span_id,appendSessionLog捕获活动 span context- 8 工具
withToolSpan包裹 + LLM 调用 GenAI 属性(gen_ai.*) - 依赖:@opentelemetry/api/sdk-trace-base/sdk-trace-node/exporter-trace-otlp-http/semantic-conventions/core/resources
- ✅ E2E 测试套件(TESTING.md):
- mock-ssh 状态化升级(per-command responses + execHistory + pushedFiles + pullData)
getToolsExecute多工具助手(tool-exec.ts)tests/e2e/mocked/chained-tools.test.ts:board_list → ssh_exec → file_sync → safe_exec 用户叙事- 缺失 journey 补齐:12-camera-check、13-safe-exec、14-kb-search(MCP fetch mock)
tests/e2e/real/board.test.ts:真实硬件,DG_E2E_BOARD_ID门控 +npm run test:e2etests/e2e/README.md(TESTING.md:205 承诺的文档)
- ✅ 测试:26 files / 210 tests(+57:gates 21 + telemetry + telemetry-extension 4 + mock-ssh + tool-exec 3 + e2e chain + journeys 12-14)
- ✅
npm run typecheckexit 0,npm test210/210 passed(26 files) - ✅ 版本号 0.6.0 → 1.0.0
v0.6 — 真实专家调度 + 3 层路由(2026-08-13)
- ✅ v0.4 方法论落地:
- Fail-closed(§1.6):7 处空 catch {} → console.warn;
dg_kb_search/dg_dispatch_expert/dg_model_route环境变量缺失时报错不返回 mock - Session Log(§3.4):
SessionLogEntry统一日志模型 +appendSessionLog+logToolIo便捷工厂;writeAuditLog向后兼容双写 - Monotonic Guard(§3.3):
GuardChain+PatternGuard+RISK_ORDER单调性;assessRisk迁移至 GuardChain(API 兼容) - 规则 10/11:
freezeResult冻结结果;timeout_ms从 schema 移除 →$DG_SSH_TIMEOUT_MS环境变量
- Fail-closed(§1.6):7 处空 catch {} → console.warn;
- ✅ v0.5 模型路由真实化:
lib/routing.ts:ROUTING_RULES规则表(priority 冲突消解)+routeByRules(L1)+routeByKb(L2)+modelRoute(3 层编排,LlmClassifier 注入)dg_model_route接入modelRoute()+makeLlmClassifier(dg-general-v1 意图分类)- UI 投影分离(§3.2 规则 8):
lib/render.ts补全 7 个 render 函数,全部工具迁移至 render 层
- ✅ v0.6 专家调度真实化:
dispatchExpert()+makeExpertInvoker(complete() 直调垂类模型,60s 超时,token_usage/latency 记录)- LLM 失败降级模板(带
⚠️ LLM 调用失败标记);无 API Key 时 fail-closed
- ✅ 测试:
tests/unit/routing.test.ts(25)、tests/unit/render.test.ts(25)、tests/journeys/10-model-route.test.ts(4)、tests/journeys/11-dispatch-expert.test.ts(3);mock-pi.ts扩展 modelRegistry - ✅
npm run typecheckexit 0,npm test153/153 passed(17 files) - ✅ 版本号 0.3.0 → 0.6.0
v0.3.1 — Review 修复(2026-08-13)
- ✅ 参照 DESIGN.md / METHODOLOGY.md / TECHNICAL_ARCHITECTURE.md / TESTING.md 完成全项目 review,产出《改进意见-2026-08-13.md》(309 行)
- ✅ 修复
lib/workflows/safe-exec.ts审计日志双写 bug:移除无条件预写action: "rejected",改为 fatal/confirmation_required/executed 三个分支各自写入 - ✅ 修复
extensions/tools.tsstale 描述:dg_board_list / dg_ssh_exec / dg_file_sync / dg_dispatch_expert / dg_model_route 移除 "v0.2 mock" 残留文案 - ✅ 移除
dg_ssh_exec返回文本中的 UUID(保留在details.audit_log_id) - ✅ 修复
extensions/system-prompt.tsMODE_CUSTOM_TYPE 重复声明:改为从 utils.ts 导入 - ✅ 完成
lib/提取:extensions/utils.ts从 1133 行瘦身为 228 行(re-export from lib/ + Pi-coupled helpers) - ✅ 文档漂移修正:README.md(8 tools / 89 tests / lib/ 结构)、AGENTS.md(lib/ 目录 + dg_workflow_* 命名空间)、TECHNICAL_ARCHITECTURE.md(DG_DEBUG 虚假文档标注为"未实现")、SESSION.md
- ✅
npm run typecheckexit 0,npm test89/89 passed
v0.3
- ✅
extensions/utils.ts:- v0.3.1:瘦身为 re-export 层(228 行),纯业务逻辑移至
lib/ Board类型(替代MockBoard,新增port, username, discovered_via, last_seen_at)loadBoardConfig/saveBoardConfig(~/.pi/agent/dgagent-boards.json)_setBoardsConfigPath/_setSettingsPath(@internal 测试路径注入)discoverBoards+discoverBoardsViaMdns(bonjour-service,超时 3s)BoardConnectionPool(Map<boardId, SshClient>,lazy connect,60s idle eviction,keepalive 30s)execOnBoard(promisified exec,stdout/stderr/exitCode/signal 捕获,TERM→2s→KILL 超时)sftpPush/sftpPull(ssh2 SFTP,自动 mkdirp remote)registerDgRobotProvider(提取自 provider.ts,供 init +/dg-setup共用)writeEnvToSettings(写~/.pi/agent/settings.jsonenv 块)SshConnectError/SshConfigError/SshExecError(带 level 信息)SshExecDetails/FileSyncDetails新增error_type?/error_level?字段
- v0.3.1:瘦身为 re-export 层(228 行),纯业务逻辑移至
- ✅
extensions/provider.ts:精简为调用registerDgRobotProvider(pi) - ✅
extensions/tools.ts:dg_board_list:真实发现(config + mDNS),新增refresh参数,warnings 数组dg_ssh_exec:真实 SSH 执行,ctx.sessionManager.getSessionId(),新增timeout_ms参数dg_file_sync:真实 SFTP push/pullfindBoardByIdhelper(从 discoverBoards 解析 board_id)- catch block 填充
error_type/error_level
- ✅
extensions/system-prompt.ts:session_start事件恢复 mode(扫描ctx.sessionManager.getEntries())/dg-setup:自动写 settings.json + runtime 调registerDgRobotProvider(pi)
- ✅
TESTING.md(新文件,231 行):12 测试原则 + checklist + 目录结构 + journey→test 映射 - ✅
METHODOLOGY.md:§六 测试方法论参考(10 新文献)+ 链接至 TESTING.md - ✅
AGENTS.md:新增npm test命令 + TESTING.md 引用 - ✅
npm run typecheckexit 0 - ✅ 测试框架重构:9 journey + 1 unit + 1 smoke,64/64 通过
- 设计原则:journey→test 一一对应,删除 mock-only 测试(旧 04/05/08),SDB Gate 移至 unit/
tests/smoke.test.ts(8 tests)— 包元数据、依赖、类型导入、utils 导出tests/journeys/01-install.test.ts(4)— provider 注册、tools 注册、commands 注册tests/journeys/02-mode-selection.test.ts(4)— /dg-mode beginner/free 设置 + session_start 恢复tests/journeys/03-mode-switch.test.ts(3)— 动态切换、last-write-wins、override、sustained statetests/journeys/04-connection-diagnostics.test.ts(4)— client-authentication / client-socket / ok / file_sync 错误透传tests/journeys/05-high-risk-confirmation.test.ts(6)— fatal 拒绝、severe/warning 确认、safe 直接执行tests/journeys/06-ssh-exec.test.ts(4)— safe 执行、timeout_ms、traceability、unknown board_id throwtests/journeys/07-file-sync.test.ts(4)— 相对路径拒绝、push、pulltests/journeys/08-board-discovery.test.ts(4)— 空配置 fallback、config 读取、loadBoardConfig、roundtriptests/journeys/09-setup-wizard.test.ts(3)— 写 settings.json、runtime registerProvider、空 API key skiptests/unit/sdb-gate.test.ts(20)— assessRisk fatal/severe/warning/safe 全模式(独立单元测试)tests/helpers/mock-pi.ts— MockPi 接口 + asExt() 双断言集中化tests/helpers/mock-ssh.ts— installSshMock + setSshConnectFail + setSshChannelOpts + mockSshStatetests/helpers/mock-bonjour.ts— installBonjourMocktests/helpers/tmp-fs.ts— createTmpFs 返回 {dir, boardsPath, settingsPath, cleanup, apply(utils)}
- ✅
vitest.config.ts:新增clearMocks: true+testTimeout: 10000 - ✅
npm test64/64 passed,npm run typecheckexit 0 - ✅ v0.3.1:
npm test89/89 passed(+25 tests: camera-check 15 + safe-exec 10),npm run typecheckexit 0 - ✅ 设计讨论:脚本化自进化架构(SESSION 2026-08-11)
- 提取 METHODOLOGY.md + TESTING.md 的设计/测试原则为通用工程原则文档(
~/workspace/engineering-principles/ENGINEERING-PRINCIPLES.md) - DESIGN.md 新增 §九(脚本化自进化架构):四层模型、成长路线、信任分级
- 核心类比:Agent 工具调用序列 = 工程师的脚本工具箱,脚本化 = 外化的记忆 = 防止退步
- 决议 MVP 路线:v0.4 提取 lib/ + 手写 3-5 个高频 workflow,不做自动模式检测(人工先于自动化)
- 提取 METHODOLOGY.md + TESTING.md 的设计/测试原则为通用工程原则文档(
v0.2 mock-demo
- ✅ 6 个工具 schema + mock 实现(结构化 details + SDB Gate 真实 + 审计日志)
- ✅ slash commands(/dg-help, /dg-status, /dg-mode, /dg-setup)
- ✅ 4 个 SKILL.md skeletons
- ✅ provider 注册(init 时)+ 4 专家模型
- ✅ system prompt RDK 域注入
代码中的 TODO 标记(v0.4+ 待实现)
无。(routed_via 已在 v0.6 完成;mock 函数已全部真实化,仅保留向后兼容。)
Mock 函数(有 docstring 标注替换版本,v0.6+ 已全部真实化,仅保留向后兼容):
mockKbSearch→ v0.4(Wikihub MCP client)✅mockDispatchExpert→ v0.6(真实专家模型 subagent)✅mockModelRoute→ v0.5(规则表 + KB + LLM 三层路由)✅
卡点
无。
下次恢复指引
v0.3 手动验证(用户需做)
pi install ./验证安装pi -e ./extensions启动/dg-setup走一遍向导,确认 settings.json 写入 + provider 注册/dg-mode beginner切模式,重启 Pi 确认 mode 恢复- 配置
~/.pi/agent/dgagent-boards.json:{ "version": 1, "boards": [ { "id": "my-x5", "host": "192.168.1.100", "username": "root" } ] } /dg-board-list确认板卡出现dg_ssh_exec在真实板卡上跑ros2 topic list
v0.4 起步
- MCP client(Wikihub):
dg_kb_search真实化(见 TECHNICAL_ARCHITECTURE.md §7.1)✅ dg_model_route真实化:规则表 + KB + LLM 三层路由(v0.5)✅- 手写更多 workflow:push-and-verify(sftpPush → execOnBoard 验证)(v1.0.4)✅ / board-health(v1.0.4)✅ — DESIGN §9.3 Layer 1 工具箱 4/4
- DG_DEBUG + 日志轮转:实现
DG_DEBUG=1stderr 调试输出(v1.0.3)✅ / 日志轮转(v1.0.2)✅ - OTel tracing:接入 OpenTelemetry(v1.0)✅
文件索引
| 文件 | 状态 |
|---|---|
extensions/utils.ts |
v0.3.1 瘦身为 re-export 层(228 行)+ Pi helpers |
extensions/provider.ts |
v0.3 精简(调 registerDgRobotProvider) |
extensions/tools.ts |
v0.3.1 修复 stale 描述 + UUID 泄漏;v1.0.4 10 tools(1253 行) |
extensions/system-prompt.ts |
v0.3.1 修复 MODE_CUSTOM_TYPE 重复声明(181 行) |
lib/risk.ts |
v0.3 完成(assessRisk + writeAuditLog) |
lib/ssh.ts |
v0.3 完成(BoardConnectionPool + exec + SFTP) |
lib/discovery.ts |
v0.3 完成(mDNS + config) |
lib/routing.ts |
v0.3 完成(mock KB/dispatch/route) |
lib/types.ts |
v0.3 完成(共享类型 + TRUNCATE_LIMITS) |
lib/env.ts |
v0.3 完成(process.env wrappers) |
lib/debug.ts |
v1.0.3 新增(DG_DEBUG stderr 调试日志) |
tests/unit/debug.test.ts |
v1.0.3 新增(10 tests) |
lib/workflows/camera-check.ts |
v0.3 完成(v4l2 + ROS2 topic) |
lib/workflows/safe-exec.ts |
v0.3.1 修复审计日志双写 bug |
lib/workflows/push-and-verify.ts |
v1.0.4 新增(sftpPush → md5 校验) |
lib/workflows/board-health.ts |
v1.0.4 新增(只读健康体检) |
tests/unit/push-and-verify.test.ts |
v1.0.4 新增(11 tests) |
tests/unit/board-health.test.ts |
v1.0.4 新增(8 tests) |
tests/journeys/15-push-and-verify.test.ts |
v1.0.5 新增(3 tests) |
tests/journeys/16-board-health.test.ts |
v1.0.5 新增(3 tests) |
lib/mode-gate.ts |
v1.1.0 新增(模式 Gate #8 阈值评估) |
lib/tros-env.ts |
v1.1.0 新增(TROS setup 候选路径共享) |
lib/workflows/build-verify.ts |
v1.1.0 新增(编译 Gate #6 + 代码 Gate #4) |
tests/unit/build-verify.test.ts |
v1.1.0 新增(13 tests) |
tests/unit/mode-gate.test.ts |
v1.1.0 新增(9 tests) |
tests/journeys/17-build-verify.test.ts |
v1.1.0 新增(3 tests) |
tests/journeys/18-mode-evaluate.test.ts |
v1.1.0 新增(3 tests) |
lib/compact.ts |
v1.1.1 新增(maybeCompact 确定性输出压缩) |
tests/unit/compact.test.ts |
v1.1.1 新增(5 tests) |
lib/observability.ts |
v1.2.0 新增(v0.5 观测层:JSONL 解析 + 使用频率聚合) |
tests/unit/observability.test.ts |
v1.2.0 新增(10 tests) |
tests/journeys/19-usage-report.test.ts |
v1.2.0 新增(3 tests,/dg-usage) |
tests/smoke.test.ts |
v0.3 完成(8 smoke tests) |
tests/helpers/mock-pi.ts |
v0.3 重构(MockPi 接口 + asExt 集中化双断言) |
tests/helpers/mock-ssh.ts |
v0.3 新增(installSshMock + setSshConnectFail + mockSshState) |
tests/helpers/mock-bonjour.ts |
v0.3 新增(installBonjourMock) |
tests/helpers/tmp-fs.ts |
v0.3 新增(createTmpFs + apply(utils) 路径重定向) |
tests/journeys/*.test.ts |
v0.3 重构(9 journey 一一对应 + unit/sdb-gate) |
tests/unit/sdb-gate.test.ts |
v0.3 新增(独立单元测试) |
tests/unit/camera-check.test.ts |
v0.3 新增(15 tests) |
tests/unit/safe-exec.test.ts |
v0.3 新增(10 tests) |
TESTING.md |
v0.3 新增(12 测试原则 + checklist + 映射表) |
vitest.config.ts |
v0.3 完成(clearMocks + testTimeout) |
prompts/dg-help.md |
v0.2 完成 |
prompts/dg-status.md |
v0.2 完成 |
skills/*/SKILL.md (×4) |
v0.2 skeleton |
TECHNICAL_ARCHITECTURE.md |
v0.3.1 修正 DG_DEBUG 虚假文档 |
改进意见-2026-08-13.md |
v0.3.1 新增(review 报告,309 行) |
关键决策速查
- 多 Agent 而非单 Agent — Orchestrator + 6 专家
- 确定性路由而非 LLM 路由 — SDB Gate、模型路由用规则表
- Wikihub 而非纯文件 — 知识库用 MCP + Postgres
- v0.2 mock 优先 — 先打通安装与 demo(用户决策)
- 技术架构先于代码 — 补架构文档后再继续实现
- ssh2 而非 node-ssh — 保留 stream 级控制(signal/timeout/error level)
- bonjour-service mDNS — SSH 服务发现
- Pi
appendEntry+session_start— mode 持久化方案 registerProviderruntime 安全 — Pi 源码确认,/dg-setup可直接调node:fs写 settings.json — Pi 无 env 写 API- 脚本化自进化 — Agent 重复工具序列 → 凝固为脚本;v0.4 MVP 手写 workflow,v1.0 全自动闭环(DESIGN.md §九)