npm install          # 安装依赖
npm run build        # 编译到 dist/（tsc）+ 打包运行时（esbuild）
npm test             # 66 个测试（vitest）
npm run mcp          # 以 stdio 方式启动 MCP 服务器

{
  "mcpServers": {
    "ai-text-engine": {
      "command": "node",
      "args": ["C:/path/to/ai-text-engine/dist/mcp/server.js"]
    }
  }
}

node scripts/verify-mcp.mjs      # stdio 握手 + 工具清单（应输出 VERIFY OK，11 个工具）
node scripts/demo.mjs            # 端到端演示：AI 全流程构建《迷雾车站》并导出
node scripts/verify-export.mjs   # 验证导出 HTML 内嵌剧情可玩

interface Story {
  meta: { title: string; subtitle?: string; version?: string; author?: string }
  start: string                                // 起始节点 id
  nodes: Record<string, StoryNode>             // 节点表
  endings: Record<string, EndingMeta>          // 结局表（upsert 节点时自动登记）
}

interface StoryNode {
  id: string
  text: string                    // 正文；支持 {varName} 插值、{#inventory} 道具列表、\n 换行
  choices: Choice[]               // 空数组 = 结局节点（必须带 ending）
  ending?: EndingMeta             // { id, title, kind: 'good'|'bad'|'true'|'hidden' }
  onEnter?: Effects               // 进入本节点时生效
  tags?: string[]                 // 仅供 AI/作者管理，不影响游戏
  note?: string                   // 设计备注，不进入游戏
}

interface Choice {
  label: string                   // 按钮文案（支持 {var} 插值）
  target: string                  // 目标节点 id
  when?: Condition                // 显示条件（不满足则选项隐藏）
  effects?: Effects               // 选择后生效
}

interface Effects {
  set?: Record<string, number | string | boolean>  // 赋值变量
  add?: Record<string, number>                     // 数值增减（不存在时从 0 起算）
  gain?: string[]                                  // 获得道具
  lose?: string[]                                  // 失去道具
  flag?: Record<string, boolean>                   // 旗标（与变量同命名空间）
}

interface Condition {
  var?: string
  op?: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'has' | 'not_has'
  value?: number | string | boolean
  and?: Condition[]
  or?: Condition[]
  not?: Condition
}

interface Achievement {
  id: string
  title: string
  description: string
  icon?: string          // emoji
  hidden?: boolean       // 解锁前在列表显示「？？？」（隐藏成就）
  when: Condition        // 达成条件；特殊变量 #steps（步数）/ #ending（结局 id）/ #visited（访问过某节点）
}

{ var: '好感度', label: '好感度', max: 100 }   // max 为进度条满值

interface StoryDocument {
  id: string
  title: string
  kind?: 'rules' | 'note' | 'letter' | 'doc'   // 守则 / 便条 / 信 / 文档
  text: string                                  // 正文（支持 {var} 插值）
}

blocks: [
  { type: 'title', title: '雾中车站', text: '雾中车站' },
  { type: 'para', text: '凌晨一点半，雾把车站裹成一只茧……' },
  { type: 'rules', title: '售票窗口告示', text: '1. 末班车 23:00 发车。\n2. 雾天禁止在站台逗留。' },
  { type: 'note', text: '（纸条，字迹潦草）' },
]

src/
├── core/          # 引擎核心（纯逻辑，无 DOM）
│   ├── types.ts   #   数据模型
│   ├── engine.ts  #   Game 状态机
│   ├── conditions.ts / effects.ts
│   ├── validate.ts / walk.ts
│   └── fixtures.ts / *.test.ts
├── export/        # 单文件 HTML 导出
│   ├── runtime.ts #   运行时渲染器（打包进 HTML）
│   ├── exporter.ts#   esbuild bundle + 模板拼装
│   └── *.test.ts
├── mcp/           # MCP 服务器
│   ├── projects.ts #  项目存储（projects/ 目录）
│   ├── handlers.ts #  工具实现（可单测）
│   └── server.ts   #  stdio transport + 工具注册
scripts/           # build-runtime / verify-mcp / demo / verify-export
projects/          # AI 创建的游戏项目（gitignore）