09 · 技能 / 配方 / 生态与流引擎

架构剖析第九篇：技能系统、配方（Recipe）、Broker/交换所、多 Agent Pipeline、Flow Engine。对应 ARCHITECTURE.md §11–§11.5。

§11.1 技能系统（Skills）

11.1.1 SKILL.md 格式

技能由 SKILL.md 文件定义，存放在 workspace/skills/ 或 workspace/tool_skills/：

markdown

# 技能名称

## Step 1: 输入解析
**Manager Review**  ← 此标记自动生成审批流程
...

## Step 2: 执行
...

## Step 3: 验证
...

11.1.2 技能工具

python

# src/tools/skill_tools.py
class SkillTools:
    """Agent 调用技能的入口。"""

# src/utils/skill_watcher_tools.py
class SkillWatcherTools:
    """技能看门狗——监控技能变化。"""

11.1.3 execute_skill 伪工具

python

# src/tools/tool_dispatcher.py
def execute_skill_schema() -> dict:
    """OpenAI function schema for execute_skill pseudo-tool.
    
    框架级 affordance，注册在每个 ToolDispatcher 上。
    Recipe/flow unit 通过 tools.whitelist 暴露此 schema。
    """
    return {
        "type": "function",
        "function": {
            "name": "execute_skill",
            "parameters": {
                "type": "object",
                "properties": {
                    "skill_id": {"type": "string"},
                    "args": {"type": "object"},
                },
                "required": ["skill_id"],
            },
        },
    }

11.1.4 Manager Review 标记

技能作者在 SKILL.md 中标记 **Manager Review** → skill_manager 自动构建审批流程。

适用于 tool_client 和 python_script 两种绑定。

§11.2 配方系统（Recipes）

11.2.1 概念

Recipe = 单 agent 多阶段图：

输入解析 → 规划 → 执行 → 验证 → 合成

11.2.2 节点类型

节点类型	说明
`compute`	纯计算（Python 表达式）
`llm_call` (native)	原生 LLM 调用（inline system_prompt + tool_whitelist）
`tool_call`	工具调用节点
`emit_event`	阻塞式事件推送
`for_each`	循环（内联 body_nodes/body_edges）

11.2.3 分支表达式

python

# 边 condition= 走 AST 白名单
# .get() 静默求值为 False → 用 x['key'] 下标语法（白名单允许）

11.2.4 output_var

python

# config.output_var 把 schema dict 包裹在一个名字下
# 没有它，schema fields 散布到顶层 → 下游 .field 访问失败

11.2.5 能力审批

每个 (recipe, agent) 对：

capabilities.extra_modules → 请求沙箱权限
审批哈希 → (recipe_id, agent_id) 唯一

python

# 安装内建模板时自动审批
# bind/SetDefault 响应携带 caps_declared + needs_approval
# CapabilityApprovalPanel + CapabilityConsentModal 在工坊 UI

11.2.6 配方开发

workspace/manager/recipes/<recipe_id>/
├── manifest.json        # 配方清单
├── state_graph.json     # 状态图
├── knowledge/           # 知识库（AGENTS.md 必须在此）
├── external_kb/         # 外部知识库
└── output_renderers/    # 自定义渲染器 .vue

完整教程见生态·Recipe。

§11.3 Broker / 交换所层

11.3.1 架构概览

src/broker/
├── hub.py               # BrokerHub: 身份 + 传输 + 匹配 + 限流 + 账本
├── identity.py          # 身份管理
├── transport.py         # 传输层
├── matching.py          # 匹配引擎
├── rate_limit.py        # 限流器
├── ledger.py            # 账本
├── store.py             # 持久化
├── reputation.py        # 信誉系统
├── packaging_cli.py     # 打包 CLI
├── workshop/            # 可安装应用
│   └── __init__.py      # rooms + threads + reputation + triggers
├── relay/               # 市场分发
├── relay_client.py      # relay 客户端
├── sdk/                 # SDK
├── user_profile/        # 用户画像
├── guild/               # 公会子系统
└── ...

11.3.2 可安装应用包

.broker.zip 结构：
├── manifest.json        # 清单（name, version, author, permissions）
├── cover.png            # 封面图
├── ui/                  # UI 资产（HTML/JS/CSS）
├── plugin.py            # 插件代码（bridge 进程内运行）
└── triggers.json        # 触发配置

11.3.3 签名与安装

bash

# 作者签名
python main.py broker keygen --name <author>
python main.py broker pack --source <dir> --output app.broker.zip
python main.py broker sign --package app.broker.zip

# 用户安装
python main.py broker install --package app.broker.zip
# 验证：sha256 + Ed25519 签名 + 作者 pubkey 匹配

11.3.4 市场

bash

# 查看市场索引
python main.py broker marketplace-index

# 发布
python main.py broker publish --package app.broker.zip

市场索引是稳定契约（docs/marketplace-index-schema.md）。

11.3.5 三层内聚

层	职责	对应模块
Hub	消息 + 交易链 + 账本	`hub.py`, `transport.py`, `ledger.py`
Workshop	安装物管理	`workshop/`, `broker_workshop.py`
Relay	市场分发	`relay/`, `relay_client.py`

11.3.6 数据库迁移

Broker 相关迁移：v18–v39, v41+

版本	说明
v18	broker 核心表
v19	broker_workshop
v20	broker_local_package_dir
v21	broker_identity_assets
v22	broker_messages
v23	broker_member_caps
v24	broker_approvals
v28	broker_author_crl
v29	broker_trusted_authors
v30–v32	broker 联邦（room/thread/message）
v36	broker_user_consents

11.3.7 REST 端点

路由	前缀	说明
`broker.py`	`/api/broker`	Broker 层（Hub/匹配/账本）
`broker_workshop.py`	`/api/broker_workshop`	安装/管理
`broker_app.py`	`/api/broker_app`	iframe UI（静态资产豁免 token）
`broker_assets.py`	`/api/broker_assets`	静态资产
`broker_dev.py`	`/api/broker_dev`	开发工具

完整教程见生态·Broker。

§11.4 多 Agent Pipeline

python

# src/bridge/routes/pipelines.py
# POST /api/pipelines/...

# 自定义多 agent 管线：
# 编排多 agent 协作
# 由 custom_pipeline skill（后端驱动）执行

操作面见管线与流。

§11.5 流引擎（Flow Engine）

11.5.1 概念

Flow = 以主 agent 轨道为主干的多 agent 工作流：

Starter → [agent_1 role_A] → [agent_2 role_B] → ... → Summary

11.5.2 FlowEngine

python

# src/flow/engine.py
class FlowEngine:
    """owner-thread + 每角色 worker-thread 并发执行。
    
    owner-thread: 管理流生命周期
    worker-thread: 每个角色一个，并行执行
    """

11.5.3 断点续跑

python

# src/flow/resume.py
def resume_flow(flow_id: str) -> FlowEngine:
    """从 DB 重建引擎。
    
    重放 mutation log + hash 校验。
    """

11.5.4 流模板

workspace/manager/flows/<template_id>/
├── template.json        # 模板定义
├── layout.json          # 编辑器布局
├── renderers/           # 自定义字段渲染器 .vue
│   └── *.vue
└── docs/                # 设计/开发文档
    ├── DESIGN.md
    └── DEVELOPMENT.md

11.5.5 内建模板

python

# src/flow/_builtin/<id>/
# install_built_ins() 在 bridge 启动时安装
# 内建模板只读（后端禁止保存/删除）
# UI 分 "系统" / "我的" 列表

11.5.6 REST 端点

路由	前缀	说明
`flow_templates.py`	`/api/flow-templates`	模板 CRUD + 自定义字段渲染器
`flows.py`	`/api/flows`	流实例（list/get/trace/cancel）
`flow_dev.py`	`/api/flow_dev`	流开发工具

11.5.7 数据库迁移

版本	说明
v25	flow_core（Python 迁移）
v26	flow_trace_index

完整教程见生态·Flow。

§11.6 公会系统（Guild）

11.6.1 数据库迁移

版本	说明
v20	guild 核心
v21	guild_task_type
v27	guild_medal_images
v33	guild_task_federation
v34	guild_medal_federation
v35	guild_ledger_federation
v37	guild_scope_approvals
v38	guild_task_lifecycle
v39	guild_merge_requests
v40	task_edit_history
v42	guild_experience_reports + guild_modification_votes
v43	guild_task_recall_votes
v44	guild_scope_members
v46	guild_task_tags

11.6.2 REST 端点

python

# src/bridge/routes/guild.py → /api/guild

下一篇：10-工程与附录 →

09 · 技能 / 配方 / 生态与流引擎 ​

§11.1 技能系统（Skills） ​

11.1.1 SKILL.md 格式 ​

11.1.2 技能工具 ​

11.1.3 execute_skill 伪工具 ​

11.1.4 Manager Review 标记 ​

§11.2 配方系统（Recipes） ​

11.2.1 概念 ​

11.2.2 节点类型 ​

11.2.3 分支表达式 ​

11.2.4 output_var ​

11.2.5 能力审批 ​

11.2.6 配方开发 ​

§11.3 Broker / 交换所层 ​

11.3.1 架构概览 ​

11.3.2 可安装应用包 ​

11.3.3 签名与安装 ​

11.3.4 市场 ​

11.3.5 三层内聚 ​

11.3.6 数据库迁移 ​

11.3.7 REST 端点 ​

§11.4 多 Agent Pipeline ​

§11.5 流引擎（Flow Engine） ​

11.5.1 概念 ​

11.5.2 FlowEngine ​

11.5.3 断点续跑 ​

11.5.4 流模板 ​

11.5.5 内建模板 ​

11.5.6 REST 端点 ​

11.5.7 数据库迁移 ​

§11.6 公会系统（Guild） ​

11.6.1 数据库迁移 ​

11.6.2 REST 端点 ​

09 · 技能 / 配方 / 生态与流引擎

§11.1 技能系统（Skills）

11.1.1 SKILL.md 格式

11.1.2 技能工具

11.1.3 execute_skill 伪工具

11.1.4 Manager Review 标记

§11.2 配方系统（Recipes）

11.2.1 概念

11.2.2 节点类型

11.2.3 分支表达式

11.2.4 output_var

11.2.5 能力审批

11.2.6 配方开发

§11.3 Broker / 交换所层

11.3.1 架构概览

11.3.2 可安装应用包

11.3.3 签名与安装

11.3.4 市场

11.3.5 三层内聚

11.3.6 数据库迁移

11.3.7 REST 端点

§11.4 多 Agent Pipeline

§11.5 流引擎（Flow Engine）

11.5.1 概念

11.5.2 FlowEngine

11.5.3 断点续跑

11.5.4 流模板

11.5.5 内建模板

11.5.6 REST 端点

11.5.7 数据库迁移

§11.6 公会系统（Guild）

11.6.1 数据库迁移

11.6.2 REST 端点