neversight/learn-skills.dev/opencli-sitemap-author

opencli-sitemap-author

You are authoring a task execution graph for agents, not an SEO sitemap. The artifact should help an agent using opencli browser decide where it is, what path to take next, which OpenCLI adapter to prefer, and how to recover when the page disagrees with memory.

Keep the sitemap small and verified. Do not crawl a whole site. Capture only task-relevant paths that you actually observed.

Storage Model

Two layers:

• Global seed: sitemaps/<site>/ (top-level)
• Local overlay: ~/.opencli/sites/<site>/sitemap/

Local overlay wins by stable id. Write new discoveries to local first. Promote to global only after review.

Recommended layout:

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

Size guidance（实测启发式）

references/sitemap-schema.md §1.1 spec 硬 800 token，但 PoC 实测简单站单 page 1-2 action 自然落到 800-2000 token。强拆反碎，author 用下表决策：

spec 800 是 lazy-load 优化目标 + Phase 2 audit 阈值；下表是 author 实战决策辅助，不替代 spec hard 限制。超 800 的文件 audit 会 flag，author 解释（"5 个 cohesive UI primitive 一起放"）或拆。

Phase 2 cron audit 按 token count 不按 byte count（CJK 中文 token-per-char 比 English 高 30-50%）。

Authoring Loop

1. Load existing memory: read local overlay first, then global seed if present.
2. Verify reality: use opencli browser <session> state, find, network, and analyze; browser state is truth. If you just completed an opencli-adapter-author session for this site, start from the retained browse trace under ~/.opencli/sites/<site>/traces/ as seed evidence instead of re-discovering the path from zero.
3. Record only durable structure: page purpose, stable anchors, state signature, actions, workflows, API references, pitfalls.
4. Use stable ids: page/action/workflow ids should survive URL params, locale text drift, and minor layout changes.
5. Write local draft: update ~/.opencli/sites/<site>/sitemap/... unless explicitly promoting to repo.
6. Mark stale on conflict: if existing sitemap disagrees with current browser state, trust browser state and mark the item stale rather than forcing the old path.

Required Action Schema

Every action edge must include:

### 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>

Use this compact form by default. Use the longer Markdown form from references/sitemap-schema.md only when an action genuinely needs long explanation. verified_at and source are inherited from file frontmatter; do not repeat them per action.

Do not promote an action without evidence. If a recovery path marks adapter_health_update, the browser-sitemap consumer must write that health update to the local overlay so the next agent does not retry a known-suspect adapter.

Partial pages（跨页通用 UI）

partial 文件 (_<name>.md，url_patterns: []) 装跨页 UI 原语（如 _tweet_card.md 的 like/reply/repost/bookmark）。被多 page 通过 action:<id> in pages/_<name>.md 引用。

Partial scope rule：partial 内所有 selector（testid / a11y / structural）必须 scoped 到 partial root，不能是 page-level first match。例如 _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 文件顶部写明 scope root 一行：

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

Workflow Fields

Each workflow should answer:

• Goal: user-facing task this workflow solves.
• State signature: minimal observable checkpoint for resume after sleep/compaction.
• Best path: prefer existing opencli <site> <command> adapter if it covers the goal.
• Fallback path: browser workflow if the adapter is missing or failing.
• Avoid: tempting paths that waste turns, trigger modals, or rely on unstable selectors.
• Stale markers: last verified date and known layout/API drift signals.

Endpoint/API knowledge should reference ids from endpoints.json when available. Do not duplicate full endpoint schemas inside sitemap files.

Fallback on_adapter_fail: convention（推荐）

Fallback path 第一行声明触发条件 + adapter_health_update directive，把"为什么走 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 清晰：consumption skill 看到 on_adapter_fail: key 知道这是 adapter-trigger 而非 entry-point fallback，directive 先执行后续才走 steps。schema v1.2 candidate，目前作为 SKILL guideline 推荐。

SITE.md Top-level routes — 标 uncovered routes

SITE.md 的 Top-level routes 不仅列已覆盖的 page，也应显式标存在但 sitemap 不导航的 route，避免 agent 默认"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 自探         # ← 同上

不写 = agent 不知该 route 存在；写 + 标 uncovered = agent 知道存在但 sitemap 帮不上忙，自己探。

Red Lines

• Sitemap is a hint; current browser state is truth.
• Do not write secrets, cookies, user-private ids, private messages, or account-specific values.
• Do not document bypasses for CAPTCHA, WAF, access control, rate limits, or paid gates.
• Do not store brittle snapshot indices like [17] as durable targets. Store semantic anchors and recovery instructions.
• Do not describe unverified paths as facts. Use draft or stale labels.
• Drafts go inside sitemap/draft-<topic>.md, not ~/.opencli/sites/<site>/sitemap.draft.md at the parent level — the latter is invisible to opencli browser sitemap availability detection.

Detailed schema

See `references/sitemap-schema.md` for the full field-level spec — SITE.md / pages/<id>.md / workflows/<id>.md / apis.md / pitfalls.md schemas, action-level state signatures, adapter_health enum (healthy / suspect / broken), endpoint reference rules, two-layer overlay semantics, draft placement, and Phase 2 validation rules.