claw-code 源码详细分析：命令宇宙 vs 工具宇宙——`commands` / `tools` 镜像清单如何驱动路由与 shim 执行？

涉及源码src/reference_data/commands_snapshot.json、tools_snapshot.jsonsrc/commands.py、src/tools.py、src/execution_registry.py、src/runtime.py、src/main.pysrc/models.pyPortingModule。1. 「两个宇宙」是什么在本仓库里命令宇宙与工具宇宙是两套有穷、可版本化的镜像清单都从 JSON 快照加载为内存中的PortingModule元组命令src/reference_data/commands_snapshot.json→PORTED_COMMANDScommands.py工具src/reference_data/tools_snapshot.json→PORTED_TOOLStools.py快照里每条记录至少包含name、source_hint、responsibility加载时映射进PortingModulestatusmirrored# 23:33:src/commands.pydefload_command_snapshot()-tuple[PortingModule,...]:raw_entriesjson.loads(SNAPSHOT_PATH.read_text())returntuple(PortingModule(nameentry[name],responsibilityentry[responsibility],source_hintentry[source_hint],statusmirrored,)forentryinraw_entries)# 23:34:src/tools.pydefload_tool_snapshot()-tuple[PortingModule,...]:raw_entriesjson.loads(SNAPSHOT_PATH.read_text())returntuple(PortingModule(nameentry[name],responsibilityentry[responsibility],source_hintentry[source_hint],statusmirrored,)forentryinraw_entries)产品语义上与具体 IDE/Agent 产品对齐时命令多对应用户显式/slash、调色板动作、工作流入口工具多对应模型 function-calling / MCP 暴露给模型的可调用面。claw-code 在路由层用kind: command | tool把两宇宙拆开评分与排序在执行层用不同 shim 签名promptvspayload区分。2. 清单如何「驱动」——三层流水线可以把数据流画成快照 → 全量宇宙 →可选过滤视图→ 路由 → 注册表 shim →QueryEnginePort摘要。阶段命令侧工具侧真相源commands_snapshot.jsontools_snapshot.json全量常量PORTED_COMMANDSPORTED_TOOLS过滤视图get_commands(..., include_plugin_commands, include_skill_commands)get_tools(simple_mode, include_mcp, permission_context)路由输入route_prompt用全量PORTED_COMMANDS同上PORTED_TOOLS精确执行execute_command/MirroredCommandexecute_tool/MirroredTool关键点路由不看get_tools的权限过滤。即使用户 CLI 里--deny-prefix mcp缩小了「可见工具列表」默认route_prompt仍会在完整PORTED_TOOLS上匹配与「模型实际能调用什么」的严格对齐需在上层再收敛见result/05.md。3. 路由PortRuntime.route_prompt3.1 分轨收集 公平首发 余量排序# 90:107:src/runtime.pydefroute_prompt(self,prompt:str,limit:int5)-list[RoutedMatch]:tokens{token.lower()fortokeninprompt.replace(/, ).replace(-, ).split()iftoken}by_kind{command:self._collect_matches(tokens,PORTED_COMMANDS,command),tool:self._collect_matches(tokens,PORTED_TOOLS,tool),}selected:list[RoutedMatch][]forkindin(command,tool):ifby_kind[kind]:selected.append(by_kind[kind].pop(0))leftoverssorted([matchformatchesinby_kind.values()formatchinmatches],keylambdaitem:(-item.score,item.kind,item.name),)selected.extend(leftovers[:max(0,limit-len(selected))])returnselected[:limit]工程含义分词把/、-替换成空格再split得到小写 token 集合适合从自然语言 prompt 里「捞」到与name/source_hint重叠的词。双宇宙并行评分对命令、工具各跑一遍_collect_matches得到两个已按分数排序的列表。各取第一名先从 command 榜、tool 榜各拿一个最高分若存在避免某一宇宙霸占整个limit。合并余量剩余候选按分数降序同分按kind、name稳定排序填满limit。3.2 单条评分名字 路径提示 职责描述# 176:192:src/runtime.pydef_collect_matches(self,tokens:set[str],modules:tuple[PortingModule,...],kind:str)-list[RoutedMatch]:matches:list[RoutedMatch][]formoduleinmodules:scoreself._score(tokens,module)ifscore0:matches.append(RoutedMatch(kindkind,namemodule.name,source_hintmodule.source_hint,scorescore))matches.sort(keylambdaitem:(-item.score,item.name))returnmatchesstaticmethoddef_score(tokens:set[str],module:PortingModule)-int:haystacks[module.name.lower(),module.source_hint.lower(),module.responsibility.lower()]score0fortokenintokens:ifany(tokeninhaystackforhaystackinhaystacks):score1returnscore学习点路由是子串命中计数不是 embeddingsource_hint含文件路径用户说MCP、review等词时容易同时命中命令与工具条目正好检验双轨公平逻辑。RoutedMatch携带kind后续执行与QueryEnginePort的matched_commands/matched_tools分拆都依赖它# 16:21:src/runtime.pydataclass(frozenTrue)classRoutedMatch:kind:strname:strsource_hint:strscore:int4. Shim 执行ExecutionRegistry→execute_*4.1 注册表 全量清单的薄包装# 47:51:src/execution_registry.pydefbuild_execution_registry()-ExecutionRegistry:returnExecutionRegistry(commandstuple(MirroredCommand(module.name,module.source_hint)formoduleinPORTED_COMMANDS),toolstuple(MirroredTool(module.name,module.source_hint)formoduleinPORTED_TOOLS),)registry.command(name)/registry.tool(name)大小写不敏感查找与get_command/get_tool一致。4.2 命令 shimprompt字符串# 75:80:src/commands.pydefexecute_command(name:str,prompt:str)-CommandExecution:moduleget_command(name)ifmoduleisNone:returnCommandExecution(namename,source_hint,promptprompt,handledFalse,messagefUnknown mirrored command:{name})actionfMirrored command {module.name} from{module.source_hint}would handle prompt{prompt!r}.returnCommandExecution(namemodule.name,source_hintmodule.source_hint,promptprompt,handledTrue,messageaction)4.3 工具 shimpayload字符串# 81:86:src/tools.pydefexecute_tool(name:str,payload:str)-ToolExecution:moduleget_tool(name)ifmoduleisNone:returnToolExecution(namename,source_hint,payloadpayload,handledFalse,messagefUnknown mirrored tool:{name})actionfMirrored tool {module.name} from{module.source_hint}would handle payload{payload!r}.returnToolExecution(namemodule.name,source_hintmodule.source_hint,payloadpayload,handledTrue,messageaction)命名差异是接口层对未来「命令吃自然语言 / 工具吃 JSON payload」的预留当前bootstrap 里工具也传了用户prompt当 payload# 119:120:src/runtime.pycommand_execstuple(registry.command(match.name).execute(prompt)formatchinmatchesifmatch.kindcommandandregistry.command(match.name))tool_execstuple(registry.tool(match.name).execute(prompt)formatchinmatchesifmatch.kindtoolandregistry.tool(match.name))即路由后的统一「用户 utterance」先灌进两条执行链真实现时可再分支解析。5.bootstrap_session路由 shim 引擎一条链# 117:133:src/runtime.pymatchesself.route_prompt(prompt,limitlimit)registrybuild_execution_registry()command_execstuple(registry.command(match.name).execute(prompt)formatchinmatchesifmatch.kindcommandandregistry.command(match.name))tool_execstuple(registry.tool(match.name).execute(prompt)formatchinmatchesifmatch.kindtoolandregistry.tool(match.name))denialstuple(self._infer_permission_denials(matches))stream_eventstuple(engine.stream_submit_message(prompt,matched_commandstuple(match.nameformatchinmatchesifmatch.kindcommand),matched_toolstuple(match.nameformatchinmatchesifmatch.kindtool),denied_toolsdenials,))turn_resultengine.submit_message(prompt,matched_commandstuple(match.nameformatchinmatchesifmatch.kindcommand),matched_toolstuple(match.nameformatchinmatchesifmatch.kindtool),denied_toolsdenials,)顺序matches→ 按kind跑 shim → 推断denials→ 把名称元组不是路径交给QueryEnginePort。报告RuntimeSession.as_markdown()分别打印Routed Matches、Command Execution、Tool Execution、Stream Events、Turn Result见runtime.py中as_markdown便于肉眼核对「路由到了谁 → shim 说了啥 → 引擎摘要里写了啥」。6. CLI清单自省、路由调试、按名 shim子命令作用commands/tools走get_commands/get_tools可带过滤列表视图route prompt直接route_prompt打印kind\tname\tscore\tsource_hintshow-command/show-toolget_command/get_tool按精确名看单条条目exec-command/exec-tool不经路由按名执行 shim失败 exit 1# 142:148:src/main.pyifargs.commandroute:matchesPortRuntime().route_prompt(args.prompt,limitargs.limit)ifnotmatches:print(No mirrored command/tool matches found.)return0formatchinmatches:print(f{match.kind}\t{match.name}\t{match.score}\t{match.source_hint})# 200:207:src/main.pyifargs.commandexec-command:resultexecute_command(args.name,args.prompt)print(result.message)return0ifresult.handledelse1ifargs.commandexec-tool:resultexecute_tool(args.name,args.payload)print(result.message)return0ifresult.handledelse1测试锚点test_route_and_show_entry_cli_run、test_exec_command_and_tool_cli_run、test_execution_registry_runs等把快照非空、路由可命中、shim 有固定子串锁在 CI 里。7. 镜像数据的「真实形状」与陷阱7.1 同名多条目快照里同一name可对应多条例如多个source_hint指向不同文件{name:add-dir,source_hint:commands/add-dir/add-dir.tsx,...},{name:add-dir,source_hint:commands/add-dir/index.ts,...},get_command/get_tool线性扫描返回首个大小写匹配项# 52:56:src/commands.pydefget_command(name:str)-PortingModule|None:needlename.lower()formoduleinPORTED_COMMANDS:ifmodule.name.lower()needle:returnmodule后果shim 与show-command展示的source_hint可能只是其中一条路由里每条快照行仍是独立PortingModule同名可多次命中、多次出现在不同RoutedMatch若分数与 limit 允许。产品化时常需要primary_fqn或entry_id消歧。7.2 工具快照里的「非顶层工具」名tools_snapshot.json中会出现UI、agentMemory等与「用户心智中的工具类名」混在一起的条目它们来自归档路径镜像。路由仍按 token 子串匹配——这是移植期忠实还原表面不是最终 UX成熟产品会在清单层再标callable: bool或分层 tool spec。8. 小结命令宇宙 / 工具宇宙由JSON 快照 →PORTED_*→可选get_*过滤构成路由固定吃全量PORTED_*与列表过滤解耦。路由在两条宇宙上独立打分、各取榜首、再合并余量输出带kind的RoutedMatch。Shim经ExecutionRegistry统一按名查找命令用prompt语义工具用payload语义bootstrap 阶段暂用同一用户字符串灌入。CLI提供列表 / 路由 / 精确查看 / 精确执行四条路径支撑移植期可测试、可调试闭环。