Metadata-Version: 2.4
Name: creatlas
Version: 0.1.1
Summary: Evidence-backed creator intelligence and research engine
Author: 翔宇 龚
License-Expression: MIT
Project-URL: Homepage, https://github.com/augong0301/CreAtlas
Project-URL: Repository, https://github.com/augong0301/CreAtlas.git
Project-URL: Issues, https://github.com/augong0301/CreAtlas/issues
Project-URL: Changelog, https://github.com/augong0301/CreAtlas/blob/main/CHANGELOG.md
Keywords: creator-intelligence,research,asr,faster-whisper,bilibili
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.115
Requires-Dist: faster-whisper>=1.1
Requires-Dist: httpx>=0.27
Requires-Dist: nvidia-cublas-cu12==12.6.4.1; platform_system == "Windows" and platform_machine == "AMD64"
Requires-Dist: nvidia-cudnn-cu12==9.10.2.21; platform_system == "Windows" and platform_machine == "AMD64"
Requires-Dist: playwright>=1.48
Requires-Dist: pycryptodome>=3.21
Requires-Dist: pydantic>=2.7
Requires-Dist: qrcode[pil]>=7.4
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn>=0.30
Requires-Dist: yt-dlp>=2025.1.15
Provides-Extra: asr
Provides-Extra: asr-gpu-windows
Provides-Extra: browser
Requires-Dist: playwright>=1.48; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.0; extra == "release"
Dynamic: license-file

# CreAtlas

**简体中文** | [English](README.en.md)

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

在仓库根目录执行：

```powershell
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 时，先使用浏览器模式：

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

creatlas bilibili browser test <UID>
```

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

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

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

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

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

```powershell
$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，请改用：

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

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

### 5. 基于证据提问

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

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

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

## 常用命令

### 控制分析范围

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

```powershell
# 最新 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`：

```powershell
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` 仍保留为兼容入口。

### 重新总结一条已有转写

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

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

### 缩小研究范围

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

## 内容源怎么选

| 配置值 | 实际行为 | 什么时候使用 |
| --- | --- | --- |
| `browser` | 使用 Playwright 管理的 Edge/Chromium，或连接已有 CDP 浏览器 | 任意公开数字 UID；推荐的常规路径 |
| `open_api` | 使用 Bilibili 官方 Open Platform | 只处理应用已授权的账号 |
| `web` | 使用扫码登录后的旧 Web 接口 | 兼容路径，可能遇到 `-403`、`-799`、HTTP 412/429 |
| `auto` | 三项 Open API 凭据齐全时选 `open_api`；显式 Cookie 存在时选 `web`；否则选 `browser` | 默认值 |

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

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

```powershell
$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，再启动服务：

```powershell
$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：

```powershell
$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` 为准。主要路由包括：

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/health` | 健康检查 |
| POST / GET | `/api/v1/creators` | 注册 / 列出创作者 |
| POST | `/api/v1/creators/{creator_id}/sync` | 同步入队 |
| POST | `/api/v1/creators/{creator_id}/analyze` | 批量加入分析队列 |
| GET | `/api/v1/creators/{creator_id}/dashboard` | 查询仪表盘数据 |
| GET | `/api/v1/creators/{creator_id}/contents` | 筛选和分页查询内容 |
| GET | `/api/v1/contents/{content_id}/transcript` | 获取转写与指标 |
| GET | `/api/v1/contents/{content_id}/analysis` | 获取结构化分析 |
| POST / GET | `/api/v1/contents/{content_id}/summaries` | 生成 / 查询摘要 |
| POST | `/api/v1/contents/{content_id}/reprocess` | 从指定阶段重新处理 |
| POST | `/api/v1/research` | 提交带来源的研究问题 |
| GET | `/api/v1/jobs` | 查询 Job |
| POST | `/api/v1/jobs/{job_id}/retry` | 重试 Job |
| POST | `/api/v1/jobs/{job_id}/run` | 立即执行指定 Job |

## Docker Compose

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

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

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

```dotenv
CREATLAS_API_TOKEN=<刚生成的 Token>
```

再启动服务：

```powershell
docker compose up --build
```

| 服务 | 作用 | 本机端口 |
| --- | --- | --- |
| `migrate` | 一次性检查、备份并升级共享 SQLite | 无 |
| `api` | FastAPI | `127.0.0.1:8000` |
| `worker` | 持久化 Job Worker + Scheduler | 无 |
| `web` | Nginx 托管 React 并反向代理 API | `127.0.0.1:5173` |

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

## 配置规则

CreAtlas 按下面的优先级取值：

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

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

```powershell
# 查看最终生效的配置；凭据会脱敏
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` 下，可以执行：

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

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

## 配置 LLM

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

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

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

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

```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 可以从这组配置开始：

```powershell
$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` 指定其他配置文件位置。

```text
~/.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、数据库、模型或音频文件。

## 系统如何工作

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

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

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

```mermaid
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`。

更详细的实现边界见 [架构说明](docs/CreAtlas_v0.1_Architecture.md)、[实现说明](ARCHITECTURE.md) 和 [CLI 参考](docs/CLI.md)。

## 开发与验证

后端检查：

```powershell
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
```

前端检查：

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

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

## 仓库结构

```text
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](TODO.md)。

## 许可证

CreAtlas 使用 [MIT 许可证](LICENSE)。
