154 lines
11 KiB
Markdown
154 lines
11 KiB
Markdown
## Context
|
|
TrueGrowth already has the pieces needed for business automation: a React/Nx workbench shell, a local runtime API, task records, assets, provider routing, ComfyUI/AIGCPanel image and video generation bridges, FunClip/FFmpeg sidecar readiness, Agent-Reach intelligence work, and a native social publishing workspace.
|
|
|
|
The missing product layer is a native visual business orchestration system that lets users connect these capabilities without leaving TrueGrowth. The editor should feel like a professional desktop workbench, not a generic open-source automation console embedded into the app.
|
|
|
|
## Goals
|
|
- Provide a visual drag-and-connect DAG editor for business workflows.
|
|
- Replace the current simple stage-list workflow page behind `/workflow` with the new editor while preserving the existing navigation and App Center entry.
|
|
- Support configurable nodes for news/intelligence, image, video, digital human, intelligent editing, publishing, transforms, conditions, and approvals.
|
|
- Execute workflows with deterministic dependency ordering, per-node state, progress, retries, cancellation, and resumable run records.
|
|
- Provide a scheduled task center for recurring and one-off automation.
|
|
- Reuse TrueGrowth's existing providers, local tasks, assets, publish adapters, and runtime bridges.
|
|
- Keep the architecture small enough to own inside TrueGrowth while allowing future provider adapters.
|
|
|
|
## Non-Goals
|
|
- Do not embed n8n, Node-RED, Activepieces, or a foreign automation UI as the main product surface.
|
|
- Do not replace the existing AI image, AI video, digital-human, intelligent editing, intelligence, task center, or publish center pages.
|
|
- Do not store raw social account cookies or provider secrets in frontend workflow definitions.
|
|
- Do not require cloud services for the first release.
|
|
|
|
## Open-Source Capability Assessment
|
|
- React Flow is the best fit for the editor canvas: node/edge rendering, drag interactions, custom nodes, minimap, controls, and fit-view behavior match the required visual DAG editing surface.
|
|
- XState is useful for node/run lifecycle modeling, but it should stay at the workflow runtime state-boundary rather than driving the entire React page.
|
|
- p-queue is a good fit for bounded local concurrency, per-provider queues, and platform rate limiting.
|
|
- Croner is a good fit for cron expressions, next-run calculations, timezone handling, and local scheduled triggers.
|
|
- SQLite is the right durable store for desktop/local runtime persistence, but implementation can start behind a repository interface so development may use the current JSON/local runtime store until the SQLite dependency is wired.
|
|
- Electron UtilityProcess is appropriate for heavy or fragile sidecars such as FFmpeg/FunClip/ASR/browser publishing once the Electron shell is packaging these flows. Browser/PWA development should keep using the local runtime API boundary.
|
|
- Full automation platforms such as n8n, Node-RED, Windmill, Temporal, or Activepieces are better as references or optional future executors than as the first embedded runtime. Their UI, credential model, plugin model, and deployment assumptions do not match TrueGrowth's asset/provider/publish-center workflow closely enough.
|
|
|
|
## Recommended Architecture
|
|
### Frontend Editor
|
|
- Reuse the existing `/workflow` route and `流程编排` navigation/App Center entry.
|
|
- Use React Flow for the main canvas.
|
|
- Keep a wide left node palette, central canvas, right inspector, bottom run/log drawer, and top toolbar for save, validate, run, schedule, duplicate, export, and history.
|
|
- Store editor documents as `WorkflowDefinition` records with nodes, edges, viewport, metadata, version, and validation status.
|
|
- Keep UI aligned with the TrueGrowth Aurora-style direction: left navigation, compact bordered white cards, 40-42px controls, orange primary actions, short Chinese labels, and no raw technical/demo copy.
|
|
|
|
### Existing Workflow Migration
|
|
- Treat the current `WorkflowPage` and `WORKFLOW_PRESETS` stage-list model as the legacy implementation.
|
|
- Preserve the visible `/workflow` route, left navigation item, and App Center card.
|
|
- Convert any useful preset examples into real graph templates with nodes and edges.
|
|
- Remove or hide the old linear-stage UI once the React Flow editor can create, save, validate, run, and schedule workflows.
|
|
- Keep existing local runtime `/local-api/workflows/run` compatibility as one adapter path, not as the whole orchestration model.
|
|
|
|
### Node Model
|
|
Each node definition should include:
|
|
- `id`, `type`, `label`, `position`
|
|
- `inputs`, `outputs`, and media/data contracts
|
|
- `configSchema` and `config`
|
|
- `providerRef` when the node calls a model/runtime/provider
|
|
- `retry`, `timeoutMs`, `concurrencyKey`, and `resourceHints`
|
|
- `secretsRef` for runtime-owned credentials
|
|
- `ui` metadata for icon, accent, collapsed summary, and inspector sections
|
|
|
|
Initial node groups:
|
|
- 输入: manual input, scheduled trigger, news/intelligence query, asset picker, webhook/API placeholder
|
|
- 生成: AI image, AI video, digital-human video, voice/TTS
|
|
- 处理: intelligent edit, ASR, subtitle, FFmpeg transform, format conversion, merge/split
|
|
- 决策: condition, switch, filter, approval gate
|
|
- 输出: save asset, publish campaign, notification/webhook placeholder
|
|
- 工具: prompt template, variable mapper, delay, script transform placeholder
|
|
|
|
### Runtime Engine
|
|
Implement a lightweight DAG engine in the local runtime:
|
|
- Validate acyclic graph and topologically sort runnable nodes.
|
|
- Track node states: idle, queued, running, waiting, succeeded, failed, skipped, cancelled.
|
|
- Track run states: draft, queued, running, waiting, succeeded, failed, partial, cancelled.
|
|
- Resolve inputs from upstream node outputs, run variables, selected assets, and schedule payloads.
|
|
- Dispatch node execution to provider adapters through existing local runtime endpoints where possible.
|
|
- Use p-queue for global concurrency, per-provider concurrency, and per-platform publishing limits.
|
|
- Emit structured events for run started, node queued, node progress, node log, node output, node failed, run completed, and run cancelled.
|
|
- Persist state before and after each node transition to support recovery.
|
|
|
|
### State Machines
|
|
Use XState for explicit runtime lifecycle state machines:
|
|
- Workflow run lifecycle: queued -> running -> waiting/succeeded/failed/partial/cancelled.
|
|
- Node lifecycle: idle -> queued -> running -> waiting -> succeeded/failed/skipped/cancelled.
|
|
- Schedule lifecycle: disabled -> armed -> firing -> backoff/armed.
|
|
|
|
XState should model lifecycle and recovery semantics; dependency resolution remains in the DAG engine.
|
|
|
|
### Scheduling
|
|
Use Croner for recurring and one-off schedules:
|
|
- Support cron expression, simple presets, timezone, start/end date, misfire policy, overlap policy, and max active runs.
|
|
- Show next run time preview in the UI.
|
|
- Store scheduled task definitions separately from workflow definitions so the same workflow can have multiple schedules.
|
|
- Each scheduled fire creates an immutable `WorkflowRun` with trigger metadata.
|
|
- Support manual "run now" for any active schedule.
|
|
|
|
### Persistence
|
|
Use a storage repository interface with these conceptual tables/collections:
|
|
- `workflow_definitions`
|
|
- `workflow_versions`
|
|
- `workflow_schedules`
|
|
- `workflow_runs`
|
|
- `workflow_node_runs`
|
|
- `workflow_run_events`
|
|
- `workflow_artifacts`
|
|
- `workflow_locks`
|
|
|
|
SQLite should become the desktop/local runtime durable implementation. During incremental development, the current local runtime JSON store may be used only behind the same repository API.
|
|
|
|
### Provider and Adapter Boundaries
|
|
- Image/video generation nodes call existing provider routing, ComfyUI, AIGCPanel, or canvas generation bridges.
|
|
- Digital-human nodes call the existing digital-human runtime path and produce video assets.
|
|
- Intelligent editing nodes call FunClip, FFmpeg, ASR, and subtitle tools through the sidecar bridge.
|
|
- Publish nodes create native social publishing campaigns and track per-target status through the existing publishing adapter.
|
|
- Intelligence/news nodes call Omni Intelligence/Agent-Reach style research tasks and output structured summaries/scripts.
|
|
- Every adapter must normalize progress, logs, artifacts, and errors into the orchestration event contract.
|
|
|
|
### Progress and Logs
|
|
- The editor run panel shows total progress, active node, queued count, failed count, and latest logs.
|
|
- Each node visually reflects status and progress on the canvas.
|
|
- The scheduled task center shows run history with trigger, status, duration, completed nodes, failed node, artifacts, and retry/open actions.
|
|
- Logs should be structured with timestamp, level, nodeId, adapter, message, and optional artifact references.
|
|
|
|
### Electron Isolation
|
|
- Keep orchestration control in the local runtime API.
|
|
- Use Electron UtilityProcess for heavy sidecars only when the desktop package is active.
|
|
- Isolate FFmpeg/FunClip/ASR/browser publishing from the renderer so crashes do not take down the workbench.
|
|
- Preserve the same endpoint/event contract in browser development and Electron packaged modes.
|
|
|
|
## Data Contracts
|
|
Key TypeScript concepts:
|
|
- `BusinessWorkflowDefinition`
|
|
- `BusinessWorkflowNode`
|
|
- `BusinessWorkflowEdge`
|
|
- `BusinessWorkflowSchedule`
|
|
- `BusinessWorkflowRun`
|
|
- `BusinessWorkflowNodeRun`
|
|
- `BusinessWorkflowEvent`
|
|
- `BusinessWorkflowArtifact`
|
|
- `BusinessWorkflowAdapter`
|
|
- `BusinessWorkflowValidationResult`
|
|
|
|
The frontend and local runtime should share serializable contracts. Runtime-only fields such as process handles, secret values, and adapter clients must not appear in frontend payloads.
|
|
|
|
## Migration Plan
|
|
1. Add OpenSpec and shared contracts.
|
|
2. Audit the existing `/workflow` implementation and convert the old stage presets into graph templates.
|
|
3. Replace the route body with the editor shell while preserving the current navigation and App Center entry.
|
|
4. Add React Flow node palette, drag/drop, edge creation, inspector editing, validation, and save/load.
|
|
5. Add the DAG engine with local mock adapters for deterministic tests.
|
|
6. Connect real adapters incrementally: intelligence/news, image, video, digital human, intelligent editing, publishing.
|
|
7. Add scheduled task center with Croner next-run preview and local runtime firing.
|
|
8. Add durable persistence and recovery, preferring SQLite in the desktop runtime.
|
|
9. Add Electron UtilityProcess isolation for heavy sidecars where needed.
|
|
|
|
## Risks
|
|
- Long-running media generation and social publishing may exceed normal request lifetimes. Mitigation: run everything as durable local tasks with polling/SSE event streams.
|
|
- Platform publishing can fail due to account health or anti-automation. Mitigation: validate capabilities, preserve logs, and support retry per target.
|
|
- Node schemas can sprawl. Mitigation: keep node groups small, shared config sections reusable, and provider-specific options hidden until a provider is selected.
|
|
- Scheduling while the app is closed depends on the local runtime/desktop process being alive. Mitigation: surface scheduler health and missed-run policy clearly.
|