SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsopencli-sitemap-author

opencli-sitemap-author

Agents & models

View repository

Updated 10-15 22:39

About this skill

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 (empirical heuristics)

references/sitemap-schema.md §1.1 spec hard 800 tokens, but PoC empirical testing shows simple sites with a single page and 1-2 actions naturally land at 800-2000 tokens. Forcing a split causes fragmentation instead; authors use the table below to decide:

The spec's 800 is a lazy-load optimization target + Phase 2 audit threshold; the table below is an author decision aid for real-world use,does not replace the spec hard limit. Files over 800 will be flagged by audit; the author explains ("5 cohesive UI primitives placed together") or splits.

File tokens Decision
< 1500 Natural size, leave as is
1500-3000 Look at cohesion — 5 cohesive UI primitives placed together is OK; split mixed content
> 3000 Must split sub-file or partial (agent lazy load budget really is limited)

Phase 2 cron audit counts by token count, not byte count (CJK Chinese token-per-char is 30-50% higher than English).

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 (cross-page shared UI)

partial files (_<name>.md，url_patterns: []) hold cross-page UI primitives (e.g. _tweet_card.md 's like/reply/repost/bookmark). Referenced by multiple pages via action:<id> in pages/_<name>.md .

Partial scope rule: all selectors inside a partial (testid / a11y / structural)must be scoped to the partial root, not page-level first match. For example _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)

Write the scope root as one line at the top of the partial file:

## 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 (recommended)

The first line of a fallback path declares the trigger condition + adapter_health_update directive, putting "why we take the fallback" and "mark adapter suspect" together:

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

Clearer than a plain step list: when the consumption skill sees the on_adapter_fail: key it knows this is an adapter-trigger rather than an entry-point fallback, and the directive executes first before the steps run. schema v1.2 candidate, currently recommended as a SKILL guideline.

SITE.md Top-level routes — mark uncovered routes

SITE.md 's Top-level routes should not only list covered pages, but alsoexplicitly mark routes that exist but are not navigated by the sitemap, to avoid the agent defaulting to "not listed in sitemap → doesn't exist":

## Top-level routes

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

Not writing it = the agent doesn't know the route exists; writing it + marking uncovered = the agent knows it exists but the sitemap can't help, so it explores on its own.

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.