gamealgo-cli 0.1.4 → 0.1.6

package/README.md

@@ -1,144 +1,72 @@
 # GameAlgo Client
 
-GameAlgo Client 是面向游戏接入方的公开客户端仓库，包含 iOS SDK、Android SDK、REST helper、TapTap Maker / Lua SDK、CLI 和接入文档。
+GameAlgo Client 是公开客户端仓库，包含 iOS SDK、Android SDK、REST helper、TapTap Maker / Lua SDK、CLI 和协议定义。
 
-## 如果你是 AI Agent，请从这里开始
+产品能力、接入流程、埋点、实验、报表与优化方法由 GameAlgo Server 在线文档统一维护，不在本仓库保留副本。
 
-你的目标不是把 README 转发给开发者，而是直接帮助当前游戏完成 GameAlgo 接入、验证和后续报表/实验配置。
+## AI Agent 从这里开始
 
-默认目标是 Activated 接入，而不是只把 SDK 代码接进工程。
+不要把 README 原样转发给开发者。先安装最新 CLI，再从目标环境读取当前文档并完成接入。
 
-| 状态 | 含义 | 能否声称接入完成 |
+| 环境 | Admin host | SDK / REST API |
 | --- | --- | --- |
-| Activated | 已使用真实 `ga_live_*`，能拉配置，并能通过事件统计看到测试事件 | 可以 |
-| Scaffolded | SDK 代码已接入，但没有真实 `ga_live_*`，运行时仍是占位或 no-op | 不可以 |
-
-如果当前仓库没有真实 `ga_live_*`，不要留下 `ga_live_xxx`、`TODO_GAME_KEY`、`no-op key` 之类占位后声称完成。你必须把获取真实 Client Game Key 当作阻塞步骤。
-
-开发者通常只需要提供游戏维度的 Game Admin Key，格式为 `ga_admin_*`。拿到 Admin Key 后，你必须用 GameAlgo CLI 自动创建或读取 Client Game Key，并把真实 `ga_live_*` 写入合适的位置。
-
-先向开发者询问这几项：
-
-- 使用国内环境还是海外环境
-- Game Admin Key，格式 `ga_admin_*`。如果用户已经提供真实 `ga_live_*`，可以跳过创建 key，但仍要验证
-- 游戏运行环境：iOS / Android / Web / Backend / TapTap Maker / TapTap 小游戏
-- 本次目标：只接基础事件，还是同时接实验、配置、报表和自动化实验
-
-然后按下面流程执行：
-
-| 环境 | Admin host |
-| --- | --- |
-| 国内 | `https://game-algo-admin.dictapis.cn` |
-| 海外 | `https://dirichlet.ai/algo_admin` |
+| 国内 | `https://game-algo-admin.dictapis.cn` | `https://game-algo-sdk.dictapis.cn` |
+| 海外 | `https://dirichlet.ai/algo_admin` | `https://dirichlet.ai/algo_sdk` |
 
 ```bash
 npm install -g gamealgo-cli@latest
+gamealgo --version
 gamealgo docs agent-onboarding --host <admin-host>
+```
+
+开发者通常只需要提供游戏维度的 Game Admin Key，格式为 `ga_admin_*`。在游戏项目根目录登录后，AI Agent 应通过 CLI 创建或读取运行时使用的 `ga_live_*`，完成 SDK 接入、事件验证、Report Pack 和实验配置。
+
+```bash
 gamealgo login --host <admin-host> --admin-key <ga_admin_xxx>
 gamealgo key list --json
 gamealgo key create --name <runtime-name> --json
 gamealgo key reveal --name <runtime-name> --json
 ```
 
-安装和更新 CLI 都使用 `npm install -g gamealgo-cli@latest`，不需要拉取 GameAlgo Client 仓库。请在每个游戏项目根目录执行 `gamealgo login`，凭据保存在项目的 `.gamealgo/cli.json`，不同游戏互不覆盖。`gamealgo docs` 从当前 Admin Host 获取最新 AI 文档；登录前显式传 `--host`，登录后 CLI 会使用已保存的 Host。需要网页阅读时使用 `gamealgo docs --open`。
-
-如果已有可用 Client Game Key，就复用或 reveal；如果没有，就创建。Client Game Key 格式为 `ga_live_*`，用于游戏运行时拉配置、拉配置文件、上报事件。
-
-如果用户暂时不能提供 `ga_admin_*`，你可以继续完成 Scaffolded 状态的代码接入，但最终回复必须明确写出：
-
-- 当前未激活，因为缺少真实 `ga_live_*`
-- 不能验证配置拉取和事件上报
-- 下一步需要用户提供 `ga_admin_*` 或真实 `ga_live_*`
-
-继续阅读并执行：
-
-1. [AI 接入流程](./docs/agent-onboarding.md)
-2. [客户端接入指南](./docs/integration-guide.md)
-3. [实验接入版本与最低版本](./docs/experiment-integration-versions.md)
-4. [AI Agent 埋点接入手册](./docs/ai-tracking-manual.md)
-5. [不同类型游戏埋点建议](./docs/tracking-recommendations.md)
-6. [Report Pack 配置](./docs/report-packs.md)
-7. [Agent CLI 命令参考](./docs/agent-cli.md)
-8. [AI LTV 优化 Playbook](./docs/ai-ltv-optimization-playbook.md)
-
-### 不要这样做
-
-- 不要向开发者索要 `ga_live_*`，除非开发者明确说要手工维护运行时 key。
-- 不要把 `ga_live_xxx` 示例值、占位 key 或 no-op key 提交到游戏工程后声称接入完成。
-- 不要把 `ga_admin_*` 写进游戏客户端、小游戏客户端脚本、公开配置或日志。
-- 不要把 README 原样甩给开发者后停止接入。
-- 不要让 GameAlgo 网络请求阻塞游戏主流程。
-- TapTap Maker / TapTap 小游戏使用 Lua SDK 客户端直连，必须配置真实 `ga_live_*`，但不能写入 `ga_admin_*`。
-- 不要默认使用 `USD`；国内游戏、TapTap Maker / TapTap 小游戏的广告和付费事件默认使用 `CNY`。
-
-## 如果你是开发者
+凭据保存在当前游戏项目的 `.gamealgo/cli.json`，不同游戏互不覆盖。需要其他主题时使用：
 
-你需要做的事很少：
-
-1. 登录 GameAlgo Admin 控制台。
-2. 创建或选择你的游戏。
-3. 在游戏的 Keys 页面创建 Game Admin Key。
-4. 把使用环境和 Game Admin Key 提供给 AI Agent。
-5. 审核 AI Agent 对游戏工程、实验配置和 Report Pack 的改动。
-
-开发者详细说明见 [开发者快速开始](./docs/developer-quickstart.md)。
+```bash
+gamealgo docs --host <admin-host>
+gamealgo docs integration-guide --host <admin-host>
+gamealgo docs ai-tracking-manual --host <admin-host>
+gamealgo docs report-packs --host <admin-host>
+gamealgo docs experiment-integration-versions --host <admin-host>
+gamealgo docs agent-cli --host <admin-host>
+```
 
-## 两类 key
+## SDK 入口
 
-| Key | 示例 | 用途 | 放在哪里 |
-| --- | --- | --- | --- |
-| Game Admin Key | `ga_admin_*` | CLI / AI Agent / CI 管理实验、脚本、配置、Report Pack，拉取报表和事件统计 | 开发机器、CI Secret、Agent Secret |
-| Client Game Key | `ga_live_*` | 游戏运行时拉取配置、拉取配置文件、上报事件 | 游戏客户端 SDK 配置 |
+- [iOS SDK](./ios/README.md)
+- [Android SDK](./android/README.md)
+- [REST helper](./rest-api/README.md)
+- [TapTap Maker / Lua SDK](./lua/README.md)
+- [CLI](./cli/README.md)
+- [Protocol OpenAPI](./protocol/openapi.yaml)
 
-常规流程是：开发者只手工创建 Game Admin Key；AI Agent 用 CLI 创建、读取和维护 Client Game Key。
+海外 SDK 地址包含 `/algo_sdk` 路径前缀，必须完整保留。客户端只能配置 `ga_live_*`；`ga_admin_*` 只允许用于开发机器、AI Agent 或 CI。
 
-## 目录结构
+## 仓库结构
 
 ```text
 ios/        iOS Swift Package SDK
 android/    Android Java SDK core
 rest-api/   REST API helper 和示例
-lua/        TapTap Maker / TapTap 小游戏 Lua SDK 和客户端 HTTP 传输
-cli/        游戏开发 Agent 使用的自动化 CLI
-examples/   可运行接入示例
-docs/       接入、埋点、报表和优化文档
+lua/        TapTap Maker / Lua SDK
+cli/        GameAlgo CLI
+protocol/   客户端协议定义
+examples/   接入示例
 ```
 
-## 平台地址
-
-环境地址：
-
-| 环境 | SDK / REST API | Admin / CLI |
-| --- | --- | --- |
-| 国内 | `https://game-algo-sdk.dictapis.cn` | `https://game-algo-admin.dictapis.cn` |
-| 海外 | `https://dirichlet.ai/algo_sdk` | `https://dirichlet.ai/algo_admin` |
-
-客户端 SDK 只配置 SDK / REST API 地址。Admin / CLI 地址只给开发者、AI Agent 和 CI 使用。
-
-## SDK 接入入口
+## 本地验证
 
-- iOS：见 [iOS SDK](./ios/README.md)，也可以通过 SwiftPM 引入本仓库。
-- Android：见 [Android SDK](./android/README.md)。
-- REST / Web / Backend：见 [REST helper](./rest-api/README.md) 和 [REST API 文档](./docs/rest-api-v1.md)。
-- TapTap Maker / TapTap 小游戏：见 [Lua SDK](./lua/README.md)。
-
-所有运行时请求都通过 `X-GameAlgo-Key: ga_live_xxx` 识别游戏，不需要游戏自己传可信 `gameId`。
-
-核心原则：SDK 后台拉取配置并写入本地快照；配置未就绪、网络失败或脚本执行失败时，游戏必须走本地默认逻辑。
-
-## 接入后的验收
-
-AI Agent 接入后应该至少完成这些验证：
-
-- 客户端配置里使用真实 `ga_live_*`，不是占位值。
-- `ga_admin_*` 没有出现在客户端代码、Info.plist、资源文件、脚本包、日志或 git diff 中。
-- `/v1/config` 能成功返回当前游戏配置，或 SDK 日志显示 config fetched / config ready。
-- `session_end` 和核心玩法事件能上传成功。
-- 如果游戏使用 Adjust 等归因 SDK，归因 callback 后能回传归因；如果需要投放 ROI 报表，Adjust API Token / App Token 已在 CLI/Admin 配置并完成同步验证。
-- `gamealgo events count` 能查到测试事件。
-- 配置未就绪时，游戏仍然能走本地默认逻辑。
-- Report Pack 可以 `validate` 和 `preview`。
-
-如果以上验证没有完成，交付说明里必须标记为 Scaffolded 或部分完成，不能写“已完成接入”。
+```bash
+npm install
+npm run check
+```
 
-完整验收和排查流程见 [AI 接入流程](./docs/agent-onboarding.md)。
+平台 SDK README 只描述与当前代码版本绑定的安装方式、公开 API 和运行时约束。业务流程与平台规则以 `gamealgo docs` 返回的在线文档为准。

package/cli/README.md

@@ -159,35 +159,47 @@ gamealgo experiment strategy publish strategy.yaml --yes
 
 每次发布 Strategy 都必须显式填写 `requiredIntegrationVersion`。填写 `0` 表示该 Strategy 不依赖任何客户端实验能力版本；填写大于 `0` 的值时，必须引用已经通过 `integration-version create` 创建、且客户端确实已经实现的版本。Run 会继承 Strategy 的最低版本，不需要重复配置。
 
-版本升级判断、旧客户端行为和托管实验覆盖率门槛的完整说明见 [实验接入版本](../docs/experiment-integration-versions.md)。
+版本升级判断、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
     config:
       firstAdLevel: 4
       interval: 30
+    script:
+      versionId: sv_xxxxxxxxxxxxxxxx
   - variantId: slower_ads
     weight: 1
     config:
       firstAdLevel: 5
       interval: 45
+    script:
+      versionId: sv_xxxxxxxxxxxxxxxx
 ```
 
 ```bash
 gamealgo experiment run create ad_frequency run.yaml --yes
 ```
 
-如果要把当前默认参数也放进实验，需要显式配置 `variantId: default`；否则默认参数不参与流量。所有有流量的实验组数量必须至少为 2。
+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。
 
 查看、评估和完成实验闭环：
 
@@ -201,12 +213,44 @@ 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` 必须显式选择：
+
+- `ltv_proxy@1`：优化标准化累计用户价值。
+- `active_days@1`：优化用户活跃天数，口径为 `1 + D1 回访率 + ... + Dk 回访率`。D0 记为 1 个活跃日，每个 Dx 只使用已经成熟到该天的实验进入用户，未回访用户按 0 计入。
+
+实验结束前可以显式修改追踪目标。修改不会重置实验分流、时间窗口、参数或脚本；平台会把当前评估标记为过期，并在下一轮评估中使用新目标重算已有实验窗口。托管实验一旦已有完成的轮次就不能修改目标，因为前后轮次不能使用不同的优选依据。
+
+```bash
+gamealgo experiment run objective xrun_xxxxxxxxxxxxxxxx \
+  --objective active_days@1 \
+  --message "改为关注用户活跃天数" \
+  --yes
+```
+
+已生成的正式轮次报告保留生成时的旧目标，不会被改写。
 
 ```bash
 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
@@ -221,28 +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 }
-  - variantId: bravo
-    config: { firstAdLevel: 5, interval: 30 }
-  - variantId: charlie
-    config: { firstAdLevel: 4, interval: 45 }
 ```
 
 `minCoverage` 表示指定平台最近 24 小时内，实验接入版本达到 Strategy `requiredIntegrationVersion` 的去重用户占比；`minUsers` 表示同一窗口内的非 Debug 去重用户数。两项可单独配置，同时配置时必须同时满足。等待期间 Strategy 继续下发默认参数，满足门槛后平台才生成首轮时间窗并开始分流。手动实验不支持 `startCondition`，托管实验不配置时仍会立即启动。`experiment run show` 返回 `startConditionSnapshot`，可查看当前用户数、覆盖率和最近检查时间。
@@ -259,6 +288,8 @@ LTV Proxy (Dk) = STANDARDIZED_DAY_VALUE_D0 + ... + STANDARDIZED_DAY_VALUE_Dk
 
 所有实验组使用同一个 `k`。平台按参考周期固定 `k 上限 = min(14, minWindowDays - 3)`，再选择不超过上限、且每个参与组都至少有 10 个成熟进入用户的最大连续 Dx。延长只增加样本，不改变评分口径。平台用本轮真实用户和线上 MurmurHash 分流规则模拟大量随机 seed，估计当前游戏用户结构下的自然组间波动，并校正多实验组与逐日重复评估。实际收入、实际 ARPU、新用户留存和新用户 LTV 只作为诊断指标，不参与主指标计算。
 
+`active_days@1` 使用相同的共同成熟 `k`、随机化检验和正式胜出规则，收入和 LTV 指标仍作为诊断数据展示，但不参与主指标排序。
+
 所有会修改线上状态的实验命令都必须显式传 `--yes`。
 
 ## 脚本和配置

package/dist/gamealgo.js

@@ -387,18 +387,37 @@ 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))
             throw new Error("experiment run requires displayName");
-        if (optionalString(body.objectiveTemplate) !== "ltv_proxy@1") {
-            throw new Error("experiment run requires objectiveTemplate: ltv_proxy@1");
+        const objectiveTemplate = optionalString(body.objectiveTemplate);
+        if (!objectiveTemplate || !["ltv_proxy@1", "active_days@1"].includes(objectiveTemplate)) {
+            throw new Error("experiment run requires objectiveTemplate: ltv_proxy@1 or active_days@1");
         }
         if (!optionalString(body.baselineVariantId)) {
             throw new Error("experiment run requires explicit baselineVariantId");
         }
-        const runType = optionalString(body.type) || "manual";
+        validateExperimentRunVariantScripts(body.variants);
+        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");
         }
@@ -412,7 +431,13 @@ async function handleExperimentRun(client, args, global) {
                 throw new Error("managed experiment run requires maxWindowDays between minWindowDays and 60");
             }
         }
-        await printResult(await client.createExperimentV2Run(strategyKey, body), global);
+        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)
+            printExperimentRunVariantScripts(result);
         return;
     }
     if (sub === "show" || sub === "get") {
@@ -499,6 +524,21 @@ async function handleExperimentRun(client, args, global) {
         await printResult({ runId, report }, global);
         return;
     }
+    if (sub === "objective") {
+        const flags = parseFlags(args);
+        const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
+        const objectiveTemplate = optionalString(flags.objective || flags["objective-template"]);
+        if (!runId || !objectiveTemplate) {
+            throw new Error("usage: gamealgo experiment run objective <runId> --objective <ltv_proxy@1|active_days@1> --message <reason> --yes");
+        }
+        if (!["ltv_proxy@1", "active_days@1"].includes(objectiveTemplate)) {
+            throw new Error("experiment objective must be ltv_proxy@1 or active_days@1");
+        }
+        const message = requiredMessage(flags, "experiment run objective");
+        await requireYes(flags, global, "experiment run objective");
+        await printResult(await client.updateExperimentV2RunObjective(runId, objectiveTemplate, message), global);
+        return;
+    }
     if (sub === "promote") {
         const flags = parseFlags(args);
         const runId = optionalString(flags.run || flags["run-id"] || flags.id) || optionalString(args.shift());
@@ -520,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|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);
@@ -1082,6 +1106,12 @@ class GameAlgoAdminClient {
     async cancelExperimentV2Run(runId, message) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/cancel`, { message });
     }
+    async updateExperimentV2RunObjective(runId, objectiveTemplate, message) {
+        return await this.patch(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/objective`, {
+            objectiveTemplate,
+            message,
+        });
+    }
     async listExperimentV2Overrides(runId) {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/experiment-runs-v2/${encodeURIComponent(runId)}/overrides`);
     }
@@ -1091,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`);
     }
@@ -1489,6 +1516,35 @@ function latestScriptVersionNames(value) {
 function objectValue(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function validateExperimentRunVariantScripts(value) {
+    if (!Array.isArray(value))
+        throw new Error("experiment run requires variants array");
+    for (let index = 0; index < value.length; index += 1) {
+        const variant = objectValue(value[index]);
+        if (!variant)
+            throw new Error(`variants[${index}] must be an object`);
+        if (!Object.prototype.hasOwnProperty.call(variant, "script"))
+            continue;
+        const script = objectValue(variant.script);
+        if (!script || !optionalString(script.versionId)) {
+            throw new Error(`variants[${index}].script requires versionId; omit script for a config-only variant`);
+        }
+    }
+}
+function printExperimentRunVariantScripts(value) {
+    const run = objectValue(objectValue(value)?.run);
+    if (!run || !Array.isArray(run.variants))
+        return;
+    console.log("\nVariant execution:");
+    for (const item of run.variants) {
+        const variant = objectValue(item);
+        if (!variant)
+            continue;
+        const variantId = optionalString(variant.variantId) ?? "(unknown)";
+        const versionId = optionalString(objectValue(variant.script)?.versionId);
+        console.log(`  ${variantId}: ${versionId ? `script ${versionId}` : "config-only"}`);
+    }
+}
 async function readJsonFile(filePath) {
     return JSON.parse(await readFile(filePath, "utf8"));
 }
@@ -1675,14 +1731,14 @@ 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
   gamealgo experiment run report xrun_xxxxxxxxxxxxxxxx --round 1
+  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.4",
+  "version": "0.1.6",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "type": "module",
   "bin": {