🤖 agent-builder

生产级 AI Agent 构建从零参考 — 对齐 OpenAI / Anthropic 官方水准

English Docs

---

这是什么

一套帮助开发者和 AI Agent 从零构建企业级 AI Agent 的完整参考指南，以通用 Agent 可读格式组织。覆盖从 monorepo 脚手架到 Playground UI 的全栈 Agent 开发链路 —— 不重复造轮子：每个节点给出"手写实现 → 成熟方案"的映射与集成代码（Vercel AI SDK、LangGraph、LlamaIndex、E2B、OpenAI Agents SDK、Langfuse、LiteLLM 等），并附工程决策理由（🔗 工程逻辑）、AI 避坑注释（🤖 AI 避坑），经两轮以上交叉审计。

v1.1 起支持执行器模式：只给一段需求，AI 按零介入协议（不提问、只假设）自主完成规格补全 → 纵向切片 → 逐片实现 → 逐片回检 → 全量回归，交付可运行产品。

安装

# Claude Code / 通用 Agent
git clone https://gitcode.com/badhope/agent-builder.git ~/.claude/skills/agent-builder
# ZCode
git clone https://gitcode.com/badhope/agent-builder.git ~/.zcode/skills/agent-builder
# 验证
cd ~/.claude/skills/agent-builder && npm install && npm run verify
# verify = 代码块解析 + 自述审计 + 审计自测 + 运行期版本探测

涵盖内容

模块	核心能力
执行器	需求十二维补全 · 假设台账 · 纵向切片 · 交付状态机 · 降级矩阵 · 交付报告
基础	Turborepo · ReAct 循环 · SSE 流式 · Next.js · Electron 桌面端
工具与技能	Token 预算 · ToolRegistry · MCP Client · Skills 加载
记忆与 RAG	三层记忆（短期/长期/情景）· 混合检索 · Qdrant/Milvus/Chroma
多 Agent	Supervisor+Worker · LangGraph 集成 · 框架对比（LangGraph/CrewAI/AutoGen）
安全	Prompt Injection 防御 · Guardrails 校验 · 工具风险分类
生产部署	Docker + K8s · CI/CD · OpenTelemetry · Webhook · Playground UI
产品细节	收纳决策表 · 输入区与消息动作 · 会话列表 · 四态 · 键盘 · 响应式
回检	需求追踪矩阵 · 接线五跳 · 假实现检测 · 证据台账 · 三轮回检
对标参考	技术生态现状 · 开源项目对标与二次开发 · 调研报告

快速开始

在你的 AI 编程助手中直接说：

• "帮我搭一个 Agent"
• "Agent 的安全怎么保障"
• "怎样让 Agent 自我反思"
• "Agent 输出如何渲染成 Artifact"
• "怎么让多个 Agent 协作"
• "聊天产品需要哪些 UI 细节"
• "只要能跑起来就行，别问我问题"

Agent 会自动加载本参考并按需读取对应参考节点。

对标标准

• OpenAI Agents SDK — Guardrails 三层校验 + Runner 架构 + Session 持久化 + Tracing 内建
• Anthropic Claude — Artifacts 协议 + Computer Use + Harness 架构 + CLAUDE.md/Auto Memory/Skills/Hooks
• MCP (Model Context Protocol) — 最新规范下的 Client + Server 双向开发
• Langfuse / OpenTelemetry — 全链路可追踪、可度量、可告警

技术栈

层	技术
前端	Next.js + React + Tailwind + shadcn/ui
后端	Node.js + Fastify + tRPC
LLM	OpenAI / Anthropic / Gemini（多 Provider 路由）
向量库	Qdrant / Milvus / Chroma（混合检索）
桌面端	Electron（contextIsolation + sandbox）
沙箱	Docker（cgroups + seccomp + cap-drop + 只读 rootfs）
部署	Docker Compose + Kubernetes
监控	OpenTelemetry + Langfuse

28 参考节点

#	节点	覆盖内容
00	types	跨层类型契约（LanguageModel / UIMessage / AgentEvent）
01	foundation	Turborepo + ReAct 循环 + SSE + Next.js + Electron
02	tools-skills	Token 预算 + ToolRegistry + MCP + Skills
03	memory-rag	三层记忆 + 混合检索
04	sandbox	Docker 沙箱 + 七层安全边界
05	multi-agent	Supervisor+Worker + LangGraph 集成
06	hitl-reflection	四级 HITL + LLM-as-Judge 自反思
07	security	Prompt Injection 防御 + Guardrails
08	eval-observability	Eval 框架 + Langfuse 全链路
09	deploy	Docker Compose + Electron + K8s + CI/CD
10	prompt-protocol	五层 Prompt + 版本管理 + A/B
11	function-calling	三 Provider 适配 + 并行派发
12	vector-db-practical	Qdrant + Milvus + Chroma
13	structured-output	Zod Schema + 容错 JSON 解析
14	mcp-server-dev	MCP Server 开发 (Stdio + SSE)
15	knowledge-base	多格式 RAG + 增量索引
16	multimodal-agent	多模态 + TTS/STT
17	streaming-advanced	SSE 优化 + 智能重连
18	framework-comparison	LangGraph/CrewAI/AutoGen 对比
19	multi-tenancy	多租户 + RBAC + 审计
20	agent-marketplace	市场 + 安全扫描 + 收益分成
21	fault-recovery	状态快照 + 幂等工具
22	guardrails-tracing	Guardrails + Tracing + 成本追踪
23	artifacts-computer-use	Artifacts + Computer Use + CLI
24	product-layer	Playground + 多模型路由 + Webhook
25	autonomous-delivery	零介入交付：需求补全 + 切片 + 状态机 + 降级
26	product-detail-catalog	产品细节目录：收纳 + 输入区 + 消息动作 + 四态
27	implementation-audit	实现回检：矩阵 + 五跳 + 假实现检测
28	framework-integration-playbook	框架融合流水线：七阶段 + 契约对齐 + 事件桥

核心设计理念

• 不重复造轮子 — 复用成熟生态工具，优先选择社区主流方案
• 生产级而非 Demo — 每个节点都经真实代码实现，非伪代码
• 渐进式强化 — 从基础到高级，每一层可选、可独立升级
• AI 友好 — 每个节点标注 LLM 常犯的错误模式，防止 AI 走偏
• 零介入交付 — 缺口补假设，不抛回给用户
• 有证据才算完成 — 真实点击、真实请求、真实落库

路线图

路线图 — 已完成版本、待办 P0-P3（含验收判据）、明确排除项。

许可

MIT License — 自由使用、修改、分发。