klutch：命令边界与受控使用
说明批量执行、文件分发与镜像导入的实际职责，列明缺失入口、运行时选择与dry-run边界。
文档状态与使用前提
审阅日期：2026-09-08。本文对应 bin/VERSION:1 的 v1.0.0-dev 源码标记，未经本次执行或生产验证。先完成快速开始，准备获准目标组、控制机依赖、远端账号、非敏感测试材料和恢复负责人。以下是命令职责说明，不是可直接用于生产的安装或初始化操作清单。
已实现命令与判断方式
- list：从节点清单解析分组并输出节点。使用前确认清单只覆盖批准范围；不能把 -l 当成已实现详细模式。
- ssh：按并发限制运行远端命令，输出逐节点结果。使用前确认具体命令的副作用、账号与主机密钥策略。
- scp：推送或拉回文件，支持递归目录。使用前确认源与目标路径、覆盖风险及重复文件名。
- dist：建立临时 HTTP 文件服务并触发反向拉取。使用前确认目标到控制机网络、服务暴露目录和退出清理。
- image push/load：分发镜像包并用 ctr 或 Docker 导入。使用前确认目标运行时、namespace、包格式和独立校验。
- init system/check：调用系统准备与检查脚本。使用前审核每一项实际修改、安全基线与可逆性。
- install/start/stop/restart/status：调用模块对应动作脚本。使用前确认描述文件与动作脚本同时存在。
主路由见 bin/klutch:227，批量执行见 core/exec.go:55，镜像导入见 bin/klutch-loadimage:35。本表只说明代码职责，不能替代环境测试或授权。
目标清单与分批操作流程
先人工核对分组解析、角色、端口和身份，再由负责人选择隔离节点做最小验证。每批必须记录节点数量、命令正文、输入文件标识、目标路径、开始结束时间及退出状态。只读命令确认通过后，也不能自动升级到系统修改权限；下一阶段必须独立评审。
SSH 超时参数当前用于建连，未见完整远端执行截止控制，不应把它当作防止长任务挂起的保证。暂停推广时保留逐节点已完成/未完成清单，不能简单重跑整组，因为某些节点可能已经产生副作用。
文件与镜像传输流程
传输前用非敏感样例确认目录结构和覆盖行为，保存独立计算的文件清单与校验值。dist 会在控制机建立临时 HTTP 服务，目标通过 curl 或 wget 拉取；传输路径与可见目录必须经过安全评审，不得把包含凭据或备份秘密的父目录直接暴露。
镜像加载优先检查 ctr，其次 Docker；代码虽接受 --runtime，但并未强制按参数选择。先确认实际目标运行时与 containerd namespace，再由实施者决定是否授权导入。加载成功还需核对镜像身份及目标范围，不代表业务工作负载已经运行。目录递归及同名文件处理要单独测试，不默认保留全部层级或自动去重。
尚未完成的入口与错误恢复
当前没有可用的 klutch-image 路由目标，不能依赖 image list/diff/rm/prune/inspect。主入口未路由 uninstall，即使内部框架或 README 提到，也不能作为已支持命令发布。config 当前接受 hosts 或 env.sh，不应照抄未实现的别名。HTML 等报告格式、断点恢复和统一失败重试没有形成完整链路证据。
遇到未知命令或缺少动作脚本，应返回能力清单确认，不临时复制不明脚本补齐。传输失败先确定成功节点与部分文件，暂停自动导入，区分网络、路径、空间与权限问题；清理前验证文件归属，不删除共享镜像或业务目录。
验收与风险控制
验收必须逐节点记录解析范围、远端身份、命令返回、样例完整性和临时服务清理结果。系统准备或模块动作只有在独立审批后才能进入测试，不能以 dry-run 输出作为生产放行依据：bin/klutch-install:123 仍强制上传和执行。默认 SSH 主机密钥策略、无认证 HTTP 服务和系统安全项修改都需单独纠偏或限制环境。
出现越界目标、秘密暴露、未知安装包、部分执行状态不明或无法确认回退点时立即停止推广。对于需要 kubeadm init/join、升级或控制面恢复的需求，应选择另行评审的集群生命周期方案，不通过任意 SSH 拼接扩张本工具的已验证范围。