Skip to Content
数字员工服务接入示例与排错

接入示例与排错

下面以独立封面应用已经采用的素材采集和 AI 打标为例。两者使用相同的员工任务 API，业务接口、数据表和审核流程由应用维护。

素材采集

  1. 应用创建本地采集记录，保存账号、采集范围、业务 runId 和本轮临时凭证。
  2. 应用后端提交通用任务，使用稳定的业务幂等键，保存 FunClaw 返回的任务 ID。
  3. 员工使用已安装的采集 Skill，向应用获取本轮 manifest，执行采集和图片交付。
  4. 图片和完整数据直接提交应用；平台任务结果保存回执摘要。
  5. 应用后台持续查询平台状态，校验结果和业务回执后完成本地采集记录。

当前采集任务的 input 结构示意：

{
  "collection": {
    "baseUrl": "https://your-app.example.com",
    "runId": "<本次业务采集 ID>",
    "token": "<本轮采集临时凭证>"
  }
}

配套 instructions 指定 $cover-materal-collector-new，要求读取输入信封、使用应用的采集入口、校验回执，并按结果文件约定交付摘要。baseUrl 需要从员工所在机器可达。

平台 output 中的 runId、received、collectionStatus、complete、stored、pending 是该应用约定的摘要字段，不是通用平台固定字段。应用应按自己的回执合同解析。

采集需要 TikHub 时，在平台员工的“执行能力”中授权。应用在“员工授权”中取得使用该员工的资格即可。

AI 打标

AI 打标复用相同链路，input 使用该应用约定的 tagging：

{
  "tagging": {
    "baseUrl": "https://your-app.example.com",
    "batchId": "<本次打标批次 ID>",
    "token": "<本轮打标临时凭证>"
  }
}

员工使用 $cover-material-tagging-new 获取本轮素材与标签维度，逐条分析并向应用回传结果。平台 output 保存 received、batchId、complete、successCount、noMatchCount、failureCount 等回执摘要。

应用同时检查平台终态、摘要和逐条回执，再完成批次。有效打标结果进入 REVIEW_REQUIRED，保留人工审核；是否匹配标签、是否通过审核，由应用业务流程决定。

自动调度与状态同步

自动检查间隔、每批数量、并发批次、手动重试和业务结算均属于应用。应用可以使用后台 worker 或已有调度机制持续运行这些逻辑；FunClaw 只执行已提交的员工任务。

应用应持久化业务记录、幂等键、平台任务 ID、最近同步时间和失败原因。Web 页面关闭、应用或 API 重启后，应能继续查询原任务。网络超时不应立即把业务任务判为永久失败。

如果使用业务回调，回执可能先于平台任务完成到达。应用应分别展示平台执行状态、业务回执进度和审核状态，按完成条件统一结算，避免一边显示“正在执行”而另一边已释放批次。

常见排查

现象优先检查
身份接口 401是否使用完整 fc_app_ Key，凭证是否过期/撤销，应用与 API 接入是否启用。
员工列表为空员工是否有效、使用授权是否过期，是否有 READ 或 TASK_CREATE。
提交 403员工使用授权是否有 TASK_CREATE；查询和结果还需要 READ。
任务一直 PENDING员工 Adapter 是否在线、是否支持应用任务，员工总体并发是否已满。
TikHub 未授权检查所选员工的平台执行能力，不给应用重复配置员工工具权限。
平台已执行，应用界面不变应用后台同步是否运行，是否保存了正确任务 ID，API 恢复后是否继续查询原任务。
图片/回执到了，任务未完成检查当前任务结果文件是否提交、回执是否完整，不用单条业务回执替代平台终态。
平台 COMPLETED，业务仍未结束检查 output 与本地回执匹配、业务结算和名额释放是否完成；待审核可能是正常业务状态。
结果接口 409尚未到 COMPLETED 或结果未就绪，先查询任务状态。
重试提交 409同一幂等键是否携带了不同内容；不要不断换键重复派发。
修改授权后旧任务 403旧任务绑定接受时的授权版本；重新授权不会恢复旧快照。

安全恢复

请求失败时保留原任务关联，退避重试查询。提交是否成功未知时，使用原幂等键和相同内容恢复；任务已明确失败且需要重新执行时，再创建新的业务尝试和幂等键。

“结果查询暂不可用”与“员工执行失败”分别处理。恢复或人工重试应记录原因；完成结算必须可重复执行，避免回执重放导致重复入库。

后续接入标题生成、生图或其他 Skill 时，继续复用这一套任务 API，为业务约定自己的 input、output 和回执即可。

Last updated on
输入与结果