Skip to main content

附件与 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。

图片或视频

{
  "kind": "image",
  "url": "https://cdn.example.com/reference.png"
}
kind=image 或 video 时只允许 kind、url,不能携带 filename 或 type。

普通文件

{
  "kind": "file",
  "url": "https://cdn.example.com/requirements.pdf",
  "filename": "requirements.pdf",
  "type": "application/pdf"
}
字段约束
urlHTTP(S) URL,最长 4096 字符
filename1~255 字符,不含目录路径;不支持 .zip 和 .skill
type可选的合法 MIME type,最长 255 字符

ZIP 素材附件

{ "kind": "archive", "archive_id": "123456789" }
只允许 kind、archive_id;不能携带 url、filename 或 type。archive_id 使用确认上传接口返回的字符串,每次 Run 最多一个 ZIP。

签发普通附件直传票据

POST /projects/{project_id}/agent/uploads
所需权限:agent.run
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。 响应:
{
  "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 过期后重新签发,不要长期保存。
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

{
  "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 上传票据

POST /projects/{project_id}/agent/archives
filename 为不含目录路径的 ZIP 文件名;size 为文件的真实字节数(正整数)。例如:
{ "filename": "materials.zip", "size": 102400 }
调用示例(请将 size 替换为实际字节数):
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}'
响应示例:
{
  "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 上传

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 已上传

POST /projects/{project_id}/agent/archives/{archive_id}/confirm
请求体可以省略,或发送空对象 {}:
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 '{}'
服务端校验上传归属与存储中的实际文件大小。重复确认返回同一批次,不会重新创建或重置处理任务。响应:
{ "attachment": { "kind": "archive", "archive_id": "123456789" } }

4. 携带返回的 attachment 启动 Run

将确认响应中的 attachment 原样放入 attachments:
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。
export MEOO_BASE_URL="https://meoo.com"
export ACCESS_TOKEN_OR_API_KEY="<替换为你的凭证>"
export PROJECT_ID="<替换为项目的 url_id>"
步骤 1:读取真实文件大小,申请 ZIP 上传票据 使用文件的实际字节数生成请求,避免手填 size 与本地文件不一致。
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。
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
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
成功响应示例:
{
  "attachment": {
    "kind": "archive",
    "archive_id": "123456789"
  }
}
步骤 4:把确认响应中的 attachment 放进 Run 请求 直接使用确认接口返回的 attachment,无需手动复制 ID。下面生成的请求形如 {"message":"…","attachments":[{"kind":"archive","archive_id":"123456789"}]}。
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:
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。

限制与处理结果

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

ZIP 上传常见错误

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

在 Run 中选择 Skill

skills 数组每项只包含一个十进制字符串 skill_id:
{
  "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。

常见错误

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