gamealgo-cli 0.1.5 → 0.1.6

package/cli/README.md

@@ -161,15 +161,17 @@ gamealgo experiment strategy publish strategy.yaml --yes
 
 版本升级判断、Strategy 最低版本和托管实验覆盖率门槛的完整说明可通过 `gamealgo docs experiment-integration-versions` 获取。
 
-创建手动实验 Run：
+默认创建托管实验 Run。除非开发者具备专业的实验设计和统计判断能力，并且会持续人工管理实验，否则不要使用手动实验：
 
 ```yaml
 # run.yaml
-displayName: 广告频率第一轮
-type: manual
+displayName: 广告频率托管实验
 platform: ios
 objectiveTemplate: ltv_proxy@1
 baselineVariantId: control
+minWindowDays: 7
+maxWindowDays: 14
+maxVariantsPerRound: 2
 variants:
   - variantId: control
     weight: 1
@@ -191,10 +193,14 @@ variants:
 gamealgo experiment run create ad_frequency run.yaml --yes
 ```
 
+CLI 在未声明 `type` 时默认提交 `managed`。托管实验由平台管理轮次、在参考周期后判断是否需要延长，并在证据明确时完成后续轮次和推全；缺少 `minWindowDays` 或 `maxWindowDays` 会直接拒绝创建，不会静默套用周期。
+
 Run 不会继承 Strategy 的脚本。每个需要执行脚本的 variant 都必须显式配置 `script.versionId`；省略 `script` 明确表示该组是 config-only。即使多个 variant 使用同一份脚本，也要在每个 variant 上重复填写同一个不可变 `versionId`。
 
 如果要把当前默认参数也放进实验，需要显式配置 `variantId: default`。`default` 会快照 Strategy 当前默认参数，因此不能写 `config`；如果默认组需要执行脚本，也必须在 `default` 上显式写 `script.versionId`。否则默认参数不参与流量。所有有流量的实验组数量必须至少为 2。
 
+Run 创建后，用户不能修改 variant、权重或启停状态，否则同一用户可能换组，前后数据也无法按同一实验口径比较。托管实验只允许平台在轮次结束后按既定流程切换下一轮候选，用户不能干预流量。需要改变候选或分流时，先取消当前 Run，再创建新 Run。
+
 查看、评估和完成实验闭环：
 
 ```bash
@@ -207,7 +213,7 @@ gamealgo experiment run report xrun_xxxxxxxxxxxxxxxx
 gamealgo experiment run promote xrun_xxxxxxxxxxxxxxxx --variant slower_ads --message "采用低频广告组" --yes
 ```
 
-`baselineVariantId` 是本次评估的对照组，必须指向一个有流量的实验组。平台按小时更新“当前评估”；`report` 返回已生成的正式报告。`promote` 会把指定 variant 写回 Strategy 默认参数，并结束当前 Run。取消实验用：
+`baselineVariantId` 是本次评估的对照组，必须指向一个有流量的实验组。平台按小时更新“当前评估”；`report` 返回已生成的正式报告。`promote` 可在手动或托管 Run 仍处于运行中时提前人工推全，不要求平台已经给出正式 winner。它会立即结束 Run，把指定 variant 的 `config` / `script` 写回 Strategy 默认参数，并淘汰其他实验组；必须通过 `--message` 记录人工推全原因。取消实验用：
 
 `objectiveTemplate` 必须显式选择：
 
@@ -229,6 +235,22 @@ gamealgo experiment run objective xrun_xxxxxxxxxxxxxxxx \
 gamealgo experiment run cancel xrun_xxxxxxxxxxxxxxxx --message "实验停止" --yes
 ```
 
+### 高级用法：手动实验
+
+手动实验不会自动延长、形成最终结论或推全。只有开发者能够自行决定采集周期、判断统计证据并负责完成实验闭环时才使用。必须通过以下任一方式显式开启：
+
+```bash
+gamealgo experiment run create ad_frequency manual-run.yaml --manual --yes
+```
+
+或者在 Run 文件中明确填写：
+
+```yaml
+type: manual
+```
+
+手动 Run 不配置 `minWindowDays`、`maxWindowDays` 和 `startCondition`。其分流同样在整个 Run 内固定；需要调整分流时，取消当前 Run 后重新创建。
+
 回滚默认参数会创建一个新的参数版本，不会改写历史版本：
 
 ```bash
@@ -243,31 +265,13 @@ gamealgo experiment override list xrun_xxxxxxxxxxxxxxxx
 gamealgo experiment override delete xrun_xxxxxxxxxxxxxxxx --user user-1 --yes
 ```
 
-托管实验也是创建 `type: managed` 的 Run，平台会按轮次自动调整流量并最终推全胜出组：
+托管实验可以使用 `startCondition` 等待接入版本覆盖率和用户数达到门槛：
 
 ```yaml
-displayName: 广告频率托管实验
-type: managed
-platform: ios
-objectiveTemplate: ltv_proxy@1
-baselineVariantId: alpha
-minWindowDays: 7
-maxWindowDays: 14
-maxVariantsPerRound: 3
 # 可选：仅托管实验支持。最近 24 小时同时满足两个门槛后才开始首轮。
 startCondition:
   minCoverage: 0.8
   minUsers: 100
-variants:
-  - variantId: alpha
-    config: { firstAdLevel: 4, interval: 30 }
-    script: { versionId: sv_xxxxxxxxxxxxxxxx }
-  - variantId: bravo
-    config: { firstAdLevel: 5, interval: 30 }
-    script: { versionId: sv_xxxxxxxxxxxxxxxx }
-  - variantId: charlie
-    config: { firstAdLevel: 4, interval: 45 }
-    script: { versionId: sv_xxxxxxxxxxxxxxxx }
 ```
 
 `minCoverage` 表示指定平台最近 24 小时内，实验接入版本达到 Strategy `requiredIntegrationVersion` 的去重用户占比；`minUsers` 表示同一窗口内的非 Debug 去重用户数。两项可单独配置，同时配置时必须同时满足。等待期间 Strategy 继续下发默认参数，满足门槛后平台才生成首轮时间窗并开始分流。手动实验不支持 `startCondition`，托管实验不配置时仍会立即启动。`experiment run show` 返回 `startConditionSnapshot`，可查看当前用户数、覆盖率和最近检查时间。

package/dist/gamealgo.js

@@ -387,7 +387,7 @@ async function handleExperimentRun(client, args, global) {
         const strategyKey = optionalString(flags.strategy || flags.key) || optionalString(args.shift());
         const filePath = optionalString(flags.file || flags.input) || optionalString(args.shift());
         if (!strategyKey || !filePath)
-            throw new Error("usage: gamealgo experiment run create <strategyKey> <run.yaml> --yes");
+            throw new Error("usage: gamealgo experiment run create <strategyKey> <run.yaml> [--manual] --yes");
         await requireYes(flags, global, "experiment run create");
         const body = await readObjectFile(filePath, "experiment run");
         if (!optionalString(body.displayName))
@@ -400,7 +400,24 @@ async function handleExperimentRun(client, args, global) {
             throw new Error("experiment run requires explicit baselineVariantId");
         }
         validateExperimentRunVariantScripts(body.variants);
-        const runType = optionalString(body.type) || "manual";
+        const fileRunType = optionalString(body.type);
+        const flagRunType = optionalString(flags.type);
+        const manualFlag = flags.manual === true;
+        if (fileRunType && fileRunType !== "managed" && fileRunType !== "manual") {
+            throw new Error("experiment run type must be managed or manual");
+        }
+        if (flagRunType && flagRunType !== "managed" && flagRunType !== "manual") {
+            throw new Error("--type must be managed or manual");
+        }
+        if (manualFlag && flagRunType && flagRunType !== "manual") {
+            throw new Error("--manual conflicts with --type managed");
+        }
+        const requestedRunType = manualFlag ? "manual" : flagRunType;
+        if (requestedRunType && fileRunType && requestedRunType !== fileRunType) {
+            throw new Error(`experiment run type conflict: file uses ${fileRunType}, CLI requests ${requestedRunType}`);
+        }
+        const runType = requestedRunType || fileRunType || "managed";
+        body.type = runType;
         if (runType !== "managed" && body.startCondition !== undefined) {
             throw new Error("experiment run startCondition is supported only when type is managed");
         }
@@ -414,6 +431,9 @@ async function handleExperimentRun(client, args, global) {
                 throw new Error("managed experiment run requires maxWindowDays between minWindowDays and 60");
             }
         }
+        else {
+            process.stderr.write("Warning: creating a manual experiment. The platform will not automatically extend, conclude, or promote it; use manual mode only when the developer will manage the experiment decision.\n");
+        }
         const result = await client.createExperimentV2Run(strategyKey, body);
         await printResult(result, global);
         if (!global.json)
@@ -540,23 +560,7 @@ async function handleExperimentRun(client, args, global) {
         await printResult(await client.cancelExperimentV2Run(runId, message), global);
         return;
     }
-    if (sub === "traffic") {
-        const flags = parseFlags(args);
-        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] --message <reason> --yes");
-        const message = requiredMessage(flags, "experiment run traffic");
-        await requireYes(flags, global, "experiment run traffic");
-        const body = { message };
-        if (flags.weight !== undefined)
-            body.weight = optionalNonNegativeInteger(flags.weight, "weight");
-        if (flags.status !== undefined)
-            body.status = optionalString(flags.status);
-        await printResult(await client.updateExperimentV2VariantTraffic(runId, variantId, body), global);
-        return;
-    }
-    throw new Error("usage: gamealgo experiment run <create|show|status|evaluate|report|objective|promote|cancel|traffic>");
+    throw new Error("usage: gamealgo experiment run <create|show|status|evaluate|report|objective|promote|cancel>");
 }
 function requiredMessage(flags, action) {
     const message = optionalString(flags.message);
@@ -1117,9 +1121,6 @@ class GameAlgoAdminClient {
     async deleteExperimentV2Override(runId, userId) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/overrides/delete`, { userId });
     }
-    async updateExperimentV2VariantTraffic(runId, variantId, body) {
-        return await this.patch(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/variants/${encodeURIComponent(variantId)}/traffic`, body);
-    }
     async listConfigFiles() {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/config-files`);
     }
@@ -1730,7 +1731,7 @@ Usage:
   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 create ad_frequency run.yaml [--manual] --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
@@ -1738,7 +1739,6 @@ Usage:
   gamealgo experiment run objective xrun_xxxxxxxxxxxxxxxx --objective active_days@1 --message "改为关注活跃天数" --yes
   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.5",
+  "version": "0.1.6",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "type": "module",
   "bin": {