- 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)
28 KiB
DGAgent 设计方法论参考
本文档汇总 DGAgent 设计过程中引用的所有设计原则和方法论,供后续设计人员参考。 包含:Unix 设计原则、Agent 架构最佳实践、以及两者的交叉审视。
最后更新:2026-08-13(v2:吸收 DeepSeek Harness 的 Fail-closed / Monotonic Guard / Session Log 不变量等设计原则)
一、Unix 设计原则
1.1 Do One Thing Well(单一职责)
"Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features." — Doug McIlroy, Bell Labs
在 Agent 设计中的应用:
Agent 层才是单一职责的正确粒度。一个 Agent 应该是某个能力域的"专家",只做一件事。
DGAgent 的应用:
初始化 Agent → 单一职责:让系统就绪
SSH 调试 Agent → 单一职责:板卡远程执行
模型部署 Agent → 单一职责:编译→部署
感知 Agent → 单一职责:传感器/视觉
控制 Agent → 单一职责:运动/执行器
通用 Agent → 单一职责:代码/文档/知识
Orchestrator → 单一职责:意图理解→任务分派
每个 Agent 内部的工具链也遵循此原则——每个工具做一件事。
与 "Start Simple" 的辩证:
Anthropic/OpenAI 建议"先做单 Agent MVP",其语境是同一流程的微步骤拆分(如"问候→查订单→退款"本身是一个客服流程)。但 DGAgent 的初始化、SSH 调试、模型部署是本质不同的能力域,不是同一流程。因此多 Agent 不是过度设计,是正确粒度。
1.2 Everything is a File(一切皆文件)
"Everything is a file. File system is the universal namespace." — Ken Thompson
在 Agent 设计中的应用:
- 知识库 = Markdown 文件,可被任何编辑器打开,可用 git 版本控制
- 工具输出 = 纯文本流,可通过管道串联
- Agent 状态 = 可持久化的文件
DGAgent 的应用:
- LLM Wiki 知识库用纯 Markdown,Wikihub 做 MCP 暴露层
- SSH 命令输出作为文本流,Agent 分析和处理
- 配置文件用环境变量 + 文件(
$DG_API_KEY、MCP config)
文件系统 ACL vs 专用 ACL 的权衡:
纯文件系统权限(owner/group/other)只有三级,无法做细粒度 ACL。DGAgent 选择 Wikihub 的 glob ACL(/** private + 逐目录覆盖),在保持文件即知识的前提下获得灵活的访问控制。
1.3 Composability(可组合性)
"Expect the output of every program to become the input to another." — Doug McIlroy
在 Agent 设计中的应用:
Agent 的工具应产生可被下游工具消费的输出。Agent 本身也可作为管道的一环被调用。
DGAgent 的应用:
- Orchestrator 将任务分解为子任务,每个子 Agent 的输出成为下一个的输入
- 工具支持 stdin/stdout 模式,允许
echo task | dg dispatch --expert perception - 初始化 Agent 的输出(板卡 IP、Key)是 SSH Agent 和模型部署 Agent 的输入
1.4 Small is Beautiful(小而美)
"Small is beautiful. Write programs that do one thing and do it well."
DGAgent 的应用:
- 每个 Agent 专注于一个能力域,工具集精简
- 每个工具不超过 5 个核心参数,描述精确
- 不追求一个 Agent 解决所有问题
1.5 Least Surprise(最小意外)
"Programs should behave in unsurprising ways. Don't have unexpected side effects."
DGAgent 的应用:
- Orchestrator 的调度逻辑对用户透明但不意外
- SSH 高危命令必须确认(符合用户对安全的预期)
- 工具命名反映其功能,不产生歧义
- 模型路由依据确定性规则,而非 LLM 自主判断
1.6 Fail-Closed(失败即闭 / 显式失败)
"Fail loud. No silent degradation." — DeepSeek Harness AGENTS.md "Programs should refuse rather than guess." — 工程共识
核心主张:任何无法确定安全结果的路径,必须显式拒绝或报错,绝不静默降级到"尽力而为"。这是 Least Surprise 的强化形态——不仅"不意外",而且"不确定就停"。
设计规则:
- 配置缺失或非法 → load-time 失败,绝不用隐式默认值吞掉
- 能力不支持 → 显式 reject(如
UNSUPPORTED_CAPABILITY),绝不 accept-then-ignore - 工具参数非法 →
INVALID_ARGS,绝不 best-effort 解析 - 审批通道缺失 → deny,绝不 静默放行
- 沙箱/执行后端缺失 →
SANDBOX_UNAVAILABLE,绝不 静默 unconfined passthrough
DGAgent 的应用:
/dg-setup检测到 key 缺失时立即报错并引导,而非用空 key 静默继续dg_ssh_exec连接失败时返回结构化错误,而非返回空输出假装成功- SDB Gate 采用危险命令黑名单(denylist)——未命中任何危险模式的命令默认
safe直接放行;命中fatal/severe/warning按等级拦截或确认(与 KB ACL 的 fail-closed 方向相反,理由见 ADR §4.4:可逆性决定默认方向) - MCP KB 条目缺 ACL 标记 → 抛
MCP_ERR_ACL_UNKNOWN,工具层回落到带标签的降级结果,绝不默认 public(v2.1.4,ADR §4.4) - 板卡发现失败时显式告知"配置文件缺失 + mDNS 无响应",而非返回空列表假装无板卡
与 Least Surprise 的区别:Least Surprise 面向用户预期("别让用户意外"),Fail-Closed 面向系统健壮性("系统自己不确定时必须停")。前者是体验原则,后者是可靠性原则,二者互补。
来源:DeepSeek Harness 的 fail-closed 设计(sandbox / approval / guard 全链路均 fail-closed)。
二、软件工程原则与嵌入式开发原则
DGAgent 帮助用户开发嵌入式软件。其生成的代码和指导的项目结构必须遵循以下原则。
2.1 通用软件工程原则
| 原则 | 全称 | 含义 |
|---|---|---|
| SRP | Single Responsibility Principle | 一个模块只有一个职责,只有一个理由去修改它 |
| OCP | Open/Closed Principle | 对扩展开放,对修改关闭——新功能通过扩展而非修改实现 |
| DRY | Don't Repeat Yourself | 每个知识点在系统中有唯一、明确的表示 |
| KISS | Keep It Simple, Stupid | 优先选择最简单的方案,不过度设计 |
| YAGNI | You Ain't Gonna Need It | 不实现当前不需要的功能 |
| LoD | Law of Demeter | 模块只和直接依赖通信,不跨越层级 |
SOLID 详解:
| 原则 | 说明 | 嵌入式示例 |
|---|---|---|
| S - 单一职责 | 一个类只做一件事 | camera_driver 只读摄像头数据,不负责推理 |
| O - 开闭原则 | 扩展代替修改 | 新增传感器类型时加子类,不改 base_driver |
| L - 里氏替换 | 子类可替换父类 | 任何 SensorDriver 子类都可用在 sensor_manager 中 |
| I - 接口隔离 | 不强迫依赖不需要的方法 | IMU 接口不包含 camera 的 start_streaming() |
| D - 依赖反转 | 依赖抽象而非具体实现 | 应用层依赖 SensorInterface,不依赖 MIPI_Camera |
2.2 嵌入式特有工程原则
| 原则 | 含义 | 为什么重要 |
|---|---|---|
| HAL | 硬件抽象层——应用代码不直接操作硬件寄存器 | 换芯片/板卡时只改 HAL,不改业务逻辑 |
| 数据驱动 | "没有硬件,只有数据流"——先设计数据,再写处理逻辑 | 让软件可测试、可移植,脱离硬件也能跑 |
| 桌面先行 | 在桌面上完成尽可能多的测试,硬件只在最终验证 | 开发效率差 10-100 倍,桌面秒级反馈 |
| 早集成 | 不要等到最后才上板,尽早频繁在真实硬件上验证 | 集成问题发现越晚代价越大 |
| 先 Profile 再优化 | 用性能分析工具定位瓶颈,不靠直觉优化 | 嵌入式资源有限,盲目优化浪费精力 |
| 自动化 | 烧录、调试、复位等重复操作脚本化 | 减少人为错误,新人上手更快 |
2.3 DGAgent 中的应用
生成的代码结构:
project/
├── hal/ # 硬件抽象层 — 芯片/板卡相关
│ ├── gpio.h
│ └── spi.h
├── drivers/ # 驱动层 — 外设封装
│ ├── camera_mipi.cpp
│ └── imu_spi.cpp
├── app/ # 应用层 — 业务逻辑
│ ├── detector.cpp
│ └── controller.cpp
└── test/ # 测试 — 桌面可运行
├── mock_hal.cpp
└── test_detector.cpp
Agent 行为约束:
- 生成代码时分层,不允许应用层直接访问
/dev/i2c-*等硬件接口 - 提示用户"先在桌面验证"而非"直接上板"
- 编译后主动跑
colcon build验证 - 不生成过度抽象的代码——嵌入式资源有限,KISS 优先于 DRY
- 每次代码生成至少解释一个工程决策的理由
2.4 新手模式中的工程教育
新手模式不仅是 RDK 操作教学,更是嵌入式工程方法的 mentorship:
- 写代码前先讨论数据流设计
- 用户想走捷径时解释为什么是坏习惯(而非禁止)
- 编译失败时教排查方法论,而非只报错
- 引入 SRP/DRY/HAL 等概念但不灌输术语——展示行为而非背诵定义
- 不预设用户懂任何专业术语,首次提及时附一句话解释
三、Agent 设计方法论
3.1 Workflow vs Agent 区分
来源: Anthropic "Building Effective Agents"
| Workflow | Agent | |
|---|---|---|
| 控制流 | 预定义代码路径 | LLM 自主决定 |
| 适合场景 | 步骤可预测的固定流程 | 开放性任务,步数不可预知 |
| 成本 | 低(少 LLM 调用) | 高(多轮推理) |
| 可预测性 | 高 | 低 |
| DGAgent 示例 | 模型 OE 编译→部署 | 板卡故障诊断 |
设计规则:
- 已知步骤的流程 → 走 Workflow(确定性)
- 需要探索的任务 → 走 Agent Loop
- 大多数系统应该混合使用两种模式
3.2 Tool Design First(工具设计优先)
来源: Anthropic "Writing Effective Tools for AI Agents"
Anthropic SWE-bench 团队花在优化工具上的时间比整体 prompt 还多。
工具设计原则:
- 工具描述比工具名重要 — 像给初级工程师写 docstring,包含用法示例和边界条件
- 一个概念一个工具 — 两个工具都能回答同一个问题 = 架构缺陷
- 返回值只含高信号信息 — 去掉 uuid、mime_type、内部 ID 等技术噪声
- 用
response_format枚举 — 让 Agent 控制输出详细程度(concise/detailed) - Poka-yoke(防呆设计) — 修改参数让错误更难发生(如强制绝对路径)
- 命名空间分组 — 相关工具用前缀分组(
rdk_ssh_*、rdk_board_*) - 不要让工具之间存在重叠功能 — 这是最常见的架构错误
- UI 投影与数据分离 — 工具返回结构化数据(由
outputschema 定义),渲染由独立的纯函数处理(render(args)→ 卡片 / 终端 / diff / 搜索结果)。数据是契约,展示是投影,两者解耦——同一份工具结果可同时供模型消费(JSON)和人类消费(卡片),互不污染 - 工具名可配置 — 工具名支持 load-time 重命名,避免模型对固定名称形成"习惯污染"后难以迁移;也便于 A/B 测试不同命名对模型调用准确率的影响
- result 不可变 — 工具结果经 finalize 后冻结,后续 guard / post-execute 不能篡改已发出的结果,保证"模型看到的 ⟺ 审计日志记录的"
- timeout 对模型不可见 —
timeoutMs是工具执行参数,不进 schema 暴露给模型——模型不应为了"赶时间"而降低推理质量;超时是系统约束,不是模型决策
工具评估流程:
原型 → 生成真实场景测试用例 → 跑评估 → 让 Agent 分析失败 → 改进工具 → 再评估
3.3 SDB — 随机-确定性边界
来源: Stanford "Runtime Architecture Patterns for Production LLM Agents"
71% 的 Agent 故障发生在 LLM 输出与确定性系统动作之间的边界。
核心概念:
SDB(Stochastic-Deterministic Boundary)是 LLM 的随机输出转换为系统确定性动作的接口。这个边界应作为一等架构元素设计,而非隐式代码。
六种运行时架构模式:
| 模式 | 名称 | 用途 | DGAgent 应用 |
|---|---|---|---|
| P1 | 层级委派 | Orchestrator → Specialist | ✅ Agent 矩阵本身 |
| P2 | Scatter-Gather + Saga | 并行 + 补偿回滚 | ⚠️ 多专家并行执行时 |
| P3 | 事件驱动 | Append-only log | 会话日志 |
| P4 | Supervisor + Gate | 策略门验证 | ⚠️ 专家输出验证 |
| P5 | 共享状态机 | Compare-and-swap | — |
| P6 | Human in the Loop | 人工审批 | ✅ SSH 高危命令确认 |
设计规则:
- 每个 LLM→系统边界都应有 Gate
- Gate 是确定性代码,不依赖 LLM 判断
- 模型路由决策应走确定性规则,不应让 LLM 自己选模型
Monotonic Guard 不变量:
多个 Guard 串联时必须满足单调性——Guard 只能 deny,不能 allow。即:一旦某层 Guard 决定拒绝,后续 Guard 无论如何不能把拒绝翻回允许。这保证了 Guard 的顺序无关正确性,只影响性能(早 deny 省后续开销)。
工具调用 → [G1: 只能 deny?] → [G2: 只能 deny?] → ... → [Gn: 只能 deny?] → execute
↑ Guard 只能叠加拒绝,不能叠加允许
为什么重要:若 Guard 能 allow,则 Guard 顺序会成为安全正确性的隐式依赖——调换两个 Guard 的注册顺序就可能从"拒绝"变成"放行",这是极难排查的安全漏洞。强制单调性后,Guard 可任意重排、增删,安全语义不变。
DGAgent 的应用:assessRisk 当前是单一函数返回一个风险等级,天然单调。但当未来叠加更多 Gate(如板卡状态检查、用户配额检查、时间段限制)时,必须保持"只能升险不能降险"的单调性——多个 Gate 的结果取最严格的,而非"任一通过即通过"。
3.4 Context Engineering(上下文工程)
来源: Anthropic "Effective Context Engineering for AI Agents" + Andrej Karpathy
"Context engineering = curating the smallest set of high-signal tokens that maximize desired outcomes."
关键策略:
| 策略 | 说明 | DGAgent 应用 |
|---|---|---|
| 渐进式披露 | Agent 逐步探索,按需加载上下文 | MCP 知识库查询 |
| Compaction | 超长对话压缩摘要后重置窗口 | SSH 长会话输出 |
| 结构化笔记 | Agent 主动写 NOTES.md 持久化 | 跨轮记忆 |
| 子 Agent 压缩 | 子 Agent 深入工作后只返回 1000-2000 token 摘要 | 专家 Agent 输出 |
| 上下文编辑 | 清除过期的 tool results 和 thinking blocks | Agent 循环内 |
| Session Log 即真相源 | 所有 model-visible 内容必须落入持久日志,且日志可重建完整上下文 | 审计日志 + 风险日志(待扩展) |
"Model-visible ⟺ Logged" 不变量:凡模型在上下文中看到的内容(工具结果、system prompt、历史消息、用户确认),必须 100% 可从持久化日志重建。这不仅是为了审计,更是为了可调试——任何一次"模型为何这样决策"的追问,都应能从日志回放完整上下文。
DGAgent 现状与差距:当前 writeAuditLog 只记 SSH 命令本身,不记工具 I/O 全量、风险评估过程、用户确认交互。未来应扩展为全量 session log,并加 runtime 校验:若某条 model-visible 内容不在日志中,启动时即报错(呼应 §1.6 Fail-Closed)。这是从"事后审计"升级到"可重放真相源"的关键一步。
3.5 12-Factor Agent
来源: 12-Factor App 方法论向 Agent 的延伸
| # | Factor | 说明 | DGAgent 适用性 |
|---|---|---|---|
| 1 | NL → Tool Calls | Agent 的职责是意图翻译成函数调用 | ✅ 核心设计 |
| 2 | Own Your Prompts | Prompt 是代码,版本控制 | ✅ |
| 3 | Own Your Context Window | 主动管理上下文,不无限 append | ⚠️ 需要实现 |
| 4 | Tools as Structured Outputs | 工具参数强类型(JSON Schema/Zod) | ✅ Pi TypeBox |
| 5 | Unify State | Agent 状态 = 业务状态,不是内存变量 | ⚠️ |
| 7 | Contact Humans via Tools | 人工干预是工具调用 | ✅ SSH 审批 |
| 8 | Own Your Control Flow | LLM 不决定控制流,代码决定 | ⚠️ 模型路由 |
| 9 | Compact Errors into Context | 错误喂回 LLM 自纠正 | ✅ |
| 10 | Small, Focused Agents | 不要 God Agent | ✅ |
| 11 | Trigger From Anywhere | 可被 webhook/email/cron 触发 | — |
| 12 | Stateless Reducer | (State, Event) → NewState |
⚠️ |
3.6 Multi-Agent Orchestrator-Worker
来源: Anthropic Multi-Agent Research System
核心经验:
- 教 Orchestrator 如何委派 — 每个子 Agent 需要:目标、输出格式、可用工具、任务边界、伸缩预算
- 按查询复杂度伸缩 — 简单任务 1 Agent + 3-10 工具调用,复杂研究 10+ Agent
- 并行是性能关键 — 3-5 子 Agent 并行 + 每个 Agent 内工具并行,复杂查询时间降低 90%
- 让 Agent 自我改进工具 — 用 Agent 测试和重写工具描述,可降低 40% 时间
- 先广后窄 — 搜索策略:先短宽查询探索,再逐步收窄
3.7 Control Plane as a Tool
来源: "Control Plane as a Tool: A Scalable Design Pattern for Agentic AI Systems"
核心思想:
Agent 只看到一个 control_plane 工具,后端的路由、验证、工具选择对 Agent 透明。适用于工具数量 > 15 或存在大量工具重叠的场景。
DGAgent 的应用:
Orchestrator 本身就是 Control Plane 的实现——用户不需要知道有哪些专家 Agent,只需描述目标。
3.8 Start Simple, Then Scale
来源: Anthropic + OpenAI + Google Cloud(三方共识)
"Success isn't about building the most sophisticated system. Start with simple prompts, optimize them, and add multi-step only when simpler solutions fall short."
DGAgent 的辩证应用:
此原则适用于同一流程内的微步骤拆分(如客服流程拆成太多 Agent)。但 DGAgent 的子领域天然独立——初始化、SSH 调试、模型部署、感知调试是不同的能力域,多 Agent 是正确粒度,非过度设计。
正确的 "Start Simple" 策略:
- 不需要一次建 6 个 Agent → 从最痛的场景开始(如 SSH 调试)
- 每个 Agent 先做最小工具集,验证可用后再扩展
- Orchestrator 先做简单路由,逐步增加编排智能
适用域注脚(重要):
"Start Simple" 成立的前提是——系统可以渐进交付,且早期不完整不会致命。这对内部工具(DGAgent)成立,对市场竞争力产品不成立。当产品要正面回应竞品(如 DeepSeek Harness 对标 OpenAI Codex / Anthropic Claude Code)时,必须"一出生就是完整 harness",此时"先建地基再追稳定性"(foundation over blast radius)是合理策略。
判断标准:
- 若早期缺失某能力会直接丢客户/丢市场 → 不适用 Start Simple,必须先建地基
- 若只是内部效率损失(如 DGAgent v0.3 时代的 mock 工具,现已全部真实化) → 适用 Start Simple,渐进真实化
反例参考:DeepSeek Harness v0.1.0-rc.5 即 vendor 整个 Cordis 框架 + 50+ 包预建,明确声明 "developer preview, compatibility-breaking changes expected"——这是商业产品逻辑,非过度设计。DGAgent 作为 Pi Extension,不应照搬此策略。
四、DGAgent 架构决策记录
4.1 为什么多 Agent 而非单 Agent MVP?
决策: 多 Agent(Orchestrator-Worker)
理由:
- 初始化、SSH 调试、模型部署、感知调试是本质不同的能力域
- 强行合并违反 Unix 单一职责原则
- 每个 Agent 由独立团队(或地瓜)维护不同的专家模型
- "Start Simple" 建议在此不适用——它不是同一流程的微步骤
但:
- 不需要一次建全部 Agent
- 从最痛的场景开始,逐步扩展
4.2 为什么 Orchestrator 是唯一用户入口?
决策: Orchestrator 是用户唯一的对话界面
理由:
- 多 Agent 复杂度对用户完全透明
- 用户只需描述目标,Orchestrator 负责分解和编排
- 对齐 Control Plane as a Tool 模式
- 降低使用门槛
4.3 为什么 Wikihub 而非纯文件 ACL?
决策: Wikihub(文件 + glob ACL + Postgres 索引)
理由:
- 纯文件 ACL 只有三级(owner/group/other),无法做 public/partner/internal 分层
- Wikihub 的 glob ACL 支持细粒度访问控制
- Postgres 提供搜索索引,弥补纯 ripgrep 的搜索质量差距
- 仍然是 Markdown 文件,可被 git 版本控制
- Karpathy 本人在 LLM Wiki gist 中建议使用搜索工具
4.4 为什么 KB ACL fail-closed,而 SDB 黑名单 fail-open?(v2.1.4)
决策: 两套相反的默认方向,按资产可逆性分流。
- SDB Gate(命令风险):denylist 未命中 → 默认
safe放行(fail-open-for-usability,§3.3) - KB ACL(文档可见性):条目缺 ACL 标记 →
MCP_ERR_ACL_UNKNOWN拒绝,绝不默认 public(fail-closed)
理由:
- 命令执行是可审计、可恢复的开发操作——过度拦截会毁掉可用性(每个
ls都要确认是灾难) - 文档可见性错配是数据泄露——一次静默放行即不可逆,且用户无从察觉
- 可逆性决定默认方向:不可逆的走闭,可逆的走开
- fail-closed 的代价(工具层回落到带标签的 mock 结果,用户可见降级原因)可接受且有提示
但:
- 工具层仍提供带
mock标签的降级结果,保证缺元数据的 KB 不会让dg_kb_search彻底不可用 - 若 Wikihub 侧未来保证 ACL 字段必填,此 Gate 变为纯断言
4.5 为什么连接池在途去重 + exec 硬截止 + 输出背压?(v2.1.4)
决策: BoardConnectionPool 三条硬规则:busy 引用计数不淘汰、同板卡在途连接去重(共享 connecting Promise,单一 TCP)、exec 超时 SIGTERM→SIGKILL 硬截止 + 输出超 50KB 停止缓冲。
理由:
- 淘汰在用连接会截断进行中的命令流——evict 必须跳过 busy 连接(否则用户命令被池管理"随机杀死")
- 同板卡并发请求各自开 TCP 会在板卡侧制造 SSH 会话风暴(嵌入式板卡 authd 资源有限)——去重后并发 N 请求 = 1 条 TCP
- 只发 SIGTERM 不清理定时器、不跟进 SIGKILL,僵死进程会吃满板卡内存——硬截止是嵌入式目标的物理约束
- 无上限缓冲意味着一条
cat big.log就能 OOM 主机 agent——背压是自保
但:
- 截断的输出显式置
stdout_truncated/stderr_truncated标志,不静默截断(fail-closed 的呈现层应用)
五、设计评审清单
以下清单用于评审 Agent 设计是否合理:
Agent 层面
- 每个 Agent 是否只有一个明确的职责?
- Agent 之间是否有清晰边界,不重叠?
- 用户是否需要知道 Agent 矩阵才能使用?理想答案是"不需要"
工具层面
- 每个工具是否只有一个用途,不与其他工具重叠?
- 工具描述是否包含了使用示例和边界条件?
- 工具参数是否强类型(JSON Schema)?
- 工具返回值是否只包含高信号信息?
- 是否有 Poka-yoke(防呆设计)?
控制流层面
- 关键控制流(路由、审批、验证)是否走确定性代码,而非 LLM 判断?
- 每个 LLM→系统边界是否都有 Gate?
- 是否有最大回合数限制和死循环检测?
上下文层面
- 长对话是否有 compaction 策略?
- 工具输出是否会撑爆上下文窗口?
- 是否有跨轮记忆机制?
可观测性层面
- 每次工具调用是否记录时间、token、结果?
- 是否有 tracing 支持(OpenTelemetry)?
- 失败能否追溯到具体步骤?
六、参考文献
- Anthropic — "Building Effective Agents" (2024) — 链接
- Anthropic — "Writing Effective Tools for AI Agents" (2025) — 链接
- Anthropic — "Effective Context Engineering for AI Agents" (2025) — 链接
- Anthropic — "How We Built Our Multi-Agent Research System" (2025) — 链接
- OpenAI — "A Practical Guide to Building Agents" (2025) — 链接
- Google Cloud — "Choose a Design Pattern for Your Agentic AI System" — 链接
- Stanford — "A Methodology for Selecting and Composing Runtime Architecture Patterns for Production LLM Agents" (2025) — alphaXiv
- 12-Factor Agent — "The 12-Factor Agent Methodology" — Pedro Alonso
- Control Plane as a Tool — "A Scalable Design Pattern for Agentic AI Systems" (2025) — arXiv
- Production-Grade Agentic AI Workflows — "Nine Best Practices" (2025) — arXiv
- LLLM — "Agentic System Design Philosophy" — 链接
- Andrej Karpathy — "LLM Wiki Pattern" — GitHub Gist
- Databricks — "Agent System Design Patterns" — 链接
- Kunwar — "Designing an Agent Orchestration Layer" (Chapter 72) — 链接
测试原则见
TESTING.md。 12 条原则 + 套件整改清单 + 旅程→测试文件一一对应表,是测试代码的设计契约。
测试方法论参考(详见 TESTING.md)
- Kent Beck — Test-Driven Development: By Example (Addison-Wesley, 2002)
- Mike Cohn — Succeeding with Agile (Addison-Wesley, 2009), Ch. 16
- Gerard Meszaros — xUnit Test Patterns (Addison-Wesley, 2007)
- Martin Fowler — "TestPyramid" (2012) / "Mocks Aren't Stubs" (2007) / "UnitTest" (2014)
- Kent C. Dodds — "Write tests. Not too many. Mostly integration." (2019) / "The Testing Trophy" (2021) / "AHA Testing" (2021)
- J.B. Rainsberger — "Integrated Tests Are A Scam" (2009)
- Guillermo Rauch — tweet (Dec 10, 2016)
- Paseo —
getpaseo/paseo测试哲学 - MSW —
mswjs/mswCONTRIBUTING.md - Epicenter —
epicenterhq/epicenter测试 skill - Kent Beck — Test-Driven Development: By Example (Addison-Wesley, 2002)
- Mike Cohn — Succeeding with Agile (Addison-Wesley, 2009), Ch. 16
- Gerard Meszaros — xUnit Test Patterns (Addison-Wesley, 2007)
- Martin Fowler — "TestPyramid" (martinfowler.com, 2012) / "Mocks Aren't Stubs" (2007) / "UnitTest" (2014)
- Kent C. Dodds — "Write tests. Not too many. Mostly integration." (2019) / "The Testing Trophy" (2021) / "AHA Testing" (2021)
- J.B. Rainsberger — "Integrated Tests Are A Scam" (blog.thecodewhisperer.com, 2009)
- Guillermo Rauch — tweet (Dec 10, 2016) — "Write tests. Not too many. Mostly integration."
- Paseo —
getpaseo/paseo测试哲学 — 链接 - MSW —
mswjs/mswCONTRIBUTING.md — 链接 - Epicenter —
epicenterhq/epicenter测试 skill — 链接