VVCMS MCP 主题文件工具与文件上传

最后更新时间：2026-09-22 18:43:11

1. 主题文件工具的共同前提

这 8 个工具只作用于每次调用时 conf.ThemeRootDir() 解析出的当前主题，不接受主题名或任意绝对根目录。

2. create_theme_file

创建文件，目标已存在时返回冲突错误，父目录会递归创建。

{
  "name": "create_theme_file",
  "arguments": {
    "path": "views/example.html",
    "content": "
Hello
"
  }
}

成功返回：

{
  "path": "views/example.html"
}

文件使用 UTF-8 内容，权限为 0644，父目录权限为 0755。

3. edit_theme_file

完整替换已有普通文件内容：

{
  "name": "edit_theme_file",
  "arguments": {
    "path": "views/example.html",
    "content": "
Updated
"
  }
}

不能编辑目录、符号链接或不存在的文件。

4. delete_theme_file

删除主题内的单个普通文件：

{
  "name": "delete_theme_file",
  "arguments": {
    "path": "views/legacy.html"
  }
}

成功返回被删除的路径：{"path": "views/legacy.html"}。

4.1 行为约定

  • 只接受普通文件。目录不会递归删除（static/old 这类目录会被拒绝），需要清理目录时请先逐个删除其中的文件，再用目录工具处理。
  • 符号链接一律拒绝，与 read_theme_file、edit_theme_file、rename_theme_path 保持一致。
  • 路径不存在返回 404；目标不是普通文件返回 409。
  • 文件是真正从磁盘移除的，删除后同一路径可以重新 create_theme_file。
  • 不可恢复，没有回收站；删除会写入事件日志（type 为 delete），失败尝试同样留痕。

5. create_theme_directory

创建主题目录及不存在的多级父目录：

{
  "name": "create_theme_directory",
  "arguments": {
    "path": "static/assets/icons"
  }
}

目录已存在时返回冲突错误。

6. delete_theme_directory

删除主题内的空目录：

{
  "name": "delete_theme_directory",
  "arguments": {
    "path": "static/legacy-assets"
  }
}

成功返回被删除的路径：{"path": "static/legacy-assets"}。

6.1 行为约定

  • 只删空目录。目录里还有任何条目（文件或子目录）就返回冲突错误，不会递归删除，也不会替调用方搬走内容。清理非空目录的标准做法是：先对每个文件调 delete_theme_file，再自底向上逐层调本工具。
  • 主题根目录本身不可删除（传空字符串或 . 会被拒绝）。
  • 路径不存在返回 404；目标是普通文件或符号链接返回 409。
  • 不可恢复，没有回收站；删除会写入事件日志（type 为 delete）。

7. read_theme_file

读取主题内已有普通文件的内容：

{
  "name": "read_theme_file",
  "arguments": {
    "path": "views/example.html"
  }
}

成功返回：

{
  "path": "views/example.html",
  "content": "
Hello
"
}

不能读取目录或符号链接；单个文件上限 4 MiB，超限返回 theme file is too large。

8. list_theme_directory

列出主题内某个目录的直接子项，path 传空字符串表示主题根目录：

{
  "name": "list_theme_directory",
  "arguments": {
    "path": "views"
  }
}

成功返回：

{
  "path": "views",
  "entries": [
    { "name": "partials", "path": "views/partials", "directory": true },
    { "name": "example.html", "path": "views/example.html", "directory": false }
  ]
}

目录排在文件前面，同类型按名称升序；符号链接会被跳过。目录不存在返回 404，目标不是目录返回 409。

9. rename_theme_path

重命名主题内的文件或目录，from 为原路径，to 为新路径，两个字段都必填：

{
  "name": "rename_theme_path",
  "arguments": {
    "from": "views/example.html",
    "to": "views/home.html"
  }
}

成功返回：{"path": "views/home.html"}。

9.1 行为约定

  • 目标路径的父目录不存在时会递归创建。
  • 目标路径已存在时返回冲突错误，不会覆盖已有内容，也不会做合并。
  • 重命名目录是整体搬迁，子文件跟着一起移动。
  • 源路径不存在返回 404；源路径是符号链接返回 409。
  • 把目录搬进它自己的子树（如 static/a → static/a/icons）返回 400，不会落成 500。
  • 重命名会写入事件日志，change_name 为 path，记录变更前后的路径。

10. 路径安全规则

以下路径会被拒绝：

  • 空路径。
  • 绝对路径。
  • . 或 ..。
  • ../outside 等词法穿越路径。
  • 通过符号链接解析到主题根目录外的路径。

11. MCP upload_file

MCP 参数是 JSON，因此文件内容使用标准 Base64；图片、文档、音视频、压缩包等常见类型都可以上传。

{
  "name": "upload_file",
  "arguments": {
    "filename": "example.png",
    "content_type": "image/png",
    "data": "BASE64_FILE_CONTENT"
  }
}

PNG 示例：

{
  "name": "upload_file",
  "arguments": {
    "filename": "pixel.png",
    "content_type": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
  }
}

成功返回：

{
  "name": "example.png",
  "path": "/uploads/2026/08/22/123456789.png"
}

11.1 说明

  • filename 必填，且必须带扩展名；不能包含 /、\ 或 ..。
  • data 必须是标准 Base64 字符串。
  • content_type 建议填写正确的 MIME 类型。
  • 单个 MCP 请求体上限 32 MB，Base64 解码后的文件上限 20 MB。
  • 扩展名必须在白名单内：图片 jpg/jpeg/png/gif/webp/bmp/ico、文档 pdf/doc/docx/xls/xlsx/ppt/pptx/txt/md/csv/json/xml、压缩包 zip/rar/7z/gz/tar、音视频 mp3/wav/mp4/webm。其他扩展名会被拒绝。
  • MCP 上传复用现有文件上传流程，因此保留 SHA-256 去重、图片 WebP 转换、存储后端配置和文件表记录行为。

12. 外部 API 文件上传

外部文件上传接口支持 PNG、JPEG、GIF、WebP、PDF、ZIP 和其他允许的文件类型。

POST /api/api_file_upload
Content-Type: multipart/form-data
Authorization: Bearer YOUR_USER_TOKEN

文件字段名称必须是 file：

curl -X POST "http://127.0.0.1:8000/api/api_file_upload" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -F "file=@./example.png;filename=example.png;type=image/png"

成功响应示例：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "name": "example.png",
    "path": "/uploads/2026/08/22/123456789.png"
  }
}

12.1 说明

  • API 可以直接上传二进制文件，不需要 Base64。
  • 图片可能根据全局上传配置转换为 WebP。
  • 系统按 SHA-256 去重；相同文件可能直接返回已有文件路径。
  • 文件会根据 MIME 类型和扩展名归类。
  • 缺少 file 时返回文件解析错误。