> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 附件与 Skills

Agent Run 可以携带图片、视频、普通文件、ZIP 素材附件和显式 Skill 选择。普通文件使用 URL 附件；ZIP 使用独立的上传、确认及 `kind: archive` 引用流程；自定义 Skill 包（`.zip` / `.skill`）必须先通过 Skills API 上传。

## 附件来源与上传方式

| 文件位置                 | 推荐方式                                                      |
| :------------------- | :-------------------------------------------------------- |
| 普通文件已有公网 HTTP(S) URL | 直接放入 `attachments[ ].url`                                 |
| 普通文件仅存在于本地设备或私有服务    | 先通过 `agent/uploads` 签发票据并上传，再使用返回的 `file_url`             |
| ZIP 素材附件             | 通过 `agent/archives` 申请票据，PUT 上传并 confirm 后使用 `archive_id` |

Meoo 会拒绝本地、私网和链路本地地址。普通 URL 附件必须能被服务端访问，实际下载响应执行 50 MiB 上限。ZIP 的压缩包上传限额按账号权益及返回的 `max_size_bytes` 判断，见下方「ZIP 附件上传与处理」。

## Run 附件 Schema

`attachments` 合计 1～10 项，按 `kind` 使用严格对象 Schema。

### 图片或视频

```text
{
  "kind": "image",
  "url": "https://cdn.example.com/reference.png"
}
```

`kind=image` 或 `video` 时只允许 `kind`、`url`，不能携带 `filename` 或 `type`。

### 普通文件

```text
{
  "kind": "file",
  "url": "https://cdn.example.com/requirements.pdf",
  "filename": "requirements.pdf",
  "type": "application/pdf"
}
```

| 字段         | 约束                                    |
| :--------- | :------------------------------------ |
| `url`      | HTTP(S) URL，最长 4096 字符                |
| `filename` | 1～255 字符，不含目录路径；不支持 `.zip` 和 `.skill` |
| `type`     | 可选的合法 MIME type，最长 255 字符             |

### ZIP 素材附件

```json
{ "kind": "archive", "archive_id": "123456789" }
```

只允许 `kind`、`archive_id`；不能携带 `url`、`filename` 或 `type`。`archive_id` 使用确认上传接口返回的字符串，每次 Run 最多一个 ZIP。

## 签发普通附件直传票据

```text
POST /projects/{project_id}/agent/uploads
```

所需权限：`agent.run`

```text
curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/uploads" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "requirements.pdf",
    "type": "application/pdf",
    "size": 102400
  }'
```

| 字段         | 必填 | 说明                                  |
| :--------- | :- | :---------------------------------- |
| `filename` | 是  | 1～255 字符，不含路径，不支持 `.zip` / `.skill` |
| `size`     | 是  | 声明的字节数，最小 1，默认上限 50MB               |
| `type`     | 否  | 缺省 `application/octet-stream`       |

允许的 `type` 包括 `image/*`、`video/*`、`audio/*`、`text/*`，以及 `application/pdf`、`application/json`、`application/octet-stream`。

响应：

```text
{
  "upload_id": "upload_01JEXAMPLE",
  "upload_url": "https://storage.example.com/signed-put",
  "file_url": "https://storage.example.com/signed-get",
  "upload_expires_at": 1785900000000,
  "file_expires_at": 1785903600000
}
```

使用步骤：

- 步骤 1：对 `upload_url` 发起一次 HTTP `PUT`。
- 步骤 2：`Content-Type` 必须与签发票据时的 `type` 相同；未传时用 `application/octet-stream`。
- 步骤 3：上传完成后，把 `file_url` 放入 Run 的 `attachments[ ].url`。
- 步骤 4：两个签名 URL 过期后重新签发，不要长期保存。

```text
curl --request PUT \
  --upload-file ./requirements.pdf \
  --header "Content-Type: application/pdf" \
  "${UPLOAD_URL}"
```

`upload_url` 和 `file_url` 使用随机对象路径，但服务端不承诺签名 URL 强制 single-use。不要把地址交给无关调用方，也不要依赖它可重复使用。

`size` 是准入时的调用方声明值，不是存储侧强制的实际字节数；请填写真实大小。无论声明值如何，Agent 下载实际响应时仍执行 50 MiB 上限。

## 带附件启动 Run

```text
{
  "message": "参考图片和需求文档创建活动报名网站",
  "attachments": [
    {
      "kind": "image",
      "url": "https://cdn.example.com/reference.png"
    },
    {
      "kind": "file",
      "url": "https://storage.example.com/signed-get",
      "filename": "requirements.pdf",
      "type": "application/pdf"
    }
  ]
}
```

## ZIP 附件上传与处理

ZIP 使用独立的 `archives` 上传与确认流程；`agent/uploads` 和 `kind: file` 不接受 ZIP。以下接口均以 `/open/v1` 为前缀，签发票据、确认上传和启动 Run 都需要 `agent.run`。

### 1. 申请 ZIP 上传票据

```text
POST /projects/{project_id}/agent/archives
```

`filename` 为不含目录路径的 ZIP 文件名；`size` 为文件的真实字节数（正整数）。例如：

```json
{ "filename": "materials.zip", "size": 102400 }
```

调用示例（请将 `size` 替换为实际字节数）：

```bash
curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/archives" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"filename":"materials.zip","size":102400}'
```

响应示例：

```json
{
  "archive_id": "123456789",
  "upload_url": "https://storage.example.com/signed-put",
  "upload_expires_at": 1785900000000,
  "max_size_bytes": 524288000
}
```

`archive_id` 必须作为字符串保存。`upload_expires_at` 为 Unix 毫秒时间戳；URL 过期后应重新申请票据。单个 ZIP 的压缩包大小受账号上传权益限制，以本次响应的 `max_size_bytes` 为准：权益允许时支持 500 MiB，缺省为 50 MiB，不应为所有账号硬编码 500 MiB。

### 2. 向签名地址 PUT 上传

```bash
curl --request PUT \
  --upload-file ./materials.zip \
  --header "Content-Type: application/zip" \
  "${UPLOAD_URL}"
```

请求体为 ZIP 原始字节，`Content-Type` 必须为 `application/zip`。直接使用返回的 `upload_url`；向存储签名地址上传时，不要附带 Meoo 的 Bearer Token 或 API Key。签名 URL 不保证强制单次使用，上传后不要再覆盖原对象，也不要公开或写入日志。

### 3. 确认 ZIP 已上传

```text
POST /projects/{project_id}/agent/archives/{archive_id}/confirm
```

请求体可以省略，或发送空对象 `{}`：

```bash
curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/archives/${ARCHIVE_ID}/confirm" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{}'
```

服务端校验上传归属与存储中的实际文件大小。重复确认返回同一批次，不会重新创建或重置处理任务。响应：

```json
{ "attachment": { "kind": "archive", "archive_id": "123456789" } }
```

### 4. 携带返回的 attachment 启动 Run

将确认响应中的 `attachment` 原样放入 `attachments`：

```bash
curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: zip_message_001" \
  --data '{"message":"读取 ZIP 中的文件并整理内容","attachments":[{"kind":"archive","archive_id":"123456789"}]}'
```

以上 `archive_id` 为示例，实际使用确认响应中的值。网络重试同一消息时复用原幂等键；发送新消息时使用新值。

### 完整示例：本地 materials.zip 上传后用于 Run

假设当前目录已有一个普通素材压缩包 `materials.zip`，其中包含需要 Agent 读取的文档、图片等文件。下面使用新增的 `agent/archives` 接口完成：申请票据 → PUT 上传 ZIP → 确认上传 → 携带返回的附件启动 Run，共四次 HTTP 请求。

以下命令在同一个 Bash / zsh 终端中按顺序执行，需要 `curl` 和 Python 3。每一步成功后再执行下一步。所有 OpenAPI 请求使用同一调用方和同一个项目；凭证需要 `agent.run` 权限，订阅事件另需 `agent.read`。`PROJECT_ID` 填写项目的 `url_id`。

```bash
export MEOO_BASE_URL="https://meoo.com"
export ACCESS_TOKEN_OR_API_KEY="<替换为你的凭证>"
export PROJECT_ID="<替换为项目的 url_id>"
```

**步骤 1：读取真实文件大小，申请 ZIP 上传票据**

使用文件的实际字节数生成请求，避免手填 `size` 与本地文件不一致。

```bash
python3 - <<'PY'
import json
from pathlib import Path

zip_path = Path("materials.zip")
payload = {"filename": zip_path.name, "size": zip_path.stat().st_size}
if payload["size"] <= 0:
    raise SystemExit("materials.zip 不能为空")
Path("archive-upload-request.json").write_text(json.dumps(payload), encoding="utf-8")
PY

curl --fail-with-body --silent --show-error \
  --request POST "$MEOO_BASE_URL/open/v1/projects/$PROJECT_ID/agent/archives" \
  --header "Authorization: Bearer $ACCESS_TOKEN_OR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @archive-upload-request.json \
  --output archive-upload-ticket.json
```

成功响应包含 `archive_id`、`upload_url`、`upload_expires_at` 和 `max_size_bytes`。上传上限以本次响应为准；账号权益允许时可达 500 MiB。文件超过上限时，申请票据会返回 `413 artifact_too_large`。

**步骤 2：向 upload\_url PUT 上传原始 ZIP**

从响应自动提取地址和字符串 ID，再上传文件本身。签名上传地址已包含鉴权信息，PUT 请求只设置 `Content-Type: application/zip`。

```bash
ARCHIVE_ID=$(python3 -c 'import json; print(json.load(open("archive-upload-ticket.json"))["archive_id"])')
UPLOAD_URL=$(python3 -c 'import json; print(json.load(open("archive-upload-ticket.json"))["upload_url"])')

curl --fail-with-body --silent --show-error \
  --request PUT "$UPLOAD_URL" \
  --header "Content-Type: application/zip" \
  --upload-file ./materials.zip
```

PUT 完成前不要确认上传。`upload_url` 过期后需要重新申请票据并上传。

**步骤 3：确认上传，取得可用于 Run 的 attachment**

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$MEOO_BASE_URL/open/v1/projects/$PROJECT_ID/agent/archives/$ARCHIVE_ID/confirm" \
  --header "Authorization: Bearer $ACCESS_TOKEN_OR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}' \
  --output archive-confirm-response.json
```

成功响应示例：

```json
{
  "attachment": {
    "kind": "archive",
    "archive_id": "123456789"
  }
}
```

**步骤 4：把确认响应中的 attachment 放进 Run 请求**

直接使用确认接口返回的 `attachment`，无需手动复制 ID。下面生成的请求形如 `{"message":"…","attachments":[{"kind":"archive","archive_id":"123456789"}]}`。

```bash
python3 - <<'PY'
import json
from pathlib import Path

confirmed = json.loads(Path("archive-confirm-response.json").read_text(encoding="utf-8"))
attachment = confirmed["attachment"]
if attachment.get("kind") != "archive" or not isinstance(attachment.get("archive_id"), str):
    raise SystemExit("确认响应没有有效的 archive 附件")
payload = {
    "message": "请读取 ZIP 中的文件，整理文件清单并总结其中的需求。",
    "attachments": [attachment],
}
Path("archive-run-request.json").write_text(
    json.dumps(payload, ensure_ascii=False), encoding="utf-8"
)
PY

IDEMPOTENCY_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')
curl --fail-with-body --silent --show-error \
  --request POST "$MEOO_BASE_URL/open/v1/projects/$PROJECT_ID/agent/runs" \
  --header "Authorization: Bearer $ACCESS_TOKEN_OR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @archive-run-request.json \
  --output archive-run-response.json
```

同一条消息重试时复用本次 `IDEMPOTENCY_KEY`，不要重新生成；新消息再生成新值。每次 Run 最多携带一个 ZIP。

**查看处理进度和最终回复**

Run 启动成功后，用响应中的 `run_id` 订阅 SSE：

```bash
RUN_ID=$(python3 -c 'import json; print(json.load(open("archive-run-response.json"))["run_id"])')
curl --fail-with-body --silent --show-error --no-buffer \
  "$MEOO_BASE_URL/open/v1/projects/$PROJECT_ID/agent/runs/$RUN_ID/events" \
  --header "Authorization: Bearer $ACCESS_TOKEN_OR_API_KEY" \
  --header "Accept: text/event-stream"
```

确认上传成功表示原始 ZIP 已落到存储；解包、内容审核、素材入库和同步到沙箱在 Run 启动后执行。通过 Archive 工具事件及最终回复判断处理结果，不能仅用 `run.completed` 判断 ZIP 成功。事件处理方式见[事件流与 Action](/open/agent/events)。

### 限制与处理结果

- 每次 Run 最多一个 ZIP，可以与图片、视频和普通文件混用；`attachments` 合计不超过 10 项。
- 引用仅对当前上传用户、项目和客户端有效；未确认、跨用户、跨项目或跨客户端的 ZIP 引用不能用于启动 Run。
- 外部 ZIP URL 不能直接作为 Run 附件使用，应先取得 ZIP 文件，再通过本节流程上传。
- 确认成功仅表示原始 ZIP 已上传，不代表已经解包或可供 Agent 使用。Run 启动后，由 Archive 流程进行解包、内容审核、素材入库及同步到沙箱。
- 使用现有 SSE 查看工具进度和回复；`run.completed` 表示本轮运行结束，不能单独作为 ZIP 处理成功的依据，需结合 Archive 工具的 `outcome` 和最终回复判断。详见[事件流与 Action](/open/agent/events)。
- 取消 Run 沿用现有 ZIP 取消处理。素材已经入库后的沙箱同步失败，不表示素材已回滚；按 Agent 返回的原因处理，需要重试时明确要求重试该 ZIP。
- 这是 ZIP 素材附件能力，不会将 ZIP 导入为项目源码。源码导入使用源码导入 API（`POST /projects/import`）；自定义 Skill 包继续使用 [Skills API](/open/reference/skills)。

### ZIP 上传常见错误

| HTTP / code               | 场景与处理                                   |
| :------------------------ | :-------------------------------------- |
| `409 invalid_request`     | ZIP 尚未上传完成；完成 PUT 后再确认                  |
| `413 artifact_too_large`  | 声明或实际大小超过账号限额；检查 `max_size_bytes` 并缩小文件 |
| `404 not_found`           | 上传、项目或引用不属于当前调用方；检查用户、项目与客户端            |
| `503 service_unavailable` | 上传权益或依赖服务暂不可用；根据错误详情处理                  |
| `400 invalid_request`     | 文件名、字节数或附件 Schema 不合法；修正参数              |

## 在 Run 中选择 Skill

`skills` 数组每项只包含一个十进制字符串 `skill_id`：

```text
{
  "message": "使用简历审阅技能分析附件",
  "skills": [
    { "skill_id": "101" }
  ]
}
```

最多选择 20 项，不允许重复 ID 或额外字段。服务端按调用方顺序解析，并在 Agent 启动前校验 Skill 是否存在、未删除、当前可访问且未处于禁止消费的下架状态。

### `skills` 的三种语义

| 请求写法            | 语义                                               |
| :-------------- | :----------------------------------------------- |
| 省略 `skills`     | 有 `conversation_id` 时继承该会话；新会话则继承项目最近会话的用户 Skill |
| `"skills": [ ]` | 清除继承的用户 Skill；服务端内置 Skill 不受影响                   |
| 非空数组            | 用本次显式选择替换继承选择，并把结果保存到会话配置                        |

显式选择的每个 Skill 都是 mandatory selection：运行时按 `preload=true` 处理，不允许静默过滤。选择会在 blocking/resume 以及后续省略 `skills` 的 Run 中继续生效。

以下情况会在启动前返回通用 `404`：

- Skill ID 不存在或已软删除。
- 私有 Skill 不属于当前用户。
- 团队 Skill 的租户、成员或套餐权限不可用。
- 非 owner 的市场 Skill 已下架或没有当前可消费状态。

如果多个 ID 解析为同一个运行时名称，或名称与运行时内置 Skill 冲突，请求返回 `400 invalid_request`。

### 权限边界

- 上传/更新私有 Skill：需要 `skill.write`。
- 在 Agent Run 中使用已可访问 Skill：只需要 `agent.run`。
- 当前不支持通过 Run 锁定 Skill 版本。
- 当前不支持需要 MCP OAuth 的 Skill 授权流程。

完整上传格式、32 MiB ZIP 限制、`SKILL.md` 规则和响应字段见 [Skills API](/open/reference/skills)。

## 常见错误

| HTTP  | 场景                                  |
| :---- | :---------------------------------- |
| `400` | 附件对象、文件名、MIME、URL、Skills 数组或名称组合不合法 |
| `403` | 缺少 `agent.run`，或项目不能使用 Agent        |
| `404` | 项目不可访问，或显式选择的 Skill 不可访问/不可消费       |
| `429` | 票据签发或 Run 启动超过限频                    |
