企业官网建设流程全解析

Freebuff 自定义 Agent 开发完全指南：用 TypeScript 编排多智能体协作工作流

【免费下载链接】freebuffThe free coding agent项目地址: https://gitcode.com/GitHub_Trending/cod/freebuff

Freebuff（Codebuff 的开源免费版）是一个通过自然语言指令直接编辑代码库的 AI 编程助手，其核心能力在于多智能体协作：它不是让单个模型包揽一切，而是编排一组高度专业化的 Agent 各司其职、协同完成任务。本指南以仓库中随项目分发的新手模板 initial-agents-dir/README.md 为主体，结合同目录下的类型定义、示例与校验源码，完整讲解如何从零编写、测试、发布自定义 Agent，并深入解释AgentDefinition的每一个字段、handleSteps生成器的运行机制以及 Agent 间协调的原理。读完本文，你将能够基于 TypeScript 写出可复用的专用 Agent，并把它发布到 Agent 市场中供全球用户调用。

一、多智能体工作流：为什么需要它

现代软件项目是包含数千个文件、多种框架、复杂依赖和领域化需求的庞大生态系统。单个 AI Agent 试图理解并修改这样的系统时，面临的根本限制不仅是"知识不够"，更是单次能处理的上下文信息量有限。

模板文档给出的解法是"聚焦上下文窗口"（Focused Context Windows）：当面对 10 万行以上的大型代码库时，把大任务拆成一个个聚焦的子问题，每个专家 Agent 只接收它需要的窄上下文——安全 Agent 只看鉴权代码，而不是 UI 组件——这样每个 Agent 的上下文都保持在可控范围内，同时整体覆盖依旧完整。

需要强调的是，这与"模仿人类组织架构"无关。模板文档明确指出：简单地创建一个"前端开发工程师"Agent 并没有抓住要点。AI Agent 没有人类那样的上下文切换成本或开会需求，它的力量来自超专业化——在狭窄领域内比人类处理得更深，再与其他专家无缝协调。

文档给出的典型调用链是：当你要求"给 API 添加认证"时，Codebuff 可能会依次/并行调用：

1. File Explorer Agent：扫描代码库，理解架构，找到相关文件；
2. Planner Agent：规划哪些文件需要修改、按什么顺序改；
3. Editor Agent：执行精确编辑；
4. Reviewer Agent：校验改动是否合理。

这套多智能体方法带来更好的上下文理解、更精确的编辑和更少的错误。模板文档还提到，它在 175+ 个覆盖多个开源仓库的真实任务评测中对 Claude Code 取得了 61% vs 53% 的对比成绩（该数据出自随仓库分发的模板 README，具体评测口径可参考仓库根目录下的 README.md 与evals/目录）。

二、快速开始：三步走

模板文档给出清晰的三步流程，配合 my-custom-agent.ts 这个可直接编辑的起点文件：

1. 编辑现有 Agent：以my-custom-agent.ts为起点，按需修改；
2. 测试你的 Agent：运行codebuff（不带--agent参数），让本地的.agents目录被加载，然后在提示符中通过@my-custom-agent呼起它；
3. 发布你的 Agent：运行codebuff publish your-agent-name，全世界用户即可使用。

模板文件的头部注释完整记录了这套使用流程：

# 进入项目后启动 codebuff codebuff # 在 codebuff 会话内通过 @ 提及自己的 Agent @my-custom-agent please review my recent changes # 发布到 Agent 市场 codebuff publish my-custom-agent

.agents 目录结构

自定义 Agent 放在项目的.agents/目录下（模板目录initial-agents-dir就是其初始化骨架，实际落盘时即映射为.agents/）。模板骨架包含：

• my-custom-agent.ts：可直接编辑的起点 Agent；
• examples/：三个按难度递进的完整示例；
• types/：类型定义（agent-definition.ts、tools.ts、util-types.ts），为编写 Agent 提供完整的 TypeScript 类型安全与智能提示；
• skills/：可复用的技能（Skill）机制，含一个example-skill示例。

起点模板逐行解读

my-custom-agent.ts 是官方给出的最小可运行 Agent，全文如下：

import type { AgentDefinition } from './types/agent-definition' const definition: AgentDefinition = { id: 'my-custom-agent', displayName: 'My Custom Agent', model: 'anthropic/claude-haiku-4.5', spawnableAgents: ['codebuff/file-explorer@0.0.6'], // Check out .agents/types/tools.ts for more information on the tools you can include. toolNames: ['run_terminal_command', 'read_files', 'spawn_agents'], spawnerPrompt: 'Spawn when you need to review code changes in the git diff', instructionsPrompt: `Review the code changes and suggest improvements. Execute the following steps: 1. Run git diff 2. Spawn a file explorer to find all relevant files 3. Read any relevant files 4. Review the changes and suggest improvements`, } export default definition

注意这里几个细节：

• id使用小写字母加连字符（my-custom-agent）；
• model是可从 OpenRouter 选用的任意模型标识，这里用的是anthropic/claude-haiku-4.5；
• spawnableAgents中的codebuff/file-explorer@0.0.6是带 publisher 和版本号的完整限定 Agent ID，说明该 Agent 可以派生其他已发布 Agent；
• toolNames只声明了三个工具，从源码结构看（见下文agent-definition.ts），未声明toolNames时默认提供常用工具集，显式声明则严格限制其工具范围；
• spawnerPrompt告诉其他 Agent"什么时候应该派生我"；
• instructionsPrompt是该 Agent 的行为指令核心。

三、AgentDefinition 结构与核心属性

每个 Agent 都是一个 TypeScript 文件，默认导出一个AgentDefinition对象。模板文档给出了最小骨架：

export default { id: 'my-agent', // 唯一标识（仅小写字母与连字符） displayName: 'My Agent', // 人类可读名称 model: 'claude-3-5-sonnet', // 使用的 AI 模型 toolNames: ['read_files', 'write_file'], // 可用工具 instructionsPrompt: 'You are...', // Agent 行为指令 spawnerPrompt: 'Use this agent when...', // 其他 Agent 何时派生它 spawnableAgents: ['helper-agent'], // 它可派生的 Agent // 可选：程序化控制 async *handleSteps() { yield { tool: 'read_files', paths: ['src/config.ts'] } yield 'STEP' // 让 AI 处理并响应 }, }

必填字段

可选字段

类型定义中的完整字段清单

上述只是模板文档的入门摘要。真正完整的字段清单定义在 types/agent-definition.ts 的AgentDefinition接口中，除上述字段外还包括大量进阶配置：

• version/publisher：版本号与发布者 ID。版本号不填时默认0.0.1，每次 publish 自动递增；发布 Agent 必须提供publisher。
• reasoningOptions：OpenRouter 推理 token 控制，max_tokens与effort（'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none'）二者必填其一；exclude: true时从响应中移除推理内容。
• providerOptions：OpenRouter 的 provider 路由控制，包括order（按序尝试的 provider 列表）、allow_fallbacks（主 provider 不可用时是否允许回退，默认 true）、require_parameters、data_collection（'allow' | 'deny'）、only/ignore（白名单/黑名单 provider）、quantizations（量化级别过滤）、sort（按price/throughput/latency排序）、max_price（各计费维度价格上限）。
• mcpServers：MCP 服务器配置（stdio 或 http/sse 两种形态，见下文）。
• inputSchema：派生该 Agent 所需的输入 schema，prompt提供字符串描述，params提供 JSON Schema 对象。类型注释中特别提示：80% 的情况下只需要prompt字符串描述。
• outputMode：'last_message'（默认，取最后一条消息）、'all_messages'（含全部工具调用与结果）、'structured_output'（强制输出 JSON 对象）。
• outputSchema：structured_output模式下的 JSON Schema。
• includeMessageHistory：是否把父 Agent 的对话历史带进上下文（默认 false，需要了解之前所有消息时开启）。
• inheritParentSystemPrompt：是否继承父 Agent 的系统提示词以复用 prompt 缓存前缀（默认 false，不能与systemPrompt同时使用）。
• windowedFileReads：启用窗口化文件读取（read_files支持{ path, offset, limit }，整文件读取有上限，glob 结果有上限），默认 false 保持传统读取行为。
• suppressCommitAttribution：去掉run_terminal_command提交指导中的署名尾注（Co-Authored-By/ "Generated with" 行），适用于代替他人提交的场景。
• compactContext：机械式上下文压缩。可为布尔值或对象{ maxContextLength, cacheExpiryMs, cacheExpiryMinTokens }。压缩在上下文超过模型预算时触发；cacheExpiryMs调节空闲阈值，传null则只在上下文超限时压缩；cacheExpiryMinTokens是冷缓存跳过压缩的最小上下文门槛。
• systemPrompt：Agent 的背景信息（可选，官方建议优先用instructionsPrompt）。
• stepPrompt：每个 Agent 步骤插入的提示词，对模型行为改变力强，但通常非必需。
• handleSteps：程序化步进生成器，见第五节。

关于模型标识，类型定义中枚举了推荐模型（agent-definition.ts），覆盖 OpenAI（gpt-5.3 / gpt-5.2 / gpt-5-mini / gpt-5-nano 等）、Anthropic（claude-opus-4.7 / claude-haiku-4.5 / claude-sonnet-4.5 等）、Gemini（gemini-3.1-pro / gemini-3-flash 等）、Qwen（qwen3-max / qwen3-coder 等）、DeepSeek（deepseek-v4-pro / deepseek-r1-0528 等）、小米 MiMo、Kimi、GLM、MiniMax 等；同时以(string & {})兜底，允许任意 OpenRouter 模型。

四、可用工具详解

toolNames字段从 types/tools.ts 的ToolName联合类型中选择。模板文档按功能分组介绍：

文件操作类

执行类

Web 与研究类

完整工具列表（源码级）

types/tools.ts 中实际定义了 28 个工具，除上述外还包括：apply_patch（Codex 风格补丁）、ask_user（向用户提多选问题并暂停）、find_files（自然语言找文件）、glob（glob 匹配文件）、list_directory、read_subtree（整棵目录子树）、add_message（向对话历史注入消息）、set_messages、set_output（设置结构化输出并回传父 Agent）、skill（按需加载技能）、suggest_followups、task_completed、think_deeply（逐步深度思考）、write_todos（维护多步实施计划）、render_ui（渲染 CLI 小组件）、lookup_agent_info、propose_str_replace/propose_write_file（提议式编辑，不实际落盘）、run_file_change_hooks、cloud_plan_ready、gravity_index等。每个工具的完整参数类型都定义在ToolParamsMap中，是编写 Agent 时最值得查阅的权威参考。

五、程序化控制：handleSteps 生成器

handleSteps是AgentDefinition中最强大的能力：它是一个生成器函数，让你把AI 推理与程序化逻辑混合起来。模板文档给出了三种 yield 语义：

• yield 'STEP'：让 AI 处理并生成一条助手消息；
• yield 'STEP_ALL'：让 AI 持续运行直到调用end_turn或某条消息不再包含工具调用；
• yield { tool: 'tool_name', ...params }：直接执行工具调用，并把结果作为生成器的 next 值返回。

基础用法示例：

async *handleSteps() { // 执行一个工具 yield { tool: 'read_files', paths: ['package.json'] } // 让 AI 处理结果并响应 yield 'STEP' // 条件逻辑 if (needsMoreAnalysis) { yield { tool: 'spawn_agents', agents: ['deep-analyzer'] } yield 'STEP_ALL' // 等待派生的 Agent 全部完成 } // 最终 AI 响应 yield 'STEP' }

生成器上下文的完整形态

类型定义（agent-definition.ts）展示了handleSteps收到的AgentStepContext，包含：

• agentState：含agentId、runId、parentId、messageHistory（对话历史）、output（set_output设置的值）、systemPrompt、toolDefinitions、contextTokenCount（经 token-count 接口更新的上下文 token 数）；
• prompt：用户（或父 Agent）发来的提示词；
• params：入参对象（配合inputSchema.params使用）；
• model：当前步骤实际运行的模型（handleSteps会被toString()序列化，不能闭包捕获请求期状态，因此要从这里读取模型来估算上下文预算）；
• contextPruning：运行时解析好的上下文剪枝阈值（maxContextLength、cacheExpiryMs、cacheExpiryMinTokens），供派生context-pruner使用；
• logger：debug/info/warn/error四级日志接口。

工具调用的类型是严格的：yield一个ToolCall对象（含toolName与input），生成器 next 值中会拿到toolResult（ToolResultOutput[]）与stepsComplete标志。模板示例中还展示了includeToolCall选项（设为 false 时不把这次工具调用注入对话记录）。

六、模型选择策略

模板文档给出的选型建议（以模板 README 为准）：

任意 OpenRouter 模型：模板文档强调，与锁定 Anthropic 模型的同类工具不同，Codebuff/Freebuff 支持 OpenRouter 上任何可用模型——从 Claude、GPT 到 Qwen、DeepSeek 等专用模型。可以针对不同任务切换模型，或在新模型发布后立即使用，无需等待平台更新。具体模型清单与定价以 OpenRouter 模型市场为准；本仓库的 agent-definition.ts 中则固化了一批经过筛选的推荐模型枚举。

七、多 Agent 协调与派生机制

Agent 可以派生其他 Agent，从而构建复杂工作流。模板文档给出了并行派生的示例：

// 父 Agent 派生多个专家 async *handleSteps() { yield { tool: 'spawn_agents', agents: [ 'security-scanner', 'performance-analyzer', 'code-reviewer' ]} yield 'STEP_ALL' // 等待全部完成 // 汇总结果 yield 'STEP' }

几个关键机制：

• spawn_agents天然并行：spawn_agents同时派生的多个 Agent 会并行独立运行（源码注释明确说明）；需要串行时，一次只派生一个。
• 派生 ID 的两种写法：spawnableAgents中可使用完整限定 ID（publisher + 版本号，如codebuff/file-picker@0.0.1），引用 Agent 商店中的已发布 Agent；或使用.agents目录中的本地 Agent 短 ID（如file-picker）。
• 输入输出契约：通过inputSchema声明入参（prompt字符串或paramsJSON Schema），通过outputMode/outputSchema声明返回方式；set_output工具设置的值会原样回传给父 Agent，并在定义了outputSchema时校验。
• 复用已发布 Agent：模板文档鼓励直接组合现成的已发布 Agent 来加快开发——"Codebuff agents are the new MCP"。

仓库中的高级示例：Dora the File Explorer

examples/03-advanced-file-explorer.ts 是一个"结构化输入输出 + 并行派生"的综合示范：

inputSchema: { prompt: { description: 'What you need to accomplish by exploring the codebase', type: 'string' }, params: { type: 'object', properties: { prompts: { type: 'array', items: { type: 'string' } } }, required: ['prompts'], additionalProperties: false, }, }, outputMode: 'structured_output', outputSchema: { type: 'object', properties: { results: { type: 'string', description: 'The results of the file exploration' } }, required: ['results'], additionalProperties: false, }, handleSteps: function* ({ prompt, params }) { const prompts: string[] = params?.prompts ?? [] // 把每个探索方向映射为一次 file-picker 派生 const filePickerPrompts = prompts.map((focusPrompt) => `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`) const { toolResult: spawnResult } = yield { toolName: 'spawn_agents', input: { agents: filePickerPrompts.map((promptText) => ({ agent_type: 'codebuff/file-picker@0.0.1', prompt: promptText })) }, } yield { toolName: 'set_output', input: { results: spawnResult } } }

它并行派生多个codebuff/file-picker@0.0.1从不同角度探索代码库，再用set_output把聚合结果以结构化 JSON 输出——这是"协调型 Agent"的典型范式。

八、进阶模式：条件工作流与迭代精化

条件工作流

模板文档展示了根据上下文内容动态选择派生目标的模式：

async *handleSteps() { const config = yield { tool: 'read_files', paths: ['config.json'] } yield 'STEP' if (config.includes('typescript')) { yield { tool: 'spawn_agents', agents: ['typescript-expert'] } } else { yield { tool: 'spawn_agents', agents: ['javascript-expert'] } } yield 'STEP_ALL' }

迭代精化（测试-修复循环）

async *handleSteps() { for (let attempt = 0; attempt < 3; attempt++) { yield { tool: 'run_terminal_command', command: 'npm test' } yield 'STEP' if (allTestsPass) break yield { tool: 'spawn_agents', agents: ['test-fixer'] } yield 'STEP_ALL' } }

这种"跑测试 → AI 分析 → 派生修复 Agent → 重跑"的循环，是把 Agent 用于真实工程任务时的核心模式。

九、最佳实践

模板文档从四个维度给出了编写指南：

Instructions（指令编写）

• 明确 Agent 的角色与专长；
• 包含优质输出的示例；
• 说明何时应向用户请求澄清；
• 定义 Agent 的能力边界。

Tool Usage（工具使用）

• 从探索类工具开始（read_files、code_search）；
• 精确小改动用str_replace，大规模改动用write_file；
• 始终用end_turn干净地结束响应。

Error Handling（错误处理）

• 在程序化流程中加入错误检查；
• 为失败操作提供回退策略；
• 记录关键决策以便调试（可用logger）。

Performance（性能）

• 按任务复杂度选择合适的模型；
• 最小化不必要的工具调用；
• 用可派生 Agent 做并行处理。

十、测试与发布

测试流程（模板文档）：

1. 本地测试：运行codebuff（不带--agent）让本地.agents加载，然后从提示符中调用你的 Agent；
2. 调试模式：在handleSteps中添加日志；
3. 单元测试：隔离测试单个函数；
4. 集成测试：测试 Agent 协调工作流。

发布流程：

1. 验证：确保 Agent 在不同代码库上都能工作；
2. 文档化：提供清晰的使用说明；
3. 发布：codebuff publish your-agent-name；
4. 维护：随模型与工具演进持续更新。

十一、Skill 技能机制：为 Agent 提供可复用指令集

除 Agent 本身外，模板还包含 skills/README.md 与 skills/example-skill/SKILL.md，介绍 Skill 机制：

• 技能是按需加载的可复用指令集，通过skill工具触发；
• 创建方式：在.agents/skills/my-skill/下创建带 YAML frontmatter 的SKILL.md；
• frontmatter 字段：name（必填，1-64 字符，小写字母数字加连字符，必须与目录名一致）、description（必填，1-1024 字符，供 Agent 发现）、license（可选，如MIT）、disable-model-invocation（可选，设为 true 则不让模型自行发现）、metadata（可选键值对）；
• 名称校验规则：不以连字符开头/结尾、不含连续连字符（合法示例git-release、api-design；非法示例Git-Release、my--skill、-skill）；
• 发现优先级：~/.agents/skills/（全局，低优先级）→.agents/skills/（项目，高优先级），项目技能覆盖同名全局技能；
• Agent 看到skill工具描述中列出的可用技能，按需调用skill({ name: "my-skill" })，随后完整的 SKILL.md 内容进入对话上下文。

十二、源码级校验机制：Agent 如何被加载验证

编写 Agent 时理解其校验流程很有价值。仓库中的 agent-validation.ts 实现了validateSingleAgent的完整校验链路：

1. 先用 Zod schema（DynamicAgentDefinitionSchema）解析模板，校验字段合法性；
2. handleSteps会被序列化为字符串并校验必须是生成器函数（isValidGeneratorFunction要求以function*开头），同时保留活函数以通过运行时的 eval 往返；
3. inputSchema.prompt会被转成 Zod schema，并校验其必须允许 string 或 undefined 值；
4. outputSchema经convertJsonSchemaToZod转为 Zod 校验器；
5. 校验通过后转换为内部AgentTemplate格式，供运行时加载。

此外validateAgents会对多个模板做重复 ID 检测（同一 Agent ID 出现两次会报错），这解释了为什么id必须是唯一标识。这套机制意味着：写 Agent 时遵循类型定义，加载时还有一层 Schema 校验兜底，字段写错或handleSteps不是生成器都会得到明确的错误信息。

十三、仓库配套示例：从入门到进阶

examples/ 目录提供了三个难度递进的完整示例，是学习的最佳素材：

• 01-basic-diff-reviewer.ts：入门级"diff 审查者"。仅用read_files和run_terminal_command两个工具 +instructionsPrompt三步指令（git diff→ 读取变更文件 → 审查并建议），展示纯声明式的 Agent 写法——无需handleSteps，靠提示词驱动。
• 02-intermediate-git-committer.ts：中级"提交信息生成器"。通过handleSteps精确编排：先跑git diff与git log --oneline -10（各带 30 秒超时），再用add_message向对话注入引导文案（"put words in AI's mouth"技巧，用includeToolCall: false隐藏注入），配合'STEP'与'STEP_ALL'控制节奏，同时定义了inputSchema.prompt声明入参"要提交什么变更"。
• 03-advanced-file-explorer.ts：高级"并行文件探索器"，即第七节详解的结构化输入输出 + 并行派生示例，同时用到了includeMessageHistory: false、set_output、outputMode: 'structured_output'等进阶字段。

这三个示例恰好覆盖了自定义 Agent 的三层能力：提示词驱动 → 生成器编排 → 多 Agent 协调与结构化契约。

结语

自定义 Agent 是 Freebuff/Codebuff 开放性的核心体现：一个 Agent 就是一个导出了AgentDefinition的 TypeScript 文件，你可以用instructionsPrompt塑造角色、用toolNames划定能力边界、用handleSteps实现程序化编排、用spawn_agents构建专家团队、用inputSchema/outputSchema定义协作契约，最终通过codebuff publish分享给全世界。配套的 types/ 类型定义、examples/ 示例与 skills/ 技能机制，共同构成了从入门到生产可用的完整开发体系。现在，打开 my-custom-agent.ts，把它改成你需要的专家吧。

【免费下载链接】freebuffThe free coding agent项目地址: https://gitcode.com/GitHub_Trending/cod/freebuff