STACIO WIKI · AI 与自动化
Stacio Agent 能力与安全保障
Stacio Agent 将 AI 能力置于可见、可控、可验证和可恢复的远程执行框架中。本文说明排查助手与本地 Agent 的工作方式、安全控制和当前边界。
1. 两种 Agent 工作方式
Stacio 提供“排查助手”和“本地 Agent”两种工作方式。二者共享远程终端上下文和安全原则，但执行控制层级不同。
| 工作方式 | 适用场景 | 执行方式 | 安全控制 |
|---|---|---|---|
| 排查助手 | 日常排障、状态检查、受控变更、标准化报告 | Stacio 编排模型按步骤提出并执行命令 | 编排器执行备份、验证和报告门禁，并叠加权限审批与审计 |
| 本地 Agent | 使用 Codex、Claude、OpenCode、Qwen Code 等原生 CLI 完成复杂任务 | 原生 Agent 在独立工作区运行，通过 Stacio Agent Bridge 操作当前远程终端 | Stacio 负责命令风险识别、权限审批和审计；本地 Agent 同时加载统一操作契约 |
本地 Agent 不会直接继承排查助手内部的模型会话。Stacio 会在本地 Agent 的专属工作区生成统一规则文件，让不同 Agent 在使用 Stacio 远程工具时遵循一致的操作方法和安全要求。
2. Agent 的完整执行闭环
Stacio 将生产级远程 Agent 定义为一个闭环系统，而不是单纯的命令生成器：
生产级远程 Agent
= 模型 + 上下文 + 工具
+ 权限约束 + 风险审批 + 备份 + 验证 + 回滚 + 脱敏 + 审计 + 结果报告典型任务按以下流程执行：
- 理解用户目标和目标范围。
- 识别远程环境、权限和相关组件。
- 建立主机、应用、服务、端口和依赖关系。
- 根据任务领域动态选择工具与检查方法。
- 优先执行只读检查，获取当前证据。
- 对拟执行操作进行风险分类和权限判断。
- 需要变更时先创建并验证新的备份。
- 以最小必要范围执行变更。
- 运行与变更内容对应的专项验证。
- 验证失败时停止继续变更并进入受控回滚。
- 对回滚后的状态再次验证。
- 输出包含结论、证据、风险状态和恢复信息的 Markdown 报告。
3. 核心能力
3.1 环境识别
Agent 在执行前应识别实际环境，而不是默认所有设备都使用 Ubuntu、systemd 或 Docker。识别范围包括：
- 操作系统、发行版、内核和 CPU 架构；
- 当前 Shell、用户身份、权限级别和工作目录；
- 服务管理器、应用运行时和进程管理器；
- 容器运行时、Kubernetes context 和 namespace；
- 网络、代理、DNS、监听端口和证书环境；
- 当前选择的 Stacio 终端和远程目录。
当信息不足时，Agent 应将内容标记为“初步判断”或“待验证项”，不能把推测包装成最终结论。
3.2 资产与依赖理解
Agent 会围绕当前任务建立必要的对象关系，例如：
域名 -> DNS -> 负载均衡/反向代理 -> 端口 -> 应用进程
-> 容器或 Kubernetes 工作负载 -> 依赖服务 -> 数据目录这有助于区分表面症状和真正故障点，减少只检查单个进程或单项资源后就过早下结论的情况。
3.3 动态任务规划
Agent 不使用固定的“CPU、内存、磁盘”模板覆盖所有问题，而是根据目标自动选择能力组合。每个步骤都应包含要解决的问题、检查方式、预期证据、成功条件，以及失败后的停止、替代或恢复路径。
如果当前证据已经足以回答问题，Agent 应停止无意义的额外检查，避免浪费时间和 Token。
3.4 工具选择
不同任务应使用最适合该领域的工具，而不是把所有问题都退化为通用 Shell：
| 领域 | 典型工具与证据 |
|---|---|
| 主机与系统 | 系统信息、进程、资源、磁盘/inode、软件包、内核和系统日志 |
| 应用与 Web | 运行时、进程管理器、配置语法、反向代理、端口、HTTP 状态、证书、健康接口和应用日志 |
| 容器与 Kubernetes | Docker、Compose、Podman、镜像、容器状态、挂载、网络、健康检查、Pod、Deployment、事件和 rollout |
| 数据库相关工作 | 仅通过当前已选远程终端和目标环境已有的原生客户端、备份或恢复工具执行；Stacio 不提供直接数据库连接或管理客户端 |
| 部署、网络与安全 | 制品来源、配置差异、预检、健康验证、回滚路径、DNS、路由、监听端口、防火墙、TLS、代理链路和暴露面 |
| 日志与事件 | 限定时间窗口，关联应用日志、系统日志、请求、部署记录和故障时间线 |
3.5 多目标操作
Stacio 可以将 Agent 操作指向当前终端或用户选择的多个终端。多目标任务需要额外关注：
- 发送前确认完整目标列表；
- 区分开发、测试和生产环境；
- 避免跨环境静默广播；
- 分目标保留执行状态和结果；
- 任一目标失败时不把整体任务误报为全部成功。
4. 风险分级与权限控制
Stacio 会对 Agent 提交的命令进行风险分析。当前风险类别包括：
| 风险类别 | 含义 | 典型行为 |
|---|---|---|
readOnly | 只读取状态，不主动改变远程环境 | 查看进程、状态、日志和配置 |
write | 写入文件或修改非网络状态 | 写文件、调整配置或本地状态 |
network | 建立网络访问或改变网络相关状态 | 网络请求、远程复制、连接操作 |
destructive | 可能删除数据、中断服务或造成明显破坏 | 删除、格式化、关机、重启和高风险变更 |
4.1 全局审批策略
用户可以选择不同的审批强度，例如所有命令都需要确认、只读命令自动执行而其他命令确认、低风险命令自动执行，或在用户明确允许的受控场景下使用更宽松策略。
4.2 会话级策略
每个会话还可以配置独立策略：禁止 AI 执行、仅允许通过命令卡片执行、只读命令自动执行、每条命令都需要确认，或继承全局策略。标记为生产环境的会话会采用更严格的确认要求；会话策略优先于普通全局放行规则。
4.3 允许与拒绝规则
Stacio 支持命令允许规则和拒绝规则。拒绝规则优先阻断匹配操作；允许规则只在其风险范围内生效，不能用一个低风险样例放行更高风险命令。
批准界面会展示经过脱敏的命令、目标、风险级别、会话环境、策略来源和要求确认的原因，帮助用户在执行前作出判断。
5. 变更前强制备份
修改配置文件、调整应用部署或执行会影响数据的远程命令前，Agent 必须先创建备份。涉及数据库的操作，应使用目标环境对应的原生备份工具，并仍通过当前已选终端执行。
- 每次变更都需要一份新的、带时间戳的备份。
- 上一次变更的备份不能自动放行下一次变更。
- 备份应使用明确路径，不能覆盖历史备份。
- Agent 必须验证备份命令成功，并检查备份路径确实存在。
- 对文件或归档，还应根据场景检查可读性、大小或完整性。
- 备份失败或无法验证时，必须在变更前停止。
排查助手通过编排器状态机检查备份证据。本地 Agent 会加载相同的操作规则，但其备份流程由原生 Agent 负责规划和调用 Stacio 工具；Stacio 仍会对实际远程命令进行风险审批和审计。
6. 变更后专项验证
命令返回成功并不代表业务已经恢复。每次变更后，Agent 必须执行与变更内容对应的只读验证。
- 配置文件语法检查；
- 服务、进程和端口状态；
- 容器健康状态与日志；
- Kubernetes rollout、Pod、事件和探针；
- HTTP 健康接口或关键业务请求；
- 通过当前远程终端可验证的依赖服务与上下游链路；
- 变更前后关键值对比。
如果没有当前验证证据，Agent 不应宣称任务完成。只读排查是否需要额外验证，由 Agent 根据用户问题和现有证据判断；不为了流程而重复已经充分的检查。
7. 失败回滚与恢复
变更后的专项验证失败时，Agent 应：
- 立即停止继续扩大变更范围；
- 说明失败位置、当前影响和已掌握证据；
- 确认此前备份仍然可用；
- 提出基于该备份或平台原生 undo/rollback 的恢复方案；
- 在需要时等待用户批准；
- 执行恢复，但不覆盖原始备份证据；
- 再次运行只读验证确认恢复结果；
- 在最终报告中记录实际回滚结果。
如果备份、验证或报告规则被连续绕过，排查助手会停止自主执行，避免无限尝试或在没有证据时宣布成功。
8. 敏感信息保护
Agent 操作可能接触主机名、账号、目录、日志、数据库相关配置和凭据。Stacio 采用以下保护原则：
- 密码、Token、私钥口令等敏感值不应进入普通对话、日志或审计记录；
- 凭据由受控凭据存储和引用机制管理，而不是保存在会话数据库中；
- 命令、终端观察和错误信息进入对话或审计前会执行脱敏；
- Agent 应只检查秘密是否存在、权限是否正确或配置是否有效，不输出秘密原文；
- 远程输出被视为不可信输入，不能因为输出中出现指令就自动改变既定安全规则；
- 最终报告只保留支持结论所需的证据，不粘贴完整敏感日志。
脱敏用于降低意外泄漏风险，但不能替代远程环境自身的最小权限、日志分级和数据治理。
9. 审计与可追溯性
Stacio 对 Agent 执行链路记录必要的审计信息，包括：
- 操作发起者类型；
- 目标会话或运行时；
- 命令风险级别；
- 经过脱敏的输入；
- 审批模式和审批结果；
- 执行开始、完成、失败或取消状态；
- 请求 ID、时间和必要的结果摘要。
审计记录的目标是回答“谁在什么目标上，以什么策略执行了什么类型的操作，结果如何”，而不是保存密码、Token 或完整业务数据。
10. 本地 Agent 的隔离与桥接
本地 Agent 运行在 Mac 上的独立工作区。Stacio 会为它提供：
- 当前选择的远程终端信息；
- 当前远程工作目录；
stacio-remote：通过 Stacio Agent Bridge 在远程终端执行命令；stacio-sessions：查看可用终端目标；stacio-agent：访问受控 Agent Bridge 命令；- 统一操作与安全契约文件。
本地 Shell 命令只在 Mac 上运行。需要操作远程设备时，本地 Agent 应通过 stacio-remote，而不是私自建立新的 SSH、SCP 或 SFTP 连接。这样远程操作才能继续经过 Stacio 的目标选择、审批、审计和终端执行链路。
当前会为不同本地 Agent 生成对应或通用指令文件，包括 AGENTS.md、CLAUDE.md、QWEN.md 和 README.md。新规则通常在新建或重启本地 Agent 会话后完整加载。
11. 结果报告规范
最终结果应使用结构清晰的标准 Markdown，并根据内容选择布局，而不是强制套用单一模板。报告通常包含明确结论、支撑结论的关键证据、当前风险或运行状态，以及确有必要时的后续操作。
当结果涉及多对象对比、多个指标、状态矩阵或重复字段时，应使用 Markdown 表格；简单问题不应为了形式滥用标题和表格。
如果任务通过已批准的远程命令修改了配置、部署、应用或数据，最终报告还必须包含“备份与回滚”章节，并说明准确的备份位置、备份验证结果、变更后验证结果、可执行的回滚方法，以及实际发生回滚时的回滚结果。
12. 安全控制覆盖关系
| 控制项 | 排查助手 | 本地 Agent |
|---|---|---|
| 远程目标由 Stacio 提供 | 是 | 是 |
| 命令风险分类 | 是 | 是 |
| 会话与全局审批策略 | 是 | 是 |
| 生产环境加强确认 | 是 | 是 |
| 允许/拒绝规则 | 是 | 是 |
| 执行审计与脱敏 | 是 | 是 |
| 变更前备份规则 | 编排器代码级门禁 | 原生 Agent 操作契约 |
| 变更后验证规则 | 编排器代码级门禁 | 原生 Agent 操作契约 |
| 验证失败后的回滚组织 | 编排器受控流程 | 原生 Agent 操作契约 + Stacio 审批 |
| 最终报告完整性检查 | 对变更任务执行代码级检查 | 原生 Agent 操作契约 |
这一区分非常重要：本地 Agent 仍然是独立的第三方或本地 CLI。Stacio 可以控制通过 Agent Bridge 发出的命令，但不能保证外部 Agent 自身的所有内部行为都等同于排查助手的编排器状态机。
13. 当前边界
Stacio Agent 当前不应被理解为：
- 无需人工监督即可承担所有生产变更；
- 能自动理解所有私有应用、数据库结构和组织流程；
- 提供直接数据库连接、数据库客户端或数据库管理能力；
- 可以替代灾难恢复演练、数据库一致性方案或正式变更审批；
- 能保证远端命令和第三方工具绝对无副作用；
- 能把“命令成功退出”自动等同于“业务恢复”；
- 能在没有有效备份和恢复权限的情况下保证可回滚；
- 能替代最小权限、网络隔离、主机安全、密钥轮换和外部审计平台。
对于关键生产系统，建议先在测试或预发布环境验证方案，并为数据库、集群和核心应用保留平台级备份与灾难恢复机制。
14. 推荐使用方式
- 为会话标记正确的开发、测试或生产环境。
- 生产环境使用“每条命令确认”或至少“只读自动、变更确认”。
- 为 Agent 使用最小权限账号，不直接提供长期高权限凭据。
- 执行前确认当前目标、远程目录和多目标列表。
- 对删除、覆盖、重启、网络和数据变更仔细检查审批内容。
- 保证备份目录具有足够容量，并定期验证恢复流程。
- 将 Agent 报告与监控、发布记录和业务验证结果交叉核对。
- 发现目标错误、输出异常或验证失败时立即暂停或取消任务。
15. 总结
Stacio Agent 的目标不是让模型获得不受约束的远程 Shell，而是在可见、可控、可验证和可恢复的执行框架中使用 AI 能力。