docs: 新增 README + 服务器部署指南（含 compose 部署面缺口与安全红线）
This commit is contained in:
Yaojia Wang
157
README.md
Normal file
157
README.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 网文创作工作流（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）。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈（已锁定）
|
||||
|
||||
| 层 | 选型 |
|
||||
|---|---|
|
||||
| 前端 | **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](https://docs.astral.sh/uv/) · pnpm · Docker
|
||||
|
||||
```bash
|
||||
# 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:8000，文档 /docs）
|
||||
uv run uvicorn ww_api.main:app --reload
|
||||
|
||||
# 6. 起前端（另开终端，默认 http://localhost:3000）
|
||||
cd apps/web && pnpm dev
|
||||
```
|
||||
|
||||
或一键起全套（pg + api + web）：
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
|
||||
> **LLM API Key 不放 `.env`**：在应用设置页 **`/settings/providers`** 录入，密文存于数据库凭据库（用 `CREDENTIAL_ENC_KEY` 加密）。`.env` 里只有那把加密主密钥本身。
|
||||
|
||||
---
|
||||
|
||||
## 工具链 & 门禁
|
||||
|
||||
改动声明「完成」前须全绿（TDD 先红后绿，覆盖率 ≥ 80%）。
|
||||
|
||||
**后端**（仓库根）：
|
||||
|
||||
```bash
|
||||
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`）：
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test # vitest（范围 lib/**：纯逻辑 + hooks）
|
||||
pnpm build
|
||||
pnpm test:coverage # 覆盖率门禁（阈值 80%）
|
||||
```
|
||||
|
||||
**改过后端 schema** 后重生成 TS 客户端：
|
||||
|
||||
```bash
|
||||
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`](./PRODUCT_SPEC.md) | 是什么 & 为什么 —— 问题、功能（含 P0/P1/P2 优先级）、数据模型、端点、Agent | 理解范围或某功能 |
|
||||
| [`UX_SPEC.md`](./UX_SPEC.md) | 长什么样 —— 信息架构、用户流、页面线框、组件、视觉 token（纸感 / warm-cream 主题） | 做任何 UI |
|
||||
| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | 怎么实现 —— 完整 DDL、网关内部、编排引擎、API 契约、横切关注点 | 实现后端 / 数据 / 网关 |
|
||||
| [`DEV_PLAN.md`](./DEV_PLAN.md) | 按什么顺序 —— Phase 0–5，每个任务标注学科 skill | 挑下一个任务 |
|
||||
| [`PROGRESS.md`](./PROGRESS.md) | 交付到哪了 —— 权威状态台账 + 变更日志 | 开工前必读 |
|
||||
|
||||
冲突裁决：更具体 / 更靠后的文档为准（`ARCHITECTURE` > `UX_SPEC`/`DEV_PLAN` > `PRODUCT_SPEC`）。协作与开发规范见 [`CLAUDE.md`](./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。
|
||||
Reference in New Issue
Block a user