慧企星助开放平台文档

GET /api/openplatform/tasks

查询任务列表（任务列表唯一入口）。待我操作、我负责的、我参与的、历史任务通过 view 范围参数传入，平台不再提供独立的分类列表接口。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403，错误信息为"请通过 X-Employee-Virtual-Id 指定当前访问用户"。

参数	类型	必填	说明
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。
`view`	string	否	任务分组视图，枚举：`all` 全部可见（默认）、`pendingActions` 待我操作、`ownedByMe` 我负责的、`involvedByMe` 我参与的、`history` 历史任务；与工作台四列表口径一致。
`statuses`	string	否	业务状态过滤，多个以逗号分隔，枚举：`pendingConfirm` 待确认、`pendingReview` 待审核、`pendingApproval` 待审批、`rejected` 被拒收、`appealing` 申诉中、`pendingSend` 待发送、`executing` 执行中、`pendingStart` 待开始、`paused` 已暂停、`suspended` 已挂起、`completed` 已完成（源站状态 3）、`forwarding` 转发中（含转发中、转发拒收、转发任务待审批、转发任务审批不通过）、`overdue` 已超期。业务状态为跨流程分组口径，一个分组含多个实际状态（如 `forwarding` 覆盖转发链路全部状态），不传表示不限状态。
`labelIds`	guid[]	否	标签过滤，任务需包含全部指定标签；标签 Id 来自 `GET /api/openplatform/labels`。
`creatorVirtualId`	string	否	发起人员工 `virtualId` 过滤。
`assigneeVirtualId`	string	否	负责人员工 `virtualId` 过滤。
`priority`	int	否	优先级过滤（1-5，数值越大越紧急）。
`dueAtFrom` / `dueAtTo`	string	否	截止时间范围，ISO 8601 带时区字符串，如 `2026-06-18T00:00:00+08:00`。
`receivedAtFrom` / `receivedAtTo`	string	否	接收时间范围，ISO 8601 带时区字符串。
`healthDegree`	string	否	健康度过滤，枚举：`green` 绿灯、`yellow` 黄灯、`red` 红灯。
`taskType`	string	否	任务类型过滤，枚举：`automation` 自动化任务、`collaboration` 协作任务、`project` 项目任务、`reward` 悬赏任务（已领取）。
`projectStatus`	string	否	所属项目状态过滤，枚举：`ing` 进行中、`atRisk` 有风险、`outOfControl` 失控、`paused` 暂停、`needJudge` 待评定。
`keyword`	string	否	任务名称关键字。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "完成季度复盘",
        "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "dueAt": "2026-06-19T00:00:00+08:00",
        "priority": 3,
        "status": 2,
        "createdAt": "2026-06-17T18:40:00+08:00",
        "projectId": "1b6eca4d-202b-4f73-907e-ea3f6334a883",
        "projectName": "二季度经营改进",
        "labels": ["季度复盘"],
        "type": 3,
        "typeStr": "项目任务",
        "isStarred": true,
        "isMilestone": false,
        "overTime": 0,
        "difficulty": 3,
        "healthDegree": 0
      }
    ]
  }
}

列表响应字段

字段	类型	说明
`data.total`	long	符合筛选条件的任务总数。
`data.page`	int	当前页码，从 1 开始。
`data.pageSize`	int	当前页返回条数上限，范围为 1 到 100。
`data.items`	TaskListItem[]	当前页任务列表。

TaskListItem 字段

字段	类型	说明
`id`	guid	任务资源标识，用于详情和动作路径。
`name`	string	任务名称。
`assignee`	object	当前负责人在本 API Key 下的成员对象（含 `virtualId`、`name` 与掩码 `phone`）；未分配时为空对象（各字段均为空字符串）。
`dueAt`	string \| null	截止时间，ISO 8601 带时区字符串；未设置时为 `null`。
`priority`	int	任务优先级。
`status`	int	任务当前状态码；可结合任务操作初始化接口判断可执行动作。
`statusStr`	string	任务状态中文文案，与 `status` 配套返回。
`createdAt`	string	创建时间，ISO 8601 带时区字符串。
`apiKeyName`	string	创建任务的三方应用名称；非开放平台创建的任务为空字符串。
`sourceAppText`	string	来源应用展示文案，如「来源于成员「张三」的个人MCP「笔记本」」或「来源于开放平台应用「工单系统」」；非开放平台创建的任务为空。
`operateBtns`	array	当前操作人在该任务上可执行的操作按钮，每项仅含 `name`（动作名）与 `label`（中文文案），调用任务操作接口前可据此判断动作可用性。
`projectId`	guid	所属项目 Id；非项目任务为零值 Guid。
`projectName`	string \| null	所属项目名称；无项目时为 `null`。
`groupId`	guid	所属项目分组 Id；无分组为零值 Guid。
`groupName`	string \| null	所属项目分组名称；无分组时为 `null`。
`targetId`	guid	所属目标 Id；未关联目标为零值 Guid。
`targetName`	string \| null	所属目标名称；未关联目标时为 `null`。
`isStarred`	bool	当前操作人是否已关注该任务。
`isMilestone`	bool	是否里程碑任务。
`type`	int	任务类型：1 自动化任务、2 协作任务、3 项目任务、4 悬赏任务（已领取）。
`typeStr`	string \| null	任务类型文案，与 `type` 配套返回。
`labels`	string[]	任务标签中文名称数组；无标签时为空数组。
`overTime`	int	逾期天数，0 表示未超期。
`difficulty`	int	任务难度，取值 1-5。
`healthDegree`	int	健康度红绿灯：0 绿灯、1 黄灯、2 红灯。
`judgedAt`	string \| null	评定时间，ISO 8601 字符串；仅已审核完成的任务有值。

GET /api/openplatform/tasks/{id}

查询任务详情。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403，错误信息为"请通过 X-Employee-Virtual-Id 指定当前访问用户"。

{ "statusCode": 100, "msg": "获取成功", "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "完成季度复盘", "content": "

整理经营数据并输出总结

", "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz", "dueAt": "2026-06-18T00:00:00+08:00", "priority": 3, "status": 2, "createdAt": "2026-06-17T16:00:00+08:00", "apiKeyName": "我的三方应用", "projectId": "1b6eca4d-202b-4f73-907e-ea3f6334a883", "projectName": "二季度经营改进", "labels": ["季度复盘"], "isStarred": true, "isMilestone": false, "difficulty": 3, "healthDegree": 0, "preTasks": [], "postTasks": [], "checkItems": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "name": "整理经营数据", "isFinish": false } ] } }

详情响应字段

详情返回包含上述 TaskListItem 的 id、name、assignee（成员对象）、dueAt、priority、status、createdAt、apiKeyName 字段，并额外包含以下字段。

字段	类型	说明
`content`	string	任务富文本内容；未填写时为空字符串。
`type`	int	任务类型：1 自动化任务、2 协作任务、3 项目任务。
`typeStr`	string	任务类型文案，与任务列表口径一致。
`statusStr`	string	任务状态文案，与任务列表口径一致。
`creator`	object	创建人的成员对象（含 `virtualId`、`name` 与掩码 `phone`）。
`executorVirtualId`	string	负责人的员工 `virtualId`。
`progress`	decimal	完成进度（0-1）。
`score`	decimal	任务贡献点（单位：点）。
`overTime`	int	逾期天数。
`checkItems`	TaskCheckItem[]	任务检查项列表；没有检查项时为空数组。
`attachments`	TaskAttachment[]	任务附件列表，每项含 `id`、`fileName`、`url`（按操作人相关人校验后签发的短时效下载地址）与 `accessible`；无附件时为空数组。
`sourceAppText`	string	来源应用展示文案（区分企业集成应用与成员个人 MCP）；非开放平台创建的任务为空。
`operateBtns`	array	当前操作人可执行的操作按钮（详情口径，含挂项目/关联目标等详情专有按钮），每项仅含 `name` 与 `label`。
`projectId`	guid	所属项目 Id；非项目任务为零值 Guid。
`projectName`	string \| null	所属项目名称；无项目时为 `null`。
`groupId`	guid	所属项目分组 Id；无分组为零值 Guid。
`groupName`	string \| null	所属项目分组名称；无分组时为 `null`。
`targetId`	guid	所属目标 Id；未关联目标为零值 Guid。
`targetName`	string \| null	所属目标名称；未关联目标时为 `null`。
`isStarred`	bool	当前操作人是否已关注该任务。
`isMilestone`	bool	是否里程碑任务。
`labels`	string[]	任务标签中文名称数组；无标签时为空数组。
`difficulty`	int	任务难度，取值 1-5。
`healthDegree`	int	健康度红绿灯：0 绿灯、1 黄灯、2 红灯。
`preTasks`	TaskPrePost[]	前置任务列表，每项含 `id` 与 `name`；无前置任务时为空数组。
`postTasks`	TaskPrePost[]	后置任务列表，每项含 `id` 与 `name`；无后置任务时为空数组。
`operateAlert`	object \| null	不通过/驳回等状态的操作提示（精简口径），含 `name`（提示标题，如「审批不通过」「被拒收」）与 `reason`（原因文本，可能为空）；正常状态为 `null`。
`judgedAt`	string \| null	评定时间，ISO 8601 字符串；仅已审核完成的任务有值。
`judgeScore`	decimal \| null	评定等级；仅已审核完成的任务有值。

TaskCheckItem 字段

字段	类型	说明
`id`	guid	检查项标识，可用于 `changeCheckItem` 等任务动作。
`name`	string	检查项名称。
`isFinish`	bool	是否已完成。

TaskPrePost 字段

preTasks（前置任务）与 postTasks（后置任务）是两个互相独立的字段，各有各的取值、不可互换：前置任务指必须先于本任务完成的任务，后置任务指需待本任务完成后才可开展的任务；两者共用下列项结构（源站字段名为 title，公开响应统一归一为 name）。

字段	类型	说明
`id`	guid	前置/后置任务 Id，可用于任务详情查询。
`name`	string	前置/后置任务标题（源站字段 `title` 归一后的公开名）。

字段说明：apiKeyName 表示创建该任务的三方应用名称，非开放平台创建的任务该字段为空字符串；checkItems 为任务检查项列表，每项包含公开 id、name 和是否完成的 isFinish。

POST /api/openplatform/tasks

创建任务。

参数	类型	必填	说明
`name`	string	是	任务名称。
`content`	string	否	编码后的富文本内容。请按 URL 编码口径提交；开放平台接收后会先做 URL 解码，再做 HTML 解码，最终按原始富文本存储。
`assigneeVirtualIds`	string[]	条件必填	负责人 `virtualId` 列表。正式发送任务时至少 1 个；保存草稿时可不传。
`checkerVirtualId`	string	否	考核人 `virtualId`。
`ccVirtualIds`	string[]	否	抄送人 `virtualId` 列表。
`priority`	int	否	优先级，默认 3。
`dueAt`	string	条件必填	截止时间。正式发送任务时必填；保存草稿时可不传。传值时必须显式带时区信息，例如 `2026-06-18T00:00:00+08:00` 或 `2026-06-17T16:00:00Z`。
`score`	decimal	否	关联贡献点，单位为“点”。
`labelIds`	guid[]	否	标签 ID 列表。
`projectId`	guid	否	所属项目 ID。不传时请直接省略该字段，或显式传 `null`；不要传空字符串 `""`。
`isDraft`	bool	否	是否保存草稿。
`sendAt`	string	否	发送时间，ISO 8601 标准时间字符串，且必须显式带时区信息，例如 `2026-06-17T19:00:00+08:00` 或 `2026-06-17T11:00:00Z`。
`completeAttachment`	bool	否	完成任务时是否必须上传附件。
`checkItems`	string[]	否	检查项列表。
`attachmentUrls`	string[]	否	已上传附件 URL 列表。

{
  "name": "完成季度复盘",
  "content": "%3Cp%3E%E6%95%B4%E7%90%86%E7%BB%8F%E8%90%A5%E6%95%B0%E6%8D%AE%E5%B9%B6%E8%BE%93%E5%87%BA%3Cstrong%3E%E6%80%BB%E7%BB%93%3C%2Fstrong%3E%3C%2Fp%3E",
  "assigneeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "priority": 3,
  "dueAt": "2026-06-18T00:00:00+08:00",
  "score": 5
}

富文本约定：content 必须传已做 URL 编码的富文本字符串，例如先把 <p>...</p> 执行 encodeURIComponent 后再提交。开放平台会先做 URL 解码，再补做 HTML 解码，最终按富文本原文存储。

请求体约定：可选的 guid 字段（如 projectId）如果没有值，请直接省略或传 null；不要传空字符串 ""。dueAt、sendAt 传值时必须使用带时区信息的 ISO 8601 标准时间字符串，例如 2026-06-18T00:00:00+08:00 或 2026-06-17T16:00:00Z；不接受没有时区的裸时间字符串。score、isDraft、completeAttachment 建议按标准 JSON 数字/布尔值传递，不要全部转成字符串。

草稿规则：当 isDraft=true 时，当前开放平台只强制要求 name；assigneeVirtualIds、dueAt、checkerVirtualId、ccVirtualIds、score、labelIds、projectId、sendAt、completeAttachment、checkItems、attachmentUrls 都可省略。正式发送任务时，仍至少需要负责人和截止时间。

{
  "statusCode": 100,
  "msg": "创建成功",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "完成季度复盘",
    "createdAt": "2026-06-17T16:00:00+08:00"
  }
}

兼容性提示：score 支持按数字提交，也兼容数字字符串；但仍建议三方按标准 JSON 数字传值，避免不同语言序列化差异。

DELETE /api/openplatform/tasks/{id}

撤销任务。只有任务创建人才能撤销，且任务状态必须为进行中、待开始、暂停、待审批、草稿、拒收、新任务、审批不通过、转发中、挂起申请之一。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。

DELETE /api/openplatform/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Host: your-domain.com
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

路径参数：

参数	类型	必填	说明
`id`	guid	是	任务 ID。

{
  "statusCode": 100,
  "msg": "撤销成功"
}

注意事项：撤销任务是不可逆操作，请谨慎调用。如果任务有子任务，必须先撤销所有子任务。撤销成功后会触发 task.canceled Webhook 事件。

PATCH /api/openplatform/tasks/{id}

修改任务。请求体必须且只能包含一个可修改字段。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。

PATCH /api/openplatform/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Host: your-domain.com
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

路径参数：

参数	类型	必填	说明
`id`	guid	是	任务 ID。

请求体参数：

字段	类型	必填	说明
`name`	string	否	任务名称。
`content`	string	否	任务内容。
`score`	decimal	否	任务贡献点，单位为“点”。
`priority`	int	否	任务优先级。
`dueAt`	string	否	截止时间，ISO 8601。
`projectId`	guid	否	项目挂靠：传入项目 Id 将任务挂入该项目；传空字符串 `""` 表示移出项目。
`alignTargetId`	guid	否	对齐的目标 Id；传空字符串 `""` 表示解除对齐。
`keyResultIds`	string[]	否	关联的关键结果 Id 列表；传空数组 `[]` 表示解除全部关联。需先对齐目标。
`assigneeVirtualId`	string	否	负责人 virtualId。
`checkerVirtualId`	string	否	检查人 virtualId。
`ccVirtualIds`	string[]	否	抄送人 virtualId 列表。
`competenceId`	string	否	能力需求 Id 数组 JSON 字符串，例如 `["能力 Id"]`；传 `[]` 表示清空能力需求。
`groupId`	guid	否	项目任务分组 Id；传空字符串 `""` 表示移出分组。
`checkItem`	object	否	检查项编辑 JSON，格式与工作台任务检查项编辑契约一致。
`completeAttachment`	bool	否	完成任务时是否必须上传附件。
`estimatedHours`	decimal	否	预计工时，不能小于 0。
`preTaskIds`	string[]	否	前置任务 Id 列表；传空数组表示清空全部前置关系。
`postTaskIds`	string[]	否	后置任务 Id 列表，与 `preTaskIds` 是两个互相独立的字段；传空数组表示清空全部后置关系。
`difficulty`	int	否	任务难度，取值 1-5。
`reason`	string	否	修改原因，建议填写以便追溯

请求示例 1：修改名称

{
  "name": "修改后的任务名称",
  "reason": "名称描述不准确"
}

请求示例 2：修改截止时间

{
  "dueAt": "2026-06-20T18:00:00+08:00",
  "reason": "项目延期"
}

请求示例 3：修改负责人

{
  "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"
}

请求示例 4：把任务挂进指定项目

{
  "projectId": "1b6eca4d-202b-4f73-907e-ea3f6334a883"
}

请求示例 5：为任务建立对齐目标

{
  "alignTargetId": "0c4e5a71-6f5e-4c22-9e2b-3d1a0f8b7c01"
}

响应示例：

{
  "statusCode": 100,
  "msg": "修改成功"
}

字段格式说明：

name：字符串，如 "新任务名称"
content：URL 编码后的富文本字符串，需先 encodeURIComponent("<p>内容</p>")
score：数值，如 5.5
priority：整数(1-5)，如 3(1最低，5最高，默认 3；分解任务不传时按 3 处理，越界值将被拒绝)
dueAt：ISO 8601 时间字符串(必须带时区)，如 "2026-06-18T00:00:00+08:00"
assigneeVirtualId：单个负责人 virtualId，如 "emp_xxx"
ccVirtualIds：virtualId 数组，如 ["emp_xxx1"]
checkerVirtualId：单个检查人 virtualId，如 "emp_xxx"
projectId：项目 Id，如 "1b6eca4d-..."；传 "" 表示移出项目（其余可选 guid 字段「省略或 null」的约定不适用于本字段的清空语义）
alignTargetId：目标 Id；传 "" 表示解除对齐
keyResultIds：关键结果 Id 数组，如 ["0c4e5a71-..."]；传 [] 表示解除全部关联

注意事项：修改操作异步处理，返回成功表示请求已接受。修改内容时，content 必须先做 URL 编码；修改截止时间时，dueAt 必须带时区信息。修改成功后会触发 task.changed Webhook 事件。

Webhook 异步触发说明：task.changed 事件是异步触发的。接口返回成功仅表示修改请求已提交到消息队列，实际修改操作由后台异步处理。第三方应用应在收到 task.changed Webhook 事件后，通过事件负载中的最新数据更新本地缓存，不要依赖接口返回立即查询任务详情，因为此时修改可能尚未完成。

PUT /api/openplatform/tasks/{id}/labels

全量替换任务标签：以请求中的标签 Id 集合为最终状态，需要新增与移除的标签由平台自动补差完成，与工作台标签维护同链路（操作人需为任务相关人）。同步处理，返回成功即已生效。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。

路径参数：

参数	类型	必填	说明
`id`	guid	是	任务 ID。

请求体参数：

字段	类型	必填	说明
`labelIds`	guid[]	是	替换后的标签 Id 全集，来自 `GET /api/openplatform/labels`；重复 Id 自动去重；传空数组 `[]` 表示清空任务全部标签。

请求示例：

PUT /api/openplatform/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/labels
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

{
  "labelIds": [
    "2f6e8a10-3c4b-4d5e-9f80-a1b2c3d4e5f6",
    "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
  ]
}

响应示例：

{
  "statusCode": 100,
  "msg": "修改成功"
}

注意事项：本接口为全量替换语义，未出现在 labelIds 中的已有标签会被移除；只想追加标签时，请先通过任务详情读取当前标签再合并提交。标签不存在、操作人无任务权限等业务校验失败时返回对应错误，已生效的部分变更不回滚。

任务接口

列表响应字段

TaskListItem 字段

详情响应字段

TaskCheckItem 字段

TaskPrePost 字段