WeaveFox 开放能力

WeaveFox 是一个 AI 应用创作和分享平台,提供开放能力以便其它工具(比如 各种 AI 智能体工具)连接 WeaveFox 实现协同完成任务。

开放能力

连接 WeaveFox

用户在 WeaveFox 平台上对话创建应用后,通过 MCP 可以让其它 AI 智能体工具连接到 WeaveFox,实现发送消息迭代应用、更新应用信息等。

WeaveFox Pages

该功能面向用户本地研发场景,在本地开发应用并进行预构建(通常是执行 build 脚本命令)获取生产环境产物,通过上传 zip 包或单 HTML 文件来托管预构建的站点应用。该类型应用不支持在 WeaveFox 平台上进行对话迭代,仅支持预览和发布。

流程:

  1. 创建应用(create_app)— 创建 WeaveFox Pages 应用(agentType 必须为 "external")。
  2. 获取上传凭证(get_upload_token)— 获取短期一次性上传凭证(10 分钟有效),返回 token。
  3. 上传产物压缩包(upload_artifact_zip)— 用临时 token 作为 Bearer Token,上传 zip 包或单 HTML 文件,返回 artifactZipUrl。
  4. 创建版本(create_version)— 传入 artifactZipUrl 创建应用版本,仅接受 upload_artifact_zip 返回的站内地址。
  5. 查看版本列表(list_versions)— 查看应用版本列表。
  6. 部署版本(deploy_version)— 部署指定版本为当前线上版本。
  7. 更新应用信息(可选)(update_app)— 设置标签、可见性等应用元信息。
也支持通过 GitHub Action 自动部署,适合 CI/CD 场景。

构建产物路径说明

WeaveFox Pages 将产物托管在云存储子路径下。如果构建产物的 index.html 中使用了绝对路径引用资源(如 /assets/index.js),这些路径会解析到存储根目录而非子路径,导致 404 Not Found。

请在构建时将资源路径配置为相对路径,常见构建工具配置方式:

配置后 index.html 中的引用将从 /assets/... 变为 ./assets/...,确保在任何子路径下都能正确加载。

提示:查询应用列表时传入 agentType: "external" 可筛选 WeaveFox Pages 应用。

接入方式

使用以下接入方式前,请先在 WeaveFox 平台的 API Key 页面 创建密钥。

MCP

通过 MCP 协议连接,AI 智能体工具可自动感知工具列表。适合 Cursor、Claude Desktop 等 MCP 客户端。

配置示例(替换 YOUR_API_KEY 为你的 API Key):

{
  "mcpServers": {
    "WeaveFox MCP": {
      "url": "https://www.weavefox.cn/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Skill

通过安装 Agent Skill 插件连接 WeaveFox,适合 Claude Code、Codex 等 AI 编码工具。

安装命令:

npx skills add https://github.com/weavefox/weavefox-cli --skill weavefox

或复制以下提示词到 AI 工具中执行:

运行 `npx skills use "https://github.com/weavefox/weavefox-cli" --skill "weavefox"` 并立即按照生成的 Skill 说明执行。读取完整输出,必要时先将输出重定向到临时文件。从其提供的 supporting-files 目录解析相对路径。

HTTP Open API

通过 HTTP REST 接口调用,需要 API Key 鉴权。适合脚本、CI/CD、自定义集成等场景。

HTTP Open API 接口列表

响应对象

多个接口复用以下对象结构,在各接口的「响应」表格中以名称引用。

应用对象 AppDTO

字段类型说明
publicIdstring应用公开 ID
namestring应用名称
descriptionstring 或 null应用描述
thumbnailUrlstring缩略图 URL,配置了自定义封面时为自定义封面地址
tagstring 或 null应用标签
agentTypestring应用类型,如 external
sourcestring 或 null应用来源,历史应用为空
appConfigobject应用配置:hideProductLogo、customThumbnailUrl、faviconUrl
metadataobject 或 null元数据,当前仅含 serviceVersion
isPublicnumber访问权限:0=私有(仅作者/协作者可访问),1=公开(任何人可通过 publicId 访问)
isVisiblenumber是否在公开应用列表/广场展示:0=不展示(仍可通过 publicId 访问),1=展示
isFeaturednumber是否精选
currentVersionIdstring 或 null当前发布版本 ID
isPublishednumber是否已发布:0=未发布,1=已发布
previewUrlstring预览地址
shareUrlstring分享地址
authorobject 或 null作者:userId、username、avatarUrl、description
viewCountnumber浏览次数
likeCountnumber点赞次数
forkCountnumberFork 次数
shareCountnumber分享次数
lastVisitedAtstring 或 null最后一次访问时间
createdAtstring创建时间
updatedAtstring更新时间

版本对象 AppVersionDTO

字段类型说明
versionstring版本号,如 v1
versionNamestring 或 null版本名称
releaseNotesstring 或 null版本说明(changelog)
releasedAtstring 或 null发布时间,null 表示尚未部署发布
previewImgstring 或 null预览图 URL
metadataobject 或 null版本元数据
createdAtstring创建时间
isCurrentReleaseboolean是否为当前发布版本

消息对象 MessageDTO

字段类型说明
idstring消息 ID
rolestringuser 或 assistant
createdAtstring创建时间
contentstring 或 null解析后的文本内容,无内容时为 null
contentStructuredobject可选,结构化数据:user 消息含 files([{ mediaType, url }]);assistant 消息为 tool 调用信息:type、toolName、input、output

公开接口

GET /readme

获取 WeaveFox 开放能力说明文档(本文件)。

参数:无

响应

HTML 渲染的本说明文档(Content-Type: text/html),非 JSON。

GET /docs

获取 WeaveFox 产品文档信息。

参数:无

响应

HTML 渲染的文档页面(Content-Type: text/html),非 JSON。

用户信息

GET /me

获取当前鉴权用户信息。

参数:无

响应

字段类型说明
codenumber0 表示成功
dataobject用户信息
data.userIdstring用户 ID
data.usernamestring用户名
data.avatarUrlstring 或 null头像 URL
data.descriptionstring 或 null个人描述

应用管理

POST /apps

创建 WeaveFox Pages 应用。

参数

参数位置类型必填说明
namebodystring是应用名称,1-100 字符
descriptionbodystring否应用描述,最多 500 字符
agentTypebodystring是固定为 external

响应

字段类型说明
codenumber0 表示成功
dataAppDTO新创建的应用对象,结构见「应用对象 AppDTO」

GET /apps

分页查询应用列表。

参数

参数位置类型必填说明
pagequerynumber否页码,默认 1
pageSizequerynumber否每页条数,最大 100,默认 10
keywordquerystring否名称/描述模糊搜索
publicIdquerystring否按 publicId 精确匹配
agentTypequerystring否筛选类型,如 external

响应

字段类型说明
codenumber0 表示成功
dataobject分页数据
data.listAppDTO[]应用列表,结构见「应用对象 AppDTO」
data.totalnumber总条数
data.pagenumber当前页码
data.pageSizenumber每页条数

PATCH /apps/:publicId

更新应用信息。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
namebodystring否应用名称,1-100 字符
descriptionbodystring否应用描述,最多 500 字符
tagbodynumber否应用标签,0-21
isPublicbodynumber否访问权限:0=私有(仅作者/协作者可访问),1=公开(任何人可通过 publicId 访问)
isVisiblebodynumber否是否在公开应用列表/广场展示:0=不展示(仍可通过 publicId 访问),1=展示
customThumbnailUrlbodystring否自定义封面图 URL,传 null 重置为默认
faviconUrlbodystring否站点图标 URL,传 null 时清除配置恢复默认
newPublicIdbodystring否新的 publicId,6-36 字符,仅字母/数字/连字符

响应

字段类型说明
codenumber0 表示成功
dataAppDTO更新后的应用对象,结构见「应用对象 AppDTO」

消息

POST /apps/:publicId/messages

发送消息给应用智能体,异步执行。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
messagebodystring是发送的消息内容

响应

字段类型说明
codenumber0 表示成功
dataobject投递结果
data.acceptedboolean是否受理,受理后智能体异步执行

受理即返回,不等待执行结果;若当前已有会话在执行,本次请求会被拒绝,请稍后重试。执行状态与结果通过 GET /apps/:publicId/message 轮询获取。

GET /apps/:publicId/message

获取应用智能体消息状态。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID

响应

字段类型说明
codenumber0 表示成功
dataobject消息状态
data.statusstringrunning=正在处理,idle=空闲
data.contentstring 或 null最近一次 assistant 输出文本,无内容时为 null
data.contentStructuredobject可选,最近一次输出的结构化数据(tool 调用时附带):type、toolName、input、output

GET /apps/:publicId/messages

分页查询应用消息列表。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
pagequerynumber否页码,默认 1
pageSizequerynumber否每页条数,最大 20,默认 20

响应

字段类型说明
codenumber0 表示成功
dataobject分页数据
data.listMessageDTO[]消息列表,按时间倒序(最新在前),结构见「消息对象 MessageDTO」
data.totalnumber总条数
data.pagenumber当前页码
data.pageSizenumber每页条数

POST /apps/:publicId/message/stop

停止应用智能体运行流。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID

响应

字段类型说明
codenumber0 表示成功
messagestring状态说明

版本管理

POST /apps/:publicId/upload-token

获取一次性临时上传凭证(10 分钟有效)。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID

响应

字段类型说明
codenumber0 表示成功
dataobject上传凭证
data.tokenstring一次性临时 token,作为上传接口的 Bearer Token

POST /apps/:publicId/upload-artifact-zip

上传产物 zip 包,返回可访问的 URL。

鉴权:upload-token 返回的 token 作为 Bearer Token。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
fileform-datafile是zip 文件,最大 5MB

响应

字段类型说明
codenumber0 表示成功
dataobject上传结果
data.artifactZipUrlstring上传后的 zip 可访问 URL

示例:

curl -X POST \
  -H "Authorization: Bearer TEMP_TOKEN" \
  -F "file=@/path/to/dist.zip" \
  https://www.weavefox.cn/api/open/v1/apps/YOUR_PUBLIC_ID/upload-artifact-zip

POST /apps/:publicId/versions

从 zip URL 创建应用版本。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
artifactZipUrlbodystring是产物 zip 的 URL,必须为 upload_artifact_zip 返回的站内地址,其他地址返回 400
changelogbodystring是版本更新日志,1-2000 字符
previewImgbodystring否预览截图 URL

响应

字段类型说明
codenumber0 表示成功
dataobject版本创建结果
data.versionstring新创建的版本号,如 v1
data.fileCountnumber产物文件数
data.totalSizenumber产物总大小(字节)

GET /apps/:publicId/versions

分页查询应用版本列表。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
pagequerynumber否页码,默认 1
pageSizequerynumber否每页条数,最大 100,默认 20

响应

字段类型说明
codenumber0 表示成功
dataobject分页数据
data.versionsAppVersionDTO[]版本列表,结构见「版本对象 AppVersionDTO」
data.hasMoreboolean是否还有下一页
data.totalnumber总条数

POST /apps/:publicId/versions/:version/deploy

部署指定版本为当前线上版本。

参数

参数位置类型必填说明
publicIdpathstring是应用 ID
versionpathstring是版本号,如 v1
securityCheckIdbodystring否安全检查 ID,仅在确认安全风险后重新部署时需要

响应

字段类型说明
codenumber0 表示成功
dataobject部署结果
data.successboolean是否部署成功
data.securityCheckobject可选,安全检测发现风险时返回
data.securityCheck.idstring安全检查 ID,确认安全后作为 securityCheckId 重新部署
data.securityCheck.issuesobject[]风险项列表
data.securityCheck.issues[].severitystring风险等级(low/medium/high)
data.securityCheck.issues[].titlestring风险标题
data.securityCheck.issues[].descriptionstring风险描述
data.securityCheck.issues[].recommendationstring修复建议
data.securityCheck.issues[].resourceobject风险涉及的资源定位(如 filePath、lineNumber 等)