tech_architecture.md
43.9 KB
LemonV 技术架构体系
文档版本: v1.0 创建日期: 2026-03-26 维护者: CTO (lemonv:cto) 状态: 初版设计
1. 概述
1.1 业务背景
LemonV 是一家专注于 AI 互动剧的内容生产公司，核心业务模式：
- 热点追踪: 实时监控全网热点（抖音/微博/小红书/快手等）
- 剧本创作: AI 自动生成互动短剧剧本
- 内容生产: 多模态内容生成（文本/音频/视频）
1.2 架构设计原则
| 原则 | 说明 |
|---|---|
| 数据驱动 | 所有内容生产决策基于数据 |
| AI Native | 架构为 AI 工作流设计，非传统系统叠加 AI |
| 水平扩展 | 热点爆发时可快速扩容爬虫和内容生成 |
| 成本敏感 | 优先使用托管服务，降低运维成本 |
| 快速迭代 | 支持 A/B 测试和灰度发布 |
2. 系统架构设计
2.1 整体架构图
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 前端层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 数据大屏 │ │ 剧本管理 │ │ 热点监控 │ │ 系统管理 │ │
│ │ (Dashboard) │ │ (Scripts) │ │ (Trends) │ │ (Admin) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │ │
└─────────┼──────────────────┼──────────────────┼──────────────────┼──────────────┘
│ │ │ │
└──────────────────┼──────────────────┼──────────────────┘
│ │
┌────────▼────────┐ ┌─────▼──────┐
│ API Gateway │ │ WebSocket │
│ (Nginx) │ │ Gateway │
└────────┬────────┘ └──────┬─────┘
│ │
┌────────────────────────────┼──────────────────┼──────────────────────────────────┐
│ │ 服务层 (Node.js) │
│ ┌─────────────────────────▼──────────────────▼─────────────────────────────┐ │
│ │ Express 主服务 │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Agent API │ │ Skill API │ │ Job API │ │ Auth API │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 核心引擎 (Core Engine) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │Orchestrator│ │Master Sess │ │Agent Mgr │ │Plugin Mgr │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────┼────────────────────────────────────────────┐
│ │ AI 流水线层 (AI Pipeline) │
│ ┌──────────────────────────────────▼────────────────────────────────────────┐ │
│ │ 任务调度器 (Job Manager) │ │
│ │ (优先级队列 + 重试机制 + 进度追踪) │ │
│ └──────────────────────────────────┬────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 爬虫引擎 │ │ 剧本生成 │ │ 内容渲染 │ │ 质量评估 │ │
│ │ (Crawler) │ │ (Script AI) │ │ (Renderer) │ │ (QA Judge) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ Agent 集群 (Multi-Agent) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │Trend Hunter│ │Scriptwriter│ │ Director │ │ Publisher │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────┼────────────────────────────────────────────┐
│ │ 数据层 (Data Layer) │
│ ┌──────────────────────────────────▼────────────────────────────────────────┐ │
│ │ 消息队列 (Redis) │ │
│ │ (任务队列 / 实时通知 / 热点缓存 / Session 状态) │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 主数据库 (SQLite) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Skills │ │ Agents │ │ Jobs │ │ Users │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 文档存储 (文件系统) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Scripts │ │ Hotspots │ │ Assets │ │ Logs │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
2.2 模块职责说明
| 层级 | 模块 | 职责 |
|---|---|---|
| 前端层 | Dashboard | 实时数据可视化、系统状态监控 |
| Scripts | 剧本管理、编辑、版本控制 | |
| Trends | 热点监控面板、趋势分析 | |
| Admin | 用户/Agent/系统配置管理 | |
| 服务层 | API Gateway | 统一入口、限流、认证、路由 |
| Core Engine | Agent 调度、任务编排、状态管理 | |
| AI 流水线 | Job Manager | 任务队列管理、优先级调度、失败重试 |
| Crawler | 多平台热点爬取、数据清洗 | |
| Script AI | 剧本生成、情节设计、对话优化 | |
| Renderer | 内容渲染（文本/音频/视频） | |
| QA Judge | 内容质量评估、多维度打分 | |
| 数据层 | Redis | 高速缓存、消息队列、状态同步 |
| SQLite | 结构化数据持久化（已支持 FTS5 全文搜索） | |
| 文件系统 | 大文本存储（剧本/热点原始数据） |
3. 技术选型报告
3.1 后端技术栈
| 技术 | 选型 | 理由 |
|---|---|---|
| 运行时 | Node.js 20+ | 团队熟悉、非阻塞 I/O 适合高并发爬虫 |
| 框架 | Express.js | 成熟稳定、生态丰富、易于扩展 |
| 数据库 | SQLite + better-sqlite3 | 无需运维、支持 FTS5 全文搜索、适合中小规模 |
| 缓存 | Redis | 热点缓存、任务队列、实时状态同步 |
| 消息队列 | Bull (Redis-based) | 可靠的作业队列、支持延迟任务、进度追踪 |
| WebSocket | ws | 轻量级、与 Express 集成简单 |
| 认证 | JWT + bcrypt | 无状态、适合微服务架构 |
3.2 前端技术栈
| 技术 | 选型 | 理由 |
|---|---|---|
| 框架 | Vue 3 + Composition API | 响应式、TypeScript 支持好、团队熟悉 |
| 构建 | Vite | 快速冷启动、HMR 极速、配置简单 |
| 路由 | vue-router 4 | 官方支持、导航守卫完善 |
| 状态 | Pinia | Vue 官方推荐、TypeScript 友好 |
| 国际化 | vue-i18n | 支持 6 语言（中/英/日/韩/西/俄） |
| UI 库 | Element Plus | 组件丰富、主题可定制 |
| 图表 | ECharts | 数据可视化丰富、交互性好 |
3.3 AI/ML 技术栈
| 技术 | 选型 | 理由 |
|---|---|---|
| LLM | Claude API | 创作能力强、长上下文支持、稳定性高 |
| CLI 工具 | Claude Code | Agent 自动化开发、代码生成 |
| 数据解析 | cheerio + puppeteer | 静态/动态页面爬取 |
| 文本处理 | natural.js | 中文分词、情感分析 |
3.4 运维/DevOps
| 技术 | 选型 | 理由 |
|---|---|---|
| 容器 | Docker | 环境一致性、快速部署 |
| 编排 | Docker Compose | 适合单机/小规模部署 |
| 监控 | 自建 + 日志 | 轻量级、成本可控 |
| CI/CD | GitHub Actions | 免费额度足够、与仓库集成 |
3.5 技术选型对比
数据库选型（为什么选择 SQLite）
| 方案 | 优点 | 缺点 | 结论 |
|---|---|---|---|
| SQLite | 零运维、FTS5全文搜索、单文件迁移 | 并发写入有限 | ✅ 选用 |
| PostgreSQL | 功能强大、高并发 | 需运维、资源占用高 | 过度设计 |
| MongoDB | 文档灵活、水平扩展 | 运维复杂、一致性弱 | 非必要 |
决策理由:
- 预期数据量：Skill 目录 2.7万条，热点数据日增
- SQLite FTS5 已支持全文搜索，满足需求
- 单机部署，无需分片
- 降低运维成本，专注业务开发
爬虫架构选型
| 方案 | 优点 | 缺点 | 结论 |
|---|---|---|---|
| 集中式调度 | 统一管理、易于监控 | 单点风险 | ✅ 选用（初期） |
| 分布式爬虫 | 高可用、高性能 | 复杂度高、成本高 | 后期演进 |
4. 数据库 Schema 设计
4.1 实体关系图
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ users │ │ agents │ │ skills │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ id (PK) │ │ id (PK) │ │ id (PK) │
│ username │ │ agent_id │◄──────│ owner_id │
│ email │ │ company_id │─┐ │ name │
│ role │ │ type │ │ │ type │
│ created_at │ │ status │ │ │ config │
└─────────────┘ │ created_at │ │ │ created_at │
└─────────────┘ │ └─────────────┘
▲ │ ▲
│ │ │
┌──────┴────────┴──┐ ┌─────┴─────────┐
│ companies │ │ skill_versions│
├──────────────────┤ ├───────────────┤
│ id (PK) │ │ id (PK) │
│ name │ │ skill_id (FK) │
│ config │ │ version │
│ created_at │ │ content │
└──────────────────┘ │ created_at │
└───────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ jobs │ │ hotspots │ │ scripts │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ id (PK) │ │ id (PK) │ │ id (PK) │
│ agent_id │◄──────│ job_id (FK) │ │ hotspot_id │◄─┐
│ type │ │ platform │ │ title │ │
│ status │ │ title │ │ content │ │
│ priority │ │ url │ │ status │ │
│ data │ │ content │ │ created_at │ │
│ result │ │ score │ └─────────────┘ │
│ created_at │ │ crawled_at │ ▲ │
└─────────────┘ └─────────────┘ │ │
└─────────┘
4.2 表结构设计
4.2.1 用户表 (users)
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT UNIQUE NOT NULL,
email TEXT UNIQUE,
password_hash TEXT,
role TEXT DEFAULT 'user', -- admin, user, viewer
avatar_url TEXT,
github_id TEXT UNIQUE,
config JSON,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_github ON users(github_id);
4.2.2 公司表 (companies)
CREATE TABLE companies (
id INTEGER PRIMARY KEY AUTOINCREMENT,
company_id TEXT UNIQUE NOT NULL, -- 如: lemonv, wechatai
name TEXT NOT NULL,
description TEXT,
config JSON, -- 公司级别配置
status TEXT DEFAULT 'active', -- active, paused, archived
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_companies_id ON companies(company_id);
4.2.3 Agent 表 (agents)
CREATE TABLE agents (
id INTEGER PRIMARY KEY AUTOINCREMENT,
agent_id TEXT UNIQUE NOT NULL, -- 如: lemonv:trend-hunter
company_id TEXT NOT NULL,
name TEXT NOT NULL,
emoji TEXT DEFAULT '🤖',
type TEXT NOT NULL, -- cxo, specialist, executor, meta
status TEXT DEFAULT 'training', -- training, ready, active, error
greeting TEXT,
config_path TEXT, -- agent.md 文件路径
skills TEXT, -- 逗号分隔的技能列表
metadata JSON, -- 动态配置
last_active_at DATETIME,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (company_id) REFERENCES companies(company_id)
);
CREATE INDEX idx_agents_company ON agents(company_id);
CREATE INDEX idx_agents_type ON agents(type);
CREATE INDEX idx_agents_status ON agents(status);
4.2.4 Skill 表 (skills)
CREATE TABLE skills (
id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_id TEXT UNIQUE NOT NULL,
owner_id TEXT, -- 所属 agent_id
name TEXT NOT NULL,
description TEXT,
type TEXT, -- builtin, custom, marketplace
category TEXT,
tags TEXT, -- JSON 数组
config JSON, -- 技能配置
code_path TEXT, -- 代码文件路径
version INTEGER DEFAULT 1,
is_public BOOLEAN DEFAULT 0,
usage_count INTEGER DEFAULT 0,
rating REAL DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- FTS5 全文搜索虚拟表
CREATE VIRTUAL TABLE skills_fts USING fts5(
skill_id,
name,
description,
content=skills,
content_rowid=id
);
-- 触发器保持 FTS 索引同步
CREATE TRIGGER skills_ai AFTER INSERT ON skills BEGIN
INSERT INTO skills_fts(rowid, skill_id, name, description)
VALUES (new.id, new.skill_id, new.name, new.description);
END;
CREATE TRIGGER skills_ad AFTER DELETE ON skills BEGIN
INSERT INTO skills_fts(skills_fts, rowid, skill_id, name, description)
VALUES ('delete', old.id, old.skill_id, old.name, old.description);
END;
CREATE TRIGGER skills_au AFTER UPDATE ON skills BEGIN
INSERT INTO skills_fts(skills_fts, rowid, skill_id, name, description)
VALUES ('delete', old.id, old.skill_id, old.name, old.description);
INSERT INTO skills_fts(rowid, skill_id, name, description)
VALUES (new.id, new.skill_id, new.name, new.description);
END;
CREATE INDEX idx_skills_owner ON skills(owner_id);
CREATE INDEX idx_skills_category ON skills(category);
CREATE INDEX idx_skills_type ON skills(type);
4.2.5 任务表 (jobs)
CREATE TABLE jobs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT UNIQUE NOT NULL, -- 如: T-mn77t6b8
from_agent TEXT, -- 分配者
to_agent TEXT NOT NULL, -- 执行者
goal_id TEXT, -- 关联目标
node_id TEXT, -- 关联 OKR 节点
type TEXT DEFAULT 'task', -- task, cron, event
priority TEXT DEFAULT 'P1', -- P0, P1, P2
title TEXT NOT NULL,
description TEXT,
status TEXT DEFAULT 'pending', -- pending, in_progress, done, failed, blocked
data JSON, -- 任务参数
result JSON, -- 执行结果
summary TEXT, -- 完成摘要
started_at DATETIME,
completed_at DATETIME,
deadline_at DATETIME,
retry_count INTEGER DEFAULT 0,
max_retries INTEGER DEFAULT 3,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_jobs_agent ON jobs(to_agent);
CREATE INDEX idx_jobs_status ON jobs(status);
CREATE INDEX idx_jobs_goal ON jobs(goal_id);
CREATE INDEX idx_jobs_priority ON jobs(priority, created_at);
CREATE INDEX idx_jobs_deadline ON jobs(deadline_at);
4.2.6 热点数据表 (hotspots)
CREATE TABLE hotspots (
id INTEGER PRIMARY KEY AUTOINCREMENT,
hotspot_id TEXT UNIQUE NOT NULL,
platform TEXT NOT NULL, -- douyin, weibo, xiaohongshu, kuaishou
category TEXT, -- 分类
title TEXT NOT NULL,
url TEXT,
content TEXT, -- 原始内容
author TEXT,
author_id TEXT,
engagement_score INTEGER, -- 互动分（点赞+评论+转发）
heat_score REAL, -- 热度分数 0-100
drama_score REAL, -- 戏剧性评分
keywords TEXT, -- JSON 关键词
related_topics TEXT, -- JSON 相关话题
crawled_at DATETIME,
processed_at DATETIME,
status TEXT DEFAULT 'new', -- new, processing, processed, ignored
raw_data JSON, -- 原始抓取数据
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- FTS5 全文搜索
CREATE VIRTUAL TABLE hotspots_fts USING fts5(
title,
content,
content=hotspots,
content_rowid=id
);
CREATE INDEX idx_hotspots_platform ON hotspots(platform);
CREATE INDEX idx_hotspots_heat ON hotspots(heat_score DESC);
CREATE INDEX idx_hotspots_time ON hotspots(crawled_at DESC);
CREATE INDEX idx_hotspots_status ON hotspots(status);
4.2.7 剧本表 (scripts)
CREATE TABLE scripts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
script_id TEXT UNIQUE NOT NULL,
hotspot_id TEXT, -- 关联热点
title TEXT NOT NULL,
genre TEXT, -- 题材: 悬疑/甜宠/都市/玄幻
style TEXT, -- 风格标签
synopsis TEXT, -- 剧情简介
content JSON, -- 剧本内容（分幕/场景/对话）
characters JSON, -- 角色设定
choices JSON, -- 互动选项设计
estimated_duration INTEGER, -- 预计时长（分钟）
target_audience TEXT, -- 目标受众
quality_score REAL, -- 质量评分
ai_model TEXT, -- 生成模型
version INTEGER DEFAULT 1,
status TEXT DEFAULT 'draft', -- draft, reviewing, approved, published, archived
created_by TEXT, -- 创建者 agent_id
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
published_at DATETIME,
FOREIGN KEY (hotspot_id) REFERENCES hotspots(hotspot_id)
);
-- FTS5 全文搜索
CREATE VIRTUAL TABLE scripts_fts USING fts5(
title,
synopsis,
content=scripts,
content_rowid=id
);
CREATE INDEX idx_scripts_hotspot ON scripts(hotspot_id);
CREATE INDEX idx_scripts_status ON scripts(status);
CREATE INDEX idx_scripts_genre ON scripts(genre);
CREATE INDEX idx_scripts_score ON scripts(quality_score DESC);
4.2.8 内容发布表 (publishes)
CREATE TABLE publishes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
publish_id TEXT UNIQUE NOT NULL,
script_id TEXT NOT NULL,
platform TEXT NOT NULL, -- 发布平台
platform_content_id TEXT, -- 平台返回的内容ID
status TEXT DEFAULT 'pending', -- pending, publishing, published, failed
schedule_at DATETIME, -- 定时发布时间
published_at DATETIME,
stats JSON, -- 发布后的统计数据
error_message TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (script_id) REFERENCES scripts(script_id)
);
CREATE INDEX idx_publishes_script ON publishes(script_id);
CREATE INDEX idx_publishes_status ON publishes(status);
CREATE INDEX idx_publishes_schedule ON publishes(schedule_at);
4.2.9 系统日志表 (system_logs)
CREATE TABLE system_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
level TEXT NOT NULL, -- debug, info, warn, error
source TEXT, -- 来源模块
agent_id TEXT, -- 关联 agent
message TEXT NOT NULL,
metadata JSON,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_logs_level ON system_logs(level);
CREATE INDEX idx_logs_source ON system_logs(source);
CREATE INDEX idx_logs_time ON system_logs(created_at DESC);
CREATE INDEX idx_logs_agent ON system_logs(agent_id);
4.3 数据库连接配置
// config/database.js
const Database = require('better-sqlite3');
const db = new Database('data/lemonv.sqlite', {
verbose: process.env.NODE_ENV === 'development' ? console.log : null
});
// 性能优化
db.pragma('journal_mode = WAL');
db.pragma('synchronous = NORMAL');
db.pragma('cache_size = 10000');
db.pragma('foreign_keys = ON');
module.exports = db;
5. API 接口规范
5.1 接口设计原则
- RESTful 风格: 资源命名，HTTP 动词表达操作
- 统一响应格式: 标准 envelope 结构
- 版本控制: URL 路径中包含版本号
/api/v1/... - 认证方式: JWT Bearer Token
- 限流: 基于 IP 和用户双重限流
5.2 统一响应格式
// 成功响应
{
"success": true,
"data": {},
"meta": {
"timestamp": "2026-03-26T08:30:00Z",
"requestId": "req_xxx"
}
}
// 错误响应
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数错误",
"details": [
{ "field": "title", "message": "标题不能为空" }
]
},
"meta": { ... }
}
// 分页响应
{
"success": true,
"data": [...],
"pagination": {
"page": 1,
"perPage": 20,
"total": 100,
"totalPages": 5
},
"meta": { ... }
}
5.3 认证接口
POST /api/auth/login
用户登录
// Request
{
"username": string,
"password": string
}
// Response
{
"success": true,
"data": {
"token": "jwt_token_string",
"refreshToken": "refresh_token_string",
"expiresIn": 86400,
"user": {
"id": "user_xxx",
"username": "john",
"role": "admin"
}
}
}
POST /api/auth/github
GitHub OAuth 登录
// Request
{
"code": "github_oauth_code"
}
// Response: 同上
5.4 Agent 管理接口
GET /api/agents
获取 Agent 列表
// Query Params
{
companyId?: string, // 按公司筛选
type?: string, // 按类型筛选
status?: string, // 按状态筛选
page?: number, // 默认 1
perPage?: number // 默认 20
}
// Response
{
"success": true,
"data": [
{
"id": "lemonv:trend-hunter",
"name": "热点分析师",
"emoji": "🔥",
"type": "executor",
"status": "ready",
"companyId": "lemonv",
"lastActiveAt": "2026-03-26T08:33:05Z"
}
],
"pagination": { ... }
}
GET /api/agents/:id
获取 Agent 详情
// Response
{
"success": true,
"data": {
"id": "lemonv:trend-hunter",
"name": "热点分析师",
"emoji": "🔥",
"type": "executor",
"status": "ready",
"companyId": "lemonv",
"greeting": "🔥 热点雷达已启动...",
"skills": ["trend_analysis", "hotspot_monitoring"],
"metadata": { ... },
"createdAt": "2026-03-24T03:49:31Z",
"lastActiveAt": "2026-03-26T08:33:05Z"
}
}
POST /api/agents/:id/tasks
向 Agent 分发任务
// Request
{
"from": "lemonv:ceo",
"task": "爬取今日抖音热点TOP50",
"priority": "P1", // P0 | P1 | P2
"goalId": "G-001",
"nodeId": "G-001.1.1",
"autoExecute": true, // 是否立即执行
"deadlineAt": "2026-03-26T18:00:00Z"
}
// Response
{
"success": true,
"data": {
"taskId": "T-mn77t6b8",
"status": "dispatched",
"dispatchedAt": "2026-03-26T08:30:00Z"
}
}
5.5 任务管理接口
GET /api/tasks
获取任务列表
// Query Params
{
agentId?: string, // 按执行者筛选
status?: string, // pending | in_progress | done | failed | blocked
priority?: string, // P0 | P1 | P2
goalId?: string, // 按目标筛选
page?: number,
perPage?: number
}
GET /api/tasks/:id
获取任务详情
// Response
{
"success": true,
"data": {
"taskId": "T-mn77t6b8",
"from": "lemonv:ceo",
"to": "lemonv:cto",
"title": "设计 LemonV 技术架构体系",
"description": "...",
"priority": "P0",
"status": "in_progress",
"goalId": "G-001",
"nodeId": "G-001.2",
"data": { ... },
"result": null,
"createdAt": "2026-03-26T08:00:00Z",
"startedAt": "2026-03-26T08:05:00Z",
"deadlineAt": "2026-03-26T18:00:00Z"
}
}
POST /api/tasks/:id/report
汇报任务完成
// Request
{
"from": "lemonv:cto",
"status": "done", // done | failed | blocked
"summary": "技术架构设计已完成，包含系统架构、技术选型、数据库Schema、API规范",
"result": {
"documentUrl": "/workspace/tech_architecture.md"
}
}
5.6 热点数据接口
GET /api/hotspots
获取热点列表
// Query Params
{
platform?: string, // douyin | weibo | xiaohongshu | kuaishou
category?: string,
minHeat?: number, // 最小热度
maxHeat?: number,
status?: string, // new | processing | processed
startDate?: string, // ISO 8601
endDate?: string,
search?: string, // 全文搜索关键词
page?: number,
perPage?: number
}
// Response
{
"success": true,
"data": [
{
"hotspotId": "hs_xxx",
"platform": "douyin",
"title": "某明星官宣",
"url": "https://...",
"heatScore": 95.5,
"dramaScore": 88.0,
"engagementScore": 1500000,
"keywords": ["明星", "官宣", "恋爱"],
"crawledAt": "2026-03-26T08:00:00Z",
"status": "processed"
}
],
"pagination": { ... }
}
GET /api/hotspots/:id
获取热点详情
// Response
{
"success": true,
"data": {
"hotspotId": "hs_xxx",
"platform": "douyin",
"category": "娱乐",
"title": "某明星官宣",
"content": "...",
"author": "娱乐账号",
"heatScore": 95.5,
"dramaScore": 88.0,
"keywords": ["明星", "官宣", "恋爱"],
"relatedTopics": ["#明星官宣", "#娱乐圈"],
"rawData": { ... },
"scripts": [
{ "scriptId": "sc_xxx", "title": "...", "status": "published" }
]
}
}
POST /api/hotspots/crawl
触发热点爬取
// Request
{
"platforms": ["douyin", "weibo"],
"limit": 50,
"priority": "P1"
}
// Response
{
"success": true,
"data": {
"jobId": "job_xxx",
"status": "queued",
"estimatedTime": "5 minutes"
}
}
5.7 剧本管理接口
GET /api/scripts
获取剧本列表
// Query Params
{
hotspotId?: string,
genre?: string, // 悬疑 | 甜宠 | 都市 | 玄幻
status?: string, // draft | reviewing | approved | published
minScore?: number,
search?: string,
page?: number,
perPage?: number
}
POST /api/scripts
创建剧本
// Request
{
"hotspotId": "hs_xxx", // 可选：关联热点
"title": "重生之我在娱乐圈",
"genre": "都市",
"synopsis": "...",
"targetAudience": "18-35岁女性",
"template": "rebirth_entertainment" // 使用模板
}
// Response
{
"success": true,
"data": {
"scriptId": "sc_xxx",
"status": "generating",
"estimatedTime": "3 minutes",
"jobId": "job_xxx"
}
}
GET /api/scripts/:id
获取剧本详情
// Response
{
"success": true,
"data": {
"scriptId": "sc_xxx",
"title": "重生之我在娱乐圈",
"genre": "都市",
"style": ["爽文", "逆袭", "甜宠"],
"synopsis": "...",
"content": {
"acts": [
{
"actNumber": 1,
"title": "重生归来",
"scenes": [
{
"sceneNumber": "1-1",
"setting": "片场",
"characters": ["女主", "反派女二"],
"dialogue": [
{ "character": "反派女二", "line": "你永远都是配角！" },
{ "character": "女主", "line": "这次不一样了..." }
],
"choices": [
{ "text": "直接反击", "nextScene": "1-2A" },
{ "text": "隐忍不发", "nextScene": "1-2B" }
]
}
]
}
]
},
"characters": [
{ "name": "女主", "traits": ["坚韧", "聪明", "复仇心切"] }
],
"estimatedDuration": 15,
"qualityScore": 87.5,
"status": "approved",
"createdAt": "2026-03-26T08:00:00Z"
}
}
PUT /api/scripts/:id
更新剧本
// Request
{
"title": "新标题",
"content": { ... },
"status": "reviewing"
}
POST /api/scripts/:id/publish
发布剧本
// Request
{
"platforms": ["douyin", "kuaishou"],
"scheduleAt": "2026-03-27T12:00:00Z" // 可选：定时发布
}
// Response
{
"success": true,
"data": {
"publishId": "pub_xxx",
"status": "scheduled",
"scheduledAt": "2026-03-27T12:00:00Z"
}
}
5.8 数据统计接口
GET /api/stats/overview
获取系统概览数据
// Response
{
"success": true,
"data": {
"agents": {
"total": 10,
"active": 8,
"training": 2
},
"tasks": {
"pending": 5,
"inProgress": 3,
"completedToday": 15
},
"hotspots": {
"today": 120,
"unprocessed": 20
},
"scripts": {
"total": 500,
"thisWeek": 50,
"published": 300,
"avgScore": 82.5
}
}
}
GET /api/stats/trends
获取趋势数据
// Query Params
{
metric: string, // hotspots | scripts | tasks
period: string, // day | week | month
startDate?: string,
endDate?: string
}
// Response
{
"success": true,
"data": {
"labels": ["03-20", "03-21", "03-22", "03-23", "03-24", "03-25", "03-26"],
"datasets": [
{
"label": "热点数量",
"data": [100, 120, 95, 140, 130, 150, 120]
}
]
}
}
5.9 WebSocket 实时接口
连接: ws://localhost:3000/ws/claude
认证
// 连接时携带 token
const ws = new WebSocket('ws://localhost:3000/ws/claude?token=jwt_token');
消息格式
// 客户端 → 服务端
{
"type": "chat",
"agentId": "lemonv:trend-hunter",
"message": "查看今日热点"
}
// 服务端 → 客户端 (流式响应)
{
"type": "chunk",
"agentId": "lemonv:trend-hunter",
"content": "正在为您查询..."
}
// 服务端 → 客户端 (完成)
{
"type": "complete",
"agentId": "lemonv:trend-hunter",
"result": { ... }
}
// 服务端 → 客户端 (任务通知)
{
"type": "task_update",
"taskId": "T-mn77t6b8",
"status": "done",
"summary": "任务完成摘要"
}
5.10 错误码定义
| 错误码 | HTTP状态 | 说明 |
|---|---|---|
OK |
200 | 成功 |
CREATED |
201 | 创建成功 |
BAD_REQUEST |
400 | 请求参数错误 |
UNAUTHORIZED |
401 | 未认证 |
FORBIDDEN |
403 | 无权限 |
NOT_FOUND |
404 | 资源不存在 |
CONFLICT |
409 | 资源冲突 |
VALIDATION_ERROR |
422 | 数据验证失败 |
RATE_LIMITED |
429 | 请求过于频繁 |
INTERNAL_ERROR |
500 | 服务器内部错误 |
6. 部署架构
6.1 开发环境
# docker-compose.dev.yml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
- "5173:5173"
volumes:
- ./data:/app/data
- ./workspace:/app/workspace
environment:
- NODE_ENV=development
- DB_PATH=/app/data/lemonv.sqlite
- REDIS_URL=redis://redis:6379
redis:
image: redis:7-alpine
ports:
- "6379:6379"
6.2 生产环境
# docker-compose.prod.yml
version: '3.8'
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/nginx/ssl
app:
build: .
deploy:
replicas: 2
environment:
- NODE_ENV=production
volumes:
- /mnt/data:/app/data
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
volumes:
redis_data:
6.3 目录结构
/data/
├── lemonv.sqlite # 主数据库
├── skills/ # Skill 目录（代码仓库外）
│ ├── skill_a/
│ └── skill_b/
├── workspace/ # 各 Agent 工作区
│ ├── lemonv/
│ │ ├── ceo/
│ │ ├── cto/
│ │ └── trend-hunter/
│ └── assets/ # 共享资源
├── hotspots/ # 热点原始数据
├── scripts/ # 剧本存档
└── logs/ # 日志文件
7. 安全规范
7.1 认证与授权
- 所有 API 需携带有效 JWT Token（除登录/注册）
- Token 有效期 24 小时，支持 Refresh Token
- 角色权限控制：admin > user > viewer
7.2 数据安全
- 密码使用 bcrypt 加密存储
- 敏感操作需二次验证
- API Key 不存储在代码中，使用环境变量
7.3 接口安全
- 全站 HTTPS
- 请求限流：IP 级别 100/分钟，用户级别 1000/分钟
- SQL 注入防护：使用参数化查询
- XSS 防护：输入过滤、输出转义
7.4 爬虫安全
- 遵守各平台 robots.txt
- 请求间隔随机 1-3 秒
- 使用代理池轮换 IP
- 异常监控，自动降速/暂停
8. 监控与运维
8.1 日志规范
- 结构化日志（JSON 格式）
- 分级：DEBUG
- 关键字段：timestamp, level, source, agent_id, message, metadata
8.2 关键指标
| 指标 | 说明 | 告警阈值 |
|---|---|---|
api_latency |
API 响应时间 | > 500ms |
error_rate |
错误率 | > 1% |
queue_depth |
任务队列深度 | > 100 |
agent_heartbeat |
Agent 心跳超时 | > 5 分钟 |
db_size |
数据库大小 | > 1GB |
8.3 健康检查
GET /health
{
"status": "healthy",
"checks": {
"database": "ok",
"redis": "ok",
"disk": "ok"
},
"timestamp": "2026-03-26T08:30:00Z"
}
9. 扩展规划
9.1 短期（1-3个月）
- [ ] 完善爬虫平台支持（抖音/微博/小红书/快手）
- [ ] 剧本生成模板库建设
- [ ] 质量评估模型优化
- [ ] 前端 Dashboard 可视化
9.2 中期（3-6个月）
- [ ] 多模态内容生成（音频/视频）
- [ ] A/B 测试框架
- [ ] 内容推荐算法
- [ ] 多租户 SaaS 化
9.3 长期（6-12个月）
- [ ] 分布式爬虫架构
- [ ] 实时流处理（Kafka/Flink）
- [ ] 私有化部署方案
- [ ] 开放 API 平台
10. 附录
10.1 术语表
| 术语 | 说明 |
|---|---|
| Agent | 智能体，具有特定能力的 AI 角色 |
| Skill | 技能，可复用的功能模块 |
| Hotspot | 热点，全网热门话题数据 |
| Script | 剧本，互动短剧内容 |
| Pipeline | 流水线，内容生产的自动化流程 |
10.2 参考文档
文档变更记录
| 版本 | 日期 | 变更内容 | 作者 |
|---|---|---|---|
| v1.0 | 2026-03-26 | 初始版本 | lemonv:cto |