sop-engine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SOP Engine

SOP 引擎

Execute Standard Operating Procedures with built-in approval gates, state management, and audit logging.

执行内置审批关卡、状态管理和审计日志的标准操作流程（SOP）。

When to Use

适用场景

Run multi-step procedures that require human approval between steps
Execute complex workflows that span multiple agent sessions
Track and audit compliance procedures
Create reusable workflow templates
Implement approval-required workflows (e.g., deployments, changes)

运行步骤间需要人工审批的多步骤流程
执行跨多个Agent会话的复杂工作流
跟踪和审计合规流程
创建可复用的工作流模板
实现需要审批的工作流（如部署、变更）

Concepts

核心概念

SOP (Standard Operating Procedure)

SOP（标准操作流程）

A defined workflow with:

Steps: Sequential actions to perform
Approval Gates: Points where human approval is required
State: Persisted between steps
Audit Log: Complete execution history

已定义的工作流，包含：

步骤：需执行的顺序操作
审批关卡：需要人工审批的节点
状态：步骤间持久化保存
审计日志：完整的执行历史记录

Execution Modes

执行模式

```
auto
```
- Execute all steps without approval
```
supervised
```
- Request approval before starting, then execute all steps
```
step_by_step
```
- Request approval before each step
```
priority_based
```
- High priority = auto, Normal/Low = supervised

```
auto
```
- 无需审批执行所有步骤
```
supervised
```
- 开始前请求审批，之后执行所有步骤
```
step_by_step
```
- 每个步骤执行前请求审批
```
priority_based
```
- 高优先级=自动执行，普通/低优先级=监督模式

Triggers

触发方式

```
manual
```
- Triggered by name
```
cron
```
- Scheduled execution (expression)
```
webhook
```
- HTTP trigger

```
manual
```
- 通过名称手动触发
```
cron
```
- 定时执行（表达式）
```
webhook
```
- HTTP触发

Installation

安装

No additional installation required. Uses built-in tools:

jq

curl

git

无需额外安装。使用内置工具：

jq

、

curl

、

git

。

Quick Start

快速开始

1. Create an SOP

1. 创建SOP

Create

sops/my-sop.md

markdown

---
name: deploy-frontend
description: Deploy frontend to staging
version: "1.0.0"
priority: high
execution_mode: supervised
triggers:
  - type: manual
  - type: cron
    expression: "0 9 * * *"
---

创建

sops/my-sop.md

：

markdown

---
name: deploy-frontend
description: Deploy frontend to staging
version: "1.0.0"
priority: high
execution_mode: supervised
triggers:
  - type: manual
  - type: cron
    expression: "0 9 * * *"
---

Deploy Frontend to Staging

Step 1: Build the Project

bash

cd /job && npm run build

bash

cd /job && npm run build

Step 2: Run Tests

bash

cd /job && npm test

bash

cd /job && npm test

Step 3: Deploy (requires approval)

bash

echo "Deploying to staging..."

bash

echo "Deploying to staging..."

Step 4: Verify

bash

curl -s https://staging.example.com/health

undefined

bash

curl -s https://staging.example.com/health

undefined

2. List Available SOPs

2. 列出可用SOP

bash

sop-list

bash

sop-list

3. Execute an SOP

3. 执行SOP

bash

sop-execute deploy-frontend

bash

sop-execute deploy-frontend

4. Approve a Step

4. 审批步骤

bash

sop-approve <run-id>

bash

sop-approve <run-id>

5. Check Status

5. 检查状态

bash

sop-status <run-id>

bash

sop-status <run-id>

Commands

命令说明

sop-list

List all available SOPs.

bash

sop-list

列出所有可用的SOP。

bash

sop-list

sop-execute

Start an SOP execution.

bash

sop-execute <sop-name>
sop-execute <sop-name> --payload '{"key": "value"}'

启动SOP执行。

bash

sop-execute <sop-name>
sop-execute <sop-name> --payload '{"key": "value"}'

sop-approve

Approve the next step in a running SOP.

bash

sop-approve <run-id>

审批正在运行的SOP的下一步。

bash

sop-approve <run-id>

sop-reject

Reject and cancel a running SOP.

bash

sop-reject <run-id> --reason "Not ready for deployment"

拒绝并取消正在运行的SOP。

bash

sop-reject <run-id> --reason "Not ready for deployment"

sop-status

Check the status of an SOP run.

bash

sop-status <run-id>

检查SOP运行的状态。

bash

sop-status <run-id>

sop-runs

List all SOP runs (active and completed).

bash

sop-runs
sop-runs --sop <sop-name>

列出所有SOP运行记录（活跃和已完成）。

bash

sop-runs
sop-runs --sop <sop-name>

SOP Definition Format

SOP定义格式

SOPs are defined in markdown files with YAML frontmatter:

markdown

---
name: <unique-name>
description: <what this does>
version: "1.0.0"
priority: normal  # low, normal, high, critical
execution_mode: supervised  # auto, supervised, step_by_step, priority_based
triggers:
  - type: manual
  - type: cron
    expression: "0 9 * * *"
  - type: webhook
    path: /webhook/deploy
---

SOP通过带有YAML前置元数据的Markdown文件定义：

markdown

---
name: <unique-name>
description: <what this does>
version: "1.0.0"
priority: normal  # low, normal, high, critical
execution_mode: supervised  # auto, supervised, step_by_step, priority_based
triggers:
  - type: manual
  - type: cron
    expression: "0 9 * * *"
  - type: webhook
    path: /webhook/deploy
---

Title

Step 1: Description

bash

command to run

bash

command to run

Step 2: Description (requires approval)

bash

another command

undefined

bash

another command

undefined

Execution Flow

执行流程

┌─────────────────┐
│  sop-execute    │
│  (start run)    │
└────────┬────────┘
         │
         ▼
    ┌────────────┐
    │ Auto Mode? │───Yes──► Execute All Steps
    └─────┬──────┘              and Complete
          │ No
          ▼
    ┌────────────┐
    │ Supervised │───Wait for──►┌─────────────┐
    │   Mode     │    Approval   │sop-approve  │
    └─────┬──────┘               └──────┬──────┘
          │                              │
          ▼                              ▼
    ┌────────────┐               Execute Remaining
    │StepByStep │───Wait for──►  Steps One-by-One
    │   Mode    │   Approval    with Approval Each
    └───────────┘

┌─────────────────┐
│  sop-execute    │
│  (start run)    │
└────────┬────────┘
         │
         ▼
    ┌────────────┐
    │ Auto Mode? │───Yes──► Execute All Steps
    └─────┬──────┘              and Complete
          │ No
          ▼
    ┌────────────┐
    │ Supervised │───Wait for──►┌─────────────┐
    │   Mode     │    Approval   │sop-approve  │
    └─────┬──────┘               └──────┬──────┘
          │                              │
          ▼                              ▼
    ┌────────────┐               Execute Remaining
    │StepByStep │───Wait for──►  Steps One-by-One
    │   Mode    │   Approval    with Approval Each
    └───────────┘

State Management

状态管理

State is persisted in

~/.thepopebot/sop-state/<run-id>.json

json

{
  "run_id": "run-abc123",
  "sop_name": "deploy-frontend",
  "status": "running",
  "current_step": 2,
  "started_at": "2024-01-15T09:00:00Z",
  "payload": {"key": "value"},
  "history": [
    {"step": 1, "status": "completed", "output": "...", "timestamp": "..."},
    {"step": 2, "status": "pending_approval", "output": "...", "timestamp": "..."}
  ]
}

状态持久化存储在

~/.thepopebot/sop-state/<run-id>.json

中：

json

{
  "run_id": "run-abc123",
  "sop_name": "deploy-frontend",
  "status": "running",
  "current_step": 2,
  "started_at": "2024-01-15T09:00:00Z",
  "payload": {"key": "value"},
  "history": [
    {"step": 1, "status": "completed", "output": "...", "timestamp": "..."},
    {"step": 2, "status": "pending_approval", "output": "...", "timestamp": "..."}
  ]
}

Audit Logging

审计日志

All SOP executions are logged to

~/.thepopebot/sop-audit/

```
<run-id>.json
```
- Full execution record
```
<run-id>.log
```
- Step-by-step output

所有SOP执行记录都会日志到

~/.thepopebot/sop-audit/

：

```
<run-id>.json
```
- 完整执行记录
```
<run-id>.log
```
- 分步执行输出

Workflow Examples

工作流示例

Deploy with Approval

带审批的部署流程

markdown

---
name: deploy-production
description: Deploy to production with approval
priority: critical
execution_mode: step_by_step
triggers:
  - type: manual
---

markdown

---
name: deploy-production
description: Deploy to production with approval
priority: critical
execution_mode: step_by_step
triggers:
  - type: manual
---

Production Deployment

Step 1: Run Tests

bash

npm test

bash

npm test

Step 2: Build

bash

npm run build

bash

npm run build

Step 3: Deploy (APPROVAL REQUIRED)

bash

./deploy.sh production

bash

./deploy.sh production

Step 4: Verify

bash

curl -s https://production.example.com/health

undefined

bash

curl -s https://production.example.com/health

undefined

Data Processing Pipeline

数据处理流水线

markdown

---
name: process-daily-data
description: Daily data processing pipeline
priority: high
execution_mode: auto
triggers:
  - type: cron
    expression: "0 2 * * *"
---

markdown

---
name: process-daily-data
description: Daily data processing pipeline
priority: high
execution_mode: auto
triggers:
  - type: cron
    expression: "0 2 * * *"
---

Daily Data Processing

Step 1: Fetch Data

bash

curl -o data/raw.json https://api.example.com/data

bash

curl -o data/raw.json https://api.example.com/data

Step 2: Transform

bash

node transform.js data/raw.json > data/processed.json

bash

node transform.js data/raw.json > data/processed.json

Step 3: Validate

bash

node validate.js data/processed.json

bash

node validate.js data/processed.json

Step 4: Archive

bash

mv data/processed.json archive/$(date +%Y%m%d).json

undefined

bash

mv data/processed.json archive/$(date +%Y%m%d).json

undefined

Best Practices

最佳实践

Use descriptive step titles - Makes approval prompts clearer
Keep steps atomic - Each step should do one thing
Include rollback commands - For critical operations
Add verification steps - Always confirm success
Use appropriate modes - Production = step_by_step, dev = auto
Document prerequisites - List what needs to be true before execution

使用描述性的步骤标题 - 让审批提示更清晰
保持步骤原子化 - 每个步骤只做一件事
包含回滚命令 - 针对关键操作
添加验证步骤 - 始终确认执行成功
使用合适的执行模式 - 生产环境=step_by_step，开发环境=auto
记录前置条件 - 列出执行前需要满足的条件

Limitations

局限性

Current implementation uses shell/bash - not all SOPs can be expressed this way
State is local to the agent - not shared across different agent instances
Approval requires human intervention via CLI

当前实现使用shell/bash - 并非所有SOP都能通过这种方式表达
状态仅存储在本地Agent中 - 无法在不同Agent实例间共享
审批需要通过CLI进行人工干预