# 创作知识系统｜正式版开发文档

> 文档性质：正式版开发文档。
> 适用范围：后续在 `main` 上重构正式架构时使用。
> 更新时间：2026-06-30。
> 核心原则：正式版不沿用本地 SQLite、本地 `data/legacy_data`、旧 `web/index.html`，也不保留 `creation_knowledge/` 作为顶层业务目录名。当前代码只作为证据和迁移来源。

## 1. 正式定位

这个系统的正式定位是：

**创作知识发现、采集、判断与解构工作台。**

它不是普通爬虫，也不是把所有内容先下载入库再慢慢判断的本地 demo。正式版要从一个创作需求出发，生成或读取 query，跨平台召回真实内容，在采集阶段先做创作知识粗筛，再把高价值候选送入单帖解构，最终形成可入库的知识 payload。

这里的“创作知识”只收能指导“怎么想、怎么判断、怎么搭框架”的知识，不收器材、剪辑软件、调色、导出等制作执行知识。这个边界来自现有 `创作知识提取-skill`，后续目录可以改，但这个 skill contract 不能被降级或打散。

证据：`创作知识提取-skill/README.md:20-30` 定义只收创作、不收制作、一帖拆成 N 颗知识；`scripts/decompose.py:176-185` 已有创作判定闸。

## 2. 正式业务链路

正式版主链路是：

```text
query -> search -> detail/media -> coarse classify -> decode -> scope -> payload -> ingest
```

每一步的业务含义：

1. **query**：来自云端 query 批次或 query 生成服务，不再以本地 JSON 作为正式输入。
2. **search**：跨小红书、微信公众号、抖音等平台召回真实内容。
3. **detail/media**：补齐正文、图片、视频、作者、原链接和媒体可访问地址。
4. **coarse classify**：先判断候选是否像创作知识，非创作内容不进入重解构。
5. **decode**：对通过粗筛的候选做单帖读懂、创作闸和知识拆颗。
6. **scope**：定位实质、形式、感受、作用、意图等作用域。
7. **payload**：按 skill contract 组装可入库 payload。
8. **ingest**：写入正式知识库，并记录入库状态。

所以答案很明确：**正式版不需要、也不应该，把所有搜索结果先下载到本地 SQLite 之后再判断。**
采集阶段只保留必要详情和媒体地址，先粗筛；只有像创作知识的候选才进入深度 decode。

证据：`acquisition/runner.py:150-220` 已按 `query x platform` 创建 run/job 并执行平台采集；`acquisition/runner.py:91-146` 已写入候选 item、媒体和粗分类；`pipeline/creation_pipeline.py:23-66` 已把 acquisition 与 decode stage 串成正式编排骨架；`decode_content/service.py` 是正式单帖解构服务。

## 3. 正式目录结构

正式版目标目录不是当前目录的小修小补，而是下面这套结构：

```text
core/
  config.py
  llm.py
  embedding.py
  models.py
  prompts.py
  jsonio.py

acquisition/
  query 生成 / 筛选
  平台搜索
  详情抓取
  媒体稳定化
  粗分类
  候选 item 状态

decode_content/
  单帖读懂
  创作闸
  what/how/why 拆颗
  作用域定位
  payload 组装
  skill contract 版本记录

pipeline/
  query -> search -> classify -> decode -> payload -> ingest 编排
  run/job 状态
  断点续跑
  去重策略

scripts/
  run_acquisition.py
  run_decode_content.py
  run_creation_pipeline.py
  build_creation_demo.py

app/ 或 web/
  正式前端
  正式 API 入口
```

这意味着：`creation_knowledge/` 不应该作为未来顶层业务目录继续存在。Step6 后它已经从活跃源码树归档，原能力对应迁到新目录：

| 当前位置 | 当前职责 | 正式目标 |
|---|---|---|
| `archive/2026-06-30-step6/legacy_api/creation_knowledge_api.py` | 旧 FastAPI 壳，曾挂 `/app`、`/data`、`/frames` | 正式入口已迁到 `app/api.py` |
| `archive/2026-06-30-step6/legacy_creation_knowledge/creation_knowledge/integrations/extractor.py` | 旧图文/图片读懂 | 正式读懂在 `decode_content/readers/imgtext.py` |
| `archive/2026-06-30-step6/legacy_creation_knowledge/creation_knowledge/integrations/video_extract.py` | 旧视频读懂、分段卡片 | 正式读懂在 `decode_content/readers/video.py` |
| `archive/2026-06-30-step6/legacy_creation_knowledge/creation_knowledge/integrations/video_frames.py` | 旧视频帧能力 | 正式能力在 `decode_content/readers/video_frames.py` |
| `archive/2026-06-30-step6/legacy_creation_knowledge/creation_knowledge/media.py` | 旧本地媒体落盘工具 | 正式媒体稳定化在 `acquisition/media/service.py` |

`创作知识提取-skill/` 不等于 `creation_knowledge/`。前者是拆解方法合同，应该保留；后者是当前 Python package 名，正式版要改名和拆分。

证据：`app/api.py:29-49` 是正式 FastAPI 入口；`decode_content/readers/imgtext.py`、`decode_content/readers/video.py`、`decode_content/readers/video_frames.py` 是正式 reader；旧包已归档到 `archive/2026-06-30-step6/legacy_creation_knowledge/`。

## 4. 分层职责

### 4.1 `core`

`core` 是全系统共用能力层，只放配置、模型、LLM、Embedding、Prompt、JSON 读写等基础能力。它不应该表达 acquisition、decode 或 pipeline 的具体业务流程。

正式版要保留：

- 配置加载和环境区分。
- LLM JSON 调用和修复。
- embedding / 作用域定位基础能力。
- Post、Card、候选 item、decode result、payload 等共享模型。
- prompt 加载与版本记录。

证据：`core/config.py:43-90` 已承载 PG、爬虫、LLM、媒体目录等配置；`scripts/decompose.py:22-30` 已依赖 `core.config`、`core.llm`、`core.prompts` 和作用域 linker。

### 4.2 `acquisition`

`acquisition` 是候选发现层。它从 query 出发，找到真实内容，补齐可判断的信息，并产出候选 item。

正式职责：

- query 生成与筛选。
- 平台搜索。
- 详情抓取。
- 媒体稳定化，正式版以 OSS/CDN URL 为主。
- 粗分类，判断候选是否值得深度 decode。
- 向云端状态源写入 run/job/item/classification。

这里的粗分类不是最终知识入库，它只是为了避免把明显非创作内容送进昂贵的单帖解构。

证据：`acquisition/runner.py:16` 定义正式默认三平台；`acquisition/queries/builder.py` 与 `acquisition/queries/filter.py` 承接 query 生成和筛选；`acquisition/classification/coarse.py:76-130` 做粗分类；`acquisition/repositories/postgres.py` 负责把 run/job/item/classification 写入正式库。

### 4.3 `decode_content`

`decode_content` 是内容解构层。它把一个候选内容从“原帖/文章/视频”推进到“可入库知识颗”。

正式职责：

- 单帖读懂：图文、视频转成可追溯的文字、卡片和媒体索引。
- 创作闸：再次过滤制作、工具、纯展示和越界内容。
- What/How/Why 拆颗：一帖可以拆成 N 颗，三类知识对等。
- 作用域定位：定位实质、形式、感受、作用、意图。
- payload 组装：一颗知识对应一个 ingest payload。
- skill contract 版本记录：记录本次拆解用到的 phase/prompt/schema 版本。

这一层要从 `scripts/decompose.py` 抽出来，但不能改坏 `创作知识提取-skill` 的核心规则。

证据：`scripts/decompose.py:1-9` 明确一帖到 N 颗再到 payload；`scripts/decompose.py:102-156` 是图文/视频读懂；`scripts/decompose.py:487-511` 是闸门、拆颗、作用域和组装；`创作知识提取-skill/extraction/phase1-frame.md:11-28` 定义类型中立拆颗；`phase2-scope.md:1-14` 定义作用域定位；`phase3-assemble.md:1-5` 定义每颗一个 payload。

### 4.4 `pipeline`

`pipeline` 是正式编排层，负责把 acquisition、decode_content、ingest 串起来。

正式职责：

- run：一次 query 批次、采集批次或解构批次。
- job：一个 query x platform 采集任务，或一个候选 item decode 任务。
- resume：失败或中断后只补未完成任务。
- dedupe：跨 query、跨平台、跨 run 去重。
- gate：粗分类、创作闸、质量闸、人工审核闸。
- ingest status：payload 是否已入正式知识库。

当前代码已有云端 acquisition run/job 的第一版正式状态对象，但还没有完整 pipeline。文档要把 pipeline 写成目标架构，不要写成已完成事实。

证据：`db/migrations/001_creation_knowledge_schema.sql` 已定义正式 run/job 表；`acquisition/repositories/postgres.py` 已提供正式 repository；`acquisition/runner.py` 已串起 query batch、run、job、item、media、classification；`scripts/decompose.py:514-525` 仍是单独 query 搜索召回入口，尚未并入正式 pipeline。

### 4.5 `app` / `web`

正式前端与 API 已从旧 `creation_knowledge/api.py` 迁出。目标是一个正式工作台，不是旧静态 demo。

正式视图：

- Query 批次视图：query 组合方式、采集覆盖、粗分类命中。
- 候选 item 视图：来源、媒体、正文、分类原因、是否进入 decode。
- Decode 视图：单帖读懂、创作闸、What/How/Why 知识颗、作用域。
- Payload/ingest 视图：payload 审核、入库状态、失败重试。

当前 Vite React 看板已迁到 `app/frontend`，列表页和详情页改读正式 API。后续还要补 decode、payload、ingest 的完整审核视图。

证据：`app/api.py:38-49` 注册正式路由并托管 `app/frontend/dist`；`app/frontend/src/pages/CreationDemo.jsx:47-55` 读取 query batch 与 run summary；`app/frontend/src/pages/CreationQueryDetail.jsx:159-162` 读取正式 query detail。

## 5. 数据策略：正式版只认云端数据库

正式版不使用本地 SQLite 作为状态源，也不把本地 `/data`、`legacy_data` 当成默认输入输出。

正式数据库已经新建在“阿里云海外 lsh 开发机”上；本地环境配置目录是：

```text
/Users/samlee/Documents/工作环境配置/阿里云海外lsh开发机
```

该目录包含机器账号说明和私钥文件，属于本机环境配置，不进入仓库、不写入本文档细节、不提交到 git。

正式数据策略：

- query 批次进入云端数据库或云端 query 服务；当前第一版已支持写入云端 `query_batches` 和 `queries`。
- acquisition 写云端 run/job/item/classification。
- 媒体统一使用 OSS/CDN URL，前端直接消费 URL。
- decode_content 写云端 decode result、scope result、payload draft。
- pipeline 记录断点续跑、失败原因、重试次数和 ingest status。
- 本地 SQLite 只作为 `local-demo` 分支或历史回看手段，不进入 `main` 的正式架构。

当前代码里的 SQLite 只说明“旧实现怎么存过数据”，不再作为正式版设计对象。正式文档不再保留“SQLite 与本地数据”作为主章节。

证据：旧 SQLite adapter 已归档到 `archive/2026-06-30-step6/legacy_sqlite/store.py`；`core/config.py` 已区分 `PgConfig` 和正式 `CreationDbConfig`；`core/db_session.py` 是正式 PG 事务入口；`db/migrations/001_creation_knowledge_schema.sql` 已落正式状态表；`acquisition/repositories/postgres.py` 已实现正式 acquisition repository。

## 6. Legacy 边界

下面这些能力保留为历史证据或 local-demo 回看，不进入正式版默认路径：

- `archive/2026-06-30-step1/legacy_web/index.html`
- `archive/2026-06-30-step1/legacy_web/frameworks.json`
- `archive/2026-06-30-step1/legacy_web/payloads.json`
- `archive/2026-06-30-step1/legacy_web/runs/*`
- `archive/2026-06-30-step1/legacy_scripts/serve_old_web.py`
- `legacy_data/app.db`
- `legacy_data/media`
- `legacy_data/queries/creation_demo.json`

它们的意义是让旧 demo 可以回看，不是正式版要继续背负的架构。2026-06-30 第一轮归档后，旧静态页、旧脚本、旧抓包证据已经迁到 `archive/2026-06-30-step1/`；如果要继续使用旧 demo，就切回 `local-demo`。

证据：`archive/2026-06-30-step1/legacy_scripts/serve_old_web.py:1-6` 明确它是 legacy decompose demo；`archive/2026-06-30-step1/legacy_scripts/serve_old_web.py:46-66` 服务旧路径并监听 `127.0.0.1:8127`；`archive/2026-06-30-step1/legacy_web/index.html:370-376` 读取旧 `frameworks.json`、`payloads.json` 和 `runs` 产物。

## 7. 保留资产与不可破坏边界

可以大改目录、命名和编排，但不能破坏这些资产：

- `创作知识提取-skill`：保留为正式 skill contract。
- 三 lane 对等：How、What、Why 都是知识颗，不默认 How 是主角。
- 组件颗机制：What/Why 可独立成颗，也可作为 How 的组件颗回链。
- 作用域定位：五类作用域开放值，定位不上才新建。
- 平台 adapter 差异：小红书、微信、抖音的搜索、详情、媒体处理差异真实存在。
- 粗分类闸门：不是每条候选都进入深度 decode。
- run/job/resume：采集批次和任务状态是正式 pipeline 雏形。

证据：`创作知识提取-skill/README.md:24-30`；`创作知识提取-skill/extraction/phase1-frame.md:11-28`；`acquisition/platforms/base.py` 定义平台 adapter 合同；`acquisition/runner.py:150-220` 已按 query x platform 跑正式 run/job，并支持 `resume`、`skip_done`。

## 8. 第一轮重构路线

第一轮重构目标：**把目录、入口、数据源方向改对，同时保留可迁移组件。**

建议顺序：

1. **新建正式目录**
   - 建 `decode_content/`、`pipeline/`、`app/` 或正式 `web/`。
   - `core/`、`acquisition/` 保留但清理边界。
   - 不再新增 `creation_knowledge/` 下的业务代码。

2. **迁移 `creation_knowledge/`**
   - `api.py` 迁到 `app/api.py`。
   - `integrations/extractor.py` 迁到 `decode_content/readers/imgtext.py`。
   - `integrations/video_extract.py` 迁到 `decode_content/readers/video.py`。
   - `media.py` 的本地落盘逻辑退出正式主链路，媒体以 OSS/CDN URL 为准。

3. **替换状态源**
   - 不做新的 SQLite adapter。
   - 基于阿里云海外 lsh 开发机新建云端数据库。
   - 先定义云端 run/job/item/decode/payload/ingest 状态对象，再改 API 和 pipeline 读写。

4. **抽 `decode_content`**
   - 从 `scripts/decompose.py` 拆出读懂、创作闸、拆颗、作用域、payload 组装。
   - 保留 `创作知识提取-skill` 作为合同源，并记录版本。

5. **补 `pipeline`**
   - 先跑 `query -> search -> classify -> decode -> payload`。
   - 再接正式 ingest。
   - 每一步写云端 run/job 状态，支持断点续跑。

6. **升级工作台**
   - 当前 query 列表和详情页可迁入正式 app。
   - 去掉本地 query JSON 和 SQLite API 假设。
   - 增加 decode、payload、ingest 状态视图。

## 9. 验收标准

后续正式实现至少满足：

- 仓库主干不再依赖本地 SQLite 作为默认状态源。
- 顶层业务目录不再使用 `creation_knowledge/` 命名。
- 从一个云端 query 批次能追踪到 search、item、classification、decode、payload、ingest。
- 非创作知识候选不会进入深度 decode，或会被显式标记为跳过。
- 每个 payload 能追溯到原帖、媒体、skill contract 版本和作用域定位过程。
- 前端默认进入正式工作台，不进入旧 `web/index.html`。
- 旧 demo 与本地历史数据只通过 `local-demo` 或归档路径访问。

## 附录 A：代码证据索引

| 判断 | 证据 |
|---|---|
| 正式 FastAPI 入口已迁到 `app` | `app/api.py:29-49` |
| 旧 FastAPI 壳已归档 | `archive/2026-06-30-step6/legacy_api/creation_knowledge_api.py` |
| 正式图文读懂在 `decode_content/readers` | `decode_content/readers/imgtext.py:29-72`, `:91-120` |
| 正式视频读懂在 `decode_content/readers` | `decode_content/readers/video.py:54-100`, `:128-150` |
| 正式视频帧能力在 `decode_content/readers` | `decode_content/readers/video_frames.py:141-172` |
| 旧本地媒体工具已归档 | `archive/2026-06-30-step6/legacy_creation_knowledge/creation_knowledge/media.py` |
| 当前主业务 API 已换成正式 acquisition routes | `app/routes/acquisition.py` |
| 当前前端已迁到 Vite React 正式工作台 | `app/frontend/src/App.jsx`, `app/frontend/src/pages/CreationDemo.jsx`, `app/frontend/src/pages/CreationQueryDetail.jsx` |
| 列表页读取正式 query batch 与 run summary | `app/frontend/src/pages/CreationDemo.jsx:47-55` |
| 详情页读取正式 query detail | `app/frontend/src/pages/CreationQueryDetail.jsx:159-162` |
| acquisition 默认三平台 | `acquisition/runner.py:16` |
| acquisition 从云端 query batch 读取 keep query | `acquisition/runner.py:168-180` |
| acquisition 做图文/视频粗分类 | `acquisition/classification/coarse.py:76-130` |
| `query x platform` job 失败继续、done/partial/failed 收敛 | `acquisition/runner.py:188-275` |
| 正式采集脚本创建 run/job，支持 resume/skip-done | `scripts/run_acquisition.py`; `acquisition/runner.py:155-165` |
| 旧 SQLite 表只作为归档证据 | `archive/2026-06-30-step6/legacy_sqlite/store.py` |
| Open AIGC PG 连接基建仍主要用于分类树 dump | `core/db.py:1-4` |
| 正式状态库配置与事务入口已存在 | `core/config.py`, `core/db_session.py` |
| 单帖解构链路是一帖到 N 颗再到 payload | `scripts/decompose.py:1-9` |
| 图文/视频读懂链路 | `scripts/decompose.py:102-156` |
| 创作判定闸 | `scripts/decompose.py:176-185` |
| 作用域候选、名词化、定位、复用/新建 | `scripts/decompose.py:304-392` |
| payload 组装 | `scripts/decompose.py:395-467` |
| 单帖取数、读懂、闸、拆颗、作用域、组装主流程 | `scripts/decompose.py:470-511` |
| skill 是自包含提取合同 | `创作知识提取-skill/README.md:1-18` |
| 只收创作、不收制作 | `创作知识提取-skill/README.md:20-22` |
| 一帖 N 颗、三 lane 对等、作用域定位 | `创作知识提取-skill/README.md:24-30` |
| phase1 类型中立拆颗 | `创作知识提取-skill/extraction/phase1-frame.md:11-28` |
| phase2 只做作用域定位 | `创作知识提取-skill/extraction/phase2-scope.md:1-14` |
| phase3 每颗组装一个 payload | `创作知识提取-skill/extraction/phase3-assemble.md:1-5` |
| 旧静态页和旧 server 是 legacy demo | `archive/2026-06-30-step1/legacy_scripts/serve_old_web.py:1-6`, `:46-66`; `archive/2026-06-30-step1/legacy_web/index.html:370-376` |

## 附录 B：Legacy 本地数据说明

本地核验时间：2026-06-30。
核验对象：`legacy_data`。
用途：只用于证明旧 demo 曾经跑通过，不作为正式版输入、状态源或迁移前提。

| 对象 | 当前结果 |
|---|---|
| query family 数 | 15 |
| keep query 数 | 430 |
| `legacy_data/app.db` | 约 52MB |
| `legacy_data/media` | 约 5.4GB |
| `creation_search_runs` | 3 |
| `creation_search_jobs` | 1302 |
| job 状态 | `done=1162`, `partial=9`, `failed=131` |
| `creation_search_items` | 6009 |
| `creation_item_classifications` | 4290 |

这些数据不再进入正式架构设计。未来如需回看，切 `local-demo` 或访问归档数据；`main` 面向云端数据库和正式目录重构。
