claw/docs/superpowers/specs/2026-04-15-generated-scene-skill-platform-design.md

Generated Scene Skill Platform Design

Goal: Evolve sgClaw from one-off business-scene integrations into a platform that can generate, register, and invoke staged scene skills through a generic runtime path, while keeping v1 implementation strictly limited to report/collection-oriented browser_script scenes.

Status: Approved brainstorming direction for formal specification.

---

Decision Summary

1. sgClaw should become a scene-skill platform, not a growing set of per-scene Rust branches.
2. V1 should support only report/collection-oriented browser_script scenes generated from existing scenario directories.
3. The generated output must include both the staged skill package and a platform registration manifest so that new scenes can be discovered and invoked with minimal or zero per-scene Rust changes.
4. In the intranet near term, deterministic mode remains the explicit 。。。 suffix path; no model is required for v1 invocation.
5. The design must preserve the existing main architecture, stay close to the current browser_script and artifact pipeline, and avoid platform changes that drift into a general workflow engine.
6. The implementation should happen on a new branch copied from ws, not directly inside the current ws branch.
7. The generator and runtime must be separated by explicit contracts so the generator can later be extracted into a standalone project.
8. The platform design must turn the full tq-lineloss-report lessons learned into durable documentation and generator input rules so future generated skills do not repeat the same mistakes.

---

Hard Constraints

1. Extensibility is mandatory

The platform must support future extension without forcing redesign of the core contracts. The design must leave clean seams for:

• additional scene types
• additional deterministic matchers
• additional parameter resolver types
• additional tool invokers beyond browser_script
• future LLM semantic routing on top of the same registered scene contracts
• future extraction of the generator into a separate project

2. Stay on the main line

The core objective is:

• generate staged scene skills from existing scenario directories
• register them automatically
• invoke them through a generic deterministic runtime path

The design must not drift into:

• a full low-code workflow engine
• a general browser RPA authoring platform
• a full login/session orchestration platform in v1
• a broad runtime rewrite unrelated to generated scene skill support

3. Preserve the current architecture theme

The design should reuse and generalize the parts of sgClaw that already look platform-like:

• skills discovery/loading
• browser_script execution seams
• artifact interpretation
• export/postprocess seams
• bootstrap target resolution seams

It must avoid large theme-breaking rewrites of the runtime unless a generic platform seam truly requires them.

4. Execution branch strategy

This work is large enough that implementation should not land directly on the active ws branch. The future implementation plan must explicitly require:

• start from the current ws branch state
• create a new branch copied from ws
• perform platform conversion there
• preserve ws as the stable reference baseline during the migration

5. Generator extraction must remain possible

The generator should not be tightly coupled to claw-new internals. The boundary between runtime and generator must be a stable package/manifest contract so the generator can later move into a separate project without redesigning registered scene skills.

6. tq-lineloss-report lessons learned must become first-class inputs

The design must require a durable lessons-learned document derived from the full tq-lineloss-report path, including deterministic routing, canonical parameterization, bootstrap targets, pipe/ws differences, timeout chains, artifact contracts, and Rust-side export constraints.

This document is not an appendix. It is a required generator-design input and future template hardening source.

The document must be split into two layers so it remains enforceable instead of becoming loose prose:

• a structured machine-consumable lessons artifact that generator templates can read or reference deterministically
• a human-oriented narrative/analysis document explaining the why, trade-offs, and debugging history behind those lessons

7. Use the superpowers process end-to-end

This design must be carried through the superpowers flow:

• brainstorming
• formal spec
• review loop
• user review
• implementation planning

8. Think through the details before implementation

The spec must make the critical details explicit now so execution does not discover foundational contract problems halfway through.

---

Why This Platform Exists

The current line-loss integration proves that sgClaw can support a staged business scene, but it also exposes the current architecture problem:

• the staged skill package exists and is useful
• the browser_script execution seam exists and is useful
• the runtime has some generic pieces already
• but deterministic routing, parameter normalization, bootstrap target selection, and scene-specific invocation are still too tied to one-off Rust code

Examples visible in the current code:

• src/compat/deterministic_submit.rs hardcodes the line-loss suffix route, target URL, host, scene matcher, org resolver, and period resolver
• src/service/server.rs:453 already has a more general bootstrap-target seam, but it still delegates deterministic planning to scene-specific logic
• src/compat/direct_skill_runtime.rs:148 already knows how to resolve and execute a browser_script tool from the skills directory, which is a strong existing platform primitive
• src/runtime/engine.rs:232 already has multi-directory runtime skill loading and browser-surface-aware filtering, which is another platform primitive

The design goal is to promote the reusable parts into a stable platform and move scene-specific behavior into generated packages plus scene manifests.

---

V1 Scope

In scope

V1 is strictly limited to report/collection-oriented browser_script scenes generated from existing scenario directories.

That means:

• input source is an existing scenario directory containing page assets and business JS logic
• generated output is a staged skill package plus a platform registration manifest
• runtime invocation uses deterministic 。。。 routing only
• execution reuses the existing browser_script invocation chain
• output is a structured report artifact plus optional generic report postprocessing such as local XLSX export/open

Out of scope

V1 does not include:

• generic action/authoring scenes such as navigation, form filling, publishing, or editor automation
• arbitrary multi-step workflow orchestration
• session/login orchestration as a generic platform capability
• non-browser_script tool generation
• full LLM semantic scene routing implementation
• a universal low-code engine

Spec-level future seams

The spec must define extension interfaces for future use, but those extensions are not part of v1 implementation:

• matcher extension seam for future LLM semantic selection
• resolver extension seam for more complex domain parsing
• invoker extension seam for new tool kinds
• artifact interpreter extension seam for non-report results
• postprocessor extension seam beyond report export/open
• generator packaging seam for future project extraction

---

Platform Architecture

The recommended platform has five units.

1. Scene Source Analyzer

Input:

• an existing scenario directory
• typical source artifacts such as index.html, js/*, business requests, export calls, state dictionaries, and target pages

Responsibility:

• inspect source structure and collect candidate scene metadata
• identify the likely business page URL/domain
• identify likely collection mode (report/collection in v1)
• extract request-shape hints, output table hints, export/report-log hints, and page dependencies
• record uncertainty instead of guessing when source evidence is incomplete

This unit is analysis-only. It does not perform runtime registration or invocation.

2. Skill Generator

Input:

• analyzed scene source description
• generator templates
• lessons-learned rules derived from existing scenes such as tq-lineloss-report

Output:

• staged skill package
• platform registration manifest
• generated references and contract docs

Generated package contents for v1:

• SKILL.toml
• SKILL.md
• references/collection-flow.md
• references/data-quality.md
• scripts/*.js
• scripts/*.test.js
• optional scene snapshot assets
• scene.toml

The generator is responsible for producing complete registration-ready output, not just scaffolding files.

3. Scene Registry Loader

Responsibility:

• scan staged skill directories
• locate scene.toml
• validate scene registration contracts
• register scenes into a unified runtime registry

This replaces the long-term need for per-scene Rust wiring.

The existing runtime already has useful loading primitives in src/runtime/engine.rs:361 and skill-dir normalization in src/compat/config_adapter.rs:90. V1 should build on those instead of replacing them.

4. Generic Deterministic Dispatcher

Responsibility:

• activate only when the raw instruction ends with 。。。
• iterate registered scenes, not hardcoded scene branches
• evaluate deterministic match rules declared in scene.toml
• resolve required canonical parameters using platform resolver types
• produce either:
  • mismatch / unsupported-scene prompt
  • missing/ambiguous parameter prompt
  • executable scene invocation plan

Multi-match and precedence rules

Extensibility means multiple registered scenes may match the same deterministic request. The platform must define this explicitly instead of allowing hidden first-match behavior.

Design rules:

• deterministic dispatch must score candidate scenes through declared match signals rather than raw file-load order
• higher-confidence signals may include page URL/title context, explicit include/exclude keyword fit, and resolver success for required parameters
• plain keyword overlap alone is not sufficient justification for silently choosing one scene when another remains plausible
• if two or more scenes remain materially plausible after deterministic scoring and required-parameter evaluation, the dispatcher must fail closed with an explicit ambiguity prompt rather than guessing
• the future implementation plan must lock the scoring and tie-break order in tests
• bootstrap/page-context signals are allowed to participate in disambiguation, but they must be declared and explainable

This keeps the system extensible without turning new scenes into routing contradictions.

This should replace scene-specific logic currently concentrated in src/compat/deterministic_submit.rs.

5. Generic Execution Pipeline

Responsibility:

• invoke the resolved tool through the existing browser_script seam
• reuse bootstrap target resolution
• interpret the artifact according to the registered artifact contract
• run generic report postprocessing such as Rust-side XLSX export
• keep business-specific interpretation out of the platform core

The strong requirement is to preserve the already-validated common path in:

• src/compat/direct_skill_runtime.rs
• src/compat/browser_script_skill_tool.rs
• the existing report-artifact and export seams

---

Scene Registration Contract

The central platform contract is a per-scene registration manifest, named scene.toml in this design.

Why a separate manifest is needed

SKILL.toml describes tools. It does not fully describe:

• deterministic routing rules
• scene identity
• platform parameter resolution contracts
• bootstrap target rules
• artifact interpretation rules
• generic postprocessing declarations

Without this manifest, the generator would only create files while the runtime would still need scene-specific Rust changes.

Manifest responsibilities

Each generated scene manifest must declare:

1. scene identity and runtime entrypoint
2. bootstrap/page context requirements
3. deterministic matching rules
4. parameter schema and resolver mapping
5. execution contract
6. artifact contract
7. postprocess contract
8. schema/version metadata sufficient for long-term generator/runtime evolution

Manifest versioning and registry rules

The manifest contract must be explicit and versioned from the start.

Required rules:

• every scene.toml must declare a manifest schema version independent from the scene version
• the runtime must validate schema compatibility before registration
• scene registration must require globally unique scene.id values across all loaded scene roots
• duplicate scene IDs must fail registration deterministically rather than silently overriding an earlier scene
• the future implementation plan must decide and test the duplicate policy explicitly, but the default design rule is fail-fast with a clear error describing both conflicting manifest locations
• manifest evolution must prefer additive compatibility where possible so a future standalone generator can target the same runtime contract intentionally rather than by coincidence

This versioned contract is part of the extraction seam: it is what allows the runtime and a future standalone generator to evolve without private coupling.

Recommended manifest shape

[scene]
id = "tq-lineloss-report"
skill = "tq-lineloss-report"
tool = "collect_lineloss"
kind = "browser_script"
version = "0.1.0"
category = "report_collection"

[manifest]
schema_version = "1"

[bootstrap]
expected_domain = "20.76.57.61"
target_url = "http://20.76.57.61:18080/gsllys/tqLinelossStatis/tqQualifyRateMonitor"
page_title_keywords = ["线损"]
requires_target_page = true

[deterministic]
suffix = "。。。"
include_keywords = ["线损", "月累计", "周累计"]
exclude_keywords = ["知乎"]

[[params]]
name = "org"
resolver = "dictionary_entity"
required = true
prompt_missing = "已命中台区线损报表技能，但缺少供电单位。"
prompt_ambiguous = "已命中台区线损报表技能，但供电单位存在歧义，请补充更完整名称。"

[params.resolver_config]
dictionary_ref = "references/org-dictionary.json"
output_label_field = "org_label"
output_code_field = "org_code"

[[params]]
name = "period"
resolver = "month_week_period"
required = true
prompt_missing = "已命中台区线损报表技能，但缺少统计周期。"
prompt_ambiguous = "已命中台区线损报表技能，但统计周期存在歧义，请补充更明确表达。"

[artifact]
type = "report-artifact"
success_status = ["ok", "partial", "empty"]
failure_status = ["blocked", "error"]

[postprocess]
exporter = "xlsx_report"
auto_open = "excel"

Design rule

scene.toml declares behavior. It does not contain business JS code.

• business collection logic stays in scripts/*.js
• platform match/resolver selection stays in the manifest
• generic runtime execution stays in the platform

---

Platform-Provided Generic Capabilities

The platform should expose a small, explicit set of reusable capability types.

1. Scene Matchers

V1 deterministic matcher types should stay simple and declarative:

• include keywords
• exclude keywords
• required suffix
• optional page URL/title constraints

This is enough for v1 report scenes and avoids overbuilding NLP into deterministic mode.

Future seam:

• add a semantic matcher interface for model-based routing later without changing the rest of the scene contract

2. Parameter Resolvers

The platform should provide reusable resolver types instead of scene-specific branches.

Recommended v1 resolver types:

• dictionary_entity
  • maps aliases to canonical label/code pairs using scene-provided dictionary data
• month_week_period
  • parses month/week intent and canonical time payloads
• fixed_enum
  • maps deterministic text options into fixed internal values
• literal_passthrough
  • preserves an already explicit literal value

Design rule:

If a new scene needs a new resolver type, add a reusable platform capability. Do not add a scene-specific Rust branch.

3. Bootstrap Resolvers

The platform must be able to produce:

• expected_domain
• target_url
• page-context validation hints

These should come from registration metadata, not from per-scene hardcoded constants.

This generalizes the existing bootstrap-target seam already present in src/service/server.rs:453.

4. Tool Invokers

V1 supports one invoker type only:

• browser_script

This is intentionally narrow. It keeps the platform close to the existing main architecture and avoids broad redesign.

Future seam:

• later add invokers for other tool kinds without changing scene registration concepts

5. Artifact Interpreters and Postprocessors

V1 should provide generic handling for report-style results:

• report-artifact interpreter
• xlsx_report exporter/postprocessor
• open-after-export policies

The platform should not know about line-loss business fields specifically. It should only know the generic artifact contract.

---

Generated Skill Package Contract

V1 generated scenes must follow a predictable staged package shape.

Required generated files

• SKILL.toml
• SKILL.md
• scene.toml
• references/collection-flow.md
• references/data-quality.md
• scripts/<entry>.js
• scripts/<entry>.test.js
• optional support assets such as scene snapshots

V1 generated skill assumptions

Generated report/collection skills must:

• accept normalized canonical args only
• validate expected page context before collection
• avoid re-parsing raw user language inside the script
• return one structured artifact object
• keep page/API collection logic inside the script
• leave generic interpretation/export policy to the platform where possible

Separation rule

The generated skill package owns:

• page inspection
• page-side state usage
• page/API calls
• row normalization
• scene-local docs and references

The platform owns:

• scene discovery and registration
• deterministic scene selection
• canonical parameter resolution using generic resolver types
• tool invocation
• artifact interpretation
• generic postprocessing

---

Migration Path from tq-lineloss One-Off to Platform Sample

The current line-loss implementation should not be discarded. It should become the first migration sample and platform proof point.

Why line-loss is the right sample

It already exercised most of the hard problems:

• deterministic routing via 。。。
• canonical org resolution
• canonical month/week resolution
• staged browser_script packaging
• bootstrap target selection
• report artifact shaping
• local export needs
• pipe/ws transport differences
• real browser/runtime timeout and callback-host issues

Phase A: Extract generic registry and invocation seams

First, add:

• scene registry loader
• manifest reader/validator
• generic deterministic dispatch planning

while preserving the existing browser_script execution seam.

Phase B: Convert tq-lineloss into the first manifest-driven scene

Move line-loss specific declarations out of hardcoded Rust branches and into registration data:

• scene identity
• target URL and expected domain
• deterministic scene match rules
• resolver mapping
• artifact/postprocess declarations

Keep the business collection script in the skill package.

Phase C: Build the generator on top of the stabilized contract

Once line-loss runs through the manifest-driven platform path, define generator templates that produce the same contracts automatically from scenario directories.

Phase D: Add future semantic routing later

When model access is available, layer semantic routing onto the same registered scene contracts.

The LLM should eventually help with:

• selecting a scene
• filling unresolved parameters

But it should not replace the registered execution contract.

---

Generator Extraction Boundary

The design must support eventually moving the generator out of sgClaw.

Required extraction seam

The generator and runtime should communicate only through generated artifacts and contracts:

• staged skill package layout
• scene.toml
• any scene-local dictionaries/reference data

Consequence

The runtime must not depend on internal generator implementation details.

This means:

• do not let the runtime call generator internals directly
• do not let the generator rely on private runtime types as its only output format
• keep manifest and package contracts explicit and versionable

This is what makes later extraction into a separate repository practical.

---

tq-lineloss-report Lessons-Learned Document Requirement

The platform design requires a dedicated lessons-learned document based on the full tq-lineloss-report implementation and debugging path.

Why this document is required

The line-loss path uncovered issues that a naive generator would recreate immediately.

These include:

• deterministic routing and prompt semantics
• strict canonical org/period normalization
• no hidden page-default fallback
• target URL / expected-domain / bootstrap-target contracts
• browser_script target URL requirements
• artifact shape discipline
• Rust-side XLSX export necessity because browser-side localhost export can fail under remote page origin constraints
• pipe vs ws differences
• callback-host and helper bootstrap timeout risks
• real-world service-console runtime validation gaps

Required sections

The lessons document should at minimum cover:

1. source-scene assumptions that must be surfaced explicitly
2. deterministic routing pitfalls
3. canonical parameterization pitfalls
4. bootstrap target and page-context pitfalls
5. execution transport pitfalls (pipe/ws)
6. artifact and export pitfalls
7. testing pitfalls
8. manual runtime validation pitfalls
9. what should become generator template rules
10. what should remain scene-specific manual work

Required format and location

The design requires both artifacts to live in a stable, versioned location under the project docs so future plans and a future standalone generator can depend on them intentionally.

Recommended shape:

• docs/superpowers/references/tq-lineloss-lessons-learned.md
  • human-oriented narrative and rationale
• docs/superpowers/references/tq-lineloss-lessons-learned.toml
  • structured generator input rules

The TOML artifact should be organized as reusable rule sections such as:

• deterministic routing rules
• canonical parameter rules
• bootstrap/target-url rules
• artifact/postprocess rules
• validation/test checklist rules

The generator should consume the structured TOML rules as template constraints or generation-time validation inputs, while the Markdown document remains the explainability companion for human reviewers.

How it should be used

This document becomes:

• template hardening input for the generator
• a checklist for reviewing generated scenes
• a planning artifact for deciding which pieces can be automated safely

---

Existing Code Surfaces to Reuse

The design should explicitly build on these current platform-adjacent surfaces rather than replacing them wholesale.

Skills discovery and loading

• src/runtime/engine.rs:232 load skills for surface from configurable directories
• src/runtime/engine.rs:361 load runtime skills across multiple roots
• src/compat/config_adapter.rs:90 skill-dir normalization

Generic browser_script execution

• src/compat/direct_skill_runtime.rs:91 raw output execution helper
• src/compat/direct_skill_runtime.rs:148 tool resolution from staged skills
• src/compat/browser_script_skill_tool.rs script loading/wrapping/invocation pipeline

Bootstrap target resolution seam

• src/service/server.rs:453 submit bootstrap target resolution

Current one-off deterministic branch that should be generalized

• src/compat/deterministic_submit.rs

The line-loss-specific pieces in that file are the main migration targets for platform conversion.

---

Failure Semantics

The platform must preserve explicit, business-safe failure semantics.

Deterministic mismatch

If the request ends with 。。。 but no registered scene matches, the runtime must return an explicit deterministic mismatch response.

Missing / ambiguous parameters

If a registered scene matches but required parameters cannot be resolved uniquely, the runtime must prompt rather than guess.

Execution failure

Execution failures should be interpreted according to the registered artifact contract and generic report semantics, not through per-scene special cases in the platform core.

Design rule

The platform should never silently recover by using page defaults when the scene contract requires canonical inputs.

---

Verification Requirements for the Future Implementation Plan

The future implementation plan must verify:

1. registry loading from generated scene manifests
2. deterministic dispatch through registered scenes instead of per-scene branches
3. manifest-driven bootstrap target selection
4. manifest-driven parameter resolver dispatch
5. generic browser_script invocation of generated scenes
6. generic report artifact interpretation
7. generic XLSX postprocessing compatibility
8. unchanged behavior for existing non-scene core flows outside v1 scope
9. migration of tq-lineloss from hardcoded branch to manifest-driven sample
10. branch strategy based on a new branch copied from ws
11. lessons-learned document completeness and reuse as generator input
12. separation seam sufficient for future generator extraction

---

Out of Scope for the V1 Implementation Plan

The future implementation plan should explicitly avoid:

• generic login/session capability as a first-class v1 platform subsystem
• full semantic routing implementation with models
• generalized action workflows
• a full scene DSL runtime
• direct implementation of multiple non-report scene kinds
• replacing the validated core browser_script execution path with a new protocol
• broad architectural rewrites unrelated to generated scene skill support

---

Recommended First Implementation Slice

The most stable first slice is:

1. create the scene manifest contract and validator
2. build a registry loader over existing staged skill directories
3. generalize deterministic dispatch to use registered scenes
4. migrate tq-lineloss into the first manifest-driven scene
5. document all line-loss lessons learned
6. only then build the scenario-directory-to-skill generator

This keeps the platform grounded in a working runtime contract before the generator is asked to automate against it.

---

Final Recommendation

Build sgClaw into a generated scene skill platform by separating it into:

• a generic runtime platform that discovers, matches, resolves, invokes, and postprocesses scenes using manifest-driven contracts
• a scenario-directory-to-skill generator that emits staged skill packages and scene registration manifests

Implement v1 only for report/collection-oriented browser_script scenes, keep deterministic invocation on the explicit 。。。 suffix, migrate tq-lineloss into the first manifest-driven sample, and preserve a clean extraction seam so the generator can later become its own project.