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

涉及源码 ：src/remote_runtime.py、src/direct_modes.py、src/main.py、src/bootstrap_graph.py，tests/test_porting_workspace.py。

1. 分支爆炸在说什么

真实 Agent/IDE Harness 里，「当前跑在哪」往往不是二元的，而是 多维组合：

控制面：本机进程 / 远程控制会话 / SSH 到另一台机器 /「Teleport」类工作区跳转；
链路面：直连后端 / 经上游代理 / 深链唤起带 query；
数据面 ：cwd、凭证、环境变量、信任门是否打开、是否允许执行 shell。

若一开始就把这些全部写进 bootstrap_session 或 QueryEnginePort，会出现：

条件组合指数级增长，单测难以覆盖；
网络/flaky 与 业务逻辑 缠在一起，排障困难；
CLI 与 UI 难以对齐「同一种模式」的命名。

模拟模式 策略是：先把「有哪些模式」和「每种模式对外暴露什么最小状态」钉死 ，实现体暂时是 占位返回值 ，从而 收束状态机的对外边界，再接真实 I/O。

2. 本仓库里的两块实现：`remote_runtime` vs `direct_modes`

2.1 远程族：`RuntimeModeReport`（remote / ssh / teleport）

python 复制代码

# 6:25:src/remote_runtime.py
@dataclass(frozen=True)
class RuntimeModeReport:
    mode: str
    connected: bool
    detail: str

    def as_text(self) -> str:
        return f'mode={self.mode}\nconnected={self.connected}\ndetail={self.detail}'


def run_remote_mode(target: str) -> RuntimeModeReport:
    return RuntimeModeReport('remote', True, f'Remote control placeholder prepared for {target}')


def run_ssh_mode(target: str) -> RuntimeModeReport:
    return RuntimeModeReport('ssh', True, f'SSH proxy placeholder prepared for {target}')


def run_teleport_mode(target: str) -> RuntimeModeReport:
    return RuntimeModeReport('teleport', True, f'Teleport resume/create placeholder prepared for {target}')

收束点：

一模式一函数 ：run_remote_mode / run_ssh_mode / run_teleport_mode，入口清晰，未来可在函数内换实现而不扩散调用点。
报告结构固定 ：mode + connected + detail，CLI 与人类 diff 都稳定。
无网络、无子进程 ：移植期 确定性输出 ，CI 只断言 mode=... 子串即可。

2.2 直连族：`DirectModeReport`（direct-connect / deep-link）

python 复制代码

# 6:21:src/direct_modes.py
@dataclass(frozen=True)
class DirectModeReport:
    mode: str
    target: str
    active: bool

    def as_text(self) -> str:
        return f'mode={self.mode}\ntarget={self.target}\nactive={self.active}'


def run_direct_connect(target: str) -> DirectModeReport:
    return DirectModeReport(mode='direct-connect', target=target, active=True)


def run_deep_link(target: str) -> DirectModeReport:
    return DirectModeReport(mode='deep-link', target=target, active=True)

收束点 ：显式保留 target （深链 URI、工作区 id 等未来可解析），与远程族用 detail 字符串 承载上下文略有不同------属于 演进期可统一的报告形状 （例如将来抽 共用 ModeReport 基类）。

3. CLI：一子命令一模态，help 写明 simulate

python 复制代码

# 68:77:src/main.py
    remote_parser = subparsers.add_parser('remote-mode', help='simulate remote-control runtime branching')
    remote_parser.add_argument('target')
    ssh_parser = subparsers.add_parser('ssh-mode', help='simulate SSH runtime branching')
    ssh_parser.add_argument('target')
    teleport_parser = subparsers.add_parser('teleport-mode', help='simulate teleport runtime branching')
    teleport_parser.add_argument('target')
    direct_parser = subparsers.add_parser('direct-connect-mode', help='simulate direct-connect runtime branching')
    direct_parser.add_argument('target')
    deep_link_parser = subparsers.add_parser('deep-link-mode', help='simulate deep-link runtime branching')
    deep_link_parser.add_argument('target')

python 复制代码

# 171:185:src/main.py
    if args.command == 'remote-mode':
        print(run_remote_mode(args.target).as_text())
        return 0
    if args.command == 'ssh-mode':
        print(run_ssh_mode(args.target).as_text())
        return 0
    if args.command == 'teleport-mode':
        print(run_teleport_mode(args.target).as_text())
        return 0
    if args.command == 'direct-connect-mode':
        print(run_direct_connect(args.target).as_text())
        return 0
    if args.command == 'deep-link-mode':
        print(run_deep_link(args.target).as_text())
        return 0

收束状态机的方式：

用户意图 → 子命令 即 离散状态，不靠「再猜一个 flag 组合」。
target 是唯一自由变量 ，先统一成字符串，后续再在各自 run_* 内做解析/校验。
与 bootstrap / turn-loop 解耦 ：当前 PortRuntime.bootstrap_session 不读取这些模式 ------避免「单条命令里藏六种 runtime」，先把 模式探针 做成 独立 CLI ，符合 分阶段集成。

4. 测试如何把「模式」钉成契约

python 复制代码

# 196:202:tests/test_porting_workspace.py
    def test_remote_mode_clis_run(self) -> None:
        remote_result = subprocess.run([sys.executable, '-m', 'src.main', 'remote-mode', 'workspace'], check=True, capture_output=True, text=True)
        ssh_result = subprocess.run([sys.executable, '-m', 'src.main', 'ssh-mode', 'workspace'], check=True, capture_output=True, text=True)
        teleport_result = subprocess.run([sys.executable, '-m', 'src.main', 'teleport-mode', 'workspace'], check=True, capture_output=True, text=True)
        self.assertIn('mode=remote', remote_result.stdout)
        self.assertIn('mode=ssh', ssh_result.stdout)
        self.assertIn('mode=teleport', teleport_result.stdout)

python 复制代码

# 238:244:tests/test_porting_workspace.py
    def test_bootstrap_graph_and_direct_modes_run(self) -> None:
        graph_result = subprocess.run([sys.executable, '-m', 'src.main', 'bootstrap-graph'], check=True, capture_output=True, text=True)
        direct_result = subprocess.run([sys.executable, '-m', 'src.main', 'direct-connect-mode', 'workspace'], check=True, capture_output=True, text=True)
        deep_link_result = subprocess.run([sys.executable, '-m', 'src.main', 'deep-link-mode', 'workspace'], check=True, capture_output=True, text=True)
        self.assertIn('Bootstrap Graph', graph_result.stdout)
        self.assertIn('mode=direct-connect', direct_result.stdout)
        self.assertIn('mode=deep-link', deep_link_result.stdout)

学习点 ：断言 稳定键 （mode=...），不断言占位文案全文------占位升级时 少碎测试。

5. 与「启动叙事」对齐：`bootstrap_graph`

python 复制代码

# 16:26:src/bootstrap_graph.py
def build_bootstrap_graph() -> BootstrapGraph:
    return BootstrapGraph(
        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.py + main ，二者分层：先 CLI 契约与小报告对象 ，再填包内实现。

7. 后续接真实现时的建议（仍防爆炸）

统一 RuntimeContext 或 SessionTransport ：内含 mode: Enum、target: str、可选 credentials_handle，由 单一工厂 根据 CLI/配置构造，避免在十处 if ssh。
真实连接失败 → 仍返回 结构化报告 （connected=False, 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 的模态面 ，再 填远程包与真实链路。

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

1. 分支爆炸在说什么

2. 本仓库里的两块实现：remote_runtime vs direct_modes

2.1 远程族：RuntimeModeReport（remote / ssh / teleport）

2.2 直连族：DirectModeReport（direct-connect / deep-link）

3. CLI：一子命令一模态，help 写明 simulate

4. 测试如何把「模式」钉成契约

5. 与「启动叙事」对齐：bootstrap_graph

6. 与 src/remote/ 占位包的关系

7. 后续接真实现时的建议（仍防爆炸）

8. 小结

2. 本仓库里的两块实现：`remote_runtime` vs `direct_modes`

2.1 远程族：`RuntimeModeReport`（remote / ssh / teleport）

2.2 直连族：`DirectModeReport`（direct-connect / deep-link）

5. 与「启动叙事」对齐：`bootstrap_graph`

6. 与 `src/remote/` 占位包的关系