Storymaker TypeScript

Storymaker 的 TypeScript / Node.js 叙事服务。项目基于 Fastify，提供世界、NPC、日历事件、对话记忆与本地 RAG 检索 API，并保留原 Python 服务的主要 HTTP 与存储行为。

主要能力

• 多世界与存档槽隔离
• NPC 创建、随机生成与旧数据导入
• NPC 对话、回复选项、对话结算与记忆持久化
• 日历推进和世界事件生成
• SQLite + 混合检索的本地 RAG
• DeepSeek、Gemini、LongCat 及 OpenAI 兼容接口
• 用于本地调试的浏览器测试页

环境要求

• Node.js 22 或更高版本
• npm
• 可选：LLM 服务商 API Key

首次启用真实语义检索时，@huggingface/transformers 会下载嵌入和重排模型。模型缓存在 .hf_models/ 与 .hf_cache/，不会提交到 Git。

快速开始

git clone git@github.com:ColdWu/storymaker-ts.git
cd storymaker-ts
npm ci
cp .env.example .env.local
npm run dev

Windows PowerShell 可使用：

Copy-Item .env.example .env.local
npm run dev

服务默认监听 http://127.0.0.1:8010。启动后可以访问：

• GET /：本地 NPC 对话测试页
• GET /health：服务与 LLM 配置状态
• GET /api/worlds：世界列表
• GET /api/npcs：当前世界的 NPC 列表
• GET /api/calendar：当前日历状态

完整接口定义见 docs/api-contract.md。默认请求世界为 bar，也可以通过 X-Storymaker-World-Id 请求头选择其他世界。

配置

复制 .env.example 为 .env.local，按需填写：

STORYMAKER_PORT=8010
STORYMAKER_LLM_PROVIDER=deepseek
STORYMAKER_LLM_API_KEY=
STORYMAKER_LLM_ENDPOINT=
STORYMAKER_LLM_MODEL=

也可以使用服务商专用变量：DEEPSEEK_API_KEY、GEMINI_API_KEY、GOOGLE_API_KEY 或 LONGCAT_API_KEY。RAG 开关、模型与检索参数均记录在 .env.example 中。

如果只需离线运行测试或暂时不下载模型，可以设置：

STORYMAKER_RAG_EMBEDDINGS_ENABLED=false
STORYMAKER_RAG_RERANKER_ENABLED=false

常用命令

npm run dev           # 开发模式，监听源码变化
npm run build         # 编译到 dist/
npm start             # 运行已编译服务
npm run typecheck     # TypeScript 类型检查
npm run test:offline  # 不依赖外部服务的测试
npm test              # 完整测试、契约检查与真实烟雾测试
npm run rag:rebuild   # 重建本地 RAG 索引

完整测试会同步并调用 Python 参考运行时，且部分流程可能访问真实 LLM 或下载模型；日常开发优先使用 npm run test:offline。

项目结构

src/       服务、路由、存储、LLM 与 RAG 实现
tests/     单元、集成、契约与一致性测试
data/      随仓库提供的示例世界数据
public/    本地浏览器测试页
scripts/   迁移、契约、烟雾测试和审计工具
docs/      API、存储与 RAG 设计文档
reports/   迁移验收及一致性审计结果

数据与安全

• 不要把真实密钥写入源码或 .env.example；仅保存在本机 .env.local。
• .env*（保留 .env.example）、私钥/证书、模型缓存、构建产物、日志与 SQLite 索引均已加入 .gitignore。
• 存档槽、会话、记忆、顾客种子、对话引子、日历和世界事件属于本地运行期数据，可能含对话内容，因此不会提交。
• 测试页中的 API Key 只用于当前页面发起的请求，不写入源码，也不写入浏览器存储。
• 如果密钥曾经进入提交历史，请立即在服务商后台撤销并重新生成；仅删除文件不足以使旧密钥失效。

相关文档

• API 契约
• 存储兼容矩阵
• RAG 子系统分析
• 迁移测试计划
• 最终一致性审计

License

本仓库暂未声明开源许可证。除非仓库所有者另行授权，否则保留所有权利。