oneshard CLAUDE.md

深空沙盒 · 项目约定

对人类和 AI agent 同等可读可玩的持久宇宙 4X 沙盒。当前处于 Phase 0（headless 情绪验证）。

常用命令

npm test                                    # vitest 全量
npm run typecheck                           # tsc --noEmit
npm run create-universe -- --name alpha     # 创世（--seed --systems --civs --tick-seconds）
npm run server -- --data data/alpha         # 起服务（--port 8420 --tick-ms 快进）
npm run cli -- --token dsx_xxx              # 人类终端客户端

铁律（改代码前读）

1. 契约先行：MCP 工具的名字/入参/返回形状改动，必须先改 docs/api-contract.md，再改 src/server/mcp.ts 与 CLI。
2. 无作弊视野：任何给玩家的数据必须经 src/views/views.ts 脱敏。永不输出：他人 token/配额/收件箱、迷雾外实时信息。新增字段时先想"这会不会泄露迷雾"。
3. 确定性：引擎（src/engine、src/core）禁止 Date.now()/Math.random()——随机走 Rng.forState(state)（游标持久化），时间只有 state.tick。墙钟只允许出现在 src/server 调度层。
4. 抛错=零副作用：行动函数（src/actions）必须先完成全部校验再 spendQuota 再变更；抛 GameError 时不允许有任何状态改动。
5. 变更段禁止 await：并发安全靠 Node 单线程 + 同步变更段（见 GameRuntime.runCivAction）。在行动/tick 的变更路径里引入 await 会制造竞态。
6. 平衡数值全部住在 src/core/constants.ts，标注均为临时值；改平衡不要动公式所在的引擎代码。
7. 设计冲突时回到四支柱裁决（docs/vision.md）：同规则同接口 / 决策质量>行动频率 / 事实层可欺骗物理层不可违反 / 渲染只是另一个客户端。
8. 测试先行（TDD，2026-07-18 起）：任何 feature/bugfix 按 红→绿→部署验证 三段走： ①先写会失败的测试（引擎/服务端=vitest；数值平衡=balance-sim 矩阵基线；前端=本地起服 Playwright 断言关键行为），确认红；②实现到绿（typecheck + vitest 全量）；③部署后生产 冒烟（curl 端点 + 前端改动必须 Playwright 实测生产页面真实行为，包括 zh/en 双语态）。 线上缺陷修复必须附带一条修复前会失败的回归测试（例：tests/auth.test.ts 静态缓存头）。 子 agent 交付不算完成——lead 必须复验可见行为后才可提交；仅 node --check/文本 grep 不构成前端验收（2026-07-18 编年史缓存脏读事故的教训）。

子 agent 分工（Claude 任 lead 总负责，汇总与最终交付）

开发、文档、code review 三类工作都应充分委派给子 agent 并行执行：

• codex（gpt-5.6-sol，已是 ~/.codex 默认）：UI/视觉/前端为主，亦可承接一般开发与 code review。 codex exec --sandbox workspace-write -C <repo> --color never - < /tmp/brief.md
• GLM 5.2（opencode coding plan）：文档/设计文集为主，亦可承接开发与 review。 opencode run -m zai-coding-plan/glm-5.2 "$(cat /tmp/brief.md)"

协作约定：brief 落盘 /tmp/*.md（必读文件清单+交付物+硬约束）；每个 agent 划互不相交的 文件范围；共享契约（docs/api-contract.md）由 lead 先行改定，子 agent 只读；子 agent 禁跑 git；两者都后台并行跑（run_in_background），lead 验收集成后统一提交。