gamealgo-cli 0.1.0 → 0.1.2

package/README.md

@@ -111,7 +111,7 @@ docs/       接入、埋点、报表和优化文档
 | 环境 | SDK / REST API | Admin / CLI |
 | --- | --- | --- |
 | 国内 | `https://game-algo-sdk.dictapis.cn` | `https://game-algo-admin.dictapis.cn` |
-| 海外 | `https://gamealgo-server-v2.gamealgo-sdk-1ea5b9.workers.dev` | `https://dirichlet.ai/algo_admin` |
+| 海外 | `https://dirichlet.ai/algo_sdk` | `https://dirichlet.ai/algo_admin` |
 
 客户端 SDK 只配置 SDK / REST API 地址。Admin / CLI 地址只给开发者、AI Agent 和 CI 使用。
 

package/cli/README.md

@@ -18,6 +18,7 @@ CLI 使用游戏维度的 Game Admin Key 鉴权。这个 key 只绑定一个游
 ```bash
 npm install -g gamealgo-cli@latest
 gamealgo help
+gamealgo --version
 ```
 
 更新 CLI 使用同一条命令：
@@ -28,6 +29,8 @@ npm install -g gamealgo-cli@latest
 
 安装和更新不需要拉取 GameAlgo Client 仓库。Node.js 版本需要为 24 或更高。
 
+Client SDK 源码仓库：<https://github.com/sunyuhao-code/GameAlgoClient>
+
 只有开发 CLI 本身时才需要源码仓库。源码内调试可以用 npm script，但涉及 `--json` 的命令必须加 `--silent`，避免 npm 自己的日志污染 JSON stdout：
 
 ```bash
@@ -163,7 +166,8 @@ gamealgo experiment strategy publish strategy.yaml --yes
 displayName: 广告频率第一轮
 type: manual
 platform: ios
-objective: ltv_proxy
+objectiveTemplate: ltv_proxy@1
+baselineVariantId: control
 variants:
   - variantId: control
     weight: 1
@@ -189,15 +193,22 @@ gamealgo experiment run create ad_frequency run.yaml --yes
 gamealgo experiment strategies
 gamealgo experiment strategy show ad_frequency
 gamealgo experiment run show xrun_xxxxxxxxxxxxxxxx
+gamealgo experiment run status xrun_xxxxxxxxxxxxxxxx
 gamealgo experiment run evaluate xrun_xxxxxxxxxxxxxxxx --from 2026-07-01 --to 2026-07-07 --yes
 gamealgo experiment run report xrun_xxxxxxxxxxxxxxxx
-gamealgo experiment run promote xrun_xxxxxxxxxxxxxxxx --variant slower_ads --yes
+gamealgo experiment run promote xrun_xxxxxxxxxxxxxxxx --variant slower_ads --message "采用低频广告组" --yes
+```
+
+`baselineVariantId` 是本次评估的对照组，必须指向一个有流量的实验组。平台按小时更新“当前评估”；`report` 返回已生成的正式报告。`promote` 会把指定 variant 写回 Strategy 默认参数，并结束当前 Run。取消实验用：
+
+```bash
+gamealgo experiment run cancel xrun_xxxxxxxxxxxxxxxx --message "实验停止" --yes
 ```
 
-`promote` 会把胜出的 variant 写回 Strategy 默认参数，并结束当前 Run。取消实验用：
+回滚默认参数会创建一个新的参数版本，不会改写历史版本：
 
 ```bash
-gamealgo experiment run cancel xrun_xxxxxxxxxxxxxxxx --yes
+gamealgo experiment strategy rollback ad_frequency --version-id xv_xxxxxxxxxxxxxxxx --message "回滚线上参数" --yes
 ```
 
 调试指定用户/设备强制进某个实验组：
@@ -214,7 +225,8 @@ gamealgo experiment override delete xrun_xxxxxxxxxxxxxxxx --user user-1 --yes
 displayName: 广告频率托管实验
 type: managed
 platform: ios
-objective: ltv_proxy
+objectiveTemplate: ltv_proxy@1
+baselineVariantId: alpha
 cycleDays: 7
 maxVariantsPerRound: 3
 # 可选：仅托管实验支持。最近 24 小时同时满足两个门槛后才开始首轮。
@@ -232,6 +244,16 @@ variants:
 
 `minCoverage` 表示指定平台最近 24 小时内，实验接入版本达到 Strategy `requiredIntegrationVersion` 的去重用户占比；`minUsers` 表示同一窗口内的非 Debug 去重用户数。两项可单独配置，同时配置时必须同时满足。等待期间 Strategy 继续下发默认参数，满足门槛后平台才生成首轮时间窗并开始分流。手动实验不支持 `startCondition`，托管实验不配置时仍会立即启动。`experiment run show` 返回 `startConditionSnapshot`，可查看当前用户数、覆盖率和最近检查时间。
 
+托管实验只执行候选组数量决定的计划轮次，不会因为结果不显著而自动追加轮次。每轮结束都会生成正式报告；最后一轮只有在证据足够明确时才更新默认参数。没有明确胜出组时，实验正常完成，Strategy 默认参数保持不变。
+
+`ltv_proxy@1` 的标准口径为：
+
+```text
+LTV Proxy = DAU ARPU * (1 + D1 + D2 + D3 + D4 + D5)
+```
+
+其中 DAU ARPU 是实验窗口内总收入除以活跃用户天数；Dx 留存只使用截至评估时已经成熟的 cohort，并按 cohort 用户数加权。平台不会等待最后一天用户的 D5 成熟后再结束实验。
+
 所有会修改线上状态的实验命令都必须显式传 `--yes`。
 
 ## 脚本和配置

package/dist/gamealgo.js

@@ -19,6 +19,16 @@ async function main() {
         printHelp();
         return;
     }
+    if (command === "version" || command === "--version" || command === "-V") {
+        const metadata = await loadPackageMetadata();
+        if (global.json) {
+            await printResult({ ok: true, name: metadata.name, version: metadata.version }, global);
+        }
+        else {
+            console.log(metadata.version);
+        }
+        return;
+    }
     try {
         if (command === "login") {
             await login(args, global);
@@ -353,7 +363,19 @@ async function handleExperimentStrategy(client, args, global) {
         await printResult(await client.archiveExperimentV2Strategy(strategyKey, sub === "archive"), global);
         return;
     }
-    throw new Error("usage: gamealgo experiment strategy <show|publish|default|archive|restore>");
+    if (sub === "rollback") {
+        const flags = parseFlags(args);
+        const strategyKey = optionalString(flags.strategy || flags.key) || optionalString(args.shift());
+        const versionId = optionalString(flags.version || flags["version-id"]);
+        const message = requiredMessage(flags, "experiment strategy rollback");
+        if (!strategyKey || !versionId) {
+            throw new Error("usage: gamealgo experiment strategy rollback <strategyKey> --version-id <versionId> --message <reason> --yes");
+        }
+        await requireYes(flags, global, "experiment strategy rollback");
+        await printResult(await client.rollbackExperimentV2Strategy(strategyKey, versionId, message), global);
+        return;
+    }
+    throw new Error("usage: gamealgo experiment strategy <show|publish|default|archive|restore|rollback>");
 }
 async function handleExperimentRun(client, args, global) {
     const sub = args.shift();
@@ -367,6 +389,12 @@ async function handleExperimentRun(client, args, global) {
         const body = await readObjectFile(filePath, "experiment run");
         if (!optionalString(body.displayName))
             throw new Error("experiment run requires displayName");
+        if (optionalString(body.objectiveTemplate) !== "ltv_proxy@1") {
+            throw new Error("experiment run requires objectiveTemplate: ltv_proxy@1");
+        }
+        if (!optionalString(body.baselineVariantId)) {
+            throw new Error("experiment run requires explicit baselineVariantId");
+        }
         if ((optionalString(body.type) || "manual") !== "managed" && body.startCondition !== undefined) {
             throw new Error("experiment run startCondition is supported only when type is managed");
         }
@@ -387,6 +415,33 @@ async function handleExperimentRun(client, args, global) {
         await printResult(response, global);
         return;
     }
+    if (sub === "status") {
+        const flags = parseFlags(args);
+        const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
+        if (!runId)
+            throw new Error("usage: gamealgo experiment run status <runId>");
+        const response = await client.getExperimentV2Run(runId);
+        const run = response.run;
+        if (!run)
+            throw new Error(`experiment run not found: ${runId}`);
+        await printResult({
+            run: {
+                id: run.id,
+                strategyKey: run.strategyKey,
+                displayName: run.displayName,
+                type: run.type,
+                status: run.status,
+                objective: run.objective,
+                baselineVariantId: run.baselineVariantId,
+                requiredIntegrationVersion: run.requiredIntegrationVersion,
+                startedAt: run.startedAt,
+                endedAt: run.endedAt,
+                promotedVariantId: run.promotedVariantId,
+                currentAssessment: run.currentAssessment ?? null,
+            },
+        }, global);
+        return;
+    }
     if (sub === "evaluate") {
         const flags = parseFlags(args);
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
@@ -397,7 +452,6 @@ async function handleExperimentRun(client, args, global) {
             from: optionalString(flags.from || flags.start || flags.startDate),
             to: optionalString(flags.to || flags.end || flags.endDate),
             days: optionalString(flags.days),
-            platform: optionalString(flags.platform),
         }), global);
         return;
     }
@@ -405,15 +459,29 @@ async function handleExperimentRun(client, args, global) {
         const flags = parseFlags(args);
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
         if (!runId)
-            throw new Error("usage: gamealgo experiment run report <runId> [--report-id <id>]");
+            throw new Error("usage: gamealgo experiment run report <runId> [--round <number> | --report-id <id>]");
         const response = await client.getExperimentV2Run(runId);
         const reports = Array.isArray(response.run?.reports) ? response.run.reports : [];
         const reportId = optionalString(flags.report || flags["report-id"] || flags.id);
-        const report = reportId
-            ? reports.map((item) => objectValue(item)).find((item) => item?.id === reportId || item?.evaluationId === reportId)
-            : objectValue(reports[reports.length - 1]);
-        if (!report)
-            throw new Error(reportId ? `experiment run report not found: ${reportId}` : "experiment run has no reports");
+        const round = flags.round === undefined ? undefined : positiveInteger(flags.round, "round");
+        const latestReport = objectValue(reports[reports.length - 1]);
+        const report = reports
+            .map((item) => objectValue(item))
+            .find((item) => {
+            if (!item)
+                return false;
+            if (reportId)
+                return item.id === reportId || item.evaluationId === reportId;
+            if (round !== undefined) {
+                const managed = objectValue(objectValue(item.report)?.managed);
+                return Number(managed?.roundNumber ?? Number(managed?.roundIndex) + 1) === round;
+            }
+            return item === latestReport;
+        });
+        if (!report) {
+            const selector = reportId ? `: ${reportId}` : round !== undefined ? ` for round ${round}` : "";
+            throw new Error(`experiment run report not found${selector}`);
+        }
         await printResult({ runId, report }, global);
         return;
     }
@@ -422,18 +490,20 @@ async function handleExperimentRun(client, args, global) {
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
         const variantId = optionalString(flags.variant || flags["variant-id"]) || optionalString(args.shift());
         if (!runId || !variantId)
-            throw new Error("usage: gamealgo experiment run promote <runId> --variant <variantId> --yes");
+            throw new Error("usage: gamealgo experiment run promote <runId> --variant <variantId> --message <reason> --yes");
+        const message = requiredMessage(flags, "experiment run promote");
         await requireYes(flags, global, "experiment run promote");
-        await printResult(await client.promoteExperimentV2Run(runId, variantId, optionalString(flags.message)), global);
+        await printResult(await client.promoteExperimentV2Run(runId, variantId, message), global);
         return;
     }
     if (sub === "cancel") {
         const flags = parseFlags(args);
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
         if (!runId)
-            throw new Error("usage: gamealgo experiment run cancel <runId> --yes");
+            throw new Error("usage: gamealgo experiment run cancel <runId> --message <reason> --yes");
+        const message = requiredMessage(flags, "experiment run cancel");
         await requireYes(flags, global, "experiment run cancel");
-        await printResult(await client.cancelExperimentV2Run(runId), global);
+        await printResult(await client.cancelExperimentV2Run(runId, message), global);
         return;
     }
     if (sub === "traffic") {
@@ -441,9 +511,10 @@ async function handleExperimentRun(client, args, global) {
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
         const variantId = optionalString(flags.variant || flags["variant-id"]) || optionalString(args.shift());
         if (!runId || !variantId)
-            throw new Error("usage: gamealgo experiment run traffic <runId> <variantId> [--weight n] [--status running|paused] --yes");
+            throw new Error("usage: gamealgo experiment run traffic <runId> <variantId> [--weight n] [--status running|paused] --message <reason> --yes");
+        const message = requiredMessage(flags, "experiment run traffic");
         await requireYes(flags, global, "experiment run traffic");
-        const body = {};
+        const body = { message };
         if (flags.weight !== undefined)
             body.weight = optionalNonNegativeInteger(flags.weight, "weight");
         if (flags.status !== undefined)
@@ -451,7 +522,13 @@ async function handleExperimentRun(client, args, global) {
         await printResult(await client.updateExperimentV2VariantTraffic(runId, variantId, body), global);
         return;
     }
-    throw new Error("usage: gamealgo experiment run <create|show|evaluate|report|promote|cancel|traffic>");
+    throw new Error("usage: gamealgo experiment run <create|show|status|evaluate|report|promote|cancel|traffic>");
+}
+function requiredMessage(flags, action) {
+    const message = optionalString(flags.message);
+    if (!message)
+        throw new Error(`${action} requires --message <reason>`);
+    return message;
 }
 async function handleExperimentOverride(client, args, global) {
     const sub = args.shift();
@@ -957,6 +1034,12 @@ class GameAlgoAdminClient {
     async archiveExperimentV2Strategy(strategyKey, archived) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/strategies-v2/${encodeURIComponent(strategyKey)}/archive`, { archived });
     }
+    async rollbackExperimentV2Strategy(strategyKey, versionId, message) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/strategies-v2/${encodeURIComponent(strategyKey)}/rollback`, {
+            versionId,
+            message,
+        });
+    }
     async createExperimentV2Run(strategyKey, body) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/strategies-v2/${encodeURIComponent(strategyKey)}/runs`, body);
     }
@@ -979,11 +1062,11 @@ class GameAlgoAdminClient {
     async promoteExperimentV2Run(runId, variantId, message) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/promote`, {
             variantId,
-            ...(message ? { message } : {}),
+            message,
         });
     }
-    async cancelExperimentV2Run(runId) {
-        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/cancel`, {});
+    async cancelExperimentV2Run(runId, message) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/cancel`, { message });
     }
     async listExperimentV2Overrides(runId) {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/overrides`);
@@ -1502,11 +1585,20 @@ function contentTypeForFileName(name) {
         return "text/javascript; charset=utf-8";
     return "text/plain; charset=utf-8";
 }
+async function loadPackageMetadata() {
+    const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const name = typeof packageJson.name === "string" ? packageJson.name : "gamealgo-cli";
+    if (typeof packageJson.version !== "string" || !packageJson.version) {
+        throw new Error("CLI package version is missing");
+    }
+    return { name, version: packageJson.version };
+}
 function printHelp() {
     console.log(`
 GameAlgo CLI
 
 Usage:
+  gamealgo --version
   gamealgo login --host <admin-url> --admin-key <game-admin-key>
   gamealgo whoami
 
@@ -1527,13 +1619,15 @@ Usage:
   gamealgo experiment strategy publish strategy.yaml --yes
   gamealgo experiment strategy default ad_frequency strategy.yaml --yes
   gamealgo experiment strategy archive ad_frequency --yes
+  gamealgo experiment strategy rollback ad_frequency --version-id xv_xxxxxxxxxxxxxxxx --message "回滚参数" --yes
   gamealgo experiment run create ad_frequency run.yaml --yes
   gamealgo experiment run show xrun_xxxxxxxxxxxxxxxx
+  gamealgo experiment run status xrun_xxxxxxxxxxxxxxxx
   gamealgo experiment run evaluate xrun_xxxxxxxxxxxxxxxx --from 2026-07-01 --to 2026-07-07 --yes
-  gamealgo experiment run report xrun_xxxxxxxxxxxxxxxx
-  gamealgo experiment run promote xrun_xxxxxxxxxxxxxxxx --variant bravo --yes
-  gamealgo experiment run cancel xrun_xxxxxxxxxxxxxxxx --yes
-  gamealgo experiment run traffic xrun_xxxxxxxxxxxxxxxx bravo --weight 0 --status paused --yes
+  gamealgo experiment run report xrun_xxxxxxxxxxxxxxxx --round 1
+  gamealgo experiment run promote xrun_xxxxxxxxxxxxxxxx --variant bravo --message "采用胜出组" --yes
+  gamealgo experiment run cancel xrun_xxxxxxxxxxxxxxxx --message "停止实验" --yes
+  gamealgo experiment run traffic xrun_xxxxxxxxxxxxxxxx bravo --weight 0 --status paused --message "暂停异常组" --yes
   gamealgo experiment override set xrun_xxxxxxxxxxxxxxxx --user user-1 --variant bravo --yes
   gamealgo experiment override list xrun_xxxxxxxxxxxxxxxx
 

package/package.json

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