ai-contract-platform/project-docs/V2-ai-runtime-manual-worker-run-2026-06-23.md

AI Platform V2 手动执行 Worker 闭环记录

时间：2026-06-23

本轮目标

延续《AI 合同平台 V2 重构版开发方案》，在 AI Runtime 管理后台增加“手动执行一次 worker”能力，并把执行结果写回运行时间线/审计，形成从问题发现到配置执行的可操作闭环。

已完成

1. 数据模型

• 新增 worker_run_executions 运行记录。
• 字段覆盖：
  • worker_name
  • trigger_type
  • triggered_by
  • queue_name
  • status
  • limit
  • processed/succeeded/failed
  • error_message
  • duration_ms
  • started_at/completed_at

2. API 契约

• GET /api/v1/runtime/worker-runs
  • 查看最近 worker 执行时间线。
• POST /api/v1/runtime/worker-runs/run-once
  • 手动执行一次 worker。
  • 请求参数支持 limit、worker_name、triggered_by。
  • 执行完成后返回本次执行记录。
• OpenAPI 已同步 WorkerRunOnceRequest 和 WorkerRunExecution schema。

3. Worker 复用

• 抽出 run_knowledge_worker_once 公共逻辑。
• CLI worker 和 API 手动执行共用同一套真实处理链路：
  • queued job 获取
  • 对象存储读取
  • 文档解析/OCR
  • 知识库导入批次、文档、chunk 写入
  • worker 心跳
  • 手动执行记录

4. 管理后台

• /admin/ai-runtime 增加：
  • Run worker once 按钮
  • 执行中的禁用态
  • 成功/失败反馈
  • Run timeline 列表
• 执行记录展示：
  • 状态
  • 触发方式
  • 触发人
  • processed/succeeded/failed
  • 耗时
  • 错误信息

5. SDK

• Python SDK 增加：
  • get_worker_runtime_health
  • list_worker_run_executions
  • run_worker_once
• 类型增加：
  • WorkerHeartbeat
  • WorkerRuntimeHealth
  • WorkerRunOnceRequest
  • WorkerRunExecution

验证命令

python -m pytest yuqei-ai-platform\services\ai-platform-api\tests\test_platform_data.py -q
python -m pytest yuqei-ai-platform\services\worker\tests -q
python -m pytest yuqei-ai-sdk-python\tests\test_ai_platform.py -q
python -c "import yaml, pathlib; yaml.safe_load(pathlib.Path('yuqei-ai-platform/packages/ai-openapi/openapi.yaml').read_text(encoding='utf-8')); print('openapi ok')"
npm --prefix yuqei-contract-platform/apps/contract-web run build
python -m compileall -q yuqei-ai-platform\services\ai-platform-api\src yuqei-ai-platform\services\worker\src yuqei-ai-sdk-python\src
git diff --check

下一步建议

1. 给 worker 死亡、长时间无心跳、失败率异常增加后台告警策略。
2. 把 OCR provider、对象存储、worker 执行这类 runtime 配置变更纳入统一 AI 审计 Trace。
3. 给 Docker Compose 增加一键 smoke test：健康检查、对象存储探针、上传样例知识文件、手动执行 worker、校验 timeline。