STACIO WIKI · 自动化指南

Stacio 自动化指南

1. 自动化能力边界

Stacio 当前提供的是“围绕已打开终端的受控自动化”，不是通用任务调度平台。

当前版本没有独立的 cron 式任务列表、定时触发器、日历触发器、守护任务编排或失败后定时补偿队列。需要定时执行时，应在明确审批后使用远端 cron/systemd timer 或 macOS launchd，并由对应系统负责权限、日志、告警和停用；Stacio 不会自动管理这些外部计划任务。

2. 自动化前的安全基线

任何自动化都应先回答：

1. 目标是哪个主机、账号、环境和运行时？
2. 输入是只读、普通写入、网络操作还是破坏性操作？
3. 多目标是否完全同构，还是存在版本、目录和权限差异？
4. 变更前是否有已验证备份？
5. 完成后用什么命令或业务请求验证？
6. 失败后如何停止、回滚和确认恢复？

自动化目标应使用完整端点核对，而不是只看会话别名：

上表是核对格式；保存会话时主机和端口仍然分开填写。会话名称可以重复或过时，runtime ID 在重连后也可能变化，所以每次批量或 Agent 操作都要重新确认当前端点。

生产环境不应把“命令已发送”“任务已入队”或“Agent 已完成”当作变更成功。完成必须有当前终端输出和专项验证证据。

3. 会话环境与 AI 策略

在新建会话或编辑会话的自动化区域可设置：

3.1 环境

环境标签是安全元数据，不会改变远端主机本身。复制、导入或重命名会话后必须重新核对，不能仅凭会话名称推断环境。

3.2 AI 执行策略

禁止模式优先；生产环境会强制保守审批；会话策略可比全局策略更严格。允许模式和风险分类无法证明命令语义绝对安全，尤其要检查管道、重定向、命令替换和包装脚本。

4. 连接后动作

4.1 三个字段的实际差异

Startup plan会明确显示 (not executed automatically)。它适合记录预期启动方式或供用户检查复制，但不能依赖它完成 cd、export、服务启动或部署。

只有连接脚本会自动执行，而且只作用于 SSH 终端。Serial、Telnet 和本地 Shell 不使用这条 SSH 注入路径。

4.2 配置连接脚本

1. 编辑 SSH 会话。
2. 在连接后动作 > 连接脚本输入一行或多行 Shell 内容。
3. 保存会话并重新连接。
4. 观察连接后的目录、提示符和命令结果。
5. 在视图 > 诊断检查失败信息。

只读示例：

cd /srv/app
pwd
git status --short --branch

Stacio 会在脚本末尾补换行并静默写入，尽量过滤脚本回显。脚本输出仍会进入当前终端。首次连接和后续重连都会重新进入就绪流程，因此脚本必须可以安全重复执行。

4.3 连接脚本设计原则

• 保持短小、可读、幂等；
• 优先切换目录、设置提示符和执行只读检查；
• 不自动部署、重启、删除、迁移数据库或修改防火墙；
• 不包含密码、Token、私钥口令或长期 secret；
• 不假设 Shell 类型、当前目录或 sudo 权限；
• 每一步失败时给出可见输出；
• 设计时考虑断线重连导致的重复执行。

连接脚本保存在会话配置中，不是凭据库。复制会话设置、查看本地数据库或诊断时应按敏感配置管理。

4.4 导入与连接脚本

从外部工具或普通 Stacio 配置导入会话时，自动执行字段不会被静默继承。导入后应手工审查并重新配置连接脚本，避免外部文件借导入路径执行命令。

5. MultiExec

MultiExec 受 License 控制，用于把键盘输入同步到多个已打开终端。

5.1 启动交互式 MultiExec

1. 先分别连接并验证至少两个终端，核对每个终端的 IP/域名、端口、账号和环境。
2. 点击工具栏多执行。
3. 在目标列表中按完整端点只勾选需要同步的终端，不要只按相似会话名称判断。
4. 若当前已经是多终端分屏，Stacio 可直接使用当前分屏目标。
5. 确认后，目标被放入一个 MultiExec 网格工作区。
6. 在任一未暂停 pane 中输入，内容会同步到其他未暂停目标。

当前可执行终端可能包含本地 Shell、SSH、Serial 或 Telnet。断开的远端终端不会成功接收输入。

5.2 暂停单个目标

每个远端 pane 可选择暂停此终端同步，暂停后：

• 该 pane 自己仍可接收用户直接输入；
• 其他 pane 的输入不会继续广播给它；
• 从暂停 pane 输入时，不会再广播到其他目标；
• 选择恢复此终端同步后重新加入同步。

暂停不是事务回滚。暂停前已发送的字符和命令仍可能正在远端执行。

5.3 生产环境注意事项

目标选择器会显示环境信息，但交互式 MultiExec 不会为每次按键或每条命令单独弹出审批。它是实时输入同步，而不是逐命令 Agent 执行链路。

生产使用时必须：

1. 先在单台非生产或 canary 主机验证命令；
2. 逐项核对目标列表中的 IP/域名、端口、账号和环境；
3. 首条命令使用 hostname、whoami、pwd 等只读身份检查，并与 Stacio 中的连接端点交叉核对；
4. 避免多行粘贴、交互式编辑器和依赖时序的命令；
5. 任何目标出现不同输出时立即暂停广播；
6. 变更操作按目标分别验证，不能用一个成功输出代表全部目标。

5.4 退出 MultiExec

关闭 MultiExec 标签时，原终端可恢复为独立标签。退出同步后应检查是否仍有目标在运行长命令，并记录部分成功、失败或未确认状态。

6. 宏

宏把实际提交过的终端命令记录到本地数据库，并按顺序回放到当前终端。

6.1 录制宏

1. 选择视图 > 宏或工具栏宏入口。
2. 点击开始录制。
3. 在本地或远程终端逐条提交命令。
4. 返回宏面板点击停止录制。
5. 输入宏名称并保存。

录制只保存实际提交的非空命令行，不保存普通光标移动或未提交文本。保存时会对常见凭据形式进行脱敏，但仍不应在终端命令中输入 secret。

6.2 管理宏

宏面板支持：

• 按名称或命令搜索；
• 按分组过滤和分组；
• 重命名和删除；
• 导入和导出；
• 查看命令数量和更新时间；
• 开启或关闭运行前确认。

导入宏后，在任何生产回放前逐条审查。宏文件是可执行内容，不应因为来源是同事或旧机器就直接信任。

6.3 回放宏

1. 先选中目标终端。
2. 在宏面板选择一条宏。
3. 检查运行预览并点击回放。
4. 若检测到破坏性命令，Stacio 会再次警告。
5. 观察每一步输出，并在结束后执行专项验证。

宏按保存顺序发送，每步默认间隔约 300 ms；它不会等待上一条命令完成。不要用宏串联耗时部署、需要交互输入、依赖前一步成功或必须串行提交的数据库变更。

7. AI 助手

7.1 配置模型

在Stacio > 设置 > AI 与执行中：

1. 添加或选择模型供应商；
2. 填写 Base URL、模型和 API Key；
3. 测试连接并拉取模型列表；
4. 配置终端上下文长度；
5. 选择命令确认和执行方式；
6. 按需设置自动放行与禁止模式。

支持的模型接口采用 OpenAI-compatible 通道。API Key 写入 Stacio 本地凭据库；模型列表和普通配置保存在本机设置中。

7.2 使用排查助手

1. 选择正确的当前终端。
2. 打开视图 > AI 助手。
3. 在目标选择器中核对终端、目录和环境。
4. 选择规则建议或模型推理。
5. 输入具体问题，优先要求只读检查和证据。
6. 检查命令卡中的目标、命令、风险和解释。
7. 批准、编辑、跳过或拒绝命令。
8. 根据终端真实输出判断结果。

启用“附带最近终端输出”时，请求会包含受字符上限控制的近期终端上下文。发送前避免让终端显示凭据、客户数据或不必要的完整日志。

7.3 变更任务

排查助手的受控编排会要求：

• 变更前备份；
• 验证备份位置和可读性；
• 执行最小变更；
• 变更后专项验证；
• 失败时组织回滚；
• 最终报告包含备份、验证和回滚信息。

这些门槛降低风险，但不能替代最小权限、人工审批、灾难恢复和业务负责人确认。

8. 本地 Agent

AI 面板的本地 Agent 模式可检测并启动 Codex、Claude、OpenCode、MiMo Code、ZCode 或 Qwen Code 等本机工具。每个工具在独立本地工作区运行，并获得当前终端、远程目录和统一操作契约。

8.1 启动

1. 在 Mac 上安装目标 Agent CLI，并确保 Stacio 能在 PATH 或常见安装路径找到它。
2. 选中要操作的远端终端。
3. 打开 AI 面板并切换到本地 Agent。
4. 从工具菜单选择已安装的 Agent。
5. 检查状态栏中的可执行文件和远程桥目标。
6. 在原生 Agent 会话中提出任务。

找不到命令时，Stacio 会显示“未检测到”或缺少可执行文件。先确认 CLI 本身能在本地 Shell 启动，再重新创建 Agent 会话。

8.2 工作区工具

本地 Agent 工作区通常会提供：

• stacio-sessions：列出可用终端；
• stacio-remote "命令"：通过 Agent Bridge 在远端执行；
• stacio-agent：访问底层 Bridge 子命令；
• AGENTS.md、CLAUDE.md、QWEN.md 或通用说明文件。

这些包装命令属于 Stacio 生成的 Agent 工作区，不保证是系统全局命令。本地 Shell 操作只发生在 Mac；远端操作应通过 Bridge，才能继续经过目标选择、审批和审计。

8.3 控制边界

Stacio 可以对通过 Agent Bridge 发出的远端命令执行风险识别、审批和审计，但不能保证第三方 CLI 的所有内部文件操作、网络请求或推理过程都受同一状态机强制。备份、验证、回滚和最终报告对本地 Agent 主要通过工作区操作契约约束。

详细说明见Agent 能力与安全保障。

9. Agent Bridge CLI

Stacio 安装包包含本地 helper stacio。主应用运行时会启动一个仅限本机的 Unix Domain Socket；Socket 路径可在设置 > AI 与执行 > Agent Bridge查看和复制。

9.1 列出目标

stacio agent sessions
stacio agent sessions --json

先获取当前 runtime ID，再执行后续命令。不要复用旧运行时 ID；终端重连后 ID 可能变化。

9.2 执行命令

stacio agent run --runtime <runtimeID> --command "uptime" --follow

也可显式指定当前终端或保存会话：

stacio agent run --target current --command "whoami"
stacio agent run --session <sessionID> --command "pwd" --follow

--follow持续输出状态事件，直到完成、失败、取消、暂停或接管。--json适合由其他本机程序解析；不要用字符串匹配代替 JSON 状态解析。

9.3 暂停、取消与接管

从事件流记录 request ID，再执行：

stacio agent pause --request <requestID>
stacio agent cancel --request <requestID>
stacio agent takeover --request <requestID>

• 暂停：停止 Agent 继续推进，保留当前任务状态；
• 取消：结束可取消的独立任务；
• 接管：把控制交还用户终端。

控制事件返回成功只说明 Stacio 接受了控制请求；仍要检查远端进程是否已经停止或是否需要人工清理。

9.4 Socket 覆盖

默认 Socket 在当前用户的 Stacio Application Support 目录。特殊调试可使用：

stacio agent --socket /path/to/agent-bridge.sock sessions

或设置 STACIO_AGENT_SOCKET。不要把 Socket 暴露给其他用户、网络共享或容器。主应用未运行、Socket 已过期或路径不匹配时，CLI 会报告 Agent Bridge 未连接。

10. 审批、风险与审计

10.1 风险分类

AI 和 Bridge 命令会按只读、写入、网络和破坏性风险进行分类。最终是否执行还会综合：

• 全局命令确认策略；
• 会话环境；
• 单会话 AI 策略；
• 自动放行模式；
• 禁止模式；
• 用户在审批条中的决定。

禁止模式优先于自动放行；生产和每条确认策略会提高审批要求。

10.2 审计记录

选择视图 > 诊断可查看：

• MultiExec 广播审计；
• AI/Agent 请求和执行状态；
• request ID、runtime、目标数量和发送结果；
• 已脱敏命令摘要；
• 应用日志和导入报告。

诊断导出条数和是否包含应用日志由设置 > 安全控制。审计用于追踪，不是完整终端录像，也不能代替远端系统日志。

11. 推荐工作流

11.1 多主机只读巡检

1. 分别打开目标终端，记录 Stacio 显示的 IP/域名、端口和账号。
2. 执行 hostname、whoami 和 pwd，与连接端点及环境标记交叉核对。
3. 启动 MultiExec。
4. 广播 whoami、uptime、df -h 等只读命令。
5. 任一输出不一致时暂停对应目标。
6. 按主机记录结果，不合并成一个模糊结论。

11.2 连接后定位项目目录

1. 把会话启动命令写成说明性计划。
2. 把实际自动动作限制在短连接脚本中。
3. 使用 cd、pwd 和只读状态命令。
4. 断线重连后确认脚本重复执行仍安全。

11.3 AI 辅助变更

1. 先要求 AI 只读诊断。
2. 明确变更目标和完成标准。
3. 检查备份命令和位置。
4. 每个写命令单独审批。
5. 观察真实终端输出。
6. 执行配置检查、服务状态、端口和业务请求验证。
7. 验证失败立即停止并回滚。

12. 不适合自动化的操作

以下任务不应直接使用连接脚本、交互式 MultiExec 或固定间隔宏：

• 不同版本或拓扑的多台生产主机批量变更；
• 需要等待上一步完成的数据库迁移；
• 需要交互确认、OTP 或人工判断的命令；
• 大范围删除、权限递归修改和防火墙重写；
• 没有备份、回滚或专项验证的部署；
• 依赖无人值守定时触发的关键任务。

这类任务应使用具备幂等、状态检查、重试边界、密钥管理和集中日志的专用自动化系统，并通过 Stacio 做人工验证或受控排障。

13. 常见问题

14. 完成标准

自动化任务只有在以下条件满足后才算完成：

• 目标、环境和账号已确认；
• 实际执行命令与批准内容一致；
• 每个目标都有终端输出或明确失败状态；
• 变更前备份已验证；
• 变更后专项检查通过；
• 部分成功、取消、暂停和未验证项已明确记录；
• 回滚方法可执行；
• 不再需要的 MultiExec、Agent、隧道或外部计划任务已停止。

安全策略详见安全与治理，运维验证详见远程运维。