慧企星助开放平台文档

项目任务接口

项目任务接口管理项目下尚未发出的任务（查询、创建草稿、单字段修改、审批通过、审批后直接执行、发送、删除和附件）。项目任务发送后会以同一任务 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,
        "createTrueName": "张三"
      }
    ]
  }
}

POST /api/openplatform/projectTasks

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

参数	类型	必填	说明
`planId`	guid	是	所属项目 Id。不传返回 `400`“planId 不能为空”。
`name`	string	是	任务名称，不能为空，否则返回 `400`“项目任务名称不能为空”。
`content`	string	否	任务内容说明。
`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`。传其它值返回 `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、delete 会改变任务的可用状态且不可轻易撤销，调用前请向用户确认目标任务与影响范围。队列类操作返回“已受理”只代表消息已投递，最终状态请重新查询详情。projectTask.sent 之后任务已落地为正式任务，如需继续操作应改用任务接口。

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，创建参数与 REST 创建请求一致；update 必须提供 taskId 与 field（name/content/priority/score/dueAt/assignees/participants/checker）及对应字段；field=score 时可同时传 difficulty、estimatedHours、estimatedHoursUnit，不传会沿用任务当前值；pass、audit、send、delete 必须提供 taskId；addAttachment 使用 url 或 resourceId（至少一项）。

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