# 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万条，热点数据日增 <1万条
- 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)
```sql
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)
```sql
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)
```sql
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)
```sql
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)
```sql
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)
```sql
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)
```sql
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)
```sql
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)
```sql
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 数据库连接配置

```javascript
// 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 统一响应格式

```typescript
// 成功响应
{
    "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
用户登录
```typescript
// 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 登录
```typescript
// Request
{
    "code": "github_oauth_code"
}

// Response: 同上
```

### 5.4 Agent 管理接口

#### GET /api/agents
获取 Agent 列表
```typescript
// 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 详情
```typescript
// 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 分发任务
```typescript
// 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
获取任务列表
```typescript
// 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
获取任务详情
```typescript
// 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
汇报任务完成
```typescript
// Request
{
    "from": "lemonv:cto",
    "status": "done",       // done | failed | blocked
    "summary": "技术架构设计已完成，包含系统架构、技术选型、数据库Schema、API规范",
    "result": {
        "documentUrl": "/workspace/tech_architecture.md"
    }
}
```

### 5.6 热点数据接口

#### GET /api/hotspots
获取热点列表
```typescript
// 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
获取热点详情
```typescript
// 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
触发热点爬取
```typescript
// 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
获取剧本列表
```typescript
// Query Params
{
    hotspotId?: string,
    genre?: string,         // 悬疑 | 甜宠 | 都市 | 玄幻
    status?: string,        // draft | reviewing | approved | published
    minScore?: number,
    search?: string,
    page?: number,
    perPage?: number
}
```

#### POST /api/scripts
创建剧本
```typescript
// 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
获取剧本详情
```typescript
// 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
更新剧本
```typescript
// Request
{
    "title": "新标题",
    "content": { ... },
    "status": "reviewing"
}
```

#### POST /api/scripts/:id/publish
发布剧本
```typescript
// 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
获取系统概览数据
```typescript
// 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
获取趋势数据
```typescript
// 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`

#### 认证
```javascript
// 连接时携带 token
const ws = new WebSocket('ws://localhost:3000/ws/claude?token=jwt_token');
```

#### 消息格式
```typescript
// 客户端 → 服务端
{
    "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 开发环境

```yaml
# 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 生产环境

```yaml
# 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 < INFO < WARN < ERROR
- 关键字段：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 参考文档
- [SQLite FTS5 文档](https://www.sqlite.org/fts5.html)
- [Express.js 最佳实践](https://expressjs.com/en/advanced/best-practice-security.html)
- [Vue 3 风格指南](https://vuejs.org/style-guide/)

---

**文档变更记录**

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| v1.0 | 2026-03-26 | 初始版本 | lemonv:cto |