统一 Artifacts 模型规范 v0.1

版本：0.1
状态：草案
适用对象：第三方 Agent 开发者、平台安装器开发者、测试同学
目标：定义 manifest 中 artifacts 的统一表达方式，让平台可以声明式处理包内文件、远程下载、压缩包、目录和外部服务声明。

1. 目标

artifacts 描述第三方 Agent 包需要落地或声明的资源。平台必须根据 artifacts[].kind 和 artifacts[].source.kind 选择处理器，不得根据 artifact 名称猜测处理逻辑。

Artifacts 模型解决以下问题：

包内二进制如何复制到安装目录。
模型文件如何落到共享目录。
远程压缩包如何下载、校验、解压并暴露可执行文件。
Skill 目录和普通目录如何区分职责。
外部服务依赖如何声明但不默认执行。

2. 支持的 kind

kind	含义	典型用途
`binary`	可执行二进制文件	服务主程序、辅助程序。
`file`	单个文件资源	模型文件、配置片段、文本资源。
`directory`	目录资源	预置资源目录、工具目录。
`archive`	压缩包资源	`ffmpeg`、运行时工具包。
`service`	外部服务依赖声明	外部模型 API、对象存储、代理服务。

Electron v0.1 Profile：

binary、file、directory、archive 会执行本地准备。
service 只识别、持久化、诊断，不执行 endpoint 检查或认证配置。

3. 通用字段

yaml

artifacts:
  - id: ffmpeg-win32
    kind: archive
    name: ffmpeg
    required: true
    source:
      kind: download
      url: https://example.com/ffmpeg.zip
      archive: zip
      extract: true
      strip_components: 0
      checksum:
        algorithm: sha256
        value: "<sha256>"
    target: "{package_shared_dir}/bin/ffmpeg"
    bins:
      - ffmpeg.exe

字段	必填	说明
`id`	是	artifact 唯一标识。
`kind`	是	`binary`、`file`、`directory`、`archive`、`service`。
`name`	是	人类可读名称。
`required`	是	是否为必需资源。
`source`	条件必填	资源来源。`service` 可使用外部服务声明。
`target`	条件必填	落地路径或解压目录。`service` 不需要。
`bins`	条件必填	需要暴露的可执行文件。archive/directory 如需引用 bin 必须声明。
`version`	否	artifact 自身版本。
`description`	否	用途说明。
`platform`	否	支持平台声明。

Electron v0.1 命名约束：

text

artifact id: ^[a-z0-9]+(?:-[a-z0-9]+)*$

平台不得自动修正非法 id。

4. Source

4.1 embedded

yaml

source:
  kind: embedded
  path: payload/llama-server/llama-server.exe

规则：

path 必须是相对包根目录的路径。
禁止绝对路径。
禁止 .. 路径穿越。
解析后必须位于解压包根目录内。
实际文件类型必须匹配 artifact kind。

4.2 download

yaml

source:
  kind: download
  url: https://example.com/ffmpeg-release-full.zip
  archive: zip
  extract: true
  strip_components: 0
  checksum:
    algorithm: sha256
    value: "<sha256>"

规则：

url 必须声明。
必须声明 checksum。
checksum 推荐且 Electron v0.1 强制使用 sha256。
如果是 archive，必须声明 archive、extract、strip_components。

Electron v0.1 Profile：

只支持 HTTPS download。
只支持 sha256。
artifact download 原始文件不缓存，只保留最终输出。
artifact downloads 可并发执行。

4.3 service

service 用于声明外部服务依赖，不代表平台必须创建或连接该服务。

yaml

artifacts:
  - id: external-model
    kind: service
    name: external model service
    required: false
    service:
      provider: openai-compatible
      endpoint_env: HIGHLIGHT_MODEL_BASE_URL
      api_key_env: HIGHLIGHT_MODEL_API_KEY
      timeout_seconds: 60
      privacy:
        sends_raw_private_data: false

Electron v0.1 Profile：

service 只进入 registry 和 diagnostics。
不执行 endpoint 检查。
不写认证配置。
不扩大网络权限。

5. Target

artifact target 表示资源最终落地路径。

Base Spec 支持通过平台 Profile 限定可写根目录。

Electron v0.1 Profile：

target 只允许 {install_dir} 和 {package_shared_dir}。
target 禁止 {user_data}。
target 不允许绝对路径。
target 不允许路径穿越。
Skill 目录通过 skills.load.extraDirs 引用，artifact 不得直接写 ~/.openclaw/skills。

5.1 Config 与 assets

配置模板和生成配置不通过 artifact 机制管理，而是由 manifest 的 config 字段和 render-config install step 处理。

为满足 AgentSkills 规范要求（Skill 只能通过相对路径访问自身目录内文件），config.output 必须指向 Skill 目录的 assets/ 下。安装完成后 Skill 可通过相对路径 assets/config.json 直接读取配置，无需依赖外部路径发现机制。

6. kind 处理规则

6.1 binary

yaml

artifacts:
  - id: highlight-service
    kind: binary
    name: service.exe
    required: true
    source:
      kind: embedded
      path: payload/service.exe
    target: "{install_dir}/payload/service.exe"

规则：

source 必须是文件。
target 表示目标文件路径。
Electron v0.1 自动把 binary 的 basename 暴露为 bin。

6.2 file

yaml

artifacts:
  - id: model-q4
    kind: file
    name: model-Q4_K_M.gguf
    required: true
    source:
      kind: embedded
      path: payload/models/model-Q4_K_M.gguf
    target: "{package_shared_dir}/models/model-Q4_K_M.gguf"

规则：

source 必须是文件。
target 表示目标文件路径。
file 不自动暴露 bin。

6.3 directory

yaml

artifacts:
  - id: tools
    kind: directory
    name: tools
    required: false
    source:
      kind: embedded
      path: payload/tools
    target: "{install_dir}/tools"
    bins:
      - helper.exe

规则：

source 必须是目录。
复制 source 目录的内容到 target。
不在 target 下额外创建 source basename。
如声明 bins，必须在 target 内存在。

Skill 注册不应通过 directory artifact 的 post_install 驱动。Skill 发现由 manifest 顶层 skills 字段驱动，平台扫描 skills 目录并通过 skills.load.extraDirs 引用，不复制到 ~/.openclaw/skills。

6.4 archive

yaml

artifacts:
  - id: ffmpeg-win32
    kind: archive
    name: ffmpeg
    required: true
    source:
      kind: download
      url: https://example.com/ffmpeg-release-full.zip
      archive: zip
      extract: true
      strip_components: 0
      checksum:
        algorithm: sha256
        value: "<sha256>"
    target: "{package_shared_dir}/bin/ffmpeg"
    bins:
      - ffmpeg.exe

规则：

archive target 表示解压目标目录。
解压前必须检查压缩包条目，防止路径穿越。
解压后不得接受 symlink。
bins 必须显式声明并强校验。

Electron v0.1 Profile：

只支持 zip。
必须 extract: true。
支持 strip_components，必须为非负整数。
不支持 extract: false 的 archive；如只需保存压缩包，应使用 file。

6.5 service

service 不落地文件，用于描述外部依赖。

Electron v0.1 仅将其写入 registry 和 diagnostics，不执行任何外部操作。

7. Artifact Outputs

平台安装后应生成 artifact outputs：

type ArtifactOutput = {
  id: string;
  kind: string;
  path: string;
  bins?: Record<string, string>;
};

placeholder 解析规则：

{artifact:<id>:path} 返回 artifact output 的 path。
{artifact:<id>:bin:<name>} 返回 bins[name]。
未找到 output 或 bin 时，placeholder 无法解析，安装失败。

8. required / optional 失败语义

场景	行为
`required: true` 下载失败	安装失败。
`required: true` checksum 失败	安装失败。
`required: true` 解压或 bins 缺失	安装失败。
`required: false` 准备失败	记录 warning，继续安装。
optional artifact 被 config 引用	如果 output 缺失，config render 失败，安装失败。

Electron v0.1 Profile：

required artifact 失败后，取消尚未开始的 artifact download。
对进行中的 fetch 使用 best-effort AbortController。
等待已开始任务 settle 后统一回滚。

9. 并发下载

Base Spec 不要求并发下载，但平台可实现下载队列。

Electron v0.1 Profile：

只有 artifact downloads 并发。
顶层 package zip download 不并发。
install/uninstall/activate 仍全局串行。
默认 maxConcurrent: 3。
下载测试不得依赖真实外网。

10. 禁止项

不得根据 artifact 名称推断处理逻辑。
不得在 checksum 缺失时下载正式 artifact。
不得让 artifact target 写出平台允许目录。
不得让 directory artifact 绕过 Skill registrar 注册 Skill。
不得在 post_install 中隐藏关键安装逻辑。

Electron v0.1 不支持 artifact post_install。配置写入必须通过 config.placeholders 和 {artifact:<id>:...} 完成。

统一 Artifacts 模型规范 v0.1 ​

1. 目标 ​

2. 支持的 kind ​

3. 通用字段 ​

4. Source ​

4.1 embedded ​

4.2 download ​

4.3 service ​

5. Target ​

5.1 Config 与 assets ​

6. kind 处理规则 ​

6.1 binary ​

6.2 file ​

6.3 directory ​

6.4 archive ​

6.5 service ​

7. Artifact Outputs ​

8. required / optional 失败语义 ​

9. 并发下载 ​

10. 禁止项 ​

统一 Artifacts 模型规范 v0.1

1. 目标

2. 支持的 kind

3. 通用字段

4. Source

4.1 embedded

4.2 download

4.3 service

5. Target

5.1 Config 与 assets

6. kind 处理规则

6.1 binary

6.2 file

6.3 directory

6.4 archive

6.5 service

7. Artifact Outputs

8. required / optional 失败语义

9. 并发下载

10. 禁止项