Initial TrueGrowth source import

This commit is contained in:
2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions

View File

@@ -0,0 +1,153 @@
## 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.

View File

@@ -0,0 +1,31 @@
# Change: Add Visual Business Orchestration
## Why
The current TrueGrowth workflow concept is not usable as a real business automation surface. Users need a visual editor where they can compose image generation, video generation, digital-human production, intelligent editing, publishing, and intelligence/news summarization into repeatable automated flows.
This also needs a scheduling layer: operators should be able to run workflows such as "every day at 09:00, summarize news, generate a digital-human video, edit it, and publish it to Douyin" with execution records, logs, progress, retries, and crash recovery.
## What Changes
- Rebuild the existing `/workflow` "流程编排" workbench module as a React Flow based visual DAG editor instead of adding a second workflow entry.
- Add draggable node types for intelligence/news input, AI image, AI video, digital human, intelligent editing, asset/material operations, publish center, conditions, transforms, webhooks/manual approval, and utility steps.
- Add a node configuration inspector with detailed provider, model, prompt, media, schedule, retry, timeout, concurrency, and output mapping settings.
- Add a lightweight TrueGrowth DAG execution engine instead of embedding a full third-party automation platform.
- Add workflow validation for cycles, missing inputs, incompatible media, unsupported publish targets, and schedule conflicts.
- Add a scheduled task center for cron-style recurring runs, one-off schedules, manual triggers, enable/disable controls, next-run preview, execution history, logs, and per-node progress.
- Connect execution to existing TrueGrowth providers, local runtime tasks, FunClip/FFmpeg/ASR sidecar, and social publishing adapters.
- Add persistence and recovery contracts so workflow definitions, schedules, runs, node events, logs, and artifacts survive refreshes and local runtime restarts.
- Add targeted unit, integration, and browser tests to prove the editor, validation, scheduling, and run tracking work end to end.
## Impact
- Affected specs: business-orchestration
- Affected code:
- `apps/web/src/workbench/WorkbenchShell.tsx`
- `apps/web/src/workbench/app-definitions.tsx`
- `apps/web/src/workbench/workbench.scss`
- `apps/web/src/workbench/truegrowth.types.ts`
- `apps/web/src/workbench/local-runtime-client.ts`
- new workbench orchestration components under `apps/web/src/workbench/`
- existing `/workflow` route implementation and `WORKFLOW_PRESETS` migration path
- local runtime orchestration endpoints under `scripts/truegrowth-local-api.mjs` or a split runtime module
- Electron runtime isolation under `apps/electron/` when packaging requires heavy sidecar isolation
- existing task, asset, provider, FunClip, ComfyUI/AIGCPanel, Agent-Reach, and social publishing bridge code

View File

@@ -0,0 +1,173 @@
## ADDED Requirements
### Requirement: Visual Orchestration Workbench
The system SHALL provide a first-class workbench module for visual business workflow orchestration on the existing `/workflow` entry.
#### Scenario: User opens orchestration from navigation
- **GIVEN** the user is in the TrueGrowth workbench
- **WHEN** the user opens the "流程编排" navigation item
- **THEN** the workbench navigates to `/workflow`
- **AND** shows the visual orchestration editor
- **AND** the page follows the TrueGrowth desktop visual system.
#### Scenario: User opens orchestration from App Center
- **GIVEN** the user is viewing the App Center
- **WHEN** the user opens the "流程编排" app card
- **THEN** the workbench navigates to the same orchestration module.
#### Scenario: Legacy workflow page is replaced
- **GIVEN** the current `/workflow` route uses a simple stage-list workflow page
- **WHEN** this change is implemented
- **THEN** the route is rebuilt as a visual DAG editor
- **AND** any useful old presets are available as graph templates rather than static linear cards.
### Requirement: Drag-and-Drop DAG Editor
The system SHALL let users build directed acyclic workflows by dragging nodes onto a canvas and connecting them with edges.
#### Scenario: User creates a workflow graph
- **GIVEN** the orchestration editor is open
- **WHEN** the user drags supported nodes onto the canvas and connects compatible ports
- **THEN** the editor creates a workflow graph with persisted node positions, node configuration, and edges
- **AND** the graph can be saved and reopened without losing layout or configuration.
#### Scenario: User connects incompatible nodes
- **GIVEN** a source node output is incompatible with a target node input
- **WHEN** the user connects the nodes or validates the workflow
- **THEN** the editor reports the incompatibility
- **AND** the workflow cannot be executed until the issue is resolved or explicitly skipped by a supported rule.
#### Scenario: User creates a cycle
- **GIVEN** a workflow graph already contains a dependency path
- **WHEN** the user adds an edge that creates a cycle
- **THEN** the editor rejects the edge or marks the workflow invalid
- **AND** explains which nodes are involved in the cycle.
### Requirement: Business Node Catalog
The system SHALL provide configurable nodes for TrueGrowth creation, editing, intelligence, and publishing capabilities.
#### Scenario: User configures creation and publishing nodes
- **GIVEN** the user adds image generation, video generation, digital-human, intelligent editing, and publish-center nodes
- **WHEN** the user selects each node
- **THEN** the inspector shows detailed settings for provider, model, prompt, media inputs, output mapping, timeout, retry, and capability-specific options.
#### Scenario: User configures an intelligence/news node
- **GIVEN** the user adds an intelligence or news summary node
- **WHEN** the user configures topic, source range, language, output format, and model
- **THEN** the node can produce structured summaries, scripts, prompts, or downstream variables for later nodes.
#### Scenario: User configures intelligent editing
- **GIVEN** the user adds an intelligent editing node
- **WHEN** the user selects ASR, FunClip, FFmpeg, subtitle, clip, merge, or format options
- **THEN** the node records a normalized edit configuration
- **AND** the runtime executes it through the appropriate local sidecar or provider adapter.
### Requirement: Workflow Validation
The system SHALL validate workflows before execution.
#### Scenario: Workflow has missing required configuration
- **GIVEN** a workflow contains a node with required fields missing
- **WHEN** the user validates or runs the workflow
- **THEN** the system reports the missing fields on the node and in the validation summary
- **AND** the run is not started.
#### Scenario: Publish target is unsupported
- **GIVEN** a publish node targets a platform account that does not support the selected media type or schedule option
- **WHEN** the workflow is validated
- **THEN** the system marks the publish node invalid
- **AND** shows the unsupported capability before execution.
### Requirement: DAG Runtime Execution
The system SHALL execute valid workflow graphs according to node dependencies and configured concurrency limits.
#### Scenario: Runtime executes dependent nodes
- **GIVEN** a valid workflow has upstream and downstream dependencies
- **WHEN** the user starts a run
- **THEN** the runtime executes nodes only after their dependencies have succeeded or produced required outputs
- **AND** records each node status, progress, logs, outputs, and artifacts.
#### Scenario: Runtime executes parallel branches
- **GIVEN** a valid workflow has independent branches
- **WHEN** the workflow run starts
- **THEN** the runtime may execute branches in parallel according to configured global, provider, and platform concurrency limits.
#### Scenario: Runtime handles node failure
- **GIVEN** a node fails during execution
- **WHEN** retry policy allows another attempt
- **THEN** the runtime retries the node according to policy
- **AND** records every attempt in the run history.
#### Scenario: Runtime cancels a run
- **GIVEN** a workflow run is queued, running, or waiting
- **WHEN** the user cancels the run
- **THEN** the runtime stops scheduling new nodes where possible
- **AND** marks pending or active nodes as cancelled with a clear final run state.
### Requirement: Progress Feedback
The system SHALL provide live progress feedback for workflow runs and node executions.
#### Scenario: User watches a running workflow
- **GIVEN** a workflow run is active
- **WHEN** a node changes state, emits progress, writes a log, or produces an artifact
- **THEN** the canvas, run panel, and run details update with the latest status.
#### Scenario: User opens a historical run
- **GIVEN** a previous run exists
- **WHEN** the user opens its details
- **THEN** the system shows trigger source, start/end time, duration, final status, node timeline, logs, errors, and generated artifacts.
### Requirement: Scheduled Task Center
The system SHALL provide a scheduled task center for recurring and one-off workflow automation.
#### Scenario: User schedules a daily automation
- **GIVEN** the user has a saved workflow that summarizes news, generates a digital-human video, edits it, and publishes it
- **WHEN** the user creates a schedule for every day at 09:00 in a selected timezone
- **THEN** the system stores the schedule
- **AND** shows the next run time and enabled status.
#### Scenario: Scheduler fires a workflow
- **GIVEN** an enabled schedule reaches its next run time
- **WHEN** the local scheduler fires
- **THEN** the system creates an immutable workflow run with trigger metadata
- **AND** execution appears in the scheduled task center history.
#### Scenario: User disables a schedule
- **GIVEN** a schedule is enabled
- **WHEN** the user disables it
- **THEN** no future runs are created for that schedule until it is enabled again
- **AND** existing historical runs remain visible.
#### Scenario: Scheduled run overlaps existing run
- **GIVEN** a schedule fires while a previous run for the same schedule is still active
- **WHEN** the schedule has an overlap policy
- **THEN** the runtime follows the policy to skip, queue, or allow the new run
- **AND** records the decision in schedule history.
### Requirement: Durable Persistence and Recovery
The system SHALL persist workflow definitions, schedules, runs, node events, logs, and artifacts so work can recover after refresh or runtime restart.
#### Scenario: User refreshes during an active run
- **GIVEN** a workflow run is active
- **WHEN** the workbench refreshes
- **THEN** the UI reloads the latest run state from the local runtime
- **AND** resumes progress updates where supported.
#### Scenario: Local runtime restarts
- **GIVEN** the local runtime restarts after previous runs or schedules existed
- **WHEN** orchestration storage is loaded
- **THEN** saved workflow definitions, schedules, completed runs, and recoverable active runs are restored
- **AND** unrecoverable active nodes are marked with a clear recovery status.
### Requirement: Adapter Isolation
The system SHALL execute provider, sidecar, and publishing work through normalized adapters.
#### Scenario: Adapter emits normalized events
- **GIVEN** a node calls image generation, video generation, digital-human, intelligent editing, intelligence, or publishing
- **WHEN** the underlying provider emits progress, logs, artifacts, success, or failure
- **THEN** the adapter converts the result into orchestration events
- **AND** no provider-specific secret values are exposed to the frontend.
#### Scenario: Heavy sidecar crashes
- **GIVEN** a heavy sidecar runs in an isolated desktop process
- **WHEN** the sidecar crashes or exits unexpectedly
- **THEN** the runtime records the node failure
- **AND** the workbench shows a recoverable error without crashing the renderer.

View File

@@ -0,0 +1,57 @@
## 1. Discovery and Dependencies
- [x] 1.1 Confirm React Flow package choice (`@xyflow/react`) and add it to the workspace dependencies.
- [x] 1.2 Confirm XState, p-queue, Croner, and SQLite package choices with runtime compatibility.
- [x] 1.3 Define shared orchestration TypeScript contracts for workflows, nodes, edges, schedules, runs, events, and artifacts.
- [x] 1.4 Decide whether initial persistence uses the current local runtime JSON store or SQLite immediately behind the repository interface. (Business orchestration now uses SQLite as primary storage when the local `sqlite3` CLI is available, with JSON shadow fallback.)
## 2. Workbench Entry
- [x] 2.1 Reuse the existing `/workflow` route, sidebar item, and App Center card instead of adding a second workflow entry.
- [x] 2.2 Audit the current `WorkflowPage`, `WORKFLOW_PRESETS`, and `/local-api/workflows/run` behavior.
- [x] 2.3 Convert useful old presets into graph templates.
- [x] 2.4 Ensure search and navigation route users into the rebuilt module.
## 3. Visual Editor
- [x] 3.1 Create the main `BusinessOrchestrationPage` component.
- [x] 3.2 Add the React Flow canvas with custom TrueGrowth node styling.
- [x] 3.3 Add the node palette with supported node groups.
- [x] 3.4 Support drag-to-create nodes, edge creation, node movement, delete, duplicate, zoom, minimap, and fit view.
- [x] 3.5 Add the right inspector for detailed node configuration.
- [x] 3.6 Add workflow-level settings for name, description, variables, concurrency, retry defaults, and failure behavior.
- [x] 3.7 Add validation UI for cycles, missing required config, incompatible input/output contracts, and unsupported target capabilities.
## 4. Runtime DAG Engine
- [x] 4.1 Implement graph validation and topological dependency planning.
- [x] 4.2 Implement workflow and node lifecycle state transitions.
- [x] 4.3 Add p-queue based global, provider, and platform concurrency limits.
- [x] 4.4 Add cancellation, retry, timeout, skip, and partial-failure behavior.
- [x] 4.5 Persist workflow run state and node events before and after transitions.
- [x] 4.6 Expose local runtime endpoints for create/update workflow, validate, run, cancel, retry node, list runs, and stream events.
## 5. Real Node Adapters
- [x] 5.1 Add an intelligence/news node adapter that outputs structured summaries and scripts.
- [x] 5.2 Add an AI image node adapter using existing image/provider routes.
- [x] 5.3 Add an AI video node adapter using existing video/provider routes.
- [x] 5.4 Add a digital-human node adapter that outputs publishable video assets.
- [x] 5.5 Add an intelligent editing node adapter using FunClip, FFmpeg, ASR, and subtitle bridge capabilities.
- [x] 5.6 Add a publish-center node adapter that creates and tracks social publishing campaigns.
- [x] 5.7 Normalize adapter progress, logs, output artifacts, and errors into orchestration events.
## 6. Scheduled Task Center
- [x] 6.1 Add a scheduler tab/page inside the orchestration module.
- [x] 6.2 Add cron expression, preset, timezone, start/end, overlap, and misfire controls.
- [x] 6.3 Show next-run previews and validation messages.
- [x] 6.4 Implement Croner-backed local scheduler registration and restore on runtime start.
- [x] 6.5 Create immutable workflow runs for scheduled fires.
- [x] 6.6 Add execution history, logs, artifacts, retry, cancel, enable/disable, and run-now actions.
## 7. Desktop Runtime Isolation
- [x] 7.1 Keep orchestration APIs stable between browser dev and Electron packaged mode.
- [x] 7.2 Move heavy FunClip/FFmpeg/ASR/browser publishing execution into Electron UtilityProcess where packaging requires it.
- [x] 7.3 Add crash detection and recovery events for isolated sidecars.
## 8. Verification
- [ ] 8.1 Validate the OpenSpec change with `openspec validate add-visual-business-orchestration --strict` when the CLI is available. (`pnpm exec openspec validate add-visual-business-orchestration --strict` is currently blocked because the `openspec` command is not installed in this workspace.)
- [x] 8.2 Add unit tests for graph validation, topological ordering, cycle rejection, config validation, and scheduler next-run calculation.
- [x] 8.3 Add runtime integration tests for a deterministic DAG with parallel branches, retries, cancellation, and recovery.
- [x] 8.4 Add workbench tests for drag/drop creation, inspector editing, validation messages, save/load, run progress, and schedule creation. (Initial render, node add, schedule controls, schedule visibility, schedule request persistence, and run progress tests are in place.)
- [x] 8.5 Add an end-to-end smoke test for a sample flow: news summary -> digital-human video -> intelligent edit -> publish draft. (Automated local API verifier covers validation, dependency order, execution, utility isolation, and social publishing draft/campaign artifact output.)