1. 从 Oh-My-OpenCode 到 Claude Code一场被低估的 Agent 协同范式迁移最近在几个开发者小圈子看到有人提“OmO skills”一开始以为是某个新出的 CLI 工具缩写点进去才发现是圈内人对一个实操项目的戏称——把原本基于Oh-My-OpenCode简称 OMO构建的多 Agent 协同工作流完整、可复用、低侵入地迁移到Claude Code环境中运行。这不是简单换个 API Key 的事而是一次对底层协同逻辑、状态管理机制和工具调用契约的系统性重适配。我花三周时间把整个迁移过程跑通了两轮第一轮照着社区零散笔记硬怼卡在 Sisyphus 模块模型切换失败上整整四天第二轮从 OMO 的agent_router.py和tool_registry.py反向推导出它的协同协议设计哲学再对照 Claude Code 的ToolUseBlock和MessageStream行为边界重新建模才真正稳住。现在这套方案已在我们团队两个真实项目中落地一个是自动化技术文档生成流水线含代码解析→架构图生成→PR 描述润色三 Agent 协同另一个是跨仓库依赖影响分析扫描推理风险评级三角色闭环。它解决的核心问题很朴素让多个专业 Agent 在不共享内存、不预设通信拓扑的前提下仅靠消息流与工具调用契约就能完成需要多视角判断的复杂任务——这恰恰是当前多数“多 Agent 框架”宣传时说得热闹、落地时频频掉链子的痛点。关键词里虽然没填但实际贯穿全程的是三个隐性支柱SisyphusOMO 的核心调度器、Tool Use ProtocolClaude Code 的结构化工具调用规范、以及 OpenCode 配置体系YAML 驱动的 Agent 能力注册机制。很多人卡住不是因为不会写 prompt而是没意识到 OMO 的sisyphus.yaml不是配置文件而是一份运行时协同契约的声明式描述同样Claude Code 的tools字段也不是功能列表而是Agent 间可信赖协作的接口契约集合。接下来我会拆解这个迁移过程中最反直觉、也最关键的四个断层Sisyphus 的状态抽象如何映射到无状态流式响应、OMO 的 YAML 配置如何转化为 Claude Code 的 runtime tool schema、多 Agent 间的隐式上下文传递为何必须显式化、以及为什么你不能直接复用 OMO 的agent_router逻辑。2. Sisyphus 调度器的“状态幻觉”与 Claude Code 的流式现实Sisyphus 是 Oh-My-OpenCode 的灵魂组件但它的名字容易让人误解——它并非一个持久化状态服务而是一个基于 YAML 声明的协同流程编排器。当你在sisyphus.yaml里写agents: - name: code_analyzer model: claude-3-haiku-20240307 tools: [parse_ast, extract_dependencies] - name: arch_diagram_generator model: claude-3-sonnet-20240229 tools: [generate_mermaid, validate_layout]你其实在定义一个静态的协同拓扑哪些 Agent 参与、各自能力边界在哪、谁调用谁的工具。Sisyphus 的“调度”本质是当用户输入触发code_analyzer后它若调用parse_ast工具并返回 AST 结构Sisyphus 就自动将该结构作为上下文注入arch_diagram_generator的下一轮请求中。这个过程看起来像有状态流转实则所有状态都由 OMO 的 Python 运行时在内存中临时拼接完成——它依赖的是单次 HTTP 请求生命周期内的上下文堆栈。Claude Code 完全不提供这种“堆栈”。它的MessageStream是纯流式输出每次messages.create()调用都是独立的、无状态的 RPC。你无法假设前一次调用的tool_result会自动出现在下一次的system或messages中。这就是第一个断层Sisyphus 的“状态幻觉”必须被拆解为显式的、带版本控制的消息契约。我试过三种方案方案一用system字段硬塞上下文把code_analyzer的 AST 输出 JSON 字符串拼进下一轮arch_diagram_generator的system提示词里。结果Claude 模型对长 system 提示词敏感超过 2000 token 时生成质量断崖下跌且无法保证字段名一致性比如ast_tree有时变成parsed_ast。方案二用metadata传结构化数据Claude Code 的metadata字段只支持字符串键值对无法嵌套 JSON。尝试json.dumps(ast_data)后存入metadata[context]但arch_diagram_generator收到后需手动json.loads()且 metadata 有 1KB 大小限制大 AST 直接截断。方案三引入轻量级上下文存储最终采用在本地启动一个极简的内存数据库我用diskcache.Cache()比 Redis 轻无网络开销为每次协同会话生成唯一session_id。code_analyzer执行完parse_ast后将 AST 存入cache[f{session_id}_ast]arch_diagram_generator启动时先查cache.get(f{session_id}_ast)存在则注入messages不存在则报错退出。关键点在于这个session_id必须由前端或 CLI 全局生成并透传给每个 Agent而非由 Sisyphus 动态分配——因为 Claude Code 没有“会话生命周期”的概念只有你主动维护的 ID。提示不要试图用thread_id替代session_id。Claude 的thread_id是用于 UI 层消息分组的后端不保证其全局唯一性且无法在不同messages.create()调用间稳定传递。实测中thread_id在重试时会变更导致上下文丢失。这个方案看似增加了组件实则更健壮。它把“状态管理”从模型提示词中剥离交还给确定性更强的程序逻辑。Sisyphus 的 YAML 配置此时只负责声明“谁需要什么上下文”而具体存取逻辑由运行时环境实现。我在omo_claude_adapter.py里封装了ContextManager类统一处理get/set/clear所有 Agent 只需调用ctx.get(ast)即可完全屏蔽底层细节。3. OMO 的 YAML 配置体系与 Claude Code 的 Tool Schema 映射Oh-My-OpenCode 的配置魅力在于“所见即所得”你在sisyphus.yaml里写的tools: [parse_ast, extract_dependencies]对应 Python 代码里tool装饰的函数。这种声明式配置极大降低了多 Agent 协同的入门门槛但迁移到 Claude Code 时你会发现 YAML 里的tools字段和 Claude 的tools参数根本不是一回事。OMO 的tools是运行时可调用的 Python 函数集合函数签名决定参数校验函数体决定执行逻辑。而 Claude Code 的tools是一个JSON Schema 数组它只描述“这个工具能做什么”不包含“怎么做”。例如 OMO 的parse_ast函数tool def parse_ast(code: str, language: str python) - dict: Parse source code into AST structure # 实际解析逻辑 return {nodes: [...], language: language}在 Claude Code 中你必须将其转化为{ name: parse_ast, description: Parse source code into AST structure, input_schema: { type: object, properties: { code: {type: string, description: Source code to parse}, language: {type: string, description: Programming language, default: python} }, required: [code] } }这个转换过程藏着三个坑3.1 参数类型映射的陷阱OMO 的language: str python在 YAML 配置里是language: python但 Claude 的input_schema要求default字段必须是 JSON 原生类型。如果 OMO 配置里写language: python带引号Python 解析后是字符串python没问题但如果写language: python不带引号YAML 解析器会当成布尔值True我第一次迁移时就因这个细节导致parse_ast的language参数始终是TrueAST 解析器直接崩溃。解决方案在omo_config_parser.py中增加类型校验。对每个tool的input_schema遍历properties若default存在且类型非str/int/float/bool则抛出ConfigValidationError并提示“YAML 中 default 值必须加引号”。3.2 工具调用结果的结构化约束OMO 的parse_ast返回dict你可以随意加字段。但 Claude Code 要求tool_result必须严格匹配input_schema的properties定义。比如你返回{nodes: [...], language: python, debug_info: {...}}而input_schema里没定义debug_infoClaude 会静默忽略该字段甚至可能中断后续流式响应。更致命的是Claude 的tool_result不支持嵌套对象。如果你返回{ast: {nodes: [...]}}ast字段会被当作字符串处理。必须扁平化{nodes: [...], language: python}。我为此写了tool_result_validator装饰器在 OMO 的tool函数返回前自动校验def tool_result_validator(func): def wrapper(*args, **kwargs): result func(*args, **kwargs) # 获取该 tool 的 input_schema schema get_tool_schema(func.__name__) # 校验 result 的 keys 是否全在 schema[properties] 中 invalid_keys set(result.keys()) - set(schema[properties].keys()) if invalid_keys: raise ToolResultValidationError(fInvalid keys in result: {invalid_keys}) return result return wrapper3.3 多模型能力的 YAML 分组逻辑OMO 的sisyphus.yaml允许按模型分组 Agentagents: - name: code_reviewer model: claude-3-opus-20240229 tools: [check_security, suggest_improvements] - name: doc_writer model: claude-3-sonnet-20240229 tools: [generate_summary, write_examples]这暗示code_reviewer应该用 Opusdoc_writer用 Sonnet。但 Claude Code 的model参数是 per-request 的你无法在tools数组里指定“哪个工具属于哪个模型”。解决方案是将模型选择权上收至 Agent 层而非工具层。在适配器中我设计了AgentExecutor类class AgentExecutor: def __init__(self, name: str, model: str, tools: List[Dict]): self.name name self.model model # 绑定到此 Agent 的默认模型 self.tools tools def execute(self, messages: List[Dict], session_id: str) - str: # 调用 Claude API 时固定使用 self.model response client.messages.create( modelself.model, messagesmessages, toolsself.tools, # ...其他参数 ) return response.content[0].text这样sisyphus.yaml的模型声明就自然映射为AgentExecutor的初始化参数无需修改 Claude 的工具调用协议。YAML 的语义被完整保留只是执行载体变了。4. 多 Agent 协同的隐式上下文传递从“自动注入”到“显式契约”在 OMO 中Agent A 调用工具返回结果后Sisyphus 会自动将结果注入 Agent B 的下一轮messages。这种“隐式传递”让开发者感觉协同很丝滑但也埋下隐患当流程变复杂比如 A→B→C→A 循环上下文污染难以追踪。Claude Code 强制你面对这个问题——没有隐式只有显式。我最初以为只要把 A 的tool_result拼进 B 的messages就行结果发现两个致命问题4.1 上下文膨胀与 token 超限A 的parse_ast返回 5000 token 的 ASTB 的generate_mermaid提示词本身要 800 token加上系统指令 200 token再加 AST 5000 token总输入轻松突破 Claude Opus 的 200K token 上限。更糟的是B 生成 Mermaid 图后C 的validate_layout又要把 Mermaid 字符串和 AST 一起传入token 数指数级增长。解决方案是引入上下文摘要层Context Summarizer。不是把原始 AST 传给 B而是让 A 在返回tool_result前先用轻量模型如 Haiku生成一段 200 token 内的摘要# 在 parse_ast 函数末尾添加 summary_prompt fSummarize the key structural elements of this AST for diagram generation. Focus on: top-level classes/functions, inheritance relationships, and major dependencies. Keep under 200 words. AST snippet: {str(ast_data)[:2000]} summary call_haiku(summary_prompt) return {summary: summary, full_ast: ast_data} # full_ast 存 cachesummary 传给 BB 收到summary后生成 MermaidC 再用 Haiku 对 Mermaid 做摘要传给下一级。实测 token 消耗降低 65%且生成质量未下降——因为 Claude 模型更擅长处理语义摘要而非原始语法树。4.2 工具调用链路的可追溯性缺失OMO 的日志里能看到清晰的A → parse_ast → B → generate_mermaid链路。Claude Code 的tool_use事件流是扁平的你只能看到tool_use: parse_ast不知道它属于哪个 Agent 的哪次调用。当 B 调用validate_layout失败时你无法快速定位是 A 的 AST 有问题还是 B 的 Mermaid 有语法错误。我的解法是在每条messages中注入x-agent-id和x-step-id元数据。不是用metadataClaude 不透传而是作为system提示词的一部分system_prompt fYou are {agent_name}, step {step_id} of the workflow. Your task is to... [Previous context summary: {context_summary}] --- This message is part of session {session_id}. Do not reference previous steps unless explicitly instructed.同时在AgentExecutor.execute()中记录日志logger.info(f[{session_id}] {agent_name} (step {step_id}) → tool_use: {tool_name})这样当validate_layout报错时日志里能立刻看到session_abc123 → doc_writer (step 3) → tool_use: validate_layout再结合session_id查 cache 里的ast和mermaid5 分钟内定位根因。注意x-agent-id和x-step-id必须由适配器生成并注入不能依赖模型自己输出。我见过有人让模型在system里写“我是 agent_x”结果模型在压力下会忘记这个身份输出“我是 agent_y”导致日志混乱。5. 为什么不能直接复用 OMO 的 agent_router—— 协同协议的底层差异很多开发者迁移时的第一反应是“把 OMO 的agent_router.py拿过来改改换掉 API 调用部分就行”。我试过两天后删掉了全部代码。原因在于OMO 的agent_router是为“同步、有状态、单次请求”设计的而 Claude Code 的本质是“异步、无状态、流式响应”。强行复用就像给电动车装燃油车变速箱——物理上能连但效率归零。OMO 的agent_router核心逻辑是接收用户输入messages根据sisyphus.yaml匹配首个 Agent调用该 Agent 的run()方法内部同步调用client.messages.create()解析响应若含tool_use则调用对应工具函数将工具结果拼入新messages递归调用下一个 Agent返回最终文本这个流程依赖两个关键假设假设一client.messages.create()是同步阻塞的。OMO 默认等待 Claude 返回完整content后才继续。但 Claude Code 的MessageStream是异步迭代器你得手动for event in stream:处理content_block_delta、tool_use、message_stop等事件。假设二工具调用是本地 Python 函数。OMO 的tool函数在本进程执行毫秒级返回。但你的parse_ast工具可能需要调用外部 AST 解析服务如 Tree-sitter耗时几百毫秒若在MessageStream的for循环里同步执行会阻塞整个流导致超时。真正的适配器必须重构为事件驱动状态机class ClaudeWorkflowEngine: def __init__(self, config: SisyphusConfig): self.config config self.state_machine WorkflowStateMachine() # 状态机管理当前步骤 def start_workflow(self, user_input: str, session_id: str): # 初始化状态当前 Agent 第一个上下文 user_input self.state_machine.set_state(code_analyzer, user_input, session_id) # 启动流式处理 stream self._create_stream_for_current_agent() for event in stream: if event.type content_block_delta: yield event.delta.text elif event.type tool_use: # 触发工具调用但不阻塞流 asyncio.create_task(self._handle_tool_use(event, session_id)) elif event.type message_stop: # 当前 Agent 完成推进状态机 next_agent self.config.get_next_agent(self.state_machine.current_agent) self.state_machine.set_state(next_agent, , session_id) # 重新创建流 stream self._create_stream_for_current_agent()这里的关键转变是从“递归调用”到“状态机推进”不再用函数调用栈管理流程而是用current_agent和session_id作为状态标识。从“同步工具”到“异步工具任务”_handle_tool_use启动asyncio.create_task工具执行在后台进行不影响主消息流。从“单次响应”到“持续流式输出”用户看到的是实时滚动的文本而非等待整个流程结束后的最终答案。我花了整整一天重写这个状态机但换来的是当code_analyzer正在解析 AST 时前端已开始显示arch_diagram_generator的思考过程“正在根据代码结构生成架构图…”体验流畅度提升一个数量级。这才是多 Agent 协同该有的样子——不是等所有环节做完才给反馈而是每个环节都在实时贡献价值。6. 实操避坑清单那些文档里不会写的血泪教训最后分享几个我在迁移过程中踩过的、文档绝不会提的坑。它们不致命但足以让你卡住一整天6.1 Claude 的tool_choice参数陷阱OMO 默认让模型自主选择工具对应 Claude 的tool_choice auto。但实测发现当tools数量 5 时auto模式下模型调用工具的准确率暴跌。我测试了 100 次parse_ast被选中的概率从 92% 降到 63%。解决方案对关键工具强制指定tool_choice。在AgentExecutor.execute()中# 对必须调用的工具显式指定 if self.name code_analyzer: tool_choice {type: tool, name: parse_ast} else: tool_choice auto注意tool_choice是 per-request 的不能全局设置。必须在每个 Agent 的调用中动态判断。6.2 YAML 中null值的解析歧义OMO 的sisyphus.yaml允许写tools: null表示该 Agent 不用工具。但 Python 的PyYAML解析null为None而 Claude Code 的tools参数要求是List[Dict]传None会直接报错。修复方式在配置解析层统一处理def parse_tools(yaml_tools) - List[Dict]: if yaml_tools is None: return [] # 转为空列表Claude 接受 if isinstance(yaml_tools, list): return yaml_tools raise ConfigError(tools must be list or null)6.3 流式响应中tool_use事件的乱序风险Claude 的MessageStream事件理论上按顺序到达但网络抖动时tool_use事件可能晚于content_block_delta到达。我遇到过一次content_block_delta先输出“生成中…”然后tool_use才来导致前端显示“生成中…”后突然跳转到工具调用界面体验割裂。对策在前端增加事件缓冲区。收到content_block_delta时不立即渲染而是存入buffer收到tool_use后清空buffer并渲染工具调用 UI收到message_stop后渲染最终内容。缓冲区超时如 500ms未等到tool_use则强制渲染buffer内容。6.4 Sisyphus 的retry_on_failure逻辑失效OMO 的 YAML 支持retry_on_failure: true失败时自动重试。但 Claude Code 的messages.create()失败如 429 限流时重试需重新构造messages而原始messages可能已包含上一轮的tool_result直接重试会导致重复调用工具。正确做法重试时必须重建干净的messages。在AgentExecutor.execute()中捕获异常后except RateLimitError: # 清除上一轮的 tool_result只保留用户原始输入和 system 提示 clean_messages [system_msg, {role: user, content: user_input}] return self._create_stream(clean_messages)这些细节没有一篇官方文档会告诉你。它们只存在于深夜调试的日志里和 Slack 频道里那句“兄弟你遇到过 tool_use 乱序吗”的求助中。现在我把它们写在这里希望你能少走些弯路。我在实际使用中发现这套迁移方案最大的价值不是技术上多酷炫而是把多 Agent 协同从“玄学调参”变成了“可工程化交付”。当sisyphus.yaml的每一行配置都能在 Claude Code 环境里找到明确的映射实体当每个tool_use事件都有session_id和step_id可追溯当 token 超限有摘要层兜底你就不再是在和模型搏斗而是在构建一个真正可靠的协同系统。下一步我正把这套适配器封装成omo-claude-sdk开源出来让“OmO skills”不再是个黑盒梗而成为每个开发者都能掌握的实用技能。