opencli-sitemap-author

opencli-sitemap-author

SEO サイトマップではなく、エージェント向けのタスク実行グラフを作成します。この成果物は、opencli browser を使用するエージェントが現在の場所を把握し、次に進む経路、優先する OpenCLI アダプター、ページの状態が記憶と異なる場合の復旧方法を判断できるようにするものです。

サイトマップは小さく、検証済みの状態に保ってください。サイト全体をクロールしないでください。実際に確認した、タスクに関係する経路だけを記録してください。

---

ストレージモデル

2 つのレイヤーがあります。

• グローバルシード：sitemaps/<site>/（トップレベル）
• ローカルオーバーレイ：~/.opencli/sites/<site>/sitemap/

安定した ID が一致する場合は、ローカルオーバーレイが優先されます。新たな発見はまずローカルに書き込みます。レビュー後にのみグローバルへ昇格します。

推奨レイアウト：

sitemap/
  SITE.md                 # site purpose, auth assumptions, stable page ids
  pages/<page-id>.md      # page state signatures, actions, linked APIs
  pages/_<partial>.md     # cross-page UI partial (e.g. _tweet_card.md)
  workflows/<task-id>.md  # best path, fallback path, avoid list
  pitfalls.md             # durable failure modes and stale areas

サイズの目安（実測に基づくヒューリスティック）

references/sitemap-schema.md §1.1 の仕様では 800 トークンが厳格な上限ですが、PoC の実測では、シンプルなサイトでも 1 ページあたり 1〜2 個のアクションが自然に 800〜2000 トークンになります。無理な分割で断片化しないよう、author は次の表を参考に判断してください。

仕様上の 800 トークンは lazy-load の最適化目標であり、Phase 2 の監査しきい値でもあります。次の表は author の実践的な判断を補助するもので、仕様上の厳格な上限に代わるものではありません。800 トークンを超えるファイルには audit がフラグを立てます。author は理由（「5 個のまとまりのある UI プリミティブを一緒に配置」など）を説明するか、分割してください。

ファイルのトークン数	判断
< 1500	自然なサイズのため、変更不要
1500-3000	cohesion を確認 — まとまりのある UI プリミティブ 5 個を一緒に配置するのは問題ありません。内容が混在している場合は分割してください
> 3000	sub-file または partial に必ず分割してください（エージェントの lazy load 予算には実際に制限があります）

Phase 2 の cron audit では、バイト数ではなくトークン数を基準にします（CJK の 1 文字あたりのトークン数は、英語より 30〜50% 多くなります）。

---

作成ループ

1. 既存の記憶を読み込む：まずローカルオーバーレイを読み、次に存在する場合はグローバルシードを読みます。
2. 実際の状態を検証する：opencli browser <session> state、find、network、analyze を使用します。真実として扱うのはブラウザーの状態です。このサイトで opencli-adapter-author のセッションを完了した直後であれば、経路をゼロから再発見するのではなく、保持されているブラウズトレース（~/.opencli/sites/<site>/traces/）を証拠のシードとして使用します。
3. 長期的に有効な構造だけを記録する：ページの目的、安定したアンカー、状態シグネチャ、アクション、ワークフロー、API 参照、注意点。
4. 安定した ID を使用する：ページ、アクション、ワークフローの ID は、URL パラメーター、ロケールによる文言の変化、軽微なレイアウト変更があっても維持できるものにします。
5. ローカルにドラフトを書く：リポジトリへ明示的に昇格する場合を除き、~/.opencli/sites/<site>/sitemap/... を更新します。
6. 不一致があれば古い情報としてマークする：既存のサイトマップが現在のブラウザー状態と一致しない場合は、ブラウザーの状態を優先し、古い経路を無理に使わず、その項目を stale としてマークします。

---

必須のアクションスキーマ

すべてのアクションエッジに、次の情報を含めてください。

### action:<stable-id>
pre: <current page / state / auth requirements>
do: <agent action, adapter command, or semantic browser command>
post: <URL / state / output that proves success>
fail: <failure signal 1> | <signal 2>
recover: <fallback instruction>; adapter_health_update: <adapter> -> suspect
evidence: opencli browser <cmd> or trace:<path>

デフォルトでは、この簡潔な形式を使用してください。アクションに長い説明が本当に必要な場合にのみ、references/sitemap-schema.md の詳細な Markdown 形式を使用します。verified_at と source はファイルの frontmatter から継承されるため、各アクションで繰り返す必要はありません。

証拠のないアクションを昇格しないでください。復旧経路で adapter_health_update を指定した場合、browser-sitemap の利用側はそのヘルス更新をローカルオーバーレイに書き込む必要があります。これにより、次のエージェントが問題が確認されたアダプターを再試行しなくなります。

Partial ページ（複数ページで共通の UI）

partial ファイル（_<name>.md、url_patterns: []）には、複数ページで使われる UI プリミティブ（例：_tweet_card.md の like/reply/repost/bookmark）を格納します。複数のページから action:<id> in pages/_<name>.md で参照されます。

Partial のスコープ規則：partial 内のすべてのセレクター（testid / a11y / structural）は、partial のルート要素にスコープされている必要があります。ページレベルで最初に一致した要素を使ってはいけません。例として、_tweet_card.md を示します。

# ❌ 错：page-level first match，会点到 timeline 首条非 target card
do: click [data-testid="like"]

# ✅ 对：scoped 到 article root
do: click [data-testid="like"] in article[role="article"] (card scope)

partial ファイルの先頭に、スコープルートを 1 行で記述します。

## Card scope rule
所有 testid selector 必须 scoped 到 `article[role="article"]`，不能用 page-level first match。

---

ワークフローのフィールド

各ワークフローでは、次の項目に答える必要があります。

• Goal：このワークフローで解決する、ユーザー向けのタスク。
• State signature：スリープやコンテキスト圧縮後に再開するための、最小限の観測可能なチェックポイント。
• Best path：目標を達成できる既存の opencli <site> <command> アダプターがある場合は、それを優先します。
• Fallback path：アダプターが存在しない場合や失敗する場合に使うブラウザーワークフロー。
• Avoid：ターンを浪費する、モーダルを表示させる、または不安定なセレクターに依存する、つい選びがちな経路。
• Stale markers：最後に検証した日付、および既知のレイアウト/API の変更を示す情報。

エンドポイント/API の知識は、利用可能な場合は endpoints.json の ID を参照してください。サイトマップファイル内にエンドポイントのスキーマ全体を重複して記載しないでください。

Fallback on_adapter_fail: の規約（推奨）

Fallback path の最初の行で、発動条件と adapter_health_update ディレクティブを宣言し、「なぜ fallback に進むのか」と「adapter を suspect としてマークする」ことをまとめて示します。

on_adapter_fail:
  - adapter_health_update: opencli twitter post -> suspect
  - opencli browser state (verify current page)
  - if not on /home: goto /home
  - action:open_compose in pages/home.md
  - ...

単なる step list より明確です。利用するスキルは on_adapter_fail: キーを見て、これが entry-point fallback ではなく adapter-trigger であることを判断できます。ディレクティブを先に実行し、その後で steps に進みます。schema v1.2 の候補であり、現時点では SKILL のガイドラインとして推奨されています。

SITE.md Top-level routes — 未カバーのルートを明示

SITE.md の Top-level routes には、カバー済みのページだけでなく、存在するものの sitemap からはたどれないルートも明示的に記載してください。これにより、エージェントが「sitemap にない → 存在しない」と判断するのを防げます。

## Top-level routes

- /home → pages/home.md
- /search → pages/search.md
- /messages → pages/messages.md（DM，本 PoC v1 不覆盖）   # ← 显式 uncovered marker
- /settings → 不在 sitemap scope，agent 自探         # ← 同上

記載しないと、エージェントはそのルートの存在を知りません。記載して未カバーとマークすれば、エージェントはそのルートが存在するものの sitemap では見つけられないと理解し、自分で探索できます。

---

禁止事項

• Sitemap はヒントであり、現在のブラウザーの状態が真実です。
• シークレット、Cookie、ユーザー固有の ID、プライベートメッセージ、アカウント固有の値を記載しないでください。
• CAPTCHA、WAF、アクセス制御、レート制限、有料ゲートの回避方法を記載しないでください。
• [17] のような壊れやすいスナップショットのインデックスを、永続的なターゲットとして保存しないでください。意味のあるアンカーと復旧手順を保存してください。
• 検証していない経路を事実として説明しないでください。draft または stale のラベルを使用してください。
• Draft は親ディレクトリの ~/.opencli/sites/<site>/sitemap.draft.md ではなく、sitemap/draft-<topic>.md に配置してください。前者は opencli browser の sitemap 利用可否検出で認識されません。

---

詳細なスキーマ

フィールドごとの完全な仕様については、references/sitemap-schema.md を参照してください。SITE.md / pages/<id>.md / workflows/<id>.md / apis.md / pitfalls.md のスキーマ、アクション単位の状態シグネチャ、adapter_health の列挙値（healthy / suspect / broken）、エンドポイント参照ルール、2 層のオーバーレイのセマンティクス、Draft の配置、Phase 2 の検証ルールを説明しています。