文件管理 API

本文档描述了 Trae 文件管理功能的 API 接口。

概述

文件管理 API 提供了文件和目录的创建、读取、更新、删除等操作，支持文件搜索、版本控制和权限管理。

端点

获取文件列表

GET /api/files/list?path={path}&recursive={recursive}

查询参数

参数	类型	必需	描述
path	string	否	目录路径，默认为根目录
recursive	boolean	否	是否递归列出子目录
include_hidden	boolean	否	是否包含隐藏文件
filter	string	否	文件类型过滤器

响应

{
  "files": [
    {
      "name": "app.js",
      "path": "/src/app.js",
      "type": "file",
      "size": 1024,
      "modified_at": "2024-01-01T00:00:00Z",
      "permissions": "rw-r--r--"
    },
    {
      "name": "components",
      "path": "/src/components",
      "type": "directory",
      "size": 0,
      "modified_at": "2024-01-01T00:00:00Z",
      "permissions": "rwxr-xr-x"
    }
  ],
  "total": 2
}

读取文件内容

GET /api/files/content?path={path}

响应

{
  "path": "/src/app.js",
  "content": "console.log('Hello World');",
  "encoding": "utf-8",
  "size": 25,
  "modified_at": "2024-01-01T00:00:00Z"
}

创建文件

POST /api/files/create

请求参数

参数	类型	必需	描述
path	string	是	文件路径
content	string	否	文件内容
encoding	string	否	文件编码，默认 utf-8
overwrite	boolean	否	是否覆盖已存在文件

响应

{
  "path": "/src/new-file.js",
  "created_at": "2024-01-01T00:00:00Z",
  "size": 0
}

更新文件内容

PUT /api/files/content

请求参数

参数	类型	必需	描述
path	string	是	文件路径
content	string	是	新的文件内容
encoding	string	否	文件编码
create_backup	boolean	否	是否创建备份

响应

{
  "path": "/src/app.js",
  "updated_at": "2024-01-01T00:00:00Z",
  "size": 1024,
  "backup_path": "/src/app.js.backup"
}

删除文件

DELETE /api/files/delete

请求参数

参数	类型	必需	描述
path	string	是	文件或目录路径
recursive	boolean	否	删除目录时是否递归删除
force	boolean	否	强制删除

移动/重命名文件

POST /api/files/move

请求参数

参数	类型	必需	描述
source_path	string	是	源路径
target_path	string	是	目标路径
overwrite	boolean	否	是否覆盖目标文件

响应

{
  "source_path": "/src/old-name.js",
  "target_path": "/src/new-name.js",
  "moved_at": "2024-01-01T00:00:00Z"
}

复制文件

POST /api/files/copy

请求参数

参数	类型	必需	描述
source_path	string	是	源路径
target_path	string	是	目标路径
overwrite	boolean	否	是否覆盖目标文件

创建目录

POST /api/files/mkdir

请求参数

参数	类型	必需	描述
path	string	是	目录路径
recursive	boolean	否	是否递归创建父目录
permissions	string	否	目录权限

搜索文件

GET /api/files/search?query={query}&path={path}&type={type}

查询参数

参数	类型	必需	描述
query	string	是	搜索关键词
path	string	否	搜索路径
type	string	否	文件类型 (file/directory)
extension	string	否	文件扩展名
size_min	number	否	最小文件大小
size_max	number	否	最大文件大小

响应

{
  "results": [
    {
      "path": "/src/components/Button.vue",
      "name": "Button.vue",
      "type": "file",
      "size": 2048,
      "modified_at": "2024-01-01T00:00:00Z",
      "match_score": 0.95
    }
  ],
  "total": 1,
  "query": "Button"
}

获取文件信息

GET /api/files/info?path={path}

响应

{
  "path": "/src/app.js",
  "name": "app.js",
  "type": "file",
  "size": 1024,
  "created_at": "2024-01-01T00:00:00Z",
  "modified_at": "2024-01-01T00:00:00Z",
  "permissions": "rw-r--r--",
  "encoding": "utf-8",
  "mime_type": "application/javascript",
  "checksum": "abc123def456"
}

文件上传

POST /api/files/upload

请求参数 (multipart/form-data)

参数	类型	必需	描述
file	file	是	上传的文件
path	string	否	目标路径
overwrite	boolean	否	是否覆盖已存在文件

响应

{
  "path": "/uploads/document.pdf",
  "name": "document.pdf",
  "size": 1048576,
  "uploaded_at": "2024-01-01T00:00:00Z",
  "checksum": "abc123def456"
}

文件下载

GET /api/files/download?path={path}

返回文件的二进制内容，设置适当的 Content-Type 和 Content-Disposition 头。

示例

创建新文件

const response = await fetch('/api/files/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    path: '/src/utils/helper.js',
    content: `export function formatDate(date) {
  return date.toISOString().split('T')[0];
}`,
    encoding: 'utf-8'
  })
});

const result = await response.json();
console.log('文件已创建:', result.path);

读取和更新文件

// 读取文件内容
const readResponse = await fetch('/api/files/content?path=/src/config.js');
const fileData = await readResponse.json();

console.log('当前内容:', fileData.content);

// 更新文件内容
const newContent = fileData.content + '\n// 新增配置';

const updateResponse = await fetch('/api/files/content', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    path: '/src/config.js',
    content: newContent,
    create_backup: true
  })
});

const updateResult = await updateResponse.json();
console.log('文件已更新:', updateResult.updated_at);

搜索文件

const searchResponse = await fetch('/api/files/search?query=component&extension=vue&path=/src');
const searchResults = await searchResponse.json();

console.log(`找到 ${searchResults.total} 个文件:`);
searchResults.results.forEach(file => {
  console.log(`- ${file.path} (匹配度: ${file.match_score})`);
});

批量操作

// 创建项目结构
const directories = [
  '/src/components',
  '/src/utils',
  '/src/assets',
  '/tests'
];

for (const dir of directories) {
  await fetch('/api/files/mkdir', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-token'
    },
    body: JSON.stringify({
      path: dir,
      recursive: true
    })
  });
}

console.log('项目结构已创建');

文件上传

const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];

const formData = new FormData();
formData.append('file', file);
formData.append('path', '/uploads/');
formData.append('overwrite', 'false');

const uploadResponse = await fetch('/api/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token'
  },
  body: formData
});

const uploadResult = await uploadResponse.json();
console.log('文件已上传:', uploadResult.path);