automation api

[hotlong]

Automation API 最后一公里：HTTP Route CRUD + Client SDK 扩展 + 执行历史接入

衔接: #741（✅ 已完成 — 核心引擎 + 插件体系）
Parent: #753（Spec 优先 Roadmap 2026.02）
阻塞: ObjectUI Roadmap P1.6（Automation Builder）

---

📊 现状（#741 交付物确认）

以下 已完成 ✅，不在本 Issue 范围内：

已完成	文件	测试
IAutomationService contract	spec/src/contracts/automation-service.ts	3 tests
AutomationEngine (DAG 引擎)	services/service-automation/src/engine.ts	27 tests
AutomationServicePlugin (Kernel 插件)	services/service-automation/src/plugin.ts	✅
CrudNodesPlugin (get/create/update/delete_record)	plugins/crud-nodes-plugin.ts	✅
LogicNodesPlugin (decision/assignment/loop)	plugins/logic-nodes-plugin.ts	✅
HttpConnectorPlugin (http_request/connector_action)	plugins/http-connector-plugin.ts	✅
热插拔 (registerNodeExecutor/unregisterNodeExecutor)	engine.ts	✅
Execution 协议 Schema (Log/StepLog/Error/Checkpoint/ConcurrencyPolicy/ScheduleState)	automation/execution.zod.ts	✅

🎯 本 Issue 目标

打通 Automation Service → HTTP API → Client SDK 的完整链路。

---

Task 1: Automation API Protocol Schema ⏱️ 0.5d

在 packages/spec/src/api/ 新增 automation-api.zod.ts：

// 定义 REST CRUD 端点的 Request/Response schemas
export const AutomationApiContracts = {
  listFlows:     { method: 'GET',    path: '/api/automation' },
  getFlow:       { method: 'GET',    path: '/api/automation/:name' },
  createFlow:    { method: 'POST',   path: '/api/automation' },
  updateFlow:    { method: 'PUT',    path: '/api/automation/:name' },
  deleteFlow:    { method: 'DELETE', path: '/api/automation/:name' },
  triggerFlow:   { method: 'POST',   path: '/api/automation/:name/trigger' },  // 已有
  toggleFlow:    { method: 'POST',   path: '/api/automation/:name/toggle' },
  listRuns:      { method: 'GET',    path: '/api/automation/:name/runs' },
  getRun:        { method: 'GET',    path: '/api/automation/:name/runs/:runId' },
};

• 定义 ListFlowsRequest/Response
• 定义 GetFlowRequest/Response
• 定义 CreateFlowRequest/Response
• 定义 UpdateFlowRequest/Response
• 定义 DeleteFlowRequest/Response
• 定义 ToggleFlowRequest/Response（enable/disable）
• 定义 ListRunsRequest/Response（复用 ExecutionLogSchema）
• 定义 GetRunRequest/Response（复用 ExecutionLogSchema + ExecutionStepLogSchema）
• 编写 schema 测试

Task 2: IAutomationService Contract 扩展 ⏱️ 0.5d

扩展 contracts/automation-service.ts 中的 IAutomationService：

export interface IAutomationService {
  // 已有 ✅
  execute(flowName: string, context?: AutomationContext): Promise<AutomationResult>;
  listFlows(): Promise<string[]>;
  registerFlow?(name: string, definition: unknown): void;
  unregisterFlow?(name: string): void;

  // 新增 🆕
  getFlow?(name: string): Promise<FlowDefinition | null>;
  toggleFlow?(name: string, enabled: boolean): Promise<void>;
  listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<ExecutionLog[]>;
  getRun?(runId: string): Promise<ExecutionLog | null>;
}

• 新增 getFlow、toggleFlow、listRuns、getRun 可选方法
• 更新合约合规测试

Task 3: AutomationEngine 执行历史 ⏱️ 1d

在 AutomationEngine 中新增 executionLog 存储：

• 每次 execute() 完成后记录 ExecutionLog（runId、flowName、input、output、durationMs、status、steps）
• 实现 getFlow(name) — 返回 flow 定义
• 实现 toggleFlow(name, enabled) — enable/disable 标记
• 实现 listRuns(flowName) — 返回执行历史
• 实现 getRun(runId) — 返回单次执行详情
• 编写测试

Task 4: HTTP Route Handler 扩展 ⏱️ 1d

在 runtime/src/http-dispatcher.ts 的 handleAutomation() 和 createDispatcherPlugin() 中新增 CRUD 路由：

当前（仅 1 个路由）：

// POST /automation/trigger/:name  ← 已有

目标（9 个路由）：

GET    /automation              → listFlows
GET    /automation/:name        → getFlow
POST   /automation              → createFlow (registerFlow)
PUT    /automation/:name        → updateFlow
DELETE /automation/:name        → deleteFlow (unregisterFlow)
POST   /automation/:name/trigger → execute (已有)
POST   /automation/:name/toggle  → toggleFlow
GET    /automation/:name/runs   → listRuns
GET    /automation/:name/runs/:runId → getRun

• 在 handleAutomation() 中新增 8 个路由分支
• 在 createDispatcherPlugin() 中注册对应的 server 路由
• 编写测试

Task 5: Client SDK automation namespace 扩展 ⏱️ 1d

扩展 packages/client/src/index.ts 中的 client.automation：

当前（仅 1 个方法）：

automation = {
  trigger: async (name, data) => { ... }
}

目标：

automation = {
  // 已有
  trigger: async (name, data) => { ... },
  // 新增
  list: async () => { ... },
  get: async (name) => { ... },
  create: async (name, definition) => { ... },
  update: async (name, definition) => { ... },
  delete: async (name) => { ... },
  toggle: async (name, enabled) => { ... },
  runs: {
    list: async (flowName, options?) => { ... },
    get: async (flowName, runId) => { ... },
  },
}

• 在 getRoute() 中已有 'automation' 路由，确认路径正确
• 新增 list(), get(), create(), update(), delete(), toggle()
• 新增 runs.list(), runs.get()
• 编写 MSW 集成测试

Task 6: 测试 + Roadmap 更新 ⏱️ 0.5d

• 运行 pnpm test，确保全部测试通过
• 更新 ROADMAP.md 中 Automation 相关 checklist
• 更新 Contract Implementation Matrix 中 service-automation 的 completeness
• 更新 Package Status Matrix 中 service-automation 的 test count

---

📐 工作量估算

Task	估时
Task 1: API Protocol Schema	0.5d
Task 2: Contract 扩展	0.5d
Task 3: Engine 执行历史	1d
Task 4: HTTP Route CRUD	1d
Task 5: Client SDK	1d
Task 6: 测试 + Roadmap	0.5d
总计	4.5d

🔗 关联

• 衔接: 实现自动化引擎插件化架构，支持能力无限扩展 #741（核心引擎已完成，本 Issue 接力 API 层）
• Parent: 更新 Spec 项目的优先 Roadmap（2026.02） #753（Spec 优先 Roadmap）
• 阻塞 ObjectUI: P1.6 Automation Builder（需要 client.automation.list/create/update 才能渲染 AutomationBuilder UI）
• 参考协议: automation/execution.zod.ts 已定义完整的 ExecutionLog/StepLog/Checkpoint schema

备注：开发任务完成后需运行 test，并及时更新 roadmap。

[hotlong]

评估当前任务的完成情况