mini-three-adapter 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +85 -85
- package/README.md +159 -159
- package/dist/build/rollup.js +60 -9
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.js +60 -9
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-MTBMOFAL.js → chunk-CQPWOYLA.js} +27 -14
- package/dist/chunk-CQPWOYLA.js.map +1 -0
- package/dist/{chunk-LB3WL24R.js → chunk-LRR4AEZM.js} +8 -4
- package/dist/chunk-LRR4AEZM.js.map +1 -0
- package/dist/{chunk-3UGQWFH3.js → chunk-MWGTYPGA.js} +87 -27
- package/dist/chunk-MWGTYPGA.js.map +1 -0
- package/dist/{chunk-4UEBRAK6.js → chunk-TMSB525P.js} +15 -6
- package/dist/chunk-TMSB525P.js.map +1 -0
- package/dist/{chunk-WLRQDTSZ.js → chunk-V2IGFCZV.js} +3 -3
- package/dist/{chunk-WLRQDTSZ.js.map → chunk-V2IGFCZV.js.map} +1 -1
- package/dist/{chunk-Z7AMDRN3.js → chunk-WB6MOHR3.js} +8 -5
- package/dist/chunk-WB6MOHR3.js.map +1 -0
- package/dist/core/index.d.ts +15 -5
- package/dist/core/index.js +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +6 -6
- package/dist/platforms/browser.d.ts +2 -2
- package/dist/platforms/browser.js +3 -3
- package/dist/platforms/wechat-game.d.ts +2 -2
- package/dist/platforms/wechat-game.js +4 -4
- package/dist/platforms/wechat-miniprogram.d.ts +2 -2
- package/dist/platforms/wechat-miniprogram.js +4 -4
- package/dist/polyfills/index.d.ts +8 -1
- package/dist/polyfills/index.js +1 -1
- package/dist/{runtime-7uUOoFhC.d.ts → runtime-DnEkKZjo.d.ts} +1 -1
- package/dist/scope.d.ts +1 -1
- package/dist/{types-BzK0LQMa.d.ts → types-X_5SJh4y.d.ts} +7 -0
- package/docs/02-architecture.md +126 -126
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +294 -291
- package/docs/05-build-plugin.md +33 -5
- package/docs/06-platform-notes.md +113 -108
- package/docs/07-integration-guide.md +13 -0
- package/docs/09-testing-and-release.md +208 -206
- package/docs/10-ai-playbook.md +140 -140
- package/docs/11-compat-matrix.md +95 -94
- package/docs/adr/0007-capability-probe-fallback.md +55 -0
- package/docs/adr/README.md +1 -0
- package/llms.txt +68 -65
- package/package.json +10 -4
- package/dist/chunk-3UGQWFH3.js.map +0 -1
- package/dist/chunk-4UEBRAK6.js.map +0 -1
- package/dist/chunk-LB3WL24R.js.map +0 -1
- package/dist/chunk-MTBMOFAL.js.map +0 -1
- package/dist/chunk-Z7AMDRN3.js.map +0 -1
package/docs/10-ai-playbook.md
CHANGED
|
@@ -1,140 +1,140 @@
|
|
|
1
|
-
# 10 · AI 协作手册
|
|
2
|
-
|
|
3
|
-
> 目标:让后续任何一次「用 AI 优化 / 迭代适配层」都能在**最小上下文**下做出正确改动。本文件本身可以直接作为系统提示词的一部分。
|
|
4
|
-
|
|
5
|
-
## 10.1 上下文装载顺序(每次会话先做)
|
|
6
|
-
|
|
7
|
-
1. `AGENTS.md` — 架构不变量、命令、修改边界。
|
|
8
|
-
2. `llms.txt` — 全仓库文件索引与一句话摘要。
|
|
9
|
-
3. `docs/03-module-map.md` — 定位要改的文件与下游影响。
|
|
10
|
-
4. `docs/02-architecture.md#25-架构不变量` — 不得破坏的 10 条规则。
|
|
11
|
-
5. 相关 ADR(`docs/adr/`)— 理解「为什么这样」。
|
|
12
|
-
6. 只读取**目标文件 + 其直接依赖**,不要一次性把整个 `src/` 塞进上下文。
|
|
13
|
-
7. 需要确认平台行为时,读 `docs/06-platform-notes.md`;需要确认能力边界时,读 `docs/11-compat-matrix.md`。
|
|
14
|
-
|
|
15
|
-
## 10.2 让 AI 先回答的三个问题(防止瞎改)
|
|
16
|
-
|
|
17
|
-
在动手前要求模型输出:
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
1. 这次改动涉及哪些模块?(列出文件路径)
|
|
21
|
-
2. 是否触碰 docs/02 中的任意一条架构不变量?哪一条?
|
|
22
|
-
3. 需要新增/修改哪些测试?验收断言是什么?
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
如果第 2 题答「是」但无法给出 ADR,先写 ADR,再改代码。
|
|
26
|
-
|
|
27
|
-
## 10.3 任务型提示词模板
|
|
28
|
-
|
|
29
|
-
### A. 修复「three 报 xxx is not defined」
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
上下文:AGENTS.md、docs/03-module-map.md、src/build/scope-rewrite.ts、src/scope.ts、src/core/runtime.ts
|
|
33
|
-
任务:three@<版本> 在 <场景> 报错 "<错误信息>"。
|
|
34
|
-
请:
|
|
35
|
-
1) 判断缺失的是「全局标识符」还是「DOM 属性」还是「构造器」;
|
|
36
|
-
2) 按 docs/08 的对应小节做最小改动;
|
|
37
|
-
3) 在 tests/ 里补一个复现用例,先让它失败再修复;
|
|
38
|
-
4) 更新 docs/03 / docs/04 / CHANGELOG.md;
|
|
39
|
-
5) 运行 npm run check,贴出结果。
|
|
40
|
-
约束:不得 import three;不得写 globalThis;不得使用字符串全局替换。
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
### B. 新增平台
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
上下文:docs/08#81-新增一个平台、src/core/platform.ts、src/platforms/wechat-game.ts、src/platforms/wx-types.ts
|
|
47
|
-
任务:新增 <平台名> 支持。
|
|
48
|
-
按 docs/08 的 7 步执行,产出:
|
|
49
|
-
- 新平台文件 + 导出 + package.json exports
|
|
50
|
-
- Capabilities 字面量与 docs/11 登记
|
|
51
|
-
- 独立测试文件(用可注入的 mock 宿主)
|
|
52
|
-
- examples/<platform>/ 最小示例
|
|
53
|
-
验收:npm run check 全绿;dispose() 后无残留监听;不调用 wx.createCanvas() 超过一次。
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
### C. 升级 three 大版本
|
|
57
|
-
|
|
58
|
-
```
|
|
59
|
-
上下文:docs/11-compat-matrix.md、docs/01-design-principles.md、src/build/scope-rewrite.ts、src/core/element.ts
|
|
60
|
-
任务:适配 three r<版本>。
|
|
61
|
-
请:
|
|
62
|
-
1) 从官方 Migration Guide 列出该版本新增/移除的全局与 DOM 依赖;
|
|
63
|
-
2) 对照 DEFAULT_GLOBAL_NAMES 与 patchElement 属性表,列出差异;
|
|
64
|
-
3) 逐项补实现 + 测试;
|
|
65
|
-
4) 检查 three/addons vs three/examples/jsm 路径、WebGPU 入口、outputColorSpace;
|
|
66
|
-
5) 更新兼容矩阵与 CHANGELOG。
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### D. 性能 / 包体优化
|
|
70
|
-
|
|
71
|
-
```
|
|
72
|
-
上下文:docs/05、docs/06#65、src/build/assets.ts、examples/wechat-minigame/vite.config.ts
|
|
73
|
-
任务:把首包体积降低到 <N>MB。
|
|
74
|
-
请给出:
|
|
75
|
-
- plugin.api.report() 的基线数据
|
|
76
|
-
- manualChunks / 分包 / Brotli / worker 目录的具体配置 diff
|
|
77
|
-
- 每项措施的验证方式与回退方案
|
|
78
|
-
禁止:静默删除资源、隐式改写 WebGLRenderer、破坏 worker 单目录约束。
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### E. 回归一个 three 官方示例场景
|
|
82
|
-
|
|
83
|
-
```
|
|
84
|
-
上下文:examples/wechat-minigame/、docs/11-compat-matrix.md、docs/08-extension-guide.md
|
|
85
|
-
任务:选取一个 three 官方示例场景 <exampleId>(controls / loaders / postprocessing 类别),
|
|
86
|
-
用 examples/wechat-minigame 的入口与构建配置接入并跑通。
|
|
87
|
-
记录到 docs/11-compat-matrix.md:three 版本、基础库、设备、结果、失败原因、所需 polyfill。
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
## 10.4 AI 输出的自检清单(要求模型逐条确认)
|
|
91
|
-
|
|
92
|
-
- [ ] 没有新增对 `three` 的运行时 import。
|
|
93
|
-
- [ ] 没有 `new Proxy(canvas)` / `Object.setPrototypeOf` / 克隆画布。
|
|
94
|
-
- [ ] 没有第二次 `wx.createCanvas()`。
|
|
95
|
-
- [ ] 所有新增订阅/定时器/全局写入都登记到 `disposers`。
|
|
96
|
-
- [ ] 构建插件的新行为有开关,默认不改变既有语义。
|
|
97
|
-
- [ ] AST 改写仍通过 `path.scope.hasBinding(name, true)`。
|
|
98
|
-
- [ ] 新增导出已同步到 `src/index.ts` 或对应 `core/index.ts`、`package.json exports`、`docs/04`。
|
|
99
|
-
- [ ] 新增/修改的测试通过,且 `npm run check` 全绿。
|
|
100
|
-
- [ ] `CHANGELOG.md`、`docs/03`(若职责变化)、`docs/11`(若能力变化)已更新。
|
|
101
|
-
|
|
102
|
-
## 10.5 常见 AI 反模式(明确禁止)
|
|
103
|
-
|
|
104
|
-
| 反模式 | 为什么错 | 正确做法 |
|
|
105
|
-
| --- | --- | --- |
|
|
106
|
-
| 「直接在 `globalThis` 上补一个 `window` 就好了」 | 破坏零全局污染与 H5 双端 | `scope` + `installGlobals()` 可逆注入 |
|
|
107
|
-
| 「用正则把 `window` 全替换成 `__m3().window`」 | 误伤局部变量、字符串、对象键 | Babel `ReferencedIdentifier` + scope 判定 |
|
|
108
|
-
| 「新建一个 `class HTMLCanvasElement` 包装 wx canvas」 | 微信内部 WeakMap 按对象身份校验 | 就地 `defineProperty` + `Symbol.hasInstance` |
|
|
109
|
-
| 「在运行时把 `WebGLRenderer.render` 猴补丁一下清深度」 | 隐式、不可观测、与 three 版本强耦合 | 应用层显式 `renderer.clearDepth()`,写进文档 |
|
|
110
|
-
| 「把 three 一起打包进适配层省事」 | 体积、版本冲突、许可 | `three` 保持 optional peer + external |
|
|
111
|
-
| 「WebGPU 不支持就 `try/catch` 回退」 | 小游戏根本没有 WebGPU 且 NodeMaterial 无 WebGL 等价物 | 插件 `webgpu` 策略 + 使用 WebGL 构建目标 |
|
|
112
|
-
|
|
|
113
|
-
|
|
114
|
-
## 10.6 机器可读的报告(给自动化 / CI 用)
|
|
115
|
-
|
|
116
|
-
- 运行期:`runtime.report()` → 能力报告文本。
|
|
117
|
-
- 运行期:`runtime.capabilities` → 结构化对象。
|
|
118
|
-
- 构建期:`plugin.api.report()` → `BuildReport`(模块数、改写数、缺失资源、解析失败、WebGPU 告警)。
|
|
119
|
-
- 构建期:`mini-three-assets.json` → 资源清单 + `game.json` 建议 + 构建报告。
|
|
120
|
-
- 项目级:`AGENTS.md` / `llms.txt` / `docs/03-module-map.md` 作为上下文索引。
|
|
121
|
-
|
|
122
|
-
建议把 `parseFailures.length === 0` 与 `missingAssets` 白名单作为 CI 门禁;把 `report()` 附在 bug issue 模板里,便于 AI 直接定位环境差异。
|
|
123
|
-
|
|
124
|
-
## 10.7 一次迭代的标准工作流
|
|
125
|
-
|
|
126
|
-
```
|
|
127
|
-
读 AGENTS.md / llms.txt / docs/03
|
|
128
|
-
↓
|
|
129
|
-
用 §10.2 三问确认边界 → 必要时写 ADR
|
|
130
|
-
↓
|
|
131
|
-
写失败测试(tests/*.test.ts,用 createMockWx)
|
|
132
|
-
↓
|
|
133
|
-
最小实现(只改 docs/03 指向的文件)
|
|
134
|
-
↓
|
|
135
|
-
npm run check(typecheck + 32+ 测试 + tsup)
|
|
136
|
-
↓
|
|
137
|
-
更新 docs/03 / docs/04 / docs/11 / CHANGELOG.md
|
|
138
|
-
↓
|
|
139
|
-
真机验收(docs/09 清单)→ 更新 docs/11 兼容矩阵
|
|
140
|
-
```
|
|
1
|
+
# 10 · AI 协作手册
|
|
2
|
+
|
|
3
|
+
> 目标:让后续任何一次「用 AI 优化 / 迭代适配层」都能在**最小上下文**下做出正确改动。本文件本身可以直接作为系统提示词的一部分。
|
|
4
|
+
|
|
5
|
+
## 10.1 上下文装载顺序(每次会话先做)
|
|
6
|
+
|
|
7
|
+
1. `AGENTS.md` — 架构不变量、命令、修改边界。
|
|
8
|
+
2. `llms.txt` — 全仓库文件索引与一句话摘要。
|
|
9
|
+
3. `docs/03-module-map.md` — 定位要改的文件与下游影响。
|
|
10
|
+
4. `docs/02-architecture.md#25-架构不变量` — 不得破坏的 10 条规则。
|
|
11
|
+
5. 相关 ADR(`docs/adr/`)— 理解「为什么这样」。
|
|
12
|
+
6. 只读取**目标文件 + 其直接依赖**,不要一次性把整个 `src/` 塞进上下文。
|
|
13
|
+
7. 需要确认平台行为时,读 `docs/06-platform-notes.md`;需要确认能力边界时,读 `docs/11-compat-matrix.md`。
|
|
14
|
+
|
|
15
|
+
## 10.2 让 AI 先回答的三个问题(防止瞎改)
|
|
16
|
+
|
|
17
|
+
在动手前要求模型输出:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
1. 这次改动涉及哪些模块?(列出文件路径)
|
|
21
|
+
2. 是否触碰 docs/02 中的任意一条架构不变量?哪一条?
|
|
22
|
+
3. 需要新增/修改哪些测试?验收断言是什么?
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
如果第 2 题答「是」但无法给出 ADR,先写 ADR,再改代码。
|
|
26
|
+
|
|
27
|
+
## 10.3 任务型提示词模板
|
|
28
|
+
|
|
29
|
+
### A. 修复「three 报 xxx is not defined」
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
上下文:AGENTS.md、docs/03-module-map.md、src/build/scope-rewrite.ts、src/scope.ts、src/core/runtime.ts
|
|
33
|
+
任务:three@<版本> 在 <场景> 报错 "<错误信息>"。
|
|
34
|
+
请:
|
|
35
|
+
1) 判断缺失的是「全局标识符」还是「DOM 属性」还是「构造器」;
|
|
36
|
+
2) 按 docs/08 的对应小节做最小改动;
|
|
37
|
+
3) 在 tests/ 里补一个复现用例,先让它失败再修复;
|
|
38
|
+
4) 更新 docs/03 / docs/04 / CHANGELOG.md;
|
|
39
|
+
5) 运行 npm run check,贴出结果。
|
|
40
|
+
约束:不得 import three;不得写 globalThis;不得使用字符串全局替换。
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### B. 新增平台
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
上下文:docs/08#81-新增一个平台、src/core/platform.ts、src/platforms/wechat-game.ts、src/platforms/wx-types.ts
|
|
47
|
+
任务:新增 <平台名> 支持。
|
|
48
|
+
按 docs/08 的 7 步执行,产出:
|
|
49
|
+
- 新平台文件 + 导出 + package.json exports
|
|
50
|
+
- Capabilities 字面量与 docs/11 登记
|
|
51
|
+
- 独立测试文件(用可注入的 mock 宿主)
|
|
52
|
+
- examples/<platform>/ 最小示例
|
|
53
|
+
验收:npm run check 全绿;dispose() 后无残留监听;不调用 wx.createCanvas() 超过一次。
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### C. 升级 three 大版本
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
上下文:docs/11-compat-matrix.md、docs/01-design-principles.md、src/build/scope-rewrite.ts、src/core/element.ts
|
|
60
|
+
任务:适配 three r<版本>。
|
|
61
|
+
请:
|
|
62
|
+
1) 从官方 Migration Guide 列出该版本新增/移除的全局与 DOM 依赖;
|
|
63
|
+
2) 对照 DEFAULT_GLOBAL_NAMES 与 patchElement 属性表,列出差异;
|
|
64
|
+
3) 逐项补实现 + 测试;
|
|
65
|
+
4) 检查 three/addons vs three/examples/jsm 路径、WebGPU 入口、outputColorSpace;
|
|
66
|
+
5) 更新兼容矩阵与 CHANGELOG。
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### D. 性能 / 包体优化
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
上下文:docs/05、docs/06#65、src/build/assets.ts、examples/wechat-minigame/vite.config.ts
|
|
73
|
+
任务:把首包体积降低到 <N>MB。
|
|
74
|
+
请给出:
|
|
75
|
+
- plugin.api.report() 的基线数据
|
|
76
|
+
- manualChunks / 分包 / Brotli / worker 目录的具体配置 diff
|
|
77
|
+
- 每项措施的验证方式与回退方案
|
|
78
|
+
禁止:静默删除资源、隐式改写 WebGLRenderer、破坏 worker 单目录约束。
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### E. 回归一个 three 官方示例场景
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
上下文:examples/wechat-minigame/、docs/11-compat-matrix.md、docs/08-extension-guide.md
|
|
85
|
+
任务:选取一个 three 官方示例场景 <exampleId>(controls / loaders / postprocessing 类别),
|
|
86
|
+
用 examples/wechat-minigame 的入口与构建配置接入并跑通。
|
|
87
|
+
记录到 docs/11-compat-matrix.md:three 版本、基础库、设备、结果、失败原因、所需 polyfill。
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 10.4 AI 输出的自检清单(要求模型逐条确认)
|
|
91
|
+
|
|
92
|
+
- [ ] 没有新增对 `three` 的运行时 import。
|
|
93
|
+
- [ ] 没有 `new Proxy(canvas)` / `Object.setPrototypeOf` / 克隆画布。
|
|
94
|
+
- [ ] 没有第二次 `wx.createCanvas()`。
|
|
95
|
+
- [ ] 所有新增订阅/定时器/全局写入都登记到 `disposers`。
|
|
96
|
+
- [ ] 构建插件的新行为有开关,默认不改变既有语义。
|
|
97
|
+
- [ ] AST 改写仍通过 `path.scope.hasBinding(name, true)`。
|
|
98
|
+
- [ ] 新增导出已同步到 `src/index.ts` 或对应 `core/index.ts`、`package.json exports`、`docs/04`。
|
|
99
|
+
- [ ] 新增/修改的测试通过,且 `npm run check` 全绿。
|
|
100
|
+
- [ ] `CHANGELOG.md`、`docs/03`(若职责变化)、`docs/11`(若能力变化)已更新。
|
|
101
|
+
|
|
102
|
+
## 10.5 常见 AI 反模式(明确禁止)
|
|
103
|
+
|
|
104
|
+
| 反模式 | 为什么错 | 正确做法 |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| 「直接在 `globalThis` 上补一个 `window` 就好了」 | 破坏零全局污染与 H5 双端 | `scope` + `installGlobals()` 可逆注入 |
|
|
107
|
+
| 「用正则把 `window` 全替换成 `__m3().window`」 | 误伤局部变量、字符串、对象键 | Babel `ReferencedIdentifier` + scope 判定 |
|
|
108
|
+
| 「新建一个 `class HTMLCanvasElement` 包装 wx canvas」 | 微信内部 WeakMap 按对象身份校验 | 就地 `defineProperty` + `Symbol.hasInstance` |
|
|
109
|
+
| 「在运行时把 `WebGLRenderer.render` 猴补丁一下清深度」 | 隐式、不可观测、与 three 版本强耦合 | 应用层显式 `renderer.clearDepth()`,写进文档 |
|
|
110
|
+
| 「把 three 一起打包进适配层省事」 | 体积、版本冲突、许可 | `three` 保持 optional peer + external |
|
|
111
|
+
| 「WebGPU 不支持就 `try/catch` 回退」 | 小游戏根本没有 WebGPU 且 NodeMaterial 无 WebGL 等价物 | 插件 `webgpu` 策略 + 使用 WebGL 构建目标 |
|
|
112
|
+
| 「能力探测时直接 `wx.createCanvas().getContext('webgl2')`」 | 偷走唯一上屏画布、且用默认属性抢先建上下文 | 用 `wx.createOffscreenCanvas()`;仅按 ADR-0007 显式回退 |
|
|
113
|
+
|
|
114
|
+
## 10.6 机器可读的报告(给自动化 / CI 用)
|
|
115
|
+
|
|
116
|
+
- 运行期:`runtime.report()` → 能力报告文本。
|
|
117
|
+
- 运行期:`runtime.capabilities` → 结构化对象。
|
|
118
|
+
- 构建期:`plugin.api.report()` → `BuildReport`(模块数、改写数、缺失资源、解析失败、WebGPU 告警)。
|
|
119
|
+
- 构建期:`mini-three-assets.json` → 资源清单 + `game.json` 建议 + 构建报告。
|
|
120
|
+
- 项目级:`AGENTS.md` / `llms.txt` / `docs/03-module-map.md` 作为上下文索引。
|
|
121
|
+
|
|
122
|
+
建议把 `parseFailures.length === 0` 与 `missingAssets` 白名单作为 CI 门禁;把 `report()` 附在 bug issue 模板里,便于 AI 直接定位环境差异。
|
|
123
|
+
|
|
124
|
+
## 10.7 一次迭代的标准工作流
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
读 AGENTS.md / llms.txt / docs/03
|
|
128
|
+
↓
|
|
129
|
+
用 §10.2 三问确认边界 → 必要时写 ADR
|
|
130
|
+
↓
|
|
131
|
+
写失败测试(tests/*.test.ts,用 createMockWx)
|
|
132
|
+
↓
|
|
133
|
+
最小实现(只改 docs/03 指向的文件)
|
|
134
|
+
↓
|
|
135
|
+
npm run check(typecheck + 32+ 测试 + tsup)
|
|
136
|
+
↓
|
|
137
|
+
更新 docs/03 / docs/04 / docs/11 / CHANGELOG.md
|
|
138
|
+
↓
|
|
139
|
+
真机验收(docs/09 清单)→ 更新 docs/11 兼容矩阵
|
|
140
|
+
```
|
package/docs/11-compat-matrix.md
CHANGED
|
@@ -1,94 +1,95 @@
|
|
|
1
|
-
# 11 · 兼容矩阵
|
|
2
|
-
|
|
3
|
-
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
-
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
-
|
|
6
|
-
## 11.1 three.js 版本
|
|
7
|
-
|
|
8
|
-
| three 版本 | 状态 | 说明 |
|
|
9
|
-
| --- | --- | --- |
|
|
10
|
-
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
-
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
-
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
-
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
-
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
-
|
|
16
|
-
### 每次 three 升级需要复核的点
|
|
17
|
-
|
|
18
|
-
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
-
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
-
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
-
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
-
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
-
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
-
|
|
25
|
-
## 11.2 微信基础库 / 平台
|
|
26
|
-
|
|
27
|
-
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
-
| --- | --- | --- | --- |
|
|
29
|
-
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
-
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
-
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ |
|
|
32
|
-
|
|
|
33
|
-
| `wx.
|
|
34
|
-
| `
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
| `
|
|
57
|
-
| `document.
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `URL`
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
1
|
+
# 11 · 兼容矩阵
|
|
2
|
+
|
|
3
|
+
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
+
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
+
|
|
6
|
+
## 11.1 three.js 版本
|
|
7
|
+
|
|
8
|
+
| three 版本 | 状态 | 说明 |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
+
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
+
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
+
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
+
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
+
|
|
16
|
+
### 每次 three 升级需要复核的点
|
|
17
|
+
|
|
18
|
+
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
+
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
+
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
+
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
+
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
+
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
+
|
|
25
|
+
## 11.2 微信基础库 / 平台
|
|
26
|
+
|
|
27
|
+
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
+
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
+
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;探测不到时回退到第二次 `createCanvas()`([ADR-0007](./adr/0007-capability-probe-fallback.md)) |
|
|
32
|
+
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
+
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
34
|
+
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
35
|
+
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
36
|
+
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
37
|
+
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
38
|
+
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
39
|
+
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
40
|
+
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
41
|
+
|
|
42
|
+
## 11.3 平台支持
|
|
43
|
+
|
|
44
|
+
| 平台 | 入口 | 状态 | 备注 |
|
|
45
|
+
| --- | --- | --- | --- |
|
|
46
|
+
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
47
|
+
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
48
|
+
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | 真实 DOM 不被覆盖;可跑 Node 测试 |
|
|
49
|
+
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
50
|
+
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
51
|
+
|
|
52
|
+
## 11.4 Web / DOM API 覆盖
|
|
53
|
+
|
|
54
|
+
| API | 提供方式 | 状态 |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
57
|
+
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
58
|
+
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
59
|
+
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
60
|
+
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
61
|
+
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
62
|
+
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
63
|
+
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
64
|
+
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
65
|
+
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
66
|
+
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
67
|
+
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
68
|
+
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
69
|
+
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
70
|
+
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
71
|
+
| `ResizeObserver` | no-op | ⚠️ |
|
|
72
|
+
| 完整 DOM(布局、CSS、事件冒泡树) | 不提供 | ❌ 超出范围 |
|
|
73
|
+
|
|
74
|
+
## 11.5 场景回归记录
|
|
75
|
+
|
|
76
|
+
以 three 官方示例场景为主体建立回归集,用 `examples/` 的三个平台工程逐一接入验证。
|
|
77
|
+
|
|
78
|
+
| 类别 | 覆盖目标 | 状态 | 备注 |
|
|
79
|
+
| --- | --- | --- | --- |
|
|
80
|
+
| `controls_*` | OrbitControls / TrackballControls / TransformControls 的多指交互 | ⬜ 未回归 | 优先验证 pointerId、capture、`pointercancel` |
|
|
81
|
+
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
82
|
+
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
83
|
+
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
84
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 55 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
85
|
+
|
|
86
|
+
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
87
|
+
|
|
88
|
+
## 11.6 已知限制汇总
|
|
89
|
+
|
|
90
|
+
1. 不模拟 WebGPU;`three/webgpu` 项目需改用 WebGL 构建目标。
|
|
91
|
+
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
92
|
+
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
93
|
+
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
94
|
+
5. 对象 URL 是 `mini-three-blob:` + `data:`,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀判断,需要适配。
|
|
95
|
+
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# ADR-0007 · 能力探测允许「主画布回退」与「无法探测」语义
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-10
|
|
5
|
+
- 影响模块:`src/core/capabilities.ts`、`src/platforms/wechat-common.ts`、`src/platforms/wechat-game.ts`、`src/platforms/wechat-miniprogram.ts`、`src/types.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
架构不变量之一是「只有一个上屏画布」,能力探测因此被限定为**只能**用 `wx.createOffscreenCanvas()`,绝不调用 `wx.createCanvas()`。
|
|
10
|
+
|
|
11
|
+
实际开发中暴露了两个问题:
|
|
12
|
+
|
|
13
|
+
1. **被探测对象 ≠ 被使用对象。** 上屏画布支持 WebGL2,离屏画布不支持(或 `createOffscreenCanvas` 根本不存在),是微信各基础库 / 机型的常态。微信开发者工具 3.18.0 模拟器就是这种情况:`capabilities.webgl2 === false`,但 three 的 `WebGLRenderer` 用 `#version 300 es` 正常渲染。
|
|
14
|
+
2. **「探测不到」被当成了「不支持」。** `probeContext` 第一个分支直接 `return false`,于是「这个宿主没提供探测手段」被写成了「这个宿主没有 WebGL2」。宿主若据此降级后端或画质,就会在支持 WebGL2 的设备上错误降级,排查色彩 / 精度问题时也会被带偏。
|
|
15
|
+
|
|
16
|
+
## 决策
|
|
17
|
+
|
|
18
|
+
1. `probeContext` 返回 `boolean | undefined`:
|
|
19
|
+
- `true` / `false` 表示**实测结果**;
|
|
20
|
+
- `undefined` 表示**无法探测**。
|
|
21
|
+
2. 探测顺序:离屏实测 → (仅当调用方显式允许时)第二次 `wx.createCanvas()` 实测 → 仍无法判定则返回 `undefined`。
|
|
22
|
+
3. `detectCapabilities` 把 `undefined` 当作未知,退回基础库版本启发式(`>= 2.20.0`),并用新增的 `capabilities.webgl2Source`(`'probe' | 'inferred' | 'override'`)标明来源;此时 `warnOnce` 提示一次。
|
|
23
|
+
|
|
24
|
+
## 理由
|
|
25
|
+
|
|
26
|
+
- 第二次 `wx.createCanvas()` 在微信里**保证**得到离屏画布(上屏画布只有第一次调用才返回),这与 `createOffscreenCanvasRaw` 里已有的兜底是同一机制,不违反「只有一个上屏画布」的本意:本意是**不要抢走那块上屏画布**,而不是禁用该 API。
|
|
27
|
+
- 因此回退**必须**在上屏画布已经解析之后调用,并且由调用方显式 opt-in(`allowCanvasFallback`)。`wechat-game` 的 `getScreenCanvas()` 就在探测之前,所以传 `true`;`wechat-miniprogram` 的画布节点来自选择器查询,不能这样探测,保持不传。
|
|
28
|
+
- `webgl2Source` 让「这份报告里的 `false` 到底是实测还是猜测」一眼可见,这是本次缺陷里最伤排查成本的部分。
|
|
29
|
+
|
|
30
|
+
## 后果
|
|
31
|
+
|
|
32
|
+
正面:
|
|
33
|
+
|
|
34
|
+
- 模拟器 / 老基础库上不再把支持 WebGL2 的主画布误判为不支持;
|
|
35
|
+
- 能力报告自带来源,宿主可以据此选择「信任」或「自己覆盖」。
|
|
36
|
+
|
|
37
|
+
负面 / 风险:
|
|
38
|
+
|
|
39
|
+
- 回退分支会多创建一个 1×1 画布(仅在离屏探测失败时发生),计入画布数量;
|
|
40
|
+
- `'inferred'` 仍然是猜测。若宿主真的不支持 WebGL2 而基础库版本又较新,报告会偏乐观——但 three r163+ 自身会在创建上下文时明确失败,比静默降级更容易发现;
|
|
41
|
+
- `probeContext` 的返回类型从 `boolean` 放宽为 `boolean | undefined`,属于**类型放宽**:既有 `(type) => boolean` 的实现仍然可赋值。
|
|
42
|
+
|
|
43
|
+
## 被否决的备选方案
|
|
44
|
+
|
|
45
|
+
| 方案 | 否决理由 |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| 继续只用离屏探测 | 就是本次缺陷本身 |
|
|
48
|
+
| 直接探测上屏画布 `getContext('webgl2')` | 会用默认属性抢先创建真实 GL 上下文,three 之后再带 `antialias` 等属性请求会拿到同一个上下文,渲染属性被静默改变 |
|
|
49
|
+
| 把 `webgl2` 改成 `boolean \| null` | 破坏公开字段语义,所有读取处都要改;用 `webgl2Source` 附加信息可达到同样诊断效果 |
|
|
50
|
+
| 探测不到就一律当 `false` | 会把未知伪装成结论,正是要修的问题 |
|
|
51
|
+
|
|
52
|
+
## 验证方式
|
|
53
|
+
|
|
54
|
+
- `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas`、离屏不可用时回退、离屏返回 false 而主画布返回 true、完全无法探测时返回 `undefined`、`webgl2Source` 三种取值。
|
|
55
|
+
- `tests/runtime.test.ts`:小游戏运行时能力报告仍包含 `wechat-game` 与 `WebGL2`。
|
package/docs/adr/README.md
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
| [0004](./0004-in-place-patching.md) | 就地 patch 画布,不改原型、不用 Proxy | Accepted |
|
|
11
11
|
| [0005](./0005-webgl2-only.md) | WebGL2 优先,不静默降级到 WebGL1 | Accepted |
|
|
12
12
|
| [0006](./0006-zero-three-dependency.md) | 运行时零 `three` 依赖,构建/运行严格隔离 | Accepted |
|
|
13
|
+
| [0007](./0007-capability-probe-fallback.md) | 能力探测允许主画布回退,`undefined` 表示「无法探测」 | Accepted |
|
|
13
14
|
|
|
14
15
|
模板(新增 ADR 时复制):
|
|
15
16
|
|