\r \r

Agent Harness Engineer v3\r

\r 本 Skill 将帮助你设计、实现和优化生产级的 AI Agent 系统，当前是 v3 版本。\r \r 本版本采用分阶段构建模式，将 Agent 系统构建拆分为 7 个明确的阶段，每个阶段都有：\r

• 理论指导：该阶段需要应用什么设计原则\r
• 抽象接口层：定义而非实现，引导 AI 根据需求生成代码（v3 核心变更）\r
• AI 构建提示：在关键位置给出引导，告诉 AI 应该生成什么\r
• 检查清单：完成标准是什么（按规模分级）\r
• 常见问题：这个阶段容易踩什么坑\r \r

v3 核心变更（必读）\r

\r

变更1：三级构建规模\r

\r Agent 系统不再只有一种构建方式。根据用户需求，分为三级：\r \r

┌───────────────────┬───────────────────────┬──────────────────────────┬──────────────────────────┐\r
│  维度             │  Minimal（最小）       │  Professional（专业）     │  Enterprise（企业）       │\r
├───────────────────┼───────────────────────┼──────────────────────────┼──────────────────────────┤\r
│  目标             │  快速原型/学习验证     │  团队工具/生产级应用      │  企业平台/高并发/多租户   │\r
│  预期代码量       │  ~300-500行           │  ~2000-4000行            │  ~6000-10000行+          │\r
│  第三方库         │  仅SDK（1-2个）       │  5-8个关键库             │  10+个全套生态栈         │\r
│  沙箱             │  路径白名单检查        │  Docker容器隔离           │  Firecracker微VM隔离      │\r
│  日志             │  print() / console.log│ structlog / loguru / pino│  OpenTelemetry 全链路     │\r
│  CLI              │  input() / 简单argparse│ click / typer / commander│  rich + 交互式TUI         │\r
│  配置管理         │  .env 文件            │  YAML + pydantic/zod     │  7级层级化配置覆盖        │\r
│  测试             │  手动测试或无          │  pytest/jest + mock      │  pytest/jest + CI/CD      │\r
│  监控             │  无                   │  基础 metrics 计数器     │  Prometheus + Grafana     │\r
│  上下文压缩       │  仅 Snip（历史截断）   │  完整四级压缩管道         │  四级 + 压缩状态恢复      │\r
│  记忆系统         │  无                   │  文件系统持久化           │  向量数据库 + 自动做梦    │\r
│  MCP集成          │  无                   │  基础 stdio MCP          │  全协议 + 连接池管理      │\r
│  多Agent          │  不支持               │  可选（Coordinator）     │  支持（Coordinator+Swarm）│\r
└───────────────────┴───────────────────────┴──────────────────────────┴──────────────────────────┘\r
```\r
\r
### 变更2：代码生成禁止复制策略\r
\r
> **关键规则：AI coding工具必须根据用户需求设计并生成代码，不得直接复制 reference 文件或 template 文件中的代码片段。**\r
> \r
> Reference 文件中的代码已从"完整实现"改为"抽象接口/类定义 + AI构建提示"。\r
> Template 文件中的代码已从"完整实现"改为"骨架 + TODO + AI构建提示"。\r
>\r
> **为什么？** 之前的 reference 和 template 中包含完整可运行代码（如 read_file 实现、sandbox 实现），AI工具会直接复制，导致生成的系统永远是"最小实现"，无法根据用户需求调整复杂度和技术栈。\r
\r
**AI coding工具的正确行为：**\r
1. 阅读 reference 中的抽象接口定义，理解需要哪些方法和属性\r
2. 阅读 reference 中的设计原理，理解为什么这样设计\r
3. 根据用户选择的规模和用途，决定生成代码的复杂度和完整度\r
4. 参考 technology-stack.md 选择合适的三方库\r
5. **自己设计并编写代码**，而非复制粘贴\r
\r
### 变更3：技术栈分级推荐\r
\r
参考 `references/11-technology-stack.md`，每个维度（日志、CLI、HTTP、沙箱、监控等）都提供 Minimal / Professional / Enterprise 三级推荐方案。AI 必须根据用户选择的规模，选择对应级别的技术栈。\r
\r
## 快速导航\r
\r
- **[SKILL.md](SKILL.md)** (本文件): 核心原则、构建规模分级、代码生成策略\r
- **[references/01-phase-init.md](references/01-phase-init.md)**: Phase 1: 项目初始化（三级规模目录结构）\r
- **[references/02-phase-llm.md](references/02-phase-llm.md)**: Phase 2: LLM抽象层（含streaming、retry、token计数接口）\r
- **[references/03-phase-tools.md](references/03-phase-tools.md)**: Phase 3: 工具系统（含concurrency分区算法、MCP adapter）\r
- **[references/04-phase-agent-loop.md](references/04-phase-agent-loop.md)**: Phase 4: Agent核心循环（含状态机、7个continue站点、流式架构）\r
- **[references/05-phase-context.md](references/05-phase-context.md)**: Phase 5: 上下文管理（含四级压缩完整算法、Session WAL设计）\r
- **[references/06-phase-permissions.md](references/06-phase-permissions.md)**: Phase 6: 权限安全（含5种模式、7级规则、6层防御、沙箱技术对比）\r
- **[references/07-phase-production.md](references/07-phase-production.md)**: Phase 7: 生产化（含OpenTelemetry、三层可观测、CI/CD）\r
- **[references/08-core-concepts.md](references/08-core-concepts.md)**: 核心概念速查（三大支柱、三组件虚拟化、13条防护规则）\r
- **[references/09-multi-agent.md](references/09-multi-agent.md)**: 多智能体（子Agent隔离设计、Token节省量化、Worktree隔离）\r
- **[references/10-mcp-integration.md](references/10-mcp-integration.md)**: MCP集成（6种传输协议、连接池、OAuth、资源管理）\r
- **[references/11-technology-stack.md](references/11-technology-stack.md)**: 技术栈分级选择指南（日志/CLI/HTTP/沙箱/监控/测试/数据库）\r
- **[references/12-sandbox-advanced.md](references/12-sandbox-advanced.md)**: 沙箱深度设计（Docker/Firecracker/gVisor/Wasm对比、bubblewrap集成）\r
- **[references/13-session-design.md](references/13-session-design.md)**: 会话设计（WAL模式、事件类型、状态机、回放恢复机制）\r
- **[references/14-observability.md](references/14-observability.md)**: 可观测性（OpenTelemetry/Prometheus/Langfuse集成、结构化日志）\r
- **[templates/minimal/](../templates/minimal/)**: Minimal 规模脚手架模板\r
- **[templates/professional/](../templates/professional/)**: Professional 规模脚手架模板\r
- **[templates/enterprise/](../templates/enterprise/)**: Enterprise 规模脚手架模板\r
\r
## 核心原则\r
\r
### 1. Harness Engineering 三大支柱\r
\r
- **Context Engineering（上下文工程）**: 管理信息的可访问性、结构和时机\r
  - 静态上下文：CLAUDE.md/AGENTS.md、设计文档\r
  - 动态上下文：日志、指标、Git状态、CI/CD状态\r
  - 上下文压缩：四级管道（Snip → Microcompact → Context-Collapse → Autocompact）\r
  - 核心原则: "Agent无法在上下文中访问的信息不存在"\r
\r
- **Architectural Constraints（架构约束）**: 通过机械执行而非建议来建立边界\r
  - 权限模型：5种模式 × 7级规则层级\r
  - 工具约束：Schema验证、并发安全标记\r
  - 安全边界：沙盒隔离、硬编码拒绝、纵深防御（6层）\r
\r
- **Entropy Management（熵管理）**: 定期清理Agent解决代码退化\r
  - 文档一致性验证、约束违规扫描、模式强制执行\r
  - 依赖审计、性能监控、覆盖率守卫\r
\r
### 2. 三组件虚拟化架构\r
\r
```\r
Session（会话）= 追加式事件日志（Append-only Event Log）\r
  - 不可变、可序列化、可回放\r
  - 类似数据库WAL，是系统的唯一事实来源\r
  - 支持故障恢复、负载迁移、调试回放\r
\r
Harness（编排器）= 无状态编排循环\r
  - 全部输入来自Session日志\r
  - 可随时崩溃、重启、迁移\r
  - 给定同样的Session日志，任何实例都会做出同样决策\r
\r
Sandbox（沙箱）= 隔离执行环境\r
  - 文件系统隔离、网络隔离、进程隔离\r
  - 凭证外置，按需创建和销毁\r
  - 限制爆炸半径（Blast Radius Containment）\r
```\r
\r
## 需求确认（构建前的必要步骤）\r
\r
> **重要：在开始构建Agent之前，必须先确认用户需求。**\r
> **如果用户已经明确提供了以下信息，可以跳过本环节。**\r
> **如果用户没有提供，AI coding工具必须主动询问用户做选择，不得自行决定。**\r
\r
### 需要确认的问题\r
\r
当用户说"帮我构建一个Agent"但没有明确说明以下信息时，AI coding工具必须主动询问：\r
\r
| 问题 | 选项/说明 | 影响 |\r
|------|---------|------|\r
| **技术栈偏好？** | Python / Node.js / TypeScript / Go | 决定项目脚手架语言 |\r
| **LLM供应商？** | Anthropic / OpenAI / Azure / 本地模型 | 决定默认配置 |\r
| **构建规模？** | Minimal / Professional / Enterprise | 决定项目复杂度、代码量、三方库数量 |\r
| **主要用途？** | 编码助手 / 自动化运维 / 数据分析 / 通用对话 / 其他 | 决定工具集 |\r
| **部署环境？** | 本地 / 云服务器 / 容器 / Serverless | 决定配置方式 |\r
| **沙箱隔离需求？** | 无 / 基础路径检查 / Docker隔离 / Firecracker微VM | 决定安全方案 |\r
| **监控需求？** | 无 / 基础日志 / 全链路追踪(Prometheus+OpenTelemetry) | 决定可观测方案 |\r
| **是否需要多Agent协作？** | 是 / 否 | 决定是否需要Phase 9内容 |\r
\r
### 询问示例\r
\r
如果用户说"帮我构建一个Agent"，但没有提供上述信息，AI coding工具应该这样询问：\r
\r
```\r
在开始构建Agent之前，我需要确认几个问题：\r
\r
1. **技术栈偏好**：\r
   - Python（推荐，功能完善）\r
   - Node.js/TypeScript\r
\r
2. **LLM供应商**：\r
   - Anthropic (Claude) - 复杂推理、长上下文\r
   - OpenAI (GPT) - 通用任务、生态丰富\r
   - Azure OpenAI - 企业合规\r
   - 本地模型 (Ollama/vLLM) - 隐私敏感\r
\r
3. **构建规模**（重要！决定生成代码的复杂度和技术栈）：\r
   - Minimal：快速原型，~300行代码，几乎无三方库依赖\r
   - Professional：生产级应用，~3000行代码，包含Docker沙箱、日志系统、测试\r
   - Enterprise：企业平台，~8000行代码，全链路监控、微VM沙箱、多Agent\r
\r
4. **主要用途**：编码助手 / 自动化运维 / 数据分析 / 通用对话 / 其他\r
\r
5. **沙箱隔离需求**：\r
   - 不需要（Agent在本地直接执行）\r
   - 基础路径检查（沙箱限制工作目录）\r
   - Docker容器隔离（推荐Professional场景）\r
   - Firecracker微VM（推荐Enterprise高安全场景）\r
\r
6. **监控需求**：\r
   - 不需要\r
   - 基础结构化日志（推荐Professional场景）\r
   - 全链路追踪（推荐Enterprise场景）\r
\r
7. **是否需要多Agent协作**？\r
   - 是 / 否\r
\r
请告诉我你的选择，我会根据你的需求构建最合适的Agent项目。\r
```\r
\r
### 快速确认模式\r
\r
如果用户已经提供了部分信息，AI coding工具只需要补充询问未提供的信息：\r
\r
```\r
根据你的需求（Python技术栈 + Anthropic模型 + 编码助手），\r
我还需要确认：\r
\r
1. 构建规模？\r
   - Minimal：快速原型（300行）\r
   - Professional：生产级（3000行）\r
   - Enterprise：企业平台（8000行）\r
\r
2. 沙箱隔离需求？\r
   - 无 / 基础路径检查 / Docker隔离 / Firecracker微VM\r
\r
3. 监控需求？\r
   - 无 / 基础日志 / 全链路追踪\r
\r
4. 是否需要多Agent协作？\r
   - 是 / 否\r
\r
请补充提供以上信息，我将开始构建。\r
```\r
\r
### 默认值策略\r
\r
如果用户没有明确偏好，AI coding工具可以建议默认值，但必须说明原因：\r
\r
```\r
你未明确说明偏好，我将使用以下默认值：\r
- 技术栈：Python（功能完善，社区活跃）\r
- LLM供应商：Anthropic（长上下文优势）\r
- 构建规模：Professional（平衡功能与复杂度，适合团队工具阶段）\r
- 主要用途：通用对话\r
- 沙箱：Docker隔离\r
- 监控：基础结构化日志\r
- 多Agent协作：否\r
\r
如果你有其他偏好，请在回复中说明，我会相应调整。\r
```\r
\r
### 构建规模决策矩阵\r
\r
AI可以辅助用户选择规模：\r
\r
```\r
┌─────────────────────────────────────────────────────────────┐\r
│ 帮你选择构建规模：                                            │\r
│                                                              │\r
│ ● 如果你是开发者，想快速验证Agent概念 → Minimal               │\r
│ ● 如果你是团队，需要可维护的生产级Agent → Professional        │\r
│ ● 如果你是平台方，需要服务多用户 → Enterprise                 │\r
│                                                              │\r
│ 如果你不确定，建议从 Professional 开始。                      │\r
└─────────────────────────────────────────────────────────────┘\r
```\r
\r
---\r
\r
## 分阶段构建指南\r
\r
> **核心规则（v3 强制）**：\r
> 1. 以下每个 Phase 的摘要仅提供目标概述。**实际构建时必须打开对应的 reference 文件**，其中包含设计原理、抽象接口定义、AI构建提示。\r
> 2. **禁止直接复制 reference 或 template 中的代码片段。** AI 必须根据用户选择的规模生成定制化代码。\r
> 3. 每个阶段完成后，必须使用**与该规模对应的检查清单**进行验收。\r
\r
### Phase 1: 项目初始化 → `references/01-phase-init.md`\r
\r
**目标**：建立项目骨架，定义目录结构（三级规模不同结构）和配置文件。\r
\r
**规模差异**：\r
- Minimal: 单文件或最小目录结构\r
- Professional: 标准 src/config/tests 分离\r
- Enterprise: 多包 monorepo 结构\r
\r
### Phase 2: LLM抽象层 → `references/02-phase-llm.md`\r
\r
**目标**：实现与供应商无关的LLM客户端抽象。\r
\r
**规模差异**：\r
- Minimal: 单一供应商直连\r
- Professional: 工厂模式 + streaming + retry\r
- Enterprise: 多供应商 + prompt cache管理 + token计数 + lazy import\r
\r
### Phase 3: 工具系统 → `references/03-phase-tools.md`\r
\r
**目标**：实现模块化的工具注册和执行机制。\r
\r
**规模差异**：\r
- Minimal: 函数字典注册\r
- Professional: Registry + Schema验证 + MCP adapter\r
- Enterprise: 并发分区算法 + 工具依赖图 + 工具结果truncation\r
\r
### Phase 4: Agent核心循环 → `references/04-phase-agent-loop.md`\r
\r
**目标**：实现健壮的Agent主循环，包含错误恢复和状态管理。\r
\r
**规模差异**：\r
- Minimal: 简单 while 循环\r
- Professional: while(true) + 7个Continue站点 + 状态机\r
- Enterprise: AsyncGenerator流式 + 双层超时 + Session回放\r
\r
### Phase 5: 上下文管理 → `references/05-phase-context.md`\r
\r
**目标**：实现四级压缩管道和记忆系统。\r
\r
**规模差异**：\r
- Minimal: 仅 Snip 历史截断\r
- Professional: 完整四级管道 + 文件记忆\r
- Enterprise: 四级 + 压缩状态恢复 + 向量数据库记忆\r
\r
### Phase 6: 权限安全 → `references/06-phase-permissions.md`\r
\r
**目标**：实现权限控制和沙箱机制。\r
\r
**规模差异**：\r
- Minimal: 命令黑名单\r
- Professional: 权限模型 + Hook系统 + Docker沙箱\r
- Enterprise: 6层纵深防御 + Firecracker + 审计日志\r
\r
### Phase 7: 生产化 → `references/07-phase-production.md`\r
\r
**目标**：添加测试、监控、日志。\r
\r
**规模差异**：\r
- Minimal: 无\r
- Professional: pytest + structlog + 基础metrics\r
- Enterprise: CI/CD + OpenTelemetry + Prometheus\r
\r
## 十大设计哲学\r
\r
1. **Async Generator流式架构**: 不是返回最终结果，而是yield每一个中间事件\r
2. **通过Continue站点实现状态机**: while(true) + 7个continue站点\r
3. **编译时特性门控**: if (feature('FEATURE_X')) // bun:bundle编译时求值\r
4. **缓存前缀稳定性**: 内置工具排序后作为稳定前缀，MCP工具变化不影响缓存\r
5. **纵深防御**: 6层叠加使绕过概率指数下降\r
6. **数据驱动的可扩展性**: settings.json + agents/*.md + skills/*.md + hooks\r
7. **上下文即稀缺资源**: 工具延迟加载、记忆按需附加、四级压缩管道\r
8. **层级化配置覆盖**: 7级设置，CLI > Flag > Policy > Managed > Local > Project > User\r
9. **隔离的子Agent上下文**: 子Agent从空白消息列表开始，完成后只返回摘要\r
10. **可逆性优先**: 文件编辑通过Edit（替换字符串），不是Write（覆盖）\r
\r
## 常见陷阱\r
\r
1. **不要在Stop hook中做太重的操作**: 可能触发prompt-too-long错误，导致逻辑被静默跳过\r
2. **Hook allow不能绕过deny规则**: deny > settings rules > hook allow，这是安全不可变量\r
3. **hasAttemptedReactiveCompact不重置**: 防止compact→仍然太长→error→stop hook→compact的无限循环\r
4. **数组合并策略是连接+去重，而非替换**: 权限规则需要累加而非覆盖\r
5. **沙盒设置文件被硬编码为不可写**: 防止Agent通过修改settings.json来关闭沙盒\r
6. **MCP工具默认使用always_ask**: 第三方工具不应被自动信任\r
7. **Prompt Cache有最小长度要求**: 约1024 token，太短的前缀不会被缓存\r
8. **上下文压缩后必须主动恢复关键状态**: 文件内容、Skill上下文、Plan、任务列表\r
\r
## 参考资源\r
\r
- **核心文档**: 本目录下的 `references/` 文件（共14个）\r
- **项目模板**: `templates/minimal/` `templates/professional/` `templates/enterprise/`\r
- **外部资源**:\r
  - Anthropic Managed Agents API文档\r
  - Claude Code源码（~512,664行TypeScript）\r
  - MCP协议规范\r
  - "Scaling Managed Agents: Decoupling the brain from the hands" - Anthropic技术论文