子集群状态与自动调度

本地模式和中心模式使用相同工具。前者把集群、任务和历史保存在本机；后者保存在中心。中心分派任务，指定 companion 执行器负责管理成员，探测本身在成员的原生节点运行。

工具	用途
`ssh_cluster_manage`	创建、更新、停用和删除集群
`ssh_cluster_policy`	管理候选路由、质量门槛与自动操作授权
`ssh_cluster_inspect`	查询集群、策略、任务、事件和历史
`ssh_cluster_task`	发起一次采集/选路测量、取消排队任务、核对未知写入的回执

配置周期探测

用 ssh_node_manage 安装、启动并检查成员节点。记录返回的 deviceId；服务器名称不能代替设备 ID。
执行器使用运行 companion 的主 @local 设备 ID。远端成员可以只安装 sshmcp-node；节点不接收中心 API Key 或其他机器的 SSH 私钥。执行器须通过已配置 SSH 管理通路访问成员；其他 companion 的 @local 只能由其本人管理。
调用 ssh_cluster_manage(action="save", expectedRevision=0, spec=...)。例如，将下列设备占位符替换为刚查询的真实 ID：

{
  "id": "office",
  "members": [{
    "device": "MEMBER_DEVICE_ID",
    "probes": [{
      "id": "ssh",
      "target": {"kind": "tcp", "address": "127.0.0.1:22"},
      "intervalMs": 10000,
      "timeoutMs": 2000,
      "window": 30
    }]
  }],
  "executors": ["COMPANION_PRIMARY_DEVICE_ID"],
  "intervalMs": 10000,
  "staleAfterMs": 60000
}

address 在成员节点解释。原生探测周期由每个 probe 的 intervalMs 控制，集群的同名字段控制执行器采集周期。上例分别为 10 秒；任务较慢时不叠加重复执行。

已有 P2P link 可使用 {"kind":"p2p","link":"已有 link ID"}；经该 link 探测对端已授权 TCP 服务可使用 {"kind":"forward","link":"已有 link ID","target":"127.0.0.1:22"}。不配置任意网段扫描；没有可用 link 或权限时会记录失败。

parent 引用现有集群，最多八层。一个设备只能有一个直接归属，父视图汇总后代。gateways 可声明本集群或后代中的网关候选。停用一个集群只退役它直接拥有的探测；子集群独立启停。

配置保存后，查询 ssh_cluster_inspect(section="clusters", id="office")，检查 appliedRevision、执行器心跳和成员 runtime。保存成功不等于成员已经加载。

授权自动选路

先使用普通路由工具配置并验证候选路径。在来源 companion 上应用一条显式 sourceDevice 路由，作为策略起点。策略必须有 2–8 个不同候选，全部使用同一来源主设备和同一 SSH 服务器；目标服务器须是 targetCluster 成员登记的管理名称或别名。

调用 ssh_cluster_policy(action="save", expectedRevision=0, spec=...)。spec 包含：

id、sourceDevice、sourceCluster、targetCluster。
candidates：每项有唯一 id 和完整 route，保留已检查路由的 server、via、sourceDevice、description、ingress、resources、enabled；sourceInstance 只能省略或为 null。其中一个候选必须与当前路由完全一致。
mandatoryVia：每个候选均须保留的完整必经跳板顺序。不会因为延迟更低而跳过这些跳板。
autoSwitch：默认 false。打开后允许达到门槛时修改路由；已有节点授权不随自动切换扩张。
autoRepair：默认 false。打开后，仅在所有候选都出现新鲜失败时尝试启动当前路径已登记、被策略引用的受管资源。若需要修改节点配置或权限，留下错误，由显式 route plan 处理。

默认每 30 秒测量候选，单候选超时 5 秒、需要 3 次独立确认、操作冷却 60 秒。当前路径正常时，替代路径的近期中位延迟须至少改善 20%；当前路径连续失败 2 次时，可以按同样确认门槛切到可用候选。默认每小时最多尝试修复 3 次。参数的单位、范围与后果都在工具 schema 中。

每次测量由 sourceDevice 的实际 companion 新建 SSH 连接并完成原有身份认证。中心到成员的管理连接耗时不会成为来源设备的候选延迟。可选 gatewayDevice 须在来源或目标集群声明，并且有新鲜、未达到容量门槛的原生负载数据。负载指连接/流配额使用率，不是 CPU 占用率。

手动改路、受管资源变更或撤权会阻止旧策略继续覆盖。检查原因后，以当前 expectedRevision 保存完整策略，才能明确接纳新的状态。

读取结果

ssh_cluster_inspect 的 section 可选 clusters、policies、jobs、events、history。后面三类默认返回最近 30 条，可通过 limit 调整，最多 256 条。权威存储会按容量淘汰旧历史和已结束任务；它不是无限日志归档。

状态/数值	含义
`healthy`	节点 runtime 和配置匹配，已配置探测有新鲜成功样本
`degraded`	有新鲜的探测失败或超时
`observation_failed`	执行器本轮无法检查成员；详细错误保留，不直接推断物理设备已关机
`configuration_unloaded`	检查到配置，但目标 runtime 尚未加载对应版本
`unknown` / `stale`	尚无足够样本或观测已过期；不会继续作为健康候选
`rttUs`、P50/P95、抖动	微秒；1000 微秒 = 1 毫秒。TCP 建连、P2P 应用 Ping、转发建连和 SSH 认证耗时分别标注
`failureRatePercent`	窗口内应用探测的失败/超时比例，不是物理网络丢包率
`atMs`、`receivedAtMs`	毫秒时间戳，分别保留测量/接收时间；成员时钟明显偏差会使状态过期

原生窗口最多 60 个样本，每节点最多 16 个探测、2 个同时进行的探测。修改目标或相关 P2P 配置会重建窗口，旧任务的迟到结果不能混入新窗口。

后台运行与退役

启用的任务使其指定 companion 在 MCP 前台退出后继续运行。要跨系统重启启动 companion，仍须用 ssh_node_manage(server="@local", action="startup", startup="login" 或 "boot") 配置系统监督；作用域与所需权限由工具返回。

停止 daemon 或失去中心连接后不启动新的写入。任务带 180 秒租约、执行者和尝试 ID；运行中每 20 秒续租。纯观测租约到期后可重新排队。执行中的路由修改结果不明时记为 unknown，只核对已保存的 route plan 回执；不会重放命令或盲目再次 apply。未开始且已经过期的计划可以确认为 not_started，其他无法核实的结果保留待处理。

退役顺序是停用引用策略，等待在途任务结束或核对未知回执，停用集群并等待 appliedRevision == revision，再解除策略、子集群和设备引用后删除。只清除 cluster:<id> 拥有的探测，保留节点其他配置和服务。

持续目录同步、外部通知、通用远程 shell 任务不由这组工具提供。

下载 SSHMCP 工具参数