内容
# agent-ops
> 面向 AI 代理和人类操作员的 Linux 主机安全基础设施 — 通过 rmux 实现的持久终端会话，全链路审计日志，MCP 原生接口适用于 AI 客户端，CLI PTY 直连适用于人类操作员，支持文件传输和多主机编排。
[中文文档](README.zh.md)
## 为什么选择 agent-ops？
AI 代理已经从“为人类生成命令”演变为**自主操作终端** — 部署服务、诊断故障、运行长时间构建和训练作业，所有这些都无需人工干预。但是，传统的终端工具（SSH、tmux）是为人类交互设计的，而不是面向编程 API 调用。agent-ops 建立在 **rmux** 之上，将终端会话从人类界面转变为 AI 代理（通过 MCP）和人类操作员（通过 CLI PTY 直连）的可编程资源，并在其上提供了三个生产级层。
在原型 AI 代理和生产部署之间存在三个问题，而现有工具（普通的 SSH MCP 服务器、基本的 tmux 封装）很大程度上忽略了这些问题：
- **可靠性**：普通的 SSH 连接断开时会终止正在运行的进程 — 长运行任务会失败。传统的 tmux 自动化依赖于 `send-keys + sleep + grep`，其中任何时间偏移都可能破坏工作流程。
- **可审计性**：当 AI 在生产环境中操作服务器时，您必须跟踪 **谁在何时对哪台机器做了什么，结果如何**。大多数 SSH 工具完全缺乏内置的审计功能。
- **安全边界**：直接向 AI 客户端提供 SSH 密钥是一个巨大的攻击面。agent-ops 使用 Bridge 代理 + Token 身份验证 + TLS 加密，将服务器访问权限限制在目标主机 — 客户端（MCP 和 CLI）永远不会持有服务器凭证。
这三个层：**协议层**（适用于 AI 客户端的 MCP 标准接口 + 适用于人类操作员的 CLI PTY 直连），**管理层**（多主机注册、组/标签过滤、广播操作），和 **合规层**（涵盖 MCP 和 CLI 操作的结构化 SQLite 审计追踪，准备好进行操作跟踪）。它们一起填补了 AI 代理原型和生产就绪之间的基础设施空白。
### agent-ops 适用场景
agent-ops 不是 SSH 或 Ansible 的替代品 — 它是 **编排层**，为 AI 代理和人类提供了一个统一的接口来操作远程 Linux 主机：
| 层 | 角色 | 工具 |
|-------|------|------|
| **编排** | AI + 人类决策，终端访问，文件往返，跨主机上下文 | agent-ops (MCP + CLI) |
| **执行** | 声明式，可重复，幂等自动化 | Ansible（或原始 shell） |
| **传输** | 加密，可靠，持久连接 | agent-ops（QUIC） |
agent-ops 不关心终端中运行的内容 — 原始 shell 命令，Ansible playbook，构建脚本或交互式调试。它提供了 **持久会话 + 审计追踪 + 多主机编排**，而您则带来工具。
**一些模式：**
```
# 模式 1：AI 读取系统状态，做出决定，执行修复
AI 代理（通过 MCP）
→ exec: cat /proc/loadavg && df -h # 读取状态
→ AI 推理： "/var/log 磁盘已满"
→ exec: du -sh /var/log/* | sort -rh | head # 诊断
→ exec: journalctl --vacuum-size=500M # 修复
→ 审计追踪：每一步都记录在 SQLite 中
# 模式 2：人类通过 CLI 调查，同时 AI 协助
人类（通过 CLI PTY 直连）
→ agent-ops-cli connect tf01 # 与 AI 正在工作的同一个会话
→ vim /etc/nginx/nginx.conf # 人类在熟悉的工具中编辑
AI 代理（通过 MCP）
→ exec: nginx -t && systemctl reload nginx # AI 验证并应用
# 模式 3：人类或 AI 将复杂工作流委托给 Ansible
AI/人类（通过 MCP 或 CLI）
→ exec: git clone ansible-playbook-repo
→ exec: ansible-playbook -i inventory deploy.yml
→ 审计追踪：谁在何时在哪些主机上运行了哪个 playbook
```
**用例：**
- **事件响应**：AI 或人类跳转到实时会话，读取系统状态，诊断根本原因，并执行修复 — 所有操作都在同一个持久终端中
- **临时操作**：跨多个主机快速执行一次性命令（`batch_exec`），文件传输，端口转发 — 无需 Playbook
- **交互式调试**：持久会话用于构建，长时间运行任务监控或通过 MCP（AI）和 CLI PTY 直连（人类）进行交互式故障排除
- **委托自动化**：使用 agent-ops 调用 Ansible，Terraform 或任何 CLI 工具 — agent-ops 提供安全隧道和审计追踪，工具提供逻辑
- **合规审计**：涵盖 AI 和人类在每个主机上的操作的完整审计追踪，可通过 `agent-ops-mcp audit query` 查询
## 架构
```mermaid
graph LR
A[AI 客户端] <-->|MCP stdio| B[agent-ops-mcp<br/>macOS/Linux/Windows]
H[人类] <-->|PTY 直连| E[agent-ops-cli<br/>macOS/Linux]
B <-->|QUIC :9778<br/>终端操作 + 文件传输| C[rmux-bridge<br/>Linux 主机]
E <-->|QUIC :9778<br/>终端附加| C
C <-->|Unix 套接字| D[RMUX 守护进程<br/>基于 rmux]
```
- **agent-ops-mcp** — 与 AI 客户端一起运行的 MCP 服务器，提供 62 种终端控制工具 + 审计 CLI
- **agent-ops-cli** — 人类操作员直接附加到远程 rmux 会话的 CLI 工具，通过 PTY 直连（`agent-ops-cli connect`），支持 vim/htop/TUI
- **rmux-bridge** — 在每个目标 Linux 主机上部署的 QUIC 加密代理，将 JSON 请求转换为 RMUX 守护进程调用
- **RMUX 守护进程** — 每个 Linux 主机上的终端多路复用器（基于 rmux）
**组件依赖关系：**
| 组件 | 运行于 | 依赖于 |
|-----------|---------|------------|
| `agent-ops-mcp` | AI 客户端机器（macOS/Linux/Windows） | 无 — 仅限二进制文件 |
| `agent-ops-cli` | 人类操作员机器（macOS/Linux） | 无 — 仅限二进制文件 |
| `rmux-bridge` | 每个目标 Linux 主机 | **RMUX 守护进程** (`curl -fsSL https://rmux.io/install.sh \| sh`) |
| RMUX 守护进程 | 每个目标 Linux 主机 | rmux（需要安装） |
> 💡 桥接器在部署期间自动检测 RMUX 套接字路径。无需手动配置。
## 功能
| 功能 | 描述 |
|---------|-------------|
| **交互式终端** | `agent-ops-cli connect` CLI 命令 — PTY 直连到远程 rmux 会话，支持 vim/htop/TUI |
| **会话管理** | 创建/销毁/列出会话，多窗格分割，窗口布局 |
| **命令执行** | `exec` 一次性执行（哨兵检测 + 退出代码），通过 send_keys + capture_pane 进行交互式程序 |
| **输出等待** | `wait_for_text` 用于终端文本，`wait_exit` 用于进程退出 |
| **文件传输** | 通过 QUIC 上传/下载，递归目录上传和下载，并发 |
| **端口转发** | 通过 QUIC 的本地端口转发隧道，用于访问远程内部服务 |
| **多主机编排** | 主机注册，组/标签/标签过滤，多窗格的 broadcast_keys |
| **审计日志** | SQLite 审计日志，记录每个工具调用，CLI 查询/统计/清理 |
| **终端状态感知** | `capture_pane`，`exec`，`wait_for_text`，`wait_stable`，`pane_info` 返回 `terminal_state`（就绪/运行/编辑器/分页器/密码/...）和光标位置，以便 AI 代理了解终端当前正在执行的操作 |
| **执行安全检查** | `exec` 在终端不处于 `ready` 状态时拒绝执行（例如，在 vim、less、密码提示中），返回 `refused: true` 并提供可行的指导，以防止命令注入 |
## 快速入门
### 构建
```bash
# 原生构建（macOS 开发）
cargo build -p agent-ops-mcp --release
cargo build -p agent-ops-cli --release
# 交叉编译桥接器适用于 Linux x86_64（静态）
just release-linux
```
### 部署
```bash
# 步骤 1：部署 rmux 守护进程（在远程主机上）
bash deploy/install-daemon.sh root@<your-bridge-ip>
# 步骤 2：编译并部署桥接器（一次性）
just release-linux
just deploy host=root@<your-bridge-ip> token=<your-token>
```
### 主机注册
创建 `config/hosts.yaml`（参见 `config/hosts.example.yaml`）：
```yaml
hosts:
- name: prod-web-01
bridge_addr: 10.0.1.10:9778
bridge_token: "your-token-here"
group: production
tags: [web, nginx]
labels:
dc: shanghai
```
> 💡 **热重载**：编辑 `hosts.yaml` 后，无需重启 — 调用 `reload_config` MCP 工具或向 MCP 服务器进程发送 `kill -HUP <pid>`。
### MCP 服务器配置
编辑 `~/.config/opencode/opencode.json`（参见 `config/mcp-config.example.json`）：
```json
{
"mcp": {
"agent-ops": {
"type": "local",
"command": ["/path/to/agent-ops-mcp"],
"args": [
"--hosts-file", "/path/to/hosts.yaml",
"--ca-cert", "/path/to/ca.crt"
],
"enabled": true
}
}
}
```
> 使用 `ca.crt` 进行远程部署；使用 `bridge.crt` 进行本地自签名测试。
## 安全
| 模式 | 触发 | 级别 |
|------|---------|:---:|
| CA 验证 | `--ca-cert /path/to/ca.crt` | ✅ 服务器身份验证，防中间人攻击 |
| 拒绝 | 未提供 CA | 🔒 默认 |
**生产环境**：运行自己的 CA，颁发每桥接证书，MCP 服务器仅持有 CA 根。
**内置保护措施**：
- **路径遍历预防**：文件上传/下载拒绝包含 `..` 的路径
- **隧道目标白名单**：`hosts.yaml` 中的可选 `allowed_tunnel_targets` 限制端口转发目标（glob 模式）
- **执行安全检查**：`exec` 在终端不处于 `ready` 状态时拒绝执行（防止命令注入到 vim/less/密码提示中）
## 审计
```bash
# 最近的操作
agent-ops-mcp audit query --format table
# 特定主机上的命令
agent-ops-mcp audit query --host tf01 --action exec --since 2026-06-01
# 统计信息
agent-ops-mcp audit stats
# 手动清理
agent-ops-mcp audit cleanup --older-than 30
```
审计数据存储在 `~/.agent-ops/audit.db`，保留 90 天，最大 500 MB。
## 知识库（设计理念）
agent-ops 为每个操作生成详细的审计追踪，但原始审计日志回答了“发生了什么” — 而不是“为什么发生”或“下次如何修复”。本节概述了将操作经验转化为共享知识库的设计理念。实施故意留给用户，因为 **知识库后端是团队基础设施偏好的问题，而不是工具处方**。
### 问题
在 AI 驱动的故障排除会话后：
- **知识停留在本地**：诊断、根本原因和修复仅存在于聊天记录中。
- **没有共享**：其他团队成员无法搜索类似的过去事件。
- **手动开销**：编写事后总结或 wiki 条目需要几天后回忆上下文。
### 三层设计
```
┌─────────────┐ 会话活动 ┌──────────────────┐
│ agent-ops │ ─── 审计事件 ────→ │ 知识提取 │
│ (MCP) │ (SQLite) │ (AI 审查) │
└─────────────┘ │ 结构化条目 │
└────────┬─────────┘
│
┌──────────────────┐
│ 输出适配器 │
│ （用户定义） │
└───┬──┬──┬──┬────┘
│ │ │ │
ONES │ wiki GitBook ...
│
curl / git / webhook
```
#### 1. 收集（内置）
现有的 **审计系统** 记录每个 MCP 工具调用和 CLI 操作 — `exec`、`capture_pane`、`session_create`、`connect` 等 — 带有时间戳、主机、成功/失败和错误消息。无需更改。
#### 2. 提取（AI 驱动）
当用户明确触发“将此会话保存为知识”时，AI 会审查整个对话历史记录和该会话的审计追踪。它提取：
| 字段 | 来源 |
|-------|--------|
| 问题 | 用户的初始报告、错误输出 |
| 诊断路径 | `exec` / `capture_pane` 调用序列 |
| 根本原因 | 修复前的最终发现 |
| 解决方案 | 解决问题的命令或配置更改 |
| 受影响的主机/标签 | 来自审计事件元数据 |
输出是一个 **结构化 JSON 条目**，而不是 Markdown 文件 — 因此输出适配器可以将其转换为任何格式。
#### 3. 输出（用户定义）
我们故意 **不** 构建特定于平台的集成。相反，用户定义一个 **接收器** — 一个脚本、命令或 webhook，它通过 `stdin`（JSON）接收知识条目。示例：
```bash
# ~/.agent-ops/sink.sh — 推送到 ONES wiki
curl -X POST "https://ones.example.com/wiki/api" \
-H "Authorization: Bearer $TOKEN" \
-d "$(cat)"
```
```bash
# 推送到基于 git 的知识仓库
echo "$(cat)" >> knowledge.jsonl && git commit -am "add troubleshooting entry"
```
### 设计原则
- **用户决定何时**: 知识提取明确触发，而不是自动 — 避免不完整的会话产生噪音条目。
- **用户决定哪里**: 没有平台锁定。接收器是团队已经使用的 CLI/API。
- **用户审查后发布**: AI 生成的条目应在推送到共享存储前由用户审查和编辑。
- **JSON 作为交换**: 结构化数据可以转换为 Markdown、API 负载、数据库行等。
此设计使 agent-ops 专注于操作，同时允许团队在其生成的审计数据之上构建自己的知识管道。
## 工具
62 个 MCP 工具涵盖整个终端生命周期，加上 `audit query/stats/cleanup` 人类操作员的 CLI 子命令：
| 类别 | 工具 |
|----------|-------|
| 主机 | `host_list`、`host_filter`、`reload_config` |
| 会话 | `session_create`、`session_list`、`session_attach`、`session_detach`、`kill_session` |
| 输入 | `send_keys`、`send_text`、`broadcast_keys` |
| 输出 | `capture_pane`、`capture_region`、`wait_for_text`、`wait_for_bytes`、`find_pane_text`、`find_text_all`、`stream_pane` |
| 执行 | `exec`、`wait_exit`、`wait_stable`、`collect_until_exit`、`spawn_command`、`shell_command`、`respawn_pane`、`cmd_escape` |
| 窗格 | `split_pane`、`split_pane_with`、`break_pane`、`join_pane`、`swap_pane`、`resize_pane`、`set_pane_title`、`get_pane_title`、`clear_history`、`close_pane`、`pane_info`、`pane_exists` |
| 窗口 | `split_window`、`close_window`、`rename_window`、`resize_window`、`select_window`、`select_layout`、`window_info`、`list_window_panes` |
| 发现 | `find_panes`、`find_sessions`、`get_pane_by_title`、`host_capabilities` |
| 缓冲区 | `list_buffers`、`paste_buffer`、`delete_buffer` |
| 文件 | `file_upload`、`file_download` |
| 批处理 | `batch_exec`、`batch_upload`、`batch_download` |
| 隧道 | `tunnel_create`、`tunnel_list`、`tunnel_close` |
| 部署 | `deploy_bridge` |
> 💡 `stream_pane` 适用于长命令实时输出监控（阻塞读，增量返回），替代 capture_pane 轮询。
完整文档：[docs/TOOLS.md](docs/TOOLS.md)
## 开发
```bash
just check # cargo check --workspace
just test # cargo test --workspace
just fmt # cargo fmt --all
just lint # cargo clippy --workspace -- -D warnings
just build # cargo build --workspace
```
## 技术栈
- **语言**：Rust 1.85+（2021 版）
- **异步运行时**：tokio
- **TLS**：rustls（无 OpenSSL 依赖）
- **终端**：rmux-sdk
- **审计存储**：rusqlite（捆绑 SQLite）
- **MCP 传输**：stdio（JSON-RPC 2.0）
## 文档
- [工具参考](docs/TOOLS.md) — 62 个 MCP 工具，带有参数和返回值
- [部署指南](docs/DEPLOY.md) — 架构、构建、部署、操作、安全
- [贡献](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
- [变更日志](CHANGELOG.md)
## 许可证
MIT
