---
slug: "sop-engine"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/maxoreric/sop-engine@main/README.md"
repo: "https://github.com/maxoreric/sop-engine"
source_file: "README.md"
branch: "main"
---
# sop-engine

> 🚀 AI 驱动的 SOP（标准操作流程）引擎 - 人说想法，Claude 写/执行 Skill，产出结果

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Runtime Tests](https://img.shields.io/badge/tests-39%2F40%20passing-brightgreen)](docs/RUNTIME-TEST-REPORT.md)

## 🎯 核心理念

**sop-engine 的「用户」是 Claude，不是人。**

- 人只需表达意图
- Claude 负责创建 Skill、编排 Workflow、执行任务
- 判别式交互：做选择题，不做填空题

## ✨ 特性

- 🔄 **Workflow 编排** - 用有向图定义复杂的任务流程
- 🧩 **可复用 Skills** - 22 个 Core Skills，像函数一样组合
- 🤖 **智能交互** - 判别式交互，最大信息增益
- 📊 **状态管理** - 完整的执行状态追踪和恢复
- ⏰ **定时触发** - 支持 cron 格式的定时任务
- 🔁 **循环和分支** - 支持条件判断和循环执行
- ✅ **已验证** - Runtime 测试 39/40 通过

## 🚀 快速开始

### 安装依赖

```bash
# macOS
brew install jq yq

# 验证安装
jq --version
yq --version
```

### 运行测试

```bash
# 基础功能测试 (16/16 通过)
./test-runtime-basic.sh

# 状态管理测试 (16/16 通过)
./test-state-manager.sh

# Workflow 执行测试 (7/8 通过)
./test-executor.sh
```

### 创建第一个 Workflow

1. **定义 Workflow** (`.sop-engine/workflows/hello.yaml`)

```yaml
workflow:
  name: hello-world
  description: 第一个 Workflow
  
  nodes:
    greet:
      type: skill
      skill: clarify-skill
      input:
        question: "Hello, World!"
  
  edges:
    - from: greet
      to: END
  
  entry: greet
  exit: END

trigger:
  type: manual
```

2. **执行 Workflow**

```bash
.sop-engine/runtime/dispatcher.sh start hello-world '{}'
```

## 📚 核心概念

### Workflow = 有向图

```
节点（Node）= Skill / Workflow / Condition / Loop / Parallel
边（Edge）= 控制流

示例：
  collect_data → analyze → check_score → generate_report → END
                              ↓ (score < 60)
                           alert_user → END
```

### 22 个 Core Skills

| 类别 | Skills |
|------|--------|
| 理解 | clarify-skill |
| 认知 | research-skill, plan-skill, evaluate-skill, reflect-skill |
| 协作 | handoff-skill |
| 记忆 | log-skill |
| 自省 | create-skill, iterate-skill, version-skill |
| 控制 | loop-skill |
| 开发 | claude-code-dev, hook-skill |
| 编排 | skill-lifecycle |
| 设计 | system-create-skill, workflow-define-skill, agent-define-skill |
| 交互 | user-confirm-skill |
| 汇总 | synthesize-skill, summarize-skill |

### 判别式交互

```
❌ 错误（生成式）: "你想要什么功能？请详细描述。"

✅ 正确（判别式）: "我设计了这个方案：
   - 功能 A
   - 功能 B
   - 功能 C
   这个方案符合你的预期吗？
   A. ✅ 符合，开始执行
   B. ❌ 需要调整"
```

## 🏗️ 项目结构

```
sop-engine/
├── .claude/                    # Claude Code 配置
│   ├── skills/                 # Skills 定义（22 个）
│   ├── agents/                 # Subagents
│   └── commands/               # Slash commands
│
├── .sop-engine/                # Runtime 数据
│   ├── runtime/                # Runtime 脚本（8 个）✅
│   │   ├── executor.sh         # Workflow 执行器
│   │   ├── dispatcher.sh       # 调度器
│   │   ├── state-manager.sh    # 状态管理
│   │   ├── skill-runner.sh     # Skill 执行器
│   │   ├── tick.sh             # 定时触发
│   │   ├── event-listener.sh   # 事件监听
│   │   ├── utils.sh            # 工具函数
│   │   └── config.sh           # 配置
│   │
│   ├── workflows/              # Workflow 定义
│   ├── running/                # 运行中的实例
│   ├── completed/              # 已完成的实例
│   └── failed/                 # 失败的实例
│
├── docs/                       # 文档
│   ├── DESIGN.md               # 设计文档
│   ├── RUNTIME-TEST-REPORT.md  # 测试报告 ✅
│   └── CAPABILITY-MAP.md       # 能力图谱
│
└── test-*.sh                   # 测试脚本 ✅
```

## 📖 使用指南

### 创建 Skill

```bash
# 使用 create-skill 命令
/create-skill 数据分析
```

### 定义 Workflow

支持的节点类型：

1. **skill** - 执行 Skill
2. **workflow** - 嵌套 Workflow
3. **condition** - 条件分支
4. **loop** - 循环控制
5. **parallel** - 并行执行

完整示例：

```yaml
workflow:
  name: data-pipeline
  
  nodes:
    collect:
      type: skill
      skill: data-collect-skill
      input:
        date: $workflow.input.date
    
    analyze:
      type: skill
      skill: data-analyze-skill
      input:
        data: $collect.output
    
    check:
      type: condition
      expression: "$analyze.output.score >= 80"
    
    success:
      type: skill
      skill: report-skill
    
    failure:
      type: skill
      skill: alert-skill
  
  edges:
    - from: collect
      to: analyze
    - from: analyze
      to: check
    - from: check
      to: success
      condition: true
    - from: check
      to: failure
      condition: false
    - from: success
      to: END
    - from: failure
      to: END
  
  entry: collect
  exit: END

trigger:
  type: manual
```

### 触发方式

1. **手动触发**
```bash
.sop-engine/runtime/dispatcher.sh start workflow-name '{"param":"value"}'
```

2. **定时触发**
```yaml
trigger:
  type: tick
  schedule: "21:00"  # 每天 21:00
  # 或 cron 格式
  schedule: "0 */6 * * *"  # 每 6 小时
```

3. **文件触发**
```yaml
trigger:
  type: file_upload
  path: "data/reports/*.pdf"
```

## 🧪 测试结果

### Runtime 测试：39/40 通过 (97.5%) ✅

| 测试模块 | 通过/总数 | 状态 |
|---------|----------|------|
| 配置和工具函数 | 16/16 | ✅ 完全通过 |
| 状态管理器 | 16/16 | ✅ 完全通过 |
| Workflow 执行器 | 7/8 | ✅ 基本通过 |

详见 [测试报告](https://github.com/maxoreric/sop-engine/blob/HEAD/docs/RUNTIME-TEST-REPORT.md)

### 已验证功能

- ✅ 配置系统
- ✅ 状态管理
- ✅ Skill 执行
- ✅ 顺序 Workflow
- ✅ 条件分支
- ✅ 循环控制

## 📊 实现状态

### Runtime 组件 ✅ (100%)

- [x] 配置系统 (config.sh)
- [x] 工具函数 (utils.sh)
- [x] 状态管理 (state-manager.sh)
- [x] Workflow 执行 (executor.sh)
- [x] Skill 执行 (skill-runner.sh)
- [x] 调度器 (dispatcher.sh)
- [x] 定时触发 (tick.sh)
- [x] 事件监听 (event-listener.sh)

### Skills ✅ (100%)

- [x] 22 个 Core Skills
- [x] system-create-skill (创建系统)
- [x] user-confirm-skill (判别式确认)
- [x] workflow-define-skill (定义 Workflow)
- [x] agent-define-skill (定义 Agent)

### 文档 ✅ (100%)

- [x] 设计文档 (DESIGN.md)
- [x] Workflow 规范 (workflow-spec.md)
- [x] Runtime 规范 (runtime-spec.md)
- [x] System Prompt (system-prompt.md)
- [x] 测试报告 (RUNTIME-TEST-REPORT.md)
- [x] README.md (本文档)

## 🔧 开发指南

### 调试 Workflow

```bash
# 查看运行中的实例
ls .sop-engine/running/

# 查看实例状态
cat .sop-engine/running/<instance-id>/state.json

# 查看执行日志
cat .sop-engine/running/<instance-id>/logs/executor.log

# 查看失败原因
cat .sop-engine/failed/<instance-id>/state.json
```

### 启动定时调度

```bash
# 启动 Tick Loop（后台运行）
.sop-engine/runtime/tick.sh daemon

# 查看状态
.sop-engine/runtime/tick.sh status

# 停止
.sop-engine/runtime/tick.sh stop
```

## 🤝 贡献

欢迎贡献！请遵循以下原则：

1. **判别式交互** - 做选择题，不做填空题
2. **Skill 和文件是一等公民** - 简单优先
3. **小步迭代** - 每次只改一点

## 📄 许可证

MIT License

## 🔗 相关资源

- [设计文档](https://github.com/maxoreric/sop-engine/blob/HEAD/docs/DESIGN.md) - 完整的设计理念
- [能力图谱](https://github.com/maxoreric/sop-engine/blob/HEAD/docs/CAPABILITY-MAP.md) - 系统能力全景
- [测试报告](https://github.com/maxoreric/sop-engine/blob/HEAD/docs/RUNTIME-TEST-REPORT.md) - Runtime 测试详情
- [Workflow 规范](https://github.com/maxoreric/sop-engine/blob/HEAD/.sop-engine/workflow-spec.md) - Workflow 定义规范
- [Runtime 规范](https://github.com/maxoreric/sop-engine/blob/HEAD/.sop-engine/runtime-spec.md) - Runtime 实现规范

---

**Made with ❤️ for AI-driven automation**