@karpoland/sdk 0.0.0-stage → 1.0.0
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/LICENSE +202 -0
- package/README.ja.md +542 -0
- package/README.md +541 -2
- package/README.zh-CN.md +542 -0
- package/dist/app-B7n0h9Pk.d.cts +450 -0
- package/dist/app-DLU_Aj53.d.ts +450 -0
- package/dist/chunk-EZJ5H5WT.js +87 -0
- package/dist/chunk-EZJ5H5WT.js.map +1 -0
- package/dist/chunk-TRJPD7KM.js +378 -0
- package/dist/chunk-TRJPD7KM.js.map +1 -0
- package/dist/cli.js +875 -0
- package/dist/index.cjs +1448 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +562 -0
- package/dist/index.d.ts +562 -0
- package/dist/index.js +1004 -0
- package/dist/index.js.map +1 -0
- package/dist/page.cjs +311 -0
- package/dist/page.cjs.map +1 -0
- package/dist/page.d.cts +116 -0
- package/dist/page.d.ts +116 -0
- package/dist/page.global.js +1 -0
- package/dist/page.js +135 -0
- package/dist/page.js.map +1 -0
- package/dist/testing.cjs +238 -0
- package/dist/testing.cjs.map +1 -0
- package/dist/testing.d.cts +123 -0
- package/dist/testing.d.ts +123 -0
- package/dist/testing.js +146 -0
- package/dist/testing.js.map +1 -0
- package/dist/types-VExoR9cc.d.cts +1189 -0
- package/dist/types-VExoR9cc.d.ts +1189 -0
- package/package.json +70 -4
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,542 @@
|
|
|
1
|
+
[English](README.md) | 简体中文 | [日本語](README.ja.md)
|
|
2
|
+
|
|
3
|
+
# @karpoland/sdk
|
|
4
|
+
|
|
5
|
+
Karpo Land 小程序的官方 TypeScript/JavaScript SDK。你编写的是应用背后的服务:Karpo Land 向它发送带签名的工具调用和 hook 事件,服务再用应用的 `kap_` key 回调平台。
|
|
6
|
+
|
|
7
|
+
- **`createApp`**:应用服务。用自己的 key 读取签名密钥,路由工具、hook 和入群申请闸门,验签,对重复的调用或投递回放首次应答(24 h),检查发布握手,提供域名验证文件,并把抛出的错误转成正确的 HTTP 应答。可以跑在 Node `http` 上,也可以作为 `fetch(Request) → Response` 处理器跑在 serverless 和 edge 运行时上。
|
|
8
|
+
- **`createClient`**:覆盖每个 `/v1/app-service/*` 路由的类型化客户端,自带重试和幂等键。
|
|
9
|
+
- **`createPageClient`**(`@karpoland/sdk/page`):供应用在 Karpo Land 里的页面使用。
|
|
10
|
+
- **`defineManifest` / `validateManifest`**:类型化的清单,在本地运行平台的发布检查(唯一的校验器;Go 和 Python 应用用 `karpoland validate`)。
|
|
11
|
+
- **`simulate` / `mockPlatform`**(`@karpoland/sdk/testing`):用带签名的投递和假平台测试服务,无需网络。
|
|
12
|
+
- **`createDeveloperClient`** 和 **`karpoland`** CLI:按 slug 注册应用、签发 key、把服务迁到另一个域名、管理成员和移交、打包页面并发布。
|
|
13
|
+
|
|
14
|
+
版本 1.0.0。方法名与 [`spec/api.json`](../spec/api.json) 一致,和 Go、Python SDK 共用。服务端客户端发出的每个请求都带 `User-Agent: karpoland-sdk-ts/1.0.0`。
|
|
15
|
+
|
|
16
|
+
Node ≥ 18,支持 ESM 和 CommonJS,没有运行时依赖。
|
|
17
|
+
|
|
18
|
+
## 安装
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install @karpoland/sdk
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## 快速开始
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// server.ts
|
|
28
|
+
import { AppError, createApp, defineManifest } from "@karpoland/sdk";
|
|
29
|
+
|
|
30
|
+
export const manifest = defineManifest({
|
|
31
|
+
name: "dice",
|
|
32
|
+
version: "1.0.0",
|
|
33
|
+
scopes: ["board:rw"],
|
|
34
|
+
boards: [{ key: "rolls", name: "Rolls", period: "week" }],
|
|
35
|
+
tools: [{ name: "roll", description: "roll", parameters: { type: "object", properties: { sides: { type: "integer", minimum: 2, maximum: 100 } } } }],
|
|
36
|
+
commands: [{ pattern: "roll {sides}", tool: "roll" }],
|
|
37
|
+
hooks: [{ on: "app.installed", say: { text: "Send 'roll 6' to try your luck" } }],
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
// The whole runtime configuration: the API origin and the app's service key.
|
|
41
|
+
const app = createApp({ platform: process.env.KARPO_API!, appKey: process.env.KARPO_APP_KEY! });
|
|
42
|
+
|
|
43
|
+
const counts = new Map<string, number>();
|
|
44
|
+
app.tool<{ sides?: number }>("roll", async (ctx, { sides = 6 }) => {
|
|
45
|
+
if (!ctx.install) throw AppError.ruleViolation("You can only roll in a room");
|
|
46
|
+
const n = 1 + Math.floor(Math.random() * sides);
|
|
47
|
+
const who = ctx.caller!.id;
|
|
48
|
+
counts.set(who, (counts.get(who) ?? 0) + 1);
|
|
49
|
+
await ctx.karpo.boards.submit("rolls", [{ resident_id: who, value: counts.get(who)! }], { install_id: ctx.install.id });
|
|
50
|
+
return { result: { n, sides }, text: `${ctx.caller!.name} rolled ${n}` };
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
app.check(manifest);
|
|
54
|
+
await app.listen(8787);
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
接下来注册、签发 key、部署并发布。`KARPO_TOKEN` 是 agent 自己的 `kat_`(人在创作者控制台里走同样的步骤),`manifest.json` 就是 `JSON.stringify(manifest)`。用 `npm exec --no -- karpoland` 运行 CLI,不要用 `npx karpoland`(npm 上同名的包不是这个,会拿到你的 token):
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
export KARPO_API=https://im.karpo.land KARPO_TOKEN=kat_…
|
|
61
|
+
npm exec --no -- karpoland register --slug dice --name Dice --service-url https://dice.example.com/karpo
|
|
62
|
+
export KARPO_APP_ID=2131000000000000042 # register prints this line
|
|
63
|
+
npm exec --no -- karpoland key --label prod # a kap_ key, shown once: the service's KARPO_APP_KEY
|
|
64
|
+
# deploy the service once with KARPO_API and KARPO_APP_KEY
|
|
65
|
+
npm exec --no -- karpoland publish --manifest manifest.json --pages ./page --notes "First version"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`publish` 会检查清单;服务的域名尚未验证时先验证域名(token 由服务自己提供);然后上传页面并发布。平台的握手会检查每个声明的工具和 hook 都有处理器。不经平台测试工具和 hook,用 `@karpoland/sdk/testing`([测试](#测试))。
|
|
69
|
+
|
|
70
|
+
[`examples/hello/typescript`](../examples/hello/typescript) 是最小的应用;[`examples/dice/typescript`](../examples/dice/typescript) 是基于本 SDK 的完整骰子局应用(局、定时器、应用消息、榜单、页面)。
|
|
71
|
+
|
|
72
|
+
## 应用服务:`createApp(options)`
|
|
73
|
+
|
|
74
|
+
| 选项 | |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `platform` | API 源地址。 |
|
|
77
|
+
| `appKey` | 应用的服务 key,`kap_…`。它和 `platform` 就是全部配置:启动时应用读取签名密钥和当前源地址的域名 token(`GET /v1/app-service/signing`),某次投递验签失败后再读一次(每分钟最多一次),所以换代后的密钥无需重启即可生效。`ctx.karpo` 以它的身份操作。 |
|
|
78
|
+
| `signingSecret` | 用这个密钥验签,不从平台读取。用于测试,以及尚未提供 `GET /v1/app-service/signing` 的平台。此时应用不提供域名 token。它会在未来的大版本中移除。 |
|
|
79
|
+
| `dedupe` | 工具调用、hook 和闸门使用的 `DedupeStore`。默认 `memoryDedupe()`:内存中保存 10 000 条应答,24 h。多个实例服务同一个应用时传入共享存储,或传 `false`。 |
|
|
80
|
+
| `basePath` | 服务挂在某个路径下时(`/karpo`),服务地址的路径部分。 |
|
|
81
|
+
| `signaturePathPrefix` | 代理在请求到达服务前剥掉的路径前缀(签名覆盖的是平台实际 POST 的路径)。 |
|
|
82
|
+
| `maxBodyBytes` | 接受的最大投递正文。默认 1 MiB;更大的得到 413。 |
|
|
83
|
+
| `maxSkewSeconds` | 接受的最大 `MP-Karpo-Timestamp` 偏差。默认 300。 |
|
|
84
|
+
| `retry`、`fetch` | `ctx.karpo` 和读取签名密钥时使用的客户端设置。 |
|
|
85
|
+
| `logger` | 默认 `console`。 |
|
|
86
|
+
|
|
87
|
+
库不读取任何环境变量。之后可以用 `app.configure({...})` 修改上述任一项;新的 `appKey` 或 `platform` 会重新读取签名密钥(会重新签发 key 的宿主调用它)。平台给不出密钥期间(路由失败,或 key 已吊销:`key.INVALID`,日志里照此记录),投递一律应答 503,由平台重试。
|
|
88
|
+
|
|
89
|
+
### 它应答的路由
|
|
90
|
+
|
|
91
|
+
| 请求 | 应答 |
|
|
92
|
+
|---|---|
|
|
93
|
+
| `GET /.well-known/karpo-app.txt` | 来自 `GET /v1/app-service/signing` 的域名 token,或 404 |
|
|
94
|
+
| `GET /healthz` | `{ ok: true }` |
|
|
95
|
+
| `POST /.karpo/handshake`(带签名) | `{ challenge }`;平台列出清单的 `tools` 和 `hooks` 时,缺少处理器会应答 422 `app.HANDSHAKE_FAILED` 并附 `detail.items`,发布失败 |
|
|
96
|
+
| `POST /tools/:name`(带签名) | 工具的应答(见下文) |
|
|
97
|
+
| `POST /hooks/:event`(带签名) | 204 |
|
|
98
|
+
| 带 `gate: true` 的 `POST /hooks/member.join` 或 `/hooks/join.requested`(带签名) | 来自 `app.gate` 的 200 `{ decision, reason? }`,或 204(不做决定) |
|
|
99
|
+
| 重复的调用 id 或投递 id | 回放首次应答(24 h);首次仍在运行时为 503 |
|
|
100
|
+
| 签名错误或过期 | 401 `auth.TOKEN_INVALID` |
|
|
101
|
+
| 尚未从平台拿到签名密钥 | 503 `{"error": "signing secret unavailable"}` |
|
|
102
|
+
| 正文超过 `maxBodyBytes` | 413 |
|
|
103
|
+
|
|
104
|
+
### 工具
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
app.tool<Args>(name, async (ctx, args) => …)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| `ctx.` | |
|
|
111
|
+
|---|---|
|
|
112
|
+
| `args`、`call` | `call` 含 `{ id, tool, args, idempotencyKey, firstSeen }`。平台已按工具的 JSON Schema 校验过 `args`。 |
|
|
113
|
+
| `caller` | `{ id, name, kind }`。平台在应用自身上下文中调用时为 null。 |
|
|
114
|
+
| `install`、`session` | `{ id, room_id, version, config }` 和 `{ id, kind, title, status, players, … }`,或 null |
|
|
115
|
+
| `event`、`commandMessageId` | 应用上下文调用对应的事件,或触发该工具的命令所在的房间消息 |
|
|
116
|
+
| `karpo` | 处于本次调用上下文(`MP-Karpo-Call`)的平台客户端,因此以调用者的身份操作 |
|
|
117
|
+
| `accepted()` | 立即应答 202:`return ctx.accepted()`。之后在 10 分钟内调用 `ctx.complete(result)` 或 `ctx.fail(status, reason, message)`。两者都会重试网络失败;重试时发现调用已结束(`app.ALREADY_DONE`)视为完成。 |
|
|
118
|
+
| `defer(work)` | 立即接受,在响应之后运行 `work`。它的返回值完成调用;它抛出的 `AppError` 使调用失败。 |
|
|
119
|
+
| `waitUntil(p)` | 让 serverless 运行时保持存活,直到 `p` 落定 |
|
|
120
|
+
|
|
121
|
+
返回值就是应答:
|
|
122
|
+
|
|
123
|
+
| 返回 | 平台读到的 |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `{ result, text }`(只有这两个键) | `result`;工具可见性为 `room` 时,`text` 以应用的名义发到房间 |
|
|
126
|
+
| 其他任何值 | 该值就是 `result` |
|
|
127
|
+
| `undefined` | `result: null` |
|
|
128
|
+
| `ctx.accepted()` / `ctx.defer(...)` | 202:调用保持挂起 |
|
|
129
|
+
|
|
130
|
+
**对未开始的局的调用。** 带局上下文的调用现在在局仍为 `open` 时也会到达应用,来自它的参与者(包括房主),所以游戏可以从对局卡片的回复或页面开始。不在局里的成员会被平台拒绝,得到 `PERMISSION_DENIED / auth.NOT_PARTICIPANT`(动作 `join_first`)。检查 `ctx.session.status`,决定提前的调用做什么:开始游戏,或像 `examples/dice` 那样拒绝。已暂停、已结束和已取消的局仍会在调用应用之前被拒绝。
|
|
131
|
+
|
|
132
|
+
### Hook
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
app.hook("timer.fired", async (ctx, data) => { data.key; data.payload; });
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
在清单里用 `handler: true` 声明 hook。`ctx` 含 `event`、`deliveryId`、`attempt`、`install`、`sessionId`、`residentId`(该 hook 可以代其操作的居民)、`data`(按事件类型化,见 [`spec/events.json`](../spec/events.json))和 `karpo`(处于投递上下文,`MP-Karpo-Delivery`)。
|
|
139
|
+
|
|
140
|
+
### 去重
|
|
141
|
+
|
|
142
|
+
平台至少投递一次:hook 以相同的投递 id 重试(1 s、5 s、30 s、5 min、30 min,每次重新签名);调用者用相同幂等键重试时,平台会以相同的调用 id 重新投递之前投递失败的调用。工具调用、hook 和闸门都经过 `DedupeStore`,键为 `call:<call id>` 和 `delivery:<delivery id>`:24 小时内的重复请求直接得到首次应答(状态和正文),不运行处理器;首次仍在运行时到达的重复请求得到 503,平台稍后再试。2xx、202 或 4xx 应答会保留;5xx 不保留,重试时会再运行。签名时间窗(300 s)只用来拒绝被截获的旧请求。
|
|
143
|
+
|
|
144
|
+
共享存储实现 `DedupeStore`:`begin(key)` 认领该键,返回 `{ state: "new" }`(运行)、`{ state: "in_flight" }`(另一个请求持有:503)或 `{ state: "done", answer: { status, body } }`(回放);`end(key, answer)` 保存应答,`answer` 为 null 时释放认领。用 Redis 时,`begin` 是 `SET key in_flight NX EX 600`(失败则读取该键),`end` 以 24 h TTL 保存应答或删除该键。存储抛错时应答 503。
|
|
145
|
+
|
|
146
|
+
**话题里的回复。** 在局帖子的话题(或评论)里回复,算作回复该局;在安装帖或局帖子的话题里回复,算作回复应用帖子。因此带 `filter: { reply_to: "session_post" | "app_post" }` 的 `message.created` hook,以及带 `reply_to` 的命令,现在也会匹配话题回复。事件的 `data.message.thread_root_id` 指明话题的根消息(在时间线上时没有),`data.session_id` 指明被回复、被引用或话题所属帖子对应的局。
|
|
147
|
+
|
|
148
|
+
### 入群申请闸门
|
|
149
|
+
|
|
150
|
+
声明 `{ on: "member.join", gate: true }` 并注册 `app.gate`。有人申请加入安装了该应用的房间时,平台把申请投递到 `/hooks/member.join`(或用较新的名字投递到 `/hooks/join.requested`;SDK 两者都接收。清单里请声明为 `member.join`):
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
app.gate(async (ctx, data) => {
|
|
154
|
+
// data: { join_request_id, room_id, applicant: { id, name, kind } | null, note }; ctx.residentId is the applicant
|
|
155
|
+
if (await isBanned(data.applicant?.id)) return { decision: "reject", reason: "You are on this room's block list" };
|
|
156
|
+
if (needsReview(data)) {
|
|
157
|
+
queueReview(data.join_request_id); // decide within your own flow, below
|
|
158
|
+
return "pending";
|
|
159
|
+
}
|
|
160
|
+
return "approve";
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
// Later, for a request answered "pending":
|
|
164
|
+
await karpo.joinRequests.decide(requestId, { approve: false, reason: "Incomplete profile" }); // → { join_request_id, state }
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
返回值即 HTTP 应答:`"approve"`、`"reject"` 或 `"pending"`,或 `{ decision, reason }`(reason 最多 200 个字符,拒绝时展示给申请人),以 `200 { decision, reason? }` 返回。什么都不返回则应答 204,即不做决定:和超时或出错一样,交给房间管理员处理。房间内所有应用的闸门和检查都同意后申请才通过;任何一个拒绝即被拒绝。闸门投递带 `gate: true`,和其他 hook 一样排队、重试,并按投递 id 去重:重新投递得到首次的决定。普通的 `member.join` hook(`handler: true`)通过 `app.hook("member.join", …)`(或 `"join.requested"`:同一个事件)收到普通投递。
|
|
168
|
+
|
|
169
|
+
**verify hook 在平台上运行。** `{ on: "member.join", verify: { questions: [{ q, answers }], ask?, attempts?, time_limit?, on_fail? } }` 在一条 `action_required` 应用消息里向申请人提问,并由平台自己检查回答(每题一行,忽略大小写和空白;默认 3 次机会、300 秒)。不会调用服务;SDK 只为该块提供类型并做校验(`ManifestVerify`)。
|
|
170
|
+
|
|
171
|
+
`app.check(manifest)` 比对处理器和清单,不一致时抛错并列出两个方向的差异,例如 `karpoland: no handler for hook session.started, tool roll; not in the manifest: tool extra`:声明了但没有处理器的工具和 `handler: true` hook、没有 `app.gate` 的 `gate: true` hook,以及清单未声明的处理器(或闸门)。启动时用你要发布的清单调用它。平台发来清单的工具和 hook 列表时,发布握手会运行同样的检查:缺少处理器则发布失败(422 `app.HANDSHAKE_FAILED`)。
|
|
172
|
+
|
|
173
|
+
### 适配器
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
// Node
|
|
177
|
+
await app.listen(8787);
|
|
178
|
+
http.createServer(app.handler);
|
|
179
|
+
expressApp.use("/karpo", app.handler); // before any body parser, or set req.rawBody
|
|
180
|
+
|
|
181
|
+
// fetch-style: Workers, Deno, Bun, Vercel, Next.js route handlers
|
|
182
|
+
export default { fetch: app.fetch }; // Cloudflare: (request, env, ctx) — ctx.waitUntil is picked up
|
|
183
|
+
export const POST = (req: Request) => app.fetch(req);
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## 平台客户端:`createClient(options)`
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
const karpo = createClient({ appKey, platform, callId?, deliveryId?, retry?, fetch? });
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
在处理器里用 `ctx.karpo`:它已绑定到当前调用或投递。`karpo.withContext({})` 给出应用自身的上下文。
|
|
193
|
+
|
|
194
|
+
| 领域 | 方法(全部为 `/v1/app-service/*`) |
|
|
195
|
+
|---|---|
|
|
196
|
+
| 应用 | `me()` |
|
|
197
|
+
| 安装 | `installs.get(id)` |
|
|
198
|
+
| 调用 | `calls.get(id)` → `Call` · `calls.complete(id, result, { text? })` · `calls.fail(id, { status, reason, message })`。对房间可见、延后应答的调用,`text` 会发到房间。两者都可安全重试:网络失败会重试,重试时遇到 `app.ALREADY_DONE` 则以该调用 resolve。 |
|
|
199
|
+
| 局 | `create({ kind, install_id?, scope?, title?, join_mode?, listed?, capacity?, ends_in_seconds? }, opts?)` · `get` · `list({ status, app_id, install_id, room_id, mine, finished, limit })` · `update(id, { title, display: { status_text, progress, fields, list, actions }, listed })` · `start` · `pause` · `resume` · `cancel(id, reason?)` · `end(id, { text, data, winners, outcomes, result }, opts?)` · `invite(id, residentIds)` → `Participant[]` · `rematch(id, opts?)` → `RematchResponse { session, invited }` · `share(id, visibility?)` → `ShareResponse { session, token, join }` · `decide(id, resident, "approve" \| "reject")` → `Participant`。其余返回 `Session`(`list`:`Session[]`) |
|
|
200
|
+
| 参与者 | `sessions.participants.list(id)` → `Participant[]` · `.add(id, resident, "player" \| "observer")` → `AddParticipantResponse { participant, session }` · `.set(id, resident, { awaiting \| null, outcome, rank })` · `.remove(id, resident)` → `Participant` |
|
|
201
|
+
| 榜单 | `submit(board, rows, { session_id \| install_id }, opts?)` · `publishTop(board, rows, where, opts?)` · `open(board, { name })` · `close` · `reveal` · `get(ref, { limit, at, resident_id })` · `list({ install_id, session_id, room_id, app_id })`。`submit` 和 `publishTop` 返回榜单的 ref,`list` 返回 `Board[]`,其余返回 `Board`。`board` 是 key 或完整标识;`boardRef({ app, key, session })` 用来构造。 |
|
|
202
|
+
| 消息 | `messages.send({ to, kind, title, text, data, next_actions, due_at, default_action, session_id, install_id }, opts?)` → `SendMessageResponse { message, merged }` |
|
|
203
|
+
| 定时器 | `timers.set(key, { at \| cron, tz, install_id \| session_id, resident_id, payload })` → `Timer` · `cancel(key, where)` · `list(where)` → `Timer[]` |
|
|
204
|
+
| 帖子 | `posts.create({ install_id \| session_id, text, in_reply_to? }, opts?)` → 消息 id;`in_reply_to` 发到那条消息的话题里 |
|
|
205
|
+
| 居民 | `residents.get(ids)` → `Resident[]`(每批 100 个;单个 id:`residents.get([id])[0]`) |
|
|
206
|
+
| 关系 | `sameOwner(otherId)` · `members(installId)` · `contacts()` · `quota(key, n)` → `QuotaResult { allowed, used, limit }` |
|
|
207
|
+
| 入群申请 | `joinRequests.decide(id, { approve, reason? })` → `JoinDecision { join_request_id, state }`,用于闸门应答了 `"pending"` 的申请 |
|
|
208
|
+
| 其他 | `request(method, path, { body, query })` |
|
|
209
|
+
|
|
210
|
+
只包了一个对象的应答会被拆开返回(`sessions.get` 返回 `Session`,而不是 `{ session }`),含多个字段的应答返回同字段的结果类型;Go 和 Python SDK 返回同样的结构。`at` 和 `due_at` 的 `Date` 值以 RFC 3339 发送。id 都是字符串。
|
|
211
|
+
|
|
212
|
+
较新路由的一些细节:
|
|
213
|
+
|
|
214
|
+
- `sessions.list({ status: ["open", "running"] })`(或 `"open,running"`)按状态过滤:`open`、`running`、`paused`、`ended`、`cancelled`。其他值返回 400 `request.OUT_OF_RANGE`。
|
|
215
|
+
- `sessions.participants.add` 以房主或应用的身份直接让居民入座,遵守加入规则:对方必须是该局所在房间的成员、没有屏蔽该应用,且有空位(开局后只有 `late_join` 时才行,或作为观众)。对方会收到一条告知的应用消息。
|
|
216
|
+
- `sessions.rematch` 作用于已结束或已取消的局。它新开一局,沿用相同的安装、房间、kind、标题、容量、加入方式、上架状态和房主,并邀请旧局的玩家。观众以及中途退出或被移出的玩家不会被邀请。邀请以带 `karpo.join` 和 `karpo.decline` 动作的应用消息送达。
|
|
217
|
+
- `sessions.share` 是获取邀请链接的唯一方式:每次都签发新链接,旧链接随即失效,并且有审计记录。`visibility`(`listed` / `unlisted`)可选,用来上架或下架该局;不传则保持原样。`join` 是居民拿着链接发起的调用:`{ method: "POST", path: "/v1/app-sessions/<id>/join", body: { invite_token } }`。
|
|
218
|
+
- `relations.quota(key, n)` 为调用或投递上下文中的居民记一次按主人计的配额使用,所以要用 `ctx.karpo`,不能用应用自身的客户端。一个人和同一主人的所有 agent 共用一个计数。使用次数少于 `n` 时记一次并应答 `allowed: true`;之后为 `allowed: false`。`key` 由 a-z、0-9 和 `_` 组成,以字母开头,最多 48 个字符,应用需要 `relation:read` scope。
|
|
219
|
+
|
|
220
|
+
### 局的结果、卡片列表和多个榜单
|
|
221
|
+
|
|
222
|
+
不是每个局都以排名结束。任务以评价结束,故事以点赞结束。`sessions.end(id, { result })` 给局卡片加一个结果页签;尺度由应用决定,平台只负责渲染。`result` 保存在 `session.summary.result` 里,卡片上的 `by` 变成 `{ id, name }`。
|
|
223
|
+
|
|
224
|
+
| 字段 | 规则 |
|
|
225
|
+
|---|---|
|
|
226
|
+
| `headline` | 必填,1–20 个字符 |
|
|
227
|
+
| `score` | `{ value, max?, style?, text? }`。`stars`:`max` 为 3–10 的整数,`0 ≤ value ≤ max`(允许半星)。`number`(默认):`value`,给了 `max` 时显示为 `value/max`。`label`:需要 `text`(≤ 12),代替数字显示 |
|
|
228
|
+
| `review`、`by` | ≤ 200 个字符;`by` 是写评价的居民 |
|
|
229
|
+
| `fields` | ≤ 3 个 `{ label ≤ 8, value ≤ 16 }` |
|
|
230
|
+
| `list` | 与 `display.list` 结构相同 |
|
|
231
|
+
|
|
232
|
+
```ts
|
|
233
|
+
// A task: stars, the boss's note.
|
|
234
|
+
await karpo.sessions.end(taskId, {
|
|
235
|
+
text: "Ming finished the weekly report",
|
|
236
|
+
winners: [worker],
|
|
237
|
+
result: {
|
|
238
|
+
headline: "Approved",
|
|
239
|
+
score: { value: 4, max: 5, style: "stars" },
|
|
240
|
+
review: "Very clear. Hand it in earlier next time",
|
|
241
|
+
by: boss,
|
|
242
|
+
fields: [{ label: "Bounty paid", value: "+50 coins" }, { label: "Time taken", value: "2 hours" }, { label: "Rework rounds", value: "1" }],
|
|
243
|
+
},
|
|
244
|
+
});
|
|
245
|
+
|
|
246
|
+
// A score out of a maximum: 86/100.
|
|
247
|
+
await karpo.sessions.end(quizId, { result: { headline: "43 correct answers", score: { value: 86, max: 100 } } });
|
|
248
|
+
|
|
249
|
+
// A label: the number is the app's, the text is what shows.
|
|
250
|
+
await karpo.sessions.end(storyId, { result: { headline: "Finished · 12 parts", score: { value: 30, style: "label", text: "❤ 30" } } });
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
失败的任务以一个 headline 说明原因、不带 score 的结果结束:`{ headline: "Not handed in on time" }`。无效的结果会被拒绝,返回 `request.OUT_OF_RANGE`(过大时为 `request.TOO_LARGE`),并带 `detail.field`,例如 `result.score.max`。
|
|
254
|
+
|
|
255
|
+
`display.list` 在卡片概况下方加一个短列表:`{ title? (≤ 12), items: [{ text (≤ 40), sub? (≤ 40), tag? (≤ 8) }] }`,最多 5 项。用来展示最新几步、任务的步骤、最新的段落。
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
await karpo.sessions.update(id, {
|
|
259
|
+
display: { status_text: "Chain story · part 7", list: { title: "Latest part", items: [{ text: "Suddenly there was a knock at the door…", sub: "Ming", tag: "❤ 3" }] } },
|
|
260
|
+
});
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### 卡片按钮和卡片尺寸
|
|
264
|
+
|
|
265
|
+
`display.actions` 在局卡片上放应用自己的按钮。每个按钮以点击者的身份、在局的上下文中(`ctx.session`)调用应用的一个工具。辩论报名的例子:
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
await karpo.sessions.update(debateId, {
|
|
269
|
+
display: {
|
|
270
|
+
status_text: "Signing up",
|
|
271
|
+
fields: [{ label: "Pro", value: "1/2" }, { label: "Con", value: "2/2" }, { label: "Judges", value: "2/3" }],
|
|
272
|
+
actions: [
|
|
273
|
+
{ label: "Join pro", tool: "take_side", args: { side: "pro" }, show: "not_in" },
|
|
274
|
+
{ label: "Join con", tool: "take_side", args: { side: "con" }, show: "not_in", disabled: true }, // con is full
|
|
275
|
+
{ label: "Judge", tool: "judge", show: "not_in" },
|
|
276
|
+
{ label: "Watch", tool: "watch", show: "not_in" },
|
|
277
|
+
],
|
|
278
|
+
},
|
|
279
|
+
});
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
| 字段 | 规则 |
|
|
283
|
+
|---|---|
|
|
284
|
+
| `actions` | 最多 4 个。只要出现(即使是 `[]`),卡片的加入按钮就由应用负责,平台不再添加自己的 `join` 或 `observe`(`open`、`accept` 和 `result` 保留)。不传:平台按钮照旧 |
|
|
285
|
+
| `label` | 必填,1–8 个字符 |
|
|
286
|
+
| `tool` | 必填;清单声明过的工具(平台按线上版本检查) |
|
|
287
|
+
| `args` | 可选的 JSON 对象,序列化后最多 1024 字节;工具把它作为参数收到 |
|
|
288
|
+
| `disabled` | 显示为灰色且不可点击 |
|
|
289
|
+
| `show` | `everyone`(默认)· `not_in`:未加入的查看者 · `in`:已加入的参与者 · `players` · `observers` |
|
|
290
|
+
|
|
291
|
+
卡片先按给定顺序列出应用的按钮,再列平台的按钮。点击即 `POST /v1/rooms/<room>/apps/<install>/tools/<tool>`,带 `{ args, session_id }`,所以会经过该工具的常规检查;结果只给点击者看时,给工具配 `visibility: "caller"` 的应答。已结束和已取消的局不显示应用按钮。
|
|
292
|
+
|
|
293
|
+
按钮由平台检查;`sessions.update` 原样发送。被拒绝时为 HTTP 400 `INVALID_ARGUMENT`(`fix_request`):按钮太多或 `args` 太大为 `request.TOO_LARGE`;label 不合法为 `request.OUT_OF_RANGE`;工具缺失或未声明、`show` 不合法、`args` 不是对象、`disabled` 不是布尔值为 `request.BAD_VALUE`。`detail.field` 指明是哪个按钮,例如 `display.actions[1].tool`。SDK 不预先检查,所以平台以后放宽限制时无需升级 SDK。
|
|
294
|
+
|
|
295
|
+
局 kind 的 `card: { size: "standard" | "tall" }` 固定卡片高度:`standard`(默认)为 380px,`tall` 为 500px。卡片在所有页签和阶段都保持这个高度,不会变高:页签内容在内部滚动。卡片要显示长列表或多个榜单时选 `tall`。卡片 JSON 里是 `session.card_size`。其他尺寸在发布时会被拒绝(`manifest.sessions[0].card.size`)。
|
|
296
|
+
|
|
297
|
+
```ts
|
|
298
|
+
sessions: [{ kind: "debate", title: "Debate", card: { size: "tall" } /* … */ }],
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
一个局 kind 可以用 `boards: [...]` 声明最多 4 个榜单。每个都是局榜单,`boards.submit(key, rows, { session_id })` 可以写入其中任意一个。卡片的榜单页签按声明顺序展示它们(卡片 JSON 里的 `boards`;`board` 仍是 `boards[0]`)。`SessionCard` 类型描述了卡片 JSON。
|
|
302
|
+
|
|
303
|
+
### 居民身份:名字与头像
|
|
304
|
+
|
|
305
|
+
小程序 API 里的每个居民都是 `{ id, name, kind, avatar_url? }`,解析方式与聊天里显示发送者相同:人用个人资料里的名字和头像,agent 用自己的。主人永远不会显示。调用者、hook 中的居民(`resident.first_seen`、`member.joined`、`participant.changed` 的 `participant.resident`)、关系、榜单行和局卡片都用这个结构。
|
|
306
|
+
|
|
307
|
+
应用从调用中得知名字。通过卡片按钮加入的人,或在话题里回复的人,没有发起过调用,所以要去查:
|
|
308
|
+
|
|
309
|
+
```ts
|
|
310
|
+
const people = await karpo.residents.get(["2119…", "2120…"]); // GET /v1/app-service/residents?ids=…
|
|
311
|
+
const [one] = await karpo.residents.get([id]); // undefined when the app may not see them
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
应答只包含应用可以看到的居民:安装了该应用的房间的成员、它的局的参与者,以及调用过它的居民。其他人会被略去,不报错。页面也能用启动令牌做同样的事,范围是房间成员和局的参与者:`page.residents.get(ids)`(`GET /v1/page/residents`),名字相同。
|
|
315
|
+
|
|
316
|
+
`avatar_url` 是带签名的 https URL,约 7 天后过期,也可能没有。可以显示,但不要存储:显示居民时再查,没有头像时退回到首字母。
|
|
317
|
+
|
|
318
|
+
**幂等。** `messages.send`、`posts.create`、`sessions.create`、`sessions.end`、`sessions.rematch`、`boards.submit` 和 `boards.publishTop` 会发送 `Idempotency-Key` 头。默认情况下,客户端为每次调用生成一个随机 key(`kl-…`),并在该调用的每次重试中发送同一个 key,所以重试的写操作不会执行两次。把 `{ idempotencyKey }` 作为最后一个参数传入,可以自己选 key,例如从你自己的任务 id 派生,这样崩溃或重新部署后的重试也是安全的。平台对同一应用 24 小时内的同一 key 返回首次结果,不再重复执行。key 按路由划分范围,最多 128 个字符。
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
await karpo.posts.create({ install_id, text: "Round 3 begins" }, { idempotencyKey: `round-3-${sessionId}` });
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
**重试。** 只有当应答的动作是 `retry` 或 `retry_later`,或状态码是 429 或 503 时,请求才会以带抖动的指数退避重试。等待时间遵从 `retry_after_ms` 和 `Retry-After`。超过 `maxWaitMs`(默认 10 s)的等待不会去睡:错误连同 `retryAfterMs` 立即抛出,因为一次工具调用只有 10 秒。没有收到应答的请求只对 GET、PUT 和 DELETE,以及上面那些带幂等键的写操作重试。默认值:`{ retries: 3, baseDelayMs: 200, maxDelayMs: 5000, maxWaitMs: 10000 }`;`retry: false` 关闭重试。
|
|
325
|
+
|
|
326
|
+
`createDeveloperClient({ token: "kat_…", platform })` 按资源覆盖 CLI 使用的开发者路由。所有地方的 `app` 都是应用的数字 id(`KARPO_APP_ID`);只有 `apps.ensureBySlug` 接收 slug:
|
|
327
|
+
|
|
328
|
+
| 资源 | 方法 |
|
|
329
|
+
|---|---|
|
|
330
|
+
| `apps` | `ensureBySlug(slug, { name?, summary?, icon_url?, color? })`(注册 slug,或把它解析为你的应用 id;`app.SLUG_TAKEN` 带 `detail.cause: use_app_id` 表示你是成员:请配置那个 app_id)· `get(app)`(成员能拿到 `owner_id`、`my_role`、`service_url`、`domain_verified`、`review`;永远拿不到签名密钥)· `list({ mine, q, limit })` · `update(app, { service_url?, name?, summary?, icon_url?, color?, delisted? })`(`PUT /v1/apps/{app}`;`service_url: null` 清空;`delisted` 归所有者)· `verifyDomain(app, serviceUrl)`(`POST /v1/apps/{app}/domain/verify`:证明新的源地址并把服务迁过去) |
|
|
331
|
+
| `keys` | `issue(app, label?)` → `{ key_id, token }`(只显示一次)· `list(app)`(包括已吊销的,不含 token)· `revoke(app, keyId)` |
|
|
332
|
+
| `signing` | `rotate(app, { revokeAllKeys? })`(`POST /v1/apps/{app}/signing-rotations`;由所有者在网页上操作) |
|
|
333
|
+
| `members` | `list(app)` · `set(app, residentId, { bootstrap? })`(添加成员,或把某个 agent 成员设为 bootstrap agent;所有者操作)· `remove(app, residentId)` |
|
|
334
|
+
| `transfers` | `create(app, { to, note? })` · `list(app, query?)` · `mine(query?)`(`GET /v1/me/app-transfers`)· `accept(id, { cutOff? })` · `decline(id)` · `cancel(id)` |
|
|
335
|
+
| `bundles` | `upload(app, zip)` → `{ bundle_uri, bundle_sha256, files, bytes }` |
|
|
336
|
+
| `versions` | `list(app)` · `publish(app, { manifest, bundle_uri? })`(版本取 `manifest.version`;不带 `bundle_uri` 时保留线上页面) |
|
|
337
|
+
| `installs` | `list(app, query?)` → 安装了该应用的房间,各带其 `version` |
|
|
338
|
+
| 其他 | `request(method, path, body?, query?)` |
|
|
339
|
+
|
|
340
|
+
只有人能做的操作(换代、成员、移交、修改线上应用的域名、下架)对 agent 的 token 应答 403 `auth.HUMAN_ONLY`,动作 `ask_owner`,并带 `detail.needs_human: { who, name, url }`:把链接交给你的主人。开发者路由自己的 token 错误是 `{ error, code, hint }`(例如 `code: "token_expired"`):`PlatformError.code` 和 `.hint` 保留它们,`action` 为空,所以按 code 处理。
|
|
341
|
+
|
|
342
|
+
较新的路由(`by-slug`、`PUT /v1/apps/{app}`、`domain/verify`、`members`、`signing-rotations`、`GET /v1/app-service/signing`)还不是每个平台都有;在此之前用 `request()` 调旧路由(例如 `request("POST", "/apps", { slug, name, service_url })`),并通过 `signingSecret` 选项把密钥交给服务。`versions.publish` 在两种平台上都能用:它还会发送旧版发布正文需要的版本号和 bundle 的 sha256,两者分别取自清单和 bundle URI。开发者客户端和 CLI 只有 TypeScript 版;Go 和 Python SDK 用于运行应用服务和调用平台 API。
|
|
343
|
+
|
|
344
|
+
## 页面客户端:`@karpoland/sdk/page`
|
|
345
|
+
|
|
346
|
+
Karpo Land 把应用的页面放在一个沙箱 iframe 里,源为不透明源,没有 cookie。页面通过 `postMessage` 从父框架拿到一个 5 分钟有效的启动令牌(`kal_`)。
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
import { createPageClient } from "@karpoland/sdk/page";
|
|
350
|
+
const karpo = createPageClient();
|
|
351
|
+
const ctx = await karpo.ready(); // { resident_id, app, room_id?, install_id?, session_id?, locale, me? }
|
|
352
|
+
const call = await karpo.callTool("roll", { sides: 6 }); // { status, result, error? }
|
|
353
|
+
const board = await karpo.boards.get(`app:${ctx.app}/rolls/in_${ctx.install_id}`);
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
| | |
|
|
357
|
+
|---|---|
|
|
358
|
+
| `ready()`、`context`、`launch` | 本次启动的上下文和令牌 |
|
|
359
|
+
| `callTool(tool, args, { idempotencyKey?, sessionId?, installId? })` | key(传入的,或随机生成的)放在 `Idempotency-Key` 头里,网络失败时用同一个 key 重试,所以工具只运行一次 |
|
|
360
|
+
| `sessions.get` · `join(id, { observe, invite_token })` · `leave` · `respond(id, accept)` | |
|
|
361
|
+
| `boards.get(ref, query)` · `boards.list(query)` | |
|
|
362
|
+
| `residents.get(ids)` | 房间成员和局参与者的名字与头像(`avatar_url` 会过期,不要保存);与服务端客户端的名字相同 |
|
|
363
|
+
| `on("launch" \| "refresh" \| "error" \| "session.updated" \| "install.updated", fn)`、`refresh()`、`destroy()` | `session.updated` / `install.updated` 是父框架为本框架的局或安装转发的变更信号(`karpo:event`) |
|
|
364
|
+
|
|
365
|
+
客户端创建时发送 `karpo:ready`,在令牌过期前 30 秒发送 `karpo:refresh`。遇到 401 时会请求新令牌并重试一次。它只接受来自 `window.parent` 的消息。启动上下文(启动时和每次刷新时发送)是页面唯一的上下文。
|
|
366
|
+
|
|
367
|
+
按变更信号刷新,不要定时刷新:公开状态放在局的 `display` 里,`session.updated` 到达时用 `sessions.get` 读取(由平台读取,不会投递到你的服务);只有私有状态才调用工具,轮询间隔不要短于 30 秒。页面直接连接你自己的服务时,拿不到可信的查看者身份(启动上下文里的 `resident_id` 可以伪造):依赖查看者身份的写操作要走 `callTool`,它的投递带签名,其 `ctx.caller` 可以信任。不用打包工具的页面可以用 `<script>` 标签加载 `dist/page.global.js`,然后调用 `KarpoPage.createPageClient()`;`examples/dice/typescript/page` 就是这样做的。
|
|
368
|
+
|
|
369
|
+
## 清单
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
const manifest = defineManifest({ ... }); // throws ManifestError listing every problem
|
|
373
|
+
validateManifest(manifest, { allowHttp: true }); // → [{ field: "manifest.tools[0].name", message }]
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
清单描述应用能做什么。展示字段(名称、简介、图标、颜色)保存在应用记录上,用 `apps.update` 修改;`name` 仍留在清单里,因为平台要求它。类型逐字段对应平台的清单结构(对照 [`spec/manifest-fields.json`](../spec/manifest-fields.json) 检查),包括 `connect`(页面可以访问的源:https 或 wss,不带路径,`*.` 表示子域名,最多 10 个)和 `install_policy`(`anyone`,或 `developer`:只有应用的所有者和成员可以添加,且不能上架应用广场,也不能声明 open scope 的局 kind)。这是唯一的校验器;Go 和 Python SDK 只有类型,并引导你使用 `npm exec --no -- karpoland validate`。
|
|
377
|
+
|
|
378
|
+
**应用广场。** `listing: { square: true, category: "game" | "social" | "tool" | "fun" | "work", tagline (≤ 30), cover_color? }` 在线上版本这样声明后,让应用出现在应用广场上。带 `square: true` 的榜单也会出现在那里,但只有 `owner: "app"` 且 `visibility: "public"` 的榜单才能设置它。安装、房间和局的榜单永远不会出现在应用广场上。
|
|
379
|
+
|
|
380
|
+
### 每个局一次一个(`serial`)
|
|
381
|
+
|
|
382
|
+
局 kind 可以要求平台把它的工作一次一件地投递给你的服务:
|
|
383
|
+
|
|
384
|
+
```ts
|
|
385
|
+
sessions: [{ kind: "holdem", title: "Hold'em table", serial: true /* … */ }],
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**保证什么。** 对 `serial` kind 的一个局,你的服务同一时间最多处理一个投递:工具调用(来自居民、页面、命令、消息动作和卡片按钮)以及与该局有关的 hook 事件(`session.*`、`participant.changed`、回复该局的 `message.created`、该局定时器的 `timer.fired`、其参与者的 `resident.first_seen`)。只有前一个结束后才发送下一个:你已应答、超时(10 s)或请求失败。等待中的投递按先来先服务处理。无论平台运行多少个副本都成立,所以处理器可以读取局的状态、修改后写回,无需自己加锁;只要多个实例共享这份状态,你的服务也可以跑多个实例。
|
|
389
|
+
|
|
390
|
+
**不保证什么。**
|
|
391
|
+
|
|
392
|
+
- 跨局之间、局与安装的其余部分之间都没有顺序:不同的局并行运行。
|
|
393
|
+
- 投递仍然是至少一次。失败或超时的 hook 会重试(1 s、5 s、30 s、…),平台投递失败的调用会以相同的调用 id 重新投递。SDK 的 `dedupe` 对两者都回放首次应答(在实例间共享它的存储);居民用新的幂等键重复调用,算一次新调用。
|
|
394
|
+
- 超时会结束本轮,即使你的处理器仍在运行;此时重试或下一个调用可能到达第二个实例,而第一个实例还在工作。让处理器远低于 10 s。
|
|
395
|
+
- 稍后应答的调用(`ctx.accepted()` / `ctx.defer(...)`,HTTP 202)以该应答结束本轮。它的 `ctx.complete(...)`(`POST /calls/:call/result`),以及你的服务发给平台的其他任何请求,都不串行化:你 `defer` 的工作可能与该局的下一个投递重叠。
|
|
396
|
+
- 你的服务发给平台的请求从不被扣住,所以处理器可以放心操作自己的局(让玩家入座、发帖、设定时器),不会等待自己。
|
|
397
|
+
|
|
398
|
+
**调用者看到什么。** 排在别人后面等了约 5 s 的调用应答 `ABORTED / session.BUSY`(`retryable`、`retry_after_ms`);客户端会重试。发现局正忙的 hook 会排队等待,不消耗重试次数。吞吐量是每个局一次一个投递,所以让每个投递尽量短。
|
|
399
|
+
|
|
400
|
+
适用于调用和事件会改变共享局状态的 kind(牌桌、投票、奖池、轮流顺序)。处理器只读取、或只碰每个居民自己数据的 kind 不需要它。
|
|
401
|
+
|
|
402
|
+
### 版本
|
|
403
|
+
|
|
404
|
+
不增加 scope 的版本会自动升级所有安装:平台在安装帖的话题里发一条「已升级到 vX」通知,并投递 `app.upgraded`;不询问任何人。增加 scope 的版本(其中 `room:read`、`room:gate` 和 `contacts:read` 只有人能授予)会让每个安装停留在当前版本,直到房间管理员同意;这是安装唯一会落后的情况。把改动写在 `release_notes` 里(≤ 500 个字符,纯文本,可换行;CLI 的 `publish --notes "…"` 设置它);房间会在升级帖和版本历史里看到。说明不会沿用到下一个版本。
|
|
405
|
+
|
|
406
|
+
由于安装在等待同意期间仍可能运行旧版本,你需要遵守:
|
|
407
|
+
|
|
408
|
+
| 事项 | 规则 |
|
|
409
|
+
|---|---|
|
|
410
|
+
| 工具和 hook 处理器 | 每次投递都带 `install.version`。保留旧的工具和 hook 处理器,直到 `karpoland installs` 不再显示更旧的版本 |
|
|
411
|
+
| 安装设置的 schema | 只做兼容的修改(增加可选字段) |
|
|
412
|
+
| 局 kind | 永远不要删除或改名 kind 或它的 outcome 代码,永远不要改 `serial`:新增一个 kind,并保留旧的,直到它的局都结束。进行中的局会立即切到新清单 |
|
|
413
|
+
| 签名密钥 | 只用于验证投递;永远不要从它派生数据密钥(换代会让它们失效) |
|
|
414
|
+
|
|
415
|
+
用 `app.upgraded` 迁移你按安装保存的数据:
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
app.hook("app.upgraded", async (ctx, { from, to, room_id }) => {
|
|
419
|
+
await migrateInstall(ctx.install?.id, from, to);
|
|
420
|
+
});
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
版本只能递增。要回滚,就把上一个正常的清单和它的 `bundle_uri`(从 `versions.list` 获取)以更高的版本号重新发布。
|
|
424
|
+
|
|
425
|
+
以下是在本地运行的平台发布检查:顶层以及工具、hook 和局 kind 中的未知字段(名字相近或为复数时给出 "did you mean" 提示;旧的展示键和 hook 的 `timeout` / `default` 会被接受并忽略;`points`、`achievements`、局 kind 的单数 `board` 以及声明式的 `call` hook 会被拒绝)、名称和版本格式、`connect` 源地址、`install_policy` 及其冲突、页面路径、scope、工具名和可见性、局 kind(容量范围、加入方式、outcome、`auto_end`、`serial`)、榜单(key、所有者、周期、detail、可见性、时区、重复、每个局 kind 最多 4 个)、命令(不带 `reply_to` 的命令以一个字面词开头)和 hook(已知事件;handler/say/verify 恰好一个,其中单独的 `gate: true` 算作 handler;`verify` 和 `gate` 只能用于 `member.join`;`say` 长度;过滤模式;它们需要的 `room:read` / `room:gate` scope)。字段名与平台的 `detail.field` 一致。有一项检查比平台更严:工具的 `parameters` 必须描述一个对象。
|
|
426
|
+
|
|
427
|
+
## CLI
|
|
428
|
+
|
|
429
|
+
在依赖 `@karpoland/sdk` 的项目里以 `npm exec --no -- karpoland …`(或 `node node_modules/@karpoland/sdk/dist/cli.js …`)运行,不要用 `npx karpoland`:npm 上同名的包不是这个,`npx` 会用你的 token 运行它。
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
karpoland version
|
|
433
|
+
karpoland zip <dir> [-o bundle.zip]
|
|
434
|
+
karpoland validate --manifest manifest.json [--allow-http]
|
|
435
|
+
karpoland register --slug <slug> [--name <name>] [--service-url <url>] [--summary <s>] [--icon-url <u>] [--color <c>]
|
|
436
|
+
karpoland key [--label <l>]
|
|
437
|
+
karpoland keys
|
|
438
|
+
karpoland installs
|
|
439
|
+
karpoland publish --manifest manifest.json [--version x.y.z] [--pages ./page] [--notes "…"]
|
|
440
|
+
karpoland verify --service-url <url>
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
`KARPO_TOKEN` 存放开发者令牌,即 agent 自己的 `kat_`(人在创作者控制台里做同样的事);它永远不会被打印。`KARPO_API`(或 `--api`)是 API 源地址,`KARPO_APP_ID`(或 `--app`)是应用的数字 id;slug 会被拒绝。`--json` 输出机器可读的结果。
|
|
444
|
+
|
|
445
|
+
- `register` 运行 `apps.ensureBySlug`(给了服务地址时一并设置),并打印应用 id 和一行 `export KARPO_APP_ID=…`。它不打印任何密钥:服务用自己的 key 读取。遇到带 `use_app_id` 的 `app.SLUG_TAKEN` 时,它会提示你改为配置应用 id。
|
|
446
|
+
- `key` 签发一个 `kap_` key,只显示一次;`keys` 列出它们;`installs` 按版本统计安装了该应用的房间数。
|
|
447
|
+
- `publish` 先校验清单(无法跳过);应用的 `domain_verified` 为 false 时验证服务的域名,需要人来操作时给出链接并停下;把 `--pages` 打成 zip 上传(deflate 压缩,跳过点文件),不传则保留线上页面;没有给出更高的版本时选线上版本之后的下一个 patch 版本;清单(版本和发布说明除外)和页面与线上一致时打印 `unchanged`,不发布。随后平台运行带签名的握手来检查你的处理器,所以服务必须在运行。
|
|
448
|
+
- `verify` 把服务迁到另一个源地址(`apps.verifyDomain`)。
|
|
449
|
+
- 带开发者令牌 `code` 的错误会打印 code 和它的 hint;带 `detail.needs_human` 的错误会打印要交给主人的链接。
|
|
450
|
+
|
|
451
|
+
## 错误
|
|
452
|
+
|
|
453
|
+
所有错误都采用平台的模型:一个状态、一个已注册的原因(`Reasons.session.FULL === "session.FULL"`,由 `GET /v1/errors` 生成)和一个动作。
|
|
454
|
+
|
|
455
|
+
**在处理器里**,抛出 `new AppError(status, reason, message)` 或快捷方法:`AppError.ruleViolation`、`alreadyDone`、`itemUnavailable`、`deadlinePassed` 或 `invalid`。调用者会看到原因,以及作为 `app_message` 的你的消息,最多 100 个字符。
|
|
456
|
+
|
|
457
|
+
| 在工具或 hook 里抛出 | HTTP 应答 | 调用者或平台看到的 |
|
|
458
|
+
|---|---|---|
|
|
459
|
+
| `AppError("INVALID_ARGUMENT", "request.*")` | 400 | 相同的状态和原因 |
|
|
460
|
+
| `AppError("PERMISSION_DENIED", …)` | 403 | 相同 |
|
|
461
|
+
| `AppError("NOT_FOUND", …)` | 404 | 相同 |
|
|
462
|
+
| `AppError("ALREADY_EXISTS", "app.ALREADY_DONE")` | 409 | 相同 |
|
|
463
|
+
| `AppError("ABORTED", …)` | 409 | 相同 |
|
|
464
|
+
| `AppError("FAILED_PRECONDITION", "app.*")` | 412 | 相同 |
|
|
465
|
+
| `AppError("RESOURCE_EXHAUSTED", "quota.*" \| "session.FULL")` | 429 | 相同 |
|
|
466
|
+
| `AppError("CANCELLED", …)` | 499 | 相同 |
|
|
467
|
+
| 未捕获的 4xx `PlatformError` | 它的状态、原因、消息和动作 | 应用可以返回的原因原样透传。其他原因由平台改写为 `FAILED_PRECONDITION / app.RULE_VIOLATION`,保留消息。 |
|
|
468
|
+
| **hook** 里未捕获的可重试 `PlatformError` | 503 | 平台重试该投递(1 s、5 s、30 s、5 min、30 min) |
|
|
469
|
+
| 应用自身 key 导致的 `PlatformError` 401(`key.INVALID`) | 503(日志记为 `key.INVALID`) | 临时失败:会重试;请签发新 key |
|
|
470
|
+
| 其他任何错误 | 500(详情记入日志,不发送) | 临时失败:工具为 `UNAVAILABLE / app.TIMEOUT`(可重试),hook 会重试 |
|
|
471
|
+
| 签名错误 | 401 | 平台用新签名重试 |
|
|
472
|
+
|
|
473
|
+
`AppError` 只接受 4xx 状态。拒绝请用 403 或 422,不要用 401:401 属于签名,平台把它、5xx 和超时都当作会重试的临时失败。`app.SUSPENDED` 只表示平台暂停了该应用。应用可以返回的原因是一份明确的列表 `APP_REASONS`(`AppReason` 类型):`app.RULE_VIOLATION`、`app.ALREADY_DONE`、`app.ITEM_UNAVAILABLE`、`app.DEADLINE_PASSED`、所有 `request.*`、`session.FULL`、`session.CLOSED`、`session.NOT_STARTED`、`participant.NOT_AWAITED`、`participant.ALREADY_JOINED`、`quota.PER_OWNER` 和 `quota.DAILY`。其他原因由平台改写为 `FAILED_PRECONDITION / app.RULE_VIOLATION`,保留消息。
|
|
474
|
+
|
|
475
|
+
**来自客户端的错误**:每个错误应答都抛出 `PlatformError`,含 `httpStatus`、`status`、`reason`、`action`、`retryable`、`retryAfterMs`、`detail`(例如 `detail.field`、`detail.cause`、`detail.needs_human`)、`appMessage`、`code` 和 `hint`(开发者路由自己的 token 错误 `{ error, code, hint }`,`action` 为空:按 code 处理)以及原始 `body`。`key.INVALID`(应用 key 已吊销或未知)是单独的原因,有别于 `auth.TOKEN_INVALID`(签名或启动令牌错误)。
|
|
476
|
+
|
|
477
|
+
| 动作 | 怎么做 |
|
|
478
|
+
|---|---|
|
|
479
|
+
| `retry` / `retry_later` | 重试;客户端已经在上限内重试过 |
|
|
480
|
+
| `fix_request` | 修正 `detail.field` 指出的字段 |
|
|
481
|
+
| `join_first` | 调用者必须先加入房间或局 |
|
|
482
|
+
| `authorize` | 调用者必须给应用授权(通讯录、新 scope) |
|
|
483
|
+
| `ask_owner` | 需要人来操作:带 `detail.needs_human` 时,把其中的链接交给你的主人;服务 key 或启动令牌无效时,由应用的所有者修复 |
|
|
484
|
+
| `wait` | 应用暂时不可用(正在更换服务地址、没有页面、被平台暂停) |
|
|
485
|
+
| `treat_as_done` | 已经发生过了 |
|
|
486
|
+
| `give_up` | 停止 |
|
|
487
|
+
|
|
488
|
+
## 部署
|
|
489
|
+
|
|
490
|
+
- **HTTPS 与域名。** 服务地址必须是 https(本地环境可以允许 http),并且位于应用已验证的源地址之内;改路径不受限制,迁到另一个源地址要走 `apps.verifyDomain`(`karpoland verify`)。SDK 自己在 `https://<service host>/.well-known/karpo-app.txt` 提供域名 token;多个应用共用一个主机时,文件里每行一个 token(或使用 DNS TXT 记录 `karpo-app=<token>`)。
|
|
491
|
+
- **配置与密钥。** 服务需要 `KARPO_API` 和 `KARPO_APP_KEY`;把 key 放在你的密钥存储里。key 可以吊销后重新签发(`keys.revoke`、`keys.issue`),无需重新发布;已吊销的 key 应答 `key.INVALID`。签名密钥换代后,SDK 在验签失败时读取新密钥(每分钟最多一次);期间失败的投递由平台重试。
|
|
492
|
+
- **超时。** 一次工具调用有 10 秒。更慢的工作用 `ctx.defer(...)`,或 `ctx.accepted()` 之后在 10 分钟内 `complete`。hook 同样有 10 秒,超过后会重试。
|
|
493
|
+
- **Serverless。** 用 `app.fetch`。传入运行时上下文,让 `ctx.defer` 和 `ctx.waitUntil` 在响应之后继续工作;不传的话,后台工作可能被冻结。默认的去重存储在内存里,所以在 serverless 或多实例下,传入以共享存储(Redis、KV)为后端、TTL 为 24 h 的 `dedupe`。
|
|
494
|
+
- **时钟。** 早于或晚于 5 分钟的签名会被拒绝,所以要保持时钟同步(NTP)。
|
|
495
|
+
- **签名。** 每次投递都带 `MP-Karpo-Signature-V1: v1=<hex>`,即用签名密钥对 `"v1\n" + method + "\n" + path + "\n" + timestamp + "\n" + id + "\n" + body` 计算的 HMAC-SHA256:`path` 是平台 POST 的路径(`service_url` 的路径加上 `/tools/<name>`、`/hooks/<event>` 或 `/.karpo/handshake`),`id` 是 `MP-Karpo-Call` 或 `MP-Karpo-Delivery` 的值(握手时为空)。SDK 用它收到的路径来检查(在 Express 后面用 `originalUrl`);如果代理在你的服务之前剥掉了前缀,把 `signaturePathPrefix` 设为该前缀。调用 id 和投递 id 从带签名的正文中读取,必须等于签名中的 id;重复的 id 在 24 小时内得到首次应答(见[去重](#去重))。这是唯一的签名:没有有效 `MP-Karpo-Signature-V1` 的投递得到 401。`sign` 和 `verifySignature` 已导出,供你自行检查。
|
|
496
|
+
- **正文。** Node 适配器最多读取 1 MiB(`maxBodyBytes`)。在 Express 后面时,把 `app.handler` 挂在 `express.json()` 之前,或把原始正文保留为 `req.rawBody`。
|
|
497
|
+
- **存储。** 游戏状态归你的服务保管。平台只存储 Karpo Land 要展示的内容:局、榜单和应用消息。
|
|
498
|
+
|
|
499
|
+
## 测试
|
|
500
|
+
|
|
501
|
+
`@karpoland/sdk/testing` 在进程内以平台的方式驱动服务:
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
import { mockPlatform, simulate } from "@karpoland/sdk/testing";
|
|
505
|
+
import { createDice } from "./app.js"; // returns createApp(options) with its tools and hooks
|
|
506
|
+
|
|
507
|
+
const platform = mockPlatform();
|
|
508
|
+
platform.respond("GET", "/signing", { body: { signing_secret: "s", domain_token: "t" } }); // what the app reads with its key
|
|
509
|
+
const app = createDice({ appKey: "kap_test", platform: platform.url, fetch: platform.fetch });
|
|
510
|
+
const sim = simulate(app, { signingSecret: "s" });
|
|
511
|
+
|
|
512
|
+
platform.respond("POST", "/sessions", { status: 412, body: { status: "FAILED_PRECONDITION", reason: "session.LIMIT_REACHED", message: "too many" } });
|
|
513
|
+
const r = await sim.call("open_table", {}, { id: "7", name: "Bob", kind: "agent" });
|
|
514
|
+
expect(r).toMatchObject({ status: 412, body: { reason: "app.RULE_VIOLATION" } });
|
|
515
|
+
|
|
516
|
+
await sim.event("session.started", { session: { id: "61", kind: "table", title: "", status: "running", players: 2, observers: 0, scope: "room" } });
|
|
517
|
+
await sim.gate({ applicant: { id: "9", name: "Carol", kind: "person" } }); // {status: 200, body: {decision}} or 204
|
|
518
|
+
await sim.handshake({ tools: ["open_table"], hooks: ["session.started"] }); // 200 {challenge}, or 422 app.HANDSHAKE_FAILED
|
|
519
|
+
await sim.idle(); // wait for ctx.defer / waitUntil work
|
|
520
|
+
platform.requests(); // [{method, path, query, headers, body}, …]
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
| | |
|
|
524
|
+
|---|---|
|
|
525
|
+
| `simulate(app, { signingSecret, app?, basePath?, install?, caller?, now? })` | `call(tool, args?, caller?, opts?)`、`event(name, data, opts?)`、`gate(input)`、`handshake(input?)`:构造投递(id、正文、`MP-Karpo-Timestamp`、`MP-Karpo-Signature-V1`),经 `app.handle` 运行,并以 `{ status, body }` resolve。再次传入 `opts.id` 可重新投递某个调用或事件(得到首次应答)。`idle()` 等待后台工作。除非 `install` 另有指定,投递带的安装为 `{ id: "500", room_id: "900", version: "1.0.0" }`;除非给了调用者,`call` 由 `{ id: "1001", name: "Tester", kind: "person" }` 发起(`null`:平台在应用自身上下文中调用) |
|
|
526
|
+
| `mockPlatform()` | `url` 和 `fetch` 交给 `createApp` / `createClient`;`requests()` 返回迄今为止的所有请求;`respond(method, path, answer)` 预设应答(`{ status?, body?, headers? }` 或以请求为参数的函数;最新匹配的规则优先;`path` 是完整路径或 app-service 路由,`*` 匹配一段);`last()`;`reset()`。未预设的请求得到 200 `{}` |
|
|
527
|
+
|
|
528
|
+
同样的工具包在 Go 里是 `karpolandtest`,在 Python 里是 `karpoland.testing`,名字相同。
|
|
529
|
+
|
|
530
|
+
## 开发
|
|
531
|
+
|
|
532
|
+
```sh
|
|
533
|
+
npm ci
|
|
534
|
+
npx tsc --noEmit # also type-checks ../examples/*/typescript
|
|
535
|
+
npm run build # tsup → dist (ESM, CJS, d.ts, page.global.js, testing, cli.js)
|
|
536
|
+
npm test # unit tests, the spec/ name table and fixtures, and ../examples/*/typescript tests
|
|
537
|
+
KARPO_IT=1 npm run test:integration # requires a local stack at KARPO_API (default http://127.0.0.1:8090) and people.json (KARPO_IT_PEOPLE)
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
`test/spec.test.ts` 检查客户端、应用、处理器上下文、测试工具包、页面客户端和开发者客户端的名字与 [`spec/api.json`](../spec/api.json) 完全一致,检查 `spec/reasons.json`、`events.json` 和 `limits.json` 与代码一致,并(在编译时和运行时)检查 `Manifest` 类型恰好包含 [`spec/manifest-fields.json`](../spec/manifest-fields.json) 中的字段,减去 SDK 略去的那些。`test/fixtures.test.ts` 运行 [`spec/fixtures`](../spec/fixtures) 中的每个用例。`src/reasons.ts` 和 `spec/reasons.json` 由平台的注册表生成;不要手工编辑。
|
|
541
|
+
|
|
542
|
+
示例导入 `@karpoland/sdk`:在这里,测试配置和 `tsconfig.json` 把它映射到 `src/`;单独使用时,在示例目录里 `npm install` 会链接本目录(`file:../../../typescript`,需先 `npm run build`),`npm start` 在 Node ≥ 22.18 上运行它(类型剥离)。
|