# 创作知识系统｜正式版施工文档

> 文档性质：施工文档。
> 目标：把当前本地 Demo 项目改造成“云端数据库 + OSS/CDN + acquisition -> decode_content -> pipeline -> app”的正式管道。
> 更新时间：2026-06-30。
> 本轮边界：本文记录正式版施工步骤；已完成的步骤会附执行记录，未完成的步骤仍按计划表述。
> 默认方案：在阿里云海外 lsh 开发机上新建 PostgreSQL 正式库；现有 Open AIGC PG/Greenplum 只作为上游分类树或历史连接，不作为本系统状态库。

## 0. 施工总原则

这次不是给旧 demo 打补丁，而是把主干改成正式工程。

核心原则：

- `main` 面向正式云端架构；旧本地数据和旧 demo 只由 `local-demo` 或归档路径负责。
- 本地 SQLite、`data/`、`legacy_data/` 不再是正式状态源。
- `creation_knowledge/` 不再作为正式顶层业务目录；其中可复用能力要迁到 `app/`、`decode_content/`、`acquisition/`。
- `创作知识提取-skill/` 是正式 skill contract，必须保留。
- 媒体正式链路统一以 OSS/CDN URL 为准，前端不再依赖本地 `/data/media/...`。
- 数据库先按可理解的业务对象建模，不在第一轮堆非常细的字段。

施工顺序不能反过来：先归档、再建云端状态源、再建本地模型和仓储、再迁 acquisition、decode、pipeline、app。

每个大步骤完成后，都要过一次“清理闸门”：

1. 查正式代码是否还引用旧入口。
2. 查测试是否还依赖旧路径。
3. 能删的从 `main` 移除。
4. 还需要回看的移到 `archive/` 或留在 `local-demo`。
5. 还没完全替代的，只能降级为 legacy shim，并在下一步清理清单里继续追踪。

## 1. 先清理与归档

### 1.1 先保留什么

这些目录和文件是正式版要继续用的资产：

| 保留对象 | 原因 |
|---|---|
| `core/` | 配置、LLM、Embedding、Prompt、PG 基建等共享底座 |
| `acquisition/` 主体 | 平台搜索、详情抓取、OSS、粗分类已经有真实代码 |
| `prompts/` | 创作闸、分类、读懂、scope normalize 等提示词仍被代码使用 |
| `tests/fixtures/` | crawler/search 离线测试仍依赖 |
| `创作知识提取-skill/` | 正式解构合同，不等于旧 `creation_knowledge/` 包名 |
| `app/frontend/src/` | 当前 Vite 前端已经迁为正式工作台起点 |

`acquisition/store.py` 已在第 6 步归档到 `archive/2026-06-30-step6/legacy_app/acquisition/store.py`；正式代码不能继续依赖它。

### 1.2 第一轮归档或删除什么

第一轮只动纯 legacy，不要急着拆核心业务代码。

建议从 `main` 移除或迁到归档位置：

- `web/index.html`
- `web/frameworks.json`
- `web/payloads.json`
- `web/runs/*`
- `scripts/serve_old_web.py`
- `scripts/rebuild_payloads.py`
- `scripts/import_to_db.py`
- `scripts/run_search.py`
- `.claude/launch.json`
- `数据接口与来源/captures/*`

本轮执行路径：已先迁到 `archive/2026-06-30-step1/`，不是直接物理删除；真实 `.env` 从 git tracking 移除，本地文件保留，提交 `.env.example` 作为模板。

处理方式：

- `web/*` 是旧单帖静态 demo 产物，正式前端不再使用。
- `scripts/serve_old_web.py` 只服务旧静态 demo，正式 API 不再需要。
- `scripts/rebuild_payloads.py` 与 `scripts/decompose.py` 里 payload 组装重复，后续统一到 `decode_content/payloads.py`。
- `scripts/import_to_db.py` 是本地 SQLite 迁移工具，正式版不再需要。
- `scripts/run_search.py` 是旧搜索和本地媒体链路，正式链路由 `run_acquisition.py` 替代。
- `数据接口与来源/captures/*` 是原始抓包证据，建议先外部归档，再从主干移除。

### 1.2.1 删除、归档、保留清单

这一节专门回答“到底删哪些文件和文件夹”。原则是：能确定只是旧 demo 产物的，先归档后从主干移除；还可能被正式链路复用的，先迁移能力，再删旧入口；真实数据、密钥和云端状态不跟代码一起删。

| 类型 | 对象 | 处理方式 | 说明 |
|---|---|---|---|
| 立即归档后从主干移除 | `web/index.html` | 移到 `archive/2026-06-30-step1/legacy_web/` | 根目录旧单帖静态 demo，不是正式前端 |
| 立即归档后从主干移除 | `web/frameworks.json` | 移到 `archive/2026-06-30-step1/legacy_web/` | 旧 demo 的本地 payload 展示数据 |
| 立即归档后从主干移除 | `web/payloads.json` | 移到 `archive/2026-06-30-step1/legacy_web/` | 旧 demo 的本地 payload 展示数据 |
| 立即归档后从主干移除 | `web/runs/*` | 移到 `archive/2026-06-30-step1/legacy_web/runs/` | 旧 demo run 结果 |
| 立即归档后从主干移除 | `scripts/serve_old_web.py` | 移到 `archive/2026-06-30-step1/legacy_scripts/` | 只服务旧静态 demo |
| 立即归档后从主干移除 | `scripts/rebuild_payloads.py` | 移到 `archive/2026-06-30-step1/legacy_scripts/` | 后续统一由 `decode_content/payloads.py` 负责 payload 组装 |
| 立即归档后从主干移除 | `scripts/import_to_db.py` | 移到 `archive/2026-06-30-step1/legacy_scripts/` | 本地 SQLite 导入工具，正式链路不用 |
| 立即归档后从主干移除 | `scripts/run_search.py` | 移到 `archive/2026-06-30-step1/legacy_scripts/` | 旧搜索入口，正式入口改为 `scripts/run_acquisition.py` |
| 立即归档后从主干移除 | `tests/test_legacy_paths.py` | 移到 `archive/2026-06-30-step1/legacy_tests/` | 测的是旧 demo 路径，不再代表正式验收 |
| 立即归档后从主干移除 | `.claude/launch.json` | 移到 `archive/2026-06-30-step1/local_agent/` | 个人本地 agent 配置，不进入正式工程 |
| 立即归档后从主干移除 | `数据接口与来源/captures/*` | 移到 `archive/2026-06-30-step1/data_interface_captures/` | 原始抓包证据保留为归档，不放主干活跃区 |
| 从 git 移除但本地保留 | `.env` | `git rm --cached .env`，新增 `.env.example` | 真实密钥不进入仓库 |
| Step6 已归档 | `acquisition/store.py` | 移到 `archive/2026-06-30-step6/legacy_sqlite/` | SQLite adapter 只供 local-demo/历史参考，正式代码不再依赖 |
| Step6 已归档 | `scripts/run_creation_search.py` | 移到 `archive/2026-06-30-step6/legacy_scripts/` | 旧 SQLite 采集 runner，正式入口改为 `scripts/run_acquisition.py` |
| Step6 已归档 | `acquisition/creation_search.py` | 移到 `archive/2026-06-30-step6/legacy_acquisition/` | 平台处理经验已迁到 adapters/media/classification/runner |
| Step5 已降级为 legacy/debug | `scripts/decompose.py` | 不删 | 正式能力已迁到 `decode_content/`，旧脚本只作调试入口 |
| Step6 已归档 | `creation_knowledge/` | 移到 `archive/2026-06-30-step6/legacy_creation_knowledge/` | API、读懂、媒体能力已迁到 `app/`、`decode_content/`、`acquisition/media/` |
| 保留 | `创作知识提取-skill/` | 永久保留 | 正式知识拆解合同层 |
| 保留 | `prompts/` | 保留 | 正式分类、闸门、读懂、scope prompt 仍使用 |
| 保留 | `tests/fixtures/` | 保留 | 离线测试证据 |
| Step6 已迁移 | `acquisition/web/app/` | 源码迁到 `app/frontend/`，旧 dist 归档 | 当前 Vite React 看板已成为正式前端起点 |

第二轮删除条件：

- `scripts/run_creation_search.py`：已在 Step6 归档。
- `acquisition/creation_search.py`：已在 Step6 归档。
- `acquisition/store.py`：已在 Step6 归档。
- `scripts/decompose.py`：已在 Step5 降级为 legacy/debug；正式 pipeline 不调用它。
- `creation_knowledge/`：已在 Step6 整体归档。

### 1.3 同步改哪些引用

删除或归档前必须同步处理引用：

- `scripts/decompose.py`
  - 旧 `web/frameworks*.json`、`web/payloads*.json` 写盘逻辑改成 legacy adapter。
  - 正式 decode 不再直接写 `web/`。
- `tests/test_legacy_paths.py`
  - 删除，或改成归档测试。
- `开发文档/产品文档.md`、`开发文档/技术文档.md`
  - 所有 `web/index.html`、SQLite、本地 JSON、`creation_knowledge` 作为正式入口的说法改成历史说明。
- `.env`
  - 从 git 移除。
  - 新增 `.env.example`，只保留键名和说明，不写真实密钥。
  - 真实 `.env` 只放本地或云机环境。

### 1.4 本步骤验收

- `git status` 只显示预期的删除、归档和新增文档。
- 没有正式代码继续引用 `web/frameworks.json`、`web/payloads.json`。
- 没有测试继续 import `scripts.serve_old_web`。
- `.env` 不再作为 tracked secret 进入后续提交。

## 2. 在云服务器新建正式数据库

### 2.1 云机事实

本地云机配置目录：

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

只读检查确认：

- 目录内有 `account.md` 和 `ali-denet.pem`。
- 云机可访问。
- 云端已有 repo：`/home/sam/Create-knowledge-find-decode`。
- 云端 repo 与本地 `main` 不完全同步，施工前必须以本地新分支或新提交为准重新部署。

安全要求：

- 不把云机 IP、账号、私钥、数据库密码写入仓库。
- 不把真实 `.env` 提交。
- 新库密码只放云机环境变量或安全密钥管理位置。

### 2.2 安装与初始化 PostgreSQL

施工动作：

1. 在云机安装 PostgreSQL server 和 client。
2. 新建数据库，例如：
   - `creation_knowledge_prod`
3. 新建应用用户，例如：
   - `ck_app`
4. 新建 schema，例如：
   - `creation_knowledge`
5. 只给应用用户访问该 schema 的必要权限。
6. 配置备份策略。
7. 配置远程访问策略：本地开发可以访问云端库，但不能开放无边界公网访问。

注意：

- 现有 `.env` 里的 `OPEN_AIGC_PG_*` 是上游 Open AIGC PG/Greenplum 配置，不要混用成本系统正式库。
- 正式库新增 `CK_DB_*` 配置。

建议新增环境变量：

```text
CK_DB_HOST=
CK_DB_PORT=5432
CK_DB_NAME=creation_knowledge_prod
CK_DB_USER=ck_app
CK_DB_PASSWORD=
CK_DB_SCHEMA=creation_knowledge
```

### 2.3 新增迁移文件

新增：

```text
db/migrations/001_creation_knowledge_schema.sql
```

第一版表不追求字段极细，先覆盖业务闭环。

建议业务对象：

| 对象 | 业务意义 |
|---|---|
| `query_batches` | 一批 query 的来源、目标、生成方式、状态 |
| `queries` | 单条 query 及其业务轴、是否保留、筛选原因 |
| `acquisition_runs` | 一次采集批次 |
| `acquisition_jobs` | 单条 query 在单个平台上的任务 |
| `candidate_items` | 候选帖子、文章、视频 |
| `media_assets` | 图片、封面、视频、原始 URL、OSS/CDN URL |
| `item_classifications` | 粗分类结果：是否创作知识、原因、模型版本 |
| `decode_jobs` | 单帖解构任务 |
| `decode_results` | 读懂文本、创作闸结果、拆颗摘要 |
| `knowledge_particles` | What/How/Why 知识颗 |
| `scope_results` | 作用域定位：实质、形式、感受、作用、意图 |
| `payload_drafts` | 待审核或待入库 payload |
| `ingest_records` | 入正式知识库记录 |
| `contract_snapshots` | skill、prompt、schema 版本快照 |

字段原则：

- 每张表都有业务 id、状态、来源、错误、创建时间、更新时间。
- 大型证据、原始平台回包、模型返回用 JSONB 保存。
- 媒体不要塞进 item 的字符串数组，拆到 `media_assets`。
- query 文本可能重复，正式 API 应优先用 query id。

### 2.4 本步骤验收

- 空库执行 migration 成功。
- migration 可重复执行或有明确版本记录。
- 本地通过 `CK_DB_*` 能连到云端正式库。
- 能写入一个 query batch、一个 query、一个 acquisition run。
- 不依赖 `CK_SQLITE_PATH`。

### 2.4.1 本步骤清理闸门

第二步完成后，重点不是删业务代码，而是防止云端施工副产物进入仓库：

| 对象 | 处理方式 | 说明 |
|---|---|---|
| 云机真实 `.env`、数据库密码、连接串 | 不进仓库 | 只放本地或云机安全路径 |
| SSH 私钥、云机账号文件 | 不进仓库 | 继续留在本机配置目录 |
| 数据库备份文件 | 不进仓库 | 只留云机备份目录 |
| 临时 SQL、psql 输出、连接测试日志 | 删除或外部归档 | 不作为项目源代码 |
| `OPEN_AIGC_PG_*` 配置 | 保留但降级用途 | 只用于上游分类树/历史连接，不再当本系统状态库 |
| `CK_SQLITE_PATH` | 不新增正式引用 | 旧 demo 可以继续用，正式代码不能继续接入 |

本步骤不删除 `acquisition/store.py` 和旧 SQLite runner，因为正式 repository 还没有接管业务流。

### 2.5 2026-06-30 执行记录

本步骤已真实在阿里云海外 lsh 开发机执行，记录非敏感事实如下：

- 已安装 PostgreSQL server/client，版本为 PostgreSQL 18.4。
- 已新建正式库 `creation_knowledge_prod`。
- 已新建应用角色 `ck_app`。
- 已新建 schema `creation_knowledge`。
- 已执行 `db/migrations/001_creation_knowledge_schema.sql`。
- migration 已重放验证，可以重复执行。
- `ck_app` 默认 `search_path` 已设置为 `creation_knowledge, public`。
- 云机上真实 `CK_DB_*` 写入 `/home/sam/.config/create-knowledge/creation_knowledge_prod.env`，权限为用户私有；仓库不保存密码。
- 本地 `.env` 已写入 `CK_DB_*`，通过 SSH tunnel 连接云端数据库；`.env` 已被 `.gitignore` 忽略。
- 云端 PostgreSQL 只监听本机地址，本地开发通过 SSH tunnel 访问，不开放无边界公网 5432。
- 已配置每日备份：`/usr/local/sbin/backup_creation_knowledge_pg.sh`，cron 位于 `/etc/cron.d/creation_knowledge_pg_backup`，备份目录为 `/var/backups/creation_knowledge`，当前策略保留 14 天。
- 已做本地写入回滚验证：可以通过应用用户写入 `query_batches`、`queries`、`acquisition_runs` 并回滚。

## 3. 本地建立模型、Schema、Repository

当前依赖已经有 `pydantic`、`psycopg2-binary`、`fastapi`，没有 SQLAlchemy/Alembic。第一版采用：

```text
SQL migration + Pydantic model/schema + psycopg2 repository
```

### 3.1 新建目录

新增：

```text
db/migrations/
app/
app/routes/
app/frontend/
acquisition/repositories/
acquisition/queries/
acquisition/platforms/
acquisition/media/
acquisition/classification/
decode_content/
decode_content/readers/
pipeline/
```

### 3.2 新建核心文件

新增：

| 文件 | 负责什么 |
|---|---|
| `core/db_session.py` | 正式 PG 连接、事务、读写边界 |
| `acquisition/domain.py` | Query、Run、Job、Item、MediaAsset、Classification |
| `acquisition/repositories/base.py` | AcquisitionRepository 接口 |
| `acquisition/repositories/postgres.py` | 云端 PG 实现 |
| `decode_content/models.py` | ReadResult、Knowledge、Scope、PayloadDraft |
| `decode_content/repository.py` | decode 结果、知识颗、payload draft 写库 |
| `pipeline/models.py` | PipelineRun、PipelineJob、Resume 状态 |
| `pipeline/repository.py` | pipeline 状态读写 |
| `app/schemas.py` | 前端 API 返回结构 |

`core/db.py` 保留给上游分类树读取。
`core/db_session.py` 负责本系统正式状态库。两者不要混在一起。

### 3.3 Repository 约定

正式业务代码只依赖接口，不直接操作 psycopg2 cursor。

`AcquisitionRepository` 至少提供：

- 创建 query batch。
- 读取待跑 query。
- 创建 acquisition run。
- 创建或更新 job。
- 写 candidate item。
- 写 media asset。
- 写 item classification。
- 查询 summary/detail 给前端。

`DecodeRepository` 至少提供：

- 领取待 decode item。
- 写 read result。
- 写 gate result。
- 写 knowledge particles。
- 写 scope results。
- 写 payload draft。

`PipelineRepository` 至少提供：

- 创建 pipeline run。
- 标记 step 状态。
- 记录失败和重试。
- 查询断点续跑位置。

### 3.4 本步骤验收

- 单元测试可用 fake repository 跑 acquisition/decode，不需要真实 DB。
- 集成测试可用临时 PG schema 跑 migration。
- 正式代码没有新增 SQLite 依赖。

### 3.4.1 本步骤清理闸门

第三步完成后，要清理的是“重复状态源”和“错误引用”，不是急着删旧业务能力：

| 对象 | 处理方式 | 说明 |
|---|---|---|
| 新正式代码里对 `acquisition.store` 的引用 | 必须删除 | 正式模型、repository、schema 不允许依赖 SQLite |
| 新正式代码里对 `CK_SQLITE_PATH` 的引用 | 必须删除 | 正式状态源只能走 `CK_DB_*` |
| `core/db.py` | 保留 | 仍用于上游 Open AIGC/分类树连接 |
| `core/db_session.py` | 保留 | 本系统正式状态库连接入口 |
| `acquisition/store.py` | 暂时保留为 legacy | 等 Step4/Step6 替代旧 runner/API 后再归档 |
| 只为新目录占位的空文件 | 保留或删除都可以 | 只要不误导为已实现业务即可 |

检查命令建议：

```text
rg "acquisition.store|CK_SQLITE_PATH|data/app.db" core acquisition decode_content pipeline app scripts
```

如果命中发生在 legacy 文件里，可以保留；如果命中发生在正式新模块里，必须改掉。

### 3.5 2026-06-30 执行记录

本步骤已完成第一版本地骨架，记录如下：

- 已新增 `core/db_session.py`，作为正式 `CK_DB_*` 云端 PostgreSQL 连接入口。
- 已在 `core/config.py` 新增 `CreationDbConfig`，明确区别于仍用于上游 Open AIGC 的 `PgConfig`。
- 已新增 `acquisition/domain.py`，覆盖 QueryBatch、Query、AcquisitionRun、AcquisitionJob、CandidateItem、MediaAsset、ItemClassification。
- 已新增 `acquisition/repositories/base.py` 和 `acquisition/repositories/postgres.py`，提供正式 acquisition repository 接口与 PostgreSQL 实现。
- 已新增 `decode_content/models.py` 和 `decode_content/repository.py`，先定义读懂、创作闸、知识颗、作用域、payload draft、contract snapshot 的模型与仓储合同，不迁移执行逻辑。
- 已新增 `pipeline/models.py` 和 `pipeline/repository.py`，先定义 orchestration/resume 的状态对象与仓储合同；是否新建 pipeline 专用表留到后续 migration 决策。
- 已新增 `app/schemas.py`，作为正式工作台 API DTO 起点。
- 已新增正式目录占位：`app/routes/`、`app/frontend/`、`decode_content/readers/`、`acquisition/queries/`、`acquisition/platforms/`、`acquisition/media/`、`acquisition/classification/`。
- 没有让正式代码新增 SQLite 依赖，旧 `acquisition/store.py` 仍只作为 legacy/local-demo adapter。
- 已用云端正式库做 repository 回滚验证：创建 query batch、query、run、job、candidate item、media asset、classification，查询 summary/detail 后 rollback。
- 当前未迁移 `scripts/decompose.py` 的旧 `web/` 写盘，也未修 `dim_attributes` 合同漂移；这些按计划留到 `decode_content/contracts.py` 与 `payloads.py` 阶段。

## 4. 改造 Acquisition

### 4.1 Query 生成与筛选

移动：

- `scripts/build_creation_demo.py` 核心逻辑 -> `acquisition/queries/builder.py`
- `acquisition/query_filter.py` -> `acquisition/queries/filter.py`

变化：

- 不再默认写 `data/queries/creation_demo.json`。
- 生成结果写入云端 `query_batches` 和 `queries`。
- 记录 query 生成方式、筛选结果、筛选 prompt 版本。

保留：

- 当前正交组合思路。
- `keep/reason/valid/relevant` 这类业务判断。

### 4.2 平台搜索与详情抓取

拆分：

```text
acquisition/platforms/base.py
acquisition/platforms/xiaohongshu.py
acquisition/platforms/weixin.py
acquisition/platforms/douyin.py
```

从现有文件迁移：

- `acquisition/search.py`
- `acquisition/crawler.py`
- `acquisition/creation_search.py` 中 `_process_xhs/_process_weixin/_process_douyin`

统一接口：

- `search(query) -> Candidate[]`
- `fetch_detail(candidate) -> PostLike`
- `normalize(raw) -> CandidateItem`

不要强行把三个平台字段抹平到失真：

- 小红书和微信偏图文/文章。
- 抖音偏视频，需要 account/cookie batch 和视频 URL。
- 平台差异进入 adapter 内部，业务层只看统一候选对象。

### 4.3 媒体转 OSS/CDN

移动：

- `acquisition/oss.py` -> `acquisition/media/oss_client.py`

新增：

- `acquisition/media/service.py`

正式行为：

- 小红书图片转 OSS/CDN。
- 微信图片转 OSS/CDN。
- 抖音视频转 OSS/CDN。
- DB 只保存媒体资产记录和 CDN URL。
- 不再把正式媒体写到本地 `/data/media/...`。

注意：

- 旧本地落盘只作为 local-demo 或测试辅助。
- 图文粗分类要支持直接使用 HTTP(S) 图片 URL。

### 4.4 粗分类

移动：

- `acquisition/classify.py` -> `acquisition/classification/coarse.py`

改造：

- 图文支持 CDN 图片 URL，不再依赖本地 `/data/...` 转 base64。
- 视频继续支持 CDN URL。
- 粗分类结果写 `item_classifications`。
- 记录模型、prompt 版本、失败原因。

### 4.5 Runner 与 CLI

新增：

```text
acquisition/runner.py
scripts/run_acquisition.py
```

替代：

- `scripts/run_creation_search.py`
- `acquisition/creation_search.py` 中直接操作 SQLite 的部分

正式 runner 做这些事：

1. 从云端读取 query batch。
2. 创建 acquisition run。
3. 为每条 query 和每个平台创建 job。
4. 搜索、详情、媒体转存、粗分类。
5. 写 candidate item、media asset、classification。
6. 更新 job 状态：pending、running、done、partial、failed。
7. 支持 resume 和 skip done。

### 4.6 本步骤验收

- 可以用一个 query batch 跑三平台 mock。
- 不创建 `data/app.db`。
- 不读取 `/data/queries/creation_demo.json`。
- item 媒体全是 CDN/OSS URL 或明确失败状态。
- 粗分类写入云端 DB。

### 4.6.1 本步骤清理闸门

第四步完成后，Acquisition 相关旧入口要分三类处理：

| 对象 | 本步骤处理方式 | 后续删除条件 |
|---|---|---|
| `scripts/build_creation_demo.py` | 保留为正式薄入口 | 不删；它已不再默认写本地 JSON |
| `acquisition/query_filter.py` | 保留为 shim | 等旧脚本全部改 import 后，可移除 |
| `scripts/run_acquisition.py` | 保留 | 正式采集 CLI |
| `acquisition/runner.py` | 保留 | 正式采集 runner |
| `scripts/run_creation_search.py` | 暂时保留为 legacy | 正式 API/前端不再读 legacy summary，真实 query batch 跑通后归档 |
| `acquisition/creation_search.py` | 暂时保留为 legacy/迁移来源 | 平台 adapter、media service、coarse classifier 的真实平台测试覆盖后归档 |
| `acquisition/store.py` | 暂时保留为 legacy SQLite adapter | API、runner、前端全不依赖 SQLite 后归档 |
| `scripts/classify_creation_items.py` | 暂时保留为 legacy 补判脚本 | 正式 item classification 重判脚本补齐后归档 |
| `data/queries/creation_demo.json` | 如果由新流程生成，删除或外部归档 | 正式 query batch 写云端 DB，不再靠本地 JSON |
| `data/media/*` 新增正式媒体 | 不允许新增 | 正式媒体进入 OSS/CDN 和 `media_assets` |

检查命令建议：

```text
rg "creation_demo.json|data/app.db|CK_SQLITE_PATH|acquisition.store" acquisition scripts app tests
```

正式新模块不应命中这些旧状态源；legacy 文件命中可以保留，但要在下一步继续追踪。

### 4.7 2026-06-30 执行记录

本轮已完成第一版 Acquisition 正式链路拆分，没有删除 legacy SQLite runner：

- 已新增 `acquisition/queries/builder.py`，承接原 `scripts/build_creation_demo.py` 的正交 query 生成核心。
- 已新增 `acquisition/queries/filter.py`，`acquisition/query_filter.py` 退为兼容 shim。
- 已将 `scripts/build_creation_demo.py` 改成薄入口：默认只打印摘要；只有显式 `--export-json` 才导出本地 JSON，只有显式 `--persist` 才写正式 PG。
- 已新增三平台 adapter：`acquisition/platforms/xiaohongshu.py`、`weixin.py`、`douyin.py`。
- 已新增 `acquisition/media/service.py`，统一把图片/视频转成可入库的媒体记录；OSS 失败时保留原 URL，不丢候选 item。
- 已新增 `acquisition/classification/coarse.py`，正式粗分类支持 HTTP(S) 图片 URL；同时补了旧 `acquisition.classify.classify_imgtext`，避免 legacy 补判在 CDN 图片下丢视觉输入。
- 已新增 `acquisition/runner.py` 和 `scripts/run_acquisition.py`，正式入口从云端 query batch 读取 query，创建 run/job，写候选 item、media asset、classification，并支持 skip done。
- 明确保留 `scripts/run_creation_search.py`、`acquisition/creation_search.py`、`acquisition/store.py` 为 legacy/local-demo 路径，本轮不改其 SQLite 语义。

交叉验证结论：

- Query 生成/筛选、平台/媒体/粗分类、正式 runner/CLI 三条 SubAgent 只读检查均确认：新链路应走 repository，不再从默认本地 query JSON 或 SQLite 取正式状态。
- 新增测试覆盖 fake repository 跑 acquisition batch、skip done、媒体 service、HTTP 图片粗分类、query batch 持久化合同、CLI 薄委托。
- 本地验证：`.venv/bin/pytest -q` 通过，`96 passed`；`.venv/bin/python -m compileall acquisition scripts core app decode_content pipeline tests` 通过；`git diff --check` 通过。

### 4.8 2026-06-30 清理闸门执行记录

按 Step1-4 清理闸门做了第二轮实际清理：

- 已删除本地运行产物：`runtime/`、空的 `web/runs/`、Python `__pycache__/`。
- 已把 `acquisition/platforms/weixin.py` 中对 `acquisition.creation_search._hash` 的依赖改为 adapter 内部实现，避免正式平台 adapter import legacy runner。
- 已将默认测试里的旧 SQLite/query demo/creation search 测试迁到 `archive/2026-06-30-step4/legacy_tests/`：
  - `tests/test_store.py`
  - `tests/test_creation_search.py`
  - `tests/test_query.py`
- 已保留 `tests/test_decompose_helpers.py`，因为 Step5 decode_content 迁移尚未执行，暂时仍需要它保护旧 decode helper 行为。
- 已脱敏 `db/README.md` 的 SSH tunnel 示例，不保留本机私钥绝对路径。
- 已把旧《产品文档》《技术文档》进一步标注为历史 demo 说明，避免继续把本地 JSON / 旧 `web/index.html` 写成正式入口。

本轮 SubAgent 交叉验证结论：

- Step1 原始 legacy 文件已不在原路径。
- Step2 未发现真实 DB 密码、私钥、psql 日志进入仓库；`.env.example` 只保留模板。
- Step3/4 正式 runner、CLI、query builder、repository 不读 SQLite、不读 `creation_demo.json`、不写 `data/app.db`。
- 仍按计划暂留为 legacy/迁移来源的文件：`acquisition/store.py`、`acquisition/creation_search.py`、`scripts/run_creation_search.py`、`acquisition/web_api.py`、`acquisition/web/app/`。这些会在 Step5/6 后继续清理。

## 5. 改造 Decode Content

改造前，读懂、创作闸、拆颗、作用域和 payload 主要压在 `scripts/decompose.py` 与 `creation_knowledge/integrations/`。

### 5.1 新建合同层

新增：

```text
decode_content/contracts.py
```

职责：

- 加载 `创作知识提取-skill/extraction/phase1-frame.md`。
- 加载 `phase2-scope.md`。
- 加载 `phase3-assemble.md`。
- 加载 schema、taxonomy、prompt。
- 计算合同版本 hash。
- 写入 `contract_snapshots`。

原则：

- 保留 `创作知识提取-skill/`。
- 不把它散落复制到别的目录。
- 每次 decode 都能追溯当时使用的合同版本。

### 5.2 读懂层

新增：

```text
decode_content/readers/imgtext.py
decode_content/readers/video.py
decode_content/readers/video_frames.py
decode_content/readers/service.py
```

迁移：

- `creation_knowledge/integrations/extractor.py` -> `imgtext.py`
- `creation_knowledge/integrations/video_extract.py` -> `video.py`
- `creation_knowledge/integrations/video_frames.py` -> `video_frames.py`
- `scripts/decompose.py::read_one` -> `readers/service.py`

正式行为：

- 输入：candidate item + media assets。
- 输出：read text、cards、media refs、is_empty。
- 不负责写 web 文件。
- 不负责 payload。

### 5.3 创作闸与质量闸

新增：

```text
decode_content/gates.py
```

迁移：

- `creation_gate`
- how admit/refute/tiebreak
- why refute

正式行为：

- 创作闸只看读懂结果，不靠标题关键词硬判。
- How 闸防止假流程。
- Why 轻闸只过滤空泛废话，不随意丢失信息。

### 5.4 拆颗与作用域

新增：

```text
decode_content/framing.py
decode_content/scoping.py
```

`framing.py` 负责：

- 调 phase1。
- 产出 What/How/Why 知识颗。
- 假 How 重拆。
- 受控值守卫。
- 组件颗 parent 校验。

`scoping.py` 负责：

- 调 phase2。
- 候选 scope。
- 名词化。
- 连接词拆原子。
- 调 `ScopeLinker`。
- 决定复用或新建。

### 5.5 Payload 组装

新增：

```text
decode_content/payloads.py
```

目标：

- 成为唯一 payload assembler。
- 取代 `scripts/decompose.py` 与 `scripts/rebuild_payloads.py` 的重复逻辑。
- 一颗知识生成一个 payload draft。
- payload 写入云端 `payload_drafts`。

同时修正合同漂移：

- 统一 `dim_attributes` 口径。
- 统一 How step 的 `input/directive/output`。
- What/Why content 统一为正式 ingest 接口可接受的字符串形态。

### 5.6 Decode Service

新增：

```text
decode_content/service.py
scripts/run_decode_content.py
```

`decode_content/service.py` 提供：

```text
decode_item(item_id) -> DecodeResult
```

它串起：

```text
load candidate -> read -> creation gate -> frame -> scope -> payload draft -> write db
```

`scripts/decompose.py` 最终只保留为 legacy/调试入口。

### 5.7 本步骤验收

- 用 fixture item 可以跑完整 decode。
- 每次 decode 都写 contract version。
- payload 组装只有一处实现。
- 不再从正式链路写 `web/frameworks.json`。

### 5.7.1 本步骤清理闸门

第五步完成后，Decode 相关旧入口要开始真正降级：

| 对象 | 本步骤处理方式 | 后续删除条件 |
|---|---|---|
| `scripts/decompose.py` | 改成 legacy/调试入口，或迁入归档 | `decode_content/service.py` 能跑完整 fixture 后归档 |
| `scripts/rebuild_payloads.py` | 保持归档，不再恢复到主干 | `decode_content/payloads.py` 是唯一 payload assembler |
| `creation_knowledge/integrations/extractor.py` | 迁到 `decode_content/readers/imgtext.py` 后归档 | 新 reader 测试通过且无正式 import |
| `creation_knowledge/integrations/video_extract.py` | 迁到 `decode_content/readers/video.py` 后归档 | 新 video reader 测试通过且无正式 import |
| `creation_knowledge/integrations/video_frames.py` | 迁到 `decode_content/readers/video_frames.py` 后归档 | 抽帧测试通过且无正式 import |
| 旧 `web/frameworks*.json` 写盘逻辑 | 删除 | 正式 decode 只写云端 decode/payload 表 |
| 旧 payload 组装函数副本 | 删除 | payload 逻辑只能留在 `decode_content/payloads.py` |

检查命令建议：

```text
rg "web/frameworks|web/payloads|creation_knowledge.integrations|rebuild_payloads" scripts creation_knowledge decode_content tests
```

正式链路里不允许再写旧 `web/` JSON；如果旧脚本还需要保留，只能明确标为 legacy。

### 5.8 2026-06-30 执行记录

本轮已完成 Step5 第一轮正式迁移：

- 新增 `decode_content/contracts.py`，集中加载 `创作知识提取-skill` 的 README、phase、schema、taxonomy、gate/normalize prompts 和 `scope_trees` cache 元信息，生成合同 hash 与 `ContractSnapshot`。
- 新增 `decode_content/readers/`，图文、整段视频、抽帧兜底 reader 已迁入正式包；正式 reader 入口支持 `CandidateItem + MediaAsset[] -> ReadResult`，不再依赖旧 `src["from"]`、本地 `/data/demo` 或 web JSON。
- 新增 `decode_content/gates.py`、`framing.py`、`scoping.py`、`payloads.py`、`service.py`，把创作闸、How/Why 质量闸、What/How/Why 拆颗、作用域定位、payload 组装和单帖 decode 编排拆到正式模块。
- `decode_content/payloads.py` 已统一正式 `dim_attributes`：`how工序 / what构成 / why原理`；What/Why content 按正式 ingest 边界输出字符串。
- `DecodeService` 每次 decode 会写合同快照；空内容或创作闸未通过会短路，只保存 read/gate/decode 状态，不生成 particles/payload drafts。
- 新增 `core/media_download.py`，把原来散在旧视频 reader 里的下载字节能力上提为共享工具；正式 acquisition/decode 不再 import `creation_knowledge.integrations`。
- 新增 `scripts/run_decode_content.py` 作为薄 CLI；正式 DB item 加载留到 Step6 pipeline/API 继续接。
- `scripts/decompose.py` 已标为 `LEGACY/debug`，保留旧 demo 调试能力，但不再作为正式链路。

本步骤清理结果：

- 已归档 `tests/test_decompose_helpers.py` 到 `archive/2026-06-30-step5/legacy_tests/`。
- 默认测试已迁到正式模块：`tests/test_decode_contracts.py`、`tests/test_decode_readers_service.py`、`tests/test_decode_payloads.py`、`tests/test_decode_gates_framing_scoping.py`、`tests/test_decode_service.py`。
- `tests/test_extractor.py`、`tests/test_video_extract.py`、`tests/test_video_frames.py` 已改为从 `decode_content.readers.*` 导入，继续保护 reader 行为。

交叉验证结论：

- SubAgent 确认 reader 不应继承旧 `src["from"]`、本地 `/data/demo`、reader 内 OSS 转存或 web 写盘行为；本轮已按 `CandidateItem + MediaAsset[]` 建正式 reader 输入。
- SubAgent 确认 `scripts/decompose.py::process_one/_run/write_run/main` 不应进入正式 service；本轮仅迁移业务能力，旧脚本保留为 legacy/debug。
- SubAgent 确认合同层要记录 phase/schema/taxonomy/prompt/scope cache 与漂移；本轮已在 `contracts.py` 记录正式常量与漂移说明。

本地验证：

```text
.venv/bin/pytest -q tests/test_decode_contracts.py tests/test_decode_readers_service.py tests/test_decode_payloads.py tests/test_decode_gates_framing_scoping.py tests/test_decode_service.py tests/test_extractor.py tests/test_video_extract.py tests/test_video_frames.py
23 passed
.venv/bin/pytest -q
84 passed
rg "creation_knowledge\\.integrations|web/frameworks|web/payloads|web/runs" decode_content tests scripts app pipeline acquisition -n
只剩 scripts/decompose.py 这个 legacy/debug 入口命中
```

## 6. 补 Pipeline 与正式 API

### 6.1 Pipeline

新增：

```text
pipeline/acquisition_runner.py
pipeline/decode_runner.py
pipeline/creation_pipeline.py
pipeline/dedupe.py
```

`creation_pipeline.py` 负责完整编排：

```text
query batch -> acquisition -> coarse classify -> decode candidates -> payload drafts -> ingest
```

`dedupe.py` 负责：

- 同平台同 source_id 去重。
- 跨 query 重复 URL 去重。
- 同 item 不重复 decode。
- 已 ingest payload 不重复写入。

Pipeline 必须记录：

- 当前 step。
- run/job 状态。
- 错误原因。
- 重试次数。
- 断点续跑位置。

### 6.2 正式 API

新增：

```text
app/api.py
app/routes/acquisition.py
app/routes/decode.py
app/routes/payloads.py
app/routes/runs.py
```

迁移：

- `creation_knowledge/api.py` 的 FastAPI 壳 -> `app/api.py`
- `acquisition/web_api.py` 的业务 API -> `app/routes/acquisition.py`

正式 API 替换：

| 旧接口 | 新接口 |
|---|---|
| `/api/creation-search/summary` | `/api/acquisition/runs/{run_id}/summary` |
| `/api/creation-search/query?query=...` | `/api/acquisition/runs/{run_id}/queries/{query_id}` |
| `/data/queries/creation_demo.json` | `/api/query-batches/{batch_id}` |
| `/data/media/...` | DB 中的 OSS/CDN URL |

API 原则：

- 不再默认挂本地 `/data`。
- 不再创建本地 media 目录。
- 不再每请求打开 SQLite。
- CORS 不再无脑 `*`，按部署环境配置。

### 6.3 前端

迁移：

```text
acquisition/web/app/src -> app/frontend/src
```

保留：

- query 列表页骨架。
- query 详情页骨架。
- 三平台候选展示。
- 创作知识/非创作知识分组思路。

改造：

- 去掉 `/data/queries/creation_demo.json`。
- 去掉 `/api/creation-search/*`。
- 改用正式 API。
- 增加 pipeline run 状态。
- 增加 decode 结果视图。
- 增加 payload draft / ingest 状态视图。

### 6.4 本步骤验收

- `uvicorn app.api:app` 能启动。
- 前端不再请求 `/data/queries/creation_demo.json`。
- 前端媒体全部来自 CDN/OSS URL。
- API 不依赖 SQLite。

### 6.4.1 本步骤清理闸门

第六步完成后，旧 API、旧前端和顶层旧包要进入最终清理：

| 对象 | 本步骤处理方式 | 后续删除条件 |
|---|---|---|
| `creation_knowledge/api.py` | 迁到 `app/api.py` 后归档 | `uvicorn app.api:app` 通过且前端改用正式 API |
| `acquisition/web_api.py` | 迁到 `app/routes/acquisition.py` 后归档 | 新 acquisition API summary/detail 测试通过 |
| `creation_knowledge/media.py` | 本步骤随旧顶层包归档 | 正式媒体只走 `acquisition/media/` 和 OSS/CDN |
| `creation_knowledge/` 顶层包 | 本步骤整体归档 | 无正式 import，API/reader/media 都已迁完 |
| `acquisition/store.py` | 本步骤归档 | 正式状态源改为 PostgreSQL repository |
| `acquisition/creation_search.py` | 本步骤归档 | 平台搜索、媒体、分类、runner 能力已拆到正式模块 |
| `scripts/run_creation_search.py` | 本步骤归档 | 正式采集入口改为 `scripts/run_acquisition.py` |
| `scripts/classify_creation_items.py` | 本步骤归档 | 后续补正式 repository-backed 重判脚本 |
| `scripts/filter_multiaxis.py` | 本步骤归档 | query 生成/筛选迁到 `acquisition/queries/*` |
| `acquisition/backfill_weixin.py` | 本步骤归档 | 旧 SQLite 补抓链路退出主干 |
| `acquisition/web/app/` | 迁到 `app/frontend/` 后归档旧位置 | 新前端能 build，且不再 fetch 本地 JSON |
| 根目录 `web/` | 删除空目录或保持归档说明 | 正式前端不再使用 |
| `/data` 静态挂载 | 从正式 API 删除 | 媒体和 query 都来自 DB/OSS/CDN |
| `/api/creation-search/*` | 删除或只在 legacy 服务保留 | 前端、测试、文档都改成正式 API |

检查命令建议：

```text
rg "creation_knowledge.api|acquisition.web_api|/api/creation-search|/data/queries|StaticFiles|CK_SQLITE_PATH" app acquisition pipeline tests
```

如果这一步后 `creation_knowledge/` 仍被正式代码引用，不能直接删；要先把最后的能力迁到 `app/` 或 `decode_content/`。

### 6.5 2026-06-30 执行记录

本步骤已按正式版方向落地第一轮代码改造：

- 新增 `app/api.py`、`app/dependencies.py` 和 `app/routes/*`，正式入口切到 `app.api:app`。
- 新增 acquisition 正式接口：query batch、run summary、query detail，不再走 `/api/creation-search/*`。
- 新增 decode、payload、pipeline run 的正式 API 占位路由，未接仓储的部分明确返回未实现，而不是伪装成已完成。
- 新增 `pipeline/acquisition_runner.py`、`pipeline/decode_runner.py`、`pipeline/creation_pipeline.py`、`pipeline/dedupe.py`，先把 acquisition 到 decode 的编排骨架接上。
- 前端从 `acquisition/web/app` 迁到 `app/frontend`，列表页和详情页改为读取正式 API。
- 前端不再请求 `/data/queries/creation_demo.json`，详情页媒体读取 item 里的 OSS/CDN URL。
- 根 `.gitignore` 的前端构建产物例外从旧路径切到 `app/frontend/dist/`。
- `creation_knowledge/api.py`、`acquisition/web_api.py` 归档到 `archive/2026-06-30-step6/legacy_api/`。
- 旧 `acquisition/web/app/dist` 归档到 `archive/2026-06-30-step6/legacy_frontend/`，旧 `acquisition/web/app` 空目录已清理。
- 顶层 `creation_knowledge/` 包整体归档到 `archive/2026-06-30-step6/legacy_creation_knowledge/`；`scripts/decompose.py` 这个 legacy/debug 入口改为引用 `decode_content/readers/*`。
- `acquisition/store.py`、`acquisition/creation_search.py`、`acquisition/backfill_weixin.py` 归档到 `archive/2026-06-30-step6/legacy_sqlite/` 与 `legacy_acquisition/`。
- `scripts/run_creation_search.py`、`scripts/classify_creation_items.py`、`scripts/filter_multiaxis.py` 归档到 `archive/2026-06-30-step6/legacy_scripts/`。
- `acquisition/classify.py` 保留为正式粗分类可复用的模型判定函数，但移除旧 SQLite 批处理入口。
- 旧本地 `/data` 媒体落盘测试归档到 `archive/2026-06-30-step6/legacy_tests/`。

本地验证：

```text
.venv/bin/pytest -q
90 passed

cd app/frontend && npm ci && npm run build
Vite build passed

rg "(/data/queries|/api/creation-search|/api/filter-prompt|CK_SQLITE_PATH|creation_knowledge\\.api|acquisition\\.web_api)" app pipeline tests
只剩 tests/test_app_api.py 里的反向断言命中
```

## 7. 测试计划

### 7.1 数据库测试

- migration 能在空库建表。
- migration 重跑有明确处理方式。
- 能插入 query batch、query、run、job。
- 能从 repository 查询 summary/detail。

### 7.2 Acquisition 测试

- 三平台 adapter 用 mock 回包测试。
- OSS client 解析 CDN URL。
- 媒体 service 能把图片/视频写成 media assets。
- 粗分类支持 HTTP 图片 URL 和视频 CDN URL。
- resume、skip done、partial、failed 状态可测。

### 7.3 Decode 测试

- 图文读懂离线测试。
- 视频读懂离线测试。
- 创作闸 admit/refute/tiebreak 测试。
- 假 How 重拆测试。
- 作用域复用/新建测试。
- payload draft 结构测试。

### 7.4 Pipeline 测试

- 从 query batch 到 acquisition run。
- 从候选 item 到 decode result。
- 从 knowledge particle 到 payload draft。
- 失败任务可重试。
- 已完成任务不会重复跑。

### 7.5 API 与前端测试

- API 合同测试不依赖 `CK_SQLITE_PATH`。
- API 合同测试不依赖本地 `/data`。
- 前端不再 fetch 本地 query JSON。
- 前端能展示 run、item、classification、decode、payload、ingest 状态。

### 7.6 Legacy 回归

- 删除旧 demo 后，不再有测试 import `scripts.serve_old_web`。
- `local-demo` 可作为旧数据回看来源。

### 7.7 每轮清理回归

每一轮改造结束，都要补一轮“反向测试”：确认正式路径没有重新长出旧依赖。

固定检查：

- 正式代码不 import `acquisition.store`。
- 正式代码不读取 `data/queries/creation_demo.json`。
- 正式代码不创建 `data/app.db`。
- 正式 API 不挂本地 `/data` 作为业务数据源。
- 前端不 fetch `/data/queries/*`。
- 新测试不再断言 legacy 路径是正式入口。

建议命令：

```text
rg "acquisition.store|CK_SQLITE_PATH|data/app.db|creation_demo.json|/data/queries|/api/creation-search|creation_knowledge.api" core acquisition decode_content pipeline app scripts tests
```

命中结果要分三类标注：

- `formal`：必须修掉。
- `legacy`：可以保留，但必须在文件或文档里说明。
- `archive`：不参与正式测试和运行。

### 7.8 2026-06-30 执行记录

本步骤已把测试计划落成一批可离线运行的正式回归测试，不连接真实云库、不读本地 SQLite、不依赖 `/data`：

- 新增 `tests/test_db_migration_contract.py`，检查正式 migration 包含 query、acquisition、decode、payload、ingest、contract snapshot 等业务表，且使用 PostgreSQL/JSONB/可重放写法，不退回 SQLite 形态。
- 新增 `tests/test_postgres_repository_contract.py`，用 fake repository 边界验证 `PostgresAcquisitionRepository` 的 summary、query detail、creation candidate 查询都走正式 PG 表和正式 domain model。
- 新增 `tests/test_platform_adapters.py`，用 mock 回包直接覆盖小红书、微信、抖音三平台 adapter 的 search/detail 映射。
- 新增 `tests/test_decode_stage_full_chain.py`，把 candidate item、media asset、decode service、skill contract、payload draft 串成一条最小离线闭环。
- 新增 `tests/test_legacy_cleanup_contract.py`，把正式源码不得依赖 SQLite、本地 `/data`、旧 API、旧 `creation_knowledge` 包的规则固化为测试；`scripts/decompose.py` 仅作为已标注的 legacy/debug 入口保留。
- 扩展 `tests/test_acquisition_runner.py`，覆盖 skip done、partial、failed 三类采集状态。
- 扩展 `tests/test_pipeline_formal.py`，覆盖 acquisition stage 成功/失败、decode stage 去重、完整 `creation_pipeline` 编排骨架。
- 扩展 `tests/test_app_api.py`，确认旧顶层 `creation_knowledge/` 已归档，活跃源码不 import legacy store/package；decode、payload、pipeline route 在仓储未实现时明确返回 501，且在注入正式仓储后存在成功返回路径，不伪装成旧本地数据接口。
- 继续保留前端 build 与 legacy 反向扫描作为每轮验收命令。

本地验证：

```text
.venv/bin/pytest -q tests/test_db_migration_contract.py tests/test_postgres_repository_contract.py tests/test_acquisition_runner.py tests/test_pipeline_formal.py tests/test_app_api.py
22 passed
```

仍然明确留到后续步骤：

- `decode_content`、payload、pipeline 的正式 PostgreSQL repository 实现。
- decode/payload/pipeline API 从 501 占位切到真实仓储读写。
- 真实云库集成测试或部署烟测，必须在有明确环境变量和测试库隔离后再执行。

## 8. 推荐提交顺序

建议拆成这些提交，降低风险：

1. `docs: add formal construction plan`
2. `chore: archive legacy static demo`
3. `chore: remove tracked env and add env example`
4. `feat(db): add cloud postgres migration and session`
5. `feat(acquisition): add domain and postgres repository`
6. `feat(acquisition): migrate query and platform adapters`
7. `feat(decode): add decode_content contract and readers`
8. `feat(decode): add framing scoping payload service`
9. `feat(pipeline): add cloud pipeline runners`
10. `feat(app): add formal api and migrate frontend`
11. `test: replace sqlite/local-data assumptions`

## 9. 风险与处理

| 风险 | 处理 |
|---|---|
| 云机 repo 与本地 main 不一致 | 施工前以本地新分支/新提交重新部署云机 |
| `.env` 已被 tracked | 先 `git rm --cached .env`，再补 `.env.example` |
| 旧 demo 删除影响回看 | 保留 `local-demo`，必要时外部归档 `web/*` |
| `creation_knowledge/` 迁移影响 import | 分阶段迁移，先加新模块，再替换 import，最后删旧包 |
| payload 合同漂移 | 先统一 `decode_content/contracts.py` 和 `payloads.py` |
| 图文分类依赖本地图片 | 改成支持 HTTP(S) 图片 URL |
| 云端数据库误用 Open AIGC PG | `CK_DB_*` 与 `OPEN_AIGC_PG_*` 明确分离 |

## 10. 最终验收

正式版完成后，应满足：

- 主干不依赖本地 SQLite。
- 主干不依赖 `legacy_data/`。
- 主干不依赖旧 `web/index.html`。
- 顶层正式业务目录不再使用 `creation_knowledge/`。
- 一个云端 query batch 可以追踪到 search、item、classification、decode、payload、ingest。
- 非创作知识候选不会进入深度 decode。
- 每个 payload 都能追溯到原帖、媒体、skill contract 版本和作用域定位。
- 前端默认进入正式工作台。
- 旧 demo 只通过 `local-demo` 或归档路径访问。

最终清理清单：

- 主干没有根目录旧 `web/index.html`。
- 主干没有旧 `web/frameworks.json`、`web/payloads.json`、`web/runs/*`。
- 主干没有正式代码使用 `acquisition/store.py`。
- 主干没有正式代码使用 `scripts/run_creation_search.py`。
- 主干没有正式代码使用 `scripts/decompose.py` 作为主入口。
- 主干没有顶层 `creation_knowledge/` 作为正式业务包。
- 主干没有真实 `.env`、数据库密码、云机私钥。
- 主干没有新产生的本地媒体、SQLite、query JSON 作为正式运行依赖。
