wwkk214222208/StageCraft

StageCraft

本文为项目根 README.md，面向开发者。玩家向使用说明见 玩家看我.md。

文档导航

docs/ 是权威文档层（施工 AI 必读）；custom/docs/ 仅供内部参考，与 docs/ / 代码冲突时以 docs/ 与代码为准。

- 玩家看我.md —— 玩家与创作者向的使用说明（通俗版）
- docs/architecture.md —— 架构手册（施工 AI 必读）：四层插件、状态事务、平台端口、运行时拓扑与事件发射点、路由宪法、组合根与启动链、并发/流式/跨端约束、验证命令与动工清单
- docs/CONTRIBUTING-API.zh.md —— API 贡献指南：如何新增/修改路由（三层结构：运行时契约 / 治理层 / 行为测试）
- docs/INCREMENTAL-UPDATE-WORK-RULES.zh.md —— 后续增量修改、并发施工、评审与证据规范
- docs/certification-matrix.md —— 平台认证矩阵（含安卓 skip-gated 说明，由 test/certification-matrix.test.ts 强制存在）
- docs/architecture-v2-proposal.md —— v2 可替换 Core / 组件参考路径（M0–M9 + LLM System 作者路径，实验性，v1 仍在发布）
- docs/v2-migration-and-usage.md —— v1/v2 共存、组件打包、桌面 plan、Android SAF 与迁移说明
- examples/v2/README.md —— 可构建的 Core + LLM System + Provider Driver + Solution + Tool 端到端样例

项目定位

StageCraft 是一个自托管、插件化的多角色角色扮演（RP）运行时，配套一个 Web 工作台。它想成为比 SillyTavern 更好上手的生态：创作者能低门槛地做角色和剧本，玩家不用配置、打开就能玩。

- 名称：stagecraft，版本 0.3.0，private，协议 AGPL-3.0-only。
- 运行形态：① 独立 Node 服务；② 作为 dsh 插件（经 dsh-rp 适配壳）；③ 安卓远程模式与同 APK 本地 Core 模式。安卓本地模式目前只在 FOA-AL00 / API 31 上有真机证据，属于实验性支持，不承诺覆盖全部 Android 版本。

已实现

以下能力已在代码与测试中落地，可直接依赖：

- 角色独立身份：每角色独立记忆 / 性格 / 目标，且可单独指定 provider + model（role.modelOverride / role.providerId；resolveRouteModel）。
- OOC 即时修正（肘击 = intervene）：对单个角色重新决策，可携带修正后的人设 / 记忆 / 印象 / 目标（POST /api/roles/intervene；room-runtime.interveneRole）。
- 群聊发言模式（玩法声明）：手动 / 导演决定部分角色发言 / 所有人依次发言；story.gameplay.chat.speechMode 声明默认，提交行动后自动执行，侧栏「设置与预设」可切换并持久化；导演选角无需审批，台词逐个生成逐个审批，空选角本地随机兜底（src/stagecraft-chat-service.ts）。
- 计费：按模型价格表记账（基础 / 缓存 / 峰谷价格，peakExcludesWeekends 周末不计峰值），/api/billing 读写，前端「计费与价格」弹窗（src/billing.ts）。
- 提示词预设管理：预设增删改 / 另存为 / ST 导入、私设条目服务端持久（/api/prompts/private-toggles，群聊作用域同样生效）、玩法场景提示词由后端 gameplayScenarios 下发（前端无 scope→模板 硬编码兜底，缺失走空态）。
- 沉浸模式玩法声明：story.gameplay..autoPublish 声明默认值，左侧栏开关随时切换并持久化；沉浸模式隐藏未在场角色。
- 导演模式玩家发言记入正文（气泡样式，始终记录；左侧栏可仅隐藏显示，不影响落盘）。
- 思维链精细化控制：玩法声明 forceThinkingOff 强制关闭（含导演选角），thinking-params.ts 按模型家族差异化设置（DeepSeek / GLM / 豆包 thinking:disabled、OpenAI reasoning_effort:none、Gemini minimal、Kimi low、Claude / 未知提示词引导）；正文输出完毕后思维链默认折叠。
- Debug 控制台：网关 onDetail 下发模型完整返回与最终提交提示词，前端 Debug 开关过滤详情（src/model-gateway.ts / src/thinking-params.ts）。
- 开放插件架构：当前 shipping 的 Node/Android 组合根均由独立 official LLM System 持有 provider/model/credential/routing/lifecycle/stream/cancel/usage；原 Core router 与旧 HTTP provider API 仅作为兼容适配面保留。v2 参考路径进一步支持可替换的 LLM System、Provider Driver（协议适配）、Solution（含 system prompt/prompt assembly）与 Core（src/v2/；详见 v2 文档），但作者路径仍是实验性、未冻结。桌面与 Android 复用同一契约；Android host.secrets 需组件声明并获授权后才是 Keystore-backed，桌面参考 Host 不宣称安全 secret port。
- 插件管理器：内置插件经引导层装载（manifest 校验 / 依赖拓扑 / provides 预检 / 单插件失败隔离，坏插件不再拖垮启动）；「插件」面板与 /admin/plugins 兜底页独立于 Core 可用（D2）；改动启用状态重启生效（D1 不热加载）；存档导出记录插件依赖快照、换环境加载前提示差异（D3，只提示不阻断）。Android 本地经 native 桥提供等价管理能力。
- DSH 辅助剧本编辑：生成 / 润色 / 一致性检查 / 扩开场（src/dsh-story-bridge.ts；creator-workbench-.ts）。
- 崩溃安全：状态变化一次 SQLite 事务提交（src/core/state-transaction.ts）。
- 开发者调试沙箱：sandbox 协议 + worker 管理 / RPC（src/debug/）。

待实现 / 规划中

- ST/MVU 兼容层：ST 卡 → 可安装、版本化的 State Module（变量 / 自动化 / 世界书均为模块贡献）。当前为设计方向、部分落地（src/compat/st-mvu.ts），重度卡仍以文字导入为主。
- 安卓本地运行 APK：同 APK 内置独立 Core 进程、Gateway 和完整 Web UI，可不依赖远程服务运行。当前仅 FOA-AL00 / API 31 有真机证据；其他 Android 版本、release 变体和多设备故障矩阵未验证，由使用者自行承担风险。
- 更丰富的剧情引擎：在不破坏边界的前提下支持更灵活、可版本化的玩法定义与补丁。
- 社区扩展与皮肤 / 一键分享分发：开放 UI 扩展机制与内容分发。
- 通用 Workflow 编排：当前 Workflow Executor 负责固定定义的注册 / 投影 / 合法转换，不是通用自动业务编排器（见下文"当前限制"）。
- 独立模式 AI 编辑流：创作者工作台的 AI 编辑（生成 / 润色 / 一致性检查 / 扩开场）当前依赖 dsh（dsh-story-bridge）。脱离 dsh 的"独立模式"AI 编辑流尚未充分测试，暂不保证可用。

技术栈

| 层      | 选型                                                                               |
| ------ | -------------------------------------------------------------------------------- |
| 运行时    | Node.js ≥ 24（脚本用 node --experimental-strip-types 直接跑 TS，服务端无打包 / 编译步骤） |
| 语言     | TypeScript（类型剥离执行，非 tsc 编译）                                                      |
| 服务端    | 原生 node:http                                                                   |
| 存储     | 原生 node:sqlite（SQLite，运行数据 data/stagecraft.sqlite）                           |
| 插件容器   | @deepseek-ai/cordis 4.0.0-rc.8（npm 别名 cordis）                              |
| 配置校验   | @deepseek-ai/schemastery 3.18.1                                              |
| 前端     | public/ 下原生 JS + CSS（无前端框架）                                                |
| 安卓核心构建 | esbuild 0.28.2（scripts/build-android-core.mjs）                             |

注意：早期文档曾设想 Fastify / Drizzle / React 技术栈，与现状不符，已归档（见 custom/docs/archive/）。

- dsh 生态兼容（低成本）：StageCraft 以 Cordis 宿主插件形态（dsh-rp / cordis.patch.yml，runtimeMode: sandboxed，RP_PORT 默认 8799）运行于 dsh 内。对 dsh 依赖较低 的外围功能性插件，可通过 dsh-rp 适配壳以简单桥接的方式接入，无需重写。

架构

核心循环：

State → Human Interaction / Workflow Action → Core → LLM Route
→ Model Result → State Event → Reducer / Local Rules → New State

四层插件边界（Core 是唯一状态权威）：

1. 人-核心交互插件：Web / HTTP / Cordis Session / CLI 入口。只发 HumanCommand，只消费 CoreView / CoreEvent，不直接碰 Store / 模型 / 领域流程。
2. 核心运行时插件：状态、Reducer、本地规则、审批、事件历史、取消 / 恢复、Command 调度。不依赖 HTTP / DOM / Cordis / 具体模型。
3. 玩法方案插件（CoreSolutionHost）：注册固定、版本化的 Workflow Definition、只读房间投影、状态类别 / 投影、可撤销 Command Handler。默认 StageCraftSolutionPlugin 提供三条 StageCraft 流程、默认状态类别与群聊命令处理器。
4. 核心-LLM 路由插件：负责 ModelRequest / ModelResult（provider 路由、SSE、thinking、usage、超时、request-scoped 取消、错误归一化）。以 requestId 等待匹配结果、隔离迟到结果。
平台端口（Port）：Core 通过小型端口使用时间、UUID、仓储、资源、秘密、文件选择、生命周期、模型传输。Clock、IdFactory、CoreStateRepository 以及 Android 本地的资源、秘密、模型传输端口已经接入；Node / SQLite / HTTP 适配器在桌面组合根。浏览器 / 安卓可提供自身实现，Core 源码不得直接依赖 Node 文件系统 / Android API / DOM / 平台密钥。

状态模型：状态类别可注册（默认 room / world / entities / narrative / memory / goals / workflow / runtime）。所有变化统一为 StateEvent，由 Reducer / Local Rules 产生新状态；applyStateEvents 先计算候选状态，再由 Repository 一次 SQLite 事务提交状态 + 批量事件 + WorkflowInstance，成功后才更新内存并广播。模型只能返回结构化结果或事件提议，不能直接写库或绕过状态校验。

兼容策略：群聊 / 导演 / 管理命令由已安装的 StageCraft Command Handler 接管；旧 HTTP 路由只构造带 scope / action 的 Core command。两条垂直流程由 StageCraftChatService / StageCraftDirectorService 持有，编辑由 StageCraftManagementService 持有。旧 RoomRuntime 仅作兼容 facade，生产组合根不安装 LegacyRuntimeSolutionPlugin。Core 对无 handler 命令 fail closed。

目录与关键入口

src/
server.ts                  服务入口（node:http 启动）
app-boot.ts                应用引导（装配组合根、挂载 Core / UI / DSH）
core/                      运行时内核（插件容器、状态仓储、Workflow、协议、平台端口）
index.ts, container.ts, plugins.ts, runtime.ts, protocol.ts
state.ts, workflow-.ts, domain-events.ts
http-human-plugin.ts, model-router-adapter.ts
cordis-plugins.ts, extensions.ts, ui.ts, renderer-host.ts, connection.ts
platform.ts              端口定义
platform/                  Node 适配：node.ts, node-sqlite-repository.ts, composition.ts, model-gateway-transport.ts
portable/                  android-core.ts, android-composition.ts（安卓本地组合根）
stagecraft-.ts            业务服务：chat / director / management / repository
creator-.ts              创作者工作台：service / ui / contracts / preview-apply
dsh-.ts                   dsh 桥接：story-bridge / story-session
debug/                     沙箱协议、worker 管理（开发期）
compat/                    兼容层：index.ts, st-mvu.ts（ST 卡 / MVU 兼容器，前瞻）
legacy-sandbox.ts          旧 sandbox（兼容）
store.ts, model-gateway.ts, workers.ts, room-runtime.ts, st-card-import.ts
prompts.ts, provider-config.ts, thinking-params.ts, types.ts, remote-access.ts
android/                     安卓工程（远程模式 + 同 APK 本地独立 Core）
dsh-rp/                      dsh 适配壳（见其 README）
public/                      前端（原生 JS / CSS）
stories/default/eldoria.json   默认剧本（含 eldoria.assets/ 角色肖像）
prompts/gameplay/              玩法场景提示词（每 scope 一个文件；userEditable=true 的场景可被用户在预设编辑器中改动，其余为内部提示词，后端不下发）
scripts/build-android-core.mjs

剧本覆盖顺序

剧本检索同时合并 bundle 默认（dist/stories/，来自仓库 stories/）与 用户数据（/stories/，DSH 插件形态下为 AppData %APPDATA%\stagecraft\stories\）。同一剧本 id 出现多份时，按以下优先级覆盖（高 → 低）：

1. 用户数据 stories/custom/（玩家自建/编辑的剧本）
2. 用户数据 stories/（首次启动从 bundle 拷贝的默认剧本，可被编辑）
3. bundle dist/stories/custom/
4. bundle dist/stories/（发布默认剧本，兜底）

加载剧本时若用户数据缺失，自动回退到 bundle 默认（loadStoryPackage 多目录查找）。把插件侧/用户数据侧的剧本固化回仓库，可用：

npm run sync:stories   # scripts/sync-stories-back.mjs：dist/stories + AppData stories → 仓库 stories/

安装与运行

要求：Node.js ≥ 24（低于 22.6 不支持类型剥离）。

推荐 pnpm（仓库带 pnpm-lock.yaml）
pnpm install
pnpm dev            # 即 node --experimental-strip-types src/server.ts

或使用 npm
npm install
npm run dev

启动后访问 http://127.0.0.1:8787。运行数据在 data/stagecraft.sqlite。

模型配置：把 providers.example.json 复制为 providers.json，填入你的模型端点与密钥（详见该文件注释）。

测试：

pnpm test           # node --experimental-strip-types --test --test-concurrency=8 test/*.test.ts

作为 dsh 插件：dsh --profile  在 RP_PORT（默认 8799）启动，核心代码与独立运行一致，仅换入口。详见 dsh-rp/README.md。

手机远程访问（浏览器直连 / 安卓配对）：

独立模式：启用远程访问（监听 0.0.0.0，生成配对码，非本机请求需 Bearer 授权）
RP_REMOTE=1 node --experimental-strip-types src/server.ts
可选：自定义监听地址 / 配对码有效期 / 会话有效期
HOST=0.0.0.0 RP_REMOTE=1 RP_REMOTE_PAIRING_TTL_MS=300000 RP_REMOTE_SESSION_TTL_MS=43200000 node --experimental-strip-types src/server.ts

- 启用后在设置弹窗点「生成手机配对码」，安卓端输入 PC 局域网地址 + 配对码完成配对，配对后通过 /api/remote/pair 换取的 Bearer token 访问后端（实时通道 /api/core/events）。
- ADB 免码直连：手机 USB（或无线调试）连电脑并执行 adb reverse tcp:8787 tcp:8787（端口与电脑实际监听端口一致）后，APK 配对页点「通过 ADB 直连（免配对码）」即可直接绑定，无需配对码——adb reverse 隧道在电脑侧呈现为 loopback，/api/remote/device-token 以回环身份直发会话 token。
- 浏览器免安装测试：手机浏览器打开 http://:/，未配对时自动跳到配对页，输入配对码即完成配对；配对后下发 HttpOnly 会话 Cookie，同一源请求自动携带（设置弹窗可随时清除已配对会话）。
- dsh 插件模式：配置 remoteEnabled: true（并确保监听地址可被手机访问）。
- 非 loopback 请求访问 /api、/assets、/custom 均需授权；HOST=0.0.0.0 而远程访问未启用时启动会报错（安全护栏）。

安卓：

- 远程模式 APK（连接你自己的StageCraft服务）：构建产物见 android/ 工程。
- Termux 本地跑：bash start-android.sh（脚本启动服务并打印局域网地址）；停止 bash close-android.sh。
- 同 APK 本地 Core 构建：pnpm build:android-core（即 scripts/build-android-core.mjs），再按 android/README.md 执行 Gradle 构建与验证。

安卓本地模式是实验性能力：当前真机证据限 FOA-AL00 / API 31。未验证的 Android 版本、release APK、旋转/前后台及其他设备不属于承诺支持范围；出现 Core 故障时使用内置恢复页、远程入口或保留的旧路径。

注意：custom/docs/ 目录不进仓库（已 ignore），里面是私有设计 / 交接 / 审计文档，请勿视为发布内容。

开发速览

- 状态权威在 Core：任何要改状态的动作都走 Command → Core → StateEvent → 事务提交。不要绕过 Core 直接写 Store / 库。
- 扩展点：新玩法通过 CoreSolutionHost 注册方案插件；UI 扩展走 core/extensions.ts + core/ui.ts + renderer-host.ts；模型接入走 LLM 路由插件。
- 兼容层：ST 卡导入在 st-card-import.ts；旧接口 / 外部调用经 compat/。改动旧接口前先读 docs/architecture.md 的"兼容策略"与 custom/docs/ 相关设计文档。
- 不要做的事：Core 不得依赖 Node 文件系统 / Android API / DOM / 平台密钥；Workflow Definition 不允许被 LLM 或 Author Pack 直接修改（未来走版本化 WorkflowPatchProposal 且需授权校验）。
- 验证基准：Cordis 锁定 4.0.0-rc.8，跟随 dsh 平台版本（dsh-rp/verify.mjs 校验 vendor 版本）。

当前限制

Core 通用内核、插件容器、状态仓储、Workflow Registry / Executor、HTTP 人机插件、LLM 路由边界已进入启动链；StageCraft 的 Store-backed domain services 仍是当前业务状态变化的执行者，并通过 Core 投影与事务仓储保持一致。Workflow Executor 当前负责固定定义的注册 / 投影 / 合法转换，不是通用自动业务编排器。未来仍需在不破坏边界的前提下继续收紧旧外部接口与迁移策略。