claw-code 源码详细分析：Remote / SSH / Teleport / Deep Link——运行时分支爆炸怎样用「模拟模式」先收束状态机？

涉及源码src/remote_runtime.py、src/direct_modes.py、src/main.py、src/bootstrap_graph.pytests/test_porting_workspace.py。1. 分支爆炸在说什么真实 Agent/IDE Harness 里「当前跑在哪」往往不是二元的而是多维组合控制面本机进程 / 远程控制会话 / SSH 到另一台机器 /「Teleport」类工作区跳转链路面直连后端 / 经上游代理 / 深链唤起带 query数据面cwd、凭证、环境变量、信任门是否打开、是否允许执行 shell。若一开始就把这些全部写进bootstrap_session或QueryEnginePort会出现条件组合指数级增长单测难以覆盖网络/flaky与业务逻辑缠在一起排障困难CLI 与 UI难以对齐「同一种模式」的命名。模拟模式策略是先把「有哪些模式」和「每种模式对外暴露什么最小状态」钉死实现体暂时是占位返回值从而收束状态机的对外边界再接真实 I/O。2. 本仓库里的两块实现remote_runtimevsdirect_modes2.1 远程族RuntimeModeReportremote / ssh / teleport# 6:25:src/remote_runtime.pydataclass(frozenTrue)classRuntimeModeReport:mode:strconnected:booldetail:strdefas_text(self)-str:returnfmode{self.mode}\nconnected{self.connected}\ndetail{self.detail}defrun_remote_mode(target:str)-RuntimeModeReport:returnRuntimeModeReport(remote,True,fRemote control placeholder prepared for{target})defrun_ssh_mode(target:str)-RuntimeModeReport:returnRuntimeModeReport(ssh,True,fSSH proxy placeholder prepared for{target})defrun_teleport_mode(target:str)-RuntimeModeReport:returnRuntimeModeReport(teleport,True,fTeleport resume/create placeholder prepared for{target})收束点一模式一函数run_remote_mode/run_ssh_mode/run_teleport_mode入口清晰未来可在函数内换实现而不扩散调用点。报告结构固定modeconnecteddetailCLI 与人类 diff 都稳定。无网络、无子进程移植期确定性输出CI 只断言mode...子串即可。2.2 直连族DirectModeReportdirect-connect / deep-link# 6:21:src/direct_modes.pydataclass(frozenTrue)classDirectModeReport:mode:strtarget:stractive:booldefas_text(self)-str:returnfmode{self.mode}\ntarget{self.target}\nactive{self.active}defrun_direct_connect(target:str)-DirectModeReport:returnDirectModeReport(modedirect-connect,targettarget,activeTrue)defrun_deep_link(target:str)-DirectModeReport:returnDirectModeReport(modedeep-link,targettarget,activeTrue)收束点显式保留target深链 URI、工作区 id 等未来可解析与远程族用detail字符串承载上下文略有不同——属于演进期可统一的报告形状例如将来抽共用ModeReport基类。3. CLI一子命令一模态help 写明 simulate# 68:77:src/main.pyremote_parsersubparsers.add_parser(remote-mode,helpsimulate remote-control runtime branching)remote_parser.add_argument(target)ssh_parsersubparsers.add_parser(ssh-mode,helpsimulate SSH runtime branching)ssh_parser.add_argument(target)teleport_parsersubparsers.add_parser(teleport-mode,helpsimulate teleport runtime branching)teleport_parser.add_argument(target)direct_parsersubparsers.add_parser(direct-connect-mode,helpsimulate direct-connect runtime branching)direct_parser.add_argument(target)deep_link_parsersubparsers.add_parser(deep-link-mode,helpsimulate deep-link runtime branching)deep_link_parser.add_argument(target)# 171:185:src/main.pyifargs.commandremote-mode:print(run_remote_mode(args.target).as_text())return0ifargs.commandssh-mode:print(run_ssh_mode(args.target).as_text())return0ifargs.commandteleport-mode:print(run_teleport_mode(args.target).as_text())return0ifargs.commanddirect-connect-mode:print(run_direct_connect(args.target).as_text())return0ifargs.commanddeep-link-mode:print(run_deep_link(args.target).as_text())return0收束状态机的方式用户意图 → 子命令即离散状态不靠「再猜一个 flag 组合」。target是唯一自由变量先统一成字符串后续再在各自run_*内做解析/校验。与bootstrap/turn-loop解耦当前PortRuntime.bootstrap_session不读取这些模式——避免「单条命令里藏六种 runtime」先把模式探针做成独立 CLI符合分阶段集成。4. 测试如何把「模式」钉成契约# 196:202:tests/test_porting_workspace.pydeftest_remote_mode_clis_run(self)-None:remote_resultsubprocess.run([sys.executable,-m,src.main,remote-mode,workspace],checkTrue,capture_outputTrue,textTrue)ssh_resultsubprocess.run([sys.executable,-m,src.main,ssh-mode,workspace],checkTrue,capture_outputTrue,textTrue)teleport_resultsubprocess.run([sys.executable,-m,src.main,teleport-mode,workspace],checkTrue,capture_outputTrue,textTrue)self.assertIn(moderemote,remote_result.stdout)self.assertIn(modessh,ssh_result.stdout)self.assertIn(modeteleport,teleport_result.stdout)# 238:244:tests/test_porting_workspace.pydeftest_bootstrap_graph_and_direct_modes_run(self)-None:graph_resultsubprocess.run([sys.executable,-m,src.main,bootstrap-graph],checkTrue,capture_outputTrue,textTrue)direct_resultsubprocess.run([sys.executable,-m,src.main,direct-connect-mode,workspace],checkTrue,capture_outputTrue,textTrue)deep_link_resultsubprocess.run([sys.executable,-m,src.main,deep-link-mode,workspace],checkTrue,capture_outputTrue,textTrue)self.assertIn(Bootstrap Graph,graph_result.stdout)self.assertIn(modedirect-connect,direct_result.stdout)self.assertIn(modedeep-link,deep_link_result.stdout)学习点断言稳定键mode...不断言占位文案全文——占位升级时少碎测试。5. 与「启动叙事」对齐bootstrap_graph# 16:26:src/bootstrap_graph.pydefbuild_bootstrap_graph()-BootstrapGraph:returnBootstrapGraph(stages(top-level prefetch side effects,warning handler and environment guards,CLI parser and pre-action trust gate,setup() commands/agents parallel load,deferred init after trust,mode routing: local / remote / ssh / teleport / direct-connect / deep-link,query engine submit loop,))作用在文档/评审层把模式路由标成独立阶段与query engine submit loop前后分明——提醒实现者先定 mode再进会话循环而不是在循环里隐式猜环境。6. 与src/remote/占位包的关系src/remote/等目录通过reference_data/subsystems/remote.json挂归档体量元数据见result/12.md代表未来真实远程子系统的代码位置当前可执行的「模式探针」在remote_runtime.py/direct_modes.pymain二者分层先 CLI 契约与小报告对象再填包内实现。7. 后续接真实现时的建议仍防爆炸统一RuntimeContext或SessionTransport内含mode: Enum、target: str、可选credentials_handle由单一工厂根据 CLI/配置构造避免在十处if ssh。真实连接失败→ 仍返回结构化报告connectedFalse,detail错误原因与现在形状兼容便于 UI 与日志。再把 mode 注入bootstrap_session例如PortRuntime.bootstrap_session(..., transport...)单测里注入 fake transport保持无网可跑。组合爆炸用表驱动测试(mode, target_validity) - expected_report而非复制五个集成测试。8. 小结Remote / SSH / Teleport / Direct-connect / Deep-link在本仓库中通过独立子命令 小型不可变报告 dataclass 纯函数入口实现模拟模式。状态机被收束在离散 CLI 分支、固定文本键mode、与核心bootstrap_session暂时分离三层。bootstrap_graph把「mode routing」写成显式阶段与submit loop解耦叙事。这是典型Harness 移植节奏先可测、无 I/O 的模态面再填远程包与真实链路。