75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# SGrobot Adapter Reference
|
|
|
|
## Boundary
|
|
|
|
SGrobot uses two runtime artifact families:
|
|
|
|
- `plan_templates/<task>/PlanTemplate.toml`: business orchestration, selectable as a digital employee task.
|
|
- `.sgclaw-workspace/skills/<skill>/SKILL.toml`: atomic runtime capability loaded by Skill Catalog.
|
|
|
|
The Codex-facing `SKILL.md` in this repository only teaches an agent how to generate those artifacts.
|
|
|
|
## Generated Flow Shape
|
|
|
|
For each rrweb semantic trace, generate one business-specific package:
|
|
|
|
```text
|
|
plan_templates/rrweb-<flow>/PlanTemplate.toml
|
|
.sgclaw-workspace/skills/rrweb-<flow>-execute/SKILL.toml
|
|
.sgclaw-workspace/skills/rrweb-<flow>-execute/scripts/execute_trace.js
|
|
.sgclaw-workspace/skills/rrweb-<flow>-execute/trace.semantic.json
|
|
```
|
|
|
|
Do not generate a single universal runtime skill that expects `trace_path` unless SGrobot core gains stable per-step argument passing. Current stable PlanTemplate usage binds a step to a skill name; the runtime resolves that skill's primary tool.
|
|
|
|
## PlanTemplate Mapping
|
|
|
|
Use three steps:
|
|
|
|
1. `open-target-page`: `skills = ["browser.open_url"]`; description includes the trace `startUrl`.
|
|
2. `run-recorded-flow`: `skills = ["rrweb-<flow>-execute"]`; executes generated page script with sgBrowser.
|
|
3. `save-result`: `skills = ["json.save_result"]`; saves structured output.
|
|
|
|
Set `requires_approval = true` on `run-recorded-flow` when `--default-mode execute` is used and the trace includes mutating actions such as `click`, `fill`, `select`, `check`, `submit`, or `risk = "write"`.
|
|
|
|
## Runtime Skill Mapping
|
|
|
|
Generated `SKILL.toml` should use:
|
|
|
|
```toml
|
|
[[tools]]
|
|
name = "execute_trace"
|
|
kind = "sgbrowser_action"
|
|
command = "sgBrowserExcuteJsCodeByDomain"
|
|
expected_domain = "<domain from startUrl>"
|
|
|
|
[tools.args]
|
|
script_path = "scripts/execute_trace.js"
|
|
```
|
|
|
|
Keep `sgBrowserExcuteJsCodeByDomain` and the `sgBrowerserOpenPage` spelling used by the existing SGrobot project. Do not replace this path with Playwright, CDP, or a generic browser action.
|
|
|
|
## Runtime Script Rules
|
|
|
|
The generated `execute_trace.js` runs inside the target page. It should:
|
|
|
|
- Default to `dry-run` unless the generator is called with `--default-mode execute`.
|
|
- Resolve target elements by stable CSS selector first, XPath second, visible text fallback last.
|
|
- Return structured JSON with `ok`, `mode`, `trace_id`, `url`, `title`, and per-action results.
|
|
- Stop on the first failed action and include an error message.
|
|
|
|
## Verification
|
|
|
|
After generating into a SGrobot repo:
|
|
|
|
```bash
|
|
node scripts/generate_sgrobot_flow.mjs --trace examples/basic-trace.json --out /Users/zhaoyilun/projects/sgrobot-architecture-design --default-mode dry-run
|
|
```
|
|
|
|
Then verify in SGrobot:
|
|
|
|
```powershell
|
|
Invoke-RestMethod 'http://127.0.0.1:42617/api/debug/plans?limit=20' | ConvertTo-Json -Depth 5
|
|
Invoke-RestMethod 'http://127.0.0.1:42617/api/skill' | ConvertTo-Json -Depth 4
|
|
```
|