64732b0d1b
审稿选章（列章端点 + 全章下拉 + 默认最近章） + 伏笔主动提醒（写作台本章伏笔）与 AI 写作时自动应用（写章上下文注入到期/逾期伏笔 + 提示词指令） + 宽屏留白优化（作品库 max-w-7xl 四列 / 正文 768px） + 主题切换水合报错修复 + AI 工作中动效强化（构思占位 / 流式进度条 / 波动三点 / 转圈） 门禁：前端 vitest 749 · lint/typecheck/build ✓；后端 pytest 1032 · ruff/mypy ✓。
网文创作工作流（Writer Work Flow）
AI 辅助的中文网文写作工作流，以 Web 应用形态交付。核心理念：把写长篇当软件工程做——先立架构（世界观 / 角色 / 大纲），对着规格逐章生成，每章写完即测（多维审查），全程维护单一真相源（数据库）。
作者不再让 AI「一口气瞎写十万字」，而是像写代码一样：需求（立项）→ 架构（设定库）→ 建模（角色卡）→ 接口（大纲）→ 实现（逐章生成）→ 测试（写完即审）→ 集成（验收更新全局状态）→ 回归（全书一致性）。AI 是「灵感增幅器 + 质检员」，作者始终掌控创意。
功能总览
- 引导式立项 — 一句灵感走向连载：选题材 / 基调 / 结局走向 / 叙事视角，AI 起草世界观、主角、金手指、总纲方案，一键建库。
- 设定库（Codex） — 结构化的单一真相源：
- 角色卡（外貌 / 动机 / 性格 / 背景 / 口癖 / 性格弧光 / 人物关系图）
- 世界观（力量体系 / 势力 / 地理 / 词条）
- 大纲 / 细纲 — AI 排分卷分章骨架，逐层细化到场景清单，并提示伏笔回收窗口。
- 写章（SSE 流式） — 注入设定 + 文风指纹，按 genre-aware 的网文写作教条（黄金三章、章末钩子、爽点密度）流式产出本章草稿。
- 五审（写完即审） — 一致性 / 伏笔 / 文风 / 节奏 四审 + 人物塑造（advisory 建议性）。审查器只读，不静默改稿。
- 验收事务（HITL） — 人在环中：作者裁决冲突后，唯一写入路径提交；未解决冲突阻断验收。章节摘要从最终已验收文本抽取，绝不污染真相源。
- 创作工具箱（15 个生成器） — 声明式 skill 框架，「加生成器 = 加一份声明」：脑洞 / 书名 / 简介 / 取名 / 金手指 / 词条 / 黄金开篇 / 细纲 / 续写 / 扩写 / 降 AI / 拆书，外加世界观 / 角色 / 大纲。
- 模板库 — 复用与沉淀常用创作模板。
- 多 Provider LLM 网关 — 路由 / 回退 / 熔断的自建薄网关；Agent 只声明能力 tier，网关按配置映射到 provider+model；支持 Kimi Code 订阅 OAuth（device flow）。
- 沉浸式写作体验 — 纸感暖色 + 夜读双主题（
data-theme切换）、写作台专注模式（隐藏侧栏加宽正文）、⌘K命令面板（跨页跳转 / 执行命令）、应用内帮助页/help（功能介绍 + 新手上手）。UI 对标编辑部式暖奶油设计语言，全程尊重prefers-reduced-motion与 WCAG AA。
技术栈（已锁定）
| 层 | 选型 |
|---|---|
| 前端 | Next.js + TypeScript（仅 UI；经 OpenAPI 生成的 TS 客户端调后端，无手写共享类型） |
| 后端 | Python + FastAPI（async，SSE） |
| 编排 | LangGraph（写→审→验收 图，Postgres checkpointer 可恢复） |
| LLM 访问 | 自建薄网关，覆盖 anthropic + openai（baseURL 兼容 DeepSeek/Kimi/Qwen/GLM）+ google-genai |
| 结构化输出 | Pydantic + instructor |
| ORM / 迁移 | SQLAlchemy 2.0（async）+ Alembic |
| 存储 | Postgres（原型不启用 pgvector） |
| 长任务 | FastAPI BackgroundTasks + jobs 表（原型不引入独立队列） |
工具链：uv（Python workspace，8 个成员）+ pnpm（前端）。Python 3.12+，Node 22。
快速开始
前置：Python 3.12+ · Node 22 · uv · pnpm · Docker
本地端口（宿主已 +1000，防与其他项目冲突）：前端 http://localhost:4000 · 后端 http://localhost:9000（API 文档
/docs）· Postgres localhost:6432。容器内部端口不变（3000 / 8000 / 5432），只改宿主发布端口；要改回默认各减 1000 即可。接线：前端apps/web/.env.local的NEXT_PUBLIC_API_BASE=http://localhost:9000指向后端；后端.env的CORS_ORIGINS放行http://localhost:4000、DATABASE_URL指向localhost:6432。
# 1. 克隆后，安装后端依赖（仓库根，uv workspace）
uv sync
# 2. 安装前端依赖
cd apps/web && pnpm install && cd ../..
# 3. 配置环境变量（CREDENTIAL_ENC_KEY 为必填的凭据加密 Fernet key，启动即校验）
cp .env.example .env
# 生产请重新生成：
# uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# 4. 起 Postgres 并跑迁移
docker compose up -d pg
uv run alembic upgrade head
# 5. 起后端 API（http://localhost:9000，文档 /docs）— 宿主端口 +1000
uv run uvicorn ww_api.main:app --port 9000 --reload
# 6. 起前端（另开终端，http://localhost:4000）— pnpm dev 已内置 -p 4000
cd apps/web && pnpm dev
或一键起全套（pg + api + web，宿主端口均已 +1000）：
docker compose up # web → :4000 · api → :9000 · pg → :6432
LLM API Key 不放
.env：在应用设置页/settings/providers录入，密文存于数据库凭据库（用CREDENTIAL_ENC_KEY加密）。.env里只有那把加密主密钥本身。
工具链 & 门禁
改动声明「完成」前须全绿（TDD 先红后绿，覆盖率 ≥ 80%）。
后端（仓库根）：
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy packages apps # 类型
uv run pytest -q # 单元 + 集成（需 pg：docker compose up -d pg）
uv run alembic check # 改过模型后校验无迁移漂移
uv run pytest -q --cov --cov-report=term-missing --cov-fail-under=80 # 覆盖率门禁
前端（apps/web）：
pnpm lint
pnpm typecheck
pnpm test # vitest（范围 lib/**：纯逻辑 + hooks）
pnpm build
pnpm test:coverage # 覆盖率门禁（阈值 80%）
改过后端 schema 后重生成 TS 客户端：
cd apps/web && pnpm gen:api
CI 见 .github/workflows/ci.yml（backend job 带 pg service 跑 ruff/mypy/alembic/pytest；frontend job 跑 gen:api/lint/typecheck/test）。
项目结构
apps/
api/ FastAPI 应用：路由 / service / 请求响应 schema / SSE 端点
web/ Next.js 前端：Server Components 读视图 + Client 编辑器/流式交互
packages/
shared/ 跨栈 Pydantic 契约 schema（前端经 OpenAPI 消费）
config/ 应用配置（Settings，环境变量边界）
db/ SQLAlchemy 2.0 模型 / Alembic 迁移 / Repository
llm_gateway/ 多 provider 网关：路由 / 回退 / 熔断 / adapter / 计费台账
agents/ 声明式 AgentSpec + 外置 prompt（Agent 只声明能力 tier）
core/ domain 领域逻辑 · memory 记忆真相源（确定性选择注入）· orchestrator LangGraph 图
skills/ 工具箱注册表 + skill 注册（声明驱动的生成器）
文档地图
四份 spec 分层，每层细化上一层；实现暴露的规格缺口须回写对应 spec。
| 文档 | 回答什么 | 何时读 |
|---|---|---|
PRODUCT_SPEC.md |
是什么 & 为什么 —— 问题、功能（含 P0/P1/P2 优先级）、数据模型、端点、Agent | 理解范围或某功能 |
UX_SPEC.md |
长什么样 —— 信息架构、用户流、页面线框、组件、视觉 token（纸感 / warm-cream 主题） | 做任何 UI |
ARCHITECTURE.md |
怎么实现 —— 完整 DDL、网关内部、编排引擎、API 契约、横切关注点 | 实现后端 / 数据 / 网关 |
DEV_PLAN.md |
按什么顺序 —— Phase 0–5，每个任务标注学科 skill | 挑下一个任务 |
PROGRESS.md |
交付到哪了 —— 权威状态台账 + 变更日志 | 开工前必读 |
冲突裁决：更具体 / 更靠后的文档为准（ARCHITECTURE > UX_SPEC/DEV_PLAN > PRODUCT_SPEC）。协作与开发规范见 CLAUDE.md。
测试与原型边界
- 测试：TDD 强制（先写失败测试）；三层——单元（一个节点/函数/Repository，mock IO）→ 集成（FastAPI 端点 + DB + mock 网关）→ E2E（写→审→验收，mock 网关）。所有测试一律 mock LLM，绝不命中真实 LLM API。覆盖率门禁 ≥ 80%。
原型作用域，以下明确不做（勿误用于生产）：
- 单用户，无 auth / 多租户 ——
users/owner_id为占位桩。 - 无向量检索 / pgvector —— 记忆注入是确定性按需选择（显式点名 + 主要角色 + 最近 N 章），非向量搜索（向量检索列 P2）。
- 无独立任务队列 —— 长任务走 FastAPI BackgroundTasks +
jobs表。 - 不做模型微调、内容分发 / 发布平台对接、移动原生 App。