协作 API

本文档描述了 Trae 团队协作功能的 API 接口。

概述

协作 API 提供了团队成员之间实时协作的功能，包括共享编辑、评论、代码审查等。

端点

创建协作会话

POST /api/collaboration/session

请求参数

参数	类型	必需	描述
project_id	string	是	项目 ID
file_path	string	是	文件路径
participants	array	否	参与者列表
permissions	object	否	权限设置

响应

{
  "session_id": "session_123",
  "project_id": "project_456",
  "file_path": "/src/app.js",
  "created_at": "2024-01-01T00:00:00Z",
  "participants": [
    {
      "user_id": "user_1",
      "username": "alice",
      "role": "owner"
    }
  ]
}

加入协作会话

POST /api/collaboration/session/{session_id}/join

请求参数

参数	类型	必需	描述
user_id	string	是	用户 ID

发送实时编辑

POST /api/collaboration/session/{session_id}/edit

请求参数

参数	类型	必需	描述
operation	object	是	编辑操作
cursor_position	number	是	光标位置
timestamp	string	是	时间戳

编辑操作格式

{
  "type": "insert",
  "position": 100,
  "content": "console.log('Hello');",
  "user_id": "user_1"
}

添加评论

POST /api/collaboration/comments

请求参数

参数	类型	必需	描述
file_path	string	是	文件路径
line_number	number	是	行号
content	string	是	评论内容
type	string	否	评论类型

响应

{
  "comment_id": "comment_123",
  "file_path": "/src/app.js",
  "line_number": 15,
  "content": "这里可以优化性能",
  "author": {
    "user_id": "user_1",
    "username": "alice"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "type": "suggestion"
}

获取评论列表

GET /api/collaboration/comments?file_path={file_path}

WebSocket 连接

实时协作功能通过 WebSocket 连接实现：

ws://api.trae.ai/collaboration/ws/{session_id}

WebSocket 消息格式

{
  "type": "edit",
  "data": {
    "operation": {
      "type": "insert",
      "position": 100,
      "content": "new code"
    },
    "user_id": "user_1",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

权限级别

• owner - 拥有者，完全控制权限
• editor - 编辑者，可以编辑和评论
• reviewer - 审查者，只能查看和评论
• viewer - 观察者，只能查看

示例

创建协作会话

const response = await fetch('/api/collaboration/session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    project_id: 'my-project',
    file_path: '/src/components/App.vue',
    participants: ['user_2', 'user_3'],
    permissions: {
      default_role: 'editor'
    }
  })
});

const session = await response.json();
console.log('协作会话已创建:', session.session_id);

建立 WebSocket 连接

const ws = new WebSocket(`ws://api.trae.ai/collaboration/ws/${sessionId}`);

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch (message.type) {
    case 'edit':
      applyEdit(message.data.operation);
      break;
    case 'cursor':
      updateCursor(message.data);
      break;
    case 'comment':
      showComment(message.data);
      break;
  }
};

// 发送编辑操作
function sendEdit(operation) {
  ws.send(JSON.stringify({
    type: 'edit',
    data: {
      operation,
      user_id: currentUserId,
      timestamp: new Date().toISOString()
    }
  }));
}

添加代码评论

const response = await fetch('/api/collaboration/comments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    file_path: '/src/utils/helper.js',
    line_number: 25,
    content: '建议使用更具描述性的变量名',
    type: 'suggestion'
  })
});

const comment = await response.json();
console.log('评论已添加:', comment.comment_id);