05 · 分阶段落地路线图

状态说明(2026-07):embedding / 向量库(Chroma)能力已整体移除——长上下文模型 让语义检索的必要性下降,且该链路本就长期降级(中转站 /embeddings 返回 403)。 长程一致性现全靠时序故事圣经 + 滚动摘要 + 最近章节。下文阶段 2 及"遗留项"中涉及 向量库/分桶记忆的条目为历史记录,保留但已不代表当前实现。

原则:每个阶段独立可跑、可验证,小步前进,不一次性铺大摊子。先把"控制层"(一致性、级联)在后端用脚本验证跑通,再上前端。

图纸总览见 00-overview.md;本文件是施工顺序,开工时照此推进。

---

阶段总览

阶段	名称	产出(验收标准)	依赖
0	地基	调通一次 LLM 请求	—
1	生成流水线 + 倾向拼装器	选倾向 + 输主题 → 生成完整大纲和章节目录	0
2	逐章生成 + 基础记忆	连续生成多章,基本连贯	1
3	长程一致性引擎 ★	20+ 章人设/伏笔不崩	2
4	大纲级联更新引擎 ★	改任一章大纲,系统提示下游影响并可一键对齐	3
5	润色引擎	整章/选段风格化润色,情节不变	2
6	Web 前端	标签选择器/大纲编辑器/流式生成/一致性看板/润色台	1-5
7	打磨	多模型路由/成本统计/导出/Docker/连 git 远程	6
8	多用户 + 移动端	JWT/邀请码注册/per-user LLM key/数据隔离；移动端适配	7

★ = 本项目的核心差异化价值,全网开源项目的空白区。

---

阶段 0 · 地基 ✅ 已完成(2026-07-18)

目标: 后端能跑起来,能调通一次大模型。

• [x] FastAPI 项目脚手架(目录结构见 01-architecture.md)
• [x] LLM 适配层:先接 DeepSeek 一家跑通(OpenAI/Gemini 留接口,后续补)
• [x] 配置管理(API key / base_url / 模型路由,借鉴 AI_NovelGenerator 的 config 分组)
• [x] 数据库模型定义(SQLite,按 02-data-model.md 建表;当时 11 张表,阶段 2/7/8 后增至 15 张)
• [x] 冒烟测试:scripts/smoke_test.py(5/5 通过)

验收: ✅ python -m app 起服务,/api/health 返回 200 + provider 状态; /api/ping-llm 在未配 key 时优雅报错(配 key 后可正常回复)。

落地实现(与图纸的偏差记录):

• /ping-llm 用 POST(带 prompt/provider body),不是 GET,比图纸更实用。
• 日志强制 UTF-8 输出,解决 Windows 控制台中文乱码。
• chromadb 暂未装(阶段 2 接向量库时再装),不影响阶段 0 启动。
• bash 工作目录不保持,后续命令统一用绝对路径 D:\my-projects\jarvis-write\backend。
• 运行说明见 backend/README.md。

---

阶段 1 · 生成流水线 + 倾向拼装器 ✅ 已完成(2026-07-18)

目标: 输入主题 + 选倾向 → 生成完整大纲和章节目录。

• [x] 移植成熟 Prompt(雪花法:种子→角色弧光→世界观→情节;借鉴 AI_NovelGenerator)
• [x] 章节蓝图分块生成(每块 20 章,携带前块尾部衔接)+ 宽容解析器(容错加粗/中英文冒号/顿号)
• [x] 倾向拼装器(见 04-tag-system.md):chips → 指令片段 → 注入 Prompt;支持自定义值、全局+临时两层作用域
• [x] 倾向预设配置文件 config/tag_presets.json(3 节点 10 维度 40+ chips)
• [x] 大纲/章节目录落库(含 content_hash 指纹 + OutlineVersion v1 快照,为阶段 4 级联打底)

验收: ✅ scripts/stage1_test.py 17/17 通过(mock LLM 全链路: 建项目→雪花四步→蓝图→解析→落库);阶段 0 冒烟回归 5/5。 真实 LLM 效果待用户配置 API key 后用同一链路验证。

落地实现(与图纸的偏差记录):

• 蓝图解析器输出格式在 Prompt 中显式约定(字段名与 outlines 表一一对应), 这是图纸没细化的部分,实现于 app/engines/pipeline/blueprint_parser.py。
• API:POST /api/projects、POST .../architecture、POST .../blueprint、 GET .../outlines、GET /api/tendency/catalog[/{node}]。

---

阶段 2 · 逐章生成 + 基础记忆 ✅ 已完成(2026-07-18)

目标: 能连续生成多章,读起来基本连贯。

• [x] 单章生成流程:上下文组装(本章+下章蓝图/最近2章结尾/滚动摘要/检索片段)→ 草稿 → 定稿
• [x] 向量库接入(Chroma,关 telemetry,不用内置 embedding,向量走 provider /embeddings)
• [x] 基础语义检索(单 collection,按章节窗口过滤,阶段 3 再分桶)
• [x] 滚动前情摘要(chapter_summaries 表,每章定稿后合并压缩)

验收: ✅ scripts/stage2_test.py 10/10(mock);真实生成《霓虹深渊》第 1-2 章 (5619/6970 字),跨章衔接自然:第 2 章正确延续伊芙夺权、莫罗猎杀、人物声口一致。

落地实现(与图纸的偏差记录):

• 用户中转站无 /embeddings(403) → 语义记忆自动降级(仅靠最近章节+滚动摘要), 生成不受阻。阶段 3 分桶记忆前需解决 embedding 来源(换支持 embeddings 的 key / 本地 embedding 模型)。
• 新增 _strip_meta 后处理:清理模型输出开头的 markdown 标题行。
• 推理模型空回复重试机制(base.ask:重试3次+翻倍 max_tokens)是本阶段前 发现的通用修复,记录于此。
• API:POST /api/projects/{id}/chapters/{n}/generate、GET .../chapters[/{n}]。

---

阶段 3 · 长程一致性引擎 ★ ✅ 已完成(2026-07-18)

目标: 写到 20+ 章,人设/伏笔/世界观不崩。三支柱落地(详见 03-engines.md)。

• [x] 时序故事圣经:事实绑 valid_from/valid_until,支持"第 N 章时角色状态"查询,支持别名识别、事实取代(旧事实自动关区间)
• [x] 章后状态抽取:LLM 严格 JSON 抽取(实体/事实变化/伏笔操作/认知更新)→ 写回圣经;宽容 JSON 解析(围栏/噪音容错);失败不阻塞生成
• [x] 伏笔调度器:四态流转 + 到期/逾期提醒(expected<=当前+2)+ 跨章模糊匹配
• [x] 一致性检查:定稿后 vs 圣经找矛盾,问题列表随 API 返回(不自动改,用户拍板)
• [x] 增强:重复用词检测(纯 Python n-gram,注入"避免清单");knowledge_states 认知分离(抽取已写,生成注入留阶段 6 看板一起完善)
• [~] 分桶加权记忆(6桶):已放弃并移除 —— embedding 来源长期无解(中转站 /embeddings 403),且长上下文模型让语义检索的必要性下降;整套向量记忆(Chroma + embedding)已删除,长程一致性由时序故事圣经 + 滚动摘要承担。

验收: ✅ scripts/stage3_test.py 19/19,含路线图指定案例(第5章受伤/第12章痊愈 → 查第8章=受伤);全量回归 46/46。真实运行:第1-2章补抽取(15实体/21事实/13伏笔, 跨章 reinforce 匹配正确);第3章带全引擎生成(1条事实被取代关区间、1条伏笔回收、 一致性检查零问题)。

落地实现(与图纸的偏差记录):

• 硬约束/伏笔提醒/避免重复三块注入草稿 Prompt(chapter.py);检查+抽取在定稿后运行。
• API:GET /api/projects/{id}/bible?chapter=N(时序快照)、GET .../foreshadowings (四态+到期)。生成接口返回 consistency_issues + extraction_stats。
• 老章节可"补抽取"(直接调 extract_and_apply),《霓虹深渊》第1-2章已补。

---

阶段 4 · 大纲级联更新引擎 ★ ✅ 已完成(2026-07-19)

目标: 改任一章大纲,系统分析下游影响,可一键对齐。这是没人做过的核心价值。

• [x] 大纲章节版本化(每次编辑/级联都存 OutlineVersion 快照,可回溯)
• [x] 改动分级:content_hash 短路无变化 → 规则粗筛(动情节字段疑似 major)→ LLM 精判;minor 不调 LLM 零成本
• [x] 影响分析:LLM 逐章判断下游依赖,输出 regenerate/review 分级建议;只分析不执行
• [x] 级联重生成:用户勾选后执行,最小侵入原则,越界章节拒绝,解析失败保留旧大纲
• [x] 正文失配标记:被改章节(含源章节)已有正文 → is_stale=true

验收: ✅ scripts/stage4_test.py 11/11;全量回归 62/62。 真实演示(《霓虹深渊》):第 4 章大改"露珠当场死亡" → 精判 major,概要准确 → 影响分析找出第 6/9/10 章依赖露珠存活(reason 引用了具体依赖情节),第 7 章 建议 review → 级联重生成 3 章,新大纲把"露珠死前塞的存储芯片"自然织入第 9/10 章, 旧的"露珠幸存觉醒"线全部清除,版本历史完整可回溯。

落地实现(与图纸的偏差记录):

• API:PUT /api/projects/{id}/outlines/{n}(编辑+分级)、POST .../outlines/{n}/impact、 POST .../outlines/cascade、GET .../outlines/{n}/versions。
• 分级失败时保守按 major 处理(宁可多提醒,不漏级联)。
• minor 改动也会标记本章正文 stale(正文毕竟和新大纲不完全符了)。

---

阶段 5 · 润色引擎 ✅ 已完成(2026-07-19)

目标: 整章或选段风格化润色,情节事实不变,去除 AI 味。

• [x] 整章润色(预览→确认→apply 写回)/ 选段润色(选中文本直接传)
• [x] 润色倾向标签(新增去AI味 chip;文艺/口语/画面感/张力/凝练/统一文风)
• [x] 硬约束锁情节:润色前 LLM 抽事实清单 → 润色时锁定 → 润色后 LLM 校验,违规报告给用户(不自动回滚)
• [x] 去 AI 味双管齐下:①去AI腔规则始终注入润色 Prompt(排比堆砌/造句定式/仿佛滥用/金句癖/情绪直喊/空洞升华);②纯规则 AI 味量化检测(每千字命中数),润色前后对比展示
• [x] AI 味独立检测接口(不调 LLM,秒回)

验收: ✅ scripts/stage5_test.py 11/11;全量回归 73/73。 真实润色《霓虹深渊》第1章选段:12 条事实锁定、零违规,文字明显收紧 ("像某种濒死的昆虫在铁皮盒里扑腾"→"像濒死的虫子";"还在,就说明今天还没死" →"还在。今天还没死。")。原文 AI 味本身很低(0.4/千字)——因为生成 Prompt 链路的质量好,这是好现象。

落地实现(与图纸的偏差记录):

• 去 AI 味是用户新增诉求(2026-07-19),已固化为:tag_presets 的"去AI味"chip + _DEAI_RULES 常驻规则 + ai_flavor.py 量化检测,三层。
• API:POST /api/projects/{id}/polish/chapter/{n}[/apply]、 POST /api/projects/{id}/polish/segment、POST /api/polish/segment、 POST /api/polish/ai-flavor。
• 单次润色限 12000 字,超长要求分段(防 token 超限截断)。

---

阶段 6 · Web 前端 ✅ 已完成(2026-07-19)

目标: 把后端能力可视化。

• [x] 项目管理(列表/新建,新建时用标签选择器设全局倾向)
• [x] 标签化倾向选择器组件(chips + 我要输入,单选/多选/自定义,大纲/正文/润色三节点复用)
• [x] 大纲编辑器(编辑 → 大改提示 → 影响分析 → 勾选级联重生成,全流程弹窗交互)
• [x] 逐章生成(阶段进度提示;真 token 流式推迟,见偏差记录)
• [x] 一致性看板:故事圣经"时间机"(选任意章看该时刻实体状态)+ 伏笔四态面板(到期高亮)
• [x] 润色工作台(选风格 → 预览 → AI味前后对比 + 事实违规提示 → 应用/放弃)

验收: ✅ 构建一次通过(TS strict);FastAPI 挂载 /app,根路径 307 重定向; 页面/静态资源/API 全 200;后端全量回归 73/73。 入口:**http://127.0.0.1:8000/**(前后端一个地址,无需单独起前端)。

落地实现(与图纸的偏差记录):

• 状态管理用 React hooks,未引入 TanStack Query/Zustand(当前规模不需要,后续膨胀再迁)。
• SSE 逐字流式推迟到阶段 7:章节生成是"草稿→定稿→检查→抽取→摘要"五段链, 真流式需后端逐段改造;当前用阶段文案+spinner 的长请求(15 分钟超时)替代。
• 路由用 HashRouter(静态挂载下刷新不 404,免配 fallback)。
• 构建产物由 FastAPI 静态托管(frontend/dist → /app),开发时 npm run dev 走 5173 代理。
• 原根路径 JSON 信息挪到 /api/info。

---

阶段 7 · 打磨 ✅ 已完成(2026-07-19)

• [x] git 初始化并推送远程:git@github.com:ynnyh/jarvis-write.git main 分支已推送(.gitignore 排除 .venv/db/chroma/.env/node_modules/dist)
• [x] Token 成本统计:llm_usage 表,base.ask 统一埋点(所有生成链路自动记账);GET /api/usage 汇总;前端顶栏实时显示累计用量
• [x] 异步生成 + 五段进度:POST .../generate-async → job_id,前端 3 秒轮询 /api/jobs/{id},实时显示"1/5 生成草稿 → … → 5/5 更新前情摘要"(替代原 10 分钟无反馈长请求)
• [x] 导出:txt(整本)/ epub(纯标准库 zip 打包,含目录 nav,结构校验通过)
• [x] Docker:多阶段 Dockerfile(前端 build → 后端运行时)+ docker-compose(数据卷持久化)。文件就绪,未实际构建验证(本机未确认 Docker 环境)
• [ ] SSE 逐 token 流式:用"异步任务+五段进度轮询"替代,体验已达标;真 token 级流式留待后续有需要再做
• [x] 多模型路由细化(quality/fast 分别指定配置):已落地为 cc-switch 风格多配置体系——设置页可存多套命名配置并各选「默认」(quality)与「快档」(fast);长生成失败自动重试 + 流式聚合兜底(治中转站 CDN 524 掐断)

验收: ✅ 全量回归 73/73;真实验证:txt 导出内容正确、epub 7 文件结构合规、 用量接口就绪、任务接口 404 语义正确、前端构建通过。代码已推送 GitHub。

---

阶段 8 · 多用户 + 移动端适配 ✅ 已完成(2026-07-19)

目标: 从单机单用户变成多账号可用,且手机上能用。

• [x] 用户体系:User 模型 + bcrypt 密码哈希 + JWT(HS256)登录态(app/auth.py);登录/注册接口
• [x] 邀请码注册:注册须填对固定共享码 INVITE_CODE,留空则关闭注册
• [x] per-user LLM key:provider_settings 加 user_id,每个账号在设置页配自己的 key;key 经 contextvar 从鉴权依赖贯穿到异步生成任务,不用层层传参
• [x] 数据隔离:projects / provider_settings / llm_usage 加 user_id 按用户过滤,跨账号访问 404
• [x] 启动迁移 app/migrate.py(幂等,不用 Alembic):旧表补 user_id 列、建初始 admin(ADMIN_USERNAME/ADMIN_PASSWORD)、存量无主数据归 admin
• [x] 前端:登录注册页 + token 注入(Authorization: Bearer)
• [x] 移动端适配:窄屏导航、双栏堆叠、按钮放大、iOS 防缩放
• [x] 部署收尾:docker-compose 改 named volume(jarvis_data → /srv/data)持久化 SQLite/Chroma;JWT_SECRET/ADMIN_PASSWORD 强制必填

已知推迟项(遗留/后续):

• 6 桶分桶加权记忆:已彻底移除(2026-07-24)。曾因中转站无 /embeddings(403)长期降级,评估后判定向量记忆非本项目命脉(长程一致性靠时序故事圣经这一确定性真相库),遂删除全部 embedding/Chroma 代码与依赖;长程上下文由"最近章节 + 滚动摘要 + 故事圣经硬约束"承担。
• SSE 逐 token 真流式:已用"异步任务 + 五段进度 3 秒轮询"替代,体验达标;真流式留待有需要再做
• 多模型路由细化(quality/fast 分 provider):已落地(cc-switch 风格多配置 + 默认/快档切换 + 重试与流式兜底)

阶段后增补(2026-07-28):

• [x] 生成质量增强:章节场景节拍(beats)、文风备忘(style_memo 随书累积)、创作初衷回注、任务分档采样温度、上游软错误识别
• [x] 翻新引擎:回填节拍 / 初始化文风备忘 / 轻度重润 / 重度重写四件套,失败保留进度可续跑(见 03 文档引擎 D)
• [x] 质感看板:章节地图附主审四维分 + AI 味指数

---

施工提醒

• 阶段 3、4 是核心价值,值得多花时间;阶段 1、2 尽量复用参考项目成熟实现,别在"生成文字"上重复造轮子。
• 每个阶段完成后,回填本文件的复选框,并在 docs/ 记录偏离设计之处,避免图纸与实现脱节。
• 借鉴来源已记录在各设计文档,开工前先读 00-overview.md 建立全局认知。