秒客来AI 开放平台文档

项目任务接口

项目任务接口管理项目下尚未发出的任务（查询、创建草稿、单字段修改、审批通过、审批后直接执行、发送、删除和附件）。项目任务发送后会以同一任务 Id 落地为正式任务，后续请改用任务接口继续操作。接口需要 projectTasks.read（查询）与 projectTasks.write（创建与所有写操作）权限。任务返回的状态字段 status 为数字枚举：0 待审批、1 已通过、2 已发送、3 已变更、4 发送失败，statusStr 为后端返回的状态名称。所有接口都只访问当前企业且继续由源站校验当前操作人的业务权限。

必填请求头：项目任务全部接口（含查询）都必须通过 X-Employee-Virtual-Id 指定当前操作人，接口只返回该员工可见范围内的数据。未传或无效时返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”。

写请求约定：所有 POST、PATCH 请求还需携带 UUID 格式的 X-Client-Request-Id；同一业务重试必须复用同一请求标识，并重新生成 X-Nonce、X-Timestamp 与签名。

标识字段约定：员工字段一律使用 virtualId 传入与返回，接口不会返回员工内部 Guid；planId、groupId、labelIds、preTaskIds、postTaskIds 是项目、分组、标签与项目任务等业务对象 Id，使用业务对象的 Guid，与员工身份无关。

GET /api/openplatform/projectTasks

分页查询指定项目下当前操作人可见的项目任务，需要 projectTasks.read 权限。项目 Id 必填，接口先校验当前操作人对该项目的访问权限，无权限时返回 403“项目不存在或您没有权限查看”。

参数	类型	必填	说明
`planId`	guid	是	所属项目 Id。不传返回 `400`“planId 不能为空”。
`page`	int	否	页码，从 `1` 开始，默认 `1`。
`pageSize`	int	否	每页条数，默认 `20`，范围 `1`-`100`。
`keyword`	string	否	名称关键词。

返回统一分页结构：data.total、data.page、data.pageSize、data.items。条目主要字段如下：

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 8,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "3f6b2c1a-9d4e-4f70-8a15-2b3c4d5e6f70",
        "name": "完成需求调研",
        "status": 0,
        "statusStr": "待审批",
        "priority": 3,
        "score": 2,
        "progress": 0,
        "dueAt": "2026-09-25T18:00:00+08:00",
        "createdAt": "2026-09-16T10:00:00+08:00",
        "isSend": false,
        "creator": { "virtualId": "emp_9eYoYgFAY4dbFcFyaaMEvTvMW_eErsjE", "name": "张三", "phone": "138****0000" }
      }
    ]
  }
}

POST /api/openplatform/projectTasks

创建项目任务草稿，需要 projectTasks.write 权限，并必须传 X-Employee-Virtual-Id。名称 name 与所属项目 planId 必填；创建成功后任务处于未发送状态，需要调用 send 动作正式下发。

参数	类型	必填	说明
`planId`	guid	是	所属项目 Id。不传返回 `400`“planId 不能为空”。
`name`	string	是	任务名称，不能为空，否则返回 `400`“项目任务名称不能为空”。
`content`	string	否	任务内容说明。纯文本会自动包装为富文本段落（`<p>`/`<br/>`，HTML 转义后按换行拆段），已含 HTML 标签的原样透传；不包装时任务发出落地会因源站富文本校验被清空。
`remark`	string	否	任务备注。
`groupId`	guid	否	任务分组 Id（项目内分组）。
`assigneeVirtualIds`	string[]	否	负责人 `virtualId` 数组。包含无效 `virtualId` 时返回 `400`。
`participantVirtualIds`	string[]	否	参与人 `virtualId` 数组。
`checkerVirtualId`	string	否	考核人 `virtualId`；不传表示不指定考核人。
`score`	decimal	否	完成贡献点，默认 `0`。
`auditScore`	decimal	否	审核贡献点，默认 `0`。
`priority`	int	否	优先级，取值 `1`-`5`，默认 `3`。
`labelIds`	guid[]	否	标签 Id 数组（业务对象 Id，非员工 Id）。
`checkItems`	string[]	否	检查项名称数组。
`attachmentUrls`	string[]	否	附件地址数组，地址先通过附件上传接口取得。
`sendAt`	datetime	否	发送时间，ISO 8601 格式；不传按当前时间。
`dueAt`	datetime	否	截止时间，ISO 8601 格式；不传按发送时间加执行时长推导。
`duration`	int	否	执行时长（小时），用于推导截止时间；不传截止时间时最少按 `1` 小时计算。
`requiresCompletionAttachment`	bool	否	完成时是否必须上传附件，默认 `false`。
`customItem`	string	否	自定义分组内容。
`preTaskIds`	guid[]	否	前置项目任务 Id 数组。
`postTaskIds`	guid[]	否	后置项目任务 Id 数组。

{
  "planId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "name": "完成需求调研",
  "content": "访谈关键用户并输出调研报告",
  "remark": "",
  "groupId": "00000000-0000-0000-0000-000000000000",
  "assigneeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "participantVirtualIds": [],
  "checkerVirtualId": "emp_Q2mYk8rLp4cN1sVx3bH9wAe6fJuKzT7",
  "score": 2,
  "auditScore": 0,
  "priority": 3,
  "labelIds": [],
  "checkItems": ["输出调研报告"],
  "attachmentUrls": [],
  "sendAt": "2026-09-20T09:00:00+08:00",
  "dueAt": "2026-09-25T18:00:00+08:00",
  "duration": 24,
  "requiresCompletionAttachment": false,
  "customItem": "",
  "preTaskIds": [],
  "postTaskIds": []
}

事件通知：创建成功会推送 projectTask.created 事件。

GET /api/openplatform/projectTasks/{id}

获取项目任务详情，需要 projectTasks.read 权限。任务 Id 为任务资源标识；员工字段统一返回 virtualId，不会返回员工内部 Guid。返回字段包括标题、内容、备注、优先级、贡献点、进度、状态（status/statusStr）、任务难度 difficulty、预计工时 workingHoursData、截止时间、发送时间、检查项、附件、标签以及所属项目信息（planId、planTitle）等。

PATCH /api/openplatform/projectTasks/{id}

单字段修改，需要 projectTasks.write 权限。请求体使用 field 指定要修改的字段名（大小写不敏感），并传对应字段值；一次只能修改一个字段。

参数	类型	必填	说明
`field`	string	是	要修改的字段名，支持 `name`、`content`、`priority`、`score`、`dueAt`、`groupId`、`assignees`、`participants`、`checker`、`preTaskIds`、`postTaskIds`。传其它值返回 `400`“不支持的项目任务修改字段”。
前后置任务说明：`field=preTaskIds` / `field=postTaskIds` 时请求体须同时携带 `preTaskIds` / `postTaskIds`（项目任务 Id 的 guid 数组，整体替换语义：以传入集合为最终状态，传 `[]` 表示清空；未同时携带对应数组返回 `400`）。源站校验前后置任务属于当前项目。
`name`	string	否	`field=name` 时使用，新名称。
`content`	string	否	`field=content` 时使用，新内容。
`priority`	int	否	`field=priority` 时使用，取值 `1`-`5`。
`score`	decimal	否	`field=score` 时使用，新贡献点。
`difficulty`	int	否	`field=score` 时使用，任务难度，取值 `1`-`5`；不传沿用任务当前难度，任务难度无法回读时返回 `400`“修改贡献点必须同时提供 difficulty，或确保任务详情可回读当前难度”。
`estimatedHours`	decimal	否	`field=score` 时使用，预计工时数值，不能为负数；不传沿用任务当前预计工时。
`estimatedHoursUnit`	int	否	`field=score` 时使用，预计工时单位：`1` 小时、`2` 天；不传沿用任务当前单位。
`dueAt`	datetime	否	`field=dueAt` 时使用且必填，新截止时间，ISO 8601 格式；不传返回 `400`“修改截止时间必须提供 dueAt”。
`groupId`	string	否	`field=groupId` 时使用，新分组 Id，必须属于当前项目；传空串表示移出分组。
`assigneeVirtualIds`	string[]	否	`field=assignees` 时使用，整体替换负责人列表；项目任务当前仅支持单个负责人，传多位返回 `400`。
`participantVirtualIds`	string[]	否	`field=participants` 时使用，整体替换参与人列表。
`checkerVirtualId`	string	否	`field=checker` 时使用，新的考核人 `virtualId`；传空表示清空考核人。

{
  "field": "score",
  "score": 3,
  "difficulty": 3,
  "estimatedHours": 4,
  "estimatedHoursUnit": 1
}

贡献点修改语义：源站贡献点修改接口按「贡献点 + 任务难度 + 预计工时」整体覆盖任务属性，因此可同时传 difficulty（1-5）、estimatedHours、estimatedHoursUnit（1 小时、2 天）。不传时会自动沿用任务当前值，不会改写为默认值；若任务详情无法回读当前难度，接口会返回 400 拒绝本次修改。

POST /api/openplatform/projectTasks/{id}/actions/{action}

执行项目任务操作，需要 projectTasks.write 权限。action 支持以下取值（大小写不敏感）：

action	说明	额外参数
`pass`	项目任务审批通过。队列类操作，返回“已受理”仅表示消息已投递。	-
`audit`	进行中审批后直接执行。队列类操作。	-
`send`	将项目任务正式下发，下发后任务 Id 不变，业务实体切换为正式任务。仅系统自动发送失败且任务仍为可发送状态时人工调用；项目未进行中时不得因已通过或待发送重复调用。队列类操作。	-
`delete`	删除项目任务。	-
`addAttachment`	追加附件，同步执行；`url` 与 `resourceId` 至少传一项，地址先通过附件上传接口取得，附件不存在时返回“上传的附件不存在！”。	`url` 或 `resourceId`

传其它 action 返回 400“不支持的项目任务操作”。

{
  "action": "addAttachment",
  "url": "https://resource.example.com/files/report.docx"
}

事件通知：审批通过会推送 projectTask.passed 事件；任务真正发出（落地为正式任务）后推送 projectTask.sent 事件，发送动作使任务进入“待发送”等待时不推送该事件。项目任务审批不通过暂未提供对外接口，因此不存在对应的不通过事件；删除操作不推送事件。

调用约束：项目未处于“进行中”时项目任务不会发出，系统会在项目进入“进行中”时自动尝试发送：无未完成前置且已到发送时间的任务立即发出，其余进入“待发送”等待（前置任务提交完成后或到发送时间自动发出），此时不得循环调用 send。项目进行中时仅“已通过”或“待发送”状态可人工调用 send；存在未完成前置或未到发送时间时 send 会使任务重新进入等待。任务贡献点低于企业要求的最低值时 send 会被拒绝（提示如“任务贡献点应大于等于1”），创建或修改任务时应把 score 设置为不小于企业最低贡献点。任务发出后，后续列表、详情、字段修改、状态流转和操作记录必须使用正式任务接口 /api/openplatform/tasks，不再调用项目任务接口。send、delete 会改变任务状态，调用前请向用户确认目标任务与影响范围。

GET /api/openplatform/projectTasks/{id}/operationRecords

查询项目任务操作记录，需要 projectTasks.read 权限。支持 page（默认 1）、pageSize（默认 20，范围 1-100），返回统一分页结构（data.total、data.page、data.pageSize、data.items）。

MCP 工具 project_task_query

项目任务查询工具，需要 projectTasks.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：list 分页列表（默认）、detail 任务详情、operationRecords 操作记录。

{
  "queryType": "list",
  "planId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "page": 1,
  "pageSize": 20,
  "keyword": "调研"
}

参数映射：queryType=list 必须提供 planId，对应 REST 列表的项目过滤；queryType=detail 与 queryType=operationRecords 必须提供 taskId，对应 REST 路径 {id} 与 {id}/operationRecords；keyword、page、pageSize 与 REST 语义一致。taskId、planId 为业务对象 Id，不是员工 Id。

MCP 工具 project_task_action

项目任务写操作工具，需要 projectTasks.write 权限。action 取值：create、update、pass、audit、send、delete、addAttachment。

{
  "action": "update",
  "taskId": "3f6b2c1a-9d4e-4f70-8a15-2b3c4d5e6f70",
  "field": "score",
  "score": 3,
  "difficulty": 3,
  "estimatedHours": 4,
  "estimatedHoursUnit": 1
}

参数说明：create 必须提供 planId，成功返回有效 id；批量负责人创建时还返回全部 ids。update 必须提供 taskId 与 field（name/content/priority/score/dueAt/assignees/participants/checker/preTaskIds/postTaskIds）及对应字段；field=score 时可同时传 difficulty、estimatedHours、estimatedHoursUnit，不传会沿用任务当前值；pass、audit、send、delete 必须提供 taskId；addAttachment 使用 url 或 resourceId（至少一项）。

发送边界：项目未进行中时，“已通过”或“待发送”不是人工发送失败，系统将在项目进入进行中时自动尝试发送：无未完成前置且已到发送时间的任务立即发出，其余进入“待发送”等待。项目进行中时仅“已通过”或“待发送”状态可人工 send，“已发送”任务不能重复 send；存在未完成前置或未到发送时间时 send 会使任务重新进入“待发送”等待。任务发出后必须切换为正式任务工具：task_list、task_get_detail、task_update、task_execute_action、task_get_progress_records。

调用约束：MCP 写操作直接生效，不经过工作台草稿确认。删除、发送、审批都会改变任务状态，调用前必须把任务名称、目标状态与关键参数完整展示给用户并取得明确确认。