内容
# runbook-exec
[](https://pypi.org/project/runbook-exec/)
> **状态**: v0.2.2 — 测试版。MCP 服务器适用于 Claude Desktop，markdown-fence 修复，Slack 终端备用，Windows 文档。
AI 驱动的 CLI 工具，将被动的 Markdown 运行手册转换为可执行的自动化，具有安全门控和审计追踪。
在事件发生时（例如凌晨 3 点），而不是由人工手动逐步骤执行运行手册，`runbook-exec` 读取 Markdown 运行手册，使用 Claude 将每个步骤按风险级别分类，自动执行安全的步骤，通过 Slack 请求人工批准高风险操作，并生成防篡改审计日志。
## 快速入门
### 1. 安装
```bash
pip install runbook-exec
```
### Windows 用户
在 Windows 上，请始终在虚拟环境中安装，以确保 `runbook-exec` 命令在您的 PATH 中可用：
```cmd
python -m venv venv
venv\Scripts\activate
pip install runbook-exec
runbook-exec --help
```
如果您看到 `'runbook-exec' is not recognized as an internal or external command`，则表示您不在活动虚拟环境中。请先运行 `venv\Scripts\activate`。
### 免费的Anthropic积分
新的Anthropic账户在 [console.anthropic.com](https://console.anthropic.com) 获得 5 美元的免费积分 — 足以运行数百次 `runbook-exec validate`。
### 2. 设置环境变量
**Linux / macOS:**
```bash
export ANTHROPIC_API_KEY=sk-ant-... # 必需
export SLACK_BOT_TOKEN=xoxb-... # 审批工作流所需
export SLACK_APP_TOKEN=xapp-... # Socket 模式所需
```
**Windows CMD:**
```cmd
set ANTHROPIC_API_KEY=sk-ant-...
set SLACK_BOT_TOKEN=xoxb-...
set SLACK_APP_TOKEN=xapp-...
```
**Windows PowerShell:**
```powershell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:SLACK_BOT_TOKEN = "xoxb-..."
$env:SLACK_APP_TOKEN = "xapp-..."
```
> 这些命令仅为当前终端会话设置变量。对于 Windows 上的永久配置，请通过控制面板 → 系统 → 高级 → 环境变量添加它们。
### 3. 运行示例运行手册
```bash
# 先进行 dry-run，看看会发生什么
runbook-exec run examples/disk-full.md --dry-run
# 验证风险级别而不执行
runbook-exec validate examples/disk-full.md
# 真正执行
runbook-exec run examples/disk-full.md
```
## 平台支持
已在 Linux、macOS 和 Windows 上测试。shell 执行器使用 `subprocess` 并运行您提供的任意 shell 命令 — 运行手册命令对于主机操作系统必须是有效的。大多数现实的运行手册都针对 Linux。在 Windows 上，请使用 `cmd.exe` 兼容命令或通过 `powershell -Command "..."` 包装 PowerShell。
## 运行手册格式
`runbook-exec` 使用 CommonMark 规范解析 Markdown。实际上有两个重要的规则：
**仅限编号列表。** 只有编号（`1.`、`2.`，...）列表项才成为步骤。项目符号（`-`、`*`）被忽略。
**代码块必须缩进在列表项下。** 只有当代码块的缩进至少与列表项的内容相同，才能将其与步骤关联。这是标准的 CommonMark 行为 — 左边缘的代码块不是列表的一部分。
✅ 正确 — 代码块缩进在列表项下：
```markdown
1. 检查磁盘使用情况
```bash
df -h
```
```
❌ 错误 — 代码块在左边缘（不会被提取为步骤的命令）：
```markdown
1. 检查磁盘使用情况
```bash
df -h
```
```
当有疑问时，运行 `runbook-exec validate <runbook.md>` — 输出中带有 `command=None` 的步骤表示代码块未被选中。
## 子命令
### `run`
端到端执行运行手册，带有安全门控和审计日志。
```bash
runbook-exec run <runbook.md> [选项]
选项：
--dry-run 模拟执行而不运行命令
--incident-id TEXT 用于审计日志文件名的标识符
--auto-approve TEXT 自动批准风险级别在或低于此级别的步骤：
read_only | modifying | destructive
--no-llm-context 禁用步骤后 LLM 决策调用
```
### `validate`
解析和分类运行手册而不执行任何命令。适用于 CI/CD。
```bash
runbook-exec validate <runbook.md>
```
### `replay`
从审计日志中显示以前的运行手册执行情况。
```bash
runbook-exec replay <audit-log.json>
```
## 配置
在项目根目录中创建一个 `.runbook-exec.toml` 文件来设置默认值：
```toml
llm_model = "claude-sonnet-4-5"
slack_channel = "#incidents"
timeout_seconds = 300
auto_approve_level = "read_only" # "read_only" | "modifying" | "destructive"
audit_log_dir = "./runbook-exec-logs"
```
### 环境变量
| 变量 | 必需 | 描述 |
|---|---|---|
| `ANTHROPIC_API_KEY` | 是 | Claude 的 Anthropic API 密钥 |
| `SLACK_BOT_TOKEN` | 审批时需要 | Slack 机器人令牌（`xoxb-...`） |
| `SLACK_APP_TOKEN` | 审批时需要 | Slack 应用令牌（`xapp-...`），用于 Socket 模式 |
### 配置优先级
命令行标志 > `.runbook-exec.toml` > 内置默认值
### Slack 备用
如果未配置 Slack（缺少 `SLACK_BOT_TOKEN` 或 `SLACK_APP_TOKEN`），则 `runbook-exec` 备用到交互式终端提示进行审批和故障指导。在启动时，会显示一个横幅，指示正在活动哪种模式。
建议在生产环境中使用 Slack，因为终端提示需要活动的 SSH 或控制台会话。终端模式对于本地测试和开发很有用。
## 风险级别
每个步骤都被归类为三个风险级别之一：
| 级别 | 描述 | 示例 |
|---|---|---|
| `read_only` | 仅观察系统状态 | `df`、`ls`、`cat`、`kubectl get`、`ps` |
| `modifying` | 更改状态但可恢复 | `systemctl restart`、`logrotate`、文件编辑 |
| `destructive` | 删除数据或需要 sudo | `rm -rf`、`DROP TABLE`、`kubectl delete` |
默认情况下，`read_only` 步骤自动运行。`modifying` 和 `destructive` 步骤需要 Slack 批准。
## 安全偏差原则
当分类器在两个风险级别之间不确定时，它始终选择更谨慎（更高风险）的级别。这是在 LLM 提示中强制执行的，而不是在后处理中执行的，因此推理反映了实际决策。
## LLM 数据披露
`runbook-exec` 在两种场景下将数据发送到 Anthropic API：
1. **步骤分类**（始终）：步骤文本和提取的命令被发送到 Claude 以确定风险级别。在执行任何操作之前，这会对每个步骤发生。
2. **步骤后决策**（除非设置 `--no-llm-context`）：在每个步骤成功执行后，步骤文本、命令、退出代码和 stdout/stderr 输出被发送到 Claude 以决定是否继续、跳过后续步骤或中止。
**未发送的内容**：Slack 令牌、审计日志内容或任何未执行的步骤的数据。
## `--no-llm-context` 标志
使用 `--no-llm-context` 防止命令输出发送到 Anthropic API：
```bash
runbook-exec run runbook.md --no-llm-context
```
设置此标志时：
- 步骤分类仍使用 LLM（仅发送步骤文本和命令）
- 禁用步骤后决策调用
- 执行继续到命令完成后的下一个步骤
- 在启动时显示警告
当运行产生敏感输出（凭证、PII、内部主机名）的运行手册时，请使用此标志，以免离开您的网络边界。
## 审计日志
每次执行都会在 `./runbook-exec-logs/`（可通过 `audit_log_dir` 配置）中生成防篡改审计日志。
审计日志使用 NDJSON 格式和 SHA-256 哈希链。每个条目都包含前一个条目的哈希值，使得篡改可被检测。
要重放和验证审计日志：
```bash
runbook-exec replay runbook-exec-logs/disk-full-20240115T030000Z-a3f1.json
```
审计日志文件永远不会被提交到源代码控制（`.gitignore` 包括 `runbook-exec-logs/`）。
## CI/CD 集成
在 PR 检查中使用 `runbook-exec validate` 来检查运行手册在合并之前 — 在凌晨 3 点的当班工程师到达之前捕获格式错误、缺少命令和分类失败。
```yaml
# .github/workflows/validate-runbooks.yml
name: 验证运行手册
on:
pull_request:
paths:
- 'runbooks/**/*.md'
- 'docs/runbooks/**/*.md'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install runbook-exec
- name: 验证所有更改的运行手册
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff --name-only origin/main...HEAD \
| grep '\.md$' \
| xargs -I{} runbook-exec validate {}
```
这仅验证在 PR 中实际更改的运行手册，而不是每次提交都验证所有运行手册。`ANTHROPIC_API_KEY` 密钥必须在您的存储库设置中配置。
**验证检查的内容：**
- 无法解析的 Markdown（格式错误）
- 没有提取命令的步骤（`command=None`）
- LLM 分类失败（格式错误的步骤文本）
- 在实际执行期间将被静默跳过的步骤
**验证不执行的操作：** 执行任何命令或连接到任何基础设施。它可以安全地在任何 CI 机器上运行。
## 示例运行手册
参见 [`examples/disk-full.md`](examples/disk-full.md) 以获取一个现实的磁盘满运行手册，其中包含 `read_only`、`modifying` 和 `destructive` 步骤的混合。
## 与 Claude Desktop 一起使用
`runbook-exec` 可以作为 MCP 服务器运行，让 Claude Desktop 通过自然对话执行运行手册 — 无需终端。
### 安装和配置
将以下内容添加到您的 Claude Desktop 配置文件中：
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"runbook-exec": {
"command": "runbook-exec",
"args": ["mcp-server"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-...",
"SLACK_BOT_TOKEN": "xoxb-...",
"SLACK_APP_TOKEN": "xapp-..."
}
}
}
}
```
重启 Claude Desktop。runbook-exec 工具将自动出现。
### 示例对话
> "验证位于 /runbooks/disk-full.md 的磁盘满运行手册"
> "预运行我们的部署运行手册并显示需要批准的内容"
> "从审计日志中显示昨晚事件发生的情况"
> "实际运行磁盘满运行手册" ← Claude 将在继续之前暂停每个高风险步骤并请求您的批准。
### 安全
- `execute_runbook` 默认设置为 `dry_run=True` — 除非您明确说“实际运行”或“非 dry-run”，否则 Claude 无法执行实际命令
- 所有审批门控均适用：`modifying` 和 `destructive` 步骤始终需要您的明确批准，无论是从 CLI 还是 Claude 调用
- 为每次执行写入完整的审计日志，包括 MCP 启动的运行
- 如果配置了 Slack，则审批将正常发送到 Slack
- 如果未配置 Slack，Claude 会以对话方式处理审批：它会显示待处理步骤，等待“是/继续”，然后继续
## 开发
```bash
# 以开发模式安装
pip install -e ".[dev]"
# 运行测试
pytest
# 运行测试并覆盖
pytest --cov=runbook_exec --cov-report=term-missing
# 整理代码
ruff check .
```
## 从源代码安装（开发）
要贡献或从本地克隆运行：
```bash
git clone https://github.com/giridharpandurangi/runbook-exec.git
cd runbook-exec
pip install -e ".[dev]"
```
