Agent Builder

---
name: agent-builder
description: |
  从 PRD、需求或点子推导并构建生产级 Agent 产品。当用户：
  (1) 提供 PRD、需求点子或 Agent 方向，想要一个可落地的产品
  (2) 要求"创建一个 agent"、"构建一个助手"或"设计一个 AI 系统"用于真实使用
  (3) 需要架构设计、组件选型或 Agent 代码骨架
  (4) 想把一个点子变成可运行、可部署的 Agent 产品
  (5) 询问 Agent 架构、agentic 模式或 harness 工程
  时使用。
  关键词：agent、PRD、产品、架构、蓝图、harness、生产级、工具调用、多步骤、编排
---

# Agent Builder —— 从 PRD 到生产级 Agent 产品

从 PRD、需求或点子推导并构建**生产级** Agent 产品。产出是真实产品，不是 demo。

## 核心恒等式

> **模型已经知道如何成为 Agent。你的工作是给它一个值得行动的世界——并把它交付上线。**

```
Agent = 模型（智能，已训练好） + Harness（载具，你构建的代码）
Harness = 工具 + 知识 + 观察 + 行动接口 + 权限
```

模型是驾驶者，Harness 是载具。你构建的是载具。

## 推导工作流：先方案，后代码

**永远先交付架构方案，经用户确认后再生成代码。** 方案未确认前，不写产品代码。

按五步 SOP 推导（完整细节见仓库 `BLUEPRINT.md`）：

### 第一步：需求拆解
从 PRD 提取硬事实：目标、用户、核心闭环、交付物、边界、约束。**缺失项必须标注"待确认"，不允许脑补。**

### 第二步：领域建模
把每个事实映射到 Harness 五要素：工具、知识、观察、行动、权限。产出五要素清单——这是产品的领域骨架。

### 第三步：组件选型
查架构决策表。**只选需要的。对每个组件问"没有它产品会怎样"——答不上来就删掉。**

### 第四步：架构设计（先交付这一步）
产出方案，包含：
- 五要素清单（工具 / 知识 / 观察 / 行动 / 权限）
- 组件选型表（选了哪些、为什么、放弃了哪些）
- 分层架构图（7 层：交互 / 产品 / Agent 编排 / 模型 / 能力集成 / 数据 / 基础设施，详见 BLUEPRINT.md Step 4）
- 工具清单（名称 / 输入 / 输出 / 副作用 / 权限）
- 系统提示词草案
- 安全边界与降级策略
- 技术栈与部署形态

### 第五步：代码生成（确认后）
分三层递进：
1. **骨架**：可运行的 agent loop + 3~5 个领域工具 + 系统提示词
2. **硬化**：错误处理、超时、重试、日志、配置化、权限检查
3. **产品化**：组件集成、测试、部署脚本、README

## PRD 分析：先回答这 8 个问题

1. 要达成什么？（目标 + "怎样算做成"）
2. 给谁用？（用户 + 频率 + 同步/异步）
3. 一次完整交付长什么样？（输入→行为→交付物的完整闭环）
4. 需要什么外部动作？（系统、API、数据源）
5. 领域知识在哪？（模型必须知道的规则、文档、schema）
6. 什么绝对不能做？（红线、数据边界、合规）
7. 失败怎么办？（工具失败、幻觉、超时、越权的降级）
8. 怎么算成功？（完成率、时延、成本、准确率）

## 组件选型（架构决策表）

按 PRD 特征选组件。参考实现在仓库 `s01`–`s17`：

| PRD 特征 | 组件 | 参考 |
|---|---|---|
| 外部系统/API/数据源 | 工具系统 | s02 |
| 破坏性/敏感操作 | 权限系统 | s03 |
| 审计/拦截/埋点 | 钩子系统 | s04 |
| 多步骤、需跟踪进度 | 任务规划 | s05 |
| 上下文会爆、可并行 | 子 Agent | s06 |
| 领域知识库庞大 | 技能加载 | s07 |
| 长会话、日志量大 | 上下文压缩 | s08 |
| 跨会话偏好 | 记忆系统 | s09 |
| 目标持久化、可续跑 | 任务系统 | s10 |
| 慢操作不阻塞 | 后台任务 | s11 |
| 定时自治触发 | 定时调度 | s12 |
| 并行任务、隔离工作区 | Agent 团队 | s13 |
| 外部工具生态 | MCP 插件 | s14 |
| 多机制协同 | 集成 Harness | s15 |
| 编排形态固定 | 工作流运行时 | s16 |
| 自动判断"何时完成" | 目标闭环 | s17 |

## "生产级"验收标准

一个产物只有同时满足以下全部条件，才算生产级，否则只是 demo：

1. **可运行**：一条命令能起，配置与密钥外置
2. **可容错**：工具失败、幻觉、超时、越权都有降级路径
3. **可观测**：有日志、指标、轨迹数据
4. **可测试**：循环与分派有单测，权限/安全有边界测试
5. **可部署**：有明确的部署形态与启动文档
6. **可度量**：有对齐 PRD 的成功指标，并能采集

## 关键原则

1. **模型就是 Agent** —— 代码只跑循环
2. **信任模型** —— 不预设工作流，给工具让它推理
3. **先方案后代码** —— 方案未确认不写代码
4. **最小选型** —— 只有 PRD 要求时才加组件
5. **交付而非 demo** —— 每个产物都要过验收标准
6. **未知标"待确认"** —— 不假设、不编造需求

## 反模式

| 反模式 | 问题 | 修正 |
|---|---|---|
| 僵化工作流 | 无法适应 | 让模型决定 |
| 前置知识 | 上下文膨胀 | 按需加载 |
| 微观管理 | 削弱智能 | 信任模型 |
| 先码后方案 | 方向错、返工 | 先方案、确认、再码 |
| 编造需求 | 产品偏离 PRD | 未知标"待确认" |
| demo 级产出 | 无法交付 | 过全部验收标准 |

## 资源

**方法论**：
- `references/prd-to-product.md` — PRD 分析与架构映射方法论

**实现**：
- `references/minimal-agent.py` — 可运行的 agent loop（骨架层）
- `references/tool-templates.py` — 工具定义
- `references/subagent-pattern.py` — 上下文隔离

**脚手架**：
- `scripts/init_agent.py` — 生成新 Agent 项目
- 仓库 `scaffold/` — 生产级项目模板

## 心态

**从**："我怎么让系统做 X？"
**到**："我怎么让模型做 X——并交付上线？"

模型是驾驶者。给它造一辆生产级的车。给模型能力与知识，划清边界，让它可观测、可测试、可部署——然后信任它去完成剩下的。

**给模型一个值得行动的世界。交付它。**