> ## 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 可以携带图片、视频、普通文件和显式 Skill 选择。普通附件与 Skill 包是两条独立链路：`.zip` / `.skill` 不能作为普通附件使用，自定义 Skill 必须先通过 Skills API 上传。

## 附件的两种来源

| 文件位置 | 推荐方式 |
| :--- | :--- |

\| 已有公网 HTTP(S) URL | 直接放入 `attachments[ ].url` |

\| 仅存在于本地设备或私有服务 | 先签发直传票据并上传，再使用返回的 `file_url` |

Meoo 会拒绝本地、私网和链路本地地址。URL 必须能被服务端直接访问；Agent 下载链路对每个附件的实际响应执行 50 MiB 上限。

## Run 附件 Schema

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

### 图片或视频

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

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

### 普通文件

```text theme={null}
{
  "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 字符             |

## 签发附件直传票据

```text theme={null}
POST /projects/{project_id}/agent/uploads
```

所需权限：`agent.run`

```text theme={null}
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 theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "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"
    }
  ]
}
```

## 在 Run 中选择 Skill

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

```text theme={null}
{
  "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](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/7b25c37b-1a42-40e8-8ae8-6196a592c345)。

## 常见错误

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