24 - OpenClaw 能力拓展平台 — 业务逻辑

更新日期：2026-04-19

1. 核心对象

• Tenant：购买方组织；其下 Workspace 对应一个或多个 OpenClaw 工作区标识（逻辑 ID，非强制绑定物理路径）。
• Asset：能力资产（技能包、MCP 包、记忆策略、组合包）。
• AssetVersion：不可变版本单元；发布、回滚、灰度的最小单位。
• Entitlement：租户对某 AssetVersion 的授权与配额。
• DeliveryBundle：交付给 OpenClaw 侧的文件集合 + 校验和 + 签名（可选）。
• AuditEvent：上架、发布、同步、失败、人工审批记录（类比 GEP 事件思路，字段从简）。

2. 资产状态机（简化）

• ISV/运营创建草稿 → 提交评审 → 通过后上架 published。
• 租户仅可见已授权且未废弃版本；紧急下架可走运营强制 deprecated（联动通知）。

3. 定制交付流（可选模块）

本节为 P2 模块，当前设计稿 v0.2，补全状态机、角色、字段、接口与数据库表。

3.1 工单核心实体

3.2 工单状态机

紧急路径：运营可直接将 submitted → in_progress（跳过报价，紧急需求）。

3.3 工单字段明细

CustomOrder 主表

CustomOrderMilestone 里程碑

CustomOrderMessage 沟通记录

CustomOrderAttachment 附件

CustomOrderAudit 审计

3.4 角色权限

3.5 完整业务流程

┌─────────────────────────────────────────────────────────────────────────────┐
│                           定制工单全生命周期                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1️⃣ 需求发起                                                               │
│  租户管理员 → 填写工单（标题/类型/需求描述/OpenClaw版本/合规要求）           │
│  → 保存草稿 draft                                                          │
│                                                                             │
│  2️⃣ 需求提交                                                               │
│  → 提交 submitted                                                          │
│  → 系统自动校验（类型必填、描述非空、合规字段格式）                           │
│  → 进入 pending_review 运营队列                                             │
│                                                                             │
│  3️⃣ 运营评审                                                               │
│  → 运营初审：确认需求清晰度、是否在服务范围内                                │
│  → 若不清晰：驳回 draft（附原因），租户补充                                 │
│  → 若可接：进入 quoting                                                     │
│                                                                             │
│  4️⃣ 报价                                                                   │
│  → 运营填写报价工时（人天）和金额                                            │
│  → 设置报价有效期 expire_at（默认 7 天）                                    │
│  → 发送报价给客户确认                                                       │
│                                                                             │
│  5️⃣ 客户确认                                                               │
│  → 租户确认 → confirmed（填写 isv_id 若运营已指派）                         │
│  → 拒绝 → cancelled（附原因）                                              │
│  → 超时 → cancelled（系统自动）                                           │
│                                                                             │
│  6️⃣ ISV 接单与交付                                                         │
│  → ISV 接单 → in_progress                                                 │
│  → 创建里程碑列表（可多个，按顺序执行）                                      │
│  → 每个里程碑：in_progress → review → passed/rejected                       │
│  → 全部通过 → delivered（自动生成 DeliveryBundle）                         │
│                                                                             │
│  7️⃣ 最终验收                                                               │
│  → 租户最终确认 → completed                                                │
│  → 可选：客户评分 + 反馈                                                   │
│  → 若有争议 → disputed → 争议解决 → completed 或 cancelled                 │
│                                                                             │
│  8️⃣ 交付物归档                                                             │
│  → DeliveryBundle 关联工单编号                                             │
│  → AuditEvent 记录完整的交付链                                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

3.6 接口清单（工单与任务）

3.7 与 DeliveryBundle 的关联

CustomOrder (confirmed)
    │
    ├─ milestone_1 ──→ [ISV 交付] ──→ DeliveryBundle ──→ AuditEvent(skill_published)
    ├─ milestone_2 ──→ [ISV 交付] ──→ DeliveryBundle ──→ AuditEvent
    └─ milestone_N ──→ [ISV 交付] ──→ DeliveryBundle ──→ AuditEvent

最终 DeliveryBundle 合并为完整定制包

• 每个里程碑 passed 后，ISV 上传交付物 ZIP
• 系统生成 DeliveryBundle，关联 occap_asset_version（若需上架）
• 工单 delivered 时，汇总所有里程碑交付物为一个最终包

3.8 任务系统（Task，比工单更轻量）

用于 平台运营内部任务分发、ISV 里程碑协作、人机协作任务，与工单共用审计框架但独立运行。

任务分页：POST /admin/occapTask/page（与工单解耦，独立接口）

3.9 通知机制

通知渠道可扩展：飞书机器人 / Slack / 企业微信（配置项）。

4. 记忆分层与同步

红线：含 密钥、token、身份证、未脱敏联系方式 的内容不得进入向量索引与对外样例。

5. 搜索与审计

• 业务搜索：按资产类型、标签、风险、租户可见性过滤。
• 语义搜索：仅对允许索引的字段建 embedding；查询记 search_audit（租户、延迟、是否命中缓存）。
• 观测搜索：按 error_signature、bundle_id、时间范围检索，支持运营复盘。

6. 权限矩阵（摘要）

7. 非目标

• 平台侧远程执行用户 MCP 工具。
• 无确认自动覆盖用户 OpenClaw 目录。

8. 业务架构（域边界）

与《需求评估文档》§四「业务架构」索引一致：下列域在组织与数据上解耦，经 Entitlement 与 DeliveryBundle 耦合。

9. 应用架构与逻辑视图（平台 ↔ OpenClaw 宿主）

• 平台进程：Cool Admin Midway 提供 REST、权限、计费、元数据与包存储；不托管用户 MCP 运行时。
• OpenClaw 宿主：用户工作区内的 CLI/脚本消费 DeliveryBundle，合并 skills / MCP manifest / 记忆策略片段。
• 集成边界：平台输出 签名（可选）+ 校验和 + 审计 ID；宿主侧合并前可运行校验脚本。

10. 场景视图（用例锚点）

主场景与 interaction_map.html 中流程一致，摘要如下：

11. 处理视图（关键控制流）

评审通过（简化时序）：

高并发与稳定性保护（与 L1/L2 档位联动）

• API：租户级 + IP 限流；搜索与导出走独立速率桶；热点列表走 Redis 短缓存。
• 搜索：防抖与查询长度上限；向量路径异步或独立超时，避免拖死主线程池。
• 写路径：Entitlement / 评审状态变更单表乐观锁或版本号，避免并发覆盖。
• 包下载：预签名 URL + 短 TTL；大文件走 CDN/OSS，应用层只做鉴权与审计。
• 降级：向量服务不可用时回退关键字检索，并在响应头或审计中标记 degraded=true（实现约定）。

12. 多身份与页面职责（摘要）

与 skills_distribution.md、page_structure.md 一致：平台运营 / 租户管理员 / 租户成员 / ISV / 审计只读 / Agent 主体 在 上传、管理、购买订阅、平台分发、定制、任务收发 上的权限边界见该文档 §1–§2；本文不重复表格。

13. Skills 分发与检索策略

• 索引分层：业务表（资产元数据）→ 全文/倒排 → 可选向量；租户 ID + Entitlement 为硬过滤条件。
• 可见性：public / tenant_private / channel_canary 与分发配置联动；Agent 检索单独记 principal_type。
• 排序：相关性 + 运营权重 + 风险惩罚因子（高危未审降权）。
• 缓存：热点列表短 TTL；失效在授权变更、版本上下架、分发配置变更时按租户维度失效。

14. Agent 自发布 / 自订阅（业务规则）

• 主体：occap_agent_principal 与 Workspace 指纹 绑定；与人类账号分域。
• 发布：内容须先 upload/init 直传；publish 仅引用 uploadId + manifest；默认进入 待审或机器快车道（策略表）。
• 订阅：仅允许订阅 已授权租户可见 的 assetVersionId；写 Entitlement 或 Capability Slot 子表（实现期二选一或并存）。
• 人机共审：risk >= high 或 策略命中 时强制进入人工评审队列。

15. 贡献点（CP）与批次结算（类比特币隐喻 · 非链）

• 非加密货币：无法币链上转账；CP 为平台内积分/权益计量，法币结算仍走支付与合同。
• 事件入账：publish_reward、subscribe_share、task_bonus、penalty 等类型写入 occap_contribution_ledger（不可改，仅追加）。
• 批次（Block）：定时或按条数滚动 occap_settlement_batch，聚合本批事件 ID 计算 MerkleRoot，关账后批次冻结（类比「出块确认」）。
• 难度调整（产品化）：若 事故率 / 驳回率 超阈，提高 评审轮次或冷却时间（类比「全网难度」），由运营策略表驱动。
• 对账：运营可按 batchId + MerkleRoot 与明细导出对账；审计只读可全量查流水。

16. 认证与会话

16.1 登录方式

• 账号密码登录（平台账号）
• 飞书 SSO（OAuth2，由飞书应用管理）
• API Key（给 Agent / ISV 机器身份用）

16.2 平台账号体系

16.3 Session 与 Token

• Web 会话：Session ID 存 Cookie，JWT 存 RefreshToken，Redis 中存 Session 状态（TTL 7 天）。
• API Key：HMAC-SHA256 签名，用于 Agent / ISV 接口调用，无 Session。
• Token 结构（JWT）：user_id, role, tenant_id, exp, iat。

16.4 权限控制（RBAC）

角色：

• platform_super：平台超级管理员，拥有所有权限
• platform_ops：平台运营，可管理租户/评审/套餐/分发/工单
• tenant_admin：租户管理员，可管理本租户成员/授权/工单/记忆策略
• tenant_member：租户成员，可浏览市场/订阅/上传/任务
• isv：ISV，可提交资产/接单/里程碑交付
• audit_readonly：只读审计，可查看所有审计记录
• agent_principal：Agent 机器身份，权限最小化，按配额限制

接口级权限：所有管理端接口 /admin/occap*/ 需要 platform_ops 或 tenant_admin（本租户范围）；开放接口 /open/v1/ 按 API Key Role 鉴权。

17. 租户与套餐

17.1 租户实体

17.2 套餐实体

quota_json 配额模板示例：

{
  "max_members": 10,
  "max_asset_count": 50,
  "max_entitlements": 20,
  "search_quota_monthly": 10000,
  "embedding_quota_monthly": 5000,
  "custom_order_quota": 5,
  "storage_quota_gb": 10
}

17.3 租户状态机

17.4 Workspace 关联

• 一个租户可绑定多个 OpenClaw Workspace（逻辑 ID）
• Workspace 与租户解耦：平台只存标识符，不直接读写用户本地目录

18. 资产与版本

18.1 资产主表

索引：slug(唯一), (status, type), (visibility, risk_level), tenant_id

18.2 资产版本表

索引：(asset_id, version)(唯一), (asset_id, status)

18.3 资产状态机（详细版）

快通道条件（同时满足）：

• risk_level = low
• official_review_required = false
• ISV 信用分 ≥ 阈值（运营策略表控制）

18.4 依赖与风险标签

// manifest_json 示例
{
  "name": "风控技能包",
  "version": "1.0.0",
  "requires": [
    {"type": "skill", "slug": "openclaw-risk-core", "version": ">=1.0.0"},
    {"type": "mcp_bundle", "slug": "data-fetcher", "version": ">=0.9.0"}
  ],
  "permissions": ["file_read", "http_request"],
  "risk_flags": ["network_io", "file_write"],
  "homepage": "https://..."
}

19. 授权 Entitlement

19.1 Entitlement 实体

索引：(tenant_id, asset_version_id)(唯一), tenant_id, status, expired_at

19.2 授权生命周期

Entitlement 创建 → active（生效）
    → 过期 expired（自然过期或欠费）
    → 撤销 revoked（运营手动撤销或违规）

授权后动作：

1. 租户门户「我的订阅」中可见该资产
2. ISV 收到「被订阅」通知
3. 触发 CP 贡献点入账（ISV 的 subscribe_share）
4. AuditEvent 记录

19.3 套餐切换时的 Entitlement 处理

19.4 Capability Slot（能力槽位）

用于 Agent 订阅场景：一个 Slot 映射到一个 AssetVersion + 配额限制。

20. 交付包 DeliveryBundle

20.1 DeliveryBundle 实体

20.2 交付流程

DeliveryBundle 创建（平台）
    → 预签名 URL 生成（TTL=15min）
    → 租户下载 / CLI 拉取
    → 下载完成（status=downloaded）
    → 合并到 OpenClaw 工作区（status=applied）
    → 失败可凭 bundle_id 查 AuditEvent 追溯

20.3 CLI 拉取脚本（伪代码）

#!/bin/bash
BUNDLE_ID=$1
CHECKSUM=$2
TMP_ZIP="/tmp/occap_bundle_${BUNDLE_ID}.zip"

# 1. 拉取包
curl -L "https://api.platform.com/open/v1/bundle/${BUNDLE_ID}/download?token=${DOWNLOAD_TOKEN}" -o $TMP_ZIP

# 2. 校验完整性
ACTUAL_SHA=$(sha256sum $TMP_ZIP | cut -d' ' -f1)
if [ "$ACTUAL_SHA" != "$CHECKSUM" ]; then
  echo "CHECKSUM_MISMATCH"
  exit 1
fi

# 3. 解压到 OpenClaw skills/ 目录
SKILLS_DIR="${OPENCLAW_WORKSPACE}/skills"
mkdir -p $SKILLS_DIR
unzip -o $TMP_ZIP -d $SKILLS_DIR

# 4. 注册 manifest（示例）
# echo "BUNDLE_APPLIED:${BUNDLE_ID}" >> ${OPENCLAW_WORKSPACE}/.occap_applied
echo "OK"