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

涉及源码：src/reference_data/commands_snapshot.json、tools_snapshot.json，src/commands.py、src/tools.py、src/execution_registry.py、src/runtime.py、src/main.py，src/models.py（PortingModule）。

1. 「两个宇宙」是什么

在本仓库里，命令宇宙与工具宇宙是两套有穷、可版本化的镜像清单，都从 JSON 快照加载为内存中的PortingModule元组：

• 命令：src/reference_data/commands_snapshot.json→PORTED_COMMANDS（commands.py）
• 工具：src/reference_data/tools_snapshot.json→PORTED_TOOLS（tools.py）

快照里每条记录至少包含name、source_hint、responsibility（加载时映射进PortingModule，status='mirrored'）：

# 23:33:src/commands.pydefload_command_snapshot()->tuple[PortingModule,...]:raw_entries=json.loads(SNAPSHOT_PATH.read_text())returntuple(PortingModule(name=entry['name'],responsibility=entry['responsibility'],source_hint=entry['source_hint'],status='mirrored',)forentryinraw_entries)

# 23:34:src/tools.pydefload_tool_snapshot()->tuple[PortingModule,...]:raw_entries=json.loads(SNAPSHOT_PATH.read_text())returntuple(PortingModule(name=entry['name'],responsibility=entry['responsibility'],source_hint=entry['source_hint'],status='mirrored',)forentryinraw_entries)

产品语义上（与具体 IDE/Agent 产品对齐时）：命令多对应用户显式/slash、调色板动作、工作流入口；工具多对应模型 function-calling / MCP 暴露给模型的可调用面。claw-code 在路由层用kind: command | tool把两宇宙拆开评分与排序，在执行层用不同 shim 签名（promptvspayload）区分。

2. 清单如何「驱动」——三层流水线

可以把数据流画成：快照 → 全量宇宙 →（可选过滤视图）→ 路由 → 注册表 shim →QueryEnginePort摘要。

关键点：路由不看get_tools的权限过滤。即使用户 CLI 里--deny-prefix mcp缩小了「可见工具列表」，默认route_prompt仍会在完整PORTED_TOOLS上匹配（与「模型实际能调用什么」的严格对齐需在上层再收敛，见result/05.md）。

3. 路由：PortRuntime.route_prompt

3.1 分轨收集 + 公平首发 + 余量排序

# 90:107:src/runtime.pydefroute_prompt(self,prompt:str,limit:int=5)->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))leftovers=sorted([matchformatchesinby_kind.values()formatchinmatches],key=lambdaitem:(-item.score,item.kind,item.name),)selected.extend(leftovers[:max(0,limit-len(selected))])returnselected[:limit]

工程含义：

1. 分词：把/、-替换成空格再split，得到小写 token 集合（适合从自然语言 prompt 里「捞」到与name/source_hint重叠的词）。
2. 双宇宙并行评分：对命令、工具各跑一遍_collect_matches，得到两个已按分数排序的列表。
3. 各取第一名：先从 command 榜、tool 榜各拿一个最高分（若存在），避免某一宇宙霸占整个limit。
4. 合并余量：剩余候选按分数降序，同分按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:score=self._score(tokens,module)ifscore>0:matches.append(RoutedMatch(kind=kind,name=module.name,source_hint=module.source_hint,score=score))matches.sort(key=lambdaitem:(-item.score,item.name))returnmatches@staticmethoddef_score(tokens:set[str],module:PortingModule)->int:haystacks=[module.name.lower(),module.source_hint.lower(),module.responsibility.lower()]score=0fortokenintokens:ifany(tokeninhaystackforhaystackinhaystacks):score+=1returnscore

学习点：路由是子串命中计数，不是 embedding；source_hint含文件路径，用户说MCP、review等词时容易同时命中命令与工具条目，正好检验双轨公平逻辑。

RoutedMatch携带kind，后续执行与QueryEnginePort的matched_commands/matched_tools分拆都依赖它：

# 16:21:src/runtime.py@dataclass(frozen=True)classRoutedMatch:kind:strname:strsource_hint:strscore:int

4. Shim 执行：ExecutionRegistry→execute_*

4.1 注册表 = 全量清单的薄包装

# 47:51:src/execution_registry.pydefbuild_execution_registry()->ExecutionRegistry:returnExecutionRegistry(commands=tuple(MirroredCommand(module.name,module.source_hint)formoduleinPORTED_COMMANDS),tools=tuple(MirroredTool(module.name,module.source_hint)formoduleinPORTED_TOOLS),)

registry.command(name)/registry.tool(name)大小写不敏感查找，与get_command/get_tool一致。

4.2 命令 shim：prompt字符串

# 75:80:src/commands.pydefexecute_command(name:str,prompt:str='')->CommandExecution:module=get_command(name)ifmoduleisNone:returnCommandExecution(name=name,source_hint='',prompt=prompt,handled=False,message=f'Unknown mirrored command:{name}')action=f"Mirrored command '{module.name}' from{module.source_hint}would handle prompt{prompt!r}."returnCommandExecution(name=module.name,source_hint=module.source_hint,prompt=prompt,handled=True,message=action)

4.3 工具 shim：payload字符串

# 81:86:src/tools.pydefexecute_tool(name:str,payload:str='')->ToolExecution:module=get_tool(name)ifmoduleisNone:returnToolExecution(name=name,source_hint='',payload=payload,handled=False,message=f'Unknown mirrored tool:{name}')action=f"Mirrored tool '{module.name}' from{module.source_hint}would handle payload{payload!r}."returnToolExecution(name=module.name,source_hint=module.source_hint,payload=payload,handled=True,message=action)

命名差异是接口层对未来「命令吃自然语言 / 工具吃 JSON payload」的预留；当前bootstrap 里工具也传了用户prompt当 payload：

# 119:120:src/runtime.pycommand_execs=tuple(registry.command(match.name).execute(prompt)formatchinmatchesifmatch.kind=='command'andregistry.command(match.name))tool_execs=tuple(registry.tool(match.name).execute(prompt)formatchinmatchesifmatch.kind=='tool'andregistry.tool(match.name))

即：路由后的统一「用户 utterance」先灌进两条执行链，真实现时可再分支解析。

5.bootstrap_session：路由 + shim + 引擎一条链

# 117:133:src/runtime.pymatches=self.route_prompt(prompt,limit=limit)registry=build_execution_registry()command_execs=tuple(registry.command(match.name).execute(prompt)formatchinmatchesifmatch.kind=='command'andregistry.command(match.name))tool_execs=tuple(registry.tool(match.name).execute(prompt)formatchinmatchesifmatch.kind=='tool'andregistry.tool(match.name))denials=tuple(self._infer_permission_denials(matches))stream_events=tuple(engine.stream_submit_message(prompt,matched_commands=tuple(match.nameformatchinmatchesifmatch.kind=='command'),matched_tools=tuple(match.nameformatchinmatchesifmatch.kind=='tool'),denied_tools=denials,))turn_result=engine.submit_message(prompt,matched_commands=tuple(match.nameformatchinmatchesifmatch.kind=='command'),matched_tools=tuple(match.nameformatchinmatchesifmatch.kind=='tool'),denied_tools=denials,)

顺序：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

# 142:148:src/main.pyifargs.command=='route':matches=PortRuntime().route_prompt(args.prompt,limit=args.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.command=='exec-command':result=execute_command(args.name,args.prompt)print(result.message)return0ifresult.handledelse1ifargs.command=='exec-tool':result=execute_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:needle=name.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提供列表 / 路由 / 精确查看 / 精确执行四条路径，支撑移植期可测试、可调试闭环。