gamealgo-cli 0.1.6 → 0.1.7

package/README.md

@@ -23,11 +23,14 @@ gamealgo docs agent-onboarding --host <admin-host>
 
 ```bash
 gamealgo login --host <admin-host> --admin-key <ga_admin_xxx>
+gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --out gamealgo-integration-plan.json
 gamealgo key list --json
 gamealgo key create --name <runtime-name> --json
 gamealgo key reveal --name <runtime-name> --json
 ```
 
+AI Agent 必须先执行 `integration get-plan`，并按返回的完整清单完成接入和人工验收。不要依赖只读某一份 README 后自行推断其他平台规则。
+
 凭据保存在当前游戏项目的 `.gamealgo/cli.json`，不同游戏互不覆盖。需要其他主题时使用：
 
 ```bash

package/cli/README.md

@@ -71,6 +71,21 @@ GAMEALGO_GAME_ADMIN_KEY=ga_admin_xxx
 gamealgo whoami
 ```
 
+## 接入计划
+
+登录后先让 CLI 根据开发者明确指定的环境和平台生成完整接入计划。CLI 不自动猜测环境或平台：
+
+```bash
+gamealgo integration get-plan \
+  --environment domestic \
+  --platform maker \
+  --out gamealgo-integration-plan.json
+```
+
+支持的环境是 `domestic`、`overseas`；支持的平台是 `ios`、`android`、`maker`、`rest`。计划包含正确地址、强制初始化规则、核心事件、广告/归因/实验条件项、验收标准和按需参考文档。
+
+计划同时包含接入完成后必须逐项执行的人工验收清单。不能只根据命令执行成功或生产报表有数据来判断接入已经完成。
+
 ## 最新文档
 
 AI Agent 可以通过 CLI 从 Admin Host 获取最新文档，不需要拉取本仓库：
@@ -311,6 +326,8 @@ gamealgo config publish configs/gameplay.json
 ## Report Pack
 
 ```bash
+gamealgo events list --days 30 --json
+gamealgo events apply gamealgo-events.yaml --json
 gamealgo report pull --out gamealgo-report-pack.json
 gamealgo report validate gamealgo-report-pack.json
 gamealgo report publish gamealgo-report-pack.json
@@ -318,7 +335,7 @@ gamealgo report publish gamealgo-report-pack.json
 
 每个游戏只有一个当前 Report Pack。`publish` 会整体覆盖上一次提交的配置，不需要传版本号；配置历史由游戏项目自己的 Git 管理。
 
-`report validate` 和 Admin 控制台保存时使用同一套服务端校验逻辑。
+`report validate` 和 `report publish` 使用同一套服务端元数据校验逻辑，只检查配置结构、事件词典与生成 SQL，不查询线上数据。凡是 Report Pack 顶层 `events` 引用的标准事件或自定义事件，其字段都必须已经登记、未废弃且字段类型一致；只引用标准看板和纯 marketing dataset 时，不需要重复登记平台内部字段。
 
 ## Adjust 投放花费
 
@@ -410,6 +427,59 @@ gamealgo report preview \
 
 ## 事件上报调试
 
+### 先查看并维护事件词典
+
+开始新增埋点或设计报表前，Agent 必须先查看当前游戏已经登记和实际上报的埋点：
+
+```bash
+gamealgo events list --days 30
+```
+
+列表会展示埋点描述、生效版本、创建时间、状态和字段定义，并根据近 30 天非调试数据给出事件级诊断：
+
+- 线上出现但词典未登记；
+- 词典已登记但近期未观测；
+- 埋点已废弃但线上仍在上报。
+
+诊断只检查埋点是否存在，不根据线上 payload 自动推断字段或字段类型。字段必须由开发 Agent 显式登记后再用于 Report Pack。标准事件同样可以维护词典并追加游戏业务字段，例如在 `level_end.payload` 中增加关卡、章节或玩法信息。
+
+Report Pack 的 `events.<eventType>.fields` 字段 ID 必须与词典字段名一致，`path` 只描述 payload 中的实际 JSON 路径。例如词典登记 `ad_type` 后，Report Pack 可以用 `"path": "$.adType"` 读取驼峰字段，但字段类型必须与词典一致。
+
+用 YAML 或 JSON 增量登记埋点：
+
+```yaml
+events:
+  level_end:
+    desc: 玩家结束关卡
+    effectiveVersion: 1.2.0
+    category: progression
+    source: standard
+    fields:
+      level_id:
+        type: string
+        required: true
+        desc: 关卡 ID
+        effectiveVersion: 1.2.0
+      chapter_id:
+        type: string
+        required: false
+        desc: 游戏追加的章节 ID
+```
+
+```bash
+gamealgo events apply gamealgo-events.yaml
+gamealgo events get level_end
+```
+
+规则：
+
+- 埋点必须填写 `desc`，`effectiveVersion` 可省略；创建时间由平台首次登记时生成。
+- 字段必须填写 `type` 和 `desc`，`effectiveVersion` 可省略；字段创建时间由平台生成。
+- 标准事件使用 `source: standard`，自定义事件使用 `source: custom`；两者都可以登记游戏追加的 payload 字段。
+- `apply` 只新增或更新文件中出现的埋点和字段，不会删除其他已有定义。
+- 不再使用的埋点需要显式废弃：`gamealgo events deprecate old_event --yes`。
+- 再次 `apply` 已废弃埋点会将其恢复为启用状态。
+
 接入 SDK 后，Agent 可以用 `events count` 检查某天事件是否已经进入原始事件表：
 
 ```bash

package/dist/gamealgo.js

@@ -74,6 +74,10 @@ async function main() {
             await handleEvents(client, args, global);
             return;
         }
+        if (command === "integration") {
+            await handleIntegration(client, args, global);
+            return;
+        }
         if (command === "marketing") {
             await handleMarketing(client, args, global);
             return;
@@ -832,9 +836,42 @@ async function handleReport(client, args, global) {
 }
 async function handleEvents(client, args, global) {
     const sub = args.shift();
-    if (sub !== "count")
-        throw new Error("usage: gamealgo events count [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--event-type level_end]");
     const flags = parseFlags(args);
+    if (sub === "list") {
+        if (args.length)
+            throw new Error("usage: gamealgo events list [--days 30] [--no-diagnostics]");
+        const days = Number(flags.days || 30);
+        if (!Number.isInteger(days) || days < 1 || days > 90)
+            throw new Error("--days must be an integer between 1 and 90");
+        await writeEventCatalogOutput(await client.listEventCatalog(days, flags["no-diagnostics"] !== true), flags, global);
+        return;
+    }
+    if (sub === "get") {
+        const eventType = args.shift();
+        if (!eventType || args.length)
+            throw new Error("usage: gamealgo events get <eventType>");
+        await writeEventCatalogOutput(await client.getEventCatalog(eventType), flags, global);
+        return;
+    }
+    if (sub === "apply") {
+        const filePath = args.shift();
+        if (!filePath || args.length)
+            throw new Error("usage: gamealgo events apply <events.yaml>");
+        const content = await readObjectFile(filePath, "event catalog");
+        await writeEventCatalogOutput(await client.applyEventCatalog(content), flags, global);
+        return;
+    }
+    if (sub === "deprecate") {
+        const eventType = args.shift();
+        if (!eventType || args.length)
+            throw new Error("usage: gamealgo events deprecate <eventType> [--yes]");
+        if (!flags.yes && !(await confirm(`Deprecate event ${eventType}?`)))
+            throw new Error("Cancelled");
+        await writeEventCatalogOutput(await client.deprecateEventCatalog(eventType), flags, global);
+        return;
+    }
+    if (sub !== "count")
+        throw new Error("usage: gamealgo events <list|get|apply|deprecate|count>");
     const timeoutMs = reportTimeoutMs(flags);
     const startedAt = Date.now();
     const stopProgress = startProgress("Querying event counts", timeoutMs);
@@ -859,6 +896,40 @@ async function handleEvents(client, args, global) {
     }
     await printResult(outputValue, global);
 }
+async function writeEventCatalogOutput(value, flags, global) {
+    if (flags.out) {
+        const filePath = String(flags.out);
+        const content = filePath.endsWith(".json") ? JSON.stringify(value, null, 2) + "\n" : YAML.stringify(value);
+        await writeTextFile(filePath, content);
+        await printResult({ ok: true, out: filePath }, global);
+        return;
+    }
+    await printResult(value, global);
+}
+async function handleIntegration(client, args, global) {
+    const sub = args.shift();
+    const flags = parseFlags(args);
+    if (args.length)
+        throw new Error("unexpected positional arguments for integration command");
+    const environment = integrationEnvironment(flags.environment);
+    const platform = integrationPlatform(flags.platform);
+    if (sub === "get-plan" || sub === "plan") {
+        const response = await client.getIntegrationPlan(environment, platform);
+        await writeIntegrationOutput(response, flags, global);
+        return;
+    }
+    throw new Error("usage: gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest>");
+}
+async function writeIntegrationOutput(value, flags, global) {
+    if (flags.out) {
+        if (typeof flags.out !== "string")
+            throw new Error("--out requires a file path");
+        await writeTextFile(flags.out, JSON.stringify(value, null, 2) + "\n");
+        await printResult({ ok: true, out: flags.out }, global);
+        return;
+    }
+    await printResult(value, global);
+}
 async function handleMarketing(client, args, global) {
     const provider = args.shift();
     if (provider !== "adjust")
@@ -1168,6 +1239,23 @@ class GameAlgoAdminClient {
     async countEvents(body, options = {}) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/count`, body, options);
     }
+    async listEventCatalog(days = 30, diagnostics = true) {
+        const params = new URLSearchParams({ days: String(days), diagnostics: diagnostics ? "1" : "0" });
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog?${params.toString()}`);
+    }
+    async getEventCatalog(eventType) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}`);
+    }
+    async applyEventCatalog(content) {
+        return await this.put(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog`, content);
+    }
+    async deprecateEventCatalog(eventType) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/deprecate`, {});
+    }
+    async getIntegrationPlan(environment, platform) {
+        const params = new URLSearchParams({ environment, platform });
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/integration/plan?${params.toString()}`);
+    }
     async getAdjustMarketing() {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/marketing/adjust`);
     }
@@ -1680,6 +1768,18 @@ async function confirm(question) {
 function normalizeHost(value) {
     return value.trim().replace(/\/+$/, "");
 }
+function integrationEnvironment(value) {
+    const environment = optionalString(value);
+    if (environment === "domestic" || environment === "overseas")
+        return environment;
+    throw new Error("--environment must be domestic or overseas");
+}
+function integrationPlatform(value) {
+    const platform = optionalString(value);
+    if (platform === "ios" || platform === "android" || platform === "maker" || platform === "rest")
+        return platform;
+    throw new Error("--platform must be ios, android, maker, or rest");
+}
 function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
@@ -1719,6 +1819,8 @@ Usage:
   gamealgo docs experiment-integration-versions --open
   gamealgo docs --host <admin-url>
 
+  gamealgo integration get-plan --environment domestic --platform maker --out gamealgo-integration-plan.json
+
   gamealgo experiment strategies
   gamealgo experiment strategies --include-archived
   gamealgo experiment integration-version latest
@@ -1767,6 +1869,10 @@ Usage:
 
   gamealgo events count --from 2026-06-23 --to 2026-06-23
   gamealgo events count --from 2026-06-23 --to 2026-06-23 --event-type level_end
+  gamealgo events list --days 30
+  gamealgo events get level_start
+  gamealgo events apply gamealgo-events.yaml
+  gamealgo events deprecate old_event --yes
 
   gamealgo marketing adjust get
   gamealgo marketing adjust configure --api-token <token> --app-token <app-token> --platform ios --currency USD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "type": "module",
   "bin": {