AnyClaw Cloud Marketplace Architecture Design Document

[TheShigure7]

AnyClaw 云端市场架构设计文档

1. 文档目标

本文档定义 AnyClaw 云端市场的统一架构视图，回答：

1. 云端市场系统分几层。
2. 云端和本地如何分工。
3. 完整模块清单是什么。
4. 模块之间如何协作。

---

2. 总体架构原则

2.1 独立 Registry，客户端消费

云端市场本身是独立服务。

AnyClaw、OpenClaw 等是客户端。

2.2 云端供给，本地执行

云端负责：

• 目录
• 检索
• 分发
• 版本
• 信任

本地负责：

• 最终筛选
• 安装
• 注册
• 热加载
• 任务恢复

2.3 市场协议中立化

云端返回的是通用包信息，不携带 AnyClaw 私有运行态语义。

例如云端可暴露：

• package_id
• kind
• version
• manifest
• tags
• dependencies
• risk_level
• download_url

但不应承载：

• session 内部状态
• 本地 runtime 内部对象标识
• 本地审批单内部状态机

---

3. 架构分层

3.1 云端层

• Catalog Service
• Search / Retrieval Service
• Package Registry Service
• Release / Version Management Service
• Distribution Service
• Publisher / Review Service
• Trust / Signature / Audit Service
• Metadata / Tagging / Embedding Builder
• Database
• Object Storage

3.2 本地市场消费层

• Market Client
• Capability Resolver / Selector
• Installer
• Installed Registry
• Runtime Loader / Activation
• Approval / Silent Install Policy

3.3 展示层

• Desktop Shell Market UI

---

4. 总体模块图

flowchart TB
    subgraph CLOUD["云端 Registry"]
        CATALOG["Catalog Service"]
        SEARCH["Search / Retrieval"]
        PKG["Package Registry"]
        RELEASE["Release / Version"]
        DIST["Distribution"]
        PUB["Publisher / Review"]
        TRUST["Trust / Audit"]
        META["Metadata / Tagging / Embedding"]
        DB["Database"]
        OBJ["Object Storage"]
    end

    subgraph LOCAL["AnyClaw 本地"]
        CLIENT["Market Client"]
        SELECTOR["Capability Resolver / Selector"]
        INSTALLER["Installer"]
        INSTALLED["Installed Registry"]
        LOADER["Runtime Loader / Activation"]
        POLICY["Approval / Silent Install Policy"]
    end

    subgraph UI["展示层"]
        SHELL["Desktop Shell Market UI"]
    end

    SHELL --> CATALOG
    SHELL --> CLIENT
    CLIENT --> CATALOG
    CLIENT --> SEARCH
    CLIENT --> PKG
    CLIENT --> RELEASE
    CLIENT --> DIST
    SELECTOR --> CLIENT
    SELECTOR --> POLICY
    INSTALLER --> DIST
    INSTALLER --> INSTALLED
    INSTALLER --> LOADER
    PKG --> DB
    RELEASE --> DB
    CATALOG --> DB
    SEARCH --> DB
    SEARCH --> META
    PUB --> DB
    TRUST --> DB
    DIST --> OBJ

Loading

---

5. 核心执行链路

5.1 手动安装链路

sequenceDiagram
    participant UI as Desktop Shell
    participant API as Cloud Registry
    participant MC as Market Client
    participant IN as Installer
    participant RL as Runtime Loader

    UI->>API: 搜索/查看详情
    API-->>UI: 返回包列表与详情
    UI->>MC: 请求安装 package
    MC->>API: resolve + download metadata
    API-->>MC: 返回版本/下载地址/checksum
    MC->>IN: 执行安装
    IN->>IN: 下载/校验/解压
    IN->>RL: 注册并加载
    RL-->>UI: 返回已安装状态

Loading

5.2 自动补能链路

sequenceDiagram
    participant AG as Main Agent
    participant SEL as Resolver / Selector
    participant MC as Market Client
    participant API as Cloud Registry
    participant IN as Installer
    participant RL as Runtime Loader

    AG->>SEL: 当前任务缺能力
    SEL->>MC: 发起市场搜索
    MC->>API: search
    API-->>MC: 候选包列表
    MC-->>SEL: 候选包+score
    SEL->>SEL: 本地过滤与决策
    alt Auto
        SEL->>IN: 安装目标包
        IN->>RL: 安装并加载
        RL-->>AG: 新能力可用
        AG->>AG: 继续原任务
    else Ask
        SEL-->>AG: 返回候选供用户确认
    else Block
        SEL-->>AG: 返回阻断原因
    end

Loading

---

6. 模块关系说明

6.1 Catalog Service 与 Search / Retrieval 的关系

• Catalog 负责“给目录与详情”。
• Search / Retrieval 负责“按条件和语义找候选”。
• 两者相关，但不应混成一个大模块。

6.2 Package Registry 与 Release / Version 的关系

• Package Registry 负责包的逻辑实体。
• Release / Version 负责包的版本、checksum、manifest、changelog。

6.3 Distribution 与 Object Storage 的关系

• Distribution 负责下载控制、令牌、URL 生成、访问策略。
• Object Storage 负责真正存文件。

6.4 Installer 与 Installed Registry 的关系

• Installer 负责下载、校验、解压、回滚。
• Installed Registry 负责记录本地已安装状态和可见性。

6.5 Selector 与 Policy 的关系

• Selector 负责筛选和排序。
• Policy 负责是否允许自动安装、是否需要 Ask、是否直接 Block。

---

7. 接口文档在整体架构中的位置

当前 云端Skill与Agent市场接口设计.md 在整套架构里主要覆盖：

• Market Client 与云端 Registry 的主链路接口
• 包模型与安装模型

它目前没有完整覆盖：

• Publisher / Review Service
• Trust / Signature / Audit Service
• Distribution Service 的内部协议细节
• Installed Registry / Runtime Loader / Policy 的本地接口

因此它应被视为：

• 架构中的一部分接口设计

而不是：

• 整套系统的完整接口大全

---

8. 后续设计建议

基于本架构，后续应继续补齐：

1. 模块规格文档
2. 数据库设计文档
3. 对象存储与分发设计文档
4. 完整接口设计文档
5. 本地安装与运行时集成设计文档

一句话总结：

AnyClaw 云端市场的正确架构不是“桌面壳 + 一个数据库”，而是“独立云端 Registry + 本地消费闭环 + 展示层”的三层结构。