d3dc620a71
- uv(workspace) + pnpm monorepo；docker-compose(pg+api+web) - SQLAlchemy 16 MVP 表 + Alembic 初版迁移(无漂移，users stub) - FastAPI 骨架：统一错误信封(带 request_id) + structlog + /jobs/:id + OpenAPI - Next.js 骨架：纸感主题 token + OpenAPI→TS 客户端代码生成(gen:api) - CI(ruff/mypy/pytest + pg service + alembic 漂移校验) - 四份设计规格(PRODUCT/UX/ARCHITECTURE/DEV_PLAN) + CLAUDE.md
159 lines
15 KiB
Markdown
159 lines
15 KiB
Markdown
# 网文创作工作流 · 开发计划（DEV_PLAN）
|
||
|
||
> 基于 [PRODUCT_SPEC.md](./PRODUCT_SPEC.md) / [UX_SPEC.md](./UX_SPEC.md) / [ARCHITECTURE.md](./ARCHITECTURE.md) 的分阶段实现计划。
|
||
> 子任务尽量**解耦**（只经契约耦合，可并行）；每个任务标注所需 **expert skill** 与**文档锚点**。
|
||
|
||
---
|
||
|
||
## 0. 锁定技术栈（本计划前提）
|
||
|
||
| 维度 | 决策 |
|
||
|---|---|
|
||
| 前端 | Next.js + TypeScript（纯 UI，OpenAPI 生成的 TS 客户端调后端） |
|
||
| 后端 | Python + FastAPI（async, SSE, Pydantic） |
|
||
| 编排 | **LangGraph**（写章→四审→验收 HITL/checkpoint/并行） |
|
||
| LLM 网关 | 薄自建：`anthropic` + `openai`(baseURL 覆盖 DeepSeek/Kimi/Qwen/GLM) + `google-genai`；缓存/降级/回退/记账自建 |
|
||
| 结构化输出 | Pydantic + `instructor` |
|
||
| ORM/迁移 | SQLAlchemy 2.0(async) + Alembic |
|
||
| 存储 | Postgres（**无向量**；确定性按需注入） |
|
||
| 长任务 | FastAPI BackgroundTasks + `jobs` 表（无专门队列） |
|
||
| 多租户 | **原型不做**（单用户 stub），后续再加 |
|
||
|
||
**原型不做（均为后续）**：多租户/Auth、向量检索(P2)、专门队列、全书扫描、社区市场。
|
||
|
||
---
|
||
|
||
## 1. 任务约定
|
||
|
||
格式：`Tx.y [skill] 标题` → 描述 · **依赖** · **DoD**(验收) · **锚点**(文档)。
|
||
|
||
**Skill 标签**（每任务调用对应 expert skill 编写）：
|
||
| 标签 | 职责 |
|
||
|---|---|
|
||
| `@devops` | monorepo/CI/docker/部署/迁移工具链 |
|
||
| `@db` | SQLAlchemy 模型、Alembic 迁移、Repository |
|
||
| `@backend` | FastAPI 端点、记忆服务、验收事务、BackgroundTasks |
|
||
| `@llm` | LLM 网关、适配器、LangGraph 图、Agent 声明 |
|
||
| `@frontend` | Next.js 页面、组件、流式渲染、TS 客户端 |
|
||
| `@qa` | 单元/集成/E2E、mock 网关、契约测试 |
|
||
| `@docs` | 文档修订 |
|
||
|
||
**解耦原则**：任务只经**契约**耦合（OpenAPI / Pydantic schema / `orchestrator`·`gateway`·`Repository` 接口）。**契约先行**——每阶段首个任务先定 schema/接口，随后 front/back/llm 并行。
|
||
|
||
---
|
||
|
||
## Phase 0 · 基建与架构栈修订
|
||
|
||
> 目标：可运行的空骨架 + 文档与锁定栈一致。
|
||
|
||
- **T0.1 [@devops] monorepo 骨架** → `apps/web`(Next/TS) + `apps/api`(FastAPI) + `packages/*`(python) + `docker-compose`(pg)。· 依赖 无 · DoD `docker compose up` 起 pg+api+web，根路由各返回 200。· 锚点 ARCH §2.2/§2.3
|
||
- **T0.2 [@db] 初始 schema + 迁移** → SQLAlchemy 模型(全部 **MVP 表**：9 张创作表 + `chapter_reviews` + `chapter_digests` + jobs/skills/provider_credentials/tier_routing/usage_ledger；**P2 表 `timeline`/`decisions` 不建**；**无向量**；users stub) + Alembic 初版迁移。· 依赖 T0.1 · DoD `alembic upgrade head` 一次建齐全部 MVP 表（含 `chapter_reviews`/`chapter_digests`，后续阶段不再加建表迁移，只加 Repository/约束）；模型↔迁移 CI 校验通过。· 锚点 ARCH §3.1
|
||
- **T0.3 [@backend] FastAPI 骨架 + 契约基建 + 可观测性底座** → 应用入口、`config`(提供商注册/档位默认/env)、统一错误信封(**带 `request_id`**)、OpenAPI 输出、`jobs` 轮询端点 `GET /jobs/:id`；**structlog 结构化日志 + 每请求 `request_id` 生成/透传中间件**（一次"写一章"= 一条贯穿 assemble→write→四审→accept 的 trace）。· 依赖 T0.1 · DoD `/openapi.json` 可取；错误信封统一且含 `request_id`；日志为 JSON 且每行带 `request_id`。· 锚点 ARCH §7.1/§7.4/§9.3
|
||
- **T0.4 [@frontend] 前端骨架 + 设计 token + 客户端代码生成** → Tailwind + 纸感 CSS 变量(UX §2)、`apps/web/lib/api` 由 `/openapi.json` 生成 TS 类型的管线。· 依赖 T0.1,T0.3 · DoD 主题 token 生效；改后端 schema 后 `npm run gen:api` 同步类型。· 锚点 UX §2 / ARCH §8.4
|
||
- **T0.5 [@devops] CI** → ruff+mypy+pytest（后端）、eslint+tsc+vitest（前端）、Alembic 校验。· 依赖 T0.1 · DoD PR 全绿才可合。· 锚点 ARCH §11
|
||
- **T0.6 [@docs] 架构栈修订** → 按计划清单回写 ARCHITECTURE+PRODUCT_SPEC（Python/FastAPI/LangGraph/无向量/无队列/单用户/OpenAPI 契约）。· 依赖 无 · DoD 两文档无残留 pgvector/队列/Node 后端/ts 代码块；三文档栈口径一致。· 锚点 全文 ✅(已完成)
|
||
|
||
---
|
||
|
||
## Phase 1 (M1) · 写章闭环骨架
|
||
|
||
> 目标：立项 → 写一章草稿（流式）→ 自动保存。**契约先行：T1.1 网关接口 + T1.4 API schema。**
|
||
|
||
- **T1.1 [@llm] LLM 网关接口 + 单 provider 适配器** → `gateway.run(LlmRequest)->LlmResponse`、`AsyncIterator[Delta]` 流；先实现 1 个 OpenAI 兼容适配器（如 DeepSeek）；档位路由读 `tier_routing`/默认；usage 回传；**每次调用按 §4.8 字段集落 `usage_ledger`**（成本账本从第一天起，带 `request_id`）。· 依赖 T0.2,T0.3 · DoD 单测：给 LlmRequest 得流式 token + usage；mock provider 可注入；一次调用产生一条 `usage_ledger` 记录。· 锚点 ARCH §4.1–4.3/§4.8/§9.3
|
||
- **T1.2 [@backend] 记忆服务 `assemble`（确定性选择）** → `select_relevant_entities`(显式+主角+近况) + `render_cards` + prompt 组装(稳定内核/易变 + 缓存断点)。· 依赖 T0.2 · DoD 单测：给定大纲/设定，输出确定且稳定块排序无时间戳。· 锚点 ARCH §3.4/§5.3
|
||
- **T1.3 [@llm] LangGraph 写章节点 + SSE** → 单节点图(write) + checkpointer(Postgres) + 流式输出归一为 SSE 事件(`token/done/error`)。· 依赖 T1.1,T1.2 · DoD 调用得流式草稿；图状态落 checkpoint。· 锚点 ARCH §5.2/§7.3
|
||
- **T1.4 [@backend] API：立项 + 写章** → `POST /projects`、`GET /projects`、`GET /projects/:id`、`POST /projects/:id/chapters/:no/draft`(SSE)、`PUT /projects/:id/chapters/:no/draft`(章节自动保存，写 `chapters` draft，见 ARCH §7.2)。· 依赖 T0.3,T1.3 · DoD 端点契约入 OpenAPI；`draft` 返回 SSE 流；`PUT draft` 幂等保存当前草稿。· 锚点 ARCH §7.2
|
||
- **T1.5 [@frontend] AppShell + 作品库 + 立项向导** → 顶栏/左导航(UX §5)、作品库卡片(UX §6.1)、5 步立项向导(UX §6.2)落 `projects` 字段。· 依赖 T0.4,T1.4 · DoD 可建作品并进入工作台。· 锚点 UX §5/§6.1/§6.2
|
||
- **T1.6 [@frontend] 写作工作台（核心）** → 三栏(目录/宋体正文编辑器/本章助手)、流式打字机、本章注入透明面板、自动保存(UX §6.3/§8.3)。· 依赖 T1.4 · DoD 选章→写本章→流式出草稿→自动保存。· 锚点 UX §6.3/§8.3
|
||
- **T1.7 [@backend] 提供商凭据管理** → 加密存储 `provider_credentials`、`GET/PUT /settings/providers`、`POST /settings/providers/test`(探测+能力矩阵)。· 依赖 T0.2,T1.1 · DoD Key 脱敏返回；测试连接通。· 锚点 ARCH §4.7 / UX §6.10
|
||
- **T1.8 [@frontend] 设置页（模型与提供商）** → 档位路由 + 凭据行(脱敏/测试连接/能力徽标)(UX §6.10)。· 依赖 T0.4,T1.7 · DoD 连一家 provider 后可写章。· 锚点 UX §6.10
|
||
- **T1.9 [@qa] M1 E2E** → 立项→写一章草稿(mock 网关)→自动保存。· 依赖 T1.5–T1.8 · DoD E2E 绿；网关用 mock 不烧 token。· 锚点 ARCH §11
|
||
|
||
---
|
||
|
||
## Phase 2 (M2) · 一致性 + 验收
|
||
|
||
> 目标：写→审(一致性)→裁决→验收（事务写回）。**契约先行：T2.1 审稿/冲突 schema。**
|
||
|
||
- **T2.1 [@llm] continuity Agent 声明 + 结构化输出契约** → `AgentSpec`(分析档) + 输出 `{conflicts:[{type,where,refs,suggestion}]}`(仅冲突；digest 改在验收时从终稿另提)。· 依赖 T1.1 · DoD 契约测试：mock 响应符合 schema。· 锚点 ARCH §5.1/§5.4
|
||
- **T2.2 [@llm] LangGraph 并行审 + review SSE** → write→并行分支(先 continuity)→collect(**落 `chapter_reviews` 留痕**)；review 端 SSE(`section/conflict/done`)。· 依赖 T1.3,T2.1 · DoD review 流式返回结构化冲突且入库可查。· 锚点 ARCH §5.2/§7.3
|
||
- **T2.3 [@db] 摘要/审稿留痕 Repository + 章节 version** → （表已在 T0.2 建好）`chapter_digests` 追加、`chapter_reviews` 写入、`chapters` 多 version 的 **Repository 逻辑 + 唯一约束**（不含新建表迁移）。· 依赖 T0.2 · DoD 单测：append 不覆盖；`(chapter, version)` 唯一。· 锚点 ARCH §3.1/§3.3
|
||
- **T2.4 [@backend] 验收事务 + 冲突 gate** → `POST /accept`(单事务：章节晋升 version + **从终稿提炼 digest** append + 裁决留痕 `chapter_reviews.decisions` + 占位 foreshadow/char 更新)；未决冲突拦截(`CONFLICT_UNRESOLVED`)；LangGraph HITL 恢复(checkpoint 仅控制流，正文/审稿以领域表为准)。· 依赖 T2.2,T2.3 · DoD 事务原子(失败全回滚)；digest 来自终稿非草稿；有未决冲突禁验收。· 锚点 ARCH §5.5/§7.1
|
||
- **T2.5 [@backend] review API + 历史** → `POST /projects/:id/chapters/:no/review`(SSE) + `GET .../reviews`(审稿历史)。· 依赖 T2.2 · DoD 契约入 OpenAPI。· 锚点 ARCH §7.2
|
||
- **T2.6 [@frontend] 审稿报告页 + 冲突裁决 + 验收 gate** → 审稿页(UX §6.4)、正文冲突就地波浪线/锚点、裁决(采纳/忽略/手改)、验收「本次将更新」清单，未决禁验收。· 依赖 T2.4,T2.5 · DoD 写→审→裁决→验收闭环。· 锚点 UX §6.4/§8.3
|
||
- **T2.7 [@qa] M2 E2E** → 写→审(一致性)→裁决→验收→摘要入库。· 依赖 T2.6 · DoD E2E 绿。· 锚点 ARCH §11
|
||
|
||
---
|
||
|
||
## Phase 3 (M3) · 伏笔 + 节奏
|
||
|
||
> 目标：伏笔账本/到期提醒/看板 + 节奏引擎 + 大纲。
|
||
|
||
- **T3.1 [@db] 伏笔表 + 状态机** → `foreshadow` 表 + 纯函数状态机(OPEN/PARTIAL/CLOSED/OVERDUE)。· 依赖 T0.2 · DoD 状态机单测覆盖全转移。· 锚点 ARCH §6.2 / PS §4.2
|
||
- **T3.2 [@backend] 到期扫描（BackgroundTask）** → 验收后触发扫描置 OVERDUE；登记/状态变更接口。· 依赖 T2.4,T3.1 · DoD 章号越界自动 OVERDUE。· 锚点 ARCH §6.2
|
||
- **T3.3 [@llm] foreshadow-analyst + pace-checker 节点** → 并入四审；genre 模板 DSL(存 `rules` genre 级)。· 依赖 T2.2 · DoD 四审齐全、结构化输出。· 锚点 ARCH §5.4/§6.2/§6.4
|
||
- **T3.4 [@llm] outliner Agent + 伏笔窗口** → 大纲节点；产出含 `foreshadow_windows`；接近回收窗口提示。· 依赖 T1.1 · DoD 生成分卷分章 + 窗口。· 锚点 ARCH §5.4 / PS §4.2
|
||
- **T3.5 [@backend] API：outline + foreshadow** → `POST /outline`、`GET /foreshadow?status=`。· 依赖 T3.1,T3.4 · DoD 看板数据可取。· 锚点 ARCH §7.2
|
||
- **T3.6 [@frontend] 伏笔看板 + 大纲编辑器 + 节奏报告** → 四泳道看板(UX §6.8)、大纲伏笔徽标(UX §6.7)、节奏节拍图(UX §6.4)。· 依赖 T3.3,T3.5 · DoD OVERDUE 琥珀提醒；节拍图渲染。· 锚点 UX §6.7/§6.8
|
||
- **T3.7 [@qa] M3 E2E** → 埋设→进展→逾期提醒；排大纲含窗口。· 依赖 T3.6 · DoD E2E 绿。· 锚点 ARCH §11
|
||
|
||
---
|
||
|
||
## Phase 4 (M4) · 文风
|
||
|
||
> 目标：学文风(指纹) + 漂移打分/回炉。
|
||
|
||
- **T4.1 [@backend] BackgroundTasks 长任务框架** → `jobs` 写入/进度/查询；`POST /style`(202+jobId)。· 依赖 T0.3 · DoD 长任务异步跑、进度可轮询。· 锚点 ARCH §7.4
|
||
- **T4.2 [@llm] style-auditor 双轨 + 并入第四审** → 提取(分析档,带原文证据)→`style_fingerprint`；漂移打分(轻量档)；**把漂移打分作为第四审并入 LangGraph review 并行分支与 review SSE**（补齐 continuity/foreshadow/pace 之外的第四审，对齐 ARCH §5.2「四审」）。· 依赖 T1.1,T2.2,T3.3 · DoD 指纹 16 维带证据；段落相似度分；review 图含四个并行分支、SSE 含文风漂移分项。· 锚点 ARCH §6.3/§5.2 / PS §4.3
|
||
- **T4.3 [@backend] API：style + refine** → `POST /style`(mode=update)、`POST /chapters/:no/refine`(回炉段)。· 依赖 T4.1,T4.2 · DoD 回炉返回新旧 diff。· 锚点 ARCH §7.2
|
||
- **T4.4 [@frontend] 文风页 + 漂移/回炉** → 样本上传+指纹+证据(UX §6.9)、漂移段标注、回炉 diff(UX §8.3)。· 依赖 T4.3 · DoD 学文风→写章漂移标红→一键回炉。· 锚点 UX §6.9/§8.3
|
||
- **T4.5 [@qa] M4 E2E** → 学文风→写章打分→回炉。· 依赖 T4.4 · DoD E2E 绿。· 锚点 ARCH §11
|
||
|
||
---
|
||
|
||
## Phase 5 (M5) · 生成 + 多 provider + 扩展
|
||
|
||
> 目标：世界观/角色生成 + 网关多 provider 韧性 + Skill/规则/命令面板。
|
||
|
||
- **T5.1 [@llm] worldbuilder + character-gen 节点** → 写手档；群像防雷同(注入已生成+已有)；编排器入库前追加 continuity 校验。· 依赖 T2.1 · DoD 批量产差异化角色卡、过校验。· 锚点 ARCH §6.5 / PS §4.5
|
||
- **T5.2 [@backend] 生成/入库 API** → `POST /world/generate`、`/characters/generate`、`POST /characters`(入库)。· 依赖 T5.1 · DoD 预览→入库→进入注入。· 锚点 ARCH §7.2
|
||
- **T5.3 [@frontend] 角色生成器 + 世界观设计器 + 设定库** → 生成模态(UX §6.6)、世界观设计器、设定库 Codex(人物/世界观/时间线, UX §6.5)。· 依赖 T5.2 · DoD 一句话生成→预览→入库；Codex 可管理。· 锚点 UX §6.5/§6.6
|
||
- **T5.4 [@llm] 网关多 provider 韧性** → 多适配器(Anthropic/Gemini/更多 OpenAI 兼容)、回退链 + 熔断 + 能力协商/降级（`usage_ledger` 记账已在 T1.1 落地，此处仅扩展多 provider 维度）。· 依赖 T1.1 · DoD 限流/不支持结构化输出时降级/回退；多 provider 记账分维度可查。· 锚点 ARCH §4.4–4.6
|
||
- **T5.5 [@backend] Skill 运行时 + 规则** → `skills` registry loader + 表权限沙箱(越权拒绝) + `POST /rules`。· 依赖 T0.2,T1.1 · DoD 自定义 skill 受表权限约束、产出经验收 gate。· 锚点 ARCH §5.6 / PS §5.5/§7
|
||
- **T5.6 [@frontend] 规则页 + 技能库 + 命令面板** → 规则管理、技能库、命令面板(⌘K)。· 依赖 T5.5 · DoD 加规则/调 skill/快捷跳转。· 锚点 UX §7
|
||
- **T5.7 [@qa] M5 E2E + 切 provider** → 生成群像入库；切换 provider 回归(降级/回退)。· 依赖 T5.3,T5.4 · DoD E2E 绿；切 provider 不破。· 锚点 ARCH §11
|
||
|
||
---
|
||
|
||
## 2. 阶段 DoD 矩阵
|
||
|
||
| 阶段 | 出口标准（Definition of Done） |
|
||
|---|---|
|
||
| Phase 0 | 骨架可起；全表迁移；CI 绿；文档与锁定栈一致 |
|
||
| M1 | 立项→写一章草稿(流式)→自动保存；连一家 provider |
|
||
| M2 | 写→审(一致性)→裁决→验收(事务)；未决冲突禁验收 |
|
||
| M3 | 伏笔账本/到期提醒/看板；大纲含回收窗口；节奏报告 |
|
||
| M4 | 学文风(指纹+证据)；漂移打分+回炉 |
|
||
| M5 | 世界观/群像生成入库；多 provider 回退/降级；Skill 沙箱 |
|
||
|
||
## 3. 任务 ↔ 文档锚点覆盖（抽样自检）
|
||
|
||
| 功能(PS §) | 任务 | UX/ARCH 锚点 |
|
||
|---|---|---|
|
||
| 立项 §6 | T1.4/T1.5 | UX §6.2 |
|
||
| 写章 §4/§6 | T1.2/T1.3/T1.6 | ARCH §5.2/§5.3 |
|
||
| 一致性 §4.1 | T2.1/T2.4/T2.6 | ARCH §6.1 |
|
||
| 伏笔 §4.2 | T3.1/T3.2/T3.6 | ARCH §6.2 / UX §6.8 |
|
||
| 文风 §4.3 | T4.2/T4.4 | ARCH §6.3 / UX §6.9 |
|
||
| 节奏 §4.4 | T3.3/T3.6 | ARCH §6.4 |
|
||
| 角色生成 §4.5 | T5.1/T5.3 | UX §6.6 |
|
||
| 多提供商 §3.3 | T1.1/T5.4 | ARCH §4 / UX §6.10 |
|
||
| 技能 §5.5 | T5.5 | ARCH §5.6 |
|
||
|
||
## 4. 后续（原型外，对应规格的 P2/后续标注）
|
||
|
||
- 多租户 + Auth（§9.1）：Repository 层加 `owner_id` 校验，接 Auth.js/OAuth。
|
||
- 向量检索（P2）：`select_relevant_entities` 接口后接 pgvector + 嵌入服务。
|
||
- 专门队列：BackgroundTasks → arq/Celery（接口不变）。
|
||
- 全书一致性回归扫描、社区 Skill 市场、夜读模式。
|