admin/claw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: remove ws-only scene routing remnants

Browse Source 
Keep the ws branch focused on websocket and Zhihu behavior by dropping staged scene-routing artifacts and restoring single-path skills dir semantics.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
木炎
2026-04-10 22:35:43 +08:00
parent 81de162756
commit b454fa3f54
17 changed files with 107 additions and 2251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

455
docs/superpowers/plans/2026-04-06-scene-skill-runtime-routing-plan.md
View File

@@ -1,455 +0,0 @@
# Scene Skill Runtime Routing Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Add a first scene-routing slice that recognizes staged business scenes from natural language and dispatches them through browser-backed execution, with `fault-details-report` using direct browser execution and `95598-repair-city-dispatch` using agent-mediated browser execution.
**Architecture:** Introduce a small registry module that loads the first staged `scene.json` contracts plus runtime dispatch policy from the external `skill_staging` root. Route matched scenes through one of two paths: `direct_browser` scenes execute through compat orchestration without the model choosing tools, while `agent_browser` scenes stay in the existing agent flow but get scene-specific browser-first prompt injection. Both modes must still execute through the existing `BrowserScriptSkillTool` / browser backend path so the final business action uses browser-internal methods.
**Tech Stack:** Rust, serde/JSON metadata loading, existing compat orchestration/runtime/workflow layers, browser-backed skill tools, focused `cargo test` coverage.
---
## File Map
**Create:**
- `src/runtime/scene_registry.rs` — load staged scene metadata, attach runtime dispatch policy, expose matching helpers for the first slice.
- `tests/scene_registry_test.rs` — focused tests for registry loading, matching, and policy behavior.
**Modify:**
- `src/runtime/mod.rs` — export the new scene registry module/types used by runtime and compat layers.
- `src/compat/config_adapter.rs` — verify the moved external `skill_staging` root resolves to the staged `skills` child, and only change path resolution if a targeted regression proves it is insufficient.
- `src/runtime/engine.rs` — inject scene-specific browser-first contracts for `agent_browser` scenes and keep existing Zhihu prompt behavior intact.
- `src/compat/workflow_executor.rs` — extend route detection and direct execution support for `fault-details-report` using the browser-backed skill path.
- `src/compat/orchestration.rs` — let primary orchestration prefer direct execution for `direct_browser` scenes while leaving `agent_browser` scenes in the agent path.
- `src/compat/browser_script_skill_tool.rs` — expose the thinnest reusable browser-backed execution helper needed so direct scene execution can reuse the same `browser_script` semantics instead of drifting into a duplicate local path.
- `src/compat/runtime.rs` — ensure runtime sees the staged skills root and continues exposing browser-backed scene tools.
- `tests/compat_config_test.rs` — add path-resolution coverage for the staged external root.
- `tests/runtime_profile_test.rs` — add scene-specific instruction contract assertions.
- `tests/browser_script_skill_tool_test.rs` — add coverage for any new reusable direct-execution helper introduced in the browser-script layer.
- `tests/compat_runtime_test.rs` — add orchestration/direct-route coverage for the new scene behavior.
**Reference:**
- `docs/superpowers/specs/2026-04-06-scene-skill-runtime-routing-design.md`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\fault-details-report\scene.json`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\95598-repair-city-dispatch\scene.json`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\SKILL.toml`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\95598-repair-city-dispatch\SKILL.toml`
### Task 1: Add Scene Registry And Matching
**Files:**
- Create: `src/runtime/scene_registry.rs`
- Modify: `src/runtime/mod.rs`
- Test: `tests/scene_registry_test.rs`
- [ ] **Step 1: Write the failing registry tests**
Add tests that prove the first-slice registry can:
- load `fault-details-report` with `dispatch_mode = direct_browser`
- load `95598-repair-city-dispatch` with `dispatch_mode = agent_browser`
- match natural-language phrases like `导出故障明细` and `95598抢修市指监测`
- ignore missing/broken scene files without panicking
Example assertions to include:
```rust
assert_eq!(entry.scene_id, "fault-details-report");
assert_eq!(entry.dispatch_mode, DispatchMode::DirectBrowser);
assert_eq!(entry.tool_name(), "fault-details-report.collect_fault_details");
assert_eq!(entry.expected_domain, "__scene_fault_details__");
```
```rust
assert_eq!(matched.scene_id, "95598-repair-city-dispatch");
assert_eq!(matched.dispatch_mode, DispatchMode::AgentBrowser);
```
- [ ] **Step 2: Run the new registry tests to verify they fail**
Run:
```bash
cargo test scene_registry --test scene_registry_test -- --nocapture
```
Expected: FAIL because `src/runtime/scene_registry.rs` and the exported registry APIs do not exist yet.
- [ ] **Step 3: Implement the minimal scene registry module**
Create `src/runtime/scene_registry.rs` with:
- a small deserialized scene metadata struct for `scene.json`
- a `DispatchMode` enum
- a single runtime registry-entry struct combining scene metadata plus runtime policy
- first-slice hardcoded runtime policy for the two initial scenes
- helper methods like:
```rust
pub fn load_first_slice_scene_registry() -> Vec<SceneRegistryEntry>
pub fn match_scene_instruction(instruction: &str) -> Option<SceneRegistryEntry>
```
Use deterministic keyword/alias matching only. Do not add embeddings, fuzzy search, or generic scoring infrastructure beyond what the spec requires.
- [ ] **Step 4: Export the registry from `src/runtime/mod.rs`**
Expose the new types/helpers needed by runtime and compat layers, for example:
```rust
mod scene_registry;
pub use scene_registry::{
load_first_slice_scene_registry,
match_scene_instruction,
DispatchMode,
SceneRegistryEntry,
};
```
- [ ] **Step 5: Run the registry tests to verify they pass**
Run:
```bash
cargo test scene_registry --test scene_registry_test -- --nocapture
```
Expected: PASS
- [ ] **Step 6: Commit Task 1**
```bash
git add src/runtime/scene_registry.rs src/runtime/mod.rs tests/scene_registry_test.rs
git commit -m "feat: add staged scene registry matching"
```
### Task 2: Verify Staged Skills Root Resolution
**Files:**
- Modify if needed: `src/compat/config_adapter.rs:94`
- Modify if needed: `src/compat/runtime.rs:152`
- Test: `tests/compat_config_test.rs`
- [ ] **Step 1: Write the targeted staged-root path test**
Add a focused test that proves an external configured `skill_staging` root resolves to its `skills` child and preserves current nested-skills behavior.
Add a test shape like:
```rust
let staged_root = root.join("external/skill_staging");
fs::create_dir_all(staged_root.join("skills")).unwrap();
fs::create_dir_all(staged_root.join("scenes")).unwrap();
let settings = DeepSeekSettings {
api_key: "key".to_string(),
base_url: "https://api.deepseek.com".to_string(),
model: "deepseek-chat".to_string(),
skills_dir: Some(staged_root.clone()),
};
assert_eq!(resolve_skills_dir(&root, &settings), staged_root.join("skills"));
```
- [ ] **Step 2: Run the focused config test and record the actual result**
Run:
```bash
cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture
```
Expected: either
- PASS immediately, proving current path resolution already supports the staged-root contract, or
- FAIL with a concrete staged-root regression that justifies a minimal config fix.
- [ ] **Step 3: Only if the staged-root test fails, implement the narrowest config fix**
If the test fails, update `src/compat/config_adapter.rs` so configured external staged roots resolve to the staged skill package directory used by runtime skill loading. Keep the change narrow:
- preserve current behavior for normal `skills` roots
- add the smallest extra branch needed for the failing staged-root case
- do not create a broad path-discovery system
- [ ] **Step 4: Verify runtime alignment with the resolved staged skills root**
Confirm `src/compat/runtime.rs` still uses the resolved `skills_dir` as-is. If no runtime code change is needed after the test outcome, leave the file untouched and rely on test coverage.
- [ ] **Step 5: Run the focused config tests to verify they pass**
Run:
```bash
cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture
```
Expected: PASS
- [ ] **Step 6: Commit Task 2**
```bash
git add src/compat/config_adapter.rs src/compat/runtime.rs tests/compat_config_test.rs
git commit -m "test: verify staged scene skill root resolution"
```
### Task 3: Inject Agent-Browser Scene Contract For 95598
**Files:**
- Modify: `src/runtime/engine.rs:135`
- Test: `tests/runtime_profile_test.rs`
- [ ] **Step 1: Write the failing instruction-contract tests**
Add focused tests proving that when the instruction matches `95598-repair-city-dispatch`, `RuntimeEngine::build_instruction(...)` includes a scene-specific browser contract requiring the tool `95598-repair-city-dispatch.collect_repair_orders` first.
Example assertion pattern:
```rust
let instruction = engine.build_instruction(
"请做95598抢修市指监测",
Some("https://example.invalid/dispatch"),
Some("95598抢修-市指"),
true,
);
assert!(instruction.contains("95598-repair-city-dispatch.collect_repair_orders"));
assert!(instruction.contains("browser workflow, not a text-only task"));
assert!(instruction.contains("generic browser probing only after"));
```
Also add a negative control showing unrelated tasks do not receive this scene contract.
- [ ] **Step 2: Run the focused runtime-profile tests to verify they fail**
Run:
```bash
cargo test --test runtime_profile_test 95598 -- --nocapture
```
Expected: FAIL because no scene-specific contract is injected yet.
- [ ] **Step 3: Implement minimal scene-aware prompt injection**
Update `src/runtime/engine.rs` to:
- query the new scene matcher
- when the matched scene is `agent_browser`, append a scene execution contract section
- preserve existing Zhihu prompt sections unchanged
Keep the contract explicit and narrow, for example:
```text
Scene execution contract:
- Matched scene: 95598-repair-city-dispatch
- Required tool: 95598-repair-city-dispatch.collect_repair_orders
- This is a browser workflow, not a text-only task.
- Business data must come from the matched browser-backed scene tool.
- Only use generic browser probing after the matched scene tool fails.
```
Do not add hard allowed-tool narrowing in this task; slice one only promises instruction-level enforcement.
- [ ] **Step 4: Run the focused runtime-profile tests to verify they pass**
Run:
```bash
cargo test --test runtime_profile_test 95598 -- --nocapture
```
Expected: PASS
- [ ] **Step 5: Commit Task 3**
```bash
git add src/runtime/engine.rs tests/runtime_profile_test.rs
git commit -m "feat: inject 95598 scene browser contract"
```
### Task 4: Add Direct Browser Route For Fault Details
**Files:**
- Modify: `src/compat/workflow_executor.rs:58`
- Modify: `src/compat/orchestration.rs:9`
- Modify: `src/compat/browser_script_skill_tool.rs:101`
- Test: `tests/browser_script_skill_tool_test.rs`
- Test: `tests/compat_runtime_test.rs`
- [ ] **Step 1: Write the failing route-detection tests**
Add focused tests that prove:
- natural language like `导出故障明细` is detected as a direct scene route
- primary orchestration is selected for that scene
- missing scene metadata leaves unrelated routing unchanged
Target the existing routing seams with test shapes like:
```rust
assert!(sgclaw::compat::orchestration::should_use_primary_orchestration(
"导出故障明细",
Some("https://example.invalid/fault"),
Some("故障明细"),
));
```
and a focused route assertion using the new route enum variant.
- [ ] **Step 2: Run the focused route tests to verify they fail**
Run:
```bash
cargo test --test compat_runtime_test fault_details -- --nocapture
```
Expected: FAIL because no direct scene route exists yet.
- [ ] **Step 3: Write the failing browser-script helper tests**
Add focused tests in `tests/browser_script_skill_tool_test.rs` for the thinnest reusable helper needed by direct scene execution. The tests should prove that the helper:
- reads the packaged script from the skill root
- wraps args exactly like `BrowserScriptSkillTool`
- invokes browser `Eval`
- returns normalized serialized output
- fails clearly when required fields like `expected_domain` are missing
- [ ] **Step 4: Run the focused browser-script helper tests to verify they fail**
Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture
```
Expected: FAIL because the reusable helper does not exist yet.
- [ ] **Step 5: Implement the reusable browser-backed execution helper**
Update `src/compat/browser_script_skill_tool.rs` with the smallest reusable helper that direct scene execution can call while preserving the same `browser_script` semantics as normal skill execution. Keep it narrow:
- reuse the same script loading and wrapping rules
- require explicit `expected_domain`
- return normalized serialized output
- do not introduce a second browser-script execution model
- [ ] **Step 6: Implement the direct fault-details route on top of that helper**
Update `src/compat/workflow_executor.rs` to:
- introduce a new direct route variant for `fault-details-report`
- extend `detect_route(...)` to return it when the scene matcher says `direct_browser`
- build required args from scene runtime policy
- call the reusable browser-script execution helper
- return normalized serialized tool output
If required scene args cannot be derived safely, return a clear failure instead of guessing.
- [ ] **Step 7: Wire primary orchestration to prefer the new direct scene route**
Update `src/compat/orchestration.rs` so `should_use_primary_orchestration(...)` and the direct execution branch treat the new `fault-details-report` route like the existing direct Zhihu routes.
- [ ] **Step 8: Run the focused direct-route and helper tests to verify they pass**
Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture
```
Expected: PASS
- [ ] **Step 9: Commit Task 4**
```bash
git add src/compat/browser_script_skill_tool.rs src/compat/workflow_executor.rs src/compat/orchestration.rs tests/browser_script_skill_tool_test.rs tests/compat_runtime_test.rs
git commit -m "feat: add direct fault-details scene routing"
```
### Task 5: Verify Tool Exposure, Browser-Surface Fallback, And Mixed Routing Together
**Files:**
- Modify if needed: `src/compat/runtime.rs:142`
- Test: `tests/compat_runtime_test.rs`
- Test: `tests/runtime_profile_test.rs`
- Test: `tests/scene_registry_test.rs`
- [ ] **Step 1: Write the failing integration-shape tests**
Add focused assertions that prove the mixed-mode design works together:
- staged browser-backed tool names are exposed
- `fault-details-report` uses direct routing
- `95598-repair-city-dispatch` stays in the agent path but gets scene-specific browser-first instruction injection
- browser-surface-disabled turns do not gain scene browser contracts
- browser-surface-disabled turns do not trigger `direct_browser` scene execution
- missing scene metadata preserves unchanged runtime behavior for unrelated tasks
- unrelated Zhihu behavior still works the same way
Use existing test seams instead of broad integration scaffolding.
- [ ] **Step 2: Run the focused mixed-routing tests to verify they fail**
Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture
```
Expected: FAIL until the mixed-routing assertions are implemented.
- [ ] **Step 3: Make the minimum runtime adjustments needed**
Only if required by the tests, adjust `src/compat/runtime.rs` so the loaded staged skills from the resolved external root are visible in the same way as existing browser-backed skills. Keep the shape of `build_browser_script_skill_tools(...)` and runtime tool assembly intact.
- [ ] **Step 4: Run the focused mixed-routing tests to verify they pass**
Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture
```
Expected: PASS
- [ ] **Step 5: Run the broader targeted verification sweep**
Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture
```
Expected: PASS
- [ ] **Step 6: Commit Task 5**
```bash
git add src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_runtime_test.rs tests/runtime_profile_test.rs
git commit -m "feat: wire staged scene mixed routing"
```
### Task 6: Final Verification And Handoff
**Files:**
- Verify: `src/runtime/scene_registry.rs`
- Verify: `src/compat/config_adapter.rs`
- Verify: `src/runtime/engine.rs`
- Verify: `src/compat/workflow_executor.rs`
- Verify: `src/compat/orchestration.rs`
- Verify: `tests/scene_registry_test.rs`
- Verify: `tests/compat_config_test.rs`
- Verify: `tests/runtime_profile_test.rs`
- Verify: `tests/compat_runtime_test.rs`
- [ ] **Step 1: Run the full focused verification set**
Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test -- --nocapture
```
Expected: PASS
- [ ] **Step 2: If any test fails, fix only the minimal root cause and re-run the same command**
Do not broaden scope. Keep fixes limited to scene registry, path resolution, prompt injection, or direct routing.
- [ ] **Step 3: Review the resulting diff against the spec**
Manually verify:
- `fault-details-report` is direct-browser
- `95598-repair-city-dispatch` is agent-browser
- both still use browser-backed execution semantics
- no broad Zhihu refactor slipped in
- the new scene-routing abstraction stays registry-driven
- [ ] **Step 4: Commit the final verification pass**
```bash
git add src/runtime/scene_registry.rs src/runtime/mod.rs src/compat/config_adapter.rs src/runtime/engine.rs src/compat/workflow_executor.rs src/compat/orchestration.rs src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_config_test.rs tests/runtime_profile_test.rs tests/compat_runtime_test.rs
git commit -m "test: verify scene skill runtime routing"
```