@musnows/scriverse

v1.2.2

Published

5 days ago

Command-line client and local server for the Scriverse long-form fiction workspace

0High
0Medium
0Low

musnows

scriverse novel writing cli

主要能力

作品书架：管理多部作品、封面、作者和简介。
正文编辑：分卷与章节树、自动保存、历史版本、行号引用、空行整理和全文检索。
章节分类：支持正文、设定、作者的话和其他四种类型。
文件导入：导入 TXT 或 DOCX，识别分卷、章节和后记类型。
设定库：管理世界设定、角色别名、角色属性与锁定字段。
组织系统：维护组织简介、设定列表和成员，一个角色可同时属于多个组织。
时间线：以看板方式管理多条大事件时间轨道，支持拆分、合并和排序。
人物关系：关系类型、关键词列表、证据与置信度，提供普通关系图和可交互的 3D 银河图。
大纲与伏笔：维护章节目标、冲突、转折和伏笔的埋设、提醒与回收。
AI 创作助手：支持 Markdown 和流式输出，可引用章节行、附加角色与设定上下文。
AI 任务：结构分析、章节分析、角色抽取、时间线分析、关系分析和一致性检查。
供应商管理：兼容 OpenAI Chat Completions 与 Anthropic Messages 协议，可配置模型、最大输出 Token、并发数和 RPM。
安全导出：支持 JSON、TXT 和 Markdown，导出内容不包含 AI 密钥。

技术栈

Node.js 22.5+
TypeScript
Express 5
Node.js SQLite
原生 HTML、CSS 和 JavaScript
Vitest 与 Supertest

快速开始

环境要求

Node.js >= 22.5.0
npm

安装与开发运行

git clone [email protected]:musnows/Scriverse.git
cd Scriverse
npm ci
npm run dev

默认访问地址：http://localhost:13210

生产构建

npm run build
npm start

Docker 部署

官方镜像为 musnows/scriverse，支持 linux/amd64 和 linux/arm64。完整的 Compose 配置、首次管理员初始化、持久化、升级、备份、日志、健康检查和 HTTPS 反向代理说明见 Docker 部署指南。

命令行工具

CLI 既可以启动本地 Scriverse，也可以连接任意已运行的服务来查询或编辑作品数据。全局安装后可直接使用 scriverse 命令：

npm install --global @musnows/scriverse
scriverse serve --data-dir ./scriverse-data

serve 默认监听 http://127.0.0.1:13210。启动本地服务不是使用其他 CLI 命令的前置条件；可以保存远程服务作为默认目标：

scriverse connect https://your-scriverse.example.com
scriverse auth login --api-key-file ./api-key.txt
scriverse work list

CLI 会按服务器保存登录凭据。所有连接服务的数据命令都可以使用 --server <url> 临时覆盖默认服务器，例如 scriverse work list --server https://another.example.com；使用前需先通过 auth login --server <url> 登录该服务器。执行 scriverse connect 可查看当前默认服务器。

使用 scriverse --help 查看本地服务、默认服务器、认证、作品、正文、资源、历史版本和搜索等全部命令。CLI 要求 Node.js >= 22.5.0。

环境变量

| 变量 | 默认值 | 说明 | | --- | --- | --- | | PORT | 13210 | HTTP 服务端口 | | HOST | 127.0.0.1 | 监听地址；服务器部署时可设为 0.0.0.0 | | DATA_DIR | <项目目录>/.data | 默认数据目录 | | DATABASE_PATH | <DATA_DIR>/novel.db | SQLite 数据库路径 | | SCRIVERSE_PRE_MIGRATION_BACKUP_RETENTION | 5 | 启动迁移备份最多保留的完整版本数；小于 2 时按 2 处理，启动时清理最旧的超额备份 | | SCRIVERSE_STARTUP_RETRY_LIMIT | 2 | 连续启动失败最多允许的次数；达到上限后停止重复初始化，修复问题并删除 <DATA_DIR>/.startup-retry.json 后才能重新启动 | | AI_NOVEL_MASTER_KEY | 自动生成并保存在 <DATA_DIR>/master.key | 加密 AI 供应商密钥的主密钥；手动配置时至少 32 个字符 | | SCRIVERSE_AI_RETRY_COUNT | 3 | AI 上游返回除 403、429、502 外的 HTTP 错误时的重试次数；有效整数按 1–20 钳制 | | SCRIVERSE_AI_BACKOFF_RETRY_COUNT | 10 | AI 上游返回 429 或 502 时的退避重试次数；有效整数按 1–20 钳制 | | SCRIVERSE_AI_STREAM_IDLE_TIMEOUT_SECONDS | 30 | 交互式 AI 流等待首个或下一个有效事件的最长空闲秒数；有效整数按 10–120 钳制，非法值回退为 30 | | SCRIVERSE_AI_RESPONSE_MAX_BYTES | 0（默认不限） | AI 供应商和 Desktop 本地 AI 响应的字节上限；正安全整数启用，未设置、0 或非法值表示不限 | | APP_AI_CHAT_TAB_LIMIT | 5 | 浏览器中可同时打开的 Agent 对话数；有效整数按 1–20 钳制，设为 1 时关闭多会话切换和工作台 | | SCRIVERSE_CHAPTER_ANNOTATION_NOTE_MAX_LENGTH | 6000 | 正文评论和待办内容的最大字符数；有效整数按 2000–20000 钳制，低于 2000 按 2000 处理，非法值回退为 6000 | | APP_AUTH_USERNAME | 空 | 可选的部署网关账号；应用内用户系统始终启用 | | APP_AUTH_PASSWORD | 空 | 可选的部署网关密码，至少 12 个字符；必须通过 HTTPS 传输 | | APP_TRUST_PROXY | false | 位于可信反向代理后时设为代理跳数（通常为 1）或 true | | APP_ALLOW_PRIVATE_AI_ENDPOINTS | 开发环境 true，生产环境 false | 生产环境默认校验 AI 供应商地址并拦截本机、内网、链路本地和保留网段。显式设为 true/1 后关闭该校验，适用于受信任的透明代理或 fake-ip 部署；启动时会打印警告 | | APP_ALLOW_REGISTRATION | false | 三个互斥等级：未设置、false、0 或其他值表示彻底禁止注册；invite 表示需要一次性邀请码才能注册；true 或 1 表示完全开放注册。invite 与开放注册时都必须配置初始化令牌 | | APP_SETUP_TOKEN | 空 | 开放或邀请码注册时必填且至少 32 个字符；仅首位管理员注册需要在页面输入 | | SCRIVERSE_AVATAR_IMAGE_MAX_BYTES | 2097152 | 头像图片上传大小上限，单位为字节 | | SCRIVERSE_COVER_IMAGE_MAX_BYTES | 5242880 | 作品封面图片上传大小上限，单位为字节；封面不支持 GIF | | SCRIVERSE_ATTACHMENT_IMAGE_MAX_BYTES | 31457280 | 设定库等其他图片附件上传大小上限，单位为字节；包括 GIF | | SCRIVERSE_AI_CHAT_IMAGE_MAX_BYTES | 5242880 | 创作助手聊天图片附件上传大小上限，单位为字节；最小可设为 1048576（1 MB） |

布尔环境变量统一接受 true/1 表示开启、false/0 表示关闭；其他数字不会被解析为布尔值。APP_TRUST_PROXY 例外，其 0–10 数字表示可信代理跳数。

上述三个图片大小限制均使用字节配置；非法、小于 1 或超过 1 GiB 的值会回退到默认值或按 1 GiB 处理。

APP_ALLOW_PRIVATE_AI_ENDPOINTS 会关闭 AI 供应商地址的 SSRF 校验，只应在可信部署必须经透明代理或 fake-ip 访问供应商时显式开启。未设置时生产环境继续校验并拦截本机、内网、链路本地和保留网段；开启后这些地址不再导致连接测试失败，服务启动时会写入警告日志。远程 MCP 服务地址仍保持独立的 SSRF 校验。

SCRIVERSE_AI_STREAM_IDLE_TIMEOUT_SECONDS 在服务启动时读取，只控制交互式 AI 流连续没有新事件的等待时间。每收到一个有效流事件都会重新计时，持续生成超过 60 秒不会因此中断；该配置不设置总时长上限，也不改变分析任务等其他 AI 请求的超时策略。修改后需重启服务生效。

SCRIVERSE_AI_RESPONSE_MAX_BYTES 控制 AI 供应商流式响应、普通响应和 Desktop 本地 AI 响应的字节上限。默认关闭上限；未设置、设为 0 或非法值时不限，设为正安全整数后按该字节数限制。修改后需重启服务生效。

SCRIVERSE_CHAPTER_ANNOTATION_NOTE_MAX_LENGTH 在服务启动时读取，同时约束 API、界面输入和 AI 写计划中的正文评论与待办。修改后需重启服务生效。

AI 上游 HTTP 重试配置在服务启动时读取。403 始终不重试；429 和 502 使用指数退避，等待从 500 毫秒开始并在 5 秒封顶，同时遵循秒数格式的 Retry-After（同样最多等待 5 秒）；其余 HTTP 错误使用线性等待。非法配置回退到对应默认值，修改后需重启服务生效。

自定义示例：

PORT=13211 DATA_DIR=/path/to/scriverse-data npm run dev

服务器部署示例：

NODE_ENV=production \
HOST=0.0.0.0 \
APP_AUTH_USERNAME=admin \
APP_AUTH_PASSWORD='请替换为足够长的随机密码' \
npm start

生产环境必须在可信反向代理后启用 HTTPS。首次初始化时，将 APP_ALLOW_REGISTRATION 设为 true 或 invite，并为 APP_SETUP_TOKEN 配置至少 32 个字符的随机值；创建的第一个用户会自动成为系统管理员，且必须在页面输入该令牌。完成后可将注册改为 false 彻底关闭，或改为 invite 仅允许持有一次性邀请码的用户注册。后续完全开放注册时不再要求初始化令牌；邀请码模式下普通注册必须填写系统管理员生成的一次性邀请码。可选的 HTTP Basic Auth 仅作为额外部署网关，其凭据只是 Base64 编码，未使用 HTTPS 时不能防止链路窃听。/api/health 保持免认证以供探活，业务 API 需要应用内登录。

AI 供应商配置

配置前请先阅读 AI 供应商兼容性与配置指南，其中列出了已验证的服务商、基础地址、模型标识符和已知差异。

启动项目后，点击顶部“AI 管理”进入平台级配置。
新建兼容 OpenAI Chat Completions 或 Anthropic Messages 的供应商，选择协议并填写基础地址、API 密钥、并发数、RPM 与最大输出 Token。
为模型填写其支持的上下文总量（Token），再添加模型。
在平台页设置全局系统提示词；它会追加在内置提示词之后。
打开一本作品，在“更多 → AI 设置”中设置该书的追加系统提示词和任务默认模型；书籍提示词会追加在全局提示词之后。

新建供应商默认最大并发请求数和 RPM 均为 10，默认最大输出 Token 为 32000；新建模型默认上下文容量为 128000 Token。侧栏对话框会显示当前请求的上下文用量圆环。

数据与安全

数据默认保存在 .data/novel.db。
AI 供应商密钥经加密后存储，主密钥默认位于 .data/master.key。
备份或迁移时，请同时保存数据库和主密钥；丢失主密钥后无法解密已保存的供应商密钥。
项目包含应用内多用户系统；首个注册用户自动成为管理员。HTTP Basic Auth 是可选的额外部署网关，不代替应用内登录。
服务默认只监听 127.0.0.1。非本机监听同样强制要求鉴权，公网入口必须使用 HTTPS、可信反向代理和防火墙访问控制。
应用默认启用 CSP、防点击劫持、MIME 嗅探防护、同源写请求校验、认证失败限速、API 限速、JSON/上传大小限制和 AI 供应商 SSRF 防护。
SQLite 查询通过 prepared statements 绑定参数；动态 SQL 片段只来自服务端受控枚举，不拼接用户输入。

测试

# 类型检查
npm run typecheck

# 全部 Vitest 测试
npm test

# 单元、集成和系统测试
npm run test:unit
npm run test:integration
npm run test:system

# 针对已启动服务的真实 E2E 测试
npm run test:e2e:real

# 类型检查、全部测试和生产构建
npm run check

test:e2e:real 默认访问 http://127.0.0.1:13210/api。如果服务运行在其他地址，可以设置 E2E_BASE_URL：

E2E_BASE_URL=http://127.0.0.1:13211/api npm run test:e2e:real

项目结构

src/
  ai.ts                  AI 调用、上下文构建与任务编排
  app.ts                 Express API 与静态界面入口
  database.ts            SQLite 表结构与迁移
  parser.ts              TXT/DOCX 小说结构解析
  server.ts              服务启动与关闭
  store.ts               业务数据存取
  public/                浏览器端界面与可视化
tests/
  unit/                  单元测试
  integration/           API 与数据集成测试
  system/                完整作者流程测试
  e2e/                   针对运行服务的端到端测试

健康检查

curl http://127.0.0.1:13210/api/health

正常响应示例：

{
  "data": {
    "status": "ok",
    "version": "0.3.3",
    "protocol": "openai-chat-completions",
    "protocols": ["openai-chat-completions", "anthropic-messages"]
  }
}

项目状态

当前为 MVP 版本，接口和数据结构仍可能调整。升级前请备份 .data 目录。

参与贡献

提交代码或文档前，请阅读协作开发规范。所有日常变更均从最新 develop 派生，并通过以 develop 为目标分支的 Pull Request 合入。

许可证

除另有说明的第三方组件外，本项目自本次许可证变更起采用 GNU Affero General Public License v3.0 only（AGPL-3.0-only）授权。你可以使用、修改、分发或商业化本软件，但分发衍生版本时必须继续以 AGPLv3 提供对应源码；如果修改后的版本通过网络与用户交互，也必须向这些用户提供该版本的对应源码。

许可证变更前已经发布的版本继续适用其发布时附带的许可证。

🌟 Special Thanks

感谢开源项目 Vditor，为叙界提供 Markdown 编辑器、即时渲染和分屏预览能力。