小南的博客

04 Vibe Coding

Fri, 10 Apr 2026 00:00:00 GMT

😀

Claude Code

工具系统设计：Claude Code 内置了 Read、Write、Edit、Bash、Grep、Glob 等精心设计的原子

工具，每个工具都有明确的边界和安全约束。这套工具体系的设计思路，可以直接迁移到自定义Agent 项目中。

记忆管理架构：CLAUDE.md（项目级记忆）+ Auto Memory（自动记忆）的双层架构，解决了Agent 的"长期记忆"难题，成熟度超过大多数开源 Agent 框架的记忆方案。

上下文工程：Claude Code 的 /compact 命令背后是一套精密的上下文压缩与管理策略，它解决的是所有 Agent 都面临的核心挑战——如何在有限的 Context Window 里塞下无限的世界知识。

人机协作模式 (Human-in-the-Loop)：Claude Code 的权限确认机制、Checkpoint 回滚机制、Plan Mode 等设计，展示了 Agent 与人类如何高效且安全地协作。

扩展生态：Skills / MCP / Plugin 三套扩展体系，分别解决了"业务逻辑封装"、"外部能力连接"和"社区生态接入"三个不同层次的问题。

Claude Code 的架构可以拆分为六大核心系统，各自承担不同的职责，共同构成一个完整的 Agent 工作闭环：

1 内置工具系统：Agent 的执行引擎

内置工具是 Claude Code 与外部世界交互的唯一通道——模型本身不能直接操作文件系统或执行命令，所有操作都必须通过工具调用 (Tool Use) 完成。Claude Code 内置了以下核心工具：

2 多级记忆系统：跨会话的知识沉淀

3 项目管理系统：Checkpoint 回滚与安全保障

让 AI Agent 自动修改代码，最大的担忧是：改坏了怎么办？ Claude Code 的项目管理系统通过Checkpoint（检查点） 机制解决了这个问题。

工作原理：Claude Code 在每次产生文件变更时，自动创建一个 Checkpoint，记录变更前的文件快照。如果对某次修改不满意，可以随时回滚到任意历史检查点——类似 Git 的 commit，但粒度更细，精确到每一轮对话中的每一次文件操作。

实际效果示例：Claude Code 重构了 3 个文件后，你发现新的实现方案不合适。通过 /rewind 命令选择回滚点，一键恢复到重构前的代码状态——所有被修改的文件恢复原貌，新创建的文件被删除，干净利落。

4 斜杠命令系统：Agent 的控制面板

斜杠命令是与 Claude Code 交互的快捷控制方式——在对话输入框中键入 / 即可调出命令菜单。

截至 2026 年 3 月，Claude Code 内置了 59 个斜杠命令（含别名），覆盖了从会话管理、模型切换到扩展配置的方方面面。

1 会话管理

命令	功能	别名
`/clear`	清空当前对话历史，释放上下文	`/reset`、`/new`
`/compact [指示]`	压缩对话历史，可指定保留重点	—
`/resume [会话]`	按 ID / 名称恢复指定历史会话	`/continue`
`/fork [名称]`	从当前对话创建分支副本	—
`/rename [名称]`	重命名当前会话	—
`/export [文件名]`	导出对话为纯文本文件	—
`/exit`	退出 CLI	`/quit`

2 模型与模式

命令	功能	别名
`/model [模型名]`	切换 AI 模型（左右箭头调整 Effort Level）	—
`/plan`	进入 Plan Mode（先规划后执行）	—
`/fast [on\\|off]`	切换快速输出模式	—
`/output-style [风格]`	切换输出风格（Default / Explanatory / Learning）	—
`/vim`	切换 Vim / Normal 编辑模式	—

3 项目与上下文

命令	功能	别名
`/init`	初始化项目，生成 `CLAUDE.md`	—
`/add-dir <路径>`	向当前会话添加额外的工作目录	—
`/context`	可视化当前上下文使用情况（彩色网格）	—
`/diff`	打开交互式 Diff 查看器，查看未提交的变更	—
`/rewind`	回滚对话和 / 或代码到历史检查点	`/checkpoint`
`/pr-comments [PR]`	获取 GitHub PR 的评论	—
`/review`	对 Pull Request 进行代码审查	—
`/security-review`	分析当前分支的变更是否存在安全漏洞	—
`/copy`	复制上一条 AI 回复到剪贴板	—

4 配置与状态

命令	功能	别名
`/config`	打开配置界面	`/settings`
`/permissions`	查看 / 修改工具权限	`/allowed-tools`
`/memory`	编辑 `CLAUDE.md` 记忆文件，管理自动记忆	—
`/doctor`	诊断安装和配置状态	—
`/status`	显示版本、模型、账户和连接状态	—
`/cost`	显示当前会话 Token 用量和费用（API 用户）	—
`/stats`	可视化每日用量、会话历史和使用模式	—
`/usage`	显示订阅套餐限额和速率限制状态	—
`/theme`	更换颜色主题（含深色 / 浅色 / 色盲友好版本）	—
`/statusline`	配置终端状态栏信息	—
`/keybindings`	打开快捷键配置文件	—
`/terminal-setup`	配置终端快捷键（如 `Shift+Enter`）	—

5 扩展与 Agent

命令	功能	别名
`/mcp`	管理 MCP Server 连接和 OAuth 认证	—
`/skills`	列出可用的 Skills	—
`/plugin`	管理 Plugin 插件	—
`/agents`	管理自定义 Agent 配置	—
`/tasks`	列出和管理后台任务	—
`/hooks`	管理 Hook 事件配置	—

6 账户与平台

命令	功能	别名
`/login`	登录 Anthropic 账户	—
`/logout`	登出 Anthropic 账户	—
`/upgrade`	打开套餐升级页面	—
`/extra-usage`	配置超额使用（限额触达后继续工作）	—
`/privacy-settings`	查看 / 修改隐私设置（Pro/Max 用户）	—
`/desktop`	将当前会话转移到桌面应用	`/app`
`/mobile`	显示移动端 App 下载二维码	`/ios`、`/android`
`/chrome`	配置 Chrome 集成设置	—
`/ide`	管理 IDE 集成状态	—
`/remote-control`	允许从 claude.ai 远程控制此会话	`/rc`
`/remote-env`	配置远程环境默认值	—
`/install-github-app`	安装 Claude GitHub Actions App	—
`/install-slack-app`	安装 Claude Slack App	—

7 信息与反馈

命令	功能	别名
`/help`	显示帮助信息和可用命令	—
`/feedback [报告]`	提交使用反馈或 Bug 报告	`/bug`
`/release-notes`	查看版本更新日志	—
`/insights`	生成使用分析报告（项目领域、交互模式、摩擦点）	—
`/stickers`	订购 Claude Code 贴纸	—
`/passes`	分享免费试用周（符合条件的账户可见）	—

8 内置 Skills（以斜杠命令形式触发）

命令	功能
`/simplify`	审查近期变更代码的复用性、质量和效率，自动修复发现的问题
`/batch <指令>`	将大规模代码变更分解为 5-30 个独立子任务，并行派发给 Agent 在隔离的 Git Worktree 中执行
`/debug [描述]`	读取会话调试日志，诊断 Claude Code 自身的运行问题

5 扩展能力系统：MCP、Skills 与 Plugin

6 多 Agent 协作系统

传统的 AI 编程助手是"单线程"的——一次只能处理一个任务。Claude Code 的多 Agent 系统打破了这一限制，引入了 Sub-Agent 委托和 Agent Team 两种协作模式。

Sub-Agent（子智能体委托）

Claude Code 在处理复杂任务时，可以自主派生出一个或多个 Sub-Agent，将子任务委托给它们并并行处理。每个 Sub-Agent 拥有独立的上下文和工具权限，完成后将结果汇报给主 Agent。

Agent Team（智能体团队）

这是更高级的多 Agent 编排模式（实验性功能），允许定义多个具有不同专长的 Agent 组成团队，协同完成复杂项目。

Claude code 配置

ccstatusline-zh

huangguang1999 • Updated May 10, 2026

使用&开发

完整十八开发阶段研发流水线

Claude Code 前后端设计规范

Claude Code 可观测闭环

Claude Code 对话模式技巧

Claude Code 工具体系

Claude Code 权限模式关系图

Claude Code 工具权限关系

Claude Code Bash 虚拟环境选择策略

Claude Code Memory

.claude/rules/*.md 项目规则详解

Claude Code 实战经验分享

📎 参考文章

一些引用

引用文章

💡

欢迎您在底部评论区留言，一起交流~

临时

Thu, 04 Jun 2026 00:00:00 GMT

第7章：Agent 层 — Main Crew

本章目标：深入理解 CrewAI 框架下的主 Agent 设计，包括 Agent/Task YAML 配置、Prompt 工程、ReAct 推理循环、step_callback 详细模式，以及工厂模式的应用。
本章依赖：第3章（数据模型）、第5章（Runner）、第6章（Session）
对应源码：
[xiaopaw/agents/main_crew.py](file:///d:/ProjectsCodes/企业级智能体实战/xiaopow/xiaopaw/agents/main_crew.py)
[xiaopaw/agents/models.py](file:///d:/ProjectsCodes/企业级智能体实战/xiaopow/xiaopaw/agents/models.py)
[xiaopaw/agents/config/agents.yaml](file:///d:/ProjectsCodes/企业级智能体实战/xiaopow/xiaopaw/agents/config/agents.yaml)
[xiaopaw/agents/config/tasks.yaml](file:///d:/ProjectsCodes/企业级智能体实战/xiaopow/xiaopaw/agents/config/tasks.yaml)
[xiaopaw/tools/intermediate_tool.py](file:///d:/ProjectsCodes/企业级智能体实战/xiaopow/xiaopaw/tools/intermediate_tool.py)
预计时间：2-3 小时

7.1 什么是 Agent？通俗理解

在聊代码之前，先理解一个概念：Agent（智能体）到底是什么？

想象你有一个非常聪明的助手，你给他一个任务，他：

思考：这个任务我应该怎么做？

行动：调用工具去完成（查资料、写代码、发消息）

观察：看看工具返回了什么结果

判断：结果对吗？需要继续吗？还是可以给出最终答案了？

回到步骤 1（如果需要的话）

这就是 Agent 的核心工作方式——ReAct（推理-行动）循环。

7.2 CrewAI 框架简介

CrewAI 是一个 Python 框架，帮助我们快速构建 AI Agent。它提供了 Agent、Task、Crew 三个核心概念。

7.2.1 核心概念一览

概念	通俗理解	在代码中
Agent	"一个员工" — 有身份、有目标、有技能	`Agent(role=..., goal=..., tools=...)`
Task	"一个任务" — 具体要做的事情	`Task(description=..., expected_output=...)`
Tool	"一个工具" — Agent 可以调用的能力	`SkillLoaderTool()`, `IntermediateTool()`
Crew	"一个团队" — 包含 Agent + Task	`Crew(agents=[...], tasks=[...])`

7.2.2 CrewAI 的执行流程

7.3 XiaoPaw 的 Agent 架构

7.3.1 整体设计

7.3.2 设计原则

原则一：极简主 Agent（单工具原则）

主 Agent 只有一个能力扩展工具：SkillLoaderTool。所有专业能力（PDF 处理、飞书操作、网络搜索等）都通过 Skill 生态接入。这样做的好处：

主 Agent 的 Prompt 更短（不需要列举所有工具）

新增 Skill 不需要修改主 Agent

主 Agent 的职责清晰：理解意图 → 编排 Skill

原则二：结构化输出

使用 Pydantic 模型强制 LLM 输出 JSON 格式：

为什么需要结构化输出？

程序可以可靠地解析 Agent 的回复（result.pydantic.reply）

可以追踪 Agent 用了哪些 Skill（result.pydantic.used_skills）

避免 LLM 输出格式不一致导致的解析错误

原则三：YAML + Python 分离

配置层	位置	内容	修改频率
YAML（人设层）	`agents.yaml`, `tasks.yaml`	Agent 的角色、目标、行为规范	经常调整（调 Prompt）
Python（代码层）	`main_crew.py`	工具绑定、LLM 绑定、工厂函数	较少修改（代码稳定）

原则四：工厂模式防污染

每次请求创建新的 Crew 实例，防止上一轮的状态污染下一轮。详见 7.7 节。

7.4 Agent 配置详解（agents.yaml）

7.4.1 完整配置

7.4.2 配置字段详解

字段	作用	对 LLM 的影响	示例
`role`	定义身份/职位	影响回复风格和专业程度	"XiaoPaw 工作助手"
`goal`	定义最终目标	指导整个推理方向	"通过 Skills 完成任务"
`backstory`	背景故事 + 行为规范	最重要的 Prompt 工程部分	工作流程、边界、策略
`max_iter`	最大迭代次数	安全阀，防止无限循环	50

7.4.3 backstory 中的 Prompt 工程技巧

技巧一：明确工作流程（Step-by-Step）

为什么 Step-by-Step 有效？因为 LLM 是"逐 token 生成"的，明确的步骤让它更容易产生正确的推理链。

技巧二：明确行为边界（负面约束）

负面约束（"不要做什么"）和正面约束（"要做什么"）同样重要。LLM 有时会"过度自信"编造结果，明确禁止可以防止。

技巧三：搜索策略优先级

让 Agent 知道工具之间的优先级关系，避免"大材小用"。

7.5 Task 配置详解（tasks.yaml）

7.5.1 完整配置

7.5.2 Task 的两要素

要素	作用	示例
`description`	任务的"输入"：告诉 Agent 当前要处理什么	历史对话 + 用户消息
`expected_output`	任务的"输出格式"：告诉 Agent 最终要返回什么	JSON 格式 {reply, used_skills}

7.5.3 模板变量注入

description 中的 {history} 和 {user_message} 是模板变量，在运行时通过 akickoff(inputs={...}) 注入：

注入过程：

7.5.4 结构化输出（output_pydantic）

在 Task 中使用：

使用结果：

7.6 历史格式化（_format_history）

7.6.1 完整实现

7.6.2 输出示例

完整历史只有 4 条时（不截断）：

完整历史有 30 条，截断到 20 条时：

7.6.3 设计要点

不直接丢弃历史：超出部分不是直接扔掉，而是告知 Agent "存在更早的历史"

引导 Agent 使用 history_reader：如果 Agent 需要更早的上下文，会主动调用 history_reader Skill

不暴露时间戳：只展示对话内容，不展示原始时间戳（保持简洁）

中文角色名：比英文更自然，LLM 处理中文语境时效果更好

7.7 Verbose 模式（step_callback）

7.7.1 什么是 Verbose 模式？

Verbose 模式让 Agent 把"心里想什么"实时告诉用户：

7.7.2 回调构建

7.7.3 ReAct 循环中的回调触发

7.7.4 适用范围

场景	verbose 推送	原因
单聊（p2p）	✅ 推送	用户主动开启，希望看到推理过程
群聊（group）	✅ 推送	群成员可以看到推理过程
话题群（thread）	❌ 不推送	避免话题污染（一个话题里塞太多消息）
Sub-Crew	❌ 不注入	Sub-Crew 的推理过程不需要暴露给用户

7.8 工厂模式（build_agent_fn）

7.8.1 为什么需要工厂模式？

先看一个"不用工厂模式"的问题：

CrewAI 的 Agent 在 kickoff() 后会积累内部状态（如执行历史、工具调用记录）。如果复用同一个实例，上一轮的状态会影响下一轮的推理。这就是"状态污染"。

7.8.2 工厂模式的实现

7.8.3 闭包原理

通俗理解：闭包就像一个"带记忆的函数"。它记住了创建时的环境（sender、max_history_turns 等），之后每次调用都能使用这些记忆。

7.9 Crew 构建详解（_build_crew）

7.9.1 完整实现

7.9.2 关键参数说明

参数	值	为什么这样设置
`temperature`	0.3	较低温度让输出更稳定。对于需要精确执行的工作助手，不可预测性是有害的
`process`	`Process.sequential`	单 Agent 单 Task，顺序执行即可
`verbose`	`True`	在控制台打印 ReAct 过程，方便调试
`output_pydantic`	`MainTaskOutput`	强制 JSON 格式输出，程序可解析
`max_iter`	50	足够的迭代次数处理复杂任务，同时防止无限循环

7.9.3 IntermediateTool 详解

7.10 完整执行流程

把以上所有部分串联起来，看一次完整的消息处理流程：

7.11 本章小结

本章我们深入学习了 XiaoPaw 的 Agent 层——Main Crew 的完整实现。核心要点回顾：

概念	说明	位置
Agent	有身份、有目标、有工具的 AI 角色	`agents.yaml` + `main_crew.py`
Task	具体的任务描述和期望输出	`tasks.yaml` + `main_crew.py`
Crew	Agent + Task 的组合体	`main_crew.py` 的 `_build_crew()`
ReAct 循环	Thought → Action → Observation 的推理循环	CrewAI 框架内部
step_callback	每轮 ReAct 后触发的回调，用于 verbose 推送	`_make_step_callback()`
工厂模式	每次请求创建新 Crew 实例，防止状态污染	`build_agent_fn()`

关键设计决策：

决策	原因
单工具原则（SkillLoaderTool）	主 Agent 极简，能力通过 Skill 扩展
YAML + Python 分离	人设可调（YAML），代码稳定（Python）
结构化输出（output_pydantic）	程序可解析，避免 LLM 输出格式不一致
工厂模式（每次新建 Crew）	防止 CrewAI 内部状态污染
历史截断 + history_reader 引导	控制上下文长度，不丢失历史
低温 LLM（temperature=0.3）	追求稳定性和可预测性

下一步：下一章将深入 Sub-Crew 与 AIO-Sandbox 沙盒的实现，了解 Skill 如何在隔离环境中安全执行。

7.12 练习

修改 agents.yaml 中的 backstory，添加一条新的行为约束（如"回复不能超过 200 字"），观察 Agent 行为变化

在 MainTaskOutput 中添加一个新字段 confidence: float，让 Agent 输出对自己回答的信心程度

尝试把 temperature 从 0.3 改为 0.8，观察 Agent 的回复风格变化

第8章：Sub-Crew 与 AIO-Sandbox

本章目标：深入理解 Sub-Crew 的创建、MCP 协议、AIO-Sandbox 沙盒通信，以及工具行为约束。
对应源码：
xiaopaw/agents/skill_crew.py
sandbox-docker-compose.yaml

8.1 Sub-Crew 设计理念

8.1.1 为什么要 Sub-Crew？

主 Agent 的上下文窗口有限（LLM 处理输入有 token 上限），如果让主 Agent 直接操控所有的文件处理、搜索、飞书工具：

8.1.2 Sub-Crew 的隔离性

维度	主 Crew	Sub-Crew
LLM 上下文	完整历史的最近20条	完全独立，不知道主对话
工具	SkillLoaderTool + IntermediateTool	Sandbox MCP 工具
生命周期	每次用户消息新建	每个 task 型 Skill 调用新建
对话历史	不分享	不获取
文件系统	不直接访问	`/workspace/sessions/{sid}/`

8.2 AIO-Sandbox 沙盒概述

8.2.1 什么是 AIO-Sandbox？

AIO-Sandbox 是一个开源的 Docker 沙盒环境，提供：

隔离的代码执行环境（Python、Bash）

文件系统操作

浏览器自动化

MCP（Model Context Protocol）接口

8.2.2 MCP 协议

MCP 是 Anthropic 提出的标准化工具调用协议。在 XiaoPaw 中：

8.2.3 Docker 挂载映射

8.3 Sub-Crew 构建（skill_crew.py）

8.3.1 build_skill_crew() 工厂

8.3.2 沙盒行为指令（sandbox_directive）

指令设计要点：

指令	目的
工作目录/输出目录	约束文件路径，防止写入随机位置
可用工具列表	明确 Sub-Crew 能调用什么
规则 1：不编造结果	防止 LLM 幻觉
规则 3：输出到指定目录	统一输出路径，方便主 Agent 定位结果
规则 6：--break-system-packages	解决 Docker 内 pip 安装冲突

8.3.3 MCP 工具集

Sub-Crew 连接沙盒时，启用所有 MCP 工具（不使用白名单）。工具约束通过 Agent backstory 行为规则来管理。

为什么不使用 create_static_tool_filter 白名单？

web_browse Skill 需要 browser_* 系列工具，静态白名单会限制这些工具

白名单后期维护成本高，新增工具需要修改代码

Backstory 行为约束更灵活，可以根据 Skill 类型调整指令

8.4 Sub-Crew 调用流程（完整串联）

8.4.1 从 SkillLoaderTool 到 Sub-Crew

8.4.2 时序图

8.5 Sub-Crew 与主 Agent 的 Session

关键点：

同一个 session 的两个 Sub-Crew 共享 /workspace/sessions/s-abc/ 目录

第一个 Sub-Crew 的输出文件可以被第二个 Sub-Crew 读取

每个 Sub-Crew 是独立实例，不知道前一个 Sub-Crew 做了什么

任务上下文（task_context）由主 Agent 负责串联

8.6 Sandbox 凭证注入

8.6.1 write_feishu_credentials()

8.6.2 使用方式

feishu_ops Skill 的 Python 脚本读取凭证：

为什么凭证不经过 LLM？

LLM 的输入/输出可能被记录到日志和 trace

凭证是敏感信息，不应暴露给第三方模型

凭证通过文件系统注入沙盒，脚本直接读取

LLM 不知道凭证的存在，也无法读取

8.7 本章小结

Sub-Crew：每次 task 型 Skill 调用创建新实例，完全隔离

AIO-Sandbox：Docker 沙盒，通过 MCP 协议通信

MCP 工具集：21 个工具全部可用，约束通过 backstory 行为规则

凭证安全：飞书/百度凭证写入沙盒文件（chmod 600），不经过 LLM

工作目录：Sandbox 路径与主机路径通过 Docker volume 双向映射

下一章将深入 SkillLoaderTool 的实现和 Skills 生态系统。

第9章：Skills 生态系统与 SkillLoaderTool

本章目标：全面理解 XiaoPaw 的 Skills 生态——从定义规范到渐进式披露，从 SkillLoaderTool 的主/子工具切换，到三种特殊处理（reference、task、history_reader）。你将会学到：Skill 是什么、如何定义、如何加载、如何执行，以及整个调用链路是如何衔接的。
对应源码：
xiaopaw/tools/skill_loader.py — 核心工具
xiaopaw/skills/load_skills.yaml — Skill 清单
xiaopaw/agents/skill_crew.py — Sub-Crew 工厂

9.1 什么是 Skill？—— 用一个比喻理解

在正式进入代码之前，我们先用一个生活中的比喻来理解 "Skill" 这个概念。

9.1.0 比喻：智能手机的应用商店

想象你的手机刚出厂时，只有打电话、发短信等最基本的功能。但当你从应用商店下载了微信、支付宝、地图等 App 后，手机的能力就大大扩展了。

XiaoPaw 的 Skill 生态 就是这个思路：

9.1.1 为什么需要 Skill 生态？

核心问题：如果让主 Agent 直接拥有所有工具（PDF 处理、Word 处理、搜索、飞书操作……），会发生什么？

关键优势：

维度	全挂工具	Skill 生态
工具描述 token 消耗	~550 tokens（所有工具）	~150 tokens（只有 Skill 列表）
选择准确度	容易选错	更精准（先在菜单中选，再加载详细指令）
扩展性	新增工具需改 Agent 定义	只需添加 SKILL.md 文件
隔离性	一个工具崩溃影响全局	每个 Skill 在独立 Sub-Crew 中运行
上下文安全	工具描述可能泄露敏感信息	阶段 0 只暴露名称+简短描述

9.2 Skill 定义规范

9.2.1 SKILL.md 格式详解

每个 Skill 目录下必须有一个 SKILL.md 文件。这个文件是 Skill 的"身份证" + "使用说明书"，分为两部分：

YAML Frontmatter 是 Skill 的"身份证"——描述 Skill 的基本信息，阶段 0 只需解析这部分。 Markdown 正文 是 Skill 的"使用说明书"——详细的执行步骤，阶段 1 按需加载。

实例：pdf Skill 的 SKILL.md

Python Libraries

pypdf - Basic Operations

...（省略更多内容）

不太好的 description 示例：

9.2.3 Skill 的类型：reference vs task

这是 Skill 生态中最核心的概念之一。两种类型的设计目标不同：

维度	`reference`（参考型）	`task`（任务型）
含义	返回操作指南给主 Agent，主 Agent 自己推理	启动独立 Sub-Crew，在沙盒中执行
执行环境	主 Agent 的推理空间	独立的 AIO-Sandbox 沙盒
上下文	共享主 Agent 上下文	完全隔离，不感知主对话
开销	轻量，只是文本返回	较重，需要启动 Sub-Crew + MCP 通信
适用场景	信息型任务、需要主 Agent 综合判断	代码执行、文件处理、API 调用
示例	`history_reader`（读取历史消息）	`pdf`、`docx`、`feishu_ops`、`baidu_search`

通俗理解：

reference 型 Skill = "给你一本说明书，你自己看着办"

task 型 Skill = "派一个专业工人去执行，你等着收结果就行"

9.2.4 load_skills.yaml — Skill 清单

skills/load_skills.yaml 是全局的 Skill 注册表，它告诉 SkillLoaderTool：有哪些 Skill 可用、各自的类型是什么、是否启用。

关键设计点：

enabled 字段：可以临时关闭某个 Skill，不需要删除文件。比如某个 Skill 的 API Key 还没配置好，设 enabled: false 即可。

type 字段：决定 Skill 的执行方式，SkillLoaderTool 据此分流。

注释：每个 Skill 的注释说明了为什么是 task 类型（需要代码执行），帮助维护者理解。

如何新增一个 Skill？ 只需三步：

创建 skills/新Skill名/SKILL.md 文件

在 load_skills.yaml 中添加条目

重启 XiaoPaw，SkillLoaderTool 自动发现新 Skill

9.3 渐进式披露（Progressive Disclosure）

9.3.1 设计原理——为什么分两阶段加载？

这是 SkillLoaderTool 最核心的设计模式。渐进式披露 的意思是：只在需要时才暴露详细信息。

Token 预算分析：

9.3.2 实现细节——_build_description() 方法

这是渐进式披露第一阶段的核心实现。它只读取 SKILL.md 的 YAML frontmatter，构建一个轻量级的 XML 格式工具描述：

为什么用 XML 格式？

XML 格式对 LLM 来说结构清晰，标签明确（、、），LLM 能准确解析。相比之下，纯文本列表或 Markdown 表格可能被 LLM 误解格式。

路径穿越防护：

这段代码的作用是：如果有人恶意配置 name="../../etc"，resolve() 会计算出实际路径，然后 startswith 检查确保它仍然在 _SKILLS_DIR 目录下。这是一个重要的安全防护。

9.3.3 _extract_frontmatter_description() — 提取 frontmatter 中的 description

通俗解释：

这个方法就像一个"图书管理员"——它只看书的封面（frontmatter），不打开书的内容（Markdown 正文）。这样就节省了时间和资源。

9.4 SkillLoaderTool 实现详解

9.4.1 类结构总览

9.4.2 PrivateAttr —— 为什么有些属性要用 PrivateAttr？

这是 CrewAI BaseTool 的一个重要机制。让我们用一个表格来对比：

属性类型	行为	用途
普通属性	被 CrewAI 序列化，传给 LLM	工具的名称、描述、参数 Schema
`PrivateAttr`	只在 Python 代码中使用，不传递给 LLM	内部状态、会话 ID、凭据、缓存

为什么 session_id 不能暴露给 LLM？

_skill_registry 和 _instruction_cache 为什么也是 PrivateAttr？

9.4.3 init 方法

9.4.4 输入输出模型

field_validator 的作用：

通俗地说，这个 validator 就像一个"翻译官"。LLM 可能会传 task_context={"page": 1}（一个 dict），但我们的 Schema 定义的是 str 类型。validator 在 Pydantic 校验之前自动把 dict 转成 '{"page": 1}' 字符串，这样就不会报错了。

9.4.5 _get_skill_instructions() — 渐进式披露第二阶段

当 LLM 决定调用某个 Skill 时，SkillLoaderTool 需要加载完整的 SKILL.md 内容。这个方法就是渐进式披露第二阶段的核心：

关键设计点总结：

缓存机制：_instruction_cache 避免同一 Skill 重复读取文件

路径占位符替换：{skill_base} → 实际的沙盒路径，让 SKILL.md 可以在不同环境复用

花括号转义：{ → {{，防止 CrewAI 模板变量冲突

sandbox_execution_directive：附加沙盒执行指令，告诉 Sub-Crew Agent 如何使用工具

9.5 三种处理类型详解

当 LLM 调用 SkillLoaderTool 时，_execute_skill_async() 方法会根据 Skill 的类型进行分流：

9.5.1 reference 型 — 返回指令文本

通俗解释：reference 型 Skill 就像"给你一本菜谱"。主 Agent 拿到菜谱后，自己理解步骤，自己决定怎么做。不需要派一个专业厨师（Sub-Crew）去执行。

适用场景：

信息型 Skill，如 history_reader

需要主 Agent 综合判断的复杂决策流程

操作指南长度适中，不会压满上下文窗口

9.5.2 task 型 — 启动 Sub-Crew

通俗解释：task 型 Skill 就像"叫一个专业服务"。比如你要处理 PDF，你自己不会，就叫一个"PDF 处理专家"（Sub-Crew）来帮你做。这个专家有自己的工具（沙盒 MCP 工具），做完后把结果告诉你。

关键点：

每次 build_skill_crew() 返回新实例，防止状态污染

Sub-Crew 在独立的沙盒中执行，与主 Agent 完全隔离

Sub-Crew 的结果通过 akickoff() 返回给主 Agent

9.5.3 history_reader — 特殊内联处理

history_reader 是一个特殊的 Skill：它虽然是 reference 型，但不需要从 SKILL.md 读取指令，而是直接在 SkillLoaderTool 内部从内存中读取历史消息。

为什么 history_reader 要特殊处理？

原因	说明
不需要沙盒	只是内存中的列表切片操作，不涉及文件系统或代码执行
避免网络开销	不启动 Sub-Crew，不需要 MCP 协议通信，响应更快
安全性	历史消息包含用户隐私数据，不应传入沙盒环境
可靠性	减少中间环节，降低出错概率

9.5.4 三种处理类型对比

9.6 SKILL.md 模板变量安全

9.6.1 问题描述

CrewAI 框架使用 {var} 语法进行模板变量替换。当 CrewAI 加载 Agent 的 backstory 或 Task 的 description 时，会自动扫描所有 {变量名} 格式的占位符，然后在 akickoff(inputs={...}) 中查找对应的值。

问题来了：SKILL.md 中可能包含代码示例，比如：

如果 CrewAI 发现 {name} 但没有在 inputs 中提供对应的值，就会报错：

9.6.2 解决方案

分两步走：

第一步：转义花括号

第二步：注入自映射变量

完整流程图：

通俗解释：

这就像"套娃"——先把 { 变成 {{（告诉 CrewAI "这是文本，别替换"），然后为了防止 CrewAI 的扫描器仍然报错，主动告诉它"这些变量都存在，值就是它们自己"，这样 CrewAI 就不会报错了。

9.7 异步双通道 — _arun 与 _run

CrewAI 的 BaseTool 支持两种调用方式：异步 _arun() 和同步 _run()。SkillLoaderTool 同时实现了两者，确保在不同场景下都能正常工作。

9.7.1 异步路径 _arun()

9.7.2 同步路径 _run()

为什么需要两个通道？

9.8 完整调用流程 — 端到端走一遍

让我们用一个具体的例子来走一遍完整的调用流程：

场景：用户在飞书中说"帮我分析这个 PDF 文件的内容"

9.9 本章小结

本章我们深入学习了 XiaoPaw 的 Skills 生态系统和 SkillLoaderTool 的实现。核心要点回顾：

知识点	核心内容
Skill 定义	SKILL.md = YAML frontmatter（元数据）+ Markdown 正文（操作指南）
Skill 类型	`reference`（返回指令，轻量）vs `task`（启动 Sub-Crew，重量）
渐进式披露	阶段 0：只加载 frontmatter 的 description（~50 字符/Skill）；阶段 1：按需加载完整 SKILL.md
SkillLoaderTool	主 Agent 的唯一工具，负责 Skill 发现、加载、分流
PrivateAttr	会话 ID、沙盒 URL 等敏感信息不暴露给 LLM
三种处理	reference（返回指令）、task（启动 Sub-Crew）、history_reader（内联分页）
模板变量安全	`{` → `{{` 转义 + 自映射注入，防止 CrewAI 报错
异步双通道	`_arun()`（异步路径，直接 await） + `_run()`（同步路径，ThreadPoolExecutor）
路径穿越防护	`resolve()` + `startswith()` 确保 Skill 路径在允许的目录内

设计哲学：

极简主 Agent：主 Agent 只有一个工具（SkillLoaderTool），所有能力通过 Skill 扩展

渐进式披露：按需加载，不浪费 token

安全第一：PrivateAttr 保护敏感信息，路径穿越防护，沙盒隔离

可扩展性：新增 Skill 只需添加 SKILL.md 文件 + 更新 load_skills.yaml

9.10 练习与思考

新增一个 Skill：尝试创建一个名为 hello_world 的 task 型 Skill，让它能接收用户的名字并返回问候语。需要：

创建 skills/hello_world/SKILL.md

在 load_skills.yaml 中注册

理解 SkillLoaderTool 如何发现和加载它

对比 reference 和 task：history_reader 是 reference 型，但如果把它改成 task 型会有什么不同？分析两种方式的优缺点。

模板变量问题：如果 SKILL.md 中有 {user_name} 这样的占位符，当前的转义机制会把它变成什么？最终 Sub-Crew 看到的是什么？

路径安全：如果 load_skills.yaml 中配置了 name: "../../etc"，SkillLoaderTool 会如何处理？画出代码执行路径。

渐进式披露的 token 节省：假设有 10 个 Skill，每个 SKILL.md 平均 3000 字符。计算渐进式披露相比全量加载节省了多少 token（假设 1 token ≈ 4 字符）。

下一章将详细介绍每个 Skill 的具体实现——包括文件处理、飞书操作、搜索、网页浏览等。

第10章：Skill 详解

本章目标：逐一深入分析每个 Skill 的设计目的、操作规范、脚本架构和实现细节。通过本章学习，你将理解每个 Skill 是如何独立工作、如何与沙盒互动、以及如何通过统一的输出规范与主 Agent 通信的。
对应目录：xiaopaw/skills/

10.1 分类总览与设计哲学

10.1.1 九大 Skill 一览

Skill	类型	使用沙盒	脚本语言	核心能力
pdf	task	✅	Python	PDF 文本提取、合并、拆分、旋转、元数据读取
docx	task	✅	Python	Word 文档创建、读取、编辑
pptx	task	✅	Python	PowerPoint 文本提取
xlsx	task	✅	Python	Excel 数据分析、读写、图表
feishu_ops	task	✅	Python	飞书消息发送、文档读取、日历管理、多维表格
scheduler_mgr	task	✅	Python	定时任务的创建/查看/更新/删除
baidu_search	task	✅	Python	百度千帆网页搜索
web_browse	task	✅	MCP 工具	网页抓取与浏览器自动化
history_reader	reference	❌	无（内联）	对话历史按页读取

10.1.2 设计哲学

每个 Skill 都遵循以下设计原则：

10.2 文件处理 Skills

文件处理是 XiaoPaw 最基础的能力之一。当用户在飞书中上传 PDF、Word、Excel 或 PowerPoint 文件时，对应的 Skill 会被触发。

10.2.1 pdf — PDF 文本提取与处理

Skill 定义：

通俗理解：PDF Skill 就像你的"PDF 全能助手"。你给它一个 PDF 文件，它能帮你提取文字、拆分页面、合并多个文件、旋转页面、提取表格等。

SKILL.md 中的核心操作指南：

使用的 Python 库：

库	用途	为什么选择它
`pypdf`	基础操作：读取、合并、拆分、旋转、元数据	纯 Python 实现，无外部依赖，安装简单
`pdfplumber`	高级操作：精确文本提取、表格提取	比 pypdf 的文本提取更准确，特别是复杂布局

为什么需要两个库？

pypdf 适合"编辑"操作（合并、拆分、旋转），pdfplumber 适合"提取"操作（文字、表格）。两者互补，覆盖了常见的 PDF 处理需求。

注意事项：

加密 PDF 需要密码才能处理

扫描版 PDF（图片）需要 OCR 才能提取文字

大文件（>100MB）处理可能较慢

10.2.2 docx — Word 文档处理

Skill 定义：

通俗理解：DOCX Skill 就像你的"Word 助手"。它能读取 Word 文档的内容，也能根据你的需求创建新的 Word 文档。

核心操作：

python-docx 库的核心概念：

概念	对应 Word 中的...	代码操作
`Document`	整个 Word 文件	`doc = Document(path)`
`Paragraph`	一个段落	`doc.add_paragraph("text")`
`Run`	段落中的一段文字（相同格式）	`run = para.add_run("text")`
`Table`	表格	`doc.add_table(rows, cols)`
`Heading`	标题（1-9 级）	`doc.add_heading("title", level=1)`

10.2.3 pptx — PowerPoint 处理

Skill 定义：

通俗理解：PPTX Skill 能帮你读取 PowerPoint 文件中的文字内容，提取每张幻灯片的标题和正文。

python-pptx 的核心概念：

概念	代码
整个 PPT 文件	`prs = Presentation(path)`
一张幻灯片	`slide = prs.slides[i]`
幻灯片上的元素	`shape = slide.shapes[j]`
文本框	`shape.text_frame`
段落	`shape.text_frame.paragraphs`

10.2.4 xlsx — Excel 数据处理

Skill 定义：

通俗理解：XLSX Skill 是你的"Excel 数据分析师"。它能读取 Excel 文件中的数据，进行筛选、排序、统计，并生成新的 Excel 文件。

为什么用 pandas？

pandas 是 Python 最强大的数据分析库。相比直接用 openpyxl 操作单元格，pandas 提供的"DataFrame"概念（类似 Excel 的表格视图）让数据分析更加直观和高效。

10.3 feishu_ops — 飞书操作

这是 XiaoPaw 最核心也是功能最丰富的 Skill，它让 Sub-Crew 能够直接与飞书平台交互——发送消息、读取文档、管理日历等。

10.3.1 脚本架构总览

10.3.2 共享认证模块 _feishu_auth.py

这是 feishu_ops 所有脚本的"地基"。每个脚本都通过 import _feishu_auth as auth 引用它，获取飞书 API 的认证 Token 和通用工具函数。

为什么需要一个共享模块？

10.3.3 消息发送脚本

send_text.py — 发送纯文字消息

这是最基础的消息发送脚本，也是理解其他脚本的起点：

参数说明：

参数	必填	说明	示例
`--routing_key`	✅	目标路由键，标识消息发给谁	`p2p:ou_abc123`（私聊）、`group:oc_xyz789`（群组）
`--text`	✅	消息文本内容	`"你好，这是定时报告"`

send_image.py — 发送图片消息

发送图片比发送文字多一步：先上传图片获取 image_key，再用 image_key 发送图片消息。

send_file.py — 发送文件消息

这是处理结果回传的核心场景。用户上传文件 → Skill 处理 → 结果保存到 outputs/ → 调用 send_file.py 将结果发回给用户。

10.3.4 文档读取脚本

read_doc.py — 读取飞书文档

read_sheet.py — 读取飞书电子表格

10.3.5 所有脚本的统一设计模式

总结 feishu_ops 所有 16 个脚本的共同模式：

10.4 baidu_search — 百度搜索

10.4.1 Skill 概述

通俗理解：baidu_search Skill 是 XiaoPaw 的"搜索引擎"。当用户问"最近有什么新闻"、"Python 最新版本是什么"这类需要实时信息的问题时，这个 Skill 会去百度搜索最新结果。

10.4.2 凭证注入

搜索 API 需要 API Key。这个 Key 通过环境变量 BAIDU_API_KEY 配置，由 CleanupService 在启动时写入沙盒：

10.4.3 搜索脚本详解

参数说明：

参数	必填	说明	示例
`--query`	✅	搜索关键词或自然语言问题	`"Python 异步编程最佳实践"`
`--top_k`	否	返回结果数，默认 20，最大 50	`--top_k 5`（精准搜索）/ `--top_k 30`（广泛调研）
`--recency`	否	时间范围过滤	`week`（近7天）/ `month`（近30天）/ `semiyear`（近半年）/ `year`（近一年）
`--sites`	否	指定站点（逗号分隔）	`"github.com,stackoverflow.com"`

典型使用场景：

10.5 web_browse — 网页浏览与自动化

10.5.1 Skill 概述

通俗理解：web_browse Skill 是 XiaoPaw 的"浏览器"。它能打开网页、提取内容、截图，甚至填写表单、点击按钮——就像真人在操作浏览器一样。

10.5.2 两种工作模式

web_browse 支持两种模式，根据任务需求选择：

模式	工具	速度	适用场景
快速提取	`sandbox_convert_to_markdown`	快（~2s）	提取网页文本内容（新闻文章、文档页面）
浏览器全功能	`browser_navigate` + `browser_*` 系列	慢（~10s）	截图、表单填写、JavaScript 动态渲染页面

为什么需要两种模式？

10.5.3 浏览器自动化工具流程

10.5.4 浏览器工具速查表

工具	功能	必填参数	可选参数
`browser_navigate`	打开 URL	`url`	-
`browser_get_markdown`	获取页面 Markdown	-	-
`browser_get_text`	获取页面纯文本	-	-
`browser_read_links`	获取所有链接	-	-
`browser_screenshot`	截图	`name`	`fullPage`, `selector`
`browser_get_clickable_elements`	获取可交互元素	-	-
`browser_click`	点击元素	`index`	-
`browser_form_input_fill`	填写输入框	`index`, `value`	`clear`
`browser_select`	下拉选择	`index`, `value`	-
`browser_press_key`	按键	`key`	-
`browser_scroll`	滚动页面	`amount`	-
`browser_evaluate`	执行 JavaScript	`script`	-
`browser_close`	关闭浏览器	-	-

10.6 scheduler_mgr — 定时任务管理

10.6.1 Skill 概述

通俗理解：scheduler_mgr Skill 是 XiaoPaw 的"闹钟管理器"。你可以通过它设置定时任务——比如"每天早上 9 点发送工作摘要"、"每周五下午 5 点生成周报"。

10.6.2 三种触发模式详解

Cron 表达式语法：

常用 Cron 表达式示例：

表达式	含义
`0 9 * * *`	每天 9:00
`0 9 * * 1-5`	工作日 9:00
`0 9 1 * *`	每月 1 号 9:00
`/30 * * *`	每 30 分钟
`0 9,18 * * *`	每天 9:00 和 18:00

10.6.3 任务数据结构

10.6.4 热加载机制

重要提示：scheduler_mgr Skill 只负责管理定时任务配置，不负责执行。触发时的业务处理由主 Agent 配合其他 Skill 完成。payload.message 必须是自然语言指令，描述"要做什么"。

10.7 history_reader — 历史阅读器

10.7.1 Skill 概述

通俗理解：history_reader 是 XiaoPaw 的"记忆回溯器"。当主 Agent 的上下文窗口只能容纳最近 20 条消息时，如果用户问"你之前说的 xxx 是什么意思"，history_reader 可以翻出更早的对话记录。

10.7.2 为什么是 reference 型？

history_reader 是唯一一个 reference 型的 Skill，它在 SkillLoaderTool 中内联实现（详见第 9 章），不需要沙盒或 Sub-Crew。

原因：

不需要沙盒：只是内存中的列表分页操作，不涉及文件系统或代码执行

避免网络开销：不启动 Sub-Crew，不需要 MCP 协议通信

安全性：历史消息包含用户隐私数据，不应传入沙盒环境

可靠性：减少中间环节，降低出错概率

10.7.3 使用场景

用户询问"回顾一下我们之前的对话"

历史截断后，Agent 需要查阅更早的消息

用户询问特定历史话题（"你上次说的那个 Python 库叫什么来着？"）

10.8 本章小结

Skill	核心能力	关键技术	凭证来源
pdf	PDF 文本提取与处理	pypdf, pdfplumber	无
docx	Word 文档创建与编辑	python-docx	无
pptx	PowerPoint 文本提取	python-pptx	无
xlsx	Excel 数据分析	pandas, openpyxl	无
feishu_ops	飞书消息/文档/日历	飞书 REST API + 16 个独立脚本	`/workspace/.config/feishu.json`
baidu_search	百度搜索	百度千帆 Web Search API	`/workspace/.config/baidu.json`
web_browse	网页浏览与自动化	sandbox_convert_to_markdown + browser_* 工具	无
scheduler_mgr	定时任务管理	读写 tasks.json + CronService 热加载	无
history_reader	历史分页读取	内联实现，内存分页	无

设计亮点：

统一脚本模式：所有 task 型 Skill 脚本遵循相同的参数解析 → 认证 → API 调用 → 响应检查 → 结果输出模式

凭证隔离：敏感信息通过文件系统注入沙盒，不经过 LLM

独立可测试：每个脚本可以独立运行和测试，不依赖整个系统

热加载：scheduler_mgr 的配置变更无需重启

10.9 练习与思考

新增一个消息类型：在 feishu_ops 中新增一个 send_markdown.py 脚本，支持发送 Markdown 格式的消息。参考 send_text.py 和 send_post.py 的实现。

搜索优化：baidu_search 的 _get_api_key() 每次都读取文件。如果改成缓存机制，应该如何设计？参考 feishu_ops 的 token 缓存思路。

文件处理链：用户上传了一个 Excel 文件，要求"分析数据并生成 PDF 报告"。这需要 chain 哪些 Skill？画出完整的调用链路。

错误处理：如果 baidu_search 的 API Key 过期了，脚本会输出什么？Sub-Crew Agent 会如何处理？主 Agent 会给用户什么回复？

Cron 表达式：用 Cron 表达式表示"每月最后一天 18:00"和"每周一、三、五 9:00"。

下一章将深入 LLM 适配器的实现——如何将阿里云的通义千问模型接入 CrewAI 框架。

第11章：LLM 适配器

本章目标：深入理解 CrewAI 的 LLM 接口机制，掌握 AliyunLLM 适配器的实现细节——重试机制、函数调用（Function Calling）、多模态图片输入、消息格式化、工具结果截断等。
对应源码：xiaopaw/llm/aliyun_llm.py

11.1 为什么需要自定义 LLM 适配器？

11.1.1 通俗理解

想象一下，你去国外旅行，发现当地的插座和你的充电器插头不匹配。你需要一个"转换插头"（适配器）才能给你的设备充电。

在 XiaoPaw 中，CrewAI 框架期望一个"标准插座"（OpenAI 格式），而阿里云通义千问（Qwen）提供的是一个"不同形状的插头"（DashScope API）。AliyunLLM 就是这个"转换插头"——它把 CrewAI 的请求翻译成 DashScope 能理解的格式，再把 DashScope 的响应翻译回 CrewAI 能理解的结果。

11.1.2 为什么不能直接用 OpenAI 的适配器？

特性	OpenAI	DashScope（通义千问）
API 端点	`api.openai.com`	`dashscope.aliyuncs.com`
认证方式	`Bearer sk-xxx`	`Bearer sk-xxx`（相同）
多地域	无	`cn`（国内）/ `intl`（国际）/ `finance`（金融云）
多模态模型	`gpt-4o`	`qwen3-vl-plus`（需单独指定）
Tool Calls 格式	标准 JSON	兼容，但部分参数需要规范化
上下文窗口	基于模型名	基于模型名（`long`→200K, `max/plus/turbo`→131K）

11.1.3 核心差异：多模态处理

最大的差异在于多模态图片处理。CrewAI 对工具返回结果的 stringify（字符串化）处理，会导致图片的 base64 编码被当作普通文本，DashScope 无法识别。AliyunLLM 需要反向还原这些字符串为多模态格式。

11.2 CrewAI `BaseLLM` 接口

11.2.1 接口定义

CrewAI 提供了 BaseLLM 抽象类，自定义 LLM 需要继承它并实现以下方法：

11.2.2 消息格式

CrewAI 传入 call() 的消息是已转换为 dict 格式的对话历史：

11.2.3 两种返回值模式

call() 方法可能返回两种不同的值，取决于 LLM 的决定：

当返回 tool_calls 时，CrewAI 会接管执行流程：

CrawlAI 的 executor 接收 tool_calls

根据 function.name 找到对应的工具函数

执行工具函数，获得结果

将结果作为 tool 消息追加到对话历史

再次调用 call()，让 LLM 基于工具结果继续推理

11.3 AliyunLLM 完整实现

11.3.1 类结构总览

11.3.2 初始化详解

为什么重试次数默认是 2？

这是一个经验值。太少（1次）可能不够覆盖偶发性的网络问题；太多（5次以上）会让用户等待过久。2 次重试（共 3 次尝试）在"可靠性"和"响应速度"之间达到了较好的平衡。

11.3.3 多地域支持

11.4 核心流程：call() 方法

11.4.1 调用流程全景图

11.4.2 重试机制详解

重试是 AliyunLLM 最关键的可靠性保障机制。不同于简单的"失败就重试"，它根据错误类型采取不同的策略：

重试策略总结：

HTTP 状态码	含义	是否重试	原因
200	成功	-	正常响应
4xx	客户端错误（参数错误等）	❌ 不重试	请求本身有问题，重试不会改变结果
429	限流（Rate Limit）	✅ 重试	配额可能在下个时间窗口恢复
5xx	服务器错误	✅ 重试	服务端临时故障，重试大概率成功
Timeout	超时	✅ 重试	可能是网络抖动

11.4.3 空内容重试

LLM 偶尔会返回空内容（content=""），这通常是因为模型限流或偶发异常。AliyunLLM 对这个情况也做了专门处理：

为什么 _retry_on_empty 要设为 False？

这防止了无限递归。如果设为 True，空内容重试内部再次遇到空内容，又会触发重试，形成死循环。设为 False 后，内层重试再遇到空内容就会直接抛出异常，终止循环。

11.5 消息格式化

11.5.1 消息校验

在发送请求前，AliyunLLM 会校验消息格式：

11.5.2 工具结果截断

当工具返回数据过大时（如 Excel 解析结果可能包含大量文本），直接发送会导致 API 返回 500 错误。AliyunLLM 会自动截断过长的工具结果：

11.6 Function Calling 详解

11.6.1 什么是 Function Calling？

Function Calling（函数调用/工具调用）是 LLM 的一项核心能力。它允许 LLM 在推理过程中"调用"外部函数来获取信息或执行操作。

通俗理解：就像你问助手"今天天气怎么样"，助手不会凭空编造，而是拿起手机查看天气预报 App，然后把结果告诉你。LLM 的 Function Calling 就是这个过程——它知道自己不能回答某些问题，所以"调用"外部工具来获取信息。

11.6.2 完整调用流程

11.6.3 两种 tool_calls 处理模式

AliyunLLM 的 call() 方法根据 available_functions 参数是否为 None，采取不同的处理方式：

为什么有两种模式？

模式	谁执行工具	适用场景
模式 1（递归）	AliyunLLM 自己	LLM 内部的工具调用循环
模式 2（返回）	CrewAI executor	CrewAI Agent 的工具调用流程

模式 2 是主要使用的方式。CrewAI 故意传 available_functions=None，让 LLM 只返回原始 tool_calls，由 CrewAI 的 _handle_native_tool_calls 统一执行。这样 CrewAI 可以控制工具的生命周期、记录 trace、管理回调等。

11.6.4 MCP 参数规范化

MCP（Model Context Protocol）工具对参数类型有严格要求。LLM 有时会把列表参数传成字符串 "None"，导致 schema 校验失败。AliyunLLM 在返回 tool_calls 前做规范化处理：

11.6.5 递归 Function Calling

当 available_functions 不为 None 时，AliyunLLM 会递归处理工具调用：

11.7 多模态图片处理

11.7.1 问题背景

CrewAI 对工具返回结果做 stringify（字符串化）时，会将图片的 base64 编码当作普通文本处理。但 DashScope 的视觉模型需要图片以特定的多模态格式传入。

11.7.2 多模态检测与还原

11.7.3 模型自动切换

当检测到图片时，AliyunLLM 自动将 model 切换为 image_model：

为什么需要切换模型？

通义千问的文本模型（如 qwen3.6-max-preview）不支持图片输入。必须使用专门的视觉模型（如 qwen3-vl-plus）才能处理图片。这个切换是自动的，对调用方透明。

![多模态模型切换流程]

11.8 上下文窗口大小

什么是 Token？

Token 是 LLM 处理文本的最小单位。粗略地说：

1 个中文字 ≈ 1.5-2 个 tokens

1 个英文单词 ≈ 1-1.5 个 tokens

一段代码 ≈ 更多 tokens（各种符号都是独立的 token）

11.9 异步调用

为什么用 asyncio.to_thread() 而不是 aiohttp？

方案	优点	缺点
`asyncio.to_thread()`	代码简单，复用同步逻辑	占用线程池资源
`aiohttp`	真正异步，不占用线程	需要重写所有 HTTP 逻辑

对于 XiaoPaw 的并发量（通常只有几个同时进行的对话），线程池的开销可以忽略不计，而代码简洁性更重要。

11.10 调试模式

当遇到 LLM 调用问题时，可以开启调试模式查看完整的请求内容：

调试模式下，日志会输出完整的请求 payload：

11.11 配置使用

在 _build_crew() 中创建 Agent 时指定 LLM：

11.12 本章小结

功能	实现方式	关键参数
多地域支持	3 个端点映射	`region`: cn / intl / finance
重试机制	按状态码分类重试	`retry_count`: 默认 2
空内容重试	递归调用，最多 2 次	`_retry_on_empty` + `_empty_retry_count`
Function Calling	两种模式（递归/返回）	`available_functions`
MCP 参数规范化	字符串 "None" → []	`_MCP_LIST_PARAMS`
工具结果截断	超 12000 字符自动截断	`LLM_TOOL_RESULT_MAX_CHARS`
多模态图片	检测 + 还原 + 模型切换	`image_model`: qwen3-vl-plus
消息校验	检查 role + tool_call_id	`_validate_messages`
上下文窗口	基于模型名推断	`get_context_window_size`
调试模式	环境变量控制	`QWEN_DEBUG_PAYLOAD=1`

11.13 练习与思考

Token 计算：一条 1000 字的中文消息大约消耗多少 tokens？如果上下文窗口是 131,072 tokens，大约能容纳多少条这样的消息？

重试策略：为什么 4xx 错误不重试，而 5xx 错误要重试？如果 API 返回 408（Request Timeout），应该怎么处理？

多模态处理：如果用户同时上传了 3 张图片，_normalize_multimodal_tool_result 能否正确处理？如果不能，应该如何改进？

工具结果截断：如果 LLM 收到截断的工具结果后，仍然尝试基于不完整的信息做结论，会导致什么问题？截断后缀中的提示信息是否足够？

模型选择：什么时候应该用 qwen-long（200K 上下文）而不是 qwen-max（131K 上下文）？多消耗的 tokens 成本是否值得？

自定义适配器：如果要把 XiaoPaw 改为使用 OpenAI 的 GPT-4，需要修改 AliyunLLM 的哪些部分？哪些部分可以复用？

下一章将深入 CronService 定时任务调度系统——如何实现精确的定时触发、任务热加载和调度状态管理。

第12章：CronService 定时任务调度

本章目标：深入理解 CronService 的调度模型、三种调度模式（at / every / cron）、tick 主循环、mtime 热加载机制、任务状态持久化，以及由定时任务触发的消息如何在 Runner 中流转。
对应源码：
xiaopaw/cron/service.py
xiaopaw/cron/models.py

12.1 调度模型

12.1.1 通俗理解

CronService 就像你的"闹钟管家"。你告诉它"每天早上 9 点提醒我开会"，它就会准时在你设定的时间"响铃"——把一条消息注入到 XiaoPaw 的处理管道中，就像有人给你发了消息一样。

12.1.2 数据模型

12.1.3 三种调度模式详解

12.2 CronService 核心实现

12.2.1 类结构

12.2.2 生命周期管理

12.2.3 主循环详解

这是 CronService 最核心的部分。每 0.05 秒执行一次 tick：

12.2.4 触发逻辑

为什么 msg_id 和 sender_id 是伪值？

因为这不是飞书用户的消息，而是定时服务产生的。使用特殊的 msg_id 和 sender_id 可以：

日志中容易区分来源

避免与真实飞书消息 ID 冲突

支持去重（如果同一任务被重复触发）

12.2.5 触发后状态更新

12.2.6 Cron 表达式计算

12.3 热加载（Hot-Reload）

12.3.1 为什么需要热加载？

定时任务不是静态配置——用户可以通过 scheduler_mgr Skill 动态创建、修改、删除任务。这些变更写入 tasks.json 后，CronService 需要立即感知，而不是等下次重启。

12.3.2 mtime 检测机制

12.3.3 加载逻辑

12.3.4 原子持久化

12.4 tasks.json 格式

12.5 完整调用链路

12.6 为什么不用 asyncio 精确定时器？

初版 CronService 使用了 asyncio.wait_for(self._sleep.wait(), timeout=...) 的精确等待方式，但后来改为简单的 tick 轮询。原因如下：

方案	精度	代码复杂度	可靠性
精确定时器	微秒级	高	需要处理 wakeup 和各种边界情况
Tick 轮询	50ms	低	简单可靠，不易出错

对于定时任务来说，50ms 的精度完全够用（用户不会因为 50ms 的延迟而感知到差异），但代码简洁性和可靠性大大提升。

12.7 本章小结

组件	功能	关键实现
`CronSchedule`	调度配置	三种模式互斥：at / every / cron
`CronPayload`	触发内容	routing_key + message（自然语言）
`CronState`	运行状态	next_run / last_run / 状态 / 错误
`CronService._loop()`	主循环	每 50ms tick，检查到期任务
`CronService._fire()`	触发任务	构造伪 InboundMessage → Runner
`CronService._check_mtime()`	热加载检测	mtime + 文件大小双重比较
`CronService._save_store()`	原子持久化	write-then-rename
`_next_cron_ms()`	Cron 计算	croniter 库 + 时区支持

设计亮点：

统一处理管道：定时消息和用户消息走完全相同的 Runner 链路

热加载：mtime 检测 + 立即重载，无需重启进程

原子写入：write-then-rename 防止文件损坏

disabled 保留：禁用的任务不丢失，方便后续重新启用

cron 重新计算：每次加载都重新计算 cron 的 next_run，确保表达式变更立即生效

12.8 练习与思考

精度分析：如果 tick_interval 从 50ms 改为 1000ms（1 秒），对定时任务的精度有什么影响？什么场景下可以接受？

原子写入：为什么 _save_store 使用 write-then-rename 而不是直接写入？如果写入过程中进程崩溃，两种方式分别会有什么后果？

cron 表达式：写出以下场景的 cron 表达式：

每月 15 号 10:00

每周一、三、五 9:00 和 18:00

工作日每小时的第 30 分钟

错误处理：如果 _fire() 中 dispatch 失败，last_status 会被设为 "error"。这个错误信息对用户有什么用？如何改进错误报告？

并发安全：如果两个任务同时到期，_fire() 是顺序执行还是并发执行？如果是顺序执行，会不会导致后面的任务延迟触发？

时区处理：如果用户在日本（UTC+9）创建了一个 cron 任务 0 9 * * *，但 tasks.json 中 tz 写的是 "Asia/Shanghai"（UTC+8），实际触发时间是什么？如何避免这种问题？

下一章将深入可观测性与日志系统——如何监控 XiaoPaw 的运行状态、记录 LLM 调用轨迹、暴露 Prometheus 指标。

💡

欢迎您在底部评论区留言，一起交流~

Harness Engineering - 搭建Mini Harness

Fri, 03 Apr 2026 00:00:00 GMT

😀

手搓 Mini Harness：用 11 个机制从零搭建一个生产级 AI Agent 控制框架

不用 LangChain，不用 LangGraph，不用任何 Agent 框架。用最裸的 Python + OpenAI SDK，从零搭建一个包含 11 个安全机制的 AI Agent 控制平面，并诚实回答一个问题：Harness 到底值不值？

一、背景：Agent 不是智能体，是一个脆弱的循环

一个基本事实：AI Agent 不是智能实体，而是一个由代码组成的、可以反复调用 LLM 的 while 循环。 这个循环本身非常脆弱——它会循环失控、会吞掉工具报错、会在长会话中把自己搞傻、会无声无息地烧掉你的钱。

这些脆弱点被归纳为 八大故障模式：

编号	故障模式	典型表现
①	循环失控	Agent 陷入无限循环，反复调用同一个工具
②	Context 溢出	长会话中上下文窗口被撑爆
③	Cache Miss	重复计算导致成本飙升
④	Tool 错误吞	工具执行失败被静默忽略，Agent 基于错误结果继续推理
⑤	状态丢失	任务中断后无法续跑，前功尽弃
⑥	缺权限闸	Agent 可能执行危险命令（如 `rm -rf`）
⑦	缺自动化评审	LLM 自审等于作者自审，天然有偏差
⑧	成本失控	异常循环导致 API 费用无限增长

针对这八大故障模式，Harness Engineering 使用了 11 个机制（8 核心 + 3 扩展）：

编号	机制	救的故障模式	实现文件
①	Agent Loop	① 循环失控	`core.py`
②	Tool Use	④ tool 错误吞	`core.py`
③	Progress Tracking	⑤ 状态丢失	`progress.py`
④	Context Management	② context 溢出 / ③ cache miss	`context.py`
⑤	Feature List	② context 溢出（源头防控）	`planner.py`
⑥	Verification Loop	④ tool 错误吞（下游验证）	`verifier.py`
⑦	Subagents	② context 溢出 / ⑧ 成本失控	`subagent.py`
⑧	Generator-Evaluator	⑦ 缺自动化评审	`evaluator.py`
⑨	Permission Gate	⑥ 缺权限闸	`permission.py`
⑩	Hooks	贯穿所有机制的事件挂钩基础设施	`hooks.py`
⑪	Token Budget	⑧ 成本失控	`budget.py`

本文将逐一拆解这 11 个机制的核心实现，并在最后用一组真实的 E2E 对比数据来回答那个核心问题。

二、项目骨架：11 个文件 = 1 个配置中心 + 10 个机制模块

整个 Mini Harness 刻意不使用任何 Agent 框架——目的不是省事，而是看清裸骨架：每一块肌肉是什么、做什么、怎么连接。框架会帮你隐藏复杂度，但代价是你不知道出了问题该去哪里找。

配置中心：HarnessConfig

所有 11 个机制共享一个配置对象，避免参数散落各处：

注意 max_steps=50——它是机制①防止循环失控的硬刹车。

三、核心机制详解

机制①②：Agent Loop + Tool Use（`core.py`）

这是整个 Mini Harness 的心脏。Agent Loop 的本质是一个 while 循环，Tool Use 是循环体内的工具调度器。

Agent Loop 核心结构

关键设计点：

max_steps 硬刹车：while steps < config.max_steps 确保循环不会无限执行

BudgetExceeded 优雅终止：token 超限时抛异常，由外层 try/except 捕获

Permission Gate 挂载点：trigger_gate("pre_tool_use") 在工具执行前拦截危险命令

Tool Use：自动反射 + 结构化错误回传

传统做法需要开发者手工维护一份 JSON Schema 配置文件，极易与代码脱节。Harness 使用 Python 的 inspect.signature 做运行时反射，自动从函数签名生成 tool schema：

核心收益：业务源码与调用契约 100% 自动同源同步。你在 Python 里增删一个参数，给大模型的 JSON 契约瞬间自适应改变。

工具执行层的 dispatch_tool 是另一个关键设计——绝不吞报错：

传统做法要么让程序崩溃（Agent 死机），要么 try...except: pass 吞掉异常（LLM 产生幻觉）。dispatch_tool 走第三条路：将错误包裹成结构化 JSON 回传给 LLM，让 LLM 自己读错误信息、修正参数、重新调用。这是 Agent 自我纠偏的核心枢纽。

机制③：Progress Tracking（`progress.py`）

故障模式⑤（状态丢失）的解药。ProgressTracker 通过 HookManager 的三个事件点把会话过程记录到 progress.md：

核心 API 是一行 tracker.register_to(agent.hooks)——零侵入接入，不需要改动 run_agent 内部任何代码。

机制④：Context Management（`context.py`）

故障模式②（context 溢出）和③（cache miss）的解药。核心策略：不改 toolset、不改 memory、不改 system prompt（三铁律），只对 messages 做结构化压缩。

三铁律的出处是 AGENTS.md 规范——压缩时绝不能改变 agent 的能力边界（toolset）、已有知识（memory）和行为规范（system prompt）。

机制⑤：Feature List（`planner.py`）

故障模式②（context 溢出）的源头防控。核心思想：用一个外部数据结构承载任务状态，把"全局规划的复杂性"从 LLM 的 context 里剥离出去。

三种模式对应任务生命周期的三个阶段：

替换模式（merge=False）：任务开始时创建清单

合并模式（merge=True）：执行过程中更新状态（pending → in_progress → completed）

查询模式（todos=None）：任务完成前检查是否全部完成

在 E2E demo 的 7 步任务中，有 5 步是 todo 操作。这不是低效，而是刻意设计：每步只做一件事的纪律，是防止 context 溢出的源头防控。

机制⑥：Verification Loop（`verifier.py`）

故障模式④（tool 错误吞）的下游验证。核心原则：验证必须由工具完成，而不是由 LLM 完成。 LLM 的自我确认没有验证效力——它倾向于说"我检查过了"，但无法真正运行自己生成的代码。

两层验证架构：

第一层（引导层）：通过 system prompt 植入验证思维：

第二层（执行层）：用真实工具验证——例如通过 subprocess 调用 pytest 验证生成的代码是否真的能跑通。工具返回的确定性结果（pass/fail）比 LLM 的自我确认可靠得多。

与第二章错误回传的本质区别：

机制	触发时机	验证主体	作用
结构化错误回传	工具调用本身出错时	工具执行层	确保错误不被吞掉
Verification Loop	工具调用成功后	独立验证工具	确保结果本身是正确的

机制⑦：Subagents（`subagent.py`）

故障模式②（context 溢出）和⑧（成本失控）的解药。核心设计：子 agent 拥有完全独立的 messages 列表，父 agent 的对话历史对子 agent 不可见。

父子迭代预算不是加法，是乘法。 假设父 agent max_steps=50，每步都 spawn 一个子 agent（max_steps=50），最坏情况是 50 × 50 = 2500 步。这是 Manus 早期版本的真实教训。

三条子 agent 设计铁律：

独立迭代上限：子 agent 步数上限必须比父更小（推荐父 50 / 子 10）

结果长度上限：子任务返回内容必须截断，防止撑爆父 context

成本上限：子任务必须设置 Token Budget，达到阈值强制终止

机制⑧：Generator-Evaluator（`evaluator.py`）

故障模式⑦（缺自动化评审）的解药。核心思想：生成和评估分离，用独立 context 的另一个 LLM 做客观审查。

为什么 LLM 自审不可靠？LLM 在生成内容时，注意力已被当前推理路径"锚定"。当被要求"检查自己的输出"时，它倾向于沿着相同的推理路径再走一遍，而不是真正以批判视角重新审视。生成者和审查者读的是同一份 messages 历史，思维起点相同，盲点也相同。

两个关键设计：

temperature=0.3：评审需要稳定性和一致性，低温度保证同样的候选方案每次评审得分接近

Evaluator 的 system prompt 完全独立：它不知道 Generator 的内部推理过程，只看最终输出

与 Verification Loop 的关系：两者可以组合使用——先用 Verification Loop 做客观验证（pytest），再用 Generator-Evaluator 做主观质量评审，构成双重质量保障。

四、三个生产级扩展机制

机制⑩：Hooks 事件总线（`hooks.py`）

Hooks 本身不直接救任何一条故障模式，而是为 Permission Gate、Progress Tracker 和 Budget Guard 提供挂载基础设施。它是整个 Harness 的"神经系统"。

六大标准事件：

HookManager 提供两类接口：

trigger(event)：普通事件，顺序调用所有 handler，单个失败不影响其他

trigger_gate(event)：门控事件，任一 handler 返回 (False, reason) 则立即 veto

关键安全策略：普通事件 handler 失败只记录不中断；门控事件 handler 失败视为拦截——因为允许一个"门坏了"的危险命令执行比多记录一条日志严重得多。

机制⑨：Permission Gate（`permission.py`）

故障模式⑥（缺权限闸）的解药。挂在 pre_tool_use gate 事件上，在执行前拦截危险命令。

核心实现是一个正则黑名单，包含 14 条危险模式（如 rm -rf、sudo、chmod 777、curl | bash 等）。任何匹配的工具调用参数都会被 veto，返回 (False, reason) 阻止执行。

机制⑪：Token Budget（`budget.py`）

故障模式⑧（成本失控）的解药。BudgetGuard 在每次 LLM 调用后累计 token 消耗，超限时抛出 BudgetExceeded 异常，由 run_agent 的 try/except 捕获后优雅终止。

五、E2E 真实数据：Harness 到底值不值？

以下是 2026-04-22 真实跑通的数据（模型：deepseek-chat，任务：分析 main.py 的重复代码并给出重构建议）：

维度	Baseline（单轮调用）	Full Harness（8 机制）	倍率
步骤数	1	7	7×
耗时	35.45 s	94.02 s	2.65×
总 tokens	1,104	15,053	13.6×
答案字符数	2,498	2,819	+13%
成本 (USD)	—	$0.0697	—
预算上限	—	$0.50	—
Permission 拦截	0	0（本次无危险命令）	—
progress.md	无	已落盘（7 条记录）	—

13.6× tokens，2.65× 耗时。 这不是 Harness 效率低，而是它的成本结构。你用 13 倍的 tokens 换来了三个用单轮调用永远买不到的属性：

可观察性：progress.md 落盘了 7 条记录，每一步做了什么、调用了哪个工具、结果是什么，全程可追溯。Baseline 跑完了，你只能看到最终答案。

可干预性：Permission Gate 就绪，任何危险命令都会被在执行前拦截。Baseline 里 agent 直接执行任何工具，包括 rm -rf——你没有机会干预。

可控性：Token Budget 守住了整个任务，$0.0697 < $0.50 上限。如果任务出现异常循环，Budget 会触发优雅终止而不是无限烧钱。

六、三条核心结论

结论一：Harness 的 13× tokens 换的是"三性"，不是低效

成本直觉建立后，你才能判断"这个任务值不值得上 Harness"——不是所有任务都需要，但凡是你需要追溯、拦截、兜底的任务，这个成本就是必要的。

结论二：Harness 与底层模型解耦

Mini Harness 基于 OpenAI Python SDK 写成，但每个机制都能在 Claude Code、Codex 里找到对应实现。如果把 core.py 的主循环换到 Anthropic SDK，只需要动 API 调用、循环结束判断、tool call 位置、结果回写格式、tool schema 字段这 5 处——Context Management、Progress Tracking、Permission Gate 等深层机制一行代码都不需要动。Harness 的架构逻辑与模型提供商是完全解耦的。

结论三：Harness 会 go stale，它是工具不是信仰

Anthropic 在 2026-03-24 的博客中坦率承认："Every component in a harness encodes an assumption about what the model can't do on its own"。今天你为 agent 加 Permission Gate，是因为模型可能误执行危险命令；如果未来模型默认就能做到"不执行危险命令"，这个组件就可以从 Harness 里移除。随着模型能力提升，Harness 的组件会慢慢过时——这不是劝退，是让你建立正确的成本直觉。

七、Mini Harness vs 生产级工具对照

机制	Mini Harness	Claude Code 生产版	OpenAI Codex 生产版
Agent Loop	`while` + `max_steps=50`	多层事件驱动	App Server JSON-RPC
Context	`head(2)+tail(6)+middle summary`	5 层 compaction pipeline	AGENTS.md 渐进披露
Progress	`progress.md` 追加写	`claude-progress.txt` + git	待补充
Feature List	`todo_tool` JSON 状态机	200+ 项结构化清单	PLANS.md 持久化
Verification	pytest subprocess	Puppeteer MCP 真机	structural test
Subagents	`delegate` 递归隔离	`/agent` + 独立 workflow	待补充
Permission	正则黑名单 14 条	27 个 hook + 规则矩阵	sandbox policy
Hooks	`HookManager` 6 事件	Claude Code 27 事件	middleware 3 hook
Budget	`BudgetGuard` + `BudgetExceeded`	token budget + iteration cap	per-model quota

Mini Harness 是"裸骨架"——功能极简，但结构透明；生产工具是成熟系统——功能丰富，但内部封装。学完骨架，以后读生产工具的源码时，你会认出每一块肌肉。

附录：关键术语快速检索

术语 / 机制	核心文件	关键函数 / 类
Agent Loop	`core.py`	`run_agent`, `while steps < config.max_steps`
Tool Use	`core.py`	`dispatch_tool`, `_build_tool_schemas`
Progress Tracking	`progress.py`	`ProgressTracker.register_to`
Context Management	`context.py`	`compress_if_needed`, `estimate_tokens`
Feature List	`planner.py`	`todo_tool`（替换/合并/查询三模式）
Verification Loop	`verifier.py`	`verify_by_pytest`
Subagents	`subagent.py`	`delegate`
Generator-Evaluator	`evaluator.py`	`evaluate`, `temperature=0.3`
Hooks	`hooks.py`	`HookManager`, `trigger_gate`
Permission Gate	`permission.py`	`PermissionGate.check`, 14 条黑名单
Token Budget	`budget.py`	`BudgetGuard.add`, `BudgetExceeded`

参考引用

来源	日期	URL
Anthropic · Effective Harnesses for Long-Running Agents	2025-11-26	链接
Anthropic · Harness Design for Long-Running Apps	2026-03-24	链接
OpenAI · Unlocking the Codex Harness	2026-02-04	链接
Phil Schmid · The Importance of Agent Harness in 2026	2026-01-05	链接
AGENTS.md 规范	—	链接

本文基于 2026 年 4 月技术状态编写，使用 deepseek-chat 模型验证 E2E demo。依赖版本：openai==2.26.0、python-dotenv==1.2.2、pytest==9.0.3、httpx==0.28.1。

📎 参考文章

大模型Agent智能体开发实战

💡

欢迎您在底部评论区留言，一起交流~

Harness Engineering - 原理与概念

Fri, 03 Apr 2026 00:00:00 GMT

😀

本文聚焦 Claude Code / Codex / Cursor 这类 AI 编程产品背后那套共同的工程系统——驾驭工程（Harness Engineering）。它是 Agent = Model + Harness 公式的右半部分，也是 2025-2026 年 AI 工程社群共同识别出的新学科。
明明底层都是 Anthropic 或 OpenAI 的模型，为什么有的 Agent 能持续跑 30 分钟不失败，有的三轮就失控？为什么同样是 Sonnet 4.6，裸 API 调用和 Claude Code 的产出质量差了一个数量级？答案全部收敛到这套系统上。
📅 时效性说明：本文全部数据与引用截止 2026 年 4 月。

Harness Engineering 驾驭工程：原理与概念

一、驾驭工程是什么

1.1 三层次能力对比

很多人认为 ChatGPT、ChatGPT + Code Interpreter、Claude Code 三者的差距在于"模型越来越强"。这是一个典型误解。下面这张表用六个维度逐条比对：

表 1-1 三层次能力对比

维度	ChatGPT（裸对话）	ChatGPT + Code Interpreter	Claude Code
能写代码吗	能	能	能
能真跑代码吗	否	能（沙箱内）	能（你本地）
能读写你的文件系统吗	否	否（只能沙箱临时文件）	能（整个项目目录）
能跨工具编排吗（git/pytest/shell）	否	部分（Python 内）	能
能持续 30 分钟不失败吗	否	否（context 溢出）	能（机制保护）
任务失败时会自己补救吗	否	部分（在同一回合内）	能（跨回合 + 跨 session）

前两行三列几乎没有差距（都能写代码、都能在沙箱里跑），但从第 3 行开始三列几乎跨了三个时代。而三列用的模型——GPT-5 / GPT-5 / Sonnet 4.6——都是当前最前沿的旗舰，能力基础在同一梯队。造成巨大落差的只有一个变量：模型外面那一层，也就是 harness。

换个更直接的说法：把 Claude Code 里的 Sonnet 4.6 换成 GPT-5，它还是比裸的 GPT-5 强；把裸 ChatGPT 的模型升级到 Sonnet 4.6，它也追不上最朴素的 Claude Code。因为一次裸 API 调用没有文件系统、没有 git commit 能力、没有跨 session 的进度文件——这些差异不在模型权重里，在调用模型的那套系统里。

1.2 Agent = Model + Harness

Agent = Model + Harness
—— Vivek Trivedy 在首篇 HaaS 博文（2025-09-23）中给出这一公式化表达；Birgitta Böckeler 于 2026-04-02 在 martinfowler.com 整理传播。

这个公式可以类比成 F1 赛车：Model 是引擎，Harness 是底盘、变速箱、空气动力学、刹车、方向盘。引擎再强，没有底盘和刹车，跑不过 100 公里就失败；引擎差一点，但底盘调校好了，能在一个赛季跑满二十几个大奖赛。

先记住一个数字作为公式的第一块硬证据：同模型只改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7 个百分点。

1.3 同任务三模式

同一个任务"帮我实现一个待办应用，包括前端 HTML 和后端 Python + pytest"，三种模式的表现截然不同：

裸 API：返回三块代码，但永远不会真的创建文件、运行测试、看到测试失败后自己改。它只是在对话框里写字。

Code Interpreter：真的创建 .py 文件、运行 pytest、看到失败。但没有访问本地项目的能力，没有 git，关闭窗口所有进度清零。

Claude Code：在本地创建完整项目结构，写完代码跑 pytest，失败了就改，最后 commit 到 git，下次打开从进度文件接着跑。

三个画面的差距，不是"模型变聪明了"，是"模型外面被加了一层肉眼看不到的工程系统"。

二、承认抵触——为什么驾驭工程不是新瓶装旧酒

2.1 你的软件工程师直觉没有错

听到"Harness Engineering"这个新词，很多工程师的第一反应是抵触：

"这不就是 feedback control 吗？控制系统搞了几十年了。" "换个名字就能发博客涨粉。" "LangChain 三年前就在做这件事，只是现在包装成新概念。"

这些工程直觉都是对的。对新术语保持怀疑，是一个成熟工程师该有的态度。但怀疑不等于否定——接下来用四条硬数据说话。

2.2 四条来自一手源的证据

表 2-1 硬数据反击表

数据	出处	含义
同模型仅改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7pp，排名 Top 30 → Top 5	LangChain 博客 2026-02-17，Vivek Trivedy：Improving DeepAgents with Harness Engineering	harness 是可测量的工程变量
OpenAI 内测产品：5 个月、约 100 万行代码、约 1500 个 PR、全程零人工编码、开发时间约为传统方式的 1/10	OpenAI 工程团队 2026-02-11：Harness engineering: leveraging Codex in an agent-first world	harness 可承担生产级工程强度
Manus 团队 6 个月内重构 harness 5 次，每次都是删掉过时的复杂逻辑	Phil Schmid 2026-01-05：The importance of Agent Harness in 2026	harness 是活的工程系统
2026-04-02 Birgitta Böckeler 在 martinfowler.com 发表 "Harness engineering for coding agent users"	martinfowler.com	业界权威博客正式纳入

第一条告诉我们——harness 是可以被 benchmark 量化的。第二条告诉我们——harness 可以承担生产级强度。feedback control 没人给它发 +13.7pp 的 benchmark 证明，也没有公司敢说"用它写了约 100 万行零人工代码"。这不是换皮，是一个已经能拉硬数据的新工程学科。

2.3 译名锁定

本文主术语锁定为 "驾驭工程"。"驾驭工程"指代 Harness Engineering，"harness"（小写原词）指代具体的一套机制组合。

三、三代工程的包含关系与术语边界

3.1 三代工程：包含关系而非替代关系

你可能已经被"上下文工程取代提示词工程"这类标题党文章荼毒过。事实是——没有谁取代谁，只有谁包含谁。

三代工程是同心圆式的包含关系：

提示词工程（2022-2023）：管单轮 LLM 对话里如何把问题问得更好。

上下文工程（2024-2025）：管多轮对话里喂给 LLM 的信息如何更精准——包括 RAG、tool calling schema、对话历史管理、instruction caching。

驾驭工程（2025-2026）：管多轮工具调用 + 长时间运行时，整个系统如何不失败——包括循环刹车、状态持久化、验证闭环、子代理分治。

以 Claude Code 处理"写登录功能"为例：一次会话同时运行着三代工程的所有机制——Prompt Engineering 层的 system prompt、Context Engineering 层的 CLAUDE.md 读取和 tool schema 注入、Harness Engineering 层的 max_iterations 硬刹车和 progress 文件持久化。没有哪一层被"替代"，只有层层叠加。

3.2 术语边界

表 3-1 术语边界对照

术语	是什么	与 Harness 的关系
Agent	一个"会用工具完成任务"的软件实体	Agent 是目标，Harness 是让目标能持续运行的工程系统
Scaffolding	prompt 到达模型前的组装层	Scaffolding 是 Harness 的一部分（偏 context 装配层）
Framework	提供类库和抽象的开发工具包（LangChain 等）	Framework 是积木，Harness 是用积木搭出来的整车
Runtime	负责执行 agent 逻辑的运行时引擎（LangGraph 等）	Runtime 是发动机，Harness 是发动机 + 底盘 + 传动

⚠️ 常见误区：把 scaffolding 当 harness 的同义词。很多博客把 "prompt scaffolding" 和 "harness" 混用，让读者低估 harness 的工程复杂度。真正的 harness 必须覆盖：(a) 循环终止刹车、(b) 跨 session 进度持久化、(c) 真机功能验证——三者缺一就不是完整 harness。

3.3 LangChain 三层架构

LangChain 创始人 Harrison Chase 在 2025-10-25 博文 Agent Frameworks, Runtimes, and Harnesses - oh my! 里把产品线切成了三层：

表 3-2 LangChain 三层产品架构

层	LangChain 对应产品	角色	类比
Framework	langchain-core / integrations	提供 LLM / tool / retriever 的抽象基类	积木
Runtime	LangGraph	提供状态机 / checkpoint / interrupt 的执行引擎	发动机
Harness	DeepAgents	把 LangGraph 组装成"能跑长任务"的完整系统	整车

2026 年之后 LangChain 的主推产品从 AgentExecutor 转向 DeepAgents——前者是 Runtime 级别的抽象，后者本身就是一个 Harness 成品。大多数工程师需要的不是 runtime，是一个能直接跑的 harness。

四、为什么此刻是驾驭工程的拐点

4.1 Karpathy 的判断：2025 Q3 是分水岭

"Agents basically didn't work before December [2024]. Now they just barely work. And this is the window where harness engineering becomes real engineering." —— Andrej Karpathy（YC AI Startup School 2025-06-17 主题演讲）

关键词是"勉强（barely）"——不是说模型变神了，而是模型终于跨过了某个基准线，让"在模型外面围一层系统让它长时间运行"从不可能变成可行。

那个基准线大致可以用 SWE-bench 60% 通过率来标。当 Claude 3.5 Sonnet 在 2025 Q3 把 SWE-bench Verified 带到 60% 量级，模型已经能"完成多数简单任务"，在外面加 harness 才有边际收益。模型只有 30% 通过率时，harness 设计再好也救不了；模型 90% 通过率时，harness 要做的事反而变少。60-90% 这个区间，是驾驭工程的黄金窗口——恰好从 2025 Q3 开始。

4.2 8 节点时间轴

表 4-1 驾驭工程术语演化时间轴

#	日期	事件	作者
1	2025-09-23	博文首次使用 "Agent Harness" 术语	Vivek Trivedy
2	2025-10-25	博文引用并传播该术语	Harrison Chase (LangChain)
3	2025-11-26	官方首篇系统化博文	Anthropic, Justin Young
4	2026-01-05	提出 Bitter Lesson 三原则	Phil Schmid
5	2026-02-11	用生产实证定型术语	OpenAI 工程团队
6	2026-02-17	+13.7pp 实证证据	Vivek Trivedy @ LangChain
7	2026-02-18	三分框架推向大众	Ethan Mollick
8	2026-03-24	GAN 启发的三角色架构	Anthropic, Prithvi Rajasekaran

规律很明显：前 4 个节点是社群博客驱动的概念孵化；后 4 个节点是大厂用实证数据 + 官方架构博文把它钉成学科。六个月完成了一门学科从诞生到定型的完整周期。

4.3 两个决定性证据

证据一（LangChain 2026-02-17）：同模型、同 benchmark、只改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7 个百分点。
证据二（OpenAI 2026-02-11）：一个内测产品，5 个月、约 100 万行代码、约 1500 个 PR、全程零人工编码、开发时间约为传统方式的 1/10。

决定模型能不能上线的是模型本身，决定能不能稳定交付的是 harness。前者是 2023 年之前 AI 工程的核心问题，后者是 2026 年及以后的核心问题。

五、Naive Agent 的八大故障模式

5.1 ~50 行 Naive Agent 完整代码

下面是一段手写的 ~50 行 naive agent——它没有任何 harness 保护，所有 LLM + tool calling 就是教科书式的 while True + JSON schema。代码里用 # 故障 ①～⑧ 注释标出了主要失效点。

这段代码是一个诚实的 "tool-calling 教科书实现"——100 行左右完成了所有"必要的事"。如果你是刚学 Agent 的人，这就是你会从 OpenAI cookbook 里抄来的版本。它的罪不在写得差，在太朴素——朴素到完全没有防御性设计，也就完全没有 harness。

⚠️ 踩坑预警：subprocess.run 的 returncode 被丢弃。run_pytest 函数只返回 result.stdout，而 result.returncode 被直接丢掉——这意味着即使 pytest 失败，agent 拿到的也只是一段普通字符串，它会以为任务成功。正确做法：显式保留 returncode——return {"passed": result.returncode == 0, "output": result.stdout + result.stderr}。

5.2 八大故障模式清单

表 5-1 八大故障模式清单

#	故障名	症状	在 naive agent 中的表现
①	循环失控	Agent 无限循环，永远不停止	`while True` 无上限
②	Context 溢出	messages 列表无限增长，超出 token 上限	`messages.append(msg)` 无清理
③	Cache Miss	system prompt 每轮变化，prompt cache 全部失效	`[session_iter={i}]` 破坏前缀
④	Tool 错误吞	工具失败返回空字符串，agent 以为成功	`except: result = ""`
⑤	状态丢失	进程挂掉后进度全丢，无法续传	无任何持久化
⑥	缺权限闸	Agent 可以执行任何危险操作	无危险命令拦截
⑦	缺自动化评审	Agent 自报完成即退出，无独立验证	`else: break`
⑧	成本失控	无 token/cost 预算，跑多少烧多少	无 budget 控制

六、八大机制——逐一击破故障模式

6.1 Agent Loop 四相循环（解 ① 循环失控）

一句话定义：把一次 agent 迭代拆成 Gather Context（收集上下文）→ Take Action（执行动作）→ Verify（验证结果）→ Iterate（迭代改进）四个阶段，并硬性加上 max_iterations 和显式终止条件。

类比：驾校教练的四步口诀——"看路况 → 踩油门 → 看前方 → 调整方向"，跑 10 圈就必须停。

解哪条故障：故障 ① 循环失控——naive agent 的 while True 在这里被替换成 for i in range(MAX_ITER)，每轮还有显式的 verify 阶段做"能不能停"的判断。

最关键的一行是 for i in range(MAX_ITER) 取代了 while True。这个计数器背后的工程思维是：agent 不该完全信任模型的自我终止判断，系统必须有一个强制出口。

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）

6.2 Tool Use 工具编排（解 ④ tool 错误吞）

一句话定义：所有工具调用包裹在结构化 schema 里，失败时返回 {"status": "error", "error": "..."} 这样的结构化回传，而不是空字符串或异常被吞。

类比：USB-C 接口——任何设备插上都能通过标准协议读到身份、能力、故障码。

解哪条故障：故障 ④ tool 错误吞——naive agent 里 except: result = "" 是典型症状，修复方式是把 error 变成结构化 return，而不是字符串或异常。

对比 naive agent 的 except: result = ""——前者是"失败了装作没事"，后者是"失败了把失败本身当作第一公民返回"。agent 下一轮看到 status: error 才会触发修复路径。结构化错误是 agent 能跑长任务的第一块基石。

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）；MCP（Model Context Protocol）官方规范进一步标准化了这种 schema 契约。

6.3 Progress Tracking 进度追踪（解 ⑤ 状态丢失）

一句话定义：把每一步的进度写到一个持久文件 + 在完成里程碑时打 git commit，这样即使 session 断了，重启时能读取进度文件从断点续传。

类比：游戏存档——开放世界游戏每过一个小任务自动存档，断了能"读档"接着跑。

解哪条故障：故障 ⑤ 状态丢失——naive agent 里 session 关掉进度全丢，修复方式是把进度写磁盘 + 用 git 历史作为额外的 checkpoint。

没有它，agent 跑 30 分钟失败一次就得从零开始。Anthropic 官方的最佳实践更强：progress 文件 + git commit 双重 checkpoint——前者记录 agent 的思考过程，后者记录代码的物理改动。

官方出处：Effective Harnesses for Long-Running Agents（Anthropic，2025-11-26，Justin Young）

6.4 Context Management 上下文管理（解 ② context 溢出 / ③ cache miss）

一句话定义：持续监控当前 messages 的 token 数，超过阈值时触发压缩（compaction）或重置（reset），同时保持 system prompt 前缀稳定不变以命中 prompt cache。

类比：工位清理——文件堆到爬不动时，要么压缩（归档成一页摘要），要么重置（从空桌开始）。

解哪条故障：一次救两条——故障 ② context 溢出（压缩能降维度）和故障 ③ cache miss（保持前缀稳定才能命中 cache）。

最容易被忽略的是 messages[0] 这一行——system prompt 永远不动。prompt cache 是按前缀匹配的，前缀一变整个 cache 作废，延迟翻倍、费用翻倍。

⚠️ 踩坑预警：在 system prompt 里加时间戳、用户名、当前任务。很多开发者把当前任务状态写进 system prompt，以为"让模型知道当前在做什么"更好——实际上这会让每轮的 system prompt 前缀都不同，prompt cache 全部失效。正确做法：system prompt 只放固定的"角色定义"，当前任务全部放进 user 消息。

官方出处：Automatic Context Compaction Cookbook（Claude Agent SDK 官方）

6.5 Feature List 任务拆解（解 ② context 溢出的源头）

一句话定义：把大任务拆成独立的子任务清单（JSON 文件存在磁盘上），强制 agent 单次只做一件事，从源头控制 context 膨胀。

类比：待办清单——早上不会一口气处理 10 件事，而是列清单、做完一件划掉一件。

解哪条故障：故障 ② context 溢出的源头——naive agent 一次把 "读文件 + 修 bug + 跑 pytest" 全塞进去，context 自然爆。Feature List 把它切成 3 个独立子任务，每个子任务 context 小得多。

这张清单以 JSON 文件形式存在磁盘上，而不是放在 context 里——这样它不会随 messages 一起被压缩掉。

6.6 Verification Loop 验证闭环（解 ④ tool 错误的下游）

一句话定义：每个 feature 完成后，用 pytest / Playwright 等真机工具去实际验证功能，而不是只看 LLM 自己说"我觉得做好了"。验证失败就回退重做。

类比：QA 验收测试——开发说"我修好了"不算数，得 QA 真的点按钮、真的跑场景才算数。

解哪条故障：故障 ④ tool 错误吞的下游——光在工具调用层面返回 error 不够，任务层面必须有"真机验证"才能确认功能真的跑通。

对比 naive agent 的 run_pytest（丢掉了 returncode），这里显式保留 result.returncode == 0 作为 passed 判定——"通过"必须来自外部真实反馈，而不是 agent 自己说通过了。

Anthropic 官方还额外约束："不可接受删掉或修改测试，因为这会导致功能缺失或带 bug"——如果 agent 发现测试在报错，正确路径是"去修实现"，错误路径是"把测试改成能过"。

官方出处：Effective Harnesses for Long-Running Agents（Anthropic，2025-11-26）

6.7 Subagents 子代理分治（解 ② context 溢出的另一种解法）

一句话定义：把特定子任务派发给一个独立 context 的子 agent，子 agent 在自己的 messages 列表里工作、完成后只把结果返回主 agent，主 agent 的 context 完全不受子任务中间过程污染。

类比：外包给顾问——CEO 把专业问题外包给咨询顾问，顾问自己开独立项目，几周后只交一份结论。CEO 的主 context 没有被中间文档污染。

解哪条故障：故障 ② context 溢出的另一解法——主 agent context 保持干净，所有"脏活"（多轮试错、大量工具调用）都在子 agent 的独立 context 里消化。

sub_messages = [...] 不是从主 agent 的 messages 复制过来的，而是全新的独立列表。主 agent 拿到的只有子 agent 的最终 return 值，中间子 agent 跑了 20 轮工具调用主 agent 一无所知——正因为"一无所知"，主 context 才能保持干净。

官方出处：Building agents with the Claude Agent SDK（Anthropic，2025-09-29）

6.8 Generator-Evaluator（GAN 启发的三角色架构，解 ⑦ 缺自动化评审）

一句话定义：借鉴 GAN 的思路，把一个任务的处理流拆成三个独立角色的 agent——Planner（规划者）拆任务、Generator（生成者）写代码、Evaluator（评价者）独立评审。Evaluator 不看 Generator 的中间过程，只看最终产出，以"怀疑者"视角打分，不通过就打回。

类比：论文评审制度——作者写论文，审稿人不看写作过程只看论文本身，按评分标准打分；编辑在作者和审稿人之间做协调。三个角色分离才能保证质量。

解哪条故障：故障 ⑦ 缺自动化评审——naive agent 里没有任何独立评审角色，agent 自己说做完就做完；Generator-Evaluator 架构把"评审"作为一个独立 agent 机械执行的步骤，打破"生成者自评偏见"。

Evaluator 的 docstring 强调——"不看生成过程"。这是整个机制的精髓：如果让同一个 LLM 既做生成又做评审，它会倾向于为自己辩护；但如果把评审单独抽成一个 agent，给它一个"怀疑者"角色的 prompt，它就会认真挑刺。这就是 GAN 的核心——通过架构性约束制造对抗，而不是靠单 agent 的自我反思。

官方出处：Harness Design for Long-Running Application Development（Anthropic，2026-03-24，Prithvi Rajasekaran）

6.9 机制 × 故障模式对照表

表 6-1 八大机制 × 八大故障模式对照

机制	主解故障	辅解故障
Agent Loop 四相循环	① 循环失控	⑥ 缺权限限闸 ⑧ 成本失控
Tool Use 工具编排	④ tool 错误吞	—
Progress Tracking 进度追踪	⑤ 状态丢失	—
Context Management 上下文管理	② context 溢出 ③ cache miss	⑧ 成本失控
Feature List 任务拆解	② context 溢出（源头）	⑧ 成本失控
Verification Loop 验证闭环	④ tool 错误吞（下游）	—
Subagents 子代理分治	② context 溢出（另一解法）	⑧ 成本失控
Generator-Evaluator生成 - 评估对抗	⑦ 缺自动化评审	—

注：⑥ 缺权限闸和 ⑧ 成本失控的完整解决方案（Permission Gate 权限闸 / Token Budget 成本预算）后面讲解。

七、三支柱正交视角

7.1 三支柱定义

除了按"故障→机制"的视角看 harness，还可以从三个工程维度——三支柱——来正交切分：

表 7-1 三支柱核心问题与判断规则

支柱	核心问题	判断规则
Context Engineering	Agent 能看见什么信息？看见的信息是否准确精简？	如果一个机制在"整理 agent 接下来输入的信息"，它属于这一柱
Architectural Constraints	Agent 能做什么、不能做什么？动作空间在哪里有边界？	如果一个机制在"约束 agent 的能力或交互边界"，它属于这一柱
Garbage Collection	Agent 能跑多久？成本和资源怎么回收？	如果一个机制在"清理过期状态 / 限制成本 / 回收资源"，它属于这一柱

来源说明：三支柱是本课程综合 Martin Fowler 系博客（Böckeler 2026-04-02）、Anthropic Rajasekaran（2026-03-24）、Phil Schmid（2026-01-05）多来源抽象的工程维度框架。

7.2 三支柱视角的价值

以 Claude Code 为例走一次三支柱归类：

Context Engineering (输入端：怎么在第一时间把对的资料喂给它)：Claude Code 读取你项目目录里的 CLAUDE.md（相当于 RAG 系统 prompt）、在长会话时触发 session 压缩（compaction）、把进度写进 progress 文件——这三项都在"整理 agent 看见的信息"。

Architectural Constraints (控制流：它发疯的时候，你怎么硬生生把它按住)：Claude Code 提供 27 种 hook 让你约束工具行为、内置 Permission Gate 控制危险操作、通过 Task tool（subagent 机制）做分治隔离——这三项都在"约束 agent 能做什么"（设红线、拉电闸）。

Garbage Collection (状态流：内存快被撑爆时，怎么有策略地遗忘)：Claude Code 有 token budget 防爆预算、做 session compaction 回收过期上下文；Anthropic 2025→2026 的工程路线注释也在从 compaction 逐步转向 reset——这条支柱核心是容错与动态收敛。

看到一个新的 Agent 产品，可以立刻问两个问题：

按机制视角：它解了八大故障模式里的哪几条？

按支柱视角：它主要投资在哪一柱？

7.3 八大机制 × 三支柱对照表

表 7-2 八大机制 × 三支柱归属

机制	Context Engineering	Architectural Constraints	Garbage Collection	归属判断说明
1 Agent Loop 四相循环	辅	主	-	循环每轮都要整理 context；四相结构本身是架构约束
2 Tool Use 工具编排	-	主	-	工具 schema 本身就是一个动作空间的约束
3 Progress Tracking	主	辅	-	跨 session 的状态持久化属于 context 延展
4 Context Management	主	-	辅	本柱的核心；compaction 也有 GC 属性
5 Feature List	主	辅	辅	JSON 清单是 context 的规划层
6 Verification Loop	-	主	-	事件驱动的错误显性化属于架构约束
7 Subagents	主	辅	辅	分治隔离是架构性的边界划分
8 Generator-Evaluator	-	主	-	三角色分离是架构约束的典型实现
9 Permission Gate（待补）	-	主	-	危险操作拦截属架构约束；第二节课补
11 Token Budget（待补）	-	-	主	成本控制属 GC；第二节课补

八、生态地图——坐标系的实战运用

8.1 10+ 主流 Harness 产品全景

表 8-1 主流 Harness 产品清单

#	产品	开发方	一句定位
1	Claude Code	Anthropic	CLI-first 驾驭工程参考实现
2	Codex CLI	OpenAI	CLI-first，OpenAI 官方 harness 参考
3	Cursor	Anysphere	IDE-native harness，VS Code 深度集成
4	Windsurf	Codeium	IDE-native，体验对标 Cursor
5	Cline	VS Code 社区	IDE-native 开源插件，autonomous agent
6	Aider	开源社区	CLI-first 开源，git commit 深度集成
7	Amp	Sourcegraph	CLI-first，代码搜索 + agent 结合
8	Roo Code	开源社区	IDE-native VS Code 扩展
9	DeepAgents	LangChain	SDK-harness，基于 LangGraph 的 harness 组件库
10	Devin	Cognition	Cloud-sandbox，完全托管的 autonomous agent
11	JetBrains Junie	JetBrains	IDE-native，JetBrains 系 IDE 集成

8.2 四系家族树

11 个产品可以归成四个"家族"：

表 8-2 四系家族特征对比

家族	主要特征	典型代表	适用场景	局限性
CLI-first	命令行为主入口，跑在本地 terminal	Claude Code / Codex CLI / Aider	后端开发、系统工程	需要命令行习惯，无 GUI
IDE-native	IDE 内置集成，UI 优先	Cursor / Windsurf / Cline / Junie	前端开发、IDE 生态依赖者	重依赖特定 IDE 生态
Cloud-sandbox	云端完全托管，无需本地环境	Devin	团队协作、远程长任务托管	成本较高、数据隐私顾虑
SDK-harness	提供 SDK 自建 harness	DeepAgents (LangChain)	定制化场景、嵌入自家产品	集成复杂度高

九、三句官方警示——harness 不是银弹

9.1 警示一：harness 会过时

"A harness encodes assumptions that go stale. What works for Claude 3.5 may not work for Claude 4.5." ——Anthropic 官方博文（2025-11-26，Justin Young）

harness 固化了一组关于模型的假设，这些假设会过期。不要把 harness 当成一次性架构写死，要像管理软件一样持续迭代。

判断 harness 是否过时的信号：同样任务的成功率下降 5pp 以上、需要频繁手动干预、新模型版本上线后 benchmark 反而退步。

9.2 警示二：Build to Delete（建造以便删除）

"The best harness is the one you're most willing to throw away and rewrite. The dataset of failures from your current harness is more valuable than the harness itself." ——Phil Schmid（2026-01-05，Bitter Lesson 三原则之一）

最好的 harness 是最愿意扔掉重写的那个。当前 harness 的失败样本比 harness 本身更有价值。不要给 harness 加舍不得删的复杂度。Manus 团队 6 个月重构 5 次的故事，本质就是这句话的实战演绎——每一次重构，都是因为上一版"舍不得删的设计"成了下一版的瓶颈。

9.3 警示三：三大开放争议还没定论

驾驭工程作为新学科，有三个核心设计选择社群仍在争论：

多 Agent（Subagents 分治）vs 单 Loop（Feature List 拆分）：多 Agent 隔离性更好但协调开销更大；单 Loop 简单可控但 context 膨胀压力全在一个 loop 里。

Compaction（压缩旧 context）vs Reset（重置 context 重来）：compaction 保留历史但引入摘要噪声；reset 干净但丢失跨 session 推理链，强依赖 Progress Tracking 做外置记忆补救。

CLI-first vs IDE-native：CLI-first 擅长长任务自主运行 + 脚本化编排；IDE-native 擅长行内交互式修改 + 视觉反馈。两种哲学尚未分出胜负。

如果有人告诉你"正确答案就是 X"，保持警惕——这门学科还在演化中。

十、总结

Agent = Model + Harness（Vivek Trivedy 原创；Böckeler @ martinfowler.com 传播）

八大故障模式——①循环失控 ②context 溢出 ③cache miss ④tool 错误吞 ⑤状态丢失 ⑥缺权限闸 ⑦缺自动化评审 ⑧成本失控

八大机制——Agent Loop / Tool Use / Progress Tracking / Context Management / Feature List / Verification Loop / Subagents / Generator-Evaluator

三支柱正交视角——Context Engineering / Architectural Constraints / Garbage Collection

四系家族树——CLI-first / IDE-native / Cloud-sandbox / SDK-harness

驾驭工程不是"feedback control 换皮"，它是一套被八大故障模式逼出来、由八大机制实现、在三支柱坐标系下工作、在 10+ 个真实产品上落地、但注定会过时所以必须准备随时删除的工程学科。

📌 信息源归属：
Agent = Model + Harness 公式：Vivek Trivedy（2025-09-23 首篇 HaaS 博文）/ Birgitta Böckeler @ martinfowler.com（2026-04-02）
Terminal Bench +13.7pp 实证数据：LangChain 博客 2026-02-17，Vivek Trivedy（原文链接）
OpenAI 约 100 万行 / 零人工编码 / 1/10 时间：OpenAI 工程团队博文 2026-02-11
八大机制主要出处：Claude Agent SDK 博文（2025-09-29）+ Anthropic Effective Harnesses（2025-11-26）+ Anthropic Harness Design（2026-03-24）
术语首用节点：Vivek Trivedy（2025-09-23）

📌 术语：
术语
含义
pp
percentage point，百分点。例 "+13.7pp" 即"提升 13.7 个百分点"
Terminal Bench 2.0
Stanford 推出的终端任务基准，考核 Agent 在真实 shell 环境完成复杂任务的通过率
SWE-bench / SWE-bench Verified
Princeton 提出的 GitHub issue 修复基准；Verified 是经人工复核的高质量子集
prompt cache
LLM 按输入前缀命中的缓存机制，前缀不变可复用，前缀被改写则缓存全部作废
HaaS
Harness-as-a-Service，由 Vivek Trivedy 在 2025-09-23 首篇博文中创造
GAN
Generative Adversarial Network，生成对抗网络，核心思路是"生成者 vs 鉴别者"对抗提升质量
Bitter Lesson
Rich Sutton 2019 年 AI 经典论文——简单通用方法最终胜过复杂领域知识

📎 参考文章

大模型Agent智能体开发实战

💡

欢迎您在底部评论区留言，一起交流~

07 Vibe Coding

Fri, 10 Apr 2026 00:00:00 GMT

😀

SDD 三大框架对比

1 三大框架核心信息

框架名称	定位标签	背景与适用场景	核心流程/特点	特性
OpenSpec	最轻量	Fission-AI (YC) 出品三步工作流适合 Brownfield（遗留项目）+ 轻量变更	聚焦「为什么做这个变更」（变更上下文）	✅ `/verify` 三维验证 ✅ Delta Spec 增量更新 ✅ 24+ AI 工具零锁定
spec-kit	最完整	GitHub 官方出品四步流程适合 Greenfield（全新项目）大型项目	聚焦「该构建什么」（规格说明）	✅ Constitution 深度约束 ✅ 项目级规则强制执行 ✅ 完整需求→代码全流程
Superpowers	最自动	obra·Skills 框架适合高质量交付场景	聚焦「代码写对了吗」（质量保证）	✅ 自动 TDD 纪律性执行 ✅ 行为驱动开发内置 ✅ Skills 自动化流程

2 三框架核心差异（互补不互斥）

OpenSpec：负责「为什么做这个变更」——管理变更上下文，适配遗留项目与轻量迭代

spec-kit：负责「该构建什么」——管理规格说明，为大型新项目提供完整流程与约束

Superpowers：负责「代码写对了吗」——管理质量保证，通过自动化流程保障交付质量

OpenSpec

OpenSpec 项目架构 & 工作流

核心定位：类 Git 逻辑，管理需求规格变更

1 项目架构（src/ 目录）

模块	核心内容
cli/	Commander.js 命令行入口
commands/	命令实现层，封装子命令逻辑
core/（重点）	init.ts（29KB 核心文件）、archive.ts（归档+Delta 合并）、specs-apply.ts（Delta 合并算法）、Zod 验证、24 个 AI 工具适配器
prompts/	AI 交互 Prompt 模板
schemas/	内置工作流 Schema 定义

核心文件速记：init 控核心流程、archive 管归档、specs-apply 是 Delta 算法核心

2 核心工作流（标准四步）

步骤	操作	核心作用
1	openspec init	初始化项目，检测并配置 AI 工具
2	/opsx:propose	AI 生成提案（Why 变更原因+规格变更+任务清单）
3	/opsx:apply	按任务清单，落地规格变更至代码
4	openspec archive	Delta 合并入主规格，归档 Why/What/How 变更记录

3 两种工作流模式

模式	流程	特点
Core（默认）	propose → apply → archive	3 步完成，简洁高效，适配常规迭代
Expanded	new → continue → apply → verify → archive	5 步流程，支持精细控制，适配复杂变更

4 Delta 规格系统（类 Git diff）

变更类型	标识	核心说明	示例
新增	ADDED	新增需求条目（含 Given/When/Then 场景）	导出 PDF 功能
修改	MODIFIED	调整已有需求	登录超时 30min→15min
删除	REMOVED	废弃需求（历史完整归档）	旧版 API 过渡至 v2 后不再维护

OpenSpec 安装 & 目录拆解

核心定位：三步安装，快速搭建 AI 协作基础设施

1 安装三步流程

步骤	操作	核心说明
1	`npm install -g openspec`	全局安装，要求 Node.js ≥ 20.19
2	`openspec init`	交互式生成项目目录结构
3	`config profile`	配置单/多命令，适配不同工作流

2 目录结构拆解（`openspec/`）

目录/文件	核心作用
`config.yaml`	项目配置，主动注入每次请求
`specs/`	系统当前行为的完整描述（源真相）
`changes/`	变更提案区，每个功能一个独立文件夹

🔗 Git 类比

specs/ ≈ main 分支 — 「当前系统长什么样」

changes/ ≈ feature 分支 — 每个功能独立开发

archive ≈ merge — 归档时合并变更到主 Spec

3 命令 Profile 类型

类型	包含命令	特点
`core profile`	`propose` / `apply` / `archive`	仅 3 个核心命令，简洁高效
`custom profile`	`propose/apply` / `archive/verify` / `onboard/sync` 等	共 11 个命令，支持更精细的流程控制

切换命令示例：

4 跨工具语法差异

工具	命令语法	说明
Claude Code	`/opsx:propose`	冒号分隔
Cursor / Windsurf	`/opsx-propose`	连字符分隔
所有工具	功能完全相同	仅语法形式不同，逻辑一致

config.yaml · 项目的「AI 宪法」

核心定位：替代传统 project.md，以 主动注入 替代 被动读取，保障 AI 协作确定性

1 为什么用 config.yaml？

对比项	旧方案（project.md）	新方案（config.yaml）
读取机制	被动读取，AI 可能读不到	主动注入，100% 生效，无遗漏
稳定性	不确定（读/不读全看 AI）	100% 稳定，强制注入每个请求
定位	文档参考	AI 协作核心配置（项目的“宪法”）

2 三层结构（从基础到核心）

层级	作用	特点
schema	定义工作流类型	基础配置，一般不改
context	全局上下文，核心层	极度精炼，主动注入每个请求
rules	格式规则约束	按 artifact 类型分层（proposal/specs/design/tasks 各有标准）

3 context 三铁律（核心准则）

原则	核心要求	目的
✅ 极度精炼	只写 AI 不知道的项目特殊约定；通用最佳实践不用写	减少 token 消耗，避免冗余
✅ 活文档	AI 忽略了就加，膨胀了就剪	始终保持精炼、有效
✅ 超 10 行审视	context 每字都是 token 成本	控制长度，优化性能

4 核心结论

主动注入 > 被动读取 context 每一字节都是 token 成本 → 精炼是优化性能的第一步

CLAUDE.md 分阶段交互

核心目标：通过分阶段控制，防止 AI 「错上加错」，大幅降低修复成本

1 核心规则

在 CLAUDE.md 中写明交互规则：

每完成一个 Phase → 暂停总结 → 等待用户确认 → 再继续下一个阶段

2 两种交互模式对比

对比项	无分阶段规则（AI 默认行为）	有分阶段规则（CLAUDE.md 控制）
执行逻辑	AI 一口气写完所有 Phase，追求快速交付	每完成一个 Phase 必须暂停，先总结变更，等待确认再继续
偏差处理	Phase 1 出现理解偏差后，后续阶段在错误上继续堆叠	Phase 1 完成即可发现偏差，仅需修正约 50 行代码，损失最小
问题暴露时机	写 500-1000 行代码后，才发现方向根本错误	偏差早期暴露，可立即调整方向，后续阶段在正确基础上推进
修复成本	极高，几乎等于全部重写	极低，仅需修正少量代码，避免大规模返工
核心效果	错上加错，越走越偏	小步快跑，精准迭代，全程可控

3 关键结论

分阶段控制是 AI 协作的“刹车”，能把错误扼杀在早期阶段

修复成本差异巨大：50 行 vs 1000 行，本质是「小修小改」和「推倒重来」的区别

CLAUDE.md 规则的核心，就是强制 AI 进入「暂停-确认-继续」的循环，避免一次性写死

OpenSpec 三步核心工作流 + 四件制品

核心目标：用「先设计、后编码」的方式，把返工时间压到最低

1 完整工作流（含可选步骤）

关键节点：propose 阶段生成全部四件制品，是整个流程的核心输入

2 四件制品详解（核心交付物）

制品	定位	核心内容
`proposal.md`	为什么做	意图：变更要解决的问题范围：影响的模块方法：大致实现思路 out-of-scope：明确不做什么，防止 AI 越界
`specs/`	做什么	Delta Spec 格式（只写变化部分）： • ADDED 新增需求 • MODIFIED 修改已有需求 • REMOVED 删除需求（不重写整个文件，是 OpenSpec 高效的关键）
`design.md`	怎么做	技术方案选型架构决策及理由数据流描述涉及的文件清单
`tasks.md`	执行清单	带 checkbox 的分阶段任务按 Phase 分组，每个 Phase 有验证步骤 AI apply 时逐个标记 [x] checkpoint 防止 AI 跑偏

3 效率对比：直接写代码 vs OpenSpec 流程

方式	时间投入	结果
直接写代码	2h 编码 + 1h 返工 = 3h ❌	返工成本高，方向错误代价极大
OpenSpec 流程	propose 5min + review 10min + apply 1.5h + verify 5min ≈ 2h ✅	省的不是编码时间，是返工时间

4 核心认知

propose 不是写代码，而是交出设计方案给你审查

审查几十行的设计，比审查几百行的代码容易 10 倍

上游花 10 分钟打磨 proposal，能省下下游 2 小时返工

工程实践：先结构化需求 + 总结架构，再进行 propose

out-of-scope 关键点 & Review 不可跳过

核心原则：明确“不做什么” + 严格执行评审，杜绝 AI 越界与返工

1 AI 的「善意」陷阱

场景	风险表现	核心逻辑
需求不完整	只要求导航栏，AI 顺带引入动画库、搜索功能	AI 会基于“善意”补充未明确需求
后果	功能溢出，偏离预期	未声明“不做什么”，AI 无法判断边界
关键认知	告诉 AI「不做什么」，和告诉它「做什么」同等重要	双向定义才能精准控制范围

2 out-of-scope 实操

操作	具体示例	效果
在 `proposal.md` 中明确写出「不做」清单	✅ 不做动画效果 ✅ 不做搜索功能 ✅ 不接入后端 API	AI 严格遵守，绝不越界，100% 可控

3 Review 不可跳过

环节	内容	成本对比
时机	`propose` 阶段之后	-
审查对象	「设计方案」（几十行），而非直接看代码（几百行）	设计评审成本远低于代码返工
耗时	仅需 5-10 分钟	-
价值	发现问题 → 改设计方案，成本极低	避免后续生成 1000 行错误代码的大规模返工
核心结论	越早发现问题，修改代价越小	本质是“止损”，而非节省时间

4 反模式 #2：跳过提案打磨，直接 apply

反模式	形象类比	后果
不做 `propose` 和 `review`，直接执行代码生成	不看建筑图纸直接开工	最常见的反模式，代价最高，必然返工

5 完整 OpenSpec 闭环

完整 OpenSpec = in-scope 清单 + out-of-scope 清单 + review 通过 → AI 精准执行，绝不越界

/opsx:verify 三维验证 · 一页速记清单

核心定位：事后验证（代码写完后），通过 3C 模型查漏补缺，确保交付质量，而非“唯一防线”

1 三维验证框架（3C Model）

维度	核心问题	检查要点
Completeness（完整性）	所有任务完成了吗？需求都有对应代码吗？	✅ 全任务 Check 状态 ✅ 全需求覆盖代码实现
Correctness（正确性）	实现匹配规格意图吗？边界条件处理了吗？	✅ 实现与 Spec 一致 ✅ 边缘场景已处理
Coherence（一致性）	`design.md` 方案在代码中体现了吗？命名一致吗？	✅ 代码落地设计方案 ✅ 命名/结构无冲突

2 真实输出样例

3 输出三级判定

等级	定义	处理策略
CRITICAL（必须修复）	阻断归档的致命问题	必须修复，否则无法归档
WARNING（建议修复）	不阻断归档的潜在风险	建议修复，不强制阻断
SUGGESTION（锦上添花）	优化建议，非硬性要求	按需采纳，提升质量

4 关键认知与边界

🚨 啊哈时刻

AI 跑完 apply 可能自认“搞定”，但 /opsx:verify 能快速暴露 WARNING

验证的核心价值：在“以为做完”的瞬间，用规范判定实际未完成

🆚 与 /analyze 的区别

命令	阶段	定位	关系
`/opsx:verify`	事后验证	代码写完后，校验交付物	两者互补，不替代
`/opsx:analyze`	事前检查	文档/提案阶段，预排风险	ㅤ

5 核心原则

verify 不阻止归档：即使存在 WARNING，用户仍可选择归档，拥有最终决定权

第一道防线：verify 是质量把关的首要环节，但不是唯一防线

省返工：通过早期校验，把问题扼杀在归档前，降低后期维护成本

Delta Spec——只写变化，不重写整个需求

1 全量 Spec vs Delta Spec 对比

方式	操作	缺点
❌ 全量 Spec	每次改需求都要重读整个 spec 文件、重写全部章节内容	AI 需处理大量 token，容易「丢东西」
✅ Delta Spec	每个 change 只描述自己的变化，spec 文件很小	AI 精准处理，不容易「丢东西」

2 Delta Spec 三种变更类型

ADDED：新增需求

MODIFIED：修改已有需求

REMOVED：删除需求

实操场景示例

以 add-projects-section 变更为例：

ADDED: 新增 Projects 展示区域

MODIFIED: Hero CTA 按钮锚点改为跳转 → #projects

3 归档行为

ADDED：追加到主 spec

MODIFIED：替换对应部分

REMOVED：从主 spec 删除

4 为什么高效

每个 change spec 文件很小 → AI token 消耗少

不容易「丢东西」

精准聚焦当前变化

5 MODIFIED vs 新建 spec 决策规则

扩展已有模块 → 使用 MODIFIED

全新业务域（首次） → ADDED 新文件

判断依据：主 spec 里有没有对应内容？

6 核心结论

每个 Delta Spec 文件只有变化部分 → AI 精准聚焦 → 不丢需求，不错改

术语	含义
pp	percentage point，百分点。例 "+13.7pp" 即"提升 13.7 个百分点"
Terminal Bench 2.0	Stanford 推出的终端任务基准，考核 Agent 在真实 shell 环境完成复杂任务的通过率
SWE-bench / SWE-bench Verified	Princeton 提出的 GitHub issue 修复基准；Verified 是经人工复核的高质量子集
prompt cache	LLM 按输入前缀命中的缓存机制，前缀不变可复用，前缀被改写则缓存全部作废
HaaS	Harness-as-a-Service，由 Vivek Trivedy 在 2025-09-23 首篇博文中创造
GAN	Generative Adversarial Network，生成对抗网络，核心思路是"生成者 vs 鉴别者"对抗提升质量
Bitter Lesson	Rich Sutton 2019 年 AI 经典论文——简单通用方法最终胜过复杂领域知识