# pipeline-service 通用产线执行引擎

## 定位

通用产线执行引擎模块。把 Hermes Agent 验证过的业务流程固化为可重复、可并发的产线业务环境。

## 核心价值

- Hermes Agent 中用 cron/delegate/terminal 跑通的流程 → 固化为产线步骤定义 → pipeline-service 自动调度执行
- 一次验证，无限次自动执行
- 多租户并发：同一产线，不同租户同时使用，数据完全隔离

## 架构

```
宿主应用 (pipeline-app / sage / 其他)
  │
  ├── load_pipeline_service()  ← 注册函数到 ServerEnv
  │
  ├── pipeline_submit(tenant_id, pipeline_id, owner_id, title, params)
  ├── pipeline_list(tenant_id, pipeline_id?)
  ├── pipeline_detail(tenant_id, task_id)
  ├── pipeline_node(tenant_id, task_id, step_name, version?)
  ├── pipeline_modify(tenant_id, task_id, updates, rerun_from)
  ├── pipeline_pause(tenant_id, task_id)
  ├── pipeline_resume(tenant_id, task_id)
  ├── pipeline_cancel(tenant_id, task_id)
  └── pipeline_register_handler(step_type, fn)  ← 注册步骤处理器
```

## 引擎工作原理

1. **提交任务** → 读取 pipeline_steps 表的步骤定义 → 创建 pipeline_task_steps 记录 → 启动执行
2. **执行循环** → 解析 DAG 依赖图 → 找到可执行步骤（所有前置完成）→ 调用 handler → 存 artifact → 继续下一步
3. **多租户** → 所有查询按 tenant_id 隔离 → 同一产线多租户并发不冲突
4. **人工干预** → 修改节点 artifact → 创建新版本 → BFS 计算受影响步骤 → 级联重跑

## 数据表

| 表名 | 用途 |
|------|------|
| pipeline_tasks | 任务主表（tenant_id 隔离） |
| pipeline_task_steps | 任务步骤执行记录 |
| pipeline_artifacts | 步骤产物（input/output，支持版本） |
| pipeline_steps | 产线步骤定义（由 pipeline_core 模块管理） |
| pipelines | 产线定义（由 pipeline_core 模块管理） |

## 步骤处理器

可插拔注册，统一接口：

```python
async def handler(tenant_id, task_id, step_name, input_data, config) -> dict:
    # 处理逻辑
    return output_data

# 注册
from pipeline_service import register_handler
register_handler("llm_generate", handler)
```

处理器按 `step_type` 匹配。步骤定义中的 `step_type` 对应 handler 注册名。

## 宿主集成

任何应用只需一行代码即可使用：

```python
from pipeline_service.init import load_pipeline_service
load_pipeline_service()
```

宿主负责：
- HTTP 路由（ahserver 管）
- 用户认证（RBAC 管）
- 前端交互（bricks 管）
- 产线定义和定价（pipeline_core/ops/dist 管）

pipeline-service 只做：调度 + 执行 + 存储。

## 目录结构

```
pipeline-service/
├── pipeline_service/
│   ├── __init__.py        # 包导出
│   ├── init.py            # load_pipeline_service() + ServerEnv 注册
│   ├── state.py           # DAG 解析、步骤状态机
│   ├── handler.py         # 步骤处理器注册表
│   ├── storage.py         # MySQL 存储层（sqlor）
│   └── executor.py        # 执行循环
├── models/
│   ├── pipeline_tasks.json
│   ├── pipeline_task_steps.json
│   └── pipeline_artifacts.json
├── init/
│   └── data.json          # appcodes 初始化数据
├── scripts/
│   └── load_path.py       # RBAC 权限注册
├── pyproject.toml
├── build.sh
└── README.md
```

## 构建与部署

```bash
cd ~/repos/pipeline-service
pip install .

# 建表
json2ddl mysql models/ > mysql.ddl.sql
mysql -u root -p pipeline < mysql.ddl.sql

# 加载 appcodes
# (通过宿主应用的 build.sh 自动加载 init/data.json)
```