feat: MVP 工程脚手架——剧情引擎、Act 1 三章内容、Jev 服务层、画像报告与分享卡、Tauri 壳

2026-10-03 10:05:10 +08:00
parent f57eabe12c
commit bf9d7dad5b
54 changed files with 8040 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 苍梧疑冢 · 互动剧情测评（MVP）
+
+陌生人交友匹配 app 的冷启动载体：单人互动叙事（"影游"）。MVP 范围 = 影游第一幕（3 章）
+ 人格画像报告 + 勋章分享卡，**不含匹配和聊天**。
+
+产品共识见 `CONTEXT.md`，架构决策见 `docs/adr/0001`~`0004`，剧本母本见
+`docs/story-framework.md`（第 4 节是 Act 1 全部选择点地图）。
+
+## 怎么跑
+
+```bash
+pnpm install
+pnpm dev        # 浏览器开发（无 API key 时自动降级 Mock，见下）
+pnpm build      # 类型检查 + 产物构建
+pnpm verify     # 无头校验：选择点地图对照母本 + 引擎三章流程 + 重玩语义
+pnpm lint       # oxlint
+pnpm tauri dev  # Tauri 桌面壳（Rust 工具链需先 source ~/.cargo/env）
+```
+
+## Jev（TypeSafe AI System One）配置
+
+复制 `.env.example` 为 `.env`，填入 key：
+
+```
+VITE_TYPESAFE_API_KEY=<your key>
+```
+
+- 有 key：前端直连 `POST https://api.typesafe.ai/v1/systemone`（`HttpJevClient`）。
+- 无 key：自动降级 `MockJevClient`（确定性伪随机返分，console 有提示），开发联调不受影响。
+- `.env` 已在 `.gitignore` 中，绝不能入库。
+
+## 项目结构
+
+```
+content/chapters/        Act 1 三章剧情数据（JSON，选择点 ID/维度标签对母本第 4 节）
+src/engine/              数据驱动剧情引擎（纯 TS，与 UI 解耦）
+  types.ts               章节 schema：dialogue / choice / narration / cutscene / chapterEnd
+  engine.ts              StoryEngine 状态机：节点推进、分支、情绪签名→场景变体、重玩
+  eventStore.ts          EventStore 接口（append-only，只有 append/list）+ localStorage 实现
+src/services/jev.ts      JevClient 接口 + HttpJevClient / MockJevClient
+src/ui/                  最简影游界面（对话框/选项/按住说话占位/场景变体渐变）
+src/ui/report/           画像报告（Jev 7 维 score）、勋章映射、canvas 分享卡
+scripts/verify.ts        内容完整性与流程校验（pnpm verify）
+src-tauri/               Tauri 2 壳（iOS/Android/桌面共用）
+```
+
+## 架构要点
+
+- **append-only 事件存储（ADR-0004）**：`EventStore` 类型层面只有 `append`/`list`，
+  没有 update/delete 路径。重玩 = 新 sessionId 的新轨迹，旧事件原样保留。
+- **三通道边界（ADR-0003）**：主线全部预写在 JSON 里；Jev 在讲述点只做
+  "情绪签名 → 预写场景变体" 的选择题（通道 1）；C3-02 问心幻境通过
+  `variantFrom: "C1-02"` 复用第一章的记忆解析。
+- **画像报告**：Act 1 结束后把全部事件轨迹汇总为 state，一次 Jev 调用并行问
+  7 个维度（依恋/冲突风格/价值观/情绪稳定性/风险偏好/文化底蕴/择偶偏好）的
+  score 问题（criteria 1-10 级），勋章取置信度最高的维度。
+
+## 已知缺口
+
+- **CORS**：浏览器直连 `api.typesafe.ai` 可能有跨域限制，正式环境需加后端代理转发。
+- **ASR 未接**：语音讲述点只有"按住说话"占位按钮，松开即以占位转写文本落事件。
+- **Tauri SQLite 未实现**：`EventStore` 目前只有 localStorage 实现；原生端应用
+  tauri-plugin-sql 实现同一接口（表只建 INSERT/SELECT，不建 UPDATE/DELETE 路径），
+  预留位置见 `src/engine/eventStore.ts` 末尾注释。
+- **Tauri 移动端（iOS/Android）推送与构建未验证**：目前只验证了 Rust 壳
+  `cargo check` 与 `tauri info`，未跑 `tauri android/ios build`。
+- **追问补全未接**：讲述点 schema 里有 `followUp` 策略占位（Jev 缺失维度检测 +
+  NPC 口吻追问，至多 1-2 句），MVP 未实现。
+- **美术全部占位**：CSS 色块 + 渐变，无图片/视频素材；cutscene 节点是占位渲染。
+- **自适应支线路由未实现**：story-framework 第 6 节的低置信度维度插支线属于后续章节工作。