heterogeneous-agent

异构 Agent 开发

当问题或功能位于外部 CLI Agent 流程中，而非常规的服务端 Agent 运行时，请使用此技能。

适用场景

• 在 apps/desktop/src/main/modules/heterogeneousAgent/drivers/ 下添加或修改驱动
• 编辑 packages/heterogeneous-agents/src/adapters/ 下的适配器
• 修改 CLI/桌面端分发启动器，包括 OpenClaw/Hermes，或调试任务评论的作者身份
• 调试 heteroAgentRawLine 传输、window.__HETERO_AGENT_TRACE 或 executeHeterogeneousAgent
• 修复 Claude Code 的 stream-json 问题，例如部分/完整分块重复、message.id 边界错误、缺少 tool_result、TodoWrite 状态漂移或子 Agent 线程路由错误
• 修复 Codex JSONL 问题，例如多工具消息混杂、轮次边界错误或缺少工具结果映射
• 修复 Claude Code / Codex 流程中的步骤边界、工具持久化、子 Agent 线程或恢复问题
• 复现多工具混杂、孤立工具消息或工具结果加载卡住的问题

流程图

1. CLI 原始标准输出 / JSONL
2. Electron 主进程启动 CLI 并广播 heteroAgentRawLine
3. 适配器将原始提供方事件映射为 HeterogeneousAgentEvent
4. executeHeterogeneousAgent 持久化助手/工具消息并转发流事件
5. createGatewayEventHandler 为 UI 加载数据
6. 只有在此流程看起来正确后，才继续调试 agent-tracing 或上下文引擎

优先阅读这些文件

• apps/desktop/src/main/controllers/HeterogeneousAgentCtr.ts
• apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts
• apps/desktop/src/main/modules/heterogeneousAgent/drivers/codex.ts
• packages/heterogeneous-agents/src/adapters/claudeCode.ts
• packages/heterogeneous-agents/src/adapters/codex.ts
• src/store/chat/slices/agentRun/actions/transports/hetero/heterogeneousAgentExecutor.ts
• src/store/chat/slices/agentRun/actions/__tests__/heterogeneousAgentExecutor.test.ts

默认调试顺序

1. 修改 UI 代码前，先确认 CLI 原始输出是否正确。应用会记录每个真实会话——通过 cat .heerogeneous-tracing/.last-live-trace 读取最近一次会话，而不是手动编写 claude -p 复现（参见 references/debug-workflow.md §2）。
2. 如果原始输出正确，则将其与适配器输出进行比较。在开发环境中，executeHeterogeneousAgent 会提供 window.__HETERO_AGENT_TRACE。
3. 如果适配后的事件看起来正确，则检查 persistToolBatch、persistToolResult、步骤转换和子 Agent 路由。
4. 修复前，先将复现过程整理为针对性测试。
5. 只有在传输/适配器/执行器流程看起来正常后，才调试后续阶段的消息处理。

关键不变量

• 一个原始工具项必须映射到一个稳定的 ToolCallPayload.id。
• 新的主 Agent 步骤必须先发出边界信号，才能将事件转发给新的助手。
• 在 Claude Code 中，具有相同 message.id 的多个助手事件属于同一轮，而非多轮。
• 在 Claude Code 中，tool_result 位于 type: 'user' 事件中，而非助手事件中。
• 在 Claude Code 部分模式下，message_delta.usage 是权威数据；不要相信每个助手块中回显的用量。
• persistToolBatch 必须在创建工具消息前，预先注册助手的 tools[]。
• 每条工具消息的 parentId 必须保持为所属助手的 ID，tool_call_id 必须保持为工具 ID。
• tool_result 必须解析出已存在的 toolMsgIdByCallId。
• 子 Agent 分块必须保留在线程范围内，不得转发到主助手流。
• 绝不能在主步骤边界清空全局 toolMsgIdByCallId 映射。

分派运行身份

连接器或桌面进程本身可能运行在另一个 Agent 的对话中。它继承的环境标识的是启动者，而不是被分派的 Agent。

• 根据当前分派构建子进程身份。清除继承的 LOBEHUB_AGENT_ID、LOBEHUB_ASSISTANT_MESSAGE_ID、LOBEHUB_TASK_ID 和 LOBEHUB_WORKSPACE_ID；将 LOBEHUB_TOPIC_ID 和 LOBEHUB_OPERATION_ID 替换为分派提供的值。仅在当前分派提供可选上下文时才注入；缺失的值不得保留祖先身份。
• 将作者身份与身份验证分开处理。清除 LOBEHUB_JWT 或回退到用户凭据，不得改变执行中的 Agent。切勿根据主题所有者或任务受派人推断作者。
• 在 apps/cli/src/commands/task/lifecycle.ts 中，如果存在主题或操作上下文，但 Agent ID 缺失或为空，lh task comment 必须拒绝发布。没有执行身份的普通终端评论仍由用户撰写。否则，错误归属的 Agent 进度可能会在后续任务运行中成为人类 <user_feedback>。

修改此约定或添加启动器时，请检查以下四个启动入口：

界面	入口点
CLI Agent 分派	apps/cli/src/device/agentRun.ts — spawnHeteroAgentRun（Agent ID 由 apps/cli/src/commands/connect.ts 转发）
CLI OpenClaw/Hermes	apps/cli/src/tools/heteroTask.ts — runHeteroTask
桌面 Agent 分派	apps/desktop/src/main/controllers/HeterogeneousAgentImpl.ts — spawnLhHeteroExec
桌面 OpenClaw/Hermes	apps/desktop/src/main/controllers/GatewayConnectionCtr.ts — runHeteroTask

回归测试必须涵盖干净环境、冲突的祖先身份，以及缺失的当前 Agent/可选上下文。在 CLI 和桌面端均检查 OpenClaw 与 Hermes，并检查 JWT 回退后的任务评论。模拟的进程启动断言只能验证环境构造，不能验证经由外部运行时的端到端传递。

常见错误模式

• Claude Code 重复输出文本或思考内容： 检查是否同时发出了部分增量内容和后续完整的助手消息块。
• Claude Code 打开过多助手消息： 检查适配器是否在每个助手事件上都截断步骤，而不是只在 message.id 变化时截断。
• Claude Code 的工具结果始终未显示： 检查是否因为代码只检查助手事件，而忽略了 type: 'user' 的 tool_result 块。
• Claude Code 的 TodoWrite 卡片显示过时： 检查是否在工具结果产生时附加了合成的 pluginState.todos。
• Claude Code 的子 Agent 对话记录泄漏到主消息气泡中： 检查 parent_tool_use_id 的处理方式，以及是否将子 Agent 的内容块转发给了主网关处理程序。
• 多个 Codex 工具被合并到一条助手消息中： 首先检查适配器是否发出了可用的步骤边界信号，例如 newStep 或等效的轮次变更信号。
• 孤立的工具消息： 首先检查步骤转换顺序，以及工具消息创建前是否已运行 persistToolBatch 阶段 1。
• 工具气泡一直处于加载状态： 查找 tool_result for unknown toolCallId，以及是否缺少 result_msg_id 回填。
• 子 Agent 工具显示在主消息气泡中： 检查是否有子 Agent 的内容块到达主网关处理程序。
• 终端错误指南错误（例如，网络中断时显示“已达到使用上限”）： 分类器根据某个结构化字段进行分支判断，但该字段的存在本身并不代表对应含义。 在信任该字段前，先在真实跟踪记录的所有事件状态中搜索它——参见 references/debug-workflow.md §8（CC 的 rate_limit_info 也会出现在 status: "allowed" 中）。

参考资料

• 有关命令、跟踪记录捕获、不变量和专项测试命令，请阅读 references/debug-workflow.md。
• 仅当用户在 Claude Code 中显式调用 /testing-heterogeneous-agents，或在 Codex 中显式调用 $testing-heterogeneous-agents 时，才可进行实时官方模型兼容性检查。诊断期间不要自动加载或运行该 技能。其失败单元的证据可用于此处的诊断或代码修复。