JVS Crew API 参考

接口描述

获取用户进行对话所需的访问令牌（AccessToken），用于后续调用 Chat 接口进行身份验证。

令牌格式: AccessToken 为 JWT，由 Header.Payload.Signature 三段经 Base64URL 编码后以 . 连接成一行；下表示例为脱敏示意，实际 RequestId、JWT 各段均更长。

令牌有效期: AccessToken 在一段时间内有效，过期后须重新调用本接口获取新令牌。

请求信息

• 认证方式: POP V1 签名（AK/SK），详见使用示例

• Action: GetAccessToken

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetAccessToken",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "AccessToken": "eyJhbGc****.eyJ********.****TCk"
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "Invalid ExternalUserId",
  "HttpStatusCode": 400
}

错误码

接口描述

与 JVS Crew 进行流式对话，采用 Server-Sent Events (SSE) 协议实时推送对话内容。

特性:

• 实时流式响应，降低首字延迟

• 支持多模态输入（文本、图片、文件）

• 会话保持，支持多轮对话

• 事件驱动，精确控制消息状态

• Agent 任务独立于 SSE 连接运行——客户端断开连接不会中止正在执行的任务；重新连接同一 SessionId 或调用 ListSessionHistory 可查询任务状态

请求信息

• 请求方法: POST

• Content-Type: application/json

• 响应 Content-Type: text/event-stream

Query 参数

请求头（Header）

请求参数

请求示例

curl -N -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/api/agent/chat?Authorization=Bearer%20<access_token>&TemplateId=<template_id>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: Chat' \
  -H 'x-acs-date: 2026-03-18T06:21:31Z' \
  -d '{
    "Input": "[{\"Role\":\"user\",\"Content\":[{\"Type\":\"text\",\"Text\":\"你好\"}]}]",
    "ExternalUserId": "test-user",
    "SessionId": "test-session-001",
    "StreamOptions": {
      "IncludeReasoning": false,
      "IncludeToolCalls": false
    },
    "Settings": {
      "OutputFileMode": "url"
    }
  }'

注意：

• -N 参数用于禁用缓冲，实时接收 SSE 流

• x-acs-date 需要设置为当前 UTC 时间（ISO 8601 格式）

• Input 是 JSON 字符串，需要转义引号

• <access_token> 替换为实际的访问令牌，若令牌过期（401 错误），需重新调用 GetAccessToken 获取

响应参数（SSE 事件）

SSE 响应格式为 data: <JSON>\n\n，每条数据行包含一个事件对象。服务端会定期发送 :ping 心跳行（无 data: 前缀）用于保持连接，客户端忽略即可。

Response 事件字段

Object=response 事件是整个回复的生命周期包装，标记回复的开始与结束。

Message 事件字段

Object=message 事件表示一段具体的消息，通过 Type 字段区分消息类型。

Content 结构（响应）

事件类型说明

注意：思考阶段（reasoning）的 content 是模型内部推理过程，通常不应展示给终端用户。客户端应通过判断当前 message 的 Type 来决定是否展示对应的 content。

SSE 响应示例

完整流程:

data: {"Object":"response","Status":"created","SequenceNumber":"0"}

data: {"Object":"response","Status":"in_progress","SequenceNumber":"1"}

: ping

data: {"Object":"message","Id":"msg_001","SessionId":"176405663****961","Type":"reasoning","Status":"in_progress","SequenceNumber":"2"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"用户在打招呼","SequenceNumber":"3"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"，我简单回复即可","SequenceNumber":"4"}

data: {"Object":"message","Id":"msg_001","Type":"message","Status":"in_progress","SequenceNumber":"5"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"您好","SequenceNumber":"6"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"in_progress","Text":"！","SequenceNumber":"7"}

data: {"Object":"content","Id":"msg_001","Type":"text","Status":"completed","Text":"用户在打招呼，我简单回复即可","SequenceNumber":"8"}

data: {"Object":"message","Id":"msg_001","Type":"reasoning","Status":"completed","SequenceNumber":"9"}

data: {"Object":"message","Id":"msg_001","Type":"message","Status":"completed","Content":[{"Type":"text","Text":"您好！"}],"SequenceNumber":"10"}

data: {"Object":"response","Status":"completed","SequenceNumber":"11"}

提示：

url类型文件数据结构示例:

{
	"Status": "completed",
	"Role": "tool",
	"Type": "plugin_call_output",
	"Content": [{
		"Object": "content",
		"Type": "data",
		"Data": {
			"name": "sandbox_send_file_to_user",
			"output": "[{\"type\": \"file\", \"source\": {\"type\": \"url\", \"url\": \"https://jvs-crew-san****k%3D\"}, \"filename\": \"test_write.txt\"}, {\"type\": \"text\", \"text\": \"Sent file: test_write.txt\"}]",
			"call_id": "call_f0***2a661"
		}
	}],
	"SequenceNumber": "106",
	"Object": "message",
	"Id": "msg_85a*****7de40a2eba"
}

base64类型文件数据结构示例:

{
	"Role": "tool",
	"Status": "completed",
	"Type": "plugin_call_output",
	"Content": [{
		"Type": "data",
		"Object": "content",
		"Data": {
      "name": "sandbox_send_file_to_user",
			"output": "[{\"type\": \"file\", \"source\": {\"type\": \"base64\", \"media_type\": \"text/markdown\", \"data\": \"IyDmrKL*****15bm0Kgo=\"}, \"filename\": \"welcome.md\"}, {\"type\": \"text\", \"text\": \"Sent file: welcome.md\"}]",
			"call_id": "call_7*****92b0dc"
		}
	}],
	"SequenceNumber": "121",
	"Object": "message",
	"Id": "msg_655f******b84e"
}

错误码

接口描述

获取会话中文件上传 URL、沙箱内路径及 FileKey，用于将文件上传至 Agentbay 为用户提供的 Context 存储空间。完整的文件上传流程分三步：

1. 调用本接口获取 UploadUrl 和 FileKey

2. 使用 HTTP PUT 请求将文件内容上传到 UploadUrl（直传对象存储，无需额外签名）

3. 凭该 FileKey 调用 SyncContext 将文件同步到沙箱，之后 Agent 方可使用该文件

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: GetChatFileUploadUrl

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetChatFileUploadUrl",
    "RegionId": "cn-shanghai",
    "FileName": "report.pdf",
    "ExternalUserId": "user-38764",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "UploadUrl": "https://oss-example.aliyuncs.com/upload/...",
  "UploadHeadersHint": "...",
  "SandboxPath": "/home/wuying/jvscrew/uploads/report_a1b2c3d4.pdf",
  "FileKey": "uploads/report_a1b2c3d4.pdf"
}

接口描述

同步指定用户的 Context 中指定文件内容到沙箱环境，确保沙箱中的用户数据与 Context 保持一致。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: SyncContext

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "SyncContext",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "FileKey": "uploads/report_a1b2c3d4.pdf",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C"
}

接口描述

按技能类型分页查询当前租户、当前模板可见的技能列表，并返回每个技能在该模板下的启用状态。

Type 必须显式传入，且一次只能查询一种类型。如需展示完整技能列表，请分别调用 Type=builtin 和 Type=market 后在调用方侧合并。内置技能默认启用，市场技能默认禁用，响应中的 Enabled 字段已经是当前租户和模板下的最终启用状态。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: ListSkills

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "ListSkills",
    "RegionId": "cn-shanghai",
    "Type": "market",
    "PageNumber": 1,
    "PageSize": 50,
    "TemplateId": "template-abc123",
    "Tags": '["tag_001","tag_002"]',
}
params["Signature"] = _sign_v1(params, sk)

响应参数

Skills 数组元素:

响应示例

{
  "Success": true,
  "Code": "200",
  "RequestId": "EA12****-****-****-****-****E5C",
  "Skills": [
    {
      "SkillId": "builtin:deep_web_search",
      "SkillName": "deep_web_search",
      "Type": "builtin",
      "Description": "深度网络信息搜索",
      "Icon": "search",
      "GmtModified": "",
      "Enabled": true,
      "SkillStatus": "",
      "Tags": []
    },
    {
      "SkillId": "skill_abc123",
      "SkillName": "my_automation_tool",
      "Type": "market",
      "Description": "自动化办公工具",
      "Icon": "code",
      "GmtModified": "2026-05-21T10:30:00Z",
      "Enabled": false,
      "SkillStatus": "AVAILABLE",
      "Tags": ["tag_001", "tag_002"]
    }
  ],
  "TotalCount": "11",
  "PageNumber": 1,
  "PageSize": 50
}

错误码

注意事项

1. Type 只能传单一值，不能同时查询 builtin 和 market。

2. PageSize 最大为 100，市场技能较多时请按页遍历。

3. 响应会回显 PageNumber 和 PageSize，可用于客户端翻页状态同步。

4. TemplateId 不传时使用默认模板；不同模板下的 Enabled 状态相互独立。

5. AK/SK 必须保存在服务端并完成签名，禁止在前端代码、浏览器或移动 App 包中暴露。

接口描述

为当前用户设置在指定 Agent 模板下对某个技能（builtin 或 market）的启用偏好。Preference 取值为 Enabled / Disabled / Default，其中 Default 会删除该用户对此技能的偏好记录，让该技能回落到模板自身的默认启用状态。

适用场景: 在前端给用户一个「单独打开/关闭某个技能」开关时，调用该接口持久化用户选择；用户点击「恢复默认」时传 Default。

与模板的关系: 用户偏好优先级高于模板默认值。设置 Enabled / Disabled 会创建/更新偏好记录；设置 Default 会删除偏好记录，该技能再次跟随模板默认。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: SetSkillPreference

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: SetSkillPreference' \
  -H 'x-acs-date: 2026-05-13T06:00:00Z' \
  -d '{
    "SkillId": "builtin:deep_web_search",
    "Preference": "Enabled"
  }'

恢复模板默认（删除偏好记录），将 Preference 改为 "Default"：

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "SkillId": "builtin:deep_web_search",
  "UserPreference": "Enabled"
}

错误码

注意事项

1. Preference=Default 是删除而不是设置——它会移除该用户对此 SkillId 的偏好记录，使技能回落到模板自身的默认启用状态。

2. SkillId 必须存在于全局 builtin 技能列表，或当前租户的市场技能列表中。

3. 设置偏好后下一次对话生效。

接口描述

分页列出当前用户在指定 Agent 模板下设置过的技能偏好。仅返回有显式偏好记录的 skill；没有偏好记录的技能不会出现在结果中。

返回内容: 每条记录包含 SkillId、UserPreference（Enabled 或 Disabled）、UpdatedAt 三个字段。Default 不会出现在 UserPreference 中——一旦用户选择 Default，该条偏好记录会被删除，从此跟随模板默认。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数），与 SetSkillPreference 相同

• 请求方法: POST

• Action: ListSkillPreferences

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: ListSkillPreferences' \
  -H 'x-acs-date: 2026-05-13T06:00:00Z' \
  -d '{
    "MaxResults": 100
  }'

翻页时携带上一次响应中的 NextToken：

{
  "MaxResults": 100,
  "NextToken": "eyJwYWdlIjoyfQ=="
}

响应参数

SkillPreferences 数组元素:

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "SkillPreferences": [
    {
      "SkillId": "builtin:deep_web_search",
      "UserPreference": "Enabled",
      "UpdatedAt": "2026-05-13T15:43:56.358003+08:00"
    }
  ],
  "NextToken": ""
}

错误码

注意事项

1. 返回结果只包含用户主动设置过偏好的技能；如需展示完整技能列表，请配合 ListSkills 使用。

2. UserPreference 不会出现 Default——Default 操作会删除偏好记录，使该技能在结果中消失。

3. MaxResults 上限为 100；偏好数较多时请按 NextToken 翻页

接口描述

获取技能包文件的预签名上传 URL，用于将技能包上传至对象存储。完整的技能包上传流程分两步：

1. 调用本接口获取 Url（预签名上传地址）

2. 使用 HTTP PUT 请求将技能包 zip 文件上传到 Url（直传对象存储，无需额外签名，需设置 Content-Type: application/octet-stream）

上传完成后，将该 Url 作为 FileUrl 传入 CreateSkillCenterSkill 或 UpdateSkillCenterSkill 即可完成技能创建或更新。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: GetSkillCenterCredential

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetSkillCenterCredential",
    "RegionId": "cn-shanghai",
    "FileName": "my_tool_v2.zip",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "RequestId": "EA12****-****-****-****-****E5C",
  "Url": "https://skill-packages-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/skills/upload/my_tool_v2.zip?Expires=..."
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "Invalid FileName",
  "HttpStatusCode": 400
}

错误码

注意事项

1. 预签名地址有效期有限，获取后应尽快完成上传。

2. 仅支持 .zip 格式的技能包文件。

接口描述

创建一个新的市场技能。技能名称和描述从上传的 OSS 技能包中自动解析，无需手动指定。完整流程为：

1. 调用 GetSkillCenterCredential 获取预签名上传 URL

2. 使用 HTTP PUT 将技能包 zip 文件上传至该 URL

3. 调用本接口，传入 FileUrl 完成技能创建

创建成功后默认触发安全检测，可通过 SkipVerify 参数跳过。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: CreateSkillCenterSkill

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "CreateSkillCenterSkill",
    "RegionId": "cn-shanghai",
    "FileUrl": "https://skill-packages-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/skills/upload/my_tool_v1.zip?Expires=...",
    "Icon": "code",
    "Tags": '["tag_001","tag_002"]',
    "SkipVerify": "false",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "RequestId": "EA12****-****-****-****-****E5C",
  "SkillId": "skill_abc123"
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "Invalid FileUrl",
  "HttpStatusCode": 400
}

错误码

注意事项

1. 技能名称和描述从技能包中自动解析，不支持通过请求参数指定。

2. 创建后技能默认状态为 INIT，安全检测通过后变为 AVAILABLE；若跳过安全检测则直接变为 AVAILABLE。

接口描述

更新已有市场技能的属性或技能包文件。当传入 FileUrl 时替换 OSS 文件；不传则仅更新 Icon、Tags 等属性。更新成功后默认触发安全检测，可通过 SkipVerify 参数跳过。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: UpdateSkillCenterSkill

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "UpdateSkillCenterSkill",
    "RegionId": "cn-shanghai",
    "SkillId": "skill_abc123",
    "FileUrl": "https://skill-packages-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/skills/upload/my_tool_v2.zip?Expires=...",
    "Icon": "code",
    "Tags": '["tag_001","tag_002"]',
    "SkipVerify": "false",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "RequestId": "EA12****-****-****-****-****E5C",
  "SkillId": "skill_abc123"
}

失败:

{
  "Success": false,
  "Code": "InvalidParameter",
  "Message": "Skill name in package does not match existing skill",
  "HttpStatusCode": 400
}

错误码

接口描述

分页查询当前租户下的市场技能列表，返回每个技能的基本信息和被模板引用的计数。支持按标签筛选。

与 ListSkills 的区别：ListSkills 面向指定模板，展示该模板下可见的技能及启用状态；本接口面向租户整体，展示租户上传的全部市场技能及被引用情况。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: ListSkillCenterSkills

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "ListSkillCenterSkills",
    "RegionId": "cn-shanghai",
    "MaxResults": "20",
    "Tags": '["tag_001","tag_002"]',
}
params["Signature"] = _sign_v1(params, sk)

翻页请求：

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "ListSkillCenterSkills",
    "RegionId": "cn-shanghai",
    "MaxResults": "20",
    "NextToken": "eyJ...",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

Skills 数组元素:

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "RequestId": "EA12****-****-****-****-****E5C",
  "Skills": [
    {
      "SkillId": "skill_abc123",
      "SkillName": "my_automation_tool",
      "Description": "自动化办公工具",
      "Icon": "code",
      "GmtModified": "2026-05-21T10:30:00Z",
      "SkillStatus": "AVAILABLE",
      "EnabledTemplateCount": 3,
      "TenantTags": ["tag_001", "tag_002"]
    },
    {
      "SkillId": "skill_def456",
      "SkillName": "data_analysis",
      "Description": "数据分析助手",
      "Icon": "chart",
      "GmtModified": "2026-05-20T08:00:00Z",
      "SkillStatus": "VERIFYING",
      "EnabledTemplateCount": 0,
      "TenantTags": []
    }
  ],
  "TotalCount": 12,
  "MaxResults": 20,
  "NextToken": ""
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "Invalid NextToken",
  "HttpStatusCode": 400
}

错误码

接口描述

设置当前用户对某个模板级 MCP 的启用偏好。Preference 取值为 enabled / disabled / default，其中 default 表示恢复跟随模板默认值（偏好记录保留，便于追溯操作时间）。

适用场景: 集成方在前端为用户提供「单独打开/关闭某个 MCP」开关时调用此接口持久化用户选择。

与模板的关系: 用户偏好优先级高于模板默认值。设置 enabled / disabled 会覆盖模板默认状态；设置 default 则回落到模板的 enabled 字段决定是否加载。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: SetUserMcpPreference

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: SetUserMcpPreference' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "amap_mcp",
    "Preference": "disabled"
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "IsEffective": false,
  "Source": "user_override"
}

错误码

接口描述

为当前用户绑定某个模板级 MCP 的专属凭证（HTTP Headers），覆盖模板共享 token。绑定后，Agent 调用该 MCP 时使用用户的 headers（URL 仍来自模板配置）。

适用场景: 高德地图、企业 OA 等外部系统按用户鉴权——每个用户需要带自己的 OAuth token 调用。通过此接口持久化绑定后，无需每次会话重传。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: SetUserMcpCredential

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: SetUserMcpCredential' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "amap_mcp",
    "Headers": {
      "Authorization": "Bearer user_oauth_token_xxx",
      "X-Custom-Header": "value"
    }
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "IsCredentialBound": true
}

错误码

接口描述

解绑当前用户对某个模板级 MCP 的专属凭证，回退使用模板共享 token。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: ClearUserMcpCredential

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: ClearUserMcpCredential' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "amap_mcp"
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "IsCredentialBound": false
}

错误码

接口描述

为当前用户创建一个专属 MCP。用户专属 MCP 的 URL、传输协议、凭证全部由用户自行控制，与模板 MCP 独立。

适用场景: 用户想接入自己的内部系统（如企业 OA、私有工具），而模板上未配置该 MCP。

连通性: 创建时不做连通性校验，写入即生效。运行时连接失败会透传给 Agent。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: CreateUserMcp

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: CreateUserMcp' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "Name": "企业 OA",
    "Transport": "sse",
    "Url": "https://my-oa.internal/mcp/sse",
    "Headers": {
      "Authorization": "Bearer my_oa_token"
    },
    "Description": "企业内部 OA 系统",
    "Timeout": 15
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "McpId": "usr_mcp_a1b2c3d4",
  "Name": "企业 OA",
  "Transport": "sse",
  "Url": "https://my-oa.internal/mcp/sse",
  "Headers": {
    "Authorization": "Bearer my_oa_token"
  },
  "Description": "企业内部 OA 系统",
  "Timeout": 15,
  "SseReadTimeout": 300,
  "IsEnabled": true,
  "CreateTime": "2026-05-27T10:00:00Z",
  "ModifyTime": "2026-05-27T10:00:00Z"
}

错误码

接口描述

更新当前用户的某个专属 MCP 配置。采用部分更新语义——只更新请求中传入的字段，未传的字段保持不变。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: UpdateUserMcp

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: UpdateUserMcp' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "usr_mcp_a1b2c3d4",
    "Headers": {
      "Authorization": "Bearer new_refreshed_token"
    },
    "Timeout": 20
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "McpId": "usr_mcp_a1b2c3d4",
  "Name": "企业 OA",
  "Transport": "sse",
  "Url": "https://my-oa.internal/mcp/sse",
  "Headers": {
    "Authorization": "Bearer new_refreshed_token"
  },
  "Description": "企业内部 OA 系统",
  "Timeout": 20,
  "SseReadTimeout": 300,
  "IsEnabled": true,
  "CreateTime": "2026-05-27T10:00:00Z",
  "ModifyTime": "2026-05-27T11:30:00Z"
}

错误码

接口描述

删除当前用户的某个专属 MCP。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: DeleteUserMcp

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: DeleteUserMcp' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "usr_mcp_a1b2c3d4"
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true
}

错误码

接口描述

查询当前用户的单个专属 MCP 详情。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: GetUserMcp

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: GetUserMcp' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "McpId": "usr_mcp_a1b2c3d4"
  }'

响应参数

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "McpId": "usr_mcp_a1b2c3d4",
  "Name": "企业 OA",
  "Transport": "sse",
  "Url": "https://my-oa.internal/mcp/sse",
  "Headers": {
    "Authorization": "Bearer my_oa_token"
  },
  "Description": "企业内部 OA 系统",
  "Timeout": 15,
  "SseReadTimeout": 300,
  "IsEnabled": true,
  "CreateTime": "2026-05-27T10:00:00Z",
  "ModifyTime": "2026-05-27T10:00:00Z"
}

错误码

接口描述

列出当前用户全部 MCP 的合并视图，包含模板级 MCP（附带用户偏好和凭证绑定状态）与用户专属 MCP。集成方拿到此列表，即可在 UI 上展示"当前用户有哪些工具可用"。

请求信息

• 认证方式: JWT 令牌（Authorization Query 参数）

• 请求方法: POST

• Action: ListUserMcps

请求参数

请求示例

curl -X POST \
  'https://wuyingai.cn-shanghai.aliyuncs.com/?Authorization=Bearer%20<access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-acs-version: 2026-03-11' \
  -H 'x-acs-action: ListUserMcps' \
  -H 'x-acs-date: 2026-05-27T06:00:00Z' \
  -d '{
    "Source": "all",
    "MaxResults": 50
  }'

响应参数

Mcps 数组元素（McpItem）:

响应示例

{
  "RequestId": "EA12****-****-****-****-****E5C",
  "HttpStatusCode": 200,
  "Code": "200",
  "Success": true,
  "Mcps": [
    {
      "McpId": "amap_mcp",
      "Name": "高德地图",
      "Description": "高德地图 MCP，提供地理编码、路径规划等能力",
      "Transport": "streamable_http",
      "Url": "https://mcp.amap.com/sse",
      "Source": "template",
      "IsEffective": true,
      "Preference": "default",
      "TemplateDefault": true,
      "IsCredentialBound": true,
      "Headers": null
    },
    {
      "McpId": "internal_crm",
      "Name": "内部 CRM",
      "Description": null,
      "Transport": "streamable_http",
      "Url": "https://crm.internal/mcp",
      "Source": "template",
      "IsEffective": false,
      "Preference": "disabled",
      "TemplateDefault": true,
      "IsCredentialBound": false,
      "Headers": null
    },
    {
      "McpId": "usr_mcp_a1b2c3d4",
      "Name": "企业 OA",
      "Description": "企业内部 OA 系统",
      "Transport": "sse",
      "Url": "https://my-oa.internal/mcp/sse",
      "Source": "user_persistent",
      "IsEffective": true,
      "Preference": null,
      "TemplateDefault": null,
      "IsCredentialBound": null,
      "Headers": {
        "Authorization": "Bearer my_oa_token"
      }
    }
  ],
  "NextToken": "",
  "MaxResults": 50
}

错误码

接口描述

触发指定用户活跃沙箱中的工作空间文件同步到 Context，用于在读取文件列表或下载文件前获取最新快照。

如果用户当前没有活跃沙箱，会返回成功且 SyncStatus 为 no_active_session。此时 Context 中仍保留上次沙箱释放或同步后的快照，调用方可以继续使用 ListWorkspaceFiles 读取已有数据。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: SyncWorkspaceFiles

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "SyncWorkspaceFiles",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

同步完成:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "SyncStatus": "completed",
  "Message": ""
}

无活跃沙箱:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "SyncStatus": "no_active_session",
  "Message": ""
}

错误码

接口描述

列举指定用户工作空间中某个目录下的文件和子目录。路径以用户工作空间根目录为基准，例如列举用户 active skills 目录时传 Path="active_skills"。

该接口只返回单层目录内容。如需读取文件内容，可先从响应中取得 FilePath，再调用 GetWorkspaceFileDownloadUrl 获取临时下载地址。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: ListWorkspaceFiles

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "ListWorkspaceFiles",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "Path": "active_skills",
    "MaxResults": 100,
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

Files 数组元素:

响应示例

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Path": "/active_skills",
  "MaxResults": 100,
  "NextToken": null,
  "Files": [
    {
      "FileName": "builtin-a",
      "FilePath": "active_skills/builtin-a",
      "FileType": "directory",
      "Size": 0,
      "ModifiedAt": "2026-05-13T08:00:00Z"
    },
    {
      "FileName": "my-custom-skill",
      "FilePath": "active_skills/my-custom-skill",
      "FileType": "directory",
      "Size": 0,
      "ModifiedAt": "2026-05-13T08:01:00Z"
    },
    {
      "FileName": ".managed_skills.json",
      "FilePath": "active_skills/.managed_skills.json",
      "FileType": "file",
      "Size": 26,
      "ModifiedAt": "2026-05-13T08:02:00Z"
    }
  ]
}

错误码

接口描述

获取指定用户工作空间文件的临时下载地址。调用方可使用返回的 DownloadUrl 直接下载文件内容，例如读取 active_skills/.managed_skills.json 或某个 skill 目录下的 SKILL.md。

FilePath 必须指向文件，不能指向目录；路径以用户工作空间根目录为基准。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: GetWorkspaceFileDownloadUrl

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetWorkspaceFileDownloadUrl",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "FilePath": "active_skills/my-custom-skill/SKILL.md",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "DownloadUrl": "https://oss.example.com/presigned/...",
  "ExpiresInSeconds": 3600,
  "FileName": "SKILL.md",
  "FileSize": 512,
  "Message": ""
}

错误码

接口描述

获取指定用户工作空间内某条文件路径的临时预签名上传地址。调用方拿到 UploadUrl 后，对该 URL 直接发起 HTTP PUT 请求即可将文件内容写入用户工作空间，路径以用户工作空间根目录为基准。

典型用法：将本地或前端选择的文件上传到 documents/report.pdf，后续可通过 ListWorkspaceFiles 看到、通过 GetWorkspaceFileDownloadUrl 下载、或在 Chat 的 Input 中通过 FileUrl 引用。

重要：执行 PUT 请求时必须按照响应里 UploadHeadersHint 给出的 header 透传，当前要求 Content-Type: ""（空字符串），否则 OSS 会返回 403。

FilePath 必须指向文件，不能指向目录（不能以 / 结尾），不能包含 ..。同一路径重复获取上传地址不会清空已有文件——真正的写入是在 PUT 阶段完成的；同路径重复 PUT 等价于覆盖（last-write-wins）。

单次上传文件大小上限当前为 50 MB（52428800 字节），由响应字段 MaxFileSize 透出，调用方应在客户端对文件大小做校验。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: GetWorkspaceFileUploadUrl

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "GetWorkspaceFileUploadUrl",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "FilePath": "documents/report.pdf",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "UploadUrl": "https://oss.example.com/presigned-put/...",
  "ExpiresInSeconds": 3600,
  "FilePath": "documents/report.pdf",
  "MaxFileSize": 52428800,
  "UploadHeadersHint": {
    "Content-Type": ""
  },
  "Message": ""
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "FilePath cannot point to directory",
  "HttpStatusCode": 400
}

完整上传示例（两步流程）

import requests

# Step 1: 获取上传地址
upload_resp = call_pop("GetWorkspaceFileUploadUrl", {
    "ExternalUserId": "user-38764",
    "FilePath": "documents/report.pdf",
})
upload_url = upload_resp["UploadUrl"]
hint = upload_resp.get("UploadHeadersHint") or {}

# Step 2: 直接 PUT 文件内容到该 URL
with open("./report.pdf", "rb") as f:
    r = requests.put(upload_url, data=f, headers=hint, timeout=120)
    assert r.status_code in (200, 201, 204), f"OSS PUT failed: HTTP {r.status_code}"

# 之后即可在 Chat 接口的 Input 中通过 FileUrl 引用 "documents/report.pdf"

错误码

接口描述

删除指定用户工作空间内的某个文件。路径以用户工作空间根目录为基准。

幂等语义：若目标文件不存在，接口仍返回成功（Success=true），便于上游做"清理-重传"等场景的幂等重试，无需先 ListWorkspaceFiles 探测。

FilePath 只能指向文件，不能指向目录（不能以 / 结尾），不能包含 ..。本接口不支持目录批量删除——如需清空全部工作空间内容，请使用 ClearUserWorkspace。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: DeleteWorkspaceFile

请求参数

请求示例

params = {
    "Format": "JSON",
    "Version": "2026-03-11",
    "AccessKeyId": ak,
    "SignatureMethod": "HMAC-SHA1",
    "Timestamp": _now_utc(),
    "SignatureVersion": "1.0",
    "SignatureNonce": str(uuid.uuid4()),
    "Action": "DeleteWorkspaceFile",
    "RegionId": "cn-shanghai",
    "ExternalUserId": "user-38764",
    "FilePath": "documents/report.pdf",
    "TemplateId": "template-abc123",
}
params["Signature"] = _sign_v1(params, sk)

响应参数

响应示例

成功（文件存在并被删除）:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Message": ""
}

成功（文件不存在，幂等返回）:

{
  "Success": true,
  "Code": "200",
  "HttpStatusCode": 200,
  "RequestId": "EA12****-****-****-****-****E5C",
  "Message": ""
}

失败:

{
  "Success": false,
  "Code": "400",
  "Message": "FilePath cannot point to directory",
  "HttpStatusCode": 400
}

错误码

注意：服务端会把底层 SDK 抛出的"文件不存在"类错误（包含 not exist / not found / no such 关键字的异常或 error_message）归一化为成功返回，调用方无需特殊处理。

接口描述

清理指定外部用户在当前租户下的工作空间数据。可按 TemplateId 限定模板；不传 TemplateId 时清理该用户在当前租户下绑定的全部工作空间。

接口只清理未删除用户的绑定记录。若用户存在但没有可清理的工作空间，返回成功且 Workspaces 为空。

请求信息

• 认证方式: POP V1 签名（AK/SK），与 GetAccessToken 相同

• Action: ClearUserWorkspace

请求参数