Back to Details

opencli-sitemap-author

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
你正在编写一份面向Agent的任务执行图谱，而非SEO站点地图。该成果应帮助使用
opencli browser
的Agent判断当前位置、下一步路径、优先选择的OpenCLI Adapter，以及当页面与记忆不符时如何恢复。
请保持站点地图精简且经过验证。不要爬取整个站点，仅记录你实际观察到的与任务相关的路径。

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:
text
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
两层结构：
  • 全局种子：
    sitemaps/<site>/
    （顶层目录）
  • 本地覆盖层：
    ~/.opencli/sites/<site>/sitemap/
本地覆盖层通过稳定ID优先级更高。新发现的内容先写入本地，仅在审核后同步到全局。
推荐目录结构：
text
sitemap/
  SITE.md                 # 站点用途、认证假设、稳定页面ID
  pages/<page-id>.md      # 页面状态签名、操作、关联API
  pages/_<partial>.md     # 跨页UI片段（例如 _tweet_card.md）
  workflows/<task-id>.md  # 最优路径、降级路径、避坑列表
  pitfalls.md             # 常见失败模式及过时区域

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 一起放"）或拆。
文件 token决策
< 1500自然 size，不动
1500-3000看 cohesion — 5 个 cohesive UI primitive 一起放 OK；mixed 内容拆
> 3000必拆 sub-file 或 partial（agent lazy load budget 真有限制）
Phase 2 cron audit 按 token count 不按 byte count（CJK 中文 token-per-char 比 English 高 30-50%）。
references/sitemap-schema.md
§1.1 规范硬性限制为800 token，但PoC实测简单站点单页面1-2个操作的内容自然落在800-2000 token区间。强行拆分反而会碎片化内容，作者可参考下表决策：
规范中的800 token是懒加载优化目标+第二阶段审核阈值；下表为作者实战决策辅助，不替代规范的硬性限制。超过800 token的文件会在审核中被标记，作者需解释（如“5个关联的UI原语放在一起”）或拆分。
文件token数决策
< 1500保持自然篇幅，无需调整
1500-3000看内容关联性——5个关联的UI原语放在一起没问题；混合内容则拆分
> 3000必须拆分为子文件或片段（Agent的懒加载预算确实有限制）
第二阶段定时审核按token数而非字节数计算（CJK中文的字符-token比英文高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.
  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. 冲突时标记为过时：若现有站点地图与当前浏览器状态不符，请信任浏览器状态并将该条目标记为过时，而非强制沿用旧路径。

Required Action Schema

必填操作Schema

Every action edge must include:
yaml
undefined
每个操作边必须包含：
yaml
undefined

action:<stable-id>

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.
pre: <当前页面/状态/认证要求> do: <Agent操作、Adapter命令或语义化浏览器命令> post: <证明成功的URL/状态/输出> fail: <失败信号1> | <信号2> recover: <降级指令>; adapter_health_update: <adapter> -> suspect evidence: opencli browser <cmd> or trace:<path>

默认使用这种紧凑格式。仅当操作确实需要长篇解释时，才使用`references/sitemap-schema.md`中的长Markdown格式。`verified_at`和`source`从文件前置元数据继承，无需在每个操作中重复。

没有证据的操作请勿同步到全局。如果降级路径标记了`adapter_health_update`，浏览器-站点地图的使用者必须将该健康更新写入本地覆盖层，以便下一个Agent不会重试已知存在问题的Adapter。

Partial pages（跨页通用 UI）

页面片段（跨页通用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
:
yaml
undefined
片段文件（
_<name>.md
，
url_patterns: []
）用于存放跨页UI原语（例如
_tweet_card.md
中的点赞/回复/转发/收藏）。可被多个页面通过
action:<id> in pages/_<name>.md
引用。
片段范围规则：片段内所有选择器（testid/无障碍标识/结构选择器）必须限定在片段根节点范围内，不能是页面级的首个匹配项。例如
_tweet_card.md
:
yaml
undefined

❌ 错：page-level first match，会点到 timeline 首条非 target card

❌ 错误：页面级首个匹配项，会点击时间线中第一条非目标卡片

do: click [data-testid="like"]
do: click [data-testid="like"]

✅ 对：scoped 到 article root

✅ 正确：限定在article根节点范围内

do: click [data-testid="like"] in article[role="article"] (card scope)

partial 文件顶部写明 scope root 一行：

```md
do: click [data-testid="like"] in article[role="article"] (card scope)

片段文件顶部需写明一行范围根节点说明：

```md

Card scope rule

卡片范围规则

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

---
所有testid选择器必须限定在
article[role="article"]
范围内，不能使用页面级首个匹配项。

---

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.
每个工作流应包含以下内容：
  • 目标：该工作流解决的面向用户的任务。
  • 状态签名：休眠/压缩后恢复所需的最小可观察检查点。
  • 最优路径：若现有
    opencli <site> <command>
    Adapter能覆盖该目标，则优先使用。
  • 降级路径：当Adapter缺失或故障时的浏览器工作流。
  • 避坑项：诱人但浪费步骤、触发弹窗或依赖不稳定选择器的路径。
  • 过时标记：最后验证日期及已知的布局/API变更信号。
端点/API知识应在可用时引用
endpoints.json
中的ID。请勿在站点地图文件中重复完整的端点Schema。

Fallback 
on_adapter_fail:
convention（推荐）

推荐降级
on_adapter_fail:
约定

Fallback path 第一行声明触发条件 + adapter_health_update directive，把"为什么走 fallback"和"标 adapter suspect"放一起：
yaml
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 推荐。
降级路径第一行需声明触发条件+adapter_health_update指令，将“为何走降级路径”和“标记Adapter为可疑”放在一起：
yaml
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
  - ...
比纯步骤列表更清晰：消费型skill看到
on_adapter_fail:
关键字就知道这是Adapter触发的降级而非入口级降级，指令会先执行，之后才走步骤流程。这是schema v1.2候选方案，目前作为SKILL指南推荐使用。

SITE.md 
Top-level routes
— 标 uncovered routes

SITE.md 
顶层路由
— 标记未覆盖路由

SITE.md
的 
Top-level routes
不仅列已覆盖的 page，也应显式标存在但 sitemap 不导航的 route，避免 agent 默认"sitemap 没列 → 不存在"：
md
undefined
SITE.md
中的
顶层路由
不仅要列出已覆盖的页面，还应显式标记存在但站点地图不导航的路由，避免Agent默认“站点地图未列出→不存在”：
md
undefined

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 帮不上忙，自己探。

---
  • /home → pages/home.md
  • /search → pages/search.md
  • /messages → pages/messages.md（私信，本PoC v1不覆盖） # ← 显式未覆盖标记
  • /settings → 不在站点地图范围内，Agent自行探索 # ← 同上

不写=Agent不知道该路由存在；写+标记未覆盖=Agent知道存在但站点地图无法提供帮助，需自行探索。

---

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.
  • 站点地图仅为参考；当前浏览器状态才是事实依据。
  • 请勿写入密钥、Cookie、用户私有ID、私人消息或账户特定值。
  • 请勿记录绕过CAPTCHA、WAF、访问控制、速率限制或付费墙的方法。
  • 请勿将
    [17]
    这类脆弱的快照索引作为持久化目标。请存储语义锚点和恢复指令。
  • 请勿将未验证的路径描述为事实。使用
    draft
    或
    stale
    标签标记。
  • 草稿需放在
    sitemap/draft-<topic>.md
    中，而非父级目录的
    ~/.opencli/sites/<site>/sitemap.draft.md
    ——后者会被
    opencli browser
    的站点地图可用性检测忽略。

Detailed schema

详细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.
完整的字段级规范请查看
references/sitemap-schema.md
——包含
SITE.md
/
pages/<id>.md
/
workflows/<id>.md
/
apis.md
/
pitfalls.md
的Schema、操作级状态签名、
adapter_health
枚举（healthy/suspect/broken）、端点引用规则、两层覆盖语义、草稿存放位置及第二阶段验证规则。