writer-work-flow/DEV_PLAN.md

网文创作工作流 · 开发计划（DEV_PLAN）

基于 PRODUCT_SPEC.md / UX_SPEC.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 市场、夜读模式。