一刻工坊｜技术白皮书 V2.0

文档密级：内部公开 最后更新：2025-12-22 依据：Based on /docs/_source_of_truth/tech_facts.md

1. 架构总览

系统采用前后端分离 + 异构微服务架构。Node.js 负责业务编排与数据管理，Python (LangGraph) 负责复杂 Agent 逻辑，通过适配层调度第三方 AI 能力。

mermaid

graph TD
    subgraph clientLayer [客户端层]
        Web[Web Browser]
        Electron[Electron Client]
        Mini[Mini Program]
    end

    subgraph gatewayLayer [网关/API层]
        LB[Load Balancer]
        API[Node.js Express API]
        Auth[Auth Middleware]
    end

    subgraph businessLayer [业务逻辑层]
        Orch[Workflow Orchestrator]
        AssetMgr[Asset Manager]
        TaskMgr[Task Manager]
        KBMgr[Knowledge Base Manager]
    end

    subgraph agentLayer [智能体层 Python]
        LangGraph[LangGraph Runner]
        StrategyAgent[Strategy Agent]
        MusicAgent[Music/Video Agent]
        RAG[RAG Engine]
    end

    subgraph adapterLayer [引擎适配层]
        SunoAdapt[Suno Adapter]
        FishAdapt[Fish Audio Adapter]
        ComfyAdapt[ComfyUI Adapter]
        FlowiseAdapt[Flowise/N8N Adapter]
        LocalAdapt[Local App Adapter]
    end

    subgraph infraLayer [基础设施]
        DB[(PostgreSQL)]
        Cache[(Redis)]
        OSS[Object Storage]
        MQ[Message Queue]
    end

    clientLayer -->|HTTPS/WSS| LB
    LB --> API
    API --> Orch & AssetMgr & TaskMgr & KBMgr
    Orch -->|HTTP/RPC| LangGraph
    Orch -->|API| FlowiseAdapt
    LangGraph --> StrategyAgent & MusicAgent
    MusicAgent --> SunoAdapt & ComfyAdapt
    TaskMgr --> DB
    AssetMgr --> OSS
    StrategyAgent --> RAG
    RAG --> KBMgr

📋 落地检查项

[ ] 前后端 API 接口契约是否由 Swagger/OpenAPI 定义？
[ ] Python Agent 服务与 Node.js 服务的通信协议（HTTP/gRPC）是否确立？
[ ] Redis 是否已配置用于 Session 存储和任务队列？

2. 关键数据流

以"用户创建任务 -> 多模态生成 -> 发布"为例的端到端数据流。

mermaid

sequenceDiagram
    participant User as 用户
    participant API as Backend API
    participant DB as Database
    participant Agent as LangGraph Agent
    participant Engine as External Engine
    participant OSS as Object Storage

    User->>API: POST /api/project/dispatch-task
    API->>DB: 创建 Task PENDING
    API-->>User: 返回 TaskID

    loop 轮询/WebSocket
        User->>API: 查询进度
    end

    API->>Agent: 异步调度任务
    activate Agent
    Agent->>API: 更新 Task RUNNING
    
    note right of Agent: 执行策划/提示词工程

    Agent->>Engine: 调用生成 API
    activate Engine
    Engine-->>Agent: 返回生成结果
    deactivate Engine

    Agent->>OSS: 上传原始素材
    OSS-->>Agent: 返回 OSS URL

    Agent->>DB: 写入 UnifiedAsset 记录
    Agent->>API: 更新 Task SUCCESS
    deactivate Agent

    User->>API: 获取任务结果
    API-->>User: 返回 UnifiedAsset 详情

📋 落地检查项

[ ] 异步任务是否有超时熔断机制？
[ ] 大文件（视频）上传是否采用了分片上传或预签名 URL 方案？
[ ] WebSocket 推送服务是否具备重连机制？

3. 核心对象模型

基于 backend/src/models/ 的核心实体定义。

对象 (Class)	核心字段	关系	描述
Project	`id`, `name`, `workflow_preset_id`, `status`	1:N Tasks	业务顶层容器，定义了一组任务的上下文。
Task	`id`, `project_id`, `type`, `status`, `input_params`, `output_data`	N:1 Project 1:N Assets	最小执行单元。状态流转的核心载体。
UnifiedAsset	`id`, `file_path`, `file_type`, `meta`, `source_task_id`	N:1 Task	系统产生或用户上传的物理文件（视频/图片/音频）。
UserCorpus	`id`, `content`, `source_url`, `tags`	N:N Assets	灵感笔记。用于 RAG 检索或作为生成参考。
Job (内部)	`id`, `task_id`, `external_job_id`, `retry_count`	N:1 Task	技术层面的执行记录，用于追踪外部 API 调用状态。
ContentTemplate	`id`, `structure_json`, `engine_config`	1:N Projects	定义生成逻辑的模板（如：Prompt 结构、引擎参数）。
KnowledgeDocument	`id`, `filename`, `status`, `chunk_count`	1:N Chunks	知识库文档主表。
KnowledgeChunk	`id`, `document_id`, `content`, `embedding`	N:1 Document	文档切片，用于向量检索。

📋 落地检查项

[ ] 数据库索引是否在 project_id, status, created_at 等高频查询字段上建立？
[ ] input_params 和 output_data 建议使用 JSONB 类型以适应多变的业务需求。
[ ] 软删除（Soft Delete）策略是否已在所有核心表中实现？

4. 任务状态机与可靠性

任务 (Task) 必须遵循严格的状态流转，以确保系统的一致性。

4.1 状态定义

PENDING: 已创建，等待调度。
QUEUED: 已进入消息队列/Agent 队列。
RUNNING: 正在执行（包括等待外部 API 响应）。
SUCCESS: 执行成功，产物已入库。
FAILED: 执行失败（重试耗尽）。
CANCELLED: 用户主动取消。

4.2 转换规则

mermaid

stateDiagram-v2
    [*] --> PENDING
    PENDING --> QUEUED: 调度器拾取
    QUEUED --> RUNNING: Agent开始执行
    RUNNING --> SUCCESS: 产物生成完成
    RUNNING --> FAILED: 报错且无重试次数
    RUNNING --> QUEUED: 报错但有重试次数
    PENDING --> CANCELLED: 用户取消
    QUEUED --> CANCELLED: 用户取消
    RUNNING --> CANCELLED: 用户取消

4.3 重试与幂等

重试策略：
- 网络错误/超时：指数退避 (Exponential Backoff)，最大重试 3 次。
- 业务错误（如违规）：不重试，直接 FAILED。
幂等策略：
- Request ID：客户端生成 UUID，服务端缓存 24h，重复请求直接返回上次结果。
- 锁机制：同一 Task 在 RUNNING 状态下拒绝重复调度。

📋 落地检查项

[ ] 状态机代码是否集中管理，禁止随意在业务逻辑中修改状态？
[ ] 失败重试是否记录了详细的 Error Log 和 Reason？
[ ] 幂等键的存储（Redis）是否设置了过期时间？

5. 外部引擎适配层

为了解耦具体供应商（如 Suno 可能换成 Udio），需在 backend/src/services 中建立统一抽象层。

5.1 统一接口定义 (Interface)

typescript

interface IGenerativeEngine {
    // 提交生成任务
    generate(params: GenerationParams): Promise<string>; // 返回 External Job ID
    
    // 查询任务状态
    checkStatus(jobId: string): Promise<GenerationResult>;
    
    // (可选) Webhook 回调处理
    handleCallback(payload: any): Promise<void>;
}

5.2 适配器实现 (Adapters)

SunoAdapter: 处理 Cookie 保活、Credit 计算、音频 URL 提取。
ComfyUIAdapter: 处理 WebSocket 连接、节点图 (Workflow JSON) 注入、图片 Base64 解码。
LocalAppAdapter (Jianying):
- 特殊性：非 HTTP 调用，需通过文件系统操作。
- 机制：生成 draft_content.json -> 写入指定目录 -> 唤起剪映主程序。

📋 落地检查项

[ ] 是否所有外部调用都经过了 Adapter，禁止业务代码直接 fetch 第三方 API？
[ ] Adapter 是否包含统一的错误映射（将第三方错误码转为系统内部错误码）？
[ ] 本地适配器是否处理了路径分隔符的跨平台兼容性？

6. API 端点参考

6.1 认证相关

方法	端点	描述	请求体	响应
POST	`/api/auth/register`	用户注册	`{ email, password, username }`	`{ token, user }`
POST	`/api/auth/login`	用户登录	`{ email, password }`	`{ token, user }`
POST	`/api/auth/refresh`	刷新 Token	`{ refreshToken }`	`{ token }`
GET	`/api/auth/me`	获取当前用户	-	`{ user }`

6.2 灵感广场

方法	端点	描述	请求体/参数	响应
POST	`/api/inspiration/parse-link`	解析外部链接	`{ url }`	`{ corpus, assets }`
GET	`/api/corpus`	获取灵感笔记列表	`?page=1&limit=20&tag=美食`	`{ data, total }`
GET	`/api/corpus/:id`	获取单条灵感详情	-	`{ corpus, relatedAssets }`
DELETE	`/api/corpus/:id`	删除灵感笔记（软删除）	-	`{ success }`
POST	`/api/materials/upload`	上传本地素材	FormData	`{ asset }`
GET	`/api/materials`	获取媒体素材列表	`?type=video&tag=风景`	`{ data, total }`
POST	`/api/materials/batch-delete`	批量删除素材	`{ ids: [] }`	`{ deletedCount }`

6.3 项目管理

方法	端点	描述	请求体/参数	响应
GET	`/api/projects`	获取项目列表	`?status=active`	`{ data, total }`
POST	`/api/projects`	创建项目	`{ name, description }`	`{ project }`
GET	`/api/projects/:id`	获取项目详情	-	`{ project, tasks }`
PUT	`/api/projects/:id`	更新项目	`{ name, ... }`	`{ project }`
DELETE	`/api/projects/:id`	删除项目	-	`{ success }`
POST	`/api/project/dispatch-task`	创建任务	`{ projectId, type, inputParams }`	`{ task }`
GET	`/api/projects/:id/tasks`	获取项目任务列表	-	`{ tasks }`

6.4 知识库

方法	端点	描述	请求体/参数	响应
POST	`/api/knowledge/upload`	上传文档	FormData	`{ document }`
GET	`/api/knowledge/documents`	获取文档列表	-	`{ documents }`
GET	`/api/knowledge/search`	RAG 检索	`?query=xxx&topK=5`	`{ chunks, scores }`
POST	`/api/knowledge/ask`	AI 问答（强制引用）	`{ question }`	`{ answer, citations }`
POST	`/api/knowledge/facts`	添加事实数据	`{ key, value }`	`{ fact }`
GET	`/api/knowledge/facts`	获取事实数据列表	-	`{ facts }`

6.5 策略蓝图

方法	端点	描述	请求体/参数	响应
POST	`/api/strategy/diagnosis`	提交账号诊断问卷	`{ answers: [] }`	`{ report, blueprint }`
GET	`/api/strategy/blueprint/:projectId`	获取项目蓝图	-	`{ blueprint, calendar }`
POST	`/api/strategy/rewrite`	AI 脚本改写	`{ content, style }`	`{ rewrittenScript }`

6.6 WebSocket 事件

事件	方向	数据	描述
`task:status`	Server → Client	`{ taskId, status }`	任务状态变更通知
`task:progress`	Server → Client	`{ taskId, progress }`	任务进度更新（0-100）
`asset:sync`	Server → Client	`{ assetId, action }`	素材同步通知（移动端上传）
`subscribe:project`	Client → Server	`{ projectId }`	订阅项目更新

7. 数据库 Schema

7.1 核心表结构

users 表

sql

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(100) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(50) DEFAULT 'user', -- admin, user, free_user
    avatar_url VARCHAR(500),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_deleted BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);

projects 表

sql

CREATE TABLE projects (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    status VARCHAR(50) DEFAULT 'active', -- active, archived, deleted
    workflow_preset_id UUID REFERENCES workflow_presets(id),
    blueprint JSONB, -- 30天蓝图数据
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_deleted BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_projects_user_id ON projects(user_id);
CREATE INDEX idx_projects_status ON projects(status);
CREATE INDEX idx_projects_created_at ON projects(created_at DESC);

tasks 表

sql

CREATE TABLE tasks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    project_id UUID NOT NULL REFERENCES projects(id),
    type VARCHAR(100) NOT NULL, -- script_generation, video_generation, etc.
    status VARCHAR(50) DEFAULT 'pending', -- pending, queued, running, success, failed, cancelled
    input_params JSONB NOT NULL,
    output_data JSONB,
    error_message TEXT,
    retry_count INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP
);

CREATE INDEX idx_tasks_project_id ON tasks(project_id);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_created_at ON tasks(created_at DESC);

unified_assets 表

sql

CREATE TABLE unified_assets (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    file_path VARCHAR(500) NOT NULL,
    file_type VARCHAR(50) NOT NULL, -- video, image, audio
    file_size BIGINT,
    file_url VARCHAR(500),
    metadata JSONB, -- 元数据（时长、分辨率、标签等）
    source_task_id UUID REFERENCES tasks(id),
    related_corpus_id UUID REFERENCES user_corpora(id),
    tags TEXT[],
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_deleted BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_assets_user_id ON unified_assets(user_id);
CREATE INDEX idx_assets_file_type ON unified_assets(file_type);
CREATE INDEX idx_assets_tags ON unified_assets USING GIN(tags);

user_corpora 表

sql

CREATE TABLE user_corpora (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    content TEXT NOT NULL,
    source_url VARCHAR(500),
    source_platform VARCHAR(50), -- douyin, xiaohongshu, bilibili
    tags TEXT[],
    metadata JSONB, -- 平台数据、原作者、发布时间等
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_deleted BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_corpora_user_id ON user_corpora(user_id);
CREATE INDEX idx_corpora_source_platform ON user_corpora(source_platform);
CREATE INDEX idx_corpora_tags ON user_corpora USING GIN(tags);

knowledge_documents 表

sql

CREATE TABLE knowledge_documents (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    filename VARCHAR(255) NOT NULL,
    file_size BIGINT,
    file_url VARCHAR(500),
    status VARCHAR(50) DEFAULT 'uploading', -- uploading, parsing, indexed, failed
    chunk_count INT DEFAULT 0,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_kb_docs_user_id ON knowledge_documents(user_id);
CREATE INDEX idx_kb_docs_status ON knowledge_documents(status);

knowledge_chunks 表

sql

CREATE TABLE knowledge_chunks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    document_id UUID NOT NULL REFERENCES knowledge_documents(id),
    content TEXT NOT NULL,
    embedding VECTOR(1536), -- pgvector extension
    chunk_index INT,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_kb_chunks_document_id ON knowledge_chunks(document_id);
-- Vector similarity search index (requires pgvector extension)
CREATE INDEX ON knowledge_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

7.2 索引策略

高频查询字段索引：

所有表的 user_id, created_at, is_deleted
tasks.status, tasks.project_id
projects.status

复合索引：

sql

CREATE INDEX idx_tasks_project_status ON tasks(project_id, status);
CREATE INDEX idx_assets_user_type ON unified_assets(user_id, file_type);

GIN 索引（数组/JSONB）：

sql

CREATE INDEX idx_assets_metadata ON unified_assets USING GIN(metadata);

8. LangGraph Agent 架构

8.1 Agent 类型与职责

LangGraph Runner (langgraph-runner/) 包含多个专业化 Agent：

Agent	文件路径	职责	输入	输出
StrategyAgent	`app/agents/strategy_agent.py`	账号诊断、蓝图生成、脚本改写	诊断问卷/原始文案	诊断报告/30天蓝图/改写脚本
MusicVideoAgent	`app/agents/music_video_agent.py`	音乐/视频生成编排	脚本、风格参数	Suno Job ID / ComfyUI Result
ProductShowcaseAgent	`app/agents/product_showcase_agent.py`	产品展示视频生成	产品信息、展示需求	分镜脚本、素材需求
VoiceoverAgent	`app/agents/voiceover_agent.py`	配音生成	文本、音色配置	音频文件 URL
KnowledgeAgent	`app/agents/knowledge_agent.py`	RAG 检索、知识问答	用户问题	检索结果、AI回答

8.2 LangGraph 工作流示例

StrategyAgent 工作流：

python

from langgraph.graph import StateGraph, END

# 定义状态
class StrategyState(TypedDict):
    diagnosis_answers: dict
    account_type: str
    strengths: List[str]
    weaknesses: List[str]
    blueprint: dict

# 定义节点
async def analyze_answers(state: StrategyState):
    """分析诊断问卷"""
    # 调用 LLM 分析问卷
    analysis = await llm.ainvoke(...)
    return {"strengths": ..., "weaknesses": ...}

async def generate_blueprint(state: StrategyState):
    """生成30天蓝图"""
    # 基于分析结果生成蓝图
    blueprint = await llm.ainvoke(...)
    return {"blueprint": blueprint}

# 构建工作流
workflow = StateGraph(StrategyState)
workflow.add_node("analyze", analyze_answers)
workflow.add_node("generate", generate_blueprint)
workflow.add_edge("analyze", "generate")
workflow.add_edge("generate", END)

app = workflow.compile()

8.3 工具调用流程

Agent 可调用的工具 (app/tools/)：

facts_retrieval: 从数据库检索事实数据
knowledge_search: 向量检索知识库
external_api_call: 调用外部 API（Suno/Fish Audio）

工具调用示例：

python

from langchain.tools import tool

@tool
async def knowledge_search(query: str, top_k: int = 5) -> List[dict]:
    """从知识库检索相关文档片段"""
    # 向量化查询
    embedding = await embeddings.embed_query(query)
    # 相似度搜索
    chunks = await db.similarity_search(embedding, top_k)
    return chunks

8.4 Agent 间通信

Supervisor 模式（多 Agent 协作）：

python

from langgraph.prebuilt import create_react_agent

# 主 Agent 调度子 Agent
supervisor = create_react_agent(
    llm,
    tools=[strategy_agent, music_agent, voiceover_agent],
    prompt="你是一个内容创作协调者..."
)

9. 部署拓扑图

9.1 单机部署（开发/测试环境）

mermaid

graph TB
    subgraph server [单机服务器]
        nginx[Nginx :80/443]
        node[Node.js Backend :3001]
        python[Python LangGraph :8000]
        postgres[(PostgreSQL :5432)]
        redis[(Redis :6379)]
        minio[MinIO :9000]
    end

    internet((Internet)) --> nginx
    nginx --> node
    nginx --> python
    node --> postgres
    node --> redis
    node --> minio
    python --> postgres
    python --> redis

特点：

所有服务运行在同一台服务器
适合开发/测试环境
成本低，配置简单

资源需求：

4 核 8GB RAM
100GB SSD
无需 GPU（使用云端 AI 服务）

9.2 集群部署（生产环境）

mermaid

graph TB
    internet((Internet)) --> cdn[CDN]
    cdn --> slb[阿里云 SLB]
    
    subgraph web [Web 层]
        nginx1[Nginx 1]
        nginx2[Nginx 2]
    end
    
    subgraph app [应用层]
        node1[Node.js 1]
        node2[Node.js 2]
        node3[Node.js 3]
    end
    
    subgraph agent [Agent 层]
        python1[LangGraph 1]
        python2[LangGraph 2]
    end
    
    subgraph data [数据层]
        rds[(PostgreSQL RDS<br/>主从)]
        redisCluster[(Redis Cluster)]
        oss[OSS 对象存储]
    end
    
    subgraph mq [消息队列]
        rabbitmq[RabbitMQ Cluster]
    end
    
    slb --> nginx1 & nginx2
    nginx1 --> node1 & node2
    nginx2 --> node2 & node3
    node1 & node2 & node3 --> rds
    node1 & node2 & node3 --> redisCluster
    node1 & node2 & node3 --> oss
    node1 & node2 & node3 --> rabbitmq
    rabbitmq --> python1 & python2
    python1 & python2 --> rds
    python1 & python2 --> oss

特点：

高可用、可扩展
服务分层部署
使用云托管数据库/缓存
CDN 加速静态资源

资源需求：

Web 层：2 台 2核4GB
应用层：3 台 4核8GB
Agent 层：2 台 4核16GB（如需本地 AI 推理，配置 GPU）
数据库：RDS（8核32GB，主从）
Redis：2GB 集群
OSS：按需

10. 安全与合规

10.1 权限控制

认证 (AuthN): JWT (JSON Web Token)，有效期 7 天，含 refresh token 机制。
授权 (AuthZ):
- 基于角色的访问控制 (RBAC)：Admin, Paid User, Free User.
- 资源隔离：用户只能访问 project_id 属于自己的资源。

10.2 内容安全

输入审核: 调用 LLM 前，先通过敏感词库/API 过滤 Prompt。
输出审核: 图片/视频生成后，异步调用鉴黄/鉴暴 API。

10.3 水印与版权

显式水印: 免费用生成的视频右下角强制叠加 "Created by YiKe"。
隐式水印: 【TBD】在音频/视频频域中嵌入用户 ID 哈希，用于溯源。

📋 落地检查项

[ ] 敏感词库是否支持热更新？
[ ] 鉴权中间件是否覆盖了除 Login/Register 外的所有 API？
[ ] 数据库连接字符串和 API Key 是否从环境变量加载，未硬编码？

11. 可观测性

11.1 日志 (Logging)

标准: JSON 格式，包含 trace_id, level, timestamp, service, msg。
存储: 本地文件 (Rotate) -> 采集器 (Filebeat) -> ES/Loki (TBD).

日志示例：

json

{
  "trace_id": "abc123",
  "level": "info",
  "timestamp": "2025-12-22T10:00:00Z",
  "service": "backend-api",
  "msg": "Task created successfully",
  "task_id": "task-xyz",
  "user_id": "user-123"
}

11.2 关键指标 (Metrics)

需接入 Prometheus 监控以下指标：

http_requests_total: API 请求量（按 status code 分组）
task_queue_depth: 任务队列堆积数
engine_latency_seconds: 外部引擎响应耗时
generation_success_rate: 生成成功率
db_connection_pool_size: 数据库连接池大小

11.3 告警 (Alerting)

严重: 支付回调失败、外部引擎 100% 报错、API 成功率 < 95%。
警告: 队列堆积超过阈值、磁盘空间 < 20%。

📋 落地检查项

[ ] 所有 API 请求是否都生成了唯一的 Trace ID 并透传至下游？
[ ] 是否配置了未捕获异常 (Uncaught Exception) 的全局处理？

12. 风险清单

风险点	影响	缓解措施
供应商 API 波动	Suno/Midjourney 等封号或改协议	1. 建立账号池轮询 2. 实现 Adapter 快速切换 3. 预留 mock 模式供演示
内容合规风险	生成违规内容导致被封禁	1. 接入第三方文本/图片审核 2. 建立黑名单机制 3. 用户协议免责声明
成本失控	用户恶意刷单消耗 Token	1. 严格的配额管理 (Quota Service) 2. 单用户并发限制 3. 异常用量告警
本地环境兼容性	剪映版本更新导致草稿失效	1. 锁定支持的剪映版本 2. 启动时环境自检 3. 提供自动降级方案 (如转云端合成)
数据库性能瓶颈	用户量增长导致查询变慢	1. 读写分离 2. 分库分表 3. 引入缓存层
AI 服务不可用	OpenAI/第三方服务宕机	1. 多供应商备份 2. 本地模型兜底 3. 服务降级

📋 落地检查项

[ ] 是否已制定详细的 API 配额表（每用户每日限制）？
[ ] 法律免责声明是否在用户注册流程中强制阅读？
[ ] 是否有备用的 LLM/绘图渠道以防主渠道断供？

版本记录：

V1.0 (2025-12-21): 初始版本，基础架构说明
V2.0 (2025-12-22): 完整版本，新增 API 端点参考、数据库 Schema、LangGraph Agent 架构、部署拓扑图

一刻工坊｜技术白皮书 V2.0 ​

目录 ​

1. 架构总览 ​

📋 落地检查项 ​

2. 关键数据流 ​

📋 落地检查项 ​

3. 核心对象模型 ​

📋 落地检查项 ​

4. 任务状态机与可靠性 ​

4.1 状态定义 ​

4.2 转换规则 ​

4.3 重试与幂等 ​

📋 落地检查项 ​

5. 外部引擎适配层 ​

5.1 统一接口定义 (Interface) ​

5.2 适配器实现 (Adapters) ​

📋 落地检查项 ​

6. API 端点参考 ​

6.1 认证相关 ​

6.2 灵感广场 ​

6.3 项目管理 ​

6.4 知识库 ​

6.5 策略蓝图 ​

6.6 WebSocket 事件 ​

7. 数据库 Schema ​

7.1 核心表结构 ​

users 表 ​

projects 表 ​

tasks 表 ​

unified_assets 表 ​

user_corpora 表 ​

knowledge_documents 表 ​

knowledge_chunks 表 ​

7.2 索引策略 ​

8. LangGraph Agent 架构 ​

8.1 Agent 类型与职责 ​

8.2 LangGraph 工作流示例 ​

8.3 工具调用流程 ​

8.4 Agent 间通信 ​

9. 部署拓扑图 ​

9.1 单机部署（开发/测试环境） ​

9.2 集群部署（生产环境） ​

10. 安全与合规 ​

10.1 权限控制 ​

10.2 内容安全 ​

10.3 水印与版权 ​

📋 落地检查项 ​

11. 可观测性 ​

11.1 日志 (Logging) ​

11.2 关键指标 (Metrics) ​

11.3 告警 (Alerting) ​

📋 落地检查项 ​

12. 风险清单 ​

📋 落地检查项 ​

一刻工坊｜技术白皮书 V2.0

目录

1. 架构总览

📋 落地检查项

2. 关键数据流

📋 落地检查项

3. 核心对象模型

📋 落地检查项

4. 任务状态机与可靠性

4.1 状态定义

4.2 转换规则

4.3 重试与幂等

📋 落地检查项

5. 外部引擎适配层

5.1 统一接口定义 (Interface)

5.2 适配器实现 (Adapters)

📋 落地检查项

6. API 端点参考

6.1 认证相关

6.2 灵感广场

6.3 项目管理

6.4 知识库

6.5 策略蓝图

6.6 WebSocket 事件

7. 数据库 Schema

7.1 核心表结构

users 表

projects 表

tasks 表

unified_assets 表

user_corpora 表

knowledge_documents 表

knowledge_chunks 表

7.2 索引策略

8. LangGraph Agent 架构

8.1 Agent 类型与职责

8.2 LangGraph 工作流示例

8.3 工具调用流程

8.4 Agent 间通信

9. 部署拓扑图

9.1 单机部署（开发/测试环境）

9.2 集群部署（生产环境）

10. 安全与合规

10.1 权限控制

10.2 内容安全

10.3 水印与版权

📋 落地检查项

11. 可观测性

11.1 日志 (Logging)

11.2 关键指标 (Metrics)

11.3 告警 (Alerting)

📋 落地检查项

12. 风险清单

📋 落地检查项