automation-guide

セマンティック自動化リファレンス

目次

• エンティティモデル
• Page / Target / Action / Fetch / Scenario / Job
• 主要操作
• エラー回復

エンティティモデル

Page (PG_xxx) ─持つ→ Target (TGT_xxx)
Page ─持つ→ Action (ACT_xxx) ─参照→ Target
Page ─持つ→ Fetch (FCH_xxx) ─参照→ Target
Scenario (SCN_xxx) ─組み合わせ→ Action/Fetch ステップ
Job (JOB_xxx) ─グループ化→ Scenario エントリ
Report (RPT_xxx) / JobReport (JRP_xxx) / Snapshot (SNP_xxx) / CustomView (VW_xxx)

Page

sm_register_page(tabId, label, page_type?, required_query_params?) → page_id（PG_xxx）。URLパターンは自動検出。クエリパラメータでページ種別を区別する場合、required_query_params: {"product": "leaflet"} を指定。順序非依存でマッチ。

Target

sm_add_target(tabId, targets: [{ label, role, ref, target_id? }]) → target_id（TGT_xxx）。target_id を渡すと既存ターゲットを再バインド。

Action

sm_add_action(page_id, label, steps)

ステップタイプ	主要パラメータ
click	target_id
type	target_id, value または param_ref
select	target_id, value または param_ref
wait	navigation, duration_ms, selector
scroll	target_id, direction
key	key
navigate	url
file_upload	target_id, file_path

param_ref: "{{name}}" でパラメータ化。retry_policy: { max_retries, delay_ms } で不安定な要素に対応。

Fetch

sm_add_fetch(page_id, label, fields: [{ name, target_id, extraction_type }])

抽出タイプ	戻り値
text	文字列
attribute	文字列（attribute パラメータを指定）
list	配列（item_selector + item_fields を追加）
count	数値
exists	真偽値

Scenario

sm_scenario_create(label, steps, params?) — ステップタイプ: navigate, action, fetch, loop, wait。テンプレート: {{param_name}}。

Job

sm_job_create(label, entries: [{ scenario_id, param_overrides? }])

主要操作

タスク	ツール
ページ定義の確認	sm_capabilities(tabId)
全定義の確認	sm_status(domain?)
ターゲットのテスト	sm_test_target(tabId, target_id)
ターゲットの再バインド	sm_add_target(targets: [{ target_id, ref }])
バックアップ	sm_export(domain) — Page, Target, Action, Fetch をエクスポート
リストア	sm_import(data, strategy?) — merge（既定）または replace-domain 戦略
削除	sm_delete(entity_type, entity_id)

エラー回復

sm_invoke/sm_fetch で needs_rebind: true → ターゲットが見つからない状態。

1. 診断: missing_targets の各エントリに対して sm_test_target(tabId, target_id) を実行
2. 修正: sm_add_target(targets: [{ target_id: "TGT_xxx", label, role, ref }]) — 既存の target_id を渡すとロケーターが更新される
3. 事前バックアップ: 大規模な変更の前に sm_export(domain) を実行

詳細ドキュメント

各ツールのパラメータ詳細・戻り値は tool_guide(tool: "sm_add_action") で確認。ワークフロー全体の判断ガイドは tool_guide(topic: "semantic_workflow") で取得。