独立的本地作者工作台。支持 TXT / 原小说项目 JSON → 选择章节与玩家身份 → 游戏草稿 → 校验发布 → 文字试玩与存档。网页与 MCP 使用同一套应用服务、SQLite 数据和校验规则。
当前可选择开放冒险与分支故事。开放冒险以有限地点和建议行动推进，支持人物知识、行动条件、持续后果、时间事件与不同结局。自由文本行动、完整数值 RPG、冒险经历转小说尚未实现。玩家循环与单局成功定义见 docs/player-loop.md。
分支故事支持数值、字符串和布尔变量：作者可设置初值，为选项添加相等/数值阈值条件，以及赋值/数值增减效果。试玩只显示当前满足条件的选项，行动后自动保存变量；重试同一请求不会重复增加数值。工作台界面支持中文与 English，语言选择保存在浏览器；切换语言不会改写小说或游戏正文。
原作书架、制作任务、世界/分支编辑器、建筑/物品库、两种试玩和模型设置统一到 Agent 工作台。新增 Ctrl/Cmd+K 搜索真实资料、草稿和任务；各页可准备带当前上下文的 Agent 讨论请求，编辑后发送。任务支持状态和关键词过滤，书架优先展示已有资料，高级编辑工具按需展开；切换页面保留输入，搜索打开草稿也遵守未保存检查。修复 #play 作者试玩与 #/play 玩家入口的冲突。详见改版验收记录。
“改编生成”新增设定/角色入口，默认提供《武林外传》白展堂测试简报：先审阅人物和可执行玩法，再逐段生成正文，保存断点并自动体检与快速模拟。可附意见只修订单段，生成新草稿并保留原稿。仍可切换原作快速改编。2026-10-29已用DeepSeek完成首个真实生成与作者审改测试版：6个地点、25张卡、三条通关路线，导出HTML已断网验证。结果、证据与未完成指标见真实测试记录；创作输入见白展堂测试目标。
- 修复：同步《寿灯》batch3 样本与测试夹具；导入脚本默认选择 batch3。
- 优化：玩家存档列表每页显示 8 条，读取存档时显示对应页；自动保存提示隐藏内部存档 ID。
- 修复：HUD、资源变化、商店与补给费用共用世界资源名称，避免同一货币显示不同称呼。
- 当前开发与待完善项见 进度文档；M1/M1b 已落地，后续生成主线为 S2/S3。
- 优化：工作台主界面改为横向铺满（小边距），无限画布优先占满视口宽度；布局约定见 docs/design-layout.md。
- 新增：生成请求会自动重试 429、5xx 和超时，并在 JSON 结构或语义校验失败时把具体字段错误发回模型修正。
- 优化：模型输出可以去掉 Markdown 代码块和前后说明后再解析；任务失败会记下错误码、字段路径、步骤、尝试次数和请求 ID。
- 新增：模型设置提供常用服务商预置、实时模型列表和无需模型即可试玩的演示路径；分支故事支持变量条件与持续效果；API/worker 提供带请求 ID 的结构化日志。
- 优化：Web 工作台使用本机来源校验，MCP 继续使用工作台访问码；模型服务商切换会保护已有 API Key。
- 修复：完善模型连接错误、变量试玩重试和生成任务恢复提示。
完整历史见 发布记录。
需要 Node.js 24 或更新版本，在本项目目录运行。SQLite 使用 Node 自带的 node:sqlite，无需安装 SQLite 原生扩展编译工具：
npm install
Copy-Item .env.example .env
npm run dev打开 http://127.0.0.1:5173 。本机 Web 工作台会直接连接本地 API，不需要输入工作台访问码；API 通过本机 Host/Origin 校验限制来源。data/access-token.txt 中的工作台访问码只用于 MCP 客户端，与模型服务商的 API Key 无关。开发命令同时启动 API、生成 worker、前端；服务仅监听本机。
默认入口 Agent 工作区 为 http://127.0.0.1:5173/#agent。左侧统一导航与会话，中间对话和常驻输入区，右侧查看真实作品上下文、制作进度与执行记录；手机使用导航、会话和上下文抽屉。沿用“模型设置”，支持连续对话、刷新恢复、工具回执与就地审阅操作。查询原作/草稿/任务、体检与修复候选可直接执行；修改世界摘要、创建/恢复生成任务、应用候选或发布会先显示目标、参数和版本，点击“确认执行”后才执行，也可拒绝。每轮最多4次模型调用，模型不能直接确认操作或修改模型设置。详见页面改版与截图记录。
Agent 可分段读取制作规划、关键规则与单段正文，运行已存规划检查，再提议确认当前玩法并排队写作，无需在对话中重传完整世界。确认卡说明角色、路线和模型费用；任务变化会拦住旧确认。详见制作审阅衔接及MCP工具用法。
对话及按需读取的原文会发送至已配置的模型。会话保存在本地 SQLite，浏览器只保存所选会话ID；已知的当前模型密钥会在存储和模型上下文中遮蔽。结果不明确的写操作不会自动重做，应先查询业务状态。模型需兼容 /chat/completions 原生工具调用；目前提供工作台作者工具白名单，尚不支持任意文件、系统命令或全部图结构自动改写。
Agent 监督是可选的独立进程（与 worker 同理，不在 npm run dev 里自动启动）：
npm run dev:agent它每 15 秒轮询任务，只做监督、失败重试与质检，并把决策写进生产面板的“Agent 动态”：失败任务按失败码分流（瞬时问题自动重试，同一任务累计最多 2 次，内容/结构问题与超限直接升级交人工）；待审阅规划只跑机制检查并摘要，绝不替人工确认；已完成任务逐单元跑正文质检，只报告不改写。监督本身不调用模型。
世界草稿的“发布前体检”还提供 Agent 修复候选：先保存并运行模拟试玩，再按路线建议生成候选、查看修改差异，由作者确认应用或驳回。首期支持行动/选项前置条件与剧情卡权重调整；需要补写正文的建议交作者处理，不自动添加占位卡，不调用模型。生成不会修改草稿；确认时用同 40 个种子重新体检与模拟，要求目标路线到达率提高、无新增体检错误、原先通过的检查不退步且死路不增加，之后原子保存新草稿、报告及候选状态。过期候选不能覆盖手改，重复确认不重复修改，已发布版本不变。有限样本改善不等于完整平衡或发布验收，原有体检错误仍须修复。
不想先配置模型时，连接失败页可以直接点击“先体验一个可玩示例”，在浏览器内完成一次选择、状态变化和结局。进入工作台后，原作书架中的“载入示例并试玩”会用同一份示例创建原作、草稿、校验结果和发布版本，再进入后端试玩链路；这条路径不调用模型，适合演示安装是否成功。
API 和 worker 会把结构化 JSONL 日志写入 data/logs/，按组件和日期生成 api-YYYY-MM-DD.jsonl、worker-YYYY-MM-DD.jsonl。每个 HTTP 响应带 X-Request-ID，排查页面错误时可用相同 ID 在 API 日志中定位请求；worker 还会记录任务、分析块和模型请求的开始、完成、失败、耗时及请求体大小。日志不记录访问码、API Key、小说正文或模型请求内容。PowerShell 可用 Get-Content data/logs/api-*.jsonl -Wait 实时查看 API 日志。
如果已有 .env，保留现有文件，不要覆盖。也可通过 APP_ACCESS_TOKEN 提供至少 24 字符的令牌。
进入网页的模型设置，可以先从常用服务商预置中选择 OpenAI、DeepSeek、阿里云百炼、硅基流动、Kimi、OpenRouter、Mistral、Ollama 或 LM Studio；预置只填写 OpenAI 兼容接口地址，不会覆盖 API Key。选择后点击“获取模型列表”，再从返回的模型 ID 中选择；不支持 /models 的服务仍可手动填写模型名称。保存即可，无需重启。模型 API Key 由模型服务商提供，用于后端调用该模型。接口使用支持 JSON 对象输出的 OpenAI 兼容 Chat Completions；本机无鉴权的模型端点可省略 API Key。分析和生成时，小说正文会发送给你配置的模型服务。
“获取模型列表”和“测试连接”只读取服务的模型列表，不发送小说或调用文本生成；部分兼容服务没有模型列表接口，此时仍可手动填写并保存配置，实际生成能力需提交任务验证。正在执行的任务沿用开始时的配置，后续执行和重试读取新配置。首次保存前，可选用 .env 中的 LLM_* 作为初始配置；保存后以工作台设置为准。
生成稳健性由进程环境变量控制，不写入模型设置：
| 变量 | 默认 | 含义 |
|---|---|---|
LLM_MAX_ATTEMPTS |
3 | 同一步骤里，对 HTTP 429、5xx 和连接超时的最大尝试次数（1–8）。401 等其它 4xx 不重试。 |
LLM_RETRY_BASE_MS |
500 | 指数退避基数，含约 ±20% 抖动。 |
LLM_RETRY_MAX_MS |
8000 | 退避上限，不能小于基数。 |
LLM_REPAIR_ATTEMPTS |
3 | 输出不是完整 JSON、不符合结构，或证据、场景连通性等语义校验失败时，把具体错误发回模型修正的次数（1–6）。 |
带 Retry-After 的 429 优先等待该响应头（秒或 HTTP 日期），最多 60 秒。已经分析完的文本块在自动重试和手动恢复时都不会重做。失败任务的 error 文本和 failure 对象包含错误码、字段路径、步骤、尝试次数和请求 ID。日志只记这些字段和耗时，不记录 API Key、访问码、小说正文或模型原文。
页面不回显已保存的 API Key，也不把它写入浏览器存储；留空保存会保留原 Key，勾选清除才会删除。更换服务来源时需要重新填写或明确清除，避免把旧 Key 发送给新服务。没有模型配置时，可以通过草稿编辑器或外部 Agent 的 MCP 工具提交草稿；应用不会生成假结果。
构建后的运行方式：
npm run build
npm start
# 另开一个终端，进入同一目录：
npm run worker此时前端与 API 位于 http://127.0.0.1:4317 ，MCP 位于 http://127.0.0.1:4317/mcp 。
- 在“原作书架”导入 TXT，核对编码、章节和段落。可用原创 封港渡口示例 测试，前两章构成一个完整局面，第三章可不选。
- 在“改编生成”选择游戏形式、章节、玩家身份、忠实或分歧策略及改编方向。只发送选定章节；按 12,000 字符切块，逐块保存分析。失败或取消后可以恢复。
- 开放冒险进入“世界草稿”：编辑开局、目标、时限和规则，审阅地点、人物、事实、行动、事件与证据。复杂条件和后果当前通过高级 JSON 编辑。分支故事进入“分支草稿”，编辑场景与选项，并通过变量、条件和效果表单设置持续后果。
- 保存、校验，再发布固定版本。草稿有未保存修改时，会阻止切换草稿或断开，浏览器离开页面也有提醒。引用和证据校验不能证明每条策略都可解，发布后应试玩。
- 在“开放冒险”开始存档：查看已知线索、在场人物、行动风险与耗时；成功行动自动保存。必要时可“等待片刻”推进局势。不同选择可留下物品消耗、信任、身份暴露或人情债等后果。刷新后从存档列表恢复；修改草稿不会改变已发布游戏和已有存档。
渡口世界样例 是手工编写的测试夹具，验证修船、谈判、商队三种策略，不是模型失败时的替代输出。
无需模型即可体验变量玩法：导入一份示例 TXT，在“分支草稿”新建手动草稿，选择原作，将原创 渡口的承诺 内容粘贴到“高级 JSON 编辑”，应用、保存、校验并发布。先帮助船夫、答应送信，才会解锁渡船路线；也可直接跟商队离开。样例使用 trust、promised 和 route，覆盖三种变量类型，所有场景均标记为原创改编。
已有无变量的草稿、发布游戏和存档可以继续使用。新字段可省略，不需要迁移或重写已发布版本；新存档复制所选发布版本的变量初值。删除或改类型前应先处理引用该变量的条件与效果。结构校验会检查引用和类型，但不能证明所有变量状态都能走到结局，带条件的故事仍应多路线试玩。
TXT 支持 UTF-8、BOM UTF-16、GB18030，单文件不超过 5 MiB。自动编码判断可覆盖。旧项目 D:/code/ai 的接入方式是完整 JSON 导出：{metadata,data:{basic:{novel},chapter:{chapters}}}，无数据库耦合，也不会修改旧项目。HTML 章节以纯文本展示。
apps/server/src/
modules/sources/ 原文解码、解析、来源仓储
modules/generation/ 任务、断点、租约、模型编排端口
modules/games/ 草稿、图校验、不可变发布
modules/sessions/ 当前场景、事件、存档、幂等动作
modules/worlds/ 开放世界草稿、来源与规则校验、不可变发布
modules/adventure-sessions/ 开放行动、事实与知识、事件、事务存档
modules/model-settings/ 模型配置、版本校验、密钥保护端口
app/ 组合根与共用命令合同
adapters/http/ Express 路由、鉴权、输出转换
adapters/mcp/ MCP 协议适配
platform/ SQLite 连接、配置、模型 HTTP 实现
apps/web/src/ 作者工作台与文字阅读界面
packages/contracts/ 跨入口 DTO 和结构校验
各模块的 domain/application 只依赖端口与纯逻辑；SQL 在 infrastructure，框架在 adapters。跨模块只引用公开 index.ts，由组合根注入服务。npm run check:architecture 检查核心层依赖、跨模块内部导入和模块循环。
SQLite 使用 Node 标准库、WAL、短事务和 worker 租约，保留原数据库表和 SQLite 文件格式。模型调用期间不持有事务。任务提交草稿和任务完成同事务；发布版本固定；试玩动作通过 requestId + expectedTurn 防止重复执行和陈旧更新。没有引入 Redis、微服务或框架容器。
npm run verify测试需要 Node.js ≥ 24（package.json 的 engines 已声明 >=24.0.0）：服务端用 node:sqlite，所有测试（根目录与 apps/web）都用 Node 自带的 node:test + tsx --test 运行，不依赖 vitest/jest。npm test 会依次跑 apps/server/test、scripts/*.test.ts 和 apps/web/test。新增测试请用 import { describe, it } from 'node:test' 与 node:assert/strict。
包含领域/真实 SQLite 行为、失败恢复、HTTP 鉴权、真实 MCP 客户端、前端请求幂等、类型检查、架构检查与生产构建。集成测试的外部模型是本地测试服务；本次未使用真实付费模型验证文本质量。
这是单用户本地版本。令牌拥有作者与试玩能力，试玩投影隐藏未来剧情，但不是多人权限隔离。不要直接作为公网服务部署。
完整分块分析会保存；最终改编使用有容量限制的资料摘选。开放冒险分散抽取所选范围的分析，分支故事偏向开篇冲突，都不等于整部长篇已被完整游戏化。人物别名自动合并、跨章冲突消解、质量自动修复尚待完善。规则校验检查结构、引用和证据位置，人物动机、公开文本是否剧透与改编质量仍需作者审阅。
开放冒险的运行时不调用模型，只执行声明式条件与效果，不运行生成代码。事实为布尔值；人物知识是事实 ID 集合，尚不模拟误信或遗忘。事件按规则触发，尚无自主规划的 NPC。自由文本以后接入行动解释层，仍由同一规则服务决定状态变化。
模型 API Key 使用 AES-256-GCM 加密后保存到 SQLite，保护密钥位于 data/model-key.bin；这能避免数据库中直接存储明文，但持有整个数据目录的人仍可解密。数据目录还含原文、工作台访问码、SQLite 及 WAL 文件。备份时先停止 API/worker，再备份整个 data 目录（自定义 DATA_DIR 时备份对应目录）；不把本地小说或凭据提交 Git。
更多：MCP 与 Agent 接入 · 模块边界 · 接口合同 · 开放冒险实施计划 · 验收记录