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

28 KiB
Raw Permalink Blame History

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 还多。

工具设计原则:

  1. 工具描述比工具名重要 — 像给初级工程师写 docstring,包含用法示例和边界条件
  2. 一个概念一个工具 — 两个工具都能回答同一个问题 = 架构缺陷
  3. 返回值只含高信号信息 — 去掉 uuid、mime_type、内部 ID 等技术噪声
  4. 用 response_format 枚举 — 让 Agent 控制输出详细程度(concise / detailed)
  5. Poka-yoke(防呆设计) — 修改参数让错误更难发生(如强制绝对路径)
  6. 命名空间分组 — 相关工具用前缀分组(rdk_ssh_*、rdk_board_*)
  7. 不要让工具之间存在重叠功能 — 这是最常见的架构错误
  8. UI 投影与数据分离 — 工具返回结构化数据(由 output schema 定义),渲染由独立的纯函数处理(render(args) → 卡片 / 终端 / diff / 搜索结果)。数据是契约,展示是投影,两者解耦——同一份工具结果可同时供模型消费(JSON)和人类消费(卡片),互不污染
  9. 工具名可配置 — 工具名支持 load-time 重命名,避免模型对固定名称形成"习惯污染"后难以迁移;也便于 A/B 测试不同命名对模型调用准确率的影响
  10. result 不可变 — 工具结果经 finalize 后冻结,后续 guard / post-execute 不能篡改已发出的结果,保证"模型看到的 ⟺ 审计日志记录的"
  11. 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

核心经验:

  1. 教 Orchestrator 如何委派 — 每个子 Agent 需要:目标、输出格式、可用工具、任务边界、伸缩预算
  2. 按查询复杂度伸缩 — 简单任务 1 Agent + 3-10 工具调用,复杂研究 10+ Agent
  3. 并行是性能关键 — 3-5 子 Agent 并行 + 每个 Agent 内工具并行,复杂查询时间降低 90%
  4. 让 Agent 自我改进工具 — 用 Agent 测试和重写工具描述,可降低 40% 时间
  5. 先广后窄 — 搜索策略:先短宽查询探索,再逐步收窄

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)?
  • 失败能否追溯到具体步骤?

六、参考文献

  1. Anthropic — "Building Effective Agents" (2024) — 链接
  2. Anthropic — "Writing Effective Tools for AI Agents" (2025) — 链接
  3. Anthropic — "Effective Context Engineering for AI Agents" (2025) — 链接
  4. Anthropic — "How We Built Our Multi-Agent Research System" (2025) — 链接
  5. OpenAI — "A Practical Guide to Building Agents" (2025) — 链接
  6. Google Cloud — "Choose a Design Pattern for Your Agentic AI System" — 链接
  7. Stanford — "A Methodology for Selecting and Composing Runtime Architecture Patterns for Production LLM Agents" (2025) — alphaXiv
  8. 12-Factor Agent — "The 12-Factor Agent Methodology" — Pedro Alonso
  9. Control Plane as a Tool — "A Scalable Design Pattern for Agentic AI Systems" (2025) — arXiv
  10. Production-Grade Agentic AI Workflows — "Nine Best Practices" (2025) — arXiv
  11. LLLM — "Agentic System Design Philosophy" — 链接
  12. Andrej Karpathy — "LLM Wiki Pattern" — GitHub Gist
  13. Databricks — "Agent System Design Patterns" — 链接
  14. Kunwar — "Designing an Agent Orchestration Layer" (Chapter 72) — 链接

测试原则见 TESTING.md。 12 条原则 + 套件整改清单 + 旅程→测试文件一一对应表,是测试代码的设计契约。

测试方法论参考(详见 TESTING.md)

  1. Kent Beck — Test-Driven Development: By Example (Addison-Wesley, 2002)
  2. Mike Cohn — Succeeding with Agile (Addison-Wesley, 2009), Ch. 16
  3. Gerard Meszaros — xUnit Test Patterns (Addison-Wesley, 2007)
  4. Martin Fowler — "TestPyramid" (2012) / "Mocks Aren't Stubs" (2007) / "UnitTest" (2014)
  5. Kent C. Dodds — "Write tests. Not too many. Mostly integration." (2019) / "The Testing Trophy" (2021) / "AHA Testing" (2021)
  6. J.B. Rainsberger — "Integrated Tests Are A Scam" (2009)
  7. Guillermo Rauch — tweet (Dec 10, 2016)
  8. Paseo — getpaseo/paseo 测试哲学
  9. MSW — mswjs/msw CONTRIBUTING.md
  10. Epicenter — epicenterhq/epicenter 测试 skill
  11. Kent Beck — Test-Driven Development: By Example (Addison-Wesley, 2002)
  12. Mike Cohn — Succeeding with Agile (Addison-Wesley, 2009), Ch. 16
  13. Gerard Meszaros — xUnit Test Patterns (Addison-Wesley, 2007)
  14. Martin Fowler — "TestPyramid" (martinfowler.com, 2012) / "Mocks Aren't Stubs" (2007) / "UnitTest" (2014)
  15. Kent C. Dodds — "Write tests. Not too many. Mostly integration." (2019) / "The Testing Trophy" (2021) / "AHA Testing" (2021)
  16. J.B. Rainsberger — "Integrated Tests Are A Scam" (blog.thecodewhisperer.com, 2009)
  17. Guillermo Rauch — tweet (Dec 10, 2016) — "Write tests. Not too many. Mostly integration."
  18. Paseo — getpaseo/paseo 测试哲学 — 链接
  19. MSW — mswjs/msw CONTRIBUTING.md — 链接
  20. Epicenter — epicenterhq/epicenter 测试 skill — 链接