@mindscraft/branch-video-agent-cli 0.4.2 → 0.4.4

package/README.md

@@ -31,9 +31,9 @@ branch-video-agent --version
 - `AIHUB_AGENT_TOKEN`
 - `BRANCH_VIDEO_AGENT_BASE_URL`
 
-AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；CLI 不读取、不传递 `AiGatewayKey` 或 AIHub `projectKey`，上游鉴权由服务端处理。
-
-AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模型固定为 `doubao-seed-2-0-mini-260215`，输入为带 SHA-256 的公共 HTTPS 图片/视频 URL、一个 candidate、可选 reference、prompt 与 criteria；输出为 `media_acceptance_review.v1`。该能力只判断可见画面，不声称分析视频音轨。`kimi-k3` 和 `MiniMax-M3` 在真实 payload Canary 通过前不可调用。
+AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；CLI 不读取、不传递 `AiGatewayKey` 或 AIHub `projectKey`，上游鉴权由服务端处理。
+
+AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模型固定为 `doubao-seed-2-0-mini-260215`，输入为带 SHA-256 的公共 HTTPS 图片/视频 URL、一个 candidate、可选 reference、prompt 与 criteria；输出为 `media_acceptance_review.v1`。该能力只判断可见画面，不声称分析视频音轨。`kimi-k3` 和 `MiniMax-M3` 在真实 payload Canary 通过前不可调用。
 
 最小调用示例：
 
@@ -44,55 +44,63 @@ AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模
   "page": 1,
   "limit": 20
 }
-'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- project list
-```
-
-## BV V3 全分支可播放性测试
-
-`playtest run` 从 `0.4.0` 起提供，使用 Playwright Chromium 驱动真实播放器。命令只读草稿或已发布版本，不会保存测试副本或自动发布；运行前仍应先通过 V3 静态 self-test。
-
-```powershell
-@'
-{
-  "source": { "kind": "draft", "projectId": "project-id" },
-  "contractPath": "project.playtest.json",
-  "reportDir": "playtest-results",
-  "concurrency": 2,
-  "limits": {
-    "scenarioTimeoutMs": 60000,
-    "maxStepsPerScenario": 100,
-    "maxScenarios": 500,
-    "maxNodeVisits": 3
-  }
-}
-'@ | branch-video-agent playtest run
-```
-
-发布版把 `source` 改为 `{ "kind": "published", "projectId": "...", "version": 3, "playUrl": "<发布接口返回值>" }`。CLI 会先读回精确版本并比较规范化内容摘要，再直接使用 `playUrl`；漂移返回 `PUBLISHED_SCRIPT_MISMATCH`。该 SHA-256 摘要只由 sidecar 绑定、发布读回比较和报告追踪消费，不是身份认证、数字签名或 HMAC。
-
-sidecar 使用 `branch-video-playtest/1`，Web 结果必须提供 iframe 内的真实操作，不接受测试侧消息注入：
-
-```json
-{
-  "schemaVersion": "branch-video-playtest/1",
-  "scriptFingerprint": "sha256:...",
-  "webResults": [{
-    "nodeId": "web_quiz",
-    "routeValue": "success",
-    "rawMessage": { "eventName": "ActivityData", "value": "1" },
-    "steps": [{
-      "action": "click",
-      "locator": { "by": "role", "role": "button", "name": "正确答案" }
-    }]
-  }]
-}
-```
-
-支持 `click`、`fill`、`selectOption`、`check`、`press`、`dragTo`、`setInputFiles` 和 `waitFor`。只要输入中有合法 `reportDir`，静态门禁、契约、版本漂移和浏览器启动等前置失败也会输出 `branch-video-playtest-report.json`、`junit.xml`；失败场景另存截图、trace、视频和浏览器日志。若 Chromium 缺失，执行 `npx playwright install chromium`。
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- project list
+```
+
+## BV V3 全分支可播放性测试
+
+`playtest run` 从 `0.4.0` 起提供，使用 Playwright Chromium 驱动真实播放器。命令只读草稿或已发布版本，不会保存测试副本或自动发布；运行前仍应先通过 V3 静态 self-test。
+
+场景规划保留较长路线，删除其完整前缀场景；沿途动作、条件、状态效果和检查仍随长路线执行。`maxScenarios` 限制去重后的场景数；无法在步骤、访问次数或搜索预算内到达的边仍会使规划失败。
+
+搜索展开上限的数值不变；可安全去重的相同状态不重复计入，其他状态沿原搜索计数。
+
+```powershell
+@'
+{
+  "source": { "kind": "draft", "projectId": "project-id" },
+  "contractPath": "project.playtest.json",
+  "reportDir": "playtest-results",
+  "concurrency": 2,
+  "limits": {
+    "scenarioTimeoutMs": 60000,
+    "maxStepsPerScenario": 100,
+    "maxScenarios": 500,
+    "maxNodeVisits": 3
+  }
+}
+'@ | branch-video-agent playtest run
+```
+
+发布版把 `source` 改为 `{ "kind": "published", "projectId": "...", "version": 3, "playUrl": "<发布接口返回值>" }`。CLI 会先读回精确版本并比较规范化内容摘要，再直接使用 `playUrl`；漂移返回 `PUBLISHED_SCRIPT_MISMATCH`。该 SHA-256 摘要只由 sidecar 绑定、发布读回比较和报告追踪消费，不是身份认证、数字签名或 HMAC。
+
+sidecar 使用 `branch-video-playtest/1`，Web 结果必须提供 iframe 内的真实操作，不接受测试侧消息注入：
+
+```json
+{
+  "schemaVersion": "branch-video-playtest/1",
+  "scriptFingerprint": "sha256:...",
+  "webResults": [{
+    "nodeId": "web_quiz",
+    "routeValue": "success",
+    "rawMessage": { "eventName": "ActivityData", "value": "1" },
+    "steps": [{
+      "action": "click",
+      "locator": { "by": "role", "role": "button", "name": "正确答案" }
+    }]
+  }]
+}
+```
+
+支持 `click`、`fill`、`selectOption`、`check`、`press`、`dragTo`、`setInputFiles` 和 `waitFor`。只要输入中有合法 `reportDir`，静态门禁、契约、版本漂移和浏览器启动等前置失败也会输出 `branch-video-playtest-report.json`、`junit.xml`；失败场景另存截图、trace、视频和浏览器日志。若 Chromium 缺失，执行 `npx playwright install chromium`。
+
+CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
 
-CI 顺序应固定为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 读回 → 发布版 `playtest run`。`playtest run` 自身始终只读，不承担发布。
+从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
 
-AIHub 导入公共库示例：
+从 `0.4.4` 起，runner 在现有超时内等待“进入游戏”或“开始体验”入口；已开始播放时直接继续，后续节点和路由断言保持不变。
+
+AIHub 导入公共库示例：
 
 ```powershell
 @'

package/dist/playtest/runner.d.ts

@@ -1,3 +1,4 @@
+import { type Frame } from 'playwright';
 import type { PlaytestContract, PlaytestLimits, PlaytestScenario, PlaytestScenarioResult } from './types.js';
 type ScriptRecord = Record<string, any>;
 interface RunnerOptions {
@@ -14,6 +15,7 @@ interface RunnerOptions {
         height: number;
     };
 }
+export declare function startPlayback(frame: Frame, entryNodeId: string, entryNodeType: string, timeout: number): Promise<void>;
 export declare function runPlaytestScenarios(options: RunnerOptions): Promise<PlaytestScenarioResult[]>;
 export declare function createDraftPlayerUrl(baseUrl: string): {
     playerUrl: string;

package/dist/playtest/runner.js

@@ -111,12 +111,24 @@ async function waitForNode(frame, nodeId, timeout) {
         throw new PlaytestError('ROUTE_TARGET_MISMATCH', `Expected node ${nodeId}, reached ${actual || 'none'}`, { expected: nodeId, actual });
     }
 }
-async function startPlayback(frame, entryNodeId, entryNodeType, timeout) {
-    const startButton = frame.getByRole('button', { name: '开始体验' });
-    if (await startButton.isVisible().catch(() => false))
-        await startButton.click();
-    await frame.locator('[data-bv-node-id]').first().waitFor({ state: 'visible', timeout });
-    const current = await frame.locator('[data-bv-node-id]').first().getAttribute('data-bv-node-id');
+export async function startPlayback(frame, entryNodeId, entryNodeType, timeout) {
+    const deadline = Date.now() + timeout;
+    const remaining = () => {
+        const value = deadline - Date.now();
+        if (value <= 0)
+            throw new PlaytestError('SCENARIO_TIMEOUT', 'Scenario timeout elapsed before entry playback completed');
+        return value;
+    };
+    const entryNode = frame.locator('[data-bv-node-id]').first();
+    if (!(await entryNode.isVisible().catch(() => false))) {
+        const startButton = frame.getByRole('button', { name: /^(开始体验|进入游戏)$/ }).first();
+        await startButton.or(entryNode).filter({ visible: true }).first().waitFor({ state: 'visible', timeout: remaining() });
+        if (!(await entryNode.isVisible().catch(() => false)) && await startButton.isVisible().catch(() => false)) {
+            await startButton.click({ timeout: remaining() });
+        }
+    }
+    await entryNode.waitFor({ state: 'visible', timeout: remaining() });
+    const current = await entryNode.getAttribute('data-bv-node-id');
     if (current !== entryNodeId) {
         const observed = await readObservedMessages(frame);
         const sawEntry = observed.some((message) => JSON.stringify(message.data).includes(entryNodeId));
@@ -480,6 +492,7 @@ async function runScenario(browser, scenario, options) {
         }));
     }
     let timeoutHandle;
+    const scenarioDeadline = Date.now() + options.limits.scenarioTimeoutMs;
     const scenarioTimeout = new Promise((_, reject) => {
         timeoutHandle = globalThis.setTimeout(() => reject(new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`)), options.limits.scenarioTimeoutMs);
     });
@@ -490,7 +503,10 @@ async function runScenario(browser, scenario, options) {
                 const playerFrame = await waitForPlayerFrame(page, options.playerUrl, options.limits.scenarioTimeoutMs);
                 await assertPlayerProtocol(playerFrame, options.limits.scenarioTimeoutMs);
                 const entryNodeId = String(options.script.graph?.entryNodeId || '');
-                await startPlayback(playerFrame, entryNodeId, String(getNode(options.script, entryNodeId).type || ''), options.limits.scenarioTimeoutMs);
+                const entryTimeout = scenarioDeadline - Date.now();
+                if (entryTimeout <= 0)
+                    throw new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`);
+                await startPlayback(playerFrame, entryNodeId, String(getNode(options.script, entryNodeId).type || ''), entryTimeout);
                 playerReady = true;
                 await assertNodeMedia(playerFrame, getNode(options.script, entryNodeId));
                 visitedNodes.push(String(options.script.graph?.entryNodeId || ''));

package/dist/playtest/scenarios.d.ts

@@ -1,2 +1,3 @@
 import type { PlaytestLimits, PlaytestScenario } from './types.js';
+export declare function removePrefixScenarios(scenarios: PlaytestScenario[]): PlaytestScenario[];
 export declare function buildPlaytestScenarios(script: unknown, limits: PlaytestLimits, nodeVisitLimits?: Record<string, number>): PlaytestScenario[];

package/dist/playtest/scenarios.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from 'node:util';
 import { PlaytestError } from './errors.js';
 import { getReachablePlaytestGraph } from './graph.js';
 function compare(actual, op, expected) {
@@ -64,7 +65,7 @@ function applyEffects(state, edge, targetNode) {
     }
     return { variables, inventory };
 }
-function findPathToEdge(entryNodeId, edges, targetEdgeId, limits, nodeVisitLimits, script) {
+function findPathToEdge(entryNodeId, edges, targetEdgeId, limits, nodeVisitLimits, script, future) {
     const definitions = script?.resources?.variables || {};
     const variables = Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [name, definition?.default ?? 0]));
     const initial = {
@@ -76,11 +77,31 @@ function findPathToEdge(entryNodeId, edges, targetEdgeId, limits, nodeVisitLimit
     };
     const entryEffects = applyEffects(initial, { variableActions: [], inventoryActions: [] }, script?.graph?.nodes?.[entryNodeId]);
     const queue = [{ ...initial, ...entryEffects }];
+    const seen = new Set();
+    let head = 0;
     let examined = 0;
-    while (queue.length) {
-        const state = queue.shift();
+    while (head < queue.length) {
+        const state = queue[head];
+        queue[head++] = undefined;
         if (state.edges.length >= limits.maxStepsPerScenario)
             continue;
+        const records = [state.visits, state.variables, state.inventory.items, state.inventory.cards];
+        // Non-finite or non-scalar values keep the original search; JSON keys would conflate them.
+        const canDeduplicate = records.every((record) => Object.values(record).every((value) => (typeof value === 'string' || typeof value === 'boolean'
+            || (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)))));
+        if (canDeduplicate) {
+            const relevant = future.get(state.nodeId);
+            // Past-only visits and unread variables cannot change any continuation.
+            const projected = [
+                Object.fromEntries(Object.entries(state.visits).filter(([name]) => relevant.nodes.has(name))),
+                Object.fromEntries(Object.entries(state.variables).filter(([name]) => relevant.variables.has(name))),
+                state.inventory.items, state.inventory.cards,
+            ];
+            const key = JSON.stringify([state.nodeId, state.edges.length, ...projected.map((record) => (Object.keys(record).sort().map((name) => [name, record[name]])))]);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
         examined += 1;
         if (examined > Math.max(10000, limits.maxScenarios * limits.maxStepsPerScenario * 20))
             break;
@@ -100,18 +121,38 @@ function findPathToEdge(entryNodeId, edges, targetEdgeId, limits, nodeVisitLimit
     }
     return null;
 }
+export function removePrefixScenarios(scenarios) {
+    // ponytail: pairwise scan; index prefixes if scenario planning becomes a bottleneck.
+    return scenarios.filter((scenario) => !scenarios.some((longer) => (longer.edges.length > scenario.edges.length
+        && scenario.edges.every((edge, index) => isDeepStrictEqual(edge, longer.edges[index])))));
+}
 export function buildPlaytestScenarios(script, limits, nodeVisitLimits = {}) {
     const { entryNodeId, reachableEdges } = getReachablePlaytestGraph(script);
     if (!entryNodeId)
         throw new PlaytestError('PLAYTEST_GRAPH_INVALID', 'script graph has no entryNodeId');
-    if (reachableEdges.length + 1 > limits.maxScenarios) {
-        throw new PlaytestError('PATH_BUDGET_EXCEEDED', `Required scenario count ${reachableEdges.length + 1} exceeds maxScenarios ${limits.maxScenarios}`, {
-            reachableEdges: reachableEdges.length,
-            maxScenarios: limits.maxScenarios,
-        });
+    const future = new Map();
+    const collectVariables = (condition, names) => {
+        if (!condition || typeof condition !== 'object')
+            return;
+        if (condition.type === 'variable' || condition.variable)
+            names.add(String(condition.variable));
+        for (const child of Object.values(condition))
+            collectVariables(child, names);
+    };
+    for (const nodeId of new Set([entryNodeId, ...reachableEdges.map((edge) => edge.to)])) {
+        const nodes = new Set([nodeId]);
+        const variables = new Set();
+        // Include all structural continuations, even currently false conditions and loops.
+        for (const from of nodes) {
+            for (const edge of reachableEdges.filter((candidate) => candidate.from === from)) {
+                nodes.add(edge.to);
+                collectVariables(edge.condition, variables);
+            }
+        }
+        future.set(nodeId, { nodes, variables });
     }
     const edgeScenarios = reachableEdges.map((targetEdge, index) => {
-        const edges = findPathToEdge(entryNodeId, reachableEdges, targetEdge.id, limits, nodeVisitLimits, script);
+        const edges = findPathToEdge(entryNodeId, reachableEdges, targetEdge.id, limits, nodeVisitLimits, script, future);
         if (!edges) {
             throw new PlaytestError('PATH_BUDGET_EXCEEDED', `No path to edge ${targetEdge.id} fits the configured step/node-visit budget`, {
                 edgeId: targetEdge.id,
@@ -126,5 +167,13 @@ export function buildPlaytestScenarios(script, limits, nodeVisitLimits = {}) {
             edges,
         };
     });
-    return [{ id: 'scenario-001', targetEdgeId: `@entry:${entryNodeId}`, edges: [] }, ...edgeScenarios];
+    const scenarios = removePrefixScenarios([{ id: 'scenario-001', targetEdgeId: `@entry:${entryNodeId}`, edges: [] }, ...edgeScenarios]);
+    if (scenarios.length > limits.maxScenarios) {
+        throw new PlaytestError('PATH_BUDGET_EXCEEDED', `Required scenario count ${scenarios.length} exceeds maxScenarios ${limits.maxScenarios}`, {
+            reachableEdges: reachableEdges.length,
+            requiredScenarios: scenarios.length,
+            maxScenarios: limits.maxScenarios,
+        });
+    }
+    return scenarios;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {
@@ -15,12 +15,12 @@
     "dist",
     "README.md"
   ],
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "playwright": "^1.57.0"
-  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "playwright": "^1.57.0"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"