@wovoon/polaris 0.6.1 → 0.6.3

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/docs/errors.md ADDED
@@ -0,0 +1,184 @@
1
+ # 错误目录(协议 1)
2
+
3
+ 所有协议/结构类错误的**原文、触发条件与修复步骤**。平台报错与此处一字不差;
4
+ 每个错误附锚点供 AI 工具引用(如 `wovoon:errors#manifest-unknown-field`)。
5
+ API 错误响应形态:`{"success":false,"message":"…","code":"…"}`,SDK 会抛出带 `code` 的 `Error`。
6
+
7
+ ## 上传 / 清单(扫描阶段)
8
+
9
+ ### <a id="marker-missing"></a>未检测到 .wovoon 标识文件
10
+
11
+ > 未在作品包中检测到 .wovoon 标识文件,请检查作品包是否支持在 wovoon 上运行(可在包根目录添加 .wovoon 文件后重新上传,参见 wovoon 协议 PROTOCOL.md)
12
+
13
+ - 触发:zip 内没有任何 `.wovoon`(或历史别名 `.wovoongame`)。
14
+ - 修复:在**包根目录**(不是压缩包外层)创建 `.wovoon`,内容见 [manifest.md](manifest.md)。空文件即可通过。
15
+
16
+ ### <a id="manifest-too-large"></a>清单超 4 KB
17
+
18
+ > .wovoon 清单文件超过 4 KB:请只保留 protocol 与 capabilities 字段(示例 {"protocol":1,"capabilities":["identity"]})后重新上传
19
+
20
+ - 修复:清单只放协议字段,业务配置放应用自己的文件里。
21
+
22
+ ### <a id="manifest-not-json"></a>不是合法 JSON
23
+
24
+ > .wovoon 清单不是合法 JSON(示例:{"protocol":1,"capabilities":["identity"]}),请修正后重新上传
25
+
26
+ ### <a id="manifest-not-object"></a>不是 JSON 对象
27
+
28
+ > .wovoon 清单必须是 JSON 对象(示例:{"protocol":1,"capabilities":["identity"]}),请修正后重新上传
29
+
30
+ ### <a id="manifest-unknown-field"></a>未知字段
31
+
32
+ > .wovoon 清单包含未知字段 "foo":协议 1 只允许 protocol、capabilities、entry 与 backend,请删除后重新上传
33
+
34
+ - 修复:删除该字段。协议字段只加不改不删;新语义等平台扩展协议版本。
35
+
36
+ ### <a id="manifest-protocol"></a>protocol 版本不支持
37
+
38
+ > .wovoon 清单的 protocol 只支持 1(当前平台协议版本),请改为 1 或删除该字段后重新上传
39
+
40
+ ### <a id="manifest-capabilities-not-array"></a>capabilities 不是数组
41
+
42
+ > .wovoon 清单的 capabilities 必须是字符串数组(如 ["identity","collection:scores"]),请修正后重新上传
43
+
44
+ ### <a id="manifest-bad-capability"></a>能力名非法
45
+
46
+ > .wovoon 清单的能力名 "Scores" 不被协议 1 认识:合法取值为 identity、function、room 或 collection:<名称>(名称 2-32 位小写字母/数字/下划线),请修正后重新上传
47
+
48
+ - 修复:集合名改小写(`collection:scores`);或改用保留能力名。
49
+
50
+ ## 上传 / 内容安全(扫描阶段)
51
+
52
+ ### <a id="credential-file"></a>凭据文件
53
+
54
+ > 网页应用包包含不应发布的凭据文件
55
+
56
+ - 触发:包内含 `.env`、`id_rsa`、`id_ed25519`、`.p12`、`.pfx`。
57
+ - 修复:从包里删除;构建时排除(如 zip 前清理)。密钥放平台侧配置而不是作品包。
58
+
59
+ ### <a id="suspected-secret"></a>疑似密钥泄露
60
+
61
+ > 应用包疑似包含密钥、口令或私钥:path/to/file.js
62
+
63
+ - 触发:文本文件命中私钥块 / AKIA·LTAI·ghp_·sk- 前缀 / `password=...` 赋值 / 带凭据的数据库连接串。
64
+ - 修复:删除硬编码密钥,改从运行时配置读取。
65
+
66
+ ### <a id="cloud-metadata"></a>云元数据地址
67
+
68
+ > 应用包包含云元数据服务访问地址:path/to/file.js
69
+
70
+ - 触发:出现 `169.254.169.254`、`metadata.google.internal`、`100.100.100.200/latest/meta-data`。
71
+
72
+ ### <a id="symlink"></a>符号链接
73
+
74
+ > 压缩包包含符号链接
75
+
76
+ ## 静态托管(发布阶段)
77
+
78
+ ### <a id="hosting-no-index"></a>缺少入口
79
+
80
+ > 静态包中没有 index.html,请上传构建后的 dist/build 成品
81
+
82
+ - 修复:上传**构建后的产物**(vite/CRA/webpack 的 dist),不是源码目录。
83
+
84
+ ### <a id="hosting-duplicate-index"></a>多个并列入口
85
+
86
+ > 静态包中存在多个并列 index.html,请只保留一个站点根目录
87
+
88
+ - 触发:例如 `a/index.html` 与 `b/index.html` 同层并列。
89
+ - 修复:压缩包外层只包一个站点根目录。
90
+
91
+ ### <a id="hosting-too-large"></a>包体超限
92
+
93
+ > 静态包文件数超出限制 / 静态包展开后大小超出限制(默认 20,000 文件 / 1 GB)
94
+
95
+ ## 云能力(运行时)
96
+
97
+ ### <a id="capability-not-declared"></a>能力未声明
98
+
99
+ > 作品未声明云能力 collection:scores:请在作品包根目录的 .wovoon 清单中加入 capabilities 声明后重新上传(参见 wovoon 协议 PROTOCOL.md)
100
+
101
+ - 触发:调用 `collection('scores')` 但 manifest 没声明 `collection:scores`。
102
+ - 修复:`.wovoon` 加声明 → `wovoon validate` → 重新上传发布。
103
+
104
+ ### <a id="login-to-write"></a>游客写数据
105
+
106
+ > 登录后才能写入云数据 / 登录后才能删除云数据
107
+
108
+ - 修复:游戏侧先判断 `session.loggedIn`,引导玩家登录平台(`wovoon dev --player 名字` 可模拟登录)。
109
+
110
+ ### <a id="not-owner"></a>越权操作他人文档
111
+
112
+ > 只能读取自己的文档 / 只能操作自己的文档
113
+
114
+ - 修复:只 set/remove `query({ownerOnly:true})` 或 `add` 返回的文档 id。
115
+
116
+ ### <a id="doc-too-large"></a>文档超限
117
+
118
+ > 单个文档不能超过 64 KB / 集合文档数已达上限(10000 条)/ 集合数量已达上限(8 个)
119
+
120
+ - 修复:拆集合或拆文档;文档内容必须是 JSON 对象。
121
+
122
+ ### <a id="doc-not-json"></a>文档形态错误
123
+
124
+ > 文档内容不能为空 / 文档内容不是合法 JSON / 文档内容必须是 JSON 对象
125
+
126
+ - 修复:`WovoonCloud.collection(x).add({...})` 传对象(SDK 负责序列化),不要手传字符串。
127
+
128
+ ### <a id="join-invalid"></a>join 声明不正确
129
+
130
+ > join 必须是 JSON 对象(如 {"author":"users.authorId"} 或 {"comments":["comments","postId"]}) /
131
+ > 一次查询最多声明 2 个 join / join 别名只能以字母开头、由字母数字下划线组成,最长 32 字符 /
132
+ > join 声明不正确:单值连接用 "集合.字段",多值连接用 ["集合", "字段"]
133
+
134
+ - 修复:单值连接 `{"别名": "集合.字段"}`(主文档字段值 = 目标文档 id);
135
+ 多值连接 `{"别名": ["集合", "字段"]}`(目标字段值 = 主文档 id);每次最多 2 个。
136
+ 被连接集合还须在 `.wovoon` 的 capabilities 中声明,否则见
137
+ [能力未声明](#capability-not-declared)。
138
+
139
+ ## 云函数与房间(运行时)
140
+
141
+ ### <a id="function-not-declared"></a>函数能力未声明
142
+
143
+ > 作品未声明云能力 function:请在作品包根目录的 .wovoon 清单中加入 capabilities 声明后重新上传(参见 wovoon 协议 PROTOCOL.md)
144
+
145
+ ### <a id="function-missing"></a>函数不存在
146
+
147
+ > 云函数不存在:settle(请把 functions/settle.js 放进作品包后重新发布)
148
+
149
+ - 修复:文件名=函数名,必须位于站点根 `functions/` 目录(与 index.html 同级)。
150
+
151
+ ### <a id="function-server-write"></a>函数写普通集合
152
+
153
+ > 云函数只能写入 writeRule=SERVER 的集合:请创作者在集合管理中把 scores 的写权限设为 SERVER
154
+
155
+ - 修复:创作者调用 `PUT /api/cloud/manage/{app}/collections/{name}` 设 `{"writeRule":"SERVER"}`。
156
+
157
+ ### <a id="function-limits"></a>函数超限
158
+
159
+ > 云函数执行超时(3 秒) / 云函数入参超过 32 KB 上限 / 云函数返回值超过 32 KB 上限 / 云函数日调用次数已达上限(200000 次)
160
+
161
+ ### <a id="room-capacity"></a>房间超限
162
+
163
+ > 房间人数已满(256 人) / 同一玩家的房间连接数已达上限(4 个) / 该作品的房间数量已达上限(5000 个)
164
+
165
+ ## 手机兼容性预检(提交阶段)
166
+
167
+ ### <a id="compat-viewport-missing"></a>缺少 viewport
168
+
169
+ > 声明支持手机,但页面缺少 viewport 配置
170
+
171
+ - 修复:入口 HTML 加 `<meta name="viewport" content="width=device-width,initial-scale=1">`。
172
+
173
+ ### <a id="compat-keyboard-only"></a>仅键盘操作
174
+
175
+ > 声明支持触屏,但制品只检测到键盘操作
176
+
177
+ - 修复:用 `pointerdown`/`click` 事件而不是只有 `keydown`。
178
+
179
+ 通过判据:检出 `click`/`pointer`(含 `mousedown`)可交互输入 **且** viewport 正确 →
180
+ `已检出可交互输入且 viewport 正确,手机兼容性预检通过`。
181
+
182
+ ### manifest-backend
183
+
184
+ `backend` 只接受 `platform` 或 `external`;自建后端 Web 应用使用 `external`,前端仍上传到 Wovoon 托管。不是后端 URL,不接受对象、空值或其他字符串。
package/docs/index.md ADDED
@@ -0,0 +1,65 @@
1
+ # 快速开始:五分钟发布一个 wovoon 应用
2
+
3
+ 面向人类与 AI coding 工具。全程不需要浏览器调试后端、不需要登录任何账号即可本地完成开发与校验。
4
+
5
+ ## 0) 安装 CLI
6
+
7
+ npm install -g @wovoon/cli
8
+
9
+ (仓库内开发:`git clone` 本仓库后 `npm install && npm run build`,CLI 位于 `cli/dist/wovoon.js`。)
10
+
11
+ ## 1) init —— 从官方模板创建
12
+
13
+ wovoon init my-app --template game --name 我的应用
14
+
15
+ 模板可选:
16
+
17
+ | 模板 | 内容 | 适合 |
18
+ |---|---|---|
19
+ | `game` | 计分 + 云存档 + 排行榜(identity + collection:scores) | 小游戏 / 交互演示 |
20
+ | `minimal` | 单页 + 云身份(identity) | 服务性应用 / 自由改造起点 |
21
+
22
+ 生成的目录:
23
+
24
+ my-app/
25
+ .wovoon ← 平台契约清单(能力声明)
26
+ index.html ← 引入 /api/cloud/sdk.js 的入口页
27
+ README.md
28
+
29
+ ## 2) dev —— 本地模拟大后台
30
+
31
+ cd my-app
32
+ wovoon dev --player 测试玩家
33
+
34
+ - 作品运行在 `http://localhost:5179/api/public/static/{id}/`(与生产同路径,SDK 自动识别作品)。
35
+ - 云能力端点与生产逐字一致:`/api/cloud/session`、`/api/cloud/{app}/collections/{name}/docs`。
36
+ - `--player 名字` 模拟登录玩家(可写云数据);不带参数为游客(读公开集合、不可写)。
37
+ - 校验与配额与生产一致(能力门禁、8 集合 / 万文档 / 64KB / limit≤100),报错文案一字不差。
38
+
39
+ 用 curl 即可验证(无需浏览器):
40
+
41
+ curl -X POST localhost:5179/api/cloud/session -H 'Content-Type: application/json' -d '{}'
42
+ curl -X POST "localhost:5179/api/cloud/dec0de11-0000-4000-8000-000000000001/collections/scores/docs" \
43
+ -H 'Content-Type: application/json' -d '{"data":"{\"score\":42,\"name\":\"测试玩家\"}"}'
44
+
45
+ ## 3) validate —— 生产规则镜像校验
46
+
47
+ wovoon validate
48
+
49
+ 本地通过 = 上传 wovoon 平台不会被协议/结构类规则拒绝(内容机审除外)。加 `--json` 得到机器可读报告。
50
+
51
+ ## 4) 发布
52
+
53
+ 把**项目目录打包为 zip**(`.wovoon` 必须在包根目录),在 wovoon 创作者平台(creator.wovoon.com)创建作品并上传:
54
+
55
+ 1. 上传图标(PNG)与宣传视频(MP4)——平台要求;
56
+ 2. 上传作品包 zip,提交审核;
57
+ 3. 机审自动通过后开通"静态托管",平台分配运行地址并发布。
58
+
59
+ 详细字段与校验规则见 [manifest.md](manifest.md);上架失败的报错对照 [errors.md](errors.md)。
60
+
61
+ ## AI 工具注意事项
62
+
63
+ - 任何协议类报错都自带修复指引;修完本地跑 `wovoon validate` 确认。
64
+ - 不要在作品包里提交 `.env`、私钥、构建工具目录(node_modules/dist 构建产物除外——上传的是构建后的成品)。
65
+ - `.wovoon` 只是声明,不会被平台对外发布;`.wovoongame` 是历史别名,内容以 `.wovoon` 优先。
@@ -0,0 +1,74 @@
1
+ # `.wovoon` 清单规范(协议 1)
2
+
3
+ `.wovoon` 是 wovoon 作品包的平台契约标识文件,放在**包根目录**。它同时承担两个职责:
4
+
5
+ 1. 标识"这是一个 wovoon 应用"(没有它,作品包会被拒绝上传);
6
+ 2. 声明应用使用的云能力(未声明的能力调用会被平台拒绝)。
7
+
8
+ ## 语法
9
+
10
+ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"protocol":1}`。
11
+
12
+ ```json
13
+ {
14
+ "protocol": 1,
15
+ "capabilities": ["identity", "collection:scores"]
16
+ }
17
+ ```
18
+
19
+ | 字段 | 类型 | 必填 | 说明 |
20
+ |---|---|---|---|
21
+ | `backend` | 字符串 | 否 | `platform` / `external`;external 表示自建后端 Web 应用,前端仍托管于平台 |
22
+ | `entry` | 字符串 | 否 | 包内 HTML 相对路径,不得以 `/` 开头或包含 `..` |
23
+ | `protocol` | 整数 | 否 | 协议版本,当前唯一支持 `1`;缺省为 1 |
24
+ | `capabilities` | 字符串数组 | 否 | 声明的能力;缺省为空 |
25
+
26
+ 协议 1 **不允许其他字段**——多余字段会在上传扫描时被拒绝(见 [errors.md](errors.md#manifest))。
27
+
28
+ ## 能力命名(冻结)
29
+
30
+ | 能力 | 含义 | 状态 |
31
+ |---|---|---|
32
+ | `identity` | 云身份:每作品稳定 playerId、登录态、昵称头像 | 可用 |
33
+ | `collection:<名称>` | 数据集合:文档 CRUD、查询排序、权限 | 可用 |
34
+ | `function` | 云函数:受限 Node 沙箱(限时/限内存/禁出网)内运行服务端逻辑 | 可用 |
35
+ | `room` | 房间实时通道:WebSocket 房间中继(快节奏多人) | 可用 |
36
+
37
+ - 集合名称:**2-32 位,小写字母开头,仅小写字母/数字/下划线**,如 `collection:scores`、`collection:player_profiles`。
38
+ - 只声明会用到的集合;改名集合时同步改 manifest。
39
+ - 历史别名 `.wovoongame` 仍被接受,**内容以 `.wovoon` 为准**;新项目一律用 `.wovoon`。
40
+
41
+ ## 校验规则(与平台一字不差)
42
+
43
+ 上传扫描按以下顺序校验,任何一步失败都会拒绝整个包:
44
+
45
+ 1. 文件 ≤ 4096 字节;
46
+ 2. 必须是合法 JSON;
47
+ 3. 必须是 JSON 对象(不能是数组/字符串/数字);
48
+ 4. 只允许 `protocol`、`capabilities`、`entry` 与 `backend` 字段;
49
+ 5. `protocol` 存在时必须是整数 `1`;
50
+ 6. `backend` 存在时只支持 `platform` 或 `external`;
51
+ 7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|collection:[a-z][a-z0-9_]{1,31})$`。
52
+
53
+ 本地预检:`wovoon validate`(规则镜像,报错文案与线上一字不差)。
54
+
55
+ ## 能力与运行时的关系
56
+
57
+ - **提交后校验**:作品包先完成上传,用户提交审核后解析清单;非法清单按技术错误退回,并给出修复指引。
58
+ - **调用即门禁**:运行时每条云能力请求都会比对 manifest 声明。例如未声明 `collection:scores` 却调用 `WovoonCloud.collection('scores')`,平台返回:
59
+
60
+ > 作品未声明云能力 collection:scores:请在作品包根目录的 .wovoon 清单中加入 capabilities 声明后重新上传(参见 wovoon 协议 PROTOCOL.md)
61
+
62
+ - **不发布**:`.wovoon` 只用于平台识别,不会随静态站点对外发布(`.wovoongame`、`.DS_Store`、`__MACOSX/` 同样跳过)。
63
+
64
+ ## 自建后端 Web 应用(协议 1)
65
+
66
+ 可选字段 `backend` 支持 `"platform"`、`"external"`,省略兼容旧协议。`external` 仅用于 Web:上传静态前端,后端独立部署。纯自建后端无需平台 SDK 或云能力;需要混合使用平台云能力时仍按实际调用声明 `capabilities`。
67
+
68
+ ```json
69
+ {"protocol":1,"backend":"external","capabilities":[]}
70
+ ```
71
+
72
+ 前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
73
+
74
+ 平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
@@ -0,0 +1,194 @@
1
+ # wovoon 应用开发指南(人类与 AI 工具通用)
2
+
3
+ > **给人类**:wovoon 是面向创作者的应用平台——前端纯静态托管 + 平台云能力(身份/数据集合/云函数/实时房间),后端不用自己搭。
4
+ > **给 AI 工具**:本文是你开发 wovoon 应用所需的全部契约。工具链已发布 npm,`npx -y @wovoon/cli` 即用;协议类报错自带修复指引,按文案修即可。
5
+ > 环境:Node ≥ 22.13。发布入口当前处于内测阶段(见文末),本地开发与验证不需要任何账号。
6
+
7
+ ---
8
+
9
+ ## 一、五分钟路径
10
+
11
+ ```bash
12
+ npx -y @wovoon/cli init 我的应用 --template game # 或 minimal(空壳)/ arena(全能力参考实现)
13
+ cd 我的应用
14
+ npx -y @wovoon/cli dev # 本地模拟平台,云能力全真
15
+ npx -y @wovoon/cli validate # 生产规则预检,PASS = 可发布
16
+ ```
17
+
18
+ `wovoon dev` 起的模拟器与生产行为逐字一致(同路径、同校验、同报错文案):静态托管在 `/api/public/static/{id}/`,云接口在 `/api/cloud/*`,可用 curl/node 直接驱动,无需浏览器。
19
+
20
+ ---
21
+
22
+ ## 二、核心契约(应用的"后端"就是这三个声明文件)
23
+
24
+ ```
25
+ 项目/
26
+ ├── .wovoon # 能力清单(未声明的能力调用会被拒,报错带修复指引)
27
+ ├── collections.json # 数据集合 + 权限
28
+ ├── functions/*.js # 云函数(服务端逻辑)
29
+ └── index.html 等静态资源 # 任意前端技术栈
30
+ ```
31
+
32
+ ### .wovoon(能力声明)
33
+
34
+ ```json
35
+ {"protocol":1,
36
+ "capabilities":["identity","function","room","collection:saves","collection:rankings"]}
37
+ ```
38
+
39
+ - 能力名固定:`identity` / `function` / `room` / `collection:<小写集合名>`(`^[a-z][a-z0-9_]{1,31}$`);
40
+ - 空文件 = protocol 1 全默认;未知字段/非法能力名会校验失败;
41
+ - join 查询的被连接集合也必须声明(防能力旁路)。
42
+
43
+ ### collections.json(集合与权限)
44
+
45
+ ```json
46
+ {
47
+ "saves": {"read":"PLAYER", "write":"OWNER"},
48
+ "rankings": {"read":"WORLD", "write":"SERVER"},
49
+ "audit_log":{"read":"PLAYER", "write":"SERVER"}
50
+ }
51
+ ```
52
+
53
+ | read | 含义 | write | 含义 |
54
+ |---|---|---|---|
55
+ | `WORLD` | 人人可见(排行榜/公告) | `OWNER` | 登录玩家写自己的文档 |
56
+ | `PLAYER` | 仅文档主人可见(个人存档) | `SERVER` | **仅云函数可写**(防作弊数据的正解) |
57
+
58
+ 配额:8 集合/作品、1 万文档/集合、单文档 64KB。
59
+
60
+ ### functions/*.js(云函数)
61
+
62
+ ```js
63
+ // functions/settle.js —— 服务端权威结算示例
64
+ exports.main = async (event, context) => {
65
+ const { kills, wave } = event; // 调用参数
66
+ const score = kills * 10 + wave * 50; // 服务端重算,不信客户端
67
+ await context.cloud.collection('rankings')
68
+ .set(context.playerId, { score, at: Date.now() }); // SERVER 数据面写入
69
+ const top = await context.cloud.collection('rankings')
70
+ .query({ orderBy: 'score', limit: 10 }); // 函数里同款查询
71
+ return { score, rank: top.findIndex(d => d.id === context.playerId) + 1 };
72
+ };
73
+
74
+ // 可选元数据(直接在函数文件里声明):
75
+ // exports.cron = '5 0 * * *'; // 五字段 cron 定时触发
76
+ // exports.onDocs = ['saves']; // 指定集合写入后触发
77
+ // exports.timeoutMs = 30000; // 长任务档 1000~60000ms(默认 3000)
78
+ ```
79
+
80
+ 沙箱:禁出网、64MB 内存、入出参 ≤32KB;限流玩家 30 次/分、作品 20 万次/日。
81
+
82
+ ---
83
+
84
+ ## 三、前端 API(页面内全局 `WovoonCloud`,平台自动注入,勿引第三方 SDK)
85
+
86
+ ```js
87
+ const cloud = await WovoonCloud.configure({});
88
+
89
+ cloud.identity(); // 每作品稳定 playerId(登录后带 displayName)
90
+
91
+ const saves = cloud.collection('saves');
92
+ const doc = await saves.add({ level: 9, gold: 300 }); // 新建(服务端生成 UUID id;需登录)
93
+ await saves.set(doc.id, { level: 10 }); // 更新自己的文档(set 只改已存在)
94
+ await saves.get(doc.id);
95
+
96
+ // 查询:where(等值 / {gte,lte,gt,lt,ne} / 数组=in)+ orderBy 数值排序
97
+ cloud.collection('rankings').query({
98
+ orderBy: 'score', order: 'desc', limit: 20,
99
+ where: { score: { gte: 100 }, region: 'east' },
100
+ });
101
+
102
+ // join 嵌入连接(每次 ≤2 个;被连接集合需已声明能力):
103
+ cloud.collection('teams').query({ join: {
104
+ members: ['cards', 'teamId'], // 多值:cards.teamId 值=本文档 id → 嵌入数组(≤200 条/侧)
105
+ captain: 'users.userId', // 单值:本文档 userId 值=目标文档 id → 嵌入对象或 null
106
+ }});
107
+ // 嵌入形态 = 目标文档数据字段拍平 + id/seq/createdAt 等平台字段
108
+
109
+ await cloud.call('settle', { kills, wave }); // 调云函数
110
+
111
+ const room = cloud.room('arena-1'); // 实时房间(256 人/房)
112
+ room.send({ x, y, hp }); // ≤4KB,300 帧/30s
113
+ room.onMessage((fromPid, frame) => {});
114
+ room.onPresence((pid, online) => {});
115
+ ```
116
+
117
+ TypeScript 构建期可用 `@wovoon/polaris`(全量类型)。
118
+
119
+ ---
120
+
121
+ ## 四、本地开发循环
122
+
123
+ ```bash
124
+ npx -y @wovoon/cli dev --player 小明 # 模拟登录玩家;不带 --player 为游客(写数据会被拒,属预期)
125
+ ```
126
+
127
+ 模拟器自测(AI 无浏览器验证法):
128
+
129
+ ```bash
130
+ curl -X POST localhost:5179/api/cloud/{appId}/functions/settle \
131
+ -H 'content-type: application/json' -d '{"event":{"kills":3,"wave":5}}'
132
+ curl "localhost:5179/api/cloud/{appId}/collections/rankings/docs?orderBy=score&limit=10"
133
+ # appId 在 dev 启动输出里;集合/函数/房间行为与生产逐字一致
134
+ ```
135
+
136
+ `npx -y @wovoon/cli validate [--json]`:manifest/密钥泄露/托管结构/文件类型白名单/手机兼容预检。
137
+ **本地 PASS = 上传不会被协议与结构类规则拒绝**(报错文案与线上一字不差)。
138
+ `README.md`、`wovoon.config.json`、`.wovoon-deploy-archive/` 自动排除,不进发布包。
139
+
140
+ ---
141
+
142
+ ## 五、AI 提示词模板
143
+
144
+ ### A. 从 0 创建
145
+
146
+ ```
147
+ 为 wovoon 平台开发一个应用:【需求描述】。先完整读一遍本指南文件(wovoon 应用开发指南),遵守其中契约。
148
+ 要点:工具用 npx -y @wovoon/cli;数据放云集合(collections.json 声明权限)、服务端逻辑写
149
+ functions/*.js(防作弊数据一律 SERVER 权限)、前端用页面内全局 WovoonCloud(勿自造 API、
150
+ 勿写后端服务器、勿用 localStorage 存跨设备进度);不确定的实现细节参考 arena 模板
151
+ (npx -y @wovoon/cli init ref --template arena 生成后翻阅)。
152
+ 完成标准:validate PASS + dev 模拟器全流程可玩。先给我集合/函数设计,确认后再写代码。
153
+ ```
154
+
155
+ ### B. 改造存量项目
156
+
157
+ ```
158
+ 把 /path/to/旧项目 改造成 wovoon 应用(功能不变,换运行依赖)。先读本指南文件,再浏览旧代码,
159
+ 给我"改造映射表"再动手:保持不动的前端 / 换云集合的数据(含权限) / 变云函数的后端逻辑 /
160
+ 用 join 表达的关系。约束:产物纯静态;沙箱禁出网(旧后端调第三方 API 的逻辑列出来问我);
161
+ 完成标准:validate PASS + dev 模拟器行为等价旧项目。
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 六、常见报错速查
167
+
168
+ | 报错 | 修复 |
169
+ |---|---|
170
+ | `作品未声明云能力 collection:xxx` | `.wovoon` 的 capabilities 加上后重跑 |
171
+ | `该集合仅云函数可写(write:SERVER)` | 预期行为:玩家侧只读,写入放 `context.cloud` |
172
+ | `join 声明不正确…` / `一次查询最多声明 2 个 join` | 单值 `"集合.字段"`,多值 `["集合","字段"]`,≤2 个 |
173
+ | `静态托管不允许该文件类型:xxx` | 类型不在白名单(html/css/js/json/图片/音视频/3D 等,详见 validate 输出) |
174
+ | `缺少 viewport`(声明手机端时) | `<meta name="viewport" content="width=device-width,initial-scale=1">` |
175
+ | `游客写数据需要登录` | dev 加 `--player 名字` 模拟登录 |
176
+
177
+ ---
178
+
179
+ ## 七、能力边界
180
+
181
+ 支持:任意静态前端;云身份;集合 CRUD+where+join+orderBy;SERVER 权限防作弊;云函数(cron/onDocs/60s 长任务);256 人实时房间;4GB/10 万文件包体。
182
+ 不支持:常驻自定义后端;云函数出网;≥3 表 join、跨集合事务、按连接字段过滤(用云函数组合);连接字段聚合。
183
+
184
+ ## 八、发布(内测阶段)
185
+
186
+ 平台处于内测:发布入口暂未公开。发布链已命令化——获得平台访问权后:
187
+
188
+ ```bash
189
+ npx -y @wovoon/cli login --token wovoon_pat_xxx # 创作者 API 令牌(平台签发,一次)
190
+ npx -y @wovoon/cli deploy # 校验→打包→上传→审发→托管→打印运行地址
191
+ npx -y @wovoon/cli versions && rollback --to 0 # 历史/回退
192
+ ```
193
+
194
+ 项目无图标/宣传视频时 deploy 自动使用内置默认素材;每次发布生成新版本并可随时回退。本地开发阶段完全不需要这一步——`dev` 模拟器已可验证全部云能力。
@@ -0,0 +1,55 @@
1
+ # 改造配方:多人竞技游戏(权威房间 + 竞技速率档)
2
+
3
+ > 适用:需要联机对战、实时竞技、防作弊的游戏。协议 1 能力(`.wovoon` 声明,纯加法):
4
+ > `room:competitive`(上行 30Hz、单帧 8KB、二进制帧)+ `gamelogic`(权威房间逻辑)。
5
+
6
+ ## 三层竞技模型
7
+
8
+ 1. **中继房**(`room`):客户端互发,配合"受害者权威判定 + settle 云函数结算"——十人内、百毫秒级对战。
9
+ 2. **竞技速率档**(`room:competitive`):声明后房间放宽上行限流并支持二进制帧——
10
+ `send(Uint8Array)` 发二进制,`onMessage` 收到 `{binary:true, data:Uint8Array}`;用 MessagePack/自定义打包做 10~20Hz 状态同步。
11
+ 3. **权威房间**(`gamelogic`):包根放 `roomservers/<mode>.js`,`cloud.room(roomId, {mode})` 加入。
12
+ 逻辑跑在平台沙箱(服务端权威):命中/血量/得分外挂改客户端无效;最长 2 小时、空房 60 秒回收、每作品 50 房。
13
+ 逻辑文件限制:每作品 ≤8 个 mode、**单文件 ≤2 MB、全部合计 ≤4 MB**(`wovoon validate` 本地即检,超限精简/压缩代码或把配置数据外置到集合)。
14
+
15
+ ## roomservers/duel.js 最小示例
16
+
17
+ ```js
18
+ exports.tickMs = 50; // 20~100ms(默认 50)
19
+ exports.setup = () => ({ hp: {}, winner: null });
20
+ exports.onJoin = (state, playerId) => { state.hp[playerId] = 100; ctx.broadcast({ hp: state.hp }); };
21
+ exports.onMessage = (state, playerId, data) => {
22
+ // 玩家输入只是"请求":命中在服务端判定
23
+ if (data.hit) { const target = data.hit; if (state.hp[target] > 0) {
24
+ state.hp[target] -= 10; ctx.broadcast({ hp: state.hp });
25
+ if (state.hp[target] <= 0) { ctx.writeDoc("rankings", "add", undefined, { winner: playerId }); ctx.close(); }
26
+ } }
27
+ };
28
+ exports.tick = (state, dt) => { /* 超时/复活等周期逻辑 */ };
29
+ // ctx:broadcast(data) / tell(playerId, data) / writeDoc(集合, op, id, doc)(仅 write:SERVER 集合)/ close()
30
+ ```
31
+
32
+ 客户端:`const r = cloud.room('duel-9527', { mode: 'duel' }); r.onMessage(...) r.send({hit: opponentId})`。
33
+ 服务端广播经 onMessage 到达(`from: 'server'`)。
34
+
35
+ ## 集合实时刷新(onChange)
36
+
37
+ `cloud.collection('rankings').onChange(({action, id}) => 重新查询())` ——
38
+ 任何写入(玩家/云函数/权威房间)都会推送变更通知(不含文档负载,收到后重查)。
39
+ 需要声明 `room` 能力(通知走系统房间通道)。
40
+
41
+ ## 能力声明清单
42
+
43
+ ```json
44
+ {"protocol":1,"capabilities":["identity","room","room:competitive","gamelogic","function","collection:rankings"]}
45
+ ```
46
+
47
+ 验证:`wovoon validate` + `wovoon dev`(模拟器同语义)本地跑通再 deploy。
48
+
49
+ ## MMO-lite 支撑(第三阶段:世界总线 / 匹配 / 房间列表)
50
+
51
+ - **常驻世界**:roomserver 声明 `exports.world = true` → 寿命 24h、空房保活 10 分钟(每作品 ≤20 个世界实例);状态定期 `ctx.writeDoc` 落集合即持久化。
52
+ - **世界总线**:逻辑里 `ctx.worldBroadcast(data)` 全服广播;客户端 `cloud.world().onMessage(...)` 订阅(跨房间、跨场景的世界事件/公告/拍卖成交)。
53
+ - **内置匹配**:`exports.matchSize = N`(2~32,默认 2);客户端 `const roomId = await cloud.match('duel')`(凑满成局,120s 超时)→ `cloud.room(roomId, {mode:'duel'})` 进入。
54
+ - **房间列表(大厅/分线)**:`cloud.rooms({mode:'world'})` → `[{roomId, mode, players, world}]`,选线进房。
55
+ - MMO-lite 组合形态:大厅房 + 分线世界房(world)+ 集合存档 + onChange 世界事件 + match 副本匹配。上限参考:单场景 256 人、单作品 200 权威房(world ≤20)、单实例部署;千人同服/无缝大世界需要 UDP+多区编排(未提供)。
@@ -0,0 +1,70 @@
1
+ # 配方:Express 后端 → wovoon 云能力
2
+
3
+ 适用:`express + 数据库` 的存量服务性应用/回合制多人游戏。
4
+ wovoon 的模型是**前端静态托管 + 大后台能力**:把 Express 的"路由 + 表"逐一映射到协议能力,多数应用能砍掉整个服务器。
5
+
6
+ > 状态说明:`collection`(数据)与 `identity`(身份)已可用;`function`(云函数)与 `room`(实时通道)是 M3 能力。
7
+ > 本配方把三种情况都标清楚,未上线能力的部分先保留你自己的服务器或等待 M3。
8
+
9
+ ## 映射总表
10
+
11
+ | Express 里 | wovoon 里 | 状态 |
12
+ |---|---|---|
13
+ | `GET /api/me`(会话) | `WovoonCloud.ready()`:playerId/登录态/昵称 | ✅ |
14
+ | `app.post('/score')` 写库 | `collection('scores').add/set` | ✅ |
15
+ | `GET /leaderboard` | `collection('scores').query({orderBy, order:'desc', limit})` | ✅ |
16
+ | 用户私人数据表 | 集合 + `ownerOnly` 权限(OWNER 写 / WORLD·PLAYER 读) | ✅ |
17
+ | 服务端秘密逻辑(发牌、结算防作弊) | `function` 云函数(SERVER 权限) | M3 |
18
+ | WebSocket 实时对战 | `room` 房间实时通道 | M3 |
19
+ | 定时任务/爬虫 | 暂不支持,先留在外部服务器 | — |
20
+
21
+ ## 改造步骤
22
+
23
+ ### 1) 前端部分:整体搬进静态包
24
+
25
+ - 把 Express 托管的 `public/`(或前端构建产物)作为站点根目录;
26
+ - 根目录加 `.wovoon`,声明用到的集合:
27
+
28
+ ```json
29
+ { "protocol": 1, "capabilities": ["identity", "collection:scores", "collection:profiles"] }
30
+ ```
31
+
32
+ ### 2) 数据部分:表 → 集合
33
+
34
+ - 每个"玩家私有"的表 → 一个集合(默认 OWNER 写正合适);
35
+ - 公开只读数据(关卡配置等)→ 直接打包进静态资源(JSON 文件 fetch 加载),不必上云;
36
+ - 公共排行榜 → `collection:scores`,每玩家一条文档 `{ score, name, ts }`;
37
+ - 外键换成 `ownerPlayerId` 语义:你的数据天然按玩家隔离,不再需要 user 表关联。
38
+
39
+ ### 3) 接口部分:逐路由替换
40
+
41
+ ```js
42
+ // 旧:fetch('/api/score', {method:'POST', body:...})
43
+ const scores = WovoonCloud.collection('scores');
44
+ const mine = await scores.query({ ownerOnly: true, limit: 1 });
45
+ await (mine.length ? scores.set(mine[0].id, { score, name }) : scores.add({ score, name }));
46
+
47
+ // 旧:fetch('/api/leaderboard')
48
+ const top = await scores.query({ orderBy: 'score', order: 'desc', limit: 20 });
49
+ ```
50
+
51
+ ### 4) 需要服务端权威的逻辑
52
+
53
+ 结算防作弊、发牌、经济系统等**必须留在服务端**的逻辑:
54
+
55
+ - **现在**:保留一个最小 Express 服务,前端 `fetch` 你的服务器(跨域照常配 CORS);静态与云数据仍走 wovoon。
56
+ - **M3 后**:迁到 `function` 云函数(受限 Node 沙箱、SERVER 权限直写集合),那时可以完全下掉服务器。声明里加 `"function"` 即可。
57
+
58
+ ### 5) 校验与发布
59
+
60
+ ```bash
61
+ wovoon validate dist # 结构与密钥检查
62
+ ```
63
+
64
+ `dist` 打 zip 上传 wovoon(`.wovoon` 在包根目录),机审通过后开通静态托管。
65
+
66
+ ## 常见坑
67
+
68
+ - **JWT/session**:不要把平台身份体系和你自己的账号体系混存; playerId 已经是"作品内稳定 ID",直接当外键。
69
+ - **机密配置**:数据库连接串等内容绝不能进作品包(`wovoon validate` 会拦);保留自有服务器时密钥放服务器侧。
70
+ - **实时性**:回合制用"集合 + 轮询/重进页面"就够;快节奏实时别硬轮询,等 `room`(M3)。