在 AI 辅助开发走向工程化的过程中多 Agent 协作正变成一个越来越常见的落地形态。HStudio 作为一款支持多模型接入的 AI 协作工具可以把 OpenAI、DeepSeek、Claude 放在同一个群聊工作区里分别承担架构、编码、评审等不同角色。这种做法与单模型对话最大的区别是每个 Agent 有独立身份、独立上下文、独立任务边界系统不再要求一个模型同时扮演所有角色而是让多个模型像团队成员一样分工配合。下面以 HStudio 为例完整走一遍“三个 Agent 群聊”的搭建过程。核心目标是配置一个使用 Claude 的架构 Agent、一个使用 DeepSeek 的编码 Agent、一个使用 OpenAI 的评审 Agent然后让它们在同一个会话中完成一次从需求拆解到代码审查的协作。如果你正在研究多 Agent 编排、想了解不同模型如何组合使用或者准备把 AI 协作工具接入自己的开发流程这篇文章会提供一条可以照着操作的路径。1. 先想清楚多 Agent 群聊解决的是“角色混乱”问题1.1 多 Agent 不是多个模型轮流发言用一句通俗的话解释多 Agent 群聊是把不同模型、不同角色放进同一个会话里让它们像同事一样围绕同一个目标协作。从技术定义上看这是多智能体系统Multi-Agent SystemMAS的典型应用。多个具备独立目标、独立上下文和独立行为边界的智能体通过消息传递完成协作。在 HStudio 里每个 Agent 绑定一个模型提供方、一个系统提示词和一组任务边界。消息进入群聊后会根据用户的指定或编排规则路由到对应 Agent。为什么单模型对话不够用因为在一个超长对话里同一个模型既要理解需求又要写代码还要自我检查很容易出现“角色混淆”。尤其是需求反复修改时模型可能忘记自己当前应该站在用户视角、架构师视角还是评审视角。多 Agent 把这个问题从结构上解决每个 Agent 只维护自己职责范围内的上下文只回答自己该回答的问题。这里容易产生一个误解多 Agent 不是模型越多越好。如果两个 Agent 的职责边界不清晰会出现互相踢皮球、反复修改同一个文件、生成内容互相覆盖的情况。HStudio 这类工具的价值不在于“能挂多少个模型”而在于能否把角色边界、调用顺序和结果汇总机制约束清楚。1.2 OpenAI、DeepSeek、Claude 为什么适合组成一个团队在实际使用中这三家模型的能力各有侧重。下面表格是常见的分工方式不是官方排名具体表现需要结合任务类型测试。模型提供方通常优势适合承担的 Agent 角色接入方式OpenAI GPT 系列指令理解稳定、生态成熟、工具调用完善需求拆解、代码评审、最终结果汇总OpenAI APIOpenAI 兼容接口DeepSeek中文理解好、性价比高、代码生成能力强编码实现、脚本编写、代码重构DeepSeek API支持 OpenAI 兼容格式Anthropic Claude长上下文、复杂推理、代码分析细致架构设计、方案评审、风险识别Anthropic API需要独立请求格式这种组合的价值在于互补Claude 适合在前半段处理大量需求文本并输出方案DeepSeek 适合在后半段做高频、低成本的代码生成OpenAI 则适合作为“第三方”审查前面两个 Agent 的产出。群聊模式让这些能力差异不再需要人工复制粘贴而是通过消息流转自动接力。1.3 角色与任务必须先分离搭建多 Agent 群聊之前要把两个概念分开角色Role由系统提示词和模型能力共同决定回答“你是谁、能做什么、不能做什么”。任务Task由用户消息或编排流程指定回答“这次要产出什么”。如果只给 Agent 一个名字而不给职责边界群聊很快就会乱掉。下面是一个最小分工示例Agent角色定义常驻任务架构 Agent系统架构师输出技术方案、模块划分、接口设计编码 Agent实现工程师按方案实现代码、补充测试和运行命令评审 Agent质量评审负责人代码审查、安全风险、可维护性建议这个表格也可以作为你设计自己 Agent 团队时的模板。先写清楚“谁负责什么”再进入 HStudio 做配置后面的流程会顺畅很多。2. 环境准备三个 API Key 和 HStudio 安装2.1 注册三个平台并获取 API Key操作目标让 HStudio 能以你的账号身份调用三家模型服务。OpenAI 的 Key 在 platform.openai.com 的 API Keys 页面创建。登录后点击创建密钥复制后立即保存因为密钥只显示一次。DeepSeek 的 Key 在 platform.deepseek.com 创建调用时会用到deepseek-chat或deepseek-reasoner这类模型名。Claude 的 Key 在 console.anthropic.com 获取同时要记录当前账号可用的模型版本号。这里要提醒一点不同地区对服务可用性、付费方式的要求不同注册、充值和模型权限都要按官方页面引导完成不要使用非官方渠道也不要把自己的 Key 分享给他人。获取 Key 后建议先放到环境变量里export OPENAI_API_KEYsk-你自己的key export DEEPSEEK_API_KEYsk-你自己的key export ANTHROPIC_API_KEYsk-ant-你自己的key为什么用环境变量而不是写死在配置文件里因为 Key 一旦进入项目文件很容易泄露到 git 仓库、截图或日志里。环境变量属于进程级配置既方便切换又能被.gitignore之外的机制保护。2.2 安装 HStudio 并确认环境HStudio 的安装方式取决于你使用的平台安装完成后可以在终端或 IDE 插件里确认版本hstudio --version如果 HStudio 提供了环境检查命令也可以跑一次hstudio doctordoctor这类命令通常用来检查环境变量是否设置、网络通路是否正常、模型配置是否完整相当于多 Agent 工作区上线前的“环境体检”。如果检查项有红色警告先解决再进入下一步不要带着未知问题往下配置。2.3 先用 curl 验证三家 API 的通路在 HStudio 里报错时最难定位的是“是 Key 的问题还是配置的问题还是网络的问题”。为了避免混在一起建议先分别用 curl 验证三家服务。OpenAI 使用 chat/completions 接口curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENAI_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复ok}], max_tokens: 16 }DeepSeek 的接口格式兼容 OpenAIcurl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 回复ok}], max_tokens: 16 }Anthropic 的请求头和路径不同需要带版本头curl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 16, messages: [{role: user, content: 回复ok}] }这里有两个关键点。第一OpenAI 和 DeepSeek 都走 OpenAI 兼容的/chat/completions格式很多 HStudio 连接配置可以复用Anthropic 走独立的/v1/messages接口不能用同一个请求模板。第二上面三个模型名只是示例具体可用的模型版本要以各平台文档和账号权限为准。模型名写错是三家中最高频的报错之一。如果三条命令都能返回正常的 completion 内容说明 API Key、网络、计费配额都没有问题。后面在 HStudio 里再出现异常就可以把排查重点放到配置层。3. 在 HStudio 里创建三个 Agent3.1 Agent 配置的核心字段HStudio 中每个 Agent 的配置通常由几个核心字段组成。下面表格按常见配置结构列出具体字段名以你安装的版本为准。字段含义典型值name群聊中显示的 Agent 名称architect / coder / reviewerprovider模型提供方openai / deepseek / anthropicmodel具体模型名gpt-4o-mini / deepseek-chat / claude-xxxsystem_prompt角色系统提示词描述职责、输出格式、禁止事项temperature采样温度0.2 到 0.5max_tokens单次回复最大长度1000 到 8000active是否参与群聊true / false重点说两个字段。temperature控制输出的随机性架构方案、代码实现、代码审查都建议调低减少“每次都生成不同答案”的问题如果是头脑风暴类任务可以适当调高。system_prompt决定 Agent 的角色边界它比用户消息更稳定是所有协作规则的基础。3.2 架构 Agent用 Claude 承担方案设计架构 Agent 使用 Anthropic 的 Claude。示例配置如下agents: architect: name: 架构师 provider: anthropic model: claude-sonnet-4-20250514 temperature: 0.3 max_tokens: 4000 system_prompt: | 你是系统架构师负责在需求讨论中给出技术方案。 要求 1. 先拆解需求再给出模块划分、数据结构和接口设计。 2. 每个方案必须说明取舍不要只给结论。 3. 使用 Markdown 输出包含架构图和接口表。 边界你不负责写完整业务代码只负责方案和关键伪代码。选 Claude 做架构设计主要是看中它的长上下文和复杂推理能力。需求文档往往很长架构师需要先读完、再梳理、最后输出方案这对上下文窗口和推理稳定性要求都比较高。配置里的model名称一定要替换成你自己的账号当前可用的版本。3.3 编码 Agent用 DeepSeek 承担代码实现编码 Agent 使用 DeepSeek。示例配置如下coder: name: 实现工程师 provider: deepseek model: deepseek-chat temperature: 0.2 max_tokens: 6000 system_prompt: | 你是实现工程师负责把架构方案转成可运行代码。 要求 1. 默认输出 Python 代码包含必要的注释。 2. 先写函数签名和数据流再补实现。 3. 完成后给出测试用例和运行命令。 边界如果发现方案不合理说明原因并请架构师重新确认不要擅自改变接口设计。这段提示词里最重要的一句话是“不要擅自改变接口设计”。它让编码 Agent 在发现方案有问题时把问题抛回给架构 Agent而不是自己一边改方案一边写代码。这也是多 Agent 协作中避免上下文污染的典型写法。DeepSeek 的 API 默认指向官方接口。如果你在本地部署了 DeepSeek 模型或使用了自建的 OpenAI 兼容网关就需要在 HStudio 的连接配置里额外指定base_url。这一点在配置阶段就要确认否则后面的群聊请求会打到错误的地址。3.4 评审 Agent用 OpenAI 承担代码审查评审 Agent 使用 OpenAI。示例配置如下reviewer: name: 质量评审 provider: openai model: gpt-4o-mini temperature: 0.4 max_tokens: 3000 system_prompt: | 你是质量评审负责人负责审查架构师和实现工程师的产出。 要求 1. 检查需求遗漏、边界条件、异常处理和安全隐患。 2. 发现问题时给出优先级P0 必须修复P1 建议修复P2 可选优化。 3. 没有问题时明确回复“通过”不要含糊。 边界你做审查和修改建议不直接重写整个方案。让 OpenAI 承担评审的原因很简单让“写代码的人”和“查代码的人”分开。如果编码 Agent 自己检查自己很容易漏掉自己思维方式造成的盲区。第三方评审 Agent 即使用的是同一个体系下的模型也能通过不同的系统提示词形成不同视角。3.5 保存配置并确认 Agent 状态把三个 Agent 的配置保存到hstudio.yaml后在终端或界面里加载hstudio config apply hstudio.yaml hstudio agent list如果agent list能列出三个 Agent并且状态显示 ready说明配置文件已经被正确解析。这里要注意ready 只代表“配置结构正确”不代表“API Key 有效”。真正的验证必须进入一次实际会话让每个 Agent 真正调用一次模型。4. 创建群聊并编排一次完整协作4.1 发起群聊会话创建群聊的方式有两种命令行方式和图形界面方式。hstudio chat --group architect,coder,reviewer或者在 HStudio 界面里新建“群聊”会话勾选三个 Agent。群聊的关键特点是所有 Agent 都能看到消息流但只有被指定的 Agent 回复或者由编排规则决定谁先回复。如果所有 Agent 都监听所有消息会出现多人同时抢答的混乱场面。4.2 三种任务分发方式常用方式有三种直接指定消息开头写架构师明确指定某个 Agent 先处理。顺序编排在配置里定义turn_order按架构、编码、评审的顺序依次执行。自由讨论所有 Agent 监听对话只有职责匹配时响应。实际项目推荐前两种。自由讨论虽然看起来智能但会让每个 Agent 的上下文快速膨胀而且容易出现多个 Agent 同时回复、内容互相覆盖的情况。4.3 一次完整示例从需求拆解到代码审查假设现在要做一个“读取 CSV 文件并统计每列空值率输出 Markdown 报表”的小工具。完整的群聊流程如下。用户先指定架构师处理架构师 我们需要一个读取 CSV 文件的工具统计每列空值率输出 Markdown 报表。架构 Agent 回复模块划分、入参出参、异常处理建议。随后用户指定编码 Agent实现工程师 按架构师的方案实现。实现 Agent 输出代码、测试用例和运行命令。最后用户指定评审 Agent评审 审查上面的代码。评审 Agent 输出 P0/P1/P2 问题清单。这个流程就是多 Agent 群聊的最小闭环。每一步之间要检查产出是否符合预期再继续不要一次性把所有指令丢进去否则任何一个 Agent 的偏差都会被后面的 Agent 放大。4.4 人工协调者仍然不可少多 Agent 群聊不是“全自动无人值守”。人工在这里承担协调者角色主要做三件事判定任务是否完成、在 Agent 之间传递最终结论、在两个 Agent 出现冲突时做决策。编排配置里可以加上保护机制group_chat: agents: [architect, coder, reviewer] max_rounds: 3 default_target: architect on_conflict: notify_humanmax_rounds限制总轮数防止架构 Agent 和评审 Agent 因为意见不一致无限循环讨论。on_conflict表示冲突时通知人工而不是让模型自己争论下去。这两项配置是生产使用中非常重要的“刹车”。5. 运行验证从结果到日志5.1 用表格定义验证标准群聊跑通后不要只看“能回复”就结束。建议按下面标准逐项验证检查项预期结果群聊创建成功三个 Agent 都在成员列表中指定 回复只有目标 Agent 回复其他 Agent 不抢答架构方案输出包含模块划分、接口设计、取舍说明代码输出可以直接执行缺少依赖时给出安装命令评审输出有清晰的 P0/P1/P2 分级结论多轮上下文长对话后每个 Agent 仍然保持自己的角色设定如果某个检查项失败比如评审 Agent 开始输出代码而不是审查结论优先检查它的system_prompt是否被后续用户消息覆盖或者是否因为上下文过长导致角色记忆被稀释。5.2 从日志看调用链路HStudio 通常支持调试日志。运行命令时加上调试级别hstudio chat --group architect,coder,reviewer --log-level debug在日志里应该能看到类似下面的调用记录[request] providerdeepseek modeldeepseek-chat agentcoder [response] providerdeepseek modeldeepseek-chat tokens_in1200 tokens_out860检查点有两个。第一每条请求都有明确的provider和agent说明路由正确第二如果所有请求都指向同一个 provider说明其他 Agent 的配置没有生效要回头检查配置文件的provider字段和模型名。5.3 控制多轮对话的上下文群聊进行到十几轮之后每个 Agent 都会积累大量上下文可能出现三种问题上下文超长导致报错、模型开始遗忘早期指令、token 成本快速上涨。控制方式有三种。一是给每个 Agent 设置合理max_tokens避免单次回复过长。二是让评审 Agent 在每轮结束时生成一份“结论摘要”把原始讨论从上下文里清理掉。三是把大任务拆成多个会话不要在同一个会话里无限追加需求。6. 常见问题排查6.1 API Key 相关的 401 错误错误现象常见原因检查方式处理建议Invalid API keyKey 写错、复制时多出空格、环境变量未生效打印环境变量确认前后端一致重新复制 Key重启终端或 HStudio 会话账号无法访问该模型未开通该模型的权限登录平台后台查看权限按平台流程申请或换用可用模型服务在当前地区不可用区域限制查看官方状态页按官方说明处理不使用非官方渠道排查顺序建议是先确认环境变量确实存在再确认 Key 没有空格然后用第一节的 curl 命令逐家测试。API 层能通问题就在 HStudio 的配置层。6.2 模型名导致的 Model not found如果你在配置里填了不存在的模型名平台通常会返回 Model not found 或 404。常见原因有两个模型版本号已经更新或者当前账号没有该模型权限。检查方式很简单调用平台的模型列表接口。OpenAI 和 DeepSeek 都支持curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY curl https://api.deepseek.com/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY把返回列表里的名称和配置里的model字段比对不一致就改成列表中的准确名称。6.3 Claude 相关的两类典型报错第一类是平台侧提示 “Claude is not available to new users right now”。这属于 Anthropic 对新账号的限制和 HStudio 无关只能等待账号权限开放或者暂时改用当前可用的模型。第二类是在安装 Claude 相关本地能力时出现 “claude native binary not installed. either postinstall did not run” 这类错误。这通常是本地 CLI 安装不完整或postinstall脚本没有跑完重新安装一次依赖即可。需要区分的是这类错误属于 Claude Code 的本地组件问题和通过 API 接入 HStudio 是两条不同的路径。6.4 429 限流和上下文超长错误现象常见原因处理建议429 Rate limit并发请求过多或超出免费额度降低群聊并发加入退避重试机制Context length exceeded单个 Agent 上下文累积过长缩短会话轮数执行摘要后开新会话timeout 超时网络波动或模型响应过慢检查网络增大超时时间降低 max_tokens6.5 Agent 之间互相覆盖比较隐蔽的问题是编码 Agent 改了架构方案评审 Agent 又改回去两个 Agent 在群里反复争论。根因是角色边界不清晰。解决方式是在每个 Agent 的system_prompt里写清楚“你只负责什么、不负责什么”同时设置max_rounds限制争论轮数最终合并由人工完成。多 Agent 群聊不是让模型自己协商到完全一致而是让它们各自输出专业意见再由人做决策。7. 从群聊跑通到生产可用最佳实践与扩展方向7.1 上线前的检查清单下面是一份可以直接使用的多 Agent 群聊上线前检查清单三个平台的 API Key 是否都通过独立 curl 验证而不是只在 HStudio 里验证过一次。配置文件是否包含真实密钥密钥是否已用环境变量替换配置文件是否加入.gitignore。每个 Agent 的system_prompt是否写清楚“不做什么”而不是只写“做什么”。是否设置了max_rounds避免 Agent 无限争论。是否开启 debug 日志并确认请求的provider与agent一一对应。群聊结果是否需要汇总存档由哪个 Agent 负责输出最终结论。输入给模型的数据是否包含敏感信息是否做了脱敏处理。7.2 角色提示词设计的三条建议第一负面约束比正面要求更重要。只说“你负责写代码”约束力远不如“你不负责修改接口设计发现问题时返回给架构师”。第二输出格式固定让下游 Agent 和人工都能快速解析。第三不要在生产环境的system_prompt里写临时需求临时需求应该通过用户消息传入否则角色配置会越来越臃肿。7.3 可以继续扩展的方向群聊模式跑通后可以在三个方向继续深入。一是接入更多模型服务比如本地部署的 DeepSeek或者自建的 OpenAI 兼容网关进一步控制成本和数据边界。二是给每个 Agent 挂载工具能力例如文件读取、git 操作、数据库查询让 Agent 从“只能聊天”变成“能操作工程环境”。三是把群聊会话改造成流水线任务把人工协调的每一步固化成自动触发规则。多 Agent 群聊能不能真正用于生产不取决于模型本身多强而取决于角色边界是否清晰、编排规则是否可控、人工把关是否到位。先用最小配置把一条需求链路跑通再逐步增加 Agent 和工具是性价比最高的验证方式。
在 AI 辅助开发走向工程化的过程中多 Agent 协作正变成一个越来越常见的落地形态。HStudio 作为一款支持多模型接入的 AI 协作工具可以把 OpenAI、DeepSeek、Claude 放在同一个群聊工作区里分别承担架构、编码、评审等不同角色。这种做法与单模型对话最大的区别是每个 Agent 有独立身份、独立上下文、独立任务边界系统不再要求一个模型同时扮演所有角色而是让多个模型像团队成员一样分工配合。下面以 HStudio 为例完整走一遍“三个 Agent 群聊”的搭建过程。核心目标是配置一个使用 Claude 的架构 Agent、一个使用 DeepSeek 的编码 Agent、一个使用 OpenAI 的评审 Agent然后让它们在同一个会话中完成一次从需求拆解到代码审查的协作。如果你正在研究多 Agent 编排、想了解不同模型如何组合使用或者准备把 AI 协作工具接入自己的开发流程这篇文章会提供一条可以照着操作的路径。1. 先想清楚多 Agent 群聊解决的是“角色混乱”问题1.1 多 Agent 不是多个模型轮流发言用一句通俗的话解释多 Agent 群聊是把不同模型、不同角色放进同一个会话里让它们像同事一样围绕同一个目标协作。从技术定义上看这是多智能体系统Multi-Agent SystemMAS的典型应用。多个具备独立目标、独立上下文和独立行为边界的智能体通过消息传递完成协作。在 HStudio 里每个 Agent 绑定一个模型提供方、一个系统提示词和一组任务边界。消息进入群聊后会根据用户的指定或编排规则路由到对应 Agent。为什么单模型对话不够用因为在一个超长对话里同一个模型既要理解需求又要写代码还要自我检查很容易出现“角色混淆”。尤其是需求反复修改时模型可能忘记自己当前应该站在用户视角、架构师视角还是评审视角。多 Agent 把这个问题从结构上解决每个 Agent 只维护自己职责范围内的上下文只回答自己该回答的问题。这里容易产生一个误解多 Agent 不是模型越多越好。如果两个 Agent 的职责边界不清晰会出现互相踢皮球、反复修改同一个文件、生成内容互相覆盖的情况。HStudio 这类工具的价值不在于“能挂多少个模型”而在于能否把角色边界、调用顺序和结果汇总机制约束清楚。1.2 OpenAI、DeepSeek、Claude 为什么适合组成一个团队在实际使用中这三家模型的能力各有侧重。下面表格是常见的分工方式不是官方排名具体表现需要结合任务类型测试。模型提供方通常优势适合承担的 Agent 角色接入方式OpenAI GPT 系列指令理解稳定、生态成熟、工具调用完善需求拆解、代码评审、最终结果汇总OpenAI APIOpenAI 兼容接口DeepSeek中文理解好、性价比高、代码生成能力强编码实现、脚本编写、代码重构DeepSeek API支持 OpenAI 兼容格式Anthropic Claude长上下文、复杂推理、代码分析细致架构设计、方案评审、风险识别Anthropic API需要独立请求格式这种组合的价值在于互补Claude 适合在前半段处理大量需求文本并输出方案DeepSeek 适合在后半段做高频、低成本的代码生成OpenAI 则适合作为“第三方”审查前面两个 Agent 的产出。群聊模式让这些能力差异不再需要人工复制粘贴而是通过消息流转自动接力。1.3 角色与任务必须先分离搭建多 Agent 群聊之前要把两个概念分开角色Role由系统提示词和模型能力共同决定回答“你是谁、能做什么、不能做什么”。任务Task由用户消息或编排流程指定回答“这次要产出什么”。如果只给 Agent 一个名字而不给职责边界群聊很快就会乱掉。下面是一个最小分工示例Agent角色定义常驻任务架构 Agent系统架构师输出技术方案、模块划分、接口设计编码 Agent实现工程师按方案实现代码、补充测试和运行命令评审 Agent质量评审负责人代码审查、安全风险、可维护性建议这个表格也可以作为你设计自己 Agent 团队时的模板。先写清楚“谁负责什么”再进入 HStudio 做配置后面的流程会顺畅很多。2. 环境准备三个 API Key 和 HStudio 安装2.1 注册三个平台并获取 API Key操作目标让 HStudio 能以你的账号身份调用三家模型服务。OpenAI 的 Key 在 platform.openai.com 的 API Keys 页面创建。登录后点击创建密钥复制后立即保存因为密钥只显示一次。DeepSeek 的 Key 在 platform.deepseek.com 创建调用时会用到deepseek-chat或deepseek-reasoner这类模型名。Claude 的 Key 在 console.anthropic.com 获取同时要记录当前账号可用的模型版本号。这里要提醒一点不同地区对服务可用性、付费方式的要求不同注册、充值和模型权限都要按官方页面引导完成不要使用非官方渠道也不要把自己的 Key 分享给他人。获取 Key 后建议先放到环境变量里export OPENAI_API_KEYsk-你自己的key export DEEPSEEK_API_KEYsk-你自己的key export ANTHROPIC_API_KEYsk-ant-你自己的key为什么用环境变量而不是写死在配置文件里因为 Key 一旦进入项目文件很容易泄露到 git 仓库、截图或日志里。环境变量属于进程级配置既方便切换又能被.gitignore之外的机制保护。2.2 安装 HStudio 并确认环境HStudio 的安装方式取决于你使用的平台安装完成后可以在终端或 IDE 插件里确认版本hstudio --version如果 HStudio 提供了环境检查命令也可以跑一次hstudio doctordoctor这类命令通常用来检查环境变量是否设置、网络通路是否正常、模型配置是否完整相当于多 Agent 工作区上线前的“环境体检”。如果检查项有红色警告先解决再进入下一步不要带着未知问题往下配置。2.3 先用 curl 验证三家 API 的通路在 HStudio 里报错时最难定位的是“是 Key 的问题还是配置的问题还是网络的问题”。为了避免混在一起建议先分别用 curl 验证三家服务。OpenAI 使用 chat/completions 接口curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENAI_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复ok}], max_tokens: 16 }DeepSeek 的接口格式兼容 OpenAIcurl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 回复ok}], max_tokens: 16 }Anthropic 的请求头和路径不同需要带版本头curl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 16, messages: [{role: user, content: 回复ok}] }这里有两个关键点。第一OpenAI 和 DeepSeek 都走 OpenAI 兼容的/chat/completions格式很多 HStudio 连接配置可以复用Anthropic 走独立的/v1/messages接口不能用同一个请求模板。第二上面三个模型名只是示例具体可用的模型版本要以各平台文档和账号权限为准。模型名写错是三家中最高频的报错之一。如果三条命令都能返回正常的 completion 内容说明 API Key、网络、计费配额都没有问题。后面在 HStudio 里再出现异常就可以把排查重点放到配置层。3. 在 HStudio 里创建三个 Agent3.1 Agent 配置的核心字段HStudio 中每个 Agent 的配置通常由几个核心字段组成。下面表格按常见配置结构列出具体字段名以你安装的版本为准。字段含义典型值name群聊中显示的 Agent 名称architect / coder / reviewerprovider模型提供方openai / deepseek / anthropicmodel具体模型名gpt-4o-mini / deepseek-chat / claude-xxxsystem_prompt角色系统提示词描述职责、输出格式、禁止事项temperature采样温度0.2 到 0.5max_tokens单次回复最大长度1000 到 8000active是否参与群聊true / false重点说两个字段。temperature控制输出的随机性架构方案、代码实现、代码审查都建议调低减少“每次都生成不同答案”的问题如果是头脑风暴类任务可以适当调高。system_prompt决定 Agent 的角色边界它比用户消息更稳定是所有协作规则的基础。3.2 架构 Agent用 Claude 承担方案设计架构 Agent 使用 Anthropic 的 Claude。示例配置如下agents: architect: name: 架构师 provider: anthropic model: claude-sonnet-4-20250514 temperature: 0.3 max_tokens: 4000 system_prompt: | 你是系统架构师负责在需求讨论中给出技术方案。 要求 1. 先拆解需求再给出模块划分、数据结构和接口设计。 2. 每个方案必须说明取舍不要只给结论。 3. 使用 Markdown 输出包含架构图和接口表。 边界你不负责写完整业务代码只负责方案和关键伪代码。选 Claude 做架构设计主要是看中它的长上下文和复杂推理能力。需求文档往往很长架构师需要先读完、再梳理、最后输出方案这对上下文窗口和推理稳定性要求都比较高。配置里的model名称一定要替换成你自己的账号当前可用的版本。3.3 编码 Agent用 DeepSeek 承担代码实现编码 Agent 使用 DeepSeek。示例配置如下coder: name: 实现工程师 provider: deepseek model: deepseek-chat temperature: 0.2 max_tokens: 6000 system_prompt: | 你是实现工程师负责把架构方案转成可运行代码。 要求 1. 默认输出 Python 代码包含必要的注释。 2. 先写函数签名和数据流再补实现。 3. 完成后给出测试用例和运行命令。 边界如果发现方案不合理说明原因并请架构师重新确认不要擅自改变接口设计。这段提示词里最重要的一句话是“不要擅自改变接口设计”。它让编码 Agent 在发现方案有问题时把问题抛回给架构 Agent而不是自己一边改方案一边写代码。这也是多 Agent 协作中避免上下文污染的典型写法。DeepSeek 的 API 默认指向官方接口。如果你在本地部署了 DeepSeek 模型或使用了自建的 OpenAI 兼容网关就需要在 HStudio 的连接配置里额外指定base_url。这一点在配置阶段就要确认否则后面的群聊请求会打到错误的地址。3.4 评审 Agent用 OpenAI 承担代码审查评审 Agent 使用 OpenAI。示例配置如下reviewer: name: 质量评审 provider: openai model: gpt-4o-mini temperature: 0.4 max_tokens: 3000 system_prompt: | 你是质量评审负责人负责审查架构师和实现工程师的产出。 要求 1. 检查需求遗漏、边界条件、异常处理和安全隐患。 2. 发现问题时给出优先级P0 必须修复P1 建议修复P2 可选优化。 3. 没有问题时明确回复“通过”不要含糊。 边界你做审查和修改建议不直接重写整个方案。让 OpenAI 承担评审的原因很简单让“写代码的人”和“查代码的人”分开。如果编码 Agent 自己检查自己很容易漏掉自己思维方式造成的盲区。第三方评审 Agent 即使用的是同一个体系下的模型也能通过不同的系统提示词形成不同视角。3.5 保存配置并确认 Agent 状态把三个 Agent 的配置保存到hstudio.yaml后在终端或界面里加载hstudio config apply hstudio.yaml hstudio agent list如果agent list能列出三个 Agent并且状态显示 ready说明配置文件已经被正确解析。这里要注意ready 只代表“配置结构正确”不代表“API Key 有效”。真正的验证必须进入一次实际会话让每个 Agent 真正调用一次模型。4. 创建群聊并编排一次完整协作4.1 发起群聊会话创建群聊的方式有两种命令行方式和图形界面方式。hstudio chat --group architect,coder,reviewer或者在 HStudio 界面里新建“群聊”会话勾选三个 Agent。群聊的关键特点是所有 Agent 都能看到消息流但只有被指定的 Agent 回复或者由编排规则决定谁先回复。如果所有 Agent 都监听所有消息会出现多人同时抢答的混乱场面。4.2 三种任务分发方式常用方式有三种直接指定消息开头写架构师明确指定某个 Agent 先处理。顺序编排在配置里定义turn_order按架构、编码、评审的顺序依次执行。自由讨论所有 Agent 监听对话只有职责匹配时响应。实际项目推荐前两种。自由讨论虽然看起来智能但会让每个 Agent 的上下文快速膨胀而且容易出现多个 Agent 同时回复、内容互相覆盖的情况。4.3 一次完整示例从需求拆解到代码审查假设现在要做一个“读取 CSV 文件并统计每列空值率输出 Markdown 报表”的小工具。完整的群聊流程如下。用户先指定架构师处理架构师 我们需要一个读取 CSV 文件的工具统计每列空值率输出 Markdown 报表。架构 Agent 回复模块划分、入参出参、异常处理建议。随后用户指定编码 Agent实现工程师 按架构师的方案实现。实现 Agent 输出代码、测试用例和运行命令。最后用户指定评审 Agent评审 审查上面的代码。评审 Agent 输出 P0/P1/P2 问题清单。这个流程就是多 Agent 群聊的最小闭环。每一步之间要检查产出是否符合预期再继续不要一次性把所有指令丢进去否则任何一个 Agent 的偏差都会被后面的 Agent 放大。4.4 人工协调者仍然不可少多 Agent 群聊不是“全自动无人值守”。人工在这里承担协调者角色主要做三件事判定任务是否完成、在 Agent 之间传递最终结论、在两个 Agent 出现冲突时做决策。编排配置里可以加上保护机制group_chat: agents: [architect, coder, reviewer] max_rounds: 3 default_target: architect on_conflict: notify_humanmax_rounds限制总轮数防止架构 Agent 和评审 Agent 因为意见不一致无限循环讨论。on_conflict表示冲突时通知人工而不是让模型自己争论下去。这两项配置是生产使用中非常重要的“刹车”。5. 运行验证从结果到日志5.1 用表格定义验证标准群聊跑通后不要只看“能回复”就结束。建议按下面标准逐项验证检查项预期结果群聊创建成功三个 Agent 都在成员列表中指定 回复只有目标 Agent 回复其他 Agent 不抢答架构方案输出包含模块划分、接口设计、取舍说明代码输出可以直接执行缺少依赖时给出安装命令评审输出有清晰的 P0/P1/P2 分级结论多轮上下文长对话后每个 Agent 仍然保持自己的角色设定如果某个检查项失败比如评审 Agent 开始输出代码而不是审查结论优先检查它的system_prompt是否被后续用户消息覆盖或者是否因为上下文过长导致角色记忆被稀释。5.2 从日志看调用链路HStudio 通常支持调试日志。运行命令时加上调试级别hstudio chat --group architect,coder,reviewer --log-level debug在日志里应该能看到类似下面的调用记录[request] providerdeepseek modeldeepseek-chat agentcoder [response] providerdeepseek modeldeepseek-chat tokens_in1200 tokens_out860检查点有两个。第一每条请求都有明确的provider和agent说明路由正确第二如果所有请求都指向同一个 provider说明其他 Agent 的配置没有生效要回头检查配置文件的provider字段和模型名。5.3 控制多轮对话的上下文群聊进行到十几轮之后每个 Agent 都会积累大量上下文可能出现三种问题上下文超长导致报错、模型开始遗忘早期指令、token 成本快速上涨。控制方式有三种。一是给每个 Agent 设置合理max_tokens避免单次回复过长。二是让评审 Agent 在每轮结束时生成一份“结论摘要”把原始讨论从上下文里清理掉。三是把大任务拆成多个会话不要在同一个会话里无限追加需求。6. 常见问题排查6.1 API Key 相关的 401 错误错误现象常见原因检查方式处理建议Invalid API keyKey 写错、复制时多出空格、环境变量未生效打印环境变量确认前后端一致重新复制 Key重启终端或 HStudio 会话账号无法访问该模型未开通该模型的权限登录平台后台查看权限按平台流程申请或换用可用模型服务在当前地区不可用区域限制查看官方状态页按官方说明处理不使用非官方渠道排查顺序建议是先确认环境变量确实存在再确认 Key 没有空格然后用第一节的 curl 命令逐家测试。API 层能通问题就在 HStudio 的配置层。6.2 模型名导致的 Model not found如果你在配置里填了不存在的模型名平台通常会返回 Model not found 或 404。常见原因有两个模型版本号已经更新或者当前账号没有该模型权限。检查方式很简单调用平台的模型列表接口。OpenAI 和 DeepSeek 都支持curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY curl https://api.deepseek.com/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY把返回列表里的名称和配置里的model字段比对不一致就改成列表中的准确名称。6.3 Claude 相关的两类典型报错第一类是平台侧提示 “Claude is not available to new users right now”。这属于 Anthropic 对新账号的限制和 HStudio 无关只能等待账号权限开放或者暂时改用当前可用的模型。第二类是在安装 Claude 相关本地能力时出现 “claude native binary not installed. either postinstall did not run” 这类错误。这通常是本地 CLI 安装不完整或postinstall脚本没有跑完重新安装一次依赖即可。需要区分的是这类错误属于 Claude Code 的本地组件问题和通过 API 接入 HStudio 是两条不同的路径。6.4 429 限流和上下文超长错误现象常见原因处理建议429 Rate limit并发请求过多或超出免费额度降低群聊并发加入退避重试机制Context length exceeded单个 Agent 上下文累积过长缩短会话轮数执行摘要后开新会话timeout 超时网络波动或模型响应过慢检查网络增大超时时间降低 max_tokens6.5 Agent 之间互相覆盖比较隐蔽的问题是编码 Agent 改了架构方案评审 Agent 又改回去两个 Agent 在群里反复争论。根因是角色边界不清晰。解决方式是在每个 Agent 的system_prompt里写清楚“你只负责什么、不负责什么”同时设置max_rounds限制争论轮数最终合并由人工完成。多 Agent 群聊不是让模型自己协商到完全一致而是让它们各自输出专业意见再由人做决策。7. 从群聊跑通到生产可用最佳实践与扩展方向7.1 上线前的检查清单下面是一份可以直接使用的多 Agent 群聊上线前检查清单三个平台的 API Key 是否都通过独立 curl 验证而不是只在 HStudio 里验证过一次。配置文件是否包含真实密钥密钥是否已用环境变量替换配置文件是否加入.gitignore。每个 Agent 的system_prompt是否写清楚“不做什么”而不是只写“做什么”。是否设置了max_rounds避免 Agent 无限争论。是否开启 debug 日志并确认请求的provider与agent一一对应。群聊结果是否需要汇总存档由哪个 Agent 负责输出最终结论。输入给模型的数据是否包含敏感信息是否做了脱敏处理。7.2 角色提示词设计的三条建议第一负面约束比正面要求更重要。只说“你负责写代码”约束力远不如“你不负责修改接口设计发现问题时返回给架构师”。第二输出格式固定让下游 Agent 和人工都能快速解析。第三不要在生产环境的system_prompt里写临时需求临时需求应该通过用户消息传入否则角色配置会越来越臃肿。7.3 可以继续扩展的方向群聊模式跑通后可以在三个方向继续深入。一是接入更多模型服务比如本地部署的 DeepSeek或者自建的 OpenAI 兼容网关进一步控制成本和数据边界。二是给每个 Agent 挂载工具能力例如文件读取、git 操作、数据库查询让 Agent 从“只能聊天”变成“能操作工程环境”。三是把群聊会话改造成流水线任务把人工协调的每一步固化成自动触发规则。多 Agent 群聊能不能真正用于生产不取决于模型本身多强而取决于角色边界是否清晰、编排规则是否可控、人工把关是否到位。先用最小配置把一条需求链路跑通再逐步增加 Agent 和工具是性价比最高的验证方式。
算法精解与面试技巧)
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
