管线 · 流引擎 · 交换所

数据库迁移、自定义多 Agent 管线、Flow（流引擎）运维。

---

🗄️ 数据库迁移与升级

自动迁移

升级会自动跑 migration（src/storage/migrations/ 目前 v1…v19）：

workspace/familiars.db  ← SQLite WAL 模式

升级前备份

务必备份 workspace/familiars.db —— 迁移不可逆地修改 schema。

迁移格式

迁移器支持两种载体：

格式	示例
*.sql	纯 SQL 语句
*.py	Python 迁移脚本（如 v16）

自定义数据库路径

设置 FAMILIARS_DB_PATH 环境变量可覆盖默认路径（测试/多实例场景）。

---

🔀 自定义多 Agent 管线 CustomPipeline

编排多 agent 协作的自定义 pipeline。

概念

CustomPipeline 由 custom_pipeline skill 的后端驱动：

• 多个 agent 按顺序/并行执行
• 每个 agent 处理特定子任务
• 结果汇总到最终输出

使用场景

• 文档处理流水线：agent A 提取 → agent B 分析 → agent C 总结
• 多语言翻译：并行翻译 → 合并校对
• 数据采集：多源采集 → 去重 → 格式化

配置

在创意工坊中配置 pipeline：

1. 选择参与的 agent
2. 定义执行顺序/并行关系
3. 配置数据传递（变量绑定）
4. 设置错误处理（重试/跳过/中断）

---

🌊 流引擎 Flow Engine

v2 流编辑器，跨 Agent 的多阶段工作流编排。

核心概念

术语	说明
FlowTemplate	流模板（JSON），定义节点/边/角色
Flow	流实例，运行中的具体执行
GraphNode	节点（compute / llm_call / emit_event / for_each / branch）
Edge	边（可带 condition 表达式）
Role	执行角色（绑定到具体 agent）

节点类型

类型	功能
compute	表达式计算（AST 白名单）
llm_call	调用 LLM（支持 output_format / output_var）
emit_event	向用户展示信息 / 阻塞等待
for_each	循环执行 body_nodes
branch	条件分支（case + else）
starter / summary	纯 IO 节点（FieldSpec 列表）

流编辑器 v2

可视化编辑器功能：

• 拖拽节点：从面板拖入画布
• 连线：节点间连接，定义数据流
• 条件边：支持 AST 白名单表达式
• 子模块容器：并行组/组合组包含链
• 暂存区：临时存放待用节点

运行与监控

查看运行中的 flow

GET /api/flows

状态：pending | running | done | failed

查看详情 / 取消

GET /api/flows/{id}      # 节点执行与事件 trace
POST /api/flows/{id}/cancel   # 中断运行

断点续跑（Resume）

bridge 崩溃中断的 flow（状态停留 running）可用 src/flow/resume.py:rehydrate 重建：

• 重放 mutation log
• 校验每步 graph hash
• 模板被改过则拒绝续跑

Flow 执行模型

FlowEngine
├── owner-thread（主线程，协调）
└── per-role worker-thread（每个角色独立工作线程）
    ├── 接收任务
    ├── 执行节点
    └── 上报结果

• 并发：不同角色可并行执行
• 同步：等待依赖节点完成
• 错误处理：节点失败触发重试/跳过/中断

---

🛒 交换所运维

查看已安装应用

GET /api/broker_workshop/instances

从市场安装

POST /api/broker_workshop/instances/install_from_url
Body: { "url": "https://...", "sha256": "...", "sig": "..." }

安装流程：

1. 下载 .broker.zip
2. 校验 sha256
3. 验证 Ed25519 签名
4. 匹配作者 pubkey
5. 解压安装

市场索引

GET /api/broker_workshop/marketplace/index

代理 FAMILIARS_MARKETPLACE_URL/index.json。

---

🔧 CLI 命令

# Flow 相关
python main.py flows list --pretty
python main.py flows get <id>
python main.py flows cancel <id>

# Broker 相关
python main.py broker list
python main.py broker install <url>
python main.py broker pack <dir>
python main.py broker sign <file>
python main.py broker verify <file>
python main.py broker publish <file>
python main.py broker marketplace-index

完整参考 → CLI 全量命令

---

📖 开发视角

主题	链接
Recipe 开发	生态·Recipe
Flow 开发	生态·Flow
Broker 开发	生态·Broker
Broker 架构	生态·Broker 架构

---

完整来源：仓库根 OPERATION.md §39–§42。