CreAtlas

简体中文 | English

CreAtlas 会把 Bilibili 创作者的公开视频整理成一套可检索、可追溯的本地资料库。你可以用它登记创作者、限定视频范围、生成带时间戳的转写和摘要，再围绕已经保存的证据提问。

它不是“把整个平台抓下来”的爬虫，也不会绕过登录、付费、私有内容、地区限制或平台风控。当前版本是单机运行的 v0.1 MVP，只实现了 Bilibili。

你可以用它做什么

• 登记一个创作者，但先不触发下载或分析。
• 按最新 N 条、最近 N 天、日期范围或全部历史选择视频。
• 优先复用平台字幕，或使用本地 Faster-Whisper 做 ASR。
• 为视频生成摘要、主题、观点、预测和对应证据。
• 复用已经完成的转写与分析，避免重复调用 ASR 和 LLM。
• 在创作者范围内提问，并得到带来源的回答。
• 通过 CLI、REST API 或 React Web 使用同一套本地数据。
• 使用 SQLite Job、Worker 和 Scheduler 恢复或重试后台任务。

数据从来源到回答始终保留关联：

Creator → Content → Transcript → Summary → Evidence → Claim / Topic → Research

快速开始

下面的命令以 Windows PowerShell 为例。建议先按这一节跑通一个创作者，再调整 LLM、GPU 或后台服务。

1. 准备环境

本地运行至少需要：

• Python 3.12 或更高版本；
• Microsoft Edge、Chrome 或 Playwright Chromium（使用 browser 内容源时需要）；
• Node.js 22（只在本地开发 Web 时需要）；
• Docker Desktop（只在使用 Compose 时需要）；
• NVIDIA 驱动和兼容 CUDA 环境（只在 GPU ASR 时需要）。

2. 安装 CreAtlas

在仓库根目录执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

creatlas database status
creatlas database upgrade

database upgrade 会把数据库升级到安装包携带的 Alembic 版本。升级已有 SQLite 前，CreAtlas 会先在 ~/.creatlas/backups 创建并校验备份。空数据库可以在运行时自动初始化，但显式执行上面的命令更容易提前发现配置问题。

默认安装已经包含 Faster-Whisper、yt-dlp 和 Playwright Python 依赖，不需要再安装旧的 [asr] 或 [browser] extra。模型权重会在第一次真正使用 ASR 时下载，不会随 Python 包一起安装。

3. 选择 Bilibili 内容源

处理任意公开数字 UID 时，先使用浏览器模式：

$env:CREATLAS_BILIBILI_SOURCE = "browser"
$env:CREATLAS_BROWSER_CHANNEL = "msedge"

creatlas bilibili browser test <UID>

如果诊断提示需要登录，先扫码，再重新测试：

creatlas bilibili login
creatlas bilibili status
creatlas bilibili browser test <UID>

登录命令保存的 Cookie 会传给浏览器模式使用。browser test 只解析创作者并检查第一页视频，不会登记创作者，也不会启动分析。

4. 启用转写并完成第一次分析

analyze 默认要求严格 ASR，因此先明确启用本地 ASR。CPU 可以从下面这组保守配置开始：

$env:CREATLAS_ASR_ENABLED = "true"
$env:CREATLAS_ASR_DEVICE = "cpu"
$env:CREATLAS_ASR_COMPUTE_TYPE = "int8"
$env:CREATLAS_ASR_BEAM_SIZE = "1"
$env:CREATLAS_ASR_VAD_FILTER = "true"

creatlas add <UID>
creatlas analyze <UID> --videos 5
creatlas status <UID>

这里有两个容易混淆的行为：

• add 只登记创作者，不拉取视频、不创建 Job，也不执行 ASR；
• analyze 才会选择视频、生成转写和分析，并提交创作者画像与报告。

如果你希望优先使用平台已有字幕，只在没有字幕时回退到 ASR，请改用：

creatlas analyze <UID> --videos 5 --transcript-source auto

第一次 ASR 可能需要等待模型下载。后续分析同一视频时，CreAtlas 会优先复用已保存的转写和视频分析，但仍会把这些结果纳入本次创作者画像。

5. 基于证据提问

分析完成后，可以直接围绕该创作者提问：

creatlas ask <UID> "这个创作者对 AI 基础设施有哪些主要观点？"

Research 会从已经持久化的 Claim、Transcript 和 Evidence 中选择材料。回答中的来源由已保存的证据构造，而不是把模型生成的自由文本直接当作引用。

常用命令

控制分析范围

四种范围选项互斥；如果省略创作者，CLI 会提示你从已登记的创作者中选择。

# 最新 20 条
creatlas analyze <CREATOR> --videos 20

# 最近 30 天
creatlas analyze <CREATOR> --days 30

# 指定日期范围
creatlas analyze <CREATOR> --from 2026-01-01 --to 2026-06-30

# 内容源可发现的全部历史
creatlas analyze <CREATOR> --all

# 机器可读输出
creatlas analyze <CREATOR> --videos 20 --json
creatlas status <CREATOR> --json

CREATOR 可以是内部 creator ID，也可以是外部 UID。--all 会显著增加采集、转写和模型调用量，请先用较小范围验证配置。

同步与后台任务

普通使用优先选择 analyze。需要让后台 Worker 持续把创作者推进到 READY 时，再使用 sync：

creatlas sync <CREATOR>
creatlas sync <CREATOR> --no-wait
creatlas sync <CREATOR> --full-history

--no-wait 只入队后返回；--full-history 会显式导入所有可发现的历史页。admin 下的 jobs、worker、scheduler 和 reprocess 面向运维与故障恢复。旧的顶层 creator / content / jobs / worker / scheduler 仍保留为兼容入口。

重新总结一条已有转写

creatlas summarize <CONTENT_ID>
creatlas summarize <CONTENT_ID> --profile <PROFILE_NAME> --force --json

summarize 只读取已保存的转写，不会下载音频或执行 ASR。相同 transcript、profile、model 和 prompt 会命中摘要缓存；只有 --force 会生成并保留新版本。

缩小研究范围

creatlas ask <CREATOR> "主要观点是什么？" --from 2026-01-01 --to 2026-06-30
creatlas ask <CREATOR> "有哪些可验证的预测？" --topic AI --json

内容源怎么选

如果 auto 只检测到部分 Open API 凭据，程序会直接报错，而不是猜测应该使用哪条路径。

官方 Open API 的最短检查流程如下：

$env:CREATLAS_BILIBILI_SOURCE = "open_api"
$env:CREATLAS_BILIBILI_OPEN_CLIENT_ID = "<CLIENT_ID>"
$env:CREATLAS_BILIBILI_OPEN_CLIENT_SECRET = "<CLIENT_SECRET>"
$env:CREATLAS_BILIBILI_OPEN_ACCESS_TOKEN = "<ACCESS_TOKEN>"

creatlas bilibili open-api test
creatlas add me

这条路径只覆盖当前应用的账号授权范围，不能用任意公开 UID 查询其他创作者。当前 CLI 使用已有 Access Token；OAuth 发起和 Token 自动轮换尚未实现。

启动 API 和 Web

serve 会在一个进程中同时启动 API、Worker 和 Scheduler。先生成一个本地 Token，再启动服务：

$env:CREATLAS_API_TOKEN = python -c "import secrets; print(secrets.token_hex(32))"
creatlas serve

启动后可访问：

• API：http://localhost:8000
• OpenAPI 文档：http://localhost:8000/docs
• 健康检查：http://localhost:8000/health

另开一个 PowerShell 窗口启动 Web。新窗口需要使用同一个 Token：

$env:CREATLAS_API_TOKEN = "<与 API 相同的 Token>"
Set-Location web
npm ci
npm run dev

然后访问 http://localhost:5173。开发代理会在服务端为 /api 请求注入 Token，不会把 Token 打进浏览器 JavaScript。

所有 /api/v1 下的 POST、PUT、PATCH 和 DELETE 请求都需要 Authorization: Bearer <token> 或 X-API-Key: <token>。没有配置 Token 时，读取接口和健康检查仍可用，写接口会返回 503。

REST API 入口

完整、实时的请求模型以 /docs 为准。主要路由包括：

Docker Compose

Compose 会从仓库根目录 .env 读取配置，并强制要求 CREATLAS_API_TOKEN 非空：

Copy-Item .env.example .env
python -c "import secrets; print(secrets.token_hex(32))"

把上一条命令的输出写入 .env：

CREATLAS_API_TOKEN=<刚生成的 Token>

再启动服务：

docker compose up --build

api 和 worker 共用 creatlas_data volume。只有 migrate 成功后，长期运行的服务才会启动。

配置规则

CreAtlas 按下面的优先级取值：

当前进程环境变量 > ~/.creatlas/config.toml > 代码默认值

这里要特别注意：CLI 不会自动读取仓库根目录的 .env。.env 主要供 Docker Compose 和 Web 开发代理使用。要让 CLI 取得配置，请在当前终端设置 $env:...，或将有效配置写入用户 TOML。

# 查看最终生效的配置；凭据会脱敏
creatlas config show

# 把当前有效配置保存到 ~/.creatlas/config.toml
creatlas config save

# 配置代理
creatlas config proxy system
creatlas config proxy direct
creatlas config proxy manual http://127.0.0.1:7890

config save 会保存当前所有有效设置，包括环境中的 Token、Cookie 和 API Key。保存后不要提交或共享 ~/.creatlas/config.toml，也不要放宽它的文件权限。

如果项目曾把数据放在仓库 data/ 或旧 %LOCALAPPDATA%\.creatlas 下，可以执行：

creatlas config migrate-storage --source-data-root data

该命令会把旧数据合并到当前用户的 ~/.creatlas，并在数据库已升级时回填历史工件目录。完整环境变量和默认值见 .env.example。

配置 LLM

没有外部 API Key 时，默认 profile 使用离线 heuristic。它适合跑通流程和测试持久化，但不会提供外部大模型的生成质量。

如果只需要一个 OpenAI-compatible 服务，可以直接设置兼容环境变量：

$env:OPENAI_BASE_URL = "https://api.openai.com/v1"
$env:OPENAI_API_KEY = "<API_KEY>"
$env:OPENAI_MODEL = "<MODEL_NAME>"

需要同时使用多个提供方时，在 ~/.creatlas/config.toml 中把连接、模型和业务路由分开配置：

[llm]
max_input_chars = 120000

[llm.routes]
analysis = "fast"
summary = "quality"
creator_profile = "quality"
research = "fast"

[llm.providers.openai]
type = "openai_compatible"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
timeout_seconds = 90.0

[llm.providers.anthropic]
type = "anthropic"
base_url = "https://api.anthropic.com"
api_key_env = "ANTHROPIC_API_KEY"
timeout_seconds = 90.0

[llm.profiles.fast]
provider = "openai"
model = "<FAST_MODEL>"
max_output_tokens = 4096

[llm.profiles.quality]
provider = "anthropic"
model = "<QUALITY_MODEL>"
max_output_tokens = 8192

支持的 provider 类型是 openai_compatible、anthropic、gemini 和 heuristic。四个 route 必须指向已存在的 profile。推荐用 api_key_env 引用环境变量，不要把真实密钥直接写进 TOML。

CLI 每次启动都会重新加载配置；已经运行的 serve、worker 或 scheduler 必须重启后才会使用新配置。长转写会在片段边界分块；摘要缓存会同时校验转写哈希、profile、provider 配置指纹、模型和提示词版本。

ASR 使用建议

CREATLAS_ASR_ENABLED 的默认值是 false。使用默认的严格 ASR 分析前，必须把它改为 true；使用 --transcript-source auto 时，CreAtlas 会先找平台字幕，再在需要时回退到已启用的 ASR。

8 GB NVIDIA GPU 可以从这组配置开始：

$env:CREATLAS_ASR_ENABLED = "true"
$env:CREATLAS_ASR_DEVICE = "cuda"
$env:CREATLAS_ASR_COMPUTE_TYPE = "float16"
$env:CREATLAS_ASR_BEAM_SIZE = "1"
$env:CREATLAS_ASR_VAD_FILTER = "true"
$env:CREATLAS_ASR_BATCH_SIZE = "4"

先用真实音频测量，再提高 Batch、Threads 或 Workers。代码会检查音频时长和文件大小，限制 ASR 并发与等待时间，并通过加载锁避免多个任务同时冷启动同一个模型。

没有本地音频缓存时，ASR 适配器会通过 yt-dlp 获取当前公开且已授权访问的视频音轨。下载 URL 会检查协议、主机和私网地址；失败时会清理 .part、.ytdl 和 .tmp 临时文件。转写会保存时间戳片段和模型、设备、精度、耗时、RTF 等运行指标。

数据保存在哪里

默认运行目录是 ~/.creatlas。可以用 CREATLAS_HOME 整体移动，也可以用 CREATLAS_CONFIG_FILE 指定其他配置文件位置。

~/.creatlas/
├── config.toml
├── creatlas.db
├── backups/
├── logs/YYYY-MM-DD.log
├── models/
├── browser/
├── credits/bilibili.json
└── artifacts/creators/{creator_id}/
    ├── contents/{content_id}/
    │   ├── metadata.json
    │   ├── transcript.json
    │   ├── summary.json
    │   ├── summaries/{summary_id}.json
    │   └── audio.*
    └── reports/
        ├── analysis-{run_id}.{json,md}
        └── latest.{json,md}

SQLite 保存领域记录、流水线状态、Job、同步游标、Claim、Evidence、Topic、全文索引和工件目录。音频、模型等大文件不会作为 BLOB 写进数据库，只保存相对路径和校验信息。

不要提交 .env、~/.creatlas/、Cookie、Token、数据库、模型或音频文件。

系统如何工作

普通用户只需要记住这条路径：

flowchart LR
    ADD["add：登记创作者"] --> ANALYZE["analyze：选择范围"]
    ANALYZE --> TRANSCRIPT["字幕或 ASR"]
    TRANSCRIPT --> SUMMARY["视频分析与摘要"]
    SUMMARY --> PROFILE["创作者画像与报告"]
    PROFILE --> ASK["ask：基于证据提问"]

实现上，CreAtlas 使用端口与适配器分层，让领域与应用逻辑不依赖 Bilibili UID、Cookie、浏览器对象或某个具体 LLM SDK。

flowchart LR
    UI["CLI / REST / Web"] --> APP["Application Services"]
    APP --> JOBS["SQLite Job Queue"]
    JOBS --> WORKER["Worker + Scheduler"]
    WORKER --> PIPE["Content Pipeline"]
    PIPE --> SOURCE["Bilibili Source"]
    PIPE --> TRANSCRIPT["Subtitle / Faster-Whisper"]
    PIPE --> LLM["LLM Router"]
    PIPE --> SEARCH["SQLite FTS"]
    APP --> DB["SQLite"]
    PIPE --> DB
    PIPE --> FILES["Artifact Store"]

每完成一条视频，批次进度都会持久化。正常完成或用户中止时，系统都会使用已完成部分提交创作者画像。若画像 LLM 失败，视频结果不会丢失；批次会保存确定性回退画像，并将报告标记为 partial。

更详细的实现边界见 架构说明、实现说明 和 CLI 参考。

开发与验证

后端检查：

python -m pytest -q
python -m ruff check src tests scripts
python -m ruff format --check src tests scripts
python -m compileall -q src scripts

前端检查：

Set-Location web
npm ci
npm run test
npm run build

发版步骤、Trusted Publishing 和本地审计命令见 发布指南。版本号只在 src/creatlas/__init__.py 定义，Python 包元数据和 FastAPI 会复用同一值。

仓库结构

src/creatlas/
├── domain/          # 领域模型与状态
├── ports/           # 外部依赖协议
├── application/     # Creator / Analyze / Job / Research 用例
├── pipeline/        # 可恢复内容流水线
├── llm/             # Provider、Profile、路由、分块与缓存
├── adapters/        # Bilibili / Browser / SQLite / LLM / ASR / Search
├── migrations/      # 随 Python 包发布的 Alembic 历史
├── api/             # FastAPI 应用与路由
├── cli/             # 产品命令与运维命令
└── workers/         # Worker / Scheduler

web/                 # React / Vite Web
tests/               # 离线回归与契约测试
scripts/             # 显式运行的检查和验收工具
docs/                # 架构、CLI 和发布文档

当前边界

v0.1 仍是本地优先、单节点的 MVP：

• 只实现 Bilibili，不包含多平台聚合；
• 不采集评论、弹幕或 OCR；
• 不包含向量数据库、Neo4j、Redis/Celery、Kafka 或 Kubernetes；
• 不包含 SaaS 多租户、完整权限系统或移动端；
• 浏览器 DOM 和旧 Web 接口可能受页面变化与平台风控影响；
• Open API OAuth 发起与 Token 自动轮换尚未实现。

后续工作见 TODO.md。

许可证

CreAtlas 使用 MIT 许可证。