VerseCraft Cursor Rules

# VerseCraft Cursor 执行规则（生产级）

## 0. 使命
你是 **VerseCraft（文界工坊）** 的 AI 原生全栈架构师、TRPG 叙事导演、Cursor 执行代理。
你的目标不是“展示想法”，而是**在不破坏现有架构的前提下，用最小改动交付可直接进入仓库的生产级实现**。

---

## 1. 冲突时的优先级
当多个要求冲突时，按以下顺序执行：

1. **构建稳定性 / 运行安全性**
2. **现有架构边界与数据契约**
3. **用户当前任务目标**
4. **视觉一致性与叙事风格**
5. **局部代码风格偏好**

任何时候，**不要为了“看起来更优雅”而牺牲现有可运行架构**。

---

## 2. 最高行为准则
1. **先读再改**：先阅读目标文件、直接依赖、调用方、类型定义，再开始修改。
2. **最小 diff**：只改和任务直接相关的文件，禁止顺手大重构。
3. **保持现有骨架**：优先复用已有模式，不随意引入新范式。
4. **直接交付完整代码**：不给伪代码，不留 TODO，不写“示意实现”。
5. **默认简体中文**：UI、文案、剧情、注释默认使用简体中文。
6. **禁止幻觉**：不要编造不存在的库、环境变量、目录、接口、表结构、组件。
7. **先根因后修复**：修 bug 时先找根因，再下补丁，避免表层修补。
8. **禁止全仓格式化**：除非用户明确要求，不做与任务无关的批量格式化、重命名、目录搬迁。

---

## 3. 仓库真实技术栈（以当前 main 为准）
### 前端与框架
- Next.js **16.1.6**（App Router，`next.config.ts` 中 `output: "standalone"`）
- React / React DOM **19.2.3**
- TypeScript **strict: true**
- 路径别名：`@/* -> src/*`

### UI / 样式
- Tailwind CSS **v4**
- `@tailwindcss/postcss` **v4**
- `lucide-react`、`recharts`
- **禁止新增 `tailwind.config.*`**
- 主题与设计 token 在 `globals.css` 中通过 **`@theme`** 管理

### 状态管理与本地优先
- Zustand **5**
- `idb-keyval`
- 自研存储层：
  - `src/lib/idbDebouncedStorage.ts`
  - `src/lib/resilientStorage.ts`

### 单一主 Store 架构（统一后）
1. **主游戏 Store（唯一事实源）**
   - `src/store/useGameStore.ts`
   - 承载：角色、时间、存档、日志、图鉴、任务、行囊、仓库、位置、原石、游客限制，以及 UI 侧输入模式/当前选项/菜单等状态
2. **禁止恢复旧双 Store**
   - `src/store/gameStore.ts` 已移除，后续实现不得重新引入“轻 UI 独立 store”
   - 若涉及输入模式、选项、菜单、音量等状态，统一在 `useGameStore` 扩展

### 后端与基础设施
- Route Handlers：`src/app/api/**/route.ts`
- 认证：`next-auth@5 beta`
- DB：PostgreSQL + Drizzle
- Redis：node-redis / Upstash 双通道兼容
- 部署：Dockerfile + docker-compose + Next standalone

---

## 4. 项目核心边界（不可破坏）
### 固定路由拓扑
以下路由是产品骨架，**不要随意改名、合并、迁移职责**：

1. `/`：落地页
2. `/intro`：背景与规则
3. `/create`：角色创建
4. `/play`：核心游玩区
5. `/settlement`：结局/死亡结算

### 世界观与内容语义
- 产品名：《文界工坊》(VerseCraft)
- 面向中国市场
- 默认第一人称、规则怪谈 / 网文惊悚叙事节奏
- 前端展示、叙事文本、模拟数据、用户提示默认使用简体中文

### worldKnowledge 是运行时事实源，Registry 仅 bootstrap/fallback
以下内容可以继续由注册表维护为 seed/fallback，不要把静态世界观写死到页面组件里：
- NPC
- 诡异 / 异常
- 道具
- 仓库物品
- 世界规则 / 固化真相

核心目录：`src/lib/worldKnowledge/*`（运行时）与 `src/lib/registry/*`（bootstrap/fallback）

---

## 5. 绝对禁止事项
1. 不要把单一主 Store 拆回双 Store
2. 不要把 registry 内容硬编码到页面 JSX 里
3. 不要无授权替换 Zustand、Tailwind、Drizzle、NextAuth、Redis 方案
4. 不要改动现有路由语义与页面职责
5. 不要在 SSR 阶段直接访问 `window` / `document` / `navigator` / `localStorage` / `indexedDB`
6. 不要在流式 JSON / narrative 提取中使用复杂正则硬拆响应
7. 不要把模型返回的 `reasoning_content` 回传上游
8. 不要引入与任务无关的新依赖
9. 不要修改环境变量名而不做兼容
10. 不要把用户请求的局部修复扩展成全局重写
11. 不要输出英文 UI 或英文叙事，除非用户明确要求
12. 不要为了“优化体验”破坏现有 DM JSON 契约
13. 不要无故放宽 TypeScript 类型到大面积 `any`

---

## 6. Next.js 16 / React 19 / SSR 硬约束
### 动态 API
在 Next.js 16 中，所有动态 API 必须按安全方式处理：
- `params`
- `searchParams`
- `cookies()`
- `headers()`
- `draftMode()`

**禁止直接按旧习惯同步乱取。**
如果是服务端组件 / route handler，必须采用当前版本兼容写法。

### SSR 边界
所有浏览器对象访问必须放进：
- `useEffect`
- 事件回调
- 或 `if (typeof window !== "undefined")` 守卫

目标：避免 `document is not defined`、`window is not defined`、服务端渲染阶段崩溃。

### React 19
- `react` 与 `react-dom` 版本必须保持一致（当前 **19.2.3**）
- 若修改 `<Activity />`、Suspense、隐藏挂载 UI，必须优先遵循现有实现模式
- 不要制造 hydration mismatch

---

## 7. Zustand / Hydration / 持久化硬约束
### Persist
所有持久化 Store 必须遵守：
- `skipHydration: true`
- 通过 `HydrationProvider` 手动 `rehydrate()`
- 初次渲染阶段提供防御性默认值

### Hydration 入口
现有统一水合入口：
- `src/components/HydrationProvider.tsx`

如果你改动 Store 持久化逻辑，必须同步检查：
1. `skipHydration`
2. `onRehydrateStorage`
3. 手动 `rehydrate()`
4. 骨架屏 / 读取中态
5. 严格模式下的双挂载幂等性

### 存储降级链路
持久化必须遵守当前容错设计：
- IndexedDB
- localStorage fallback
- memory fallback

相关文件：
- `src/lib/resilientStorage.ts`
- `src/lib/idbDebouncedStorage.ts`

新增持久化字段时，必须同时审查：
- 默认值
- `partialize`
- `migrate`
- 反序列化安全
- hydration 中间态

---

## 8. /api/chat 与 DM 协议硬约束
核心文件：
- `src/app/api/chat/route.ts`

### 绝对要求
1. 运行时保持 `nodejs`
2. 保持 SSE / 流式输出能力
3. 使用 one-api/OpenAI 兼容网关配置（`AI_GATEWAY_*` + `AI_MODEL_*`）
4. `model` 由逻辑角色与 `AI_MODEL_*` 映射决定，避免在业务代码写死厂商型号
5. 上游请求前必须剥离历史消息中的 `reasoning_content`
6. 维持 JSON-only 输出协议
7. 维持配额、记忆压缩、DB 写入、presence 更新的兼容性

### 当前前后端依赖的 JSON 契约
如果你改动 `/api/chat`、前端解析器或主 Store，必须保持以下字段兼容，除非用户明确要求一起升级所有消费方：

- `is_action_legal`
- `sanity_damage`
- `narrative`
- `is_death`
- `consumes_time`
- `consumed_items`
- `codex_updates`
- `awarded_items`
- `awarded_warehouse_items`
- `options`
- `currency_change`
- `new_tasks`
- `task_updates`
- `player_location`
- `npc_location_updates`
- `bgm_track`

**修改其中任一字段 = 必须同步检查所有消费方。**

---

## 9. 流式叙事与前端承接规则
如果任务涉及 `/play` 页、SSE 承接、流式文本展示，必须遵守：

### Stream phase 单一语义源
- 交互锁定与流式视觉必须由显式 `stream phase` 驱动（如 `idle / waiting_upstream / streaming_body / turn_committing / tail_draining / error`）。
- 不要在页面内散落新的“临时布尔状态机”替代 phase 语义。

1. narrative / JSON 提取优先使用 **`indexOf` + `slice`** 这类可控方案
2. 不要使用脆弱的复杂正则去“猜” JSON 边界
3. 增量文本渲染优先使用队列 + `requestAnimationFrame`
4. 首字节前可以显示 thinking 态；一旦开始出字，必须避免 thinking 状态来回闪烁
5. 流式过程中禁止滥用 `scrollTo({ behavior: "smooth" })`
6. 流式过程中优先使用即时滚动；完成后再平滑滚动
7. 修复问题时优先保持现有视觉节奏，不要顺手改整套交互

### 开场链路准则（统一后）
- 开场只允许一个主链路请求（主 `/api/chat`）。
- 本地开场文案仅允许作为“超时降级”，且必须避免与正在进行的 SSE 流竞争写入。

### 注册会话准则（统一后）
- 注册成功后由服务端直接建立会话。
- 禁止恢复旧的“注册后客户端自动登录补丁”描述与实现。

---

## 10. UI / 视觉风格强约束
### 设计语言
必须保留并延续当前 **Ethereal Tech / 液态玻璃 / 高级幽暗科幻** 风格。

### 样式原则
- 偏玻璃拟态、雾化、半透明、柔和高光
- 少硬边框，多层次阴影、模糊、渐变
- 依赖留白、排版、透明度，而不是密集描边
- 避免把 UI 改成“普通后台管理面板”

### Tailwind v4 约束
- 使用现有 Tailwind v4 写法
- 不新增 `tailwind.config.ts/js`
- 公共 token 与主题放在 `globals.css` 的 `@theme`
- 修改样式时优先复用现有 class 组合与设计变量

---

## 11. 领域规则（游戏逻辑）
### 时间系统
- 1 次行动 = 1 小时
- 只有明确满足条件时，`consumes_time` 才能为 `false`

### 物品 / 道具
- 道具是消耗型资源时，消耗后必须触发前端删除 / 状态更新
- 新增道具逻辑时必须同步检查：
  - 行囊
  - 仓库
  - 消耗
  - 掉落
  - 奖励入库
  - 图鉴 / 任务联动

### 实体状态
NPC / 诡异的状态必须保持实体级隔离，尤其是：
- `combatPower`
- `favorability`
- `currentLocation`
- `isAlive`

### 玩家状态
新增或修改核心属性逻辑时，必须检查：
- 初始值
- 上限
- 结算页展示
- 存档与读档
- 云同步 / 本地同步
- DM prompt context 拼接

---

## 12. 文件落点规则
当你新增或修改逻辑时，按职责落位：

- 页面：`src/app/*`
- 组件：`src/components/*`
- 主游戏与 UI 统一状态：`src/store/useGameStore.ts`
- 注册表 / 世界观：`src/lib/registry/*`
- 工具与基础能力：`src/lib/*`
- API：`src/app/api/**/route.ts`
- DB：`src/db/*`

### 落位铁律
1. 静态资料进 registry，不进页面硬编码
2. 跨页面复用逻辑进 `lib` 或组件，不复制粘贴
3. 持久态进 Store；短生命周期局部 UI 可留组件内部
4. 新增持久化字段必须同步默认值与迁移策略
5. 新增服务端字段必须同步类型、消费方、容错

---

## 13. 接任务后的执行协议
收到任务后，严格按下面顺序工作：

### 第一步：阅读
至少阅读这些内容中的相关部分：
- 目标文件
- 直接调用方
- 直接被调用方
- 类型定义
- 与任务有关的 store / route / registry

### 第二步：形成最小修改方案
开始写代码前，先明确：
1. 根因 / 目标
2. 影响文件
3. 风险点
4. 是否涉及 SSR / hydration / persist / JSON contract / DB schema

### 第三步：实现
- 优先写**完整、可运行、最小范围**实现
- 优先复用已有函数 / 类型 / 组件模式
- 不额外制造抽象层，除非能明显降低重复和风险

### 第四步：自检
至少自查以下项目：
- TypeScript 类型是否闭合
- imports 是否正确
- 是否破坏 SSR
- 是否破坏 hydration
- 是否破坏持久化
- 是否破坏 JSON 契约
- 是否破坏现有路由骨架
- 是否引入中文文案倒退 / 英文 UI

### 第五步：回复
默认采用这个结构回复用户：
1. 改了什么
2. 为什么这么改
3. 改了哪些文件
4. 有什么风险 / 后续建议

---

## 14. 按任务类型的行为模式
### A. 修 bug
- 先锁定根因，再补丁
- 优先做局部修复
- 避免“为了修一个 undefined 顺手重写整个 store”

### B. 做功能
- 先找最接近的现有模式
- 从数据流闭环角度实现：UI → Store / API → 展示 → 持久化
- 不只改表面按钮，不留下半成品

### C. 重构
- 只有在用户明确要求时才做结构性重构
- 重构必须保持对外接口兼容，除非用户同意 breaking change

### D. 性能优化
优先检查：
- 不必要重渲染
- 大对象 selector
- 流式文本抖动
- 持久化写放大
- hydration 重复执行
- 浏览器端阻塞

### E. 部署 / Docker / 环境变量
- 尊重仓库当前 Dockerfile、docker-compose、Next standalone 方案
- 不擅自切换包管理器、镜像源或 CI 流程
- 只有在确有问题时，才做最小修改

---

## 15. 修改前必须特别警惕的高风险区域
以下区域一旦改坏，影响范围会很大，必须谨慎：

1. `src/store/useGameStore.ts`
2. `src/components/HydrationProvider.tsx`
3. `src/lib/resilientStorage.ts`
4. `src/app/api/chat/route.ts`
5. `src/app/play/page.tsx`
6. `src/db/schema.ts`
7. `next.config.ts`
8. `Dockerfile`
9. `docker-compose.yml`

这些文件的修改必须是**强理由、强自检、强兼容**。

---

## 16. 代码风格
1. 优先显式类型，不滥用 `any`
2. 复用现有命名风格
3. 保持函数职责单一
4. 只在有价值时写注释，注释用中文
5. 优先小而稳的 helper，不堆超长巨函数
6. 保持 import 路径清晰，优先 `@/*`
7. 不做炫技式抽象
8. 不引入“看起来高级但维护更差”的模式

---

## 17. 完成定义（Definition of Done）
一个任务只有同时满足以下条件，才算完成：

- 代码与仓库当前技术栈一致
- 不破坏 Next.js 16 / React 19 / SSR / hydration
- 不破坏单一主 Store 架构（`useGameStore`）
- 不破坏 `/api/chat` 的 JSON 契约
- 不破坏现有 route topology
- UI / 文案 / 叙事保持中文与产品气质
- 改动范围最小且闭环完整
- 用户拿到后可以直接进入仓库，而不是继续补洞

---


## 18. 默认验证思路
优先遵循仓库当前锁文件与现有脚本。

### 包管理器规则
- 若仓库存在 `pnpm-lock.yaml`，优先使用 `pnpm`
- 若仓库存在 `package-lock.json`，优先使用 `npm`
- 若仓库存在 `yarn.lock`，优先使用 `yarn`

当前仓库已存在 `pnpm-lock.yaml`，默认使用：

- `pnpm build`
- `pnpm test:play`
- `pnpm db:generate`
- `pnpm db:push`

**不要擅自虚构新的 script。**
**不要在 npm / pnpm / yarn 之间随意切换，除非用户明确要求或仓库锁文件发生变化。**
---

## 19. 最终原则
你是在维护一个已经长出真实骨架的项目，不是在空白沙盒里写 demo。

因此请始终做到：
- **尊重现状**
- **优先兼容**
- **最小改动**
- **闭环交付**
- **中文一致**
- **生产可用**