AI 灵感小说家

一个基于 Google AI Studio Build 模式生成、后续人工整理维护的 AI 辅助小说创作工具。

它覆盖了从灵感生成、题材确认、分卷规划、章节大纲，到正文续写、摘要同步和设定整理的完整流程。当前默认用户体验仍以前端本地模式为主，但仓库已经引入 server/ 后端原型、运行态治理层，以及可切换的后端真源边界。

项目定位

这个仓库更适合理解为一个“可继续维护的原型产品”，而不是已经工程化完成的商业项目。

适合的使用场景：

本地写作辅助工具
AI 协同创作 demo
作为后续产品化的基础版本

当前不包含的能力：

用户登录
云端同步
面向真实用户的线上账号体系、云端同步与托管服务
自动化测试体系的完整业务保障（目前只有治理验证脚本和单元级测试）
权限控制或多人协作

M1 后端骨架

M1 Task 1 已经把后端基础骨架和前端数据访问边界落到仓库里，但当前用户功能依然默认走本地实现。

infra/docker-compose.yml 提供本地 PostgreSQL + pgvector 开发容器
server/ 是独立的 Fastify + TypeScript 后端工作区
services/repositories/ 与 services/api/ 用于前端后续切换真源时的 repository / gateway 边界

本阶段的默认策略仍然是：

UI 继续读取浏览器本地数据
NovelRepositoryProvider 默认回退到 LocalNovelRepository
后端真源切换放到后续 M1 任务处理

M1 切换现状

当前仓库已完成 M1-TASK-009、M1-TASK-010、M1-TASK-011 与 M1-TASK-012 的 formal closeout：后端接口、知识中枢、proposal 审批链、写作检查、ingest MVP、最小知识控制台面板、主工作区 app-shell 接入，以及 Bookshelf ingest facade 收口都已回写到仓库；最新现场证据里 AI 生成分卷 和 WritingDesk -> AI 一键整章 保持绿色。当前 active governed task 已切到 M1-TASK-013，范围单独锁定为按 rollout checklist 执行 knowledge/materials 域验证与 closeout；这一步不会重开已关闭任务，也不会把后续域切换或写手学习器范围混进来。

但默认仍然是安全回退模式：

当 services/runtime/backendConfig.ts 中的 enabled 为 false 时，前端继续走本地仓库
当 enabled 为 true 时，NovelRepositoryProvider 会切到 ApiNovelRepository
Bookshelf / Brainstorming / OutlineBuilder / WritingDesk 的后端可见性增强也跟随这一开关生效

M1 不允许一次性全量切换。逐域切换顺序、验证门槛、回滚口都写在：

docs/10-product/API_SCHEMA_DRAFT_2026-04-10.md
docs/20-delivery/M1_ROLLOUT_CHECKLIST_2026-04-10.md

当前切换状态补充：

novels/chapters 已完成真实后端 smoke，列表、创建、元数据更新、正文保存、快照创建/恢复、删除都已验证
knowledge/materials 已进入当前受治理验证阶段：后端 routes、前端 knowledgeApi / materialApi、以及 WritingDesk 的知识/素材消费路径都已在代码里存在，但 domain-2 closeout 证据仍需按 checklist 补齐
proposals/events、writing context/checks、ingest jobs 仍需在 knowledge/materials 完成后按 checklist 顺序继续推进

当前明确仍未收口的 rollout / evidence 边界：

App.tsx 已停止直接调用 saveNovelToDB，顶层本地覆盖写入现在统一经由 NovelRepository.saveLocalOverlay(...)
WritingDesk.tsx 已停止直接导入 proposalApi / writingApi，当前后端写作编排已收口到 services/writingDeskBackendService.ts
当前运行页中的 Bookshelf / Brainstorming / OutlineBuilder / WritingDesk 已停止直接导入后端 client；页面层 API 编排收口已完成，测试里仍会按需 mock services/api/*
主工作区的 components/app-shell/ 现已正式接入：App.tsx 会渲染左侧导航、当前作品摘要和功能总览；当前这部分不再只是 worktree 草稿
services/writerProfileService.ts 仍然是静态写作预设，不是“喂小说学习”后的写手能力
当前下一缺口已被单列到 M1-TASK-013：按 rollout checklist 对 knowledge/materials 做单域验证与 closeout；其中必须按当前源码如实记录一条事实，Brainstorming 虽已有 material-save service 和 handler，但当前 render tree 并未确认接出可见的保存素材入口

本地开发如果需要让前端启动后直接读取后端真源，可以通过 .env.local 显式设置：

VITE_BACKEND_ENABLED=true
VITE_BACKEND_BASE_URL=http://127.0.0.1:3004
VITE_BACKEND_TIMEOUT_MS=10000

说明：

这是本地运行时开关，不会替代治理文档里的逐域切换规则
globalThis.__AI_NOVEL_BACKEND_CONFIG__ 仍然拥有更高优先级，可用于临时覆盖
修改 .env.local 后需要重启前端开发服务器

技术栈

React 19
TypeScript
Vite
@google/genai
浏览器 IndexedDB

说明：虽然工作目录名里带有“Vue Project”，但当前实现实际上是 React 项目。

核心功能

书架页管理本地小说作品
AI 生成小说灵感候选
灵感页支持“创意委托单”式输入，不再只靠单关键词
手动补充或修改书名、题材、核心设定
AI 规划分卷结构
AI 分批生成章节大纲
AI 续写章节正文
根据正文反向生成章节标题与摘要
从正文中提取角色 / 地点 / 规则等世界设定
长篇目标卡、剧情线和基础一致性检查
章节历史版本保存与恢复
本地备份与恢复小说库 JSON
从旧版 localStorage 数据迁移到 IndexedDB

名词边界

为避免后续需求和重构方向继续混淆，仓库内以下概念必须区分：

角色状态 / 角色卡片：指某一部小说内部的人物、剧情线、世界设定等知识状态面板；这是现有功能，保留，不删除
写作母版 / writerProfile：指当前代码里的静态写作风格预设；它能参与提示词，但还不是“喂小说学习”出来的写手
写手学习器：指未来新增的全局可复用能力，允许喂给系统一部或多部小说，学习文风、规则、叙事偏好，并沉淀参考片段库

后续产品方向按“两条能力并存”理解：

保留现有角色状态卡片，用于小说内部知识管理
另行新增写手学习器，用于跨作品复用的写作风格学习与参考检索
写手学习器边界说明见 docs/30-refactor/2026-04-14-writer-learning-boundary-note.md

快速开始

建议环境：

Node.js 20+
npm 10+

1. 安装依赖

npm install

2. 启动开发环境

npm run dev

默认地址：

http://localhost:3000

3. 打开页面设置

进入应用后，在以下任一位置打开 页面设置：

书架页右上角
写作页左上角

然后填写：

方案名称
AI 接口
API Key
模型名称
Base URL（Gemini 之外的接口可选）
推理强度（仅 OpenAI / Codex-Manager）

注意：

当前所有 AI 功能都统一读取“当前选中的方案”
现在支持保存多套方案，例如 方案1 / Gemini、方案2 / 硅基流动、方案3 / 本地 Codex-Manager
你可以在页面设置里随时切换当前使用方案
不再提供预设模型列表
填好 API Key 后，可以在设置弹窗里动态获取当前接口的模型列表并直接选择
不再要求通过 .env.local 提供运行时 Key

4. 打包

npm run build

5. 本地预览

npm run preview

6. 启动 M1 本地数据库骨架

docker compose -f infra/docker-compose.yml up -d postgres

7. 验证 `server/` 基础骨架

cd server
npm install
npm test

8. Provider 烟雾测试的本地 Key 约定

仓库默认不提交真实 provider key，但后续本地联调 / 烟雾测试可以继续使用固定文件路径：

本地真实 key 文件：docs/APIKEY.txt
仓库示例文件：docs/APIKEY.txt.example

约定说明：

docs/APIKEY.txt 只作为本地运行时输入，不应提交到版本库
.gitignore 已显式忽略这个真实文件路径
需要走真实 provider 的测试脚本时，继续从这个本地文件读取 key 即可
对话、日志、截图和治理文档都不应打印文件内的真实值

目录结构

.
├─ components/        UI 与主要交互流程
├─ services/          AI 调用与本地存储
├─ App.tsx            顶层状态流转
├─ index.tsx          应用入口
├─ types.ts           核心数据类型
├─ vite.config.ts     Vite 配置
├─ server/           后端原型和数据接口
├─ scripts/          工程与测试脚本
│  └─ governance/     治理验证与健康导出
└─ docs/
   ├─ README.md
   ├─ 00-governance/   稳定治理设计与治理方案
   ├─ 10-product/      产品、架构、接口与数据设计
   ├─ 20-delivery/     当前交付设计、计划、任务与 rollout 材料
   ├─ 30-refactor/     重构准备与重构计划
   ├─ 40-governance-history/
   ├─ 50-evidence/
   ├─ 60-automation/
   ├─ 99-local-runtime/
   └─ governance/      运行态治理入口、状态与索引

说明：

docs/governance/ 继续是运行态治理入口。
根目录历史文档与 docs/refactor/、docs/superpowers/ 当前仍保留兼容副本；新的链接应优先使用编号目录。

页面流程

应用主流程由 App.tsx 控制，共 4 个步骤：

BOOKSHELF
IDEA
OUTLINE
WRITING

对应关系：

书架页：管理作品、备份恢复、统一 AI 页面设置
灵感页：AI 生成创意或手动录入
大纲页：先做分卷，再做章节级规划
写作页：正文生成、摘要同步、设定维护、长篇辅助

数据存储

项目当前是“本地优先 + 可切换后端真源”的双模式存储：

默认本地模式：IndexedDB
backend-enabled 模式：novels/chapters 已可通过 repository 边界切到后端真源，IndexedDB 退化为缓存 / 备份 / 兼容层
历史兼容：启动时尝试从 localStorage 迁移
备份格式：JSON 文件导出 / 导入

这意味着：

默认本地模式下，清理浏览器数据仍会导致本地内容丢失
backend-enabled 模式并不等于“已经完成全域切换”，其余领域仍需按 rollout checklist 逐域验证
没有登录体系时，不同浏览器之间仍不会自动同步，同一台电脑也需要靠备份文件迁移数据

AI 相关说明

所有 AI 能力集中在：

services/aiConfigService.ts
services/geminiService.ts

当前支持：

Gemini
硅基流动
OpenAI / Codex-Manager

当前已经封装的能力包括：

灵感生成
分卷规划
分卷修改
章节大纲生成
章节大纲修改
正文生成
正文润色 / 修改
单章摘要生成
批量刷新摘要
世界设定提取
世界设定重建

Provider 说明：

Gemini 走 @google/genai
硅基流动 走 OpenAI 兼容 chat/completions
OpenAI / Codex-Manager 走 OpenAI 兼容 responses

如果你使用本地 Codex-Manager 网关，推荐配置方式通常是：

AI 接口：OpenAI / Codex-Manager
Base URL：http://localhost:48760/v1
模型：例如 gpt-5.4
推理强度：例如 high

说明：

模型列表会尝试从 /v1/models 动态拉取
正文生成、分卷、大纲、摘要、设定整理都会统一走 /v1/responses
reasoning effort 会跟随页面设置一起发送，适合 GPT-5 这类推理模型

当前提示词策略：

灵感阶段强调“结构化创意简报 + 明确差异化 + 长篇延展性”，避免只生成换皮创意
分卷阶段强调章节范围连续、卷目标明确、冲突逐卷升级
章节大纲阶段强调“本章推进了什么”，减少空泛氛围描述
正文生成阶段强调紧接上下文续写、具体场景推进、结尾留推进力
正文修改阶段强调尽量保留有效原文，只按用户意图做针对性增强
设定提取阶段只沉淀对后续创作有长期价值的角色与设定变化

灵感页这次升级后的输入维度包括：

关键词 / 必备元素
题材偏好
主角钩子
世界观 / 背景
核心冲突
情绪气质
目标读者
参考作品气质
避雷项 / 不想出现

灵感结果卡片这次会额外展示：

一句话钩子
主角身份与起始困境
核心冲突
世界观或机制新意
长篇升级路径
追更卖点

另外，AI 服务层现在会对部分结构化结果做基础归一化处理，例如：

分卷章节范围自动连续化
大纲与设定结果做基础字段清洗
统一要求 JSON 输出，降低模型跑偏对页面流程的影响

Governance

Repository governance starts at AGENTS.md.

AI workers and future maintainers should follow the governance documents under docs/governance/ before making code or architecture changes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AI 灵感小说家

项目定位

M1 后端骨架

M1 切换现状

技术栈

核心功能

名词边界

快速开始

1. 安装依赖

2. 启动开发环境

3. 打开页面设置

4. 打包

5. 本地预览

6. 启动 M1 本地数据库骨架

7. 验证 `server/` 基础骨架

8. Provider 烟雾测试的本地 Key 约定

目录结构

页面流程

数据存储

AI 相关说明

相关文档

Governance

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
components		components
docs		docs
infra		infra
scripts		scripts
server		server
services		services
.gitignore		.gitignore
AGENTS.md		AGENTS.md
App.test.tsx		App.test.tsx
App.tsx		App.tsx
README.md		README.md
index.html		index.html
index.tsx		index.tsx
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
types.ts		types.ts
vite-env.d.ts		vite-env.d.ts
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

AI 灵感小说家

项目定位

M1 后端骨架

M1 切换现状

技术栈

核心功能

名词边界

快速开始

1. 安装依赖

2. 启动开发环境

3. 打开页面设置

4. 打包

5. 本地预览

6. 启动 M1 本地数据库骨架

7. 验证 server/ 基础骨架

8. Provider 烟雾测试的本地 Key 约定

目录结构

页面流程

数据存储

AI 相关说明

相关文档

Governance

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

7. 验证 `server/` 基础骨架

Packages