docs: 四文档同步 0.1.36——CSP 红线纪律

AGENTS:版本头 0.1.36(三问题处置/arith 根因)/测试 7011/新增 CSP 红线(严禁 Function()/eval——一律 arith)/
打包版≠开发版(CSP 分野)环境坑 + dev:web 浏览器通道说明(Tabbit 劫持端口用 WSL IP 绕过)
README:测试数 102/7011 + 版本沿革 0.1.36 行
MOD_GUIDE:版本头/尾注 0.1.36 + produceExpr 改用 arith 求值说明(表达式无脚本化能力)
MEMORY:时间线 0.1.36 + 测试数 + 新增 8e 决策(CSP 血案全纪录/军规/真实错误文字教训)
This commit is contained in:
2026-08-24 22:38:37 +08:00
parent 41cffdfdb6
commit 2984d05647
3 changed files with 15 additions and 6 deletions
+3
View File
@@ -31,6 +31,8 @@ SMOKE_TEST=1 SMOKE_SHOTS_DIR=/tmp/opencode/shots npx electron ... # 附
- **`npm rebuild electron esbuild` 会删掉 `node_modules/electron/dist/electron`**Linux 二进制),修复:
`ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js`
- 私有 registry 的 `_auth` token 只在用户级 `~/.npmrc`;项目 `.npmrc` 只保留 registry 映射,不要把 token 写进仓库。
- **打包版≠开发版(CSP 分野)**devvite server 无 CSP)能跑不代表打包版能跑——CSP 性 bug(如 0.1.36 unsafe-eval)只出现在 out/;改完务必 build +(可能的话)真实 GUI 冒烟。
- **WSL 无显示环境调试**`npm run dev:web`vite.web.config.ts,端口 5179 + host 0.0.0.0)纯浏览器通道——Windows 浏览器开 `http://<WSL_IP>:5179`window.api(导出/导入/MOD 扫描)缺失自动跳过,其余全功能等价(存档走浏览器 OPFS)。**注意**:部分浏览器(如 TabbitDance 后台 node)会劫持 localhost 端口段(5173/5179 全 502)——用 WSL 网卡 IP 绕过。
- Linux 无 emoji 字体:**所有图标一律用汉字印章字符**renderer/ui/styles.css 的 `.s-icon/.res-icon/.bld-icon`),不要引入 emoji。
## 架构(0.1.14 大重构后,目录与路径以此为准)
@@ -57,6 +59,7 @@ src/main/ Electron 主进程(app:// 协议 + IPC 存
- **统一随机**:引擎只经 `World.rng`UI 播种用 `RngHub.rollSeed()`、音效白噪用 `RngHub.audioNoise01()`**不要**在逻辑里引入 Math.random()(引擎域 0 处)。渲染层 canvas 粒子散布的 Math.random 不进引擎状态,可留。
- **引擎单线程定论**(0.1.21 实测):`advanceMonth` 2160 月平均 **0.05ms/tick**——无 Worker 化必要;拖帧热点在 UI 渲染与存档(都已在 0.1.20/0.1.21 修)。
- **事件闸**:pending 事件唯一写入入口是 `events.ts``fire(w, id, priority)`(0=普通遇占放弃 / 1=高优 raid·渡劫·大比可顶替被占者,被顶替者入 `eventQueue` 下月兑现不丢失)。**禁止直写 `state.pendingEvent`**(渡劫/破境丹均已改走 fire)。`applyEventChoice` 前置校验 `pendingEvent===id`(陈旧 Modal 二次结算防线)。
- **禁 eval/字符串求值(0.1.36 CSP 红线)**:打包 renderer 的 CSP 禁 unsafe-eval——**严禁 `Function()`/`eval()` 求值表达式**(业务字符串一律走 `data/arith.ts` 纯解析器:数字/L/四则/括号/幂/负号白名单,非法 NaN 不抛;bonusOf/produceExpr/MOD 表达式已全量替换)。开发模式无 CSP 常掩盖此问题——凡是新表达式求值必须用 arith。
- **特效/音效语义出口**`WorldEventBus.onFx?(em: FxEmit)` + `World.emitFx(kind, source?)`(零 rng 消耗);UI 的 `makeBus` 桥接 FxGate`onLog kind` 音效映射保留作兜底。
- **插件架构**0.1.8 起,路径已迁 engine/runtime|kernel):`kernel/plugin.ts` 协议、`runtime/pluginManager.ts` 安装管线(依赖校验/异常回滚/追踪型上下文——注销时钩子全摘)、`plugin-bootstrap.ts` 三核心插件(core-systems/core-data/core-events protected)。事件多池 `world.eventPools`**findEvent 必须带 world 参数查池**。能力卡 12 张经 `viaCap` 注册;tournament/tribulation/apprentice/season 四卡各自内部检查 `w.sysEnabled`(无独立钩子)。
- **MOD 红线(0.1.26 规范)**MOD 只含 JSON 零脚本(`docs/MOD_GUIDE.md`);**禁止新增 rng 消耗**(全局随机序列);不改核心时序(扩展走五口:事件池/模板/词库/灾因/配方);`modPreflight`+`validateMod` 先行(id 冲突用 `findEvent` 权威检测);MOD 只影响**新开档**世界(老档世界变形成档记录);MOD 状态随 `state.plugins` 持久化(对应 `worldGen.npcs` 落档保证读档永稳)。