三生执笔

一纸山河，执笔入仙。「三生执笔」— AI 为你写仙侠大梦。可自由开口，言出即法。多结局，可存档，每世都值得重来。

微信小程序端的 AI 交互式叙事游戏（橙光风格 + Character.AI 混合）。玩家通过 ABCD 选项和自由输入推进剧情，AI 实时生成中文叙事；创作者可在小程序内配置世界模板和模型路由。

核心原则：游戏引擎管规则和状态，LLM 管叙事生成。 所有剧情判定（条件、章节、结局、属性变更）由引擎执行，LLM 只产出叙事文本和结构化状态变更建议，并经引擎二次校验。

功能特性

• 流式剧情（打字机效果）+ 3-4 个 AI 生成选项 + 自由输入（话语/行动自动区分）
• 属性系统与检定：章节/结局/地点解锁由结构化条件（属性、好感度、flag、修为）驱动
• 群像世界：NPC 有自己的 persona、记忆、好感度与在场名单，对话不再是两人的独白
• 动态地点：AI 可在模板之外创造新场景，随剧情实时登记并持续可用
• 多存档槽（1 个自动 + 5 个手动）、章节 TOC 目录、行动结局跨回合反馈
• 创作者模式：小程序内可视化编辑世界模板、NPC、地点、任务、事件与模型路由

技术架构

pnpm monorepo，三个包：

包	说明
packages/shared	@character/shared — 纯 TypeScript 类型定义（零运行时成本，server 直接引源码，无需构建）
server	@character/server — Node.js + TypeScript + Fastify v5 + PostgreSQL(Drizzle) + Vercel AI SDK + LangGraph.js
miniapp	微信原生小程序（WXML + WXSS + TypeScript）

游戏循环是 LangGraph StateGraph：输入 → 解析（自由输入意图）→ 构建上下文 → 引擎判定条件 → 拼装 prompt → 生成剧情（SSE 流式）→ 提取状态变更（低温度）→ 引擎校验应用 → 生成选项 → 检查章节/结局触发 → 返回。详见 docs/architecture.md 与 docs/decisions.md。

快速开始

1. 安装依赖

pnpm install

2. 配置环境变量

cp server/.env.example server/.env

编辑 server/.env 填入数据库连接和 API Key（API Key 缺失或为占位符 sk-xxx 时服务会抛错；DEEPSEEK_API_KEY 为必填）。

3. 初始化数据库

pnpm db:migrate  # 自动建库（若不存在）+ 建表（幂等，可重复执行）
pnpm db:seed     # 导入预设世界 + 模型路由配置（幂等）

需要本机有 PostgreSQL（默认连接 postgresql://postgres:postgres@localhost:5432/character，需有 CREATEDB 权限）——数据库本身无需预建，migrate 会先连 postgres 维护库自动创建目标库。

4. 启动后端

pnpm dev:server  # tsx watch，http://localhost:3000

5. 运行小程序

用微信开发者工具打开 miniapp/ 目录编译（首次打开会自动生成 project.config.json，需填入你的小程序 appid）。默认 serverUrl 为部署域名，本地开发在「我的」页覆盖为 http://localhost:5500 或 http://localhost:3000，并在开发者工具详情中勾选「不校验合法域名」。

登录说明（dev 模式）

.env 中 WECHAT_APPID/WECHAT_SECRET 是占位符时，微信登录直接用任意 code 作为 openid，任意字符串即可登录，无需真实微信 appid。

部署（Docker + OpenResty）

生产链路：小程序 → https://<你的域名> → OpenResty 443 反代（proxy_buffering off 保证 SSE 不被缓冲）→ 容器 127.0.0.1:5500。

cp server/.env.example server/.env
docker compose up -d --build app   # 先构建镜像（init 与 app 共用同一镜像，变更代码后必须重建）
docker compose run --rm init       # 一次性初始化：自动建库 + 建表 + seed

生产配置模板见 server/.env.example（compose 的 env_file 直接读 server/.env，改完配置需 docker compose up -d --build 生效）；OpenResty 反代配置参考 deploy/openresty-wen2so.conf（含真实域名的部署配置不入库）。

预设世界

worlds/ 下有 xianxia / apocalypse / palace 三个模板目录，目前只有修仙世界（xianxia）实现并 seed 进数据库，其余两个仍是空壳，需在 server/src/db/seed/preset-worlds.ts 中实现。

模型路由

model_routes 表按阶段配置模型（narrative / options / state_extraction / summary / free_input），支持 anthropic / openai / deepseek 或自定义 baseUrl，每个阶段可独立设置 temperature、max_tokens 与 API key。seed 默认全走 DeepSeek。

常用命令

命令	说明
pnpm dev:server	启动后端（tsx watch，localhost:3000）
pnpm db:migrate	建表（幂等裸 SQL）
pnpm db:seed	导入预设世界 + 模型路由（幂等）
cd server && pnpm typecheck	服务端类型检查
cd server && pnpm db:studio	Drizzle Studio 数据库可视化

项目没有 lint 和测试框架；验证方式是 typecheck + server/test/ 下的手写脚本（需要服务器运行中且数据库已 seed）。

文档

• 架构总览 — 分层结构、游戏循环、SSE 事件流、数据库表
• 决策记录 — 全部架构决策及理由
• 界面设计稿 — 主题「夜行修仙」的静态设计稿（本地起静态服务即可预览）