opencli-sitemap-author

opencli-sitemap-author

你正在编写的是 面向 Agent 的任务执行图，而不是 SEO 站点地图。该产物应帮助使用 opencli browser 的 Agent 判断当前所在位置、接下来应走哪条路径、优先使用哪个 OpenCLI 适配器，以及页面与记忆不一致时如何恢复。

保持站点地图精简且经过验证。不要爬取整个站点。只记录你实际观察到的、与任务相关的路径。

---

存储模型

两层结构：

• 全局种子：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 token，但 PoC 实测中，简单站点的单个页面 1-2 个操作通常自然落在 800-2000 token。强行拆分会导致碎片化，因此 author 可按下表决策：

规范中的 800 既是 lazy-load 优化目标，也是 Phase 2 审计阈值；下表是 author 的实战决策辅助，不替代规范的硬性限制。超过 800 的文件会被审计标记，author 需要说明理由（例如"5 个内聚的 UI 原语放在一起"）或进行拆分。

文件 token	决策
< 1500	自然体积，不做调整
1500-3000	视内聚性而定：5 个内聚的 UI 原语放在一起可以接受；内容混杂则拆分
> 3000	必须拆分为子文件或局部文件（Agent 的 lazy load 预算确实有限）

Phase 2 的定时审计按 token 数量计算，而不是按字节数计算（中文的单字 token 数比英文高 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. 冲突时标记过期：如果已有站点地图与当前浏览器状态不一致，以浏览器状态为准，并将该条目标记为过期，而不是强行沿用旧路径。

---

必需的操作 Schema

每条操作边都必须包含：

### 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，浏览器站点地图的消费端必须将该健康状态更新写入本地覆盖层，以免下一个 Agent 重试已知存在问题的适配器。

局部文件（跨页通用 UI）

局部文件（_<name>.md，url_patterns: []）用于存放跨页面的 UI 原语，例如 _tweet_card.md 中的点赞、回复、转发、收藏。多个页面通过 action:<id> in pages/_<name>.md 引用它。

局部作用域规则：局部文件内的所有选择器（testid / a11y / 结构类）必须限定在局部文件的根节点范围内，不能使用页面级的第一个匹配项。例如 _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)

局部文件顶部需用一行写明作用域根节点：

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

---

工作流字段

每个工作流都应回答以下问题：

• 目标：该工作流解决的、面向用户的任务。
• 状态签名：用于在休眠或上下文压缩后恢复的最小可观察检查点。
• 最佳路径：如果已有 opencli <site> <command> 适配器能覆盖该目标，优先使用它。
• 回退路径：当适配器缺失或失败时使用的浏览器工作流。
• 规避项：那些会浪费轮次、触发弹窗或依赖不稳定选择器的诱人路径。
• 过期标记：最近一次验证的日期，以及已知的布局或 API 漂移信号。

如果存在 endpoints.json，端点或 API 相关知识应引用其中的 id。不要在站点地图文件中重复完整的端点 Schema。

Fallback on_adapter_fail: 约定（推荐）

Fallback 路径的第一行声明触发条件和 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
  - ...

这比纯步骤列表更清晰。消费方 skill 看到 on_adapter_fail: 键，就知道这是 adapter 触发的 fallback，而不是入口级 fallback。指令先执行，之后再走步骤。这是 schema v1.2 的候选方案，目前作为 SKILL 指南推荐使用。

SITE.md Top-level routes — 标注未覆盖的路由

SITE.md 的 Top-level routes 不仅要列出已覆盖的页面，还应显式标注存在但 sitemap 不做导航的路由，避免 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 不知道该路由存在；写上并标注 uncovered，Agent 就知道它存在，只是 sitemap 帮不上忙，需要自行探索。

---

Red Lines

• Sitemap 仅作提示；当前浏览器状态才是事实依据。
• 不要写入密钥、Cookie、用户私有 ID、私信或账户相关的具体值。
• 不要记录针对 CAPTCHA、WAF、访问控制、速率限制或付费墙的绕过方法。
• 不要把脆弱的快照索引（如 [17]）当作持久目标。应存储语义锚点和恢复说明。
• 不要把未验证的路径描述为事实。请使用 draft 或 stale 标签。
• 草稿应放在 sitemap/draft-<topic>.md 中，而不是上级目录的 ~/.opencli/sites/<site>/sitemap.draft.md。后者对 opencli browser 的 sitemap 可用性检测不可见。

---

Detailed schema

完整的字段级规范见 references/sitemap-schema.md，包括 SITE.md / pages/<id>.md / workflows/<id>.md / apis.md / pitfalls.md 的 schema、动作级状态签名、adapter_health 枚举（healthy / suspect / broken）、端点引用规则、两层 overlay 语义、草稿放置位置以及 Phase 2 校验规则。