DGAgent/SESSION.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

41 KiB
Raw Permalink Blame History

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_MALFORMED typed 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/pushError SFTP 错误注入(错误流不产数据,忠实 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 typecheck exit 0;npm test 546 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 路径、safeExec post-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 typecheck exit 0;npm test 416 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.ts DECISION_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.occurrences JSDoc 写明滑动窗口计数 + 严格连续断链语义
  • ✅ Low 批:.gitignore + .pnpm-store/;dg_board_list source 三元表达式只算一次;extractJsonObject() 抽公共(parseClassifierJson/parseModeEvaluationJson 去重,顺带收紧 Array 分支 fail-closed)
  • ✅ 验证:npm run typecheck exit 0;npm test 403 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-exec toBeTruthy → UUID 断言;telemetry toBeDefined → trace/parent_span 格式断言;/dg-autoloop --json 补测(review nit #9);TESTING.md 整改清单 + 目录结构刷新
  • ✅ 验证:npm run typecheck exit 0;npm test 402 passed / 3 skipped(53 files)

v2.1.0 — 执行载体 + 命令日志(方法论 review 欠账修复,2026-08-14)

  • ✅ lib/runner.ts runRegisteredWorkflow:把注册 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_type command + 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 typecheck exit 0;npm test 399 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 typecheck exit 0;npm test 353 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 typecheck exit 0;npm test 323 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/resolveSince KISS 解析
  • ✅ 渲染:工具表加失败率列;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 typecheck exit 0;npm test 310 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.ts renderUsageReport(纯渲染:总览 + 工具排行表 + 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 typecheck exit 0;npm test 300 passed / 3 skipped(40 files + 1 skipped)

v1.1.1 — 上下文工程输出压缩 + poka-yoke 加固(2026-08-14)

  • ✅ Context Engineering 输出压缩(DESIGN.md §2.4 落地):
    • lib/compact.ts maybeCompact — 确定性启发式(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.ts renderCompactedOutput(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 typecheck exit 0;npm test 287 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.ts parseBuildResult — 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 typecheck exit 0;npm test 277 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_id
    • tests/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 typecheck exit 0;npm test 249 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 纯函数导出,独立单测
  • ✅ 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 typecheck exit 0;npm test 243 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 typecheck exit 0;npm test 224 passed / 3 skipped(28 files + 1 skipped)

v1.0.2 — 日志轮转 + 评审遗留修复(2026-08-14)

  • ✅ A2 日志轮转(TECH_ARCHITECTURE.md §6.1 落地):
    • lib/risk.ts maybeRotateLog: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 typecheck exit 0;npm test 214 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 typecheck exit 0;npm test 210 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.ts validateExpertType/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)
  • ✅ OpenTelemetry tracing(METHODOLOGY.md §五 全勾选):
    • lib/telemetry.ts:NodeTracerProvider + SimpleSpanProcessor + JsonlSpanExporter(JSONL 默认);DG_OTEL_ENDPOINT → OTLP/HTTP;DG_OTEL_ENABLED=0 no-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:e2e
    • tests/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 typecheck exit 0,npm test 210/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 环境变量
  • ✅ 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 typecheck exit 0,npm test 153/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.ts stale 描述: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.ts MODE_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 typecheck exit 0,npm test 89/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.json env 块)
    • SshConnectError / SshConfigError / SshExecError(带 level 信息)
    • SshExecDetails / FileSyncDetails 新增 error_type? / error_level? 字段
  • ✅ 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/pull
    • findBoardById helper(从 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 typecheck exit 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 state
    • tests/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 throw
    • tests/journeys/07-file-sync.test.ts(4)— 相对路径拒绝、push、pull
    • tests/journeys/08-board-discovery.test.ts(4)— 空配置 fallback、config 读取、loadBoardConfig、roundtrip
    • tests/journeys/09-setup-wizard.test.ts(3)— 写 settings.json、runtime registerProvider、空 API key skip
    • tests/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 + mockSshState
    • tests/helpers/mock-bonjour.ts — installBonjourMock
    • tests/helpers/tmp-fs.ts — createTmpFs 返回 {dir, boardsPath, settingsPath, cleanup, apply(utils)}
  • ✅ vitest.config.ts:新增 clearMocks: true + testTimeout: 10000
  • ✅ npm test 64/64 passed, npm run typecheck exit 0
  • ✅ v0.3.1:npm test 89/89 passed(+25 tests: camera-check 15 + safe-exec 10),npm run typecheck exit 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,不做自动模式检测(人工先于自动化)

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 手动验证(用户需做)

  1. pi install ./ 验证安装
  2. pi -e ./extensions 启动
  3. /dg-setup 走一遍向导,确认 settings.json 写入 + provider 注册
  4. /dg-mode beginner 切模式,重启 Pi 确认 mode 恢复
  5. 配置 ~/.pi/agent/dgagent-boards.json:
    {
      "version": 1,
      "boards": [
        { "id": "my-x5", "host": "192.168.1.100", "username": "root" }
      ]
    }
    
  6. /dg-board-list 确认板卡出现
  7. dg_ssh_exec 在真实板卡上跑 ros2 topic list

v0.4 起步

  1. MCP client(Wikihub):dg_kb_search 真实化(见 TECHNICAL_ARCHITECTURE.md §7.1)✅
  2. dg_model_route 真实化:规则表 + KB + LLM 三层路由(v0.5)✅
  3. 手写更多 workflow:push-and-verify(sftpPush → execOnBoard 验证)(v1.0.4)✅ / board-health(v1.0.4)✅ — DESIGN §9.3 Layer 1 工具箱 4/4
  4. DG_DEBUG + 日志轮转:实现 DG_DEBUG=1 stderr 调试输出(v1.0.3)✅ / 日志轮转(v1.0.2)✅
  5. 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 行)

关键决策速查

  1. 多 Agent 而非单 Agent — Orchestrator + 6 专家
  2. 确定性路由而非 LLM 路由 — SDB Gate、模型路由用规则表
  3. Wikihub 而非纯文件 — 知识库用 MCP + Postgres
  4. v0.2 mock 优先 — 先打通安装与 demo(用户决策)
  5. 技术架构先于代码 — 补架构文档后再继续实现
  6. ssh2 而非 node-ssh — 保留 stream 级控制(signal/timeout/error level)
  7. bonjour-service mDNS — SSH 服务发现
  8. Pi appendEntry + session_start — mode 持久化方案
  9. registerProvider runtime 安全 — Pi 源码确认,/dg-setup 可直接调
  10. node:fs 写 settings.json — Pi 无 env 写 API
  11. 脚本化自进化 — Agent 重复工具序列 → 凝固为脚本;v0.4 MVP 手写 workflow,v1.0 全自动闭环(DESIGN.md §九)