业务需求 Swarm 与工程实施 Swarm 全链路边界与双向握手协议
本协议旨在彻底厘清"业务需求 Swarm（概念设计层）"与"工程实施 Swarm（物理实现层）"的系统边界，明确其全链路输入输出、职责分工及双向握手规范。
一、双 Swarm 职责与边界矩阵 (Separation Matrix)
| 维度 | 业务需求 Swarm (The Concept Layer) | 工程实施 Swarm (The Realization Layer) |
|---|---|---|
| 核心定位 | 概念设计师与业务建模师（平台无关） | 技术交付专家与平台适配器（平台强相关） |
| 输入源 | 用户模糊的自然语言需求、企业历史业务模板、行业标准规范 | 业务需求 Swarm 交付的统一逻辑 DSL (L-DSL) |
| 核心职责 | 1. 梳理完整的业务实体、属性及关联关系（ER 建模） 2. 规划业务流程的状态流转、触发条件与审批角色 3. 规划仪表盘、报表和页面的概念性排版与信息层级 | 1. 规划特定平台 API/CLI 的调用序列与参数组装 2. 将逻辑流转翻译为特定平台的审批引擎或自动化流 3. 负责物理界面的渲染（如 Docx Block 拼装、视图配置） |
| 技术边界 | 严禁包含任何特定平台的 API 限制、CLI 命令、JS 代码、HTML 标签等物理实现细节。 | 100% 承担特定平台的频控（Rate Limit）、安全凭证、事务一致性、网络重试及布局渲染。 |
| 最终产出 | 平台无关的 统一逻辑描述契约 (Logical-DSL) | 运行在特定平台（如飞书、简道云）上的物理应用实例 |
二、业务需求 Swarm：全链路设计概念层 (The Design Concept Layer)
业务需求 Swarm 的核心任务是完成从"用户痛点 ──> 结构化逻辑模型"的全链路设计。它由四个细分专业 Agent 协作完成：
┌──────────────────────┐
│ 用户模糊需求 │
└──────────┬───────────┘
│ (自然语言)
▼
┌───────────────────────────────────────────────────────────────────────────┐
│ 业务需求 Swarm 内部链路 │
│ │
│ 1. 需求分析与场景拆解 (FDE Agent) │
│ - 识别核心业务流（例如：合同签约 ──> 付款 ──> 归档） │
│ │
│ 2. 实体关系与数据建模 (表单建模 Agent) │
│ - 梳理 Entity (Contract, Payment)、Attributes 与 Relation (1:N) │
│ │
│ 3. 流程状态机规划 (流程控制 Agent) │
│ - 设计状态转移：Draft ──[Submit]──> Approving ──[Approve]──> Active │
│ │
│ 4. 信息大盘与交互逻辑规划 (仪表盘设计 Agent) │
│ - 规划信息优先级：首屏 KPI ──> 中部申请表单 ──> 底部流程轨迹 │
└───────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ 统一逻辑 DSL (L-DSL) │
└──────────────────────┘2.1 概念层输出：统一逻辑 DSL (L-DSL) 标准结构
为了不给工程实施端带来任何"物理猜测"，L-DSL 必须是完备的。以下是一个合同管理的 L-DSL 样例：
{
"meta": {
"appName": "企业合同与付款管理系统",
"version": "1.0.0"
},
"domainModel": {
"entities": [
{
"id": "contract",
"label": "合同基本信息",
"properties": [
{"id": "code", "label": "合同编号", "type": "STRING", "required": true},
{"id": "amount", "label": "合同金额", "type": "DECIMAL", "rules": ["min:0"]}
]
},
{
"id": "payment",
"label": "付款记录",
"properties": [
{"id": "pay_date", "label": "付款日期", "type": "DATE"},
{"id": "pay_amount", "label": "付款金额", "type": "DECIMAL"}
]
}
],
"relations": [
{
"from": "contract",
"to": "payment",
"type": "ONE_TO_MANY",
"label": "合同拥有的付款记录"
}
]
},
"workflowModel": {
"processes": [
{
"targetEntity": "contract",
"states": ["DRAFT", "PENDING_CFO", "ACTIVE", "REJECTED"],
"transitions": [
{
"from": "DRAFT",
"to": "PENDING_CFO",
"trigger": "SUBMIT",
"condition": "contract.amount > 50000"
},
{
"from": "PENDING_CFO",
"to": "ACTIVE",
"trigger": "CFO_APPROVE"
}
]
}
]
},
"portalModel": {
"layouts": [
{
"page": "dashboard",
"title": "合同执行监控大盘",
"sections": [
{"type": "KPI_CARD", "targetProperty": "contract.amount", "aggregation": "SUM", "label": "总签约额"},
{"type": "GRID_VIEW", "targetEntity": "contract", "label": "合同台账列表"},
{"type": "FORM", "targetEntity": "payment", "label": "新增付款申请"}
]
}
]
}
}三、工程实施 Swarm：平台物理实现层 (The Realization Layer)
工程实施 Swarm 严禁干涉业务逻辑的对错，它的使命是把 L-DSL 在目标平台上百分之百、最优性能地物理实例化。
┌──────────────────────┐
│ 统一逻辑 DSL (L-DSL) │
└──────────┬───────────┘
│ (接收契约)
▼
┌───────────────────────────────────────────────────────────────────────────┐
│ 工程实施 Swarm (以飞书为例) │
│ │
│ 1. 平台能力映射规划 (Physical Planner) │
│ - "ONE_TO_MANY" 映射为：多维表格的关联字段 (Link Field) + 双向引用 │
│ - "KPI_CARD" 映射为：多维表格仪表盘 (Bitable Dashboard Chart Block) │
│ │
│ 2. API/CLI 编排与调用 (Lark CLI Execution) │
│ - 规划串行/并行 DDL，计算建表顺序（先建 contract，后建 payment 并建 Link） │
│ - 处理并发写入速率限制 (Rate Limit Retry Backoff) │
│ │
│ 3. 协同门户拼装 (Lark UI Designer) │
│ - 调用 `lark-cli docs` 创建 Docx 文档作为入口 │
│ - 获取多维表格的 Form Block ID 与 Grid Block ID，依次注入 Docx │
└───────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ 飞书中的运行实例 │
└──────────────────────┘3.1 以飞书生态为例的映射与执行规划表
| 逻辑概念 (L-DSL) | 飞书物理映射方案 (Engineering Mapping) | 飞书 CLI 执行细节 (Feishu CLI Implementation) |
|---|---|---|
| Entity (数据表) | 多维表格中的 Table | lark-cli base table create --app-token "..." --table-name "xxx" |
| ONE_TO_MANY (关联关系) | 飞书多维表格的 关联字段 (Type: 18) | 1. 建立 contract 表与 payment 表； 2. 在 payment 表中创建关联 contract 的字段； 3. 在 contract 表中配置单向/双向关联。 |
| Workflow (流程转移) | 飞书审批 (Approval V2) + 多维表格自动化流 | 1. 创建飞书审批定义 (Approval Definition)； 2. 建立 Bitable Webhook 触发器； 3. 审批通过后通过 CLI 回写状态。 |
| Portal Layout (页面布局) | 飞书富文本新版文档 (Docx Block) | 1. lark-cli docs +create 生成一个说明文档； 2. 获取 Bitable 视图对应的 block_id； 3. 拼装为 Markdown 语法注入文档，形成无缝门户。 |
四、双向握手协议 (The Handshake & Alignment Protocols)
两个 Swarm 之间在发生改变时，依靠以下两个关键握手协议维持整个生命周期的闭环：
4.1 正向握手：从设计到部署 (L2P Handshake)
- 握手触发：业务需求 Swarm 完成模型、流程和仪表盘的设计，输出 L_DSL_v1 并向消息总线广播。
- 工程认领：
- 如果用户环境是飞书，飞书实施 Agent 接收 L_DSL_v1；
- 如果用户环境是简道云，简道云实施 Agent 接收。
- 物理规划：实施 Agent 对 L_DSL_v1 进行完整性校验。如果通过，根据其依赖关系拓扑排序（Topological Sort）计算 DDL 步骤并依次调用 API 执行，完成交付。
4.2 反向握手：遥测采集与 ML 反馈闭环 (P2L Handshake)
这是当用户在零代码平台的可视化界面手动修改了配置时，触发的反向对齐协议。
┌─────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ 1. 物理层变更事件│ ────> │ 2. 实施端翻译网关 │ ────> │ 3. 产生逻辑 Delta │
│ (飞书 Field.Type│ │ (将物理差异翻译为 │ │ (Logical-Diff) │
│ 3 改为 11) │ │ 平台无关的语义) │ │ │
└─────────────────┘ └────────────────────┘ └─────────┬──────────┘
│
▼
┌─────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ 6. 形成 DPO 语料 │ <──── │ 5. 提示词增强 / RAG│ <──── │ 4. 业务需求 Swarm │
│ (完成模型进化) │ │ (写入上下文长期记忆)│ │ 重载逻辑模型 │
└─────────────────┘ └────────────────────┘ └────────────────────┘物理事件捕获：用户在飞书界面中，把"付款金额"从"单行文本格式（TEXT）"修改为了"数字格式（NUMBER）"。飞书事件监听器捕获：
bitable.table.field.updated_v1: { field_name: "付款金额", type: 2 }实施端翻译网关：飞书实施 Agent 识别到这一物理变更，由于它拥有"物理-逻辑"映射字典，它将其翻译为语义化的修改意图：
{"action": "UPDATE_PROPERTY", "entity": "payment", "property": "pay_amount", "to_type": "DECIMAL"}业务需求端重载：翻译后的标准 Logical-Diff 发送给业务需求 Swarm。业务需求 Swarm 的模型中，将合同金额的逻辑定义从 STRING 更新为 DECIMAL，保证下一次基于该模型对话时，AI 的脑子和真实的物理数据库是一致的。
将该物理差异 (TEXT -> DECIMAL) 打包成 DPO (Direct Preference Optimization) 训练语料对，训练业务需求 Swarm 里的"表单建模 Agent"，使其下次面对类似"金额、单价、款项"等名词时，默认生成 DECIMAL 而非 STRING。
