claw/docs/superpowers/specs/2026-04-06-scene-skill-runtime-routing-design.md

# Scene Skill Runtime Routing Design

**Goal:** Add a minimal, extensible scene-routing layer so staged business scenes can be triggered from natural language while still executing through the existing browser-backed skill path.

**Architecture:** Introduce a registry-driven scene contract loader that reads staged `scene.json` metadata, matches user instructions to a scene, and chooses one of two dispatch modes: direct browser execution or agent-mediated browser execution. Both modes must reuse the same browser-backed skill tool path so scene skills continue to execute through browser-internal methods rather than text-only responses or local fake execution.

**Tech Stack:** Rust, serde/JSON scene metadata loading, existing `BrowserScriptSkillTool`, existing compat runtime / runtime engine / workflow executor layers, focused Rust unit tests.

---

## Problem Statement

The codebase already supports two useful but separate ideas:

1. **Zhihu special-case runtime routing**
   - `src/compat/workflow_executor.rs` detects a narrow set of Zhihu tasks and can execute them directly without relying on the model to choose tools.
   - This is stable, but not extensible for a growing set of business scenes.

2. **Browser-backed skills**
   - `src/compat/runtime.rs` loads skills and exposes `browser_script` tools through `BrowserScriptSkillTool`.
   - `src/compat/browser_script_skill_tool.rs` executes those tools by calling the browser backend with `Action::Eval`, so actual execution already happens through browser-internal methods.
   - This is extensible, but tool choice currently depends too heavily on generic agent behavior.

The staged business scenes under `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging` already provide most of the metadata needed to bridge these two ideas. We need a first integration slice that uses scene metadata to improve routing without turning every scene into a hardcoded Zhihu-style exception.

## Design Goals

- Support natural-language triggering for staged scenes.
- Preserve the current browser-backed execution contract: both scene modes must end in browser-internal execution via the existing browser tool path.
- Support both dispatch styles discussed with the user:
  - one scene that can execute without the model
  - one scene that still uses the model for orchestration
- Keep the first slice small, covering only:
  - `fault-details-report`
  - `95598-repair-city-dispatch`
- Keep the design extensible so more scene skills can be added in the same directory later without more ad hoc routing branches.
- Avoid broad refactors or a new generic workflow platform in this slice.

## Non-Goals

- Do not build a scene editor, scene UI, or registry authoring workflow.
- Do not implement a full artifact post-processing platform for all report/monitor types.
- Do not convert every staged scene into a direct Rust executor.
- Do not replace the existing Zhihu-specific runtime path in this slice.

## Source of Truth and Paths

### Staged scene source
The new staged scene source for this work is:

- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging`

The runtime integration must read scene metadata from this location for the initial slice.

### Existing runtime integration points
- `src/compat/config_adapter.rs` — current skills-dir resolution logic
- `src/compat/runtime.rs` — current skill loading and browser-script tool exposure
- `src/runtime/engine.rs` — runtime instruction building and allowed-tool shaping
- `src/compat/workflow_executor.rs` — existing direct execution routing pattern
- `src/compat/browser_script_skill_tool.rs` — browser-backed execution path for `browser_script` tools

## Scene Contract Model

Introduce a small internal scene contract model derived from `scene.json` and paired runtime policy. The loader should extract only the fields needed for the first slice:

- `id`
- `name`
- `summary`
- `tags`
- `inputs`
- `outputs`
- `skill.package`
- `skill.tool`
- `skill.artifact_type`

Add a runtime-only dispatch policy associated with each enabled scene inside the same internal registry entry used at runtime:

- `dispatch_mode`
  - `direct_browser`
  - `agent_browser`
- `expected_domain`
  - bare hostname required by the underlying browser-backed skill tool
- optional `aliases`
  - additional deterministic keywords/phrases when `id/name/summary/tags` are not enough for first-slice matching
- optional `default_args`
  - runtime-supplied tool arguments when a scene needs fixed/default values for first execution

This runtime policy may be hardcoded in Rust for the first slice, but it must be represented through one consistent scene-routing abstraction so future scenes can join the same path without rewriting the whole design. The abstraction should be a single registry entry type that combines scene metadata with runtime dispatch policy, rather than a metadata loader plus a separate ad hoc match table.

## Dispatch Modes

### 1. `direct_browser`
This mode is for scenes whose collection flow is deterministic enough to bypass the model once the scene is recognized.

**Initial scene:** `fault-details-report`

**Behavior:**
- Detect scene from natural language.
- Resolve the corresponding browser-backed skill tool.
- Execute it directly through the existing browser-backed skill path.
- Return the collected artifact result without delegating tool choice to the model.

**Important constraint:**
This is not a local fake implementation. Even in direct mode, the actual collection must still go through the existing browser-backed execution path, meaning it ultimately uses browser-internal methods through the browser backend.

### 2. `agent_browser`
This mode is for scenes that still benefit from agent orchestration, explanation, or downstream reasoning, but whose business data must still come from browser-backed execution.

**Initial scene:** `95598-repair-city-dispatch`

**Behavior:**
- Detect scene from natural language.
- Inject a strong scene execution contract into the runtime instruction.
- Treat calling the matching browser-backed skill tool first as a policy requirement for the scene.
- In slice one, enforce that policy through scene-specific instruction injection rather than a hard runtime gate.
- Allow generic browser probing only as a fallback after the scene tool fails.
- Keep final explanation/summarization in the agent path, but never let the model invent business data.

## Matching Strategy

Implement a minimal matcher that scores user instructions against enabled scenes using:

- scene `id`
- scene `name`
- scene `summary`
- scene `tags`
- optional runtime aliases for the first slice

The matcher should be intentionally simple and deterministic in this slice. Avoid semantic embedding or fuzzy retrieval infrastructure.

Expected first-slice matches:

- `fault-details-report`
  - phrases like `故障明细`, `故障明细报表`, `导出故障明细`
- `95598-repair-city-dispatch`
  - phrases like `95598抢修市指`, `市指抢修监测`, `95598抢修队列`

If no scene matches, runtime behavior must remain unchanged.

## Runtime Loading Design

### Scene registry loading
Add a small loader that reads enabled scenes from the staged scene directory. For the first slice, it is acceptable to read the concrete scene files directly instead of implementing a full generic registry parser, as long as the resulting module boundary is registry-oriented rather than one-off.

The loader should:
- resolve the staged scene root
- read the two initial `scene.json` files
- deserialize them into a small internal scene metadata struct
- pair them with dispatch policy in the same in-memory registry entry
- ignore malformed or missing scenes safely
- never fail runtime startup solely because one or both initial scene files are absent

### Skill loading alignment
The corresponding skill packages must still be loaded into runtime skill exposure so the browser-backed tools are available to the runtime.

For this slice, the staged scene source and staged skill packages should be treated as coming from the same external root:
- staged scenes under `.../skill_staging/scenes`
- staged skill packages under `.../skill_staging/skills`

The implementation must make that staged skill package root visible to runtime skill loading. If current `skills_dir` resolution cannot express that directly, the design should extend configuration/path resolution to support a staged external skills root explicitly rather than relying on implicit mirroring.

## Execution Design

### Direct browser path (`fault-details-report`)
Add a direct execution route that is scene-driven rather than Zhihu-specific.

High-level flow:
1. Runtime receives user instruction.
2. Scene matcher recognizes `fault-details-report`.
3. Runtime resolves the browser-backed tool name `fault-details-report.collect_fault_details`.
4. Runtime builds the required tool arguments, including:
   - `expected_domain` from the matched scene's runtime policy
   - any first-slice scene inputs that can be deterministically derived from the current request/context
   - any fixed/default args declared in runtime policy
5. Runtime executes that skill through the existing browser-backed mechanism.
6. Runtime returns normalized tool output as the direct route result.

Input/argument rules for the first slice:
- Direct execution is only allowed when all required tool arguments are available.
- `expected_domain` must always come from runtime scene policy, not from model inference.
- If a required scene/tool input cannot be derived from the user request or current browser context, the direct route must fail clearly instead of fabricating values.
- The first slice may keep direct-mode argument mapping intentionally narrow; unsupported requests should fall back safely rather than guessing.

Return-shape rule for the first slice:
- The direct route should return normalized serialized tool output (for example, the tool payload string or normalized JSON text), not a model-authored prose summary. This keeps direct mode deterministic and makes the browser-backed result explicit.

Implementation note:
The cleanest first slice is to add a small scene direct-execution helper in the compat runtime/workflow area that invokes the already-loaded browser-backed skill tool abstraction rather than duplicating browser request logic.

### Agent browser path (`95598-repair-city-dispatch`)
This path stays inside the agent flow.

High-level flow:
1. Runtime receives user instruction.
2. Scene matcher recognizes `95598-repair-city-dispatch`.
3. `RuntimeEngine::build_instruction` injects a scene execution contract containing:
   - the matched scene name
   - the required tool name `95598-repair-city-dispatch.collect_repair_orders`
   - explicit requirement that this is a browser workflow, not a text-only task
   - explicit requirement that business data must come from the browser-backed scene tool
   - fallback rules for generic browser probing only after tool failure
4. Agent runs and chooses the required tool.
5. Tool executes through the existing browser-backed skill path.
6. Agent may summarize the result, but cannot fabricate data.

Enforcement note for the first slice:
- The `agent_browser` guarantee is primarily an instruction-contract guarantee in slice one.
- If allowed-tool shaping can narrow the exposed tool set for a matched scene without destabilizing existing behavior, that is a valid enhancement, but it is not required for the first slice.
- The minimum guaranteed behavior for slice one is strong scene-specific prompt injection plus preservation of the rule that the model must not invent collected business data.

## Browser Execution Contract

This requirement is non-negotiable for both dispatch modes:

- scene skills must execute like the Zhihu flow in the sense that the final business action is performed through browser-internal methods
- scene skills must not devolve into text-only pseudo execution
- direct mode and agent mode both reuse the existing browser-backed skill execution path

Concretely, the final path for scene skill execution should remain compatible with:
- `BrowserScriptSkillTool`
- browser backend invocation
- browser-side `Eval` / browser action execution semantics

## Error Handling

- **Scene metadata missing or invalid:** skip that scene and continue with normal runtime behavior.
- **Scene matched but skill/tool unavailable:** do not crash; log enough context for diagnosis and fall back safely.
- **Browser surface unavailable:** disable scene browser routing for that turn and fall back to current non-scene behavior.
- **Tool execution fails in `agent_browser` mode:** allow existing fallback prompt behavior to continue, but preserve the rule that the model cannot invent collected data.
- **Tool execution fails in `direct_browser` mode:** return a concise execution failure instead of pretending collection succeeded.

## Extensibility Rules

This slice should be built so future scene additions only need:
- a new scene metadata file under the staged scene path
- a matching skill package/tool
- a dispatch-mode declaration/policy
- optional aliases if the natural-language names are not sufficiently explicit

Avoid these anti-patterns:
- per-scene `if user said X then do Y` branches scattered across runtime files
- duplicating browser execution code for each scene
- binding future scenes to Zhihu-specific assumptions

## Testing Strategy

### Scene registry tests
- load valid metadata for `fault-details-report`
- load valid metadata for `95598-repair-city-dispatch`
- ignore broken/missing scene files safely

### Matching tests
- instruction variants match `fault-details-report`
- instruction variants match `95598-repair-city-dispatch`
- unrelated instructions do not match

### Instruction-building tests
- `agent_browser` scene injects the required browser-first scene contract
- unmatched instructions do not gain scene-specific constraints
- Zhihu-specific instruction behavior remains unchanged

### Tool exposure tests
- staged skills from the moved path are loaded into runtime
- browser-backed tool names include:
  - `fault-details-report.collect_fault_details`
  - `95598-repair-city-dispatch.collect_repair_orders`

### Direct execution tests
- `fault-details-report` direct route invokes the browser-backed tool path rather than bypassing the browser layer
- direct route returns failure cleanly when tool execution fails

## Recommended First Implementation Slice

1. Add a tiny scene metadata loader and dispatch-mode policy module.
2. Extend runtime path resolution so the moved staged skills/scenes are visible.
3. Add deterministic scene matching for the two initial scenes.
4. Implement `agent_browser` instruction injection for `95598-repair-city-dispatch`.
5. Implement `direct_browser` execution for `fault-details-report` using the browser-backed skill path.
6. Add focused tests for matching, loading, tool exposure, and direct-vs-agent behavior.

## Open Design Constraint Captured From Discussion

The user explicitly requires the following combined behavior:

- support both kinds of scene execution in the same architecture
- one initial scene should be able to execute without the model
- one initial scene should execute through the model
- both must still use browser-internal execution methods like the Zhihu path
- the design must stay extensible because more staged skills may be added under the same path later

This design is built around those exact constraints.