跳到主要内容

创建分享链接

创建一个可分享的链接，用于查看任务进度和结果。

端点​

POST https://api.xmz.ai/v1/agentrix/tasks/:taskId/share

认证​

需要在授权头中提供 API 密钥：

Authorization: Bearer YOUR_API_KEY

重要提示​

  • 仅限所有者 ：只有任务所有者可以创建分享链接
  • 仅限云模式 ：仅支持在云模式下运行的任务（machineId 必须为 null）
  • 权限 : 通过权限标志控制观众可以执行的操作

路径参数​

参数类型必需描述
taskId字符串是任务标识符

请求体​

所有字段都是可选的。如果未提供，则应用默认权限。

参数类型默认描述
permissions对象见下文访问权限配置

权限对象​

字段类型默认描述
canSendMessage布尔值false允许向任务发送消息
canCreatePr布尔值false允许创建拉取请求
canApprovePr布尔值false允许批准拉取请求
canViewPr布尔值true允许查看拉取请求
canMergePr布尔值false允许合并拉取请求

请求体架构​

{
  "permissions": {
    "canSendMessage": false,
    "canCreatePr": false,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

响应​

成功响应（201 创建）​

{
  "shareCode": "abc123xyz"
}

响应字段​

字段类型描述
shareCode字符串分享访问任务的代码

错误响应​

400 错误请求​

{
  "code": "INVALID_REQUEST",
  "error": "validation_error",
  "message": "Invalid request parameters"
}

401 未授权​

{
  "code": "UNAUTHORIZED",
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 禁止访问​

{
  "code": "FORBIDDEN",
  "error": "forbidden",
  "message": "Only task owner can create share links"
}

404 未找到​

{
  "code": "TASK_NOT_FOUND",
  "error": "not_found",
  "message": "Task not found"
}

示例​

示例 1：默认权限（仅查看）​

创建具有默认权限（仅查看）的共享链接：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

示例 2：自定义权限​

创建允许发送消息和查看 PR 的共享链接：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canCreatePr": false,
      "canApprovePr": false,
      "canViewPr": true,
      "canMergePr": false
    }
  }'

示例 3：完全权限​

创建一个启用所有权限的分享链接：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canCreatePr": true,
      "canApprovePr": true,
      "canViewPr": true,
      "canMergePr": true
    }
  }'

使用流程​

  1. 任务所有者 ：调用此端点来创建分享链接
  2. 获取分享码 : API 返回一个 shareCode（例如：abc123xyz）
  3. 分享给他人 : 所有者将代码分享给观众
  4. 观众验证 : 观众使用 GET /v1/auth/share?code=<shareCode> 进行验证
  5. 访问任务 : 观众可以根据其权限访问任务

权限详情​

仅查看访问​

默认权限仅允许查看任务进度和结果：

{
  "permissions": {
    "canSendMessage": false,
    "canCreatePr": false,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

交互式访问​

允许观众发送消息并与任务互动：

{
  "permissions": {
    "canSendMessage": true,
    "canCreatePr": true,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

完全访问权限​

赋予观众完全控制权（谨慎使用）：

{
  "permissions": {
    "canSendMessage": true,
    "canCreatePr": true,
    "canApprovePr": true,
    "canViewPr": true,
    "canMergePr": true
  }
}

安全最佳实践​

  1. 最小权限 ：仅授予观众所需的权限
  2. 默认仅查看 : 大多数使用场景只需要 canViewPr: true
  3. 谨慎处理写入权限 : 对 canMergePr 和 canApprovePr 要小心
  4. 私密分享 : 仅与预期查看者分享代码
  5. 监控访问 : 跟踪谁在访问你的共享任务

常见使用场景​

Demo 或作品集​

分享一个完成的任务来展示你的作品（仅查看）：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

协作评审​

允许团队成员查看和评论任务：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canViewPr": true
    }
  }'

客户演示​

与需要批准 PR 的客户分享：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canViewPr": true,
      "canApprovePr": true
    }
  }'

限制​

  • 仅限云模式 ：本地计算机任务无法共享
  • 仅限任务所有者 ：只有创建任务的用户才能创建分享链接
  • 无过期时间 : 当前分享码不会过期（谨慎管理访问权限）

相关端点​

  • 创建任务 - 创建一个分享任务
  • 获取分享信息 - 检索分享链接详情（GET /v1/tasks/:taskId/share）
  • 使用分享码认证 - 观看者认证（GET /v1/auth/share?code=<shareCode> ）

需要帮助？​