慧企星助开放平台文档

自动化任务接口

自动化任务接口提供周期任务的查询、创建、单字段修改、启停、重发、执行、审批和附件操作，需要 automationTasks.read（查询）与 automationTasks.write（创建与所有写操作）权限。周期类型统一使用字符串枚举 cycleType：daily 每天、weekly 每周、monthly 每月；任务状态使用字符串枚举 status：approval 待审批、running 进行中、rejected 已驳回、paused 已暂停。所有接口都只访问当前企业且继续由源站校验当前操作人的业务权限。

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

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

标识字段约定：员工字段一律使用 virtualId 传入与返回，接口不会返回员工内部 Guid；labelIds、templateId、targetId 是业务对象 Id，使用业务对象的 Guid，与员工身份无关。

GET /api/openplatform/automationTasks

分页查询当前操作人可见的自动化任务，需要 automationTasks.read 权限。

参数	类型	必填	说明
`page`	int	否	页码，从 `1` 开始，默认 `1`。
`pageSize`	int	否	每页条数，默认 `20`，最大 `100`；超过上限返回 `400`。
`keyword`	string	否	名称关键词，最长 `100` 字符。
`status`	string	否	任务状态，字符串枚举：`approval` 待审批、`running` 进行中、`rejected` 已驳回、`paused` 已暂停。不传表示不限状态；传其它值返回 `400`，错误信息为“status 必须为 approval、running、rejected 或 paused”。
`cycleType`	string	否	周期类型，字符串枚举：`daily` 每天、`weekly` 每周、`monthly` 每月。不传表示不限周期；传其它值返回 `400`，错误信息为“cycleType 必须为 daily、weekly 或 monthly”。
`creatorVirtualId`	string	否	创建人员工 `virtualId` 过滤；无效时返回 `400`“creatorVirtualId 不存在或不属于当前企业”。不传返回全部可见任务。
`labelIds`	guid[]	否	标签 Id 数组过滤；包含无效 Guid 时返回 `400`“labelIds 必须是有效的标签 Guid 列表”，重复 Id 自动去重。
`priority`	int	否	优先级过滤，取值 `1`-`5`；越界返回 `400`“priority 必须在 1-5 之间”。
`taskType`	string	否	任务类型过滤，字符串枚举：`automation` 自动化任务、`automationReward` 悬赏任务；传其它值返回 `400`。不传表示全部可见类型。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "8d2e3f40-5b6c-4d7e-9f80-1a2b3c4d5e6f",
        "name": "每日客户回访",
        "content": "完成客户回访并记录结果",
        "status": 1,
        "cycleType": 1,
        "cycle": "1,2,3,4,5",
        "sendHour": 9,
        "sendMinute": 0,
        "priority": 3,
        "score": 2,
        "duration": 30,
        "assignees": [
          { "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz", "name": "张三" }
        ],
        "participants": [],
        "startAt": "2026-09-15T00:00:00+08:00",
        "endAt": "2026-12-31T23:59:59+08:00",
        "createdAt": "2026-09-15T08:30:00+08:00"
      }
    ]
  }
}

POST /api/openplatform/automationTasks

创建自动化任务，需要 automationTasks.write 权限，并必须传 X-Employee-Virtual-Id。名称 name 不能为空。

参数	类型	必填	说明
`name`	string	是	任务名称，不能为空，否则返回 `400`“自动化任务名称不能为空”。
`content`	string	否	任务内容说明。
`assigneeVirtualIds`	string[]	否	负责人 `virtualId` 数组。包含无效 `virtualId` 时返回 `400`。
`participantVirtualIds`	string[]	否	参与人 `virtualId` 数组。
`cycleType`	string	否	周期类型，字符串枚举：`daily`、`weekly`、`monthly`，默认 `daily`；传其它值返回 `400`“cycleType 必须为 daily、weekly 或 monthly”。
`cycle`	string	否	周期取值。按天为逗号分隔的天序号，按周为逗号分隔的星期序号，按月为逗号分隔的日期序号。
`sendHour`	int	否	发送时间的小时，取值 `0`-`23`。
`sendMinute`	int	否	发送时间的分钟，取值 `0`-`59`。
`priority`	int	否	优先级，取值 `1`-`5`，默认 `3`。
`score`	decimal	否	完成贡献点，默认 `0`。
`auditScore`	decimal	否	审批贡献点，默认 `0`。
`duration`	int	否	任务时长，单位由业务配置决定。
`checkerVirtualId`	string	否	考核人 `virtualId`；不传表示不指定考核人。
`setCheckerType`	int	否	考核人设置方式，`1` 或 `2`，默认 `1`。
`checkItems`	string[]	否	检查项名称数组。
`attachmentUrls`	string[]	否	附件地址数组，地址先通过附件上传接口取得。
`labelIds`	guid[]	否	标签 Id 数组（业务对象 Id，非员工 Id）。
`requiresCompletionAttachment`	bool	否	完成时是否必须上传附件，默认 `false`。
`difficulty`	int	否	任务难度，取值 `1`-`5`，默认 `2`。
`customItem`	string	否	自定义字段内容。
`templateId`	guid	否	关联任务模板 Id。
`keyResultIdAry`	string	否	关联关键结果 Id 串。
`targetId`	guid	否	关联目标 Id。
`workingHoursData`	object	否	预计工时数据，含 `estimated`（预计工时）、`unit`（`1` 小时、`2` 天）、`convertRatio`（换算比例）。
`endCondition`	int	否	结束条件：`0` 不限、`1` 按次数、`2` 按日期，默认 `0`。
`startAt`	datetime	否	任务生效开始时间，ISO 8601 格式；不传按当前时间。
`endAt`	datetime	否	任务结束时间，`endCondition=2` 时使用；不传表示不限结束时间。
`intervalNum`	int	否	间隔数，默认 `1`。按周时为间隔周数，按月时为间隔月数。
`maxExecutions`	int	否	最大执行次数，`endCondition=1` 时使用。
`skipHolidays`	bool	否	是否跳过节假日，默认 `false`。
`skipSaturdays`	bool	否	是否跳过周六，默认 `false`。
`skipSundays`	bool	否	是否跳过周日，默认 `false`。

{
  "name": "每日客户回访",
  "content": "完成客户回访并记录结果",
  "assigneeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "participantVirtualIds": [],
  "cycleType": "daily",
  "cycle": "1,2,3,4,5",
  "sendHour": 9,
  "sendMinute": 0,
  "priority": 3,
  "score": 2,
  "auditScore": 0,
  "duration": 30,
  "checkerVirtualId": "emp_Q2mYk8rLp4cN1sVx3bH9wAe6fJuKzT7",
  "setCheckerType": 1,
  "checkItems": ["填写回访记录"],
  "attachmentUrls": [],
  "labelIds": [],
  "requiresCompletionAttachment": false,
  "difficulty": 2,
  "templateId": "00000000-0000-0000-0000-000000000000",
  "targetId": "00000000-0000-0000-0000-000000000000",
  "keyResultIdAry": "",
  "workingHoursData": { "estimated": 0.5, "unit": 1, "convertRatio": 8 },
  "endCondition": 1,
  "intervalNum": 1,
  "maxExecutions": 30,
  "startAt": "2026-09-15T00:00:00+08:00",
  "endAt": "2026-12-31T23:59:59+08:00",
  "skipHolidays": true,
  "skipSaturdays": false,
  "skipSundays": false
}

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

GET /api/openplatform/automationTasks/{id}

获取自动化任务详情。任务 Id 为任务资源标识；员工字段统一返回 virtualId，不会返回员工内部 Guid。

PATCH /api/openplatform/automationTasks/{id}

单字段修改，需要 automationTasks.write 权限。请求体使用 field 指定要修改的字段名，并传对应字段值；一次只能修改一个字段。

参数	类型	必填	说明
`field`	string	是	要修改的字段名，支持 `name`、`content`、`priority`、`score`、`duration`、`assignees`、`participants`、`checker`。传其它值返回 `400`“不支持的自动化任务修改字段”。
`name`	string	否	`field=name` 时使用，新名称。
`content`	string	否	`field=content` 时使用，新内容。
`priority`	int	否	`field=priority` 时使用，取值 `1`-`5`。
`score`	decimal	条件必填	`field=score` 时必须提供，新贡献点；只传 `field=score` 而不给值时返回 `400`“修改贡献点必须提供 score”（显式传 `0` 表示把贡献点归零，是合法值）。
`difficulty`	int	否	`field=score` 时使用，任务难度，取值 `1`-`5`；不传沿用任务当前难度。
`estimatedHours`	decimal	否	`field=score` 时使用，预计工时数值，不能为负数；不传沿用任务当前预计工时。
`estimatedHoursUnit`	int	否	`field=score` 时使用，预计工时单位：`1` 小时、`2` 天；不传沿用任务当前单位。
`duration`	int	否	`field=duration` 时使用，新任务时长。
`assigneeVirtualIds`	string[]	否	`field=assignees` 时使用，整体替换负责人列表。
`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 拒绝本次修改，不会改写为默认值；score 本身未提供时同样直接拒绝，避免字段缺失把贡献点静默归零。

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

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

action	说明	额外参数
`repeat`	重发任务。队列类操作，返回“已受理”仅表示消息已投递。	-
`delete`	删除任务。	-
`enable`	启用任务。	-
`disable`	停用任务。	-
`execute`	立即执行任务。队列类操作。	-
`pass`	审批通过。	-
`overrule`	审批驳回，必须传驳回理由。	`reason`
`addAttachment`	追加附件，需传附件地址。	`url` 或 `attachmentUrls`

{
  "action": "overrule",
  "reason": "回访频次过高，请调整为每周一次后重新提交"
}

事件通知：审批通过会推送 automationTask.passed 事件、审批驳回会推送 automationTask.rejected 事件；通过开放平台强制发送成功或失败分别推送 automationTask.sent、automationTask.sendFailed 事件。定时作业自动触发的执行不推送事件。

调用约束：delete、disable、overrule 会改变任务的可用状态，调用前请向用户确认目标任务与影响范围。队列类操作返回“已受理”只代表消息已投递，最终状态请重新查询详情。

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

查询自动化任务操作记录，需要 automationTasks.read 权限。支持 page、pageSize，返回统一分页结构（data.total、data.page、data.pageSize、data.items）。

MCP 工具 automation_task_query

自动化任务查询工具，需要 automationTasks.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：list 分页列表、detail 任务详情、operationRecords 操作记录。

{
  "queryType": "list",
  "page": 1,
  "pageSize": 20,
  "keyword": "客户回访",
  "status": "running",
  "cycleType": "daily"
}

参数映射：queryType=detail 与 queryType=operationRecords 必须提供 taskId，对应 REST 路径 {id} 与 {id}/operationRecords；keyword、status、cycleType、page、pageSize 与 REST 语义一致。taskId 为任务资源 Id，不是员工 Id。

MCP 工具 automation_task_action

自动化任务写操作工具，需要 automationTasks.write 权限。action 取值：create、update、repeat、delete、enable、disable、execute、pass、overrule、addAttachment。

{
  "action": "update",
  "taskId": "8d2e3f40-5b6c-4d7e-9f80-1a2b3c4d5e6f",
  "field": "score",
  "score": 3,
  "difficulty": 3,
  "estimatedHours": 4,
  "estimatedHoursUnit": 1
}

参数说明：create 与 update 之外的写操作必须提供 taskId；update 必须提供 field（name/content/priority/score/duration/assignees/participants/checker）及对应字段；field=score 时可同时传 difficulty、estimatedHours、estimatedHoursUnit，不传会沿用任务当前值；overrule 使用 reason；addAttachment 使用 url 或 attachmentUrls。创建参数与 REST 创建请求一致。

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