publishport-opencli 1.0.0

package/skills/opencli-sitemap-author/references/sitemap-schema.md

@@ -0,0 +1,660 @@
+# Sitemap Schema Reference
+
+详细 schema 规范。`SKILL.md` 给的是 inline 模板，本文件 spec 化字段、约束、validation 规则、跨文件引用格式。
+
+进入条件：先读 `SKILL.md` 拿到 framing（task execution graph for agents）和两层存储模型。本文件展开**怎么写得对**。
+
+## v1.1 changelog（vs v1）
+
+12 patches，按主题分 3 组。验证基础：twitter PoC（12 files / opencli-user）+ hackernews PoC（10 files / opencli-质量官）双站。
+
+**Group 1 — Scope/boundary**（clarifications，不改 format）
+1. §1.1 双语 / CJK token-per-char 比 English 高 30-50%，必要时拆 sub-file（不放宽 800）
+2. §2.1 `auth_strategy` 取主体不取并集；例外靠 page-level `contract_strength` 区分
+3. §2.5 `pitfalls.md` 只 task-executor 级；adapter-internal 坑回 `notes.md`
+4. §2.5 pitfall id / trigger / workaround 全部 **task-executor 第一人称**视角
+5. §2.4 `apis.md` entry 加 optional `notes:` 字段（GraphQL queryId path 等 meta）
+6. §2.2 page `Linked APIs` 收集中可留空，**不要塞 fake id**
+
+**Group 2 — Reuse/compactness**（结构变化）
+7. §2.2 + §4 partial 页面语义：`page_id` 以 `_` 前缀 + `url_patterns: []`，跨页通用 UI 抽到 partial
+8. §3 action schema 加 Form B compact YAML（~80 token / action vs Form A markdown ~250）
+9. §3 drop action-level `verified_at` / `source`，继承文件 frontmatter
+
+**Group 3 — Execution health/anchors**（action-level 语义）
+10. §3.3 跨页 UI 原语 action 允许 adapter-first + DOM fallback 在单个 action 内（不强抬到 workflow 层）
+11. §3.4 Recovery 加 `adapter_health_update:` directive + skill 实现 health 写回闭环
+12. §2.2 `testid` 标 optional；`selector_pattern` 一等 anchor + 列 5 种合法形态 + 禁 `nth-child` / 单 class / 文案 selector
+
+详细内容见各 section。
+
+---
+
+## 1. 文件层约束
+
+### 1.1 大小约束（agent token budget）
+
+**每个 .md 文件 body ≤ 800 token**（不含 frontmatter）。超过必须拆。
+
+理由：agent 用 sitemap 是 lazy load 模式，只读"当前 page + 当前 workflow + 必要 pitfalls"。单文件大 → agent context 被沉默打爆，特别是 compaction 之后 re-load 时。
+
+实操：
+- 一个 page 有 > 8 个 action → 拆 `pages/<page>/index.md` + `pages/<page>/actions/<group>.md`
+- 一个 workflow 步骤多 → 拆主线 + `workflows/<task>/sub/<step>.md`
+- **双语 / CJK 内容 token-per-char 比 English 高 30-50%**：CJK 单字 ~0.7-1 token，加上术语混排实测一个 1.5KB 中文 markdown 文件就 ~1000 token。**必要时拆 sub-file 而非放宽 800 限制** — 软 target 必然漂，一年后会变 3000，lazy load 失效
+
+### 1.2 Frontmatter（每文件必填）
+
+```yaml
+---
+schema_version: 1
+last_verified: 2026-06-02       # YYYY-MM-DD
+source: local | global          # 标识所在存储层
+---
+```
+
+字段 `schema_version` 用于未来 schema 迁移（v2 引入新字段时旧文件能识别）。
+
+---
+
+## 2. 文件类型 schema
+
+### 2.1 `SITE.md`
+
+```yaml
+---
+schema_version: 1
+site: twitter.com
+last_verified: 2026-06-02
+source: global
+login_required: true
+auth_strategy: COOKIE_API   # 引用 strategy-selection.md ladder
+---
+
+## Overview
+<1-2 句站点定位，agent 看一眼就知道这是什么站>
+
+## Top-level routes
+<URL pattern → page_id 映射，只列主干>
+- / → pages/home.md
+- /<user> → pages/profile.md
+- /search → pages/search.md
+
+## Common goals
+<主要 user task → workflow 映射>
+- publish a post → workflows/publish.md
+- find user → workflows/search-user.md
+- export data → workflows/export.md
+
+## Site-wide pitfalls
+<跨页通用坑，详细见 pitfalls.md>
+- requires login for most reads
+- "Latest" tab is time-sorted; "For You" is personalized
+```
+
+**Required**: `Overview`, `Top-level routes`, `Common goals`
+**Optional**: `Site-wide pitfalls` (引用即可)
+**Frontmatter required**: `site`, `login_required`, `auth_strategy`
+
+`auth_strategy` 取值：`PUBLIC_API | COOKIE_API | PAGE_FETCH | INTERCEPT | DOM_STATE | UI_SELECTOR`，定义见 [`../../opencli-adapter-author/references/strategy-selection.md`](../../opencli-adapter-author/references/strategy-selection.md)。
+
+**取主体不取并集**：`auth_strategy` 单值，覆盖该站绝大多数请求的策略。少数例外（如 twitter 公开 profile 可裸 fetch，主体仍是 COOKIE_API）在对应 page 的 `Linked APIs` section 里逐条标 `contract_strength` 区分，不靠 frontmatter 表达。array form 加复杂度无收益。
+
+### 2.2 `pages/<page-id>.md`
+
+```yaml
+---
+schema_version: 1
+page_id: home
+url_patterns:
+  - https://twitter.com/home
+  - https://twitter.com/i/timeline
+purpose: main feed surface
+last_verified: 2026-06-02
+source: local
+---
+
+## Visual anchors
+<agent 用什么 anchor 确认"我在这页">
+- a11y: role=main, name="Home timeline"
+- text: "What's happening?" (compose prompt)
+- pattern: feed items have role=article
+- testid: [data-testid="primaryColumn"]   # optional - 新站常用，老站可省
+- selector_pattern: tr.athing + tr.subtext  # optional - structural / attribute selector，无 testid 的老站常用
+
+## Actions on this page
+<可执行 action，按 stable id 命名>
+
+### action:open_compose
+（详见下面 §3 Action schema）
+
+### action:scroll_for_more
+...
+
+## Linked APIs
+<本页面触发的 endpoint id 列表，不复制 endpoint 内容>
+- endpoint_id: timeline_v2
+  triggers_on: page load + infinite scroll
+- endpoint_id: notifications_count
+  triggers_on: page load (silent poll)
+
+## Page-specific pitfalls
+<只列本页独有坑>
+- compose dialog can be obscured by toast notifications
+```
+
+**Required**: `Visual anchors`, `Actions on this page`
+**Optional**: `Linked APIs` (建议放，引用 `apis.md` 已注册的 endpoint id), `Page-specific pitfalls`
+**Frontmatter required**: `page_id`, `url_patterns` (array), `purpose`
+
+`page_id` 必须 stable — 不依赖 URL params / locale / A/B variant。命名建议 `home / search / profile / compose / settings` 这类语义化。
+
+#### Visual anchors 类型（5 种）
+
+| 类型 | 何时用 | 例 |
+|---|---|---|
+| `a11y` | 现代站，role + name 稳定的 | `role=button name="Post"` |
+| `text` | 站点文案不漂的（少见，i18n 风险）| `"What's happening?"` |
+| `pattern` | 多元素重复模式 | `feed items have role=article` |
+| `testid` | **Optional** — 新站约定 `data-testid="..."` 的（Twitter / React 系新站常见）| `[data-testid="tweetTextarea_0"]` |
+| `selector_pattern` | **Optional, 但旧站必填**：structural / attribute selector，无 testid 时的稳定 fallback | `tr.athing[id="<id>"] + tr` |
+
+`testid` 不存在的老站（HackerNews / 论坛系 / 政府站）`selector_pattern` 是一等 anchor 类型，不视为降级。a11y + selector_pattern 组合通常比 text 更稳。
+
+`selector_pattern` 的合法形态（按稳定性降序）：
+
+| 形态 | 例 | 何时用 |
+|---|---|---|
+| **id-anchored** | `tr.athing[id="<id>"]` | 元素有 stable id（HN story / DOM-stable comment 行） |
+| **sibling traversal** | `tr.athing + tr.subtext`, `~ a.morelink` | 元素本身无 stable handle，但 sibling 关系稳定 |
+| **attribute boundary** | `a[href^="item?id="]`, `a[href*="/status/"]` | 元素靠 URL pattern 区分（HN comments link / Twitter status link） |
+| **form name** | `input[name="title"]`, `textarea[name="text"]` | 老式 form，`name` attribute 几乎不漂 |
+| **ARIA** | `[role="article"]`, `[aria-label*="..."]` | semantic 锚点，跟 `a11y` 重叠但当 a11y 不够时 selector form 仍可作 anchor |
+
+**Discouraged**（高危 anchor）：
+
+- ❌ `tr.athing:nth-child(<rank>)` — rank ↔ nth-child 在多 row 模式下不等价（HN athing + subtext 双 row 就破了）
+- ❌ 单 class 抓（`.tweet`）— 同 class 多元素时点错
+- ❌ 文案 selector（`a:contains("Post")`）— i18n / rebrand 漂
+
+这些会触发 "verify 通过但点错 element" silent failure，**禁止**作为 stable anchor。
+
+#### `Linked APIs` 可留空
+
+`Linked APIs` 引用的 `endpoint_id` 必须存在于 `apis.md`（间接也在 `endpoints.json`）。如果该站 `endpoints.json` 还在收集中（如 twitter 32+ GraphQL operation 大部分没登记），page `Linked APIs` 留空合理，**不要塞 fake id 占位**。后续 adapter-author 补 `endpoints.json` 后再回填。
+
+#### Partial 页面（跨页通用 UI）
+
+跨页通用 UI（如 tweet card 在 home / profile / status / notifications / bookmarks 都出现）抽到 partial 文件：
+
+- `page_id` 前缀 `_`（如 `_tweet_card`）标识为 partial
+- `url_patterns: []`（空数组，表示无独立 URL）
+- 其他 page 通过 `action:<id> in pages/_tweet_card.md` reference 这里的 action
+- partial 文件不算独立 page，但 schema 字段结构跟正常 page 一样
+
+避免在多 page 复制相同 action，违反 SoT；也避免 arbitrary 把跨页 UI 塞给某个具体 page "拥有"。
+
+### 2.3 `workflows/<task-id>.md`
+
+```yaml
+---
+schema_version: 1
+workflow_id: publish-post
+intent: publish a public post (text only)
+last_verified: 2026-06-02
+source: global
+---
+
+## Goal
+<user-facing 描述，agent 用来匹配 user intent>
+Create a new public post on this site with text content.
+
+## State signature
+<workflow 级 checkpoint，re-entry 时用来定位"走到哪一步了">
+- entry: any page on the site, logged in
+- success: post visible on author's timeline within 5s
+
+## Best path
+adapter: opencli twitter post
+adapter_health: healthy        # healthy | suspect | broken
+preconditions:
+  - logged_in
+  - text content ready
+estimated_turns: 1
+
+## Fallback path
+<adapter 不可用 / unhealthy 时的 browser workflow，引用 action id>
+1. From any page → navigate to /home (or use current if already on /home)
+2. Use action `open_compose` (see pages/home.md)
+3. Type text into compose textarea
+4. Use action `submit_post` (see pages/home.md)
+
+estimated_turns: 4
+
+## Avoid
+<反模式 — 哪些路径浪费 turn / 触发 modal / 用不稳定 selector>
+- Manual clicking when adapter is healthy
+- Mobile site path (/m/...) — different DOM structure
+- Right-click context menu paths — locale-dependent
+
+## Re-entry checkpoints
+<给定 browser state，agent 知道走到 workflow 哪一步>
+- on /home, compose dialog NOT visible → start from step 1
+- on /home, compose dialog visible → start from step 3
+- on /<user>/status/<id>, success indicator → done
+
+## State validation
+<完成后怎么验证真的成功>
+- timeline shows new post within 5s
+- post URL accessible
+- post text matches submitted content
+
+## Stale markers
+<known drift signals — agent 看到这些应该重新探测而不是相信本 workflow>
+- "Post" button text changed (i18n drift)
+- compose dialog moved to right sidebar (UI redesign 2026-Q3 rumor)
+```
+
+**Required**: `Goal`, `State signature`, `Best path`, `Fallback path`, `Avoid`
+**Optional but recommended**: `Re-entry checkpoints`, `State validation`, `Stale markers`
+**Frontmatter required**: `workflow_id`, `intent`
+
+`adapter_health` enum:
+- `healthy`：adapter 30 天内 verified working，无 unresolved fix issue
+- `suspect`：adapter 存在但 last_verified 老于 30 天，或最近有 fix PR 还没 merge
+- `broken`：adapter 已知 broken，必须走 Fallback path
+
+`adapter_health` 应该周期性 audit 更新（Phase 2 cron）。手写时建议保守标 `suspect`，验证过才标 `healthy`。
+
+### 2.4 `apis.md`
+
+```yaml
+---
+schema_version: 1
+last_verified: 2026-06-02
+source: local
+---
+
+## Endpoint index
+
+<endpoint_id ↔ trigger 映射，DO NOT 复制 endpoint URL/method/params/response — 那些在 `endpoints.json`>
+
+### endpoint:timeline_v2
+- triggers_on_pages: [home]
+- triggered_by_actions: [page_load, scroll_for_more]
+- contract_strength: internal-unstable
+- notes: GraphQL /i/api/graphql/{queryId}/HomeTimeline   # optional - meta 信息（queryId 路径 / 已知 schema 变化）
+
+### endpoint:search_typeahead
+- triggers_on_pages: [search]
+- triggered_by_actions: [search_input_keystroke]
+- contract_strength: internal-unstable
+
+### endpoint:post_create
+- triggers_on_pages: [home, compose]
+- triggered_by_actions: [submit_post]
+- contract_strength: internal-unstable
+```
+
+**Required per entry**:
+- `endpoint_id` — 必须存在于同站 `~/.opencli/sites/<site>/endpoints.json`
+- `triggers_on_pages` — array of `page_id`
+- `triggered_by_actions` — array of `action:<stable-id>`
+- `contract_strength` — `stable | visible-ui | internal-unstable`，定义见 `strategy-selection.md`
+
+**Optional per entry**:
+- `notes` — meta 信息（GraphQL queryId path、已知 schema 变化、特殊 auth 头）。**不要**复制 endpoint URL / method / params / response shape — 那些只在 `endpoints.json`
+
+**Forbidden**:
+- Endpoint URL / method / params / response shape（这些只在 `endpoints.json` 单一来源）
+- Auth detail（同上）
+
+理由：sitemap 是 navigation layer，endpoints.json 是 API layer。两层各自演进，避免双 stale。
+
+### 2.5 `pitfalls.md`
+
+```yaml
+---
+schema_version: 1
+last_verified: 2026-06-02
+source: local
+---
+
+## Site-specific pitfalls
+
+### pitfall:login_wall_on_search
+trigger: searching without logged-in session
+symptom: redirected to /login
+workaround: check session before navigating to /search
+verified_at: 2026-06-02
+
+### pitfall:infinite_scroll_throttle
+trigger: rapid scroll triggers > 5 timeline_v2 fetches
+symptom: rate_limit_429 response
+workaround: wait 2s between scrolls; or use cursor-based pagination
+verified_at: 2026-05-15
+
+### pitfall:locale_button_drift
+trigger: site locale is non-English
+symptom: hardcoded "Post" / "Submit" text selectors fail
+workaround: use a11y role + aria-label instead of visible text
+verified_at: 2026-06-01
+```
+
+**Required per entry**:
+- `pitfall_id` — stable id, **第一人称 task-executor 视角**（"agent 调命令时会撞到" 视角，不是 "实现 adapter 的人会撞到" 视角）
+- `trigger` — what causes this，从 task-executor 视角描述（"agent 想做 X 时" 而非 "adapter 实现里有 Y bug"）
+- `symptom` — how agent observes the failure
+- `workaround` — what to do instead，task-executor 可执行（不是 "修 adapter"）
+- `verified_at` — when last seen
+
+#### Scope（避免 sitemap 变杂物间）
+
+`pitfalls.md` 只放 **task-executor 级**坑 — 跑命令 / 操作页面会撞到的坑。**adapter-internal 实现坑**（queryId 解析 / envelope unwrap / bigint id / 字段 silent rename）放在 `~/.opencli/sites/<site>/notes.md`，不进 sitemap。
+
+判断标准：
+
+| 坑的修复者是谁 | 落地 |
+|---|---|
+| 跑命令的 agent（标 `adapter_health=suspect` / 切 Fallback path / 等 cooldown） | `pitfalls.md`（task-executor 级） |
+| 写 adapter 的 agent（改解析逻辑 / 升级 queryId / 改字段路径） | `notes.md`（adapter-internal） |
+
+反例（**不要**写进 pitfalls.md）：
+
+```md
+### pitfall:queryid_rotation_breaks_adapter        # ❌ adapter-internal naming
+- trigger: adapter 调 cookie-API endpoint，queryId 已 rotation   # ❌ adapter 视角
+- workaround: adapter 升级 queryId path                          # ❌ task-executor 做不了
+```
+
+正例：
+
+```md
+### pitfall:adapter_returns_empty_after_api_drift   # ✅ task-executor naming
+- trigger: Best path adapter 返回 typed error 或空 result        # ✅ agent 视角
+- workaround: 标 workflow adapter_health=suspect 走 Fallback path # ✅ task-executor 可执行
+```
+
+---
+
+## 3. Action Schema（pages 内）
+
+每个 page 的 actions section 包含若干 action 节点。**两种合法 form**，作者按需选：
+
+#### Form A: Markdown 详尽（适合复杂 action / 第一次编写）
+
+```md
+### action:<stable-id>
+
+Preconditions:
+- <current page / state / auth requirements>
+
+Do:
+- <agent action — preferably semantic browser command or existing adapter>
+
+Postconditions:
+- <URL / state / output that proves success>
+
+Failure signals:
+- <how agent detects this edge no longer works>
+
+Recovery:
+- <fallback action / re-state / re-find instruction>
+- adapter_health_update: <adapter command> -> suspect    # OPTIONAL — see §3.3
+
+State signature:                          # OPTIONAL — for multi-step internal recovery
+  url_pattern: <regex or exact match>
+  dom_anchor: <a11y role+name OR semantic selector>
+
+Evidence:
+- observed_with: opencli browser <session> <command>
+- trace: <path to trace artifact, optional>
+```
+
+#### Form B: Compact YAML（首选，~80 token / action vs Markdown ~250）
+
+```yaml
+### action:<stable-id>
+pre: <current page / state / auth requirements>
+do: <agent action, adapter or semantic browser command>
+post: <URL / state / output that proves success>
+fail: <failure signal 1> | <signal 2> | <signal 3>
+recover: <fallback instruction>; adapter_health_update: <adapter> -> suspect
+evidence: opencli browser <cmd>
+```
+
+字段分隔符约定（避免 ambiguity）：
+
+| 符号 | 用途 | 例 |
+|---|---|---|
+| `\|` | 多 failure signal 平级枚举（"任一发生即视为失败"）| `fail: button_not_found \| /flow/login redirect` |
+| `\|\|` | 多 do path / recovery path **fallback priority**（"前者失败试后者"）| `do: opencli twitter like <url> \|\| click [data-testid="like"]` |
+| `;` | 多 recovery 指令 **sequential**（"逐条执行"）| `recover: adapter_health_update: opencli twitter like -> suspect; dom_click within card scope` |
+
+字段语义完全等价 Form A，**推荐 Form B**，密集站避免 verbose markdown 把 page 撑爆。
+
+#### `verified_at` 由文件级 frontmatter `last_verified` 继承
+
+**Form A / B 都不写 action-level `verified_at`** — 文件 frontmatter `last_verified` 已经覆盖该文件所有 action 的最新验证日期。重复写既是冗余又是 drift 源（10 个 action 各自 `verified_at: 2026-06-02` 改时容易漏 1-2 个）。
+
+`source: local | global` 也不在 action 内重复 — 文件位置已隐含。Form A 旧 `Evidence` block 简化为 `observed_with` + optional `trace`，丢 `verified_at` / `source`。
+
+### 3.1 字段说明
+
+**Preconditions**：列出 action 可执行的前置。
+- 一般是 page state（"on /home"）+ auth state（"logged_in"）+ UI state（"compose dialog not yet open"）
+
+**Do**：实际操作。优先级：
+1. 已有 adapter 命令（`opencli twitter post`）
+2. semantic browser command（`opencli browser click "Post" button`）
+3. 显式 selector（最后选项，写 stable anchor 不是裸 CSS）
+
+**Postconditions**：成功观察信号。必须具体 — "page changed" 不算，"URL is /compose AND textarea is focused" 才算。
+
+**Failure signals**：哪些观察等同"action 失败 / sitemap 漂"。
+- `login_wall_appears`
+- `upgrade_modal_opens_instead`
+- `button_not_found`
+- `URL_does_not_change_within_3s`
+
+**Recovery**：失败时该做什么。
+- 链到 fallback path（"use action `mobile_compose` from pages/mobile-home.md"）
+- 或回 探测模式（"re-run `find` for 'Post' button with a11y role=button"）
+- 可含 `adapter_health_update:` directive（见 §3.3）
+
+**State signature**（OPTIONAL）：用于 action **内部多步骤**的 mid-flight re-entry。
+- 简单 action（单 click）不需要
+- 复杂 action（"submit form" 包含 type + click + wait）建议加，agent 中断恢复时知道走到哪
+- 跟 workflow 级 state signature 区分：workflow signature 是 "走到 workflow 第几步"，action signature 是 "action 内部第几步"
+
+**Evidence**：trust gate — 没 evidence 的 action 不能 promote 到 global。
+- `observed_with`：当时跑的命令（用于复现）
+- `trace`：optional，对复杂 action 建议附 trace artifact 路径
+- `verified_at` 不写在 action 里 — 继承文件 frontmatter `last_verified`
+- `source` 不写在 action 里 — 文件位置已隐含
+
+### 3.2 Action id 命名约定
+
+- 动词 + 名词：`open_compose / submit_post / scroll_for_more / dismiss_modal`
+- 不要 page-prefix：action 默认作用域是它所在的 page，不要写 `home_open_compose`
+- stable：跨 URL params / locale / A/B variant 都应稳定
+
+### 3.3 Action-level adapter-first 模式（跨页 UI 原语）
+
+对**跨页 UI 原语 action**（一般在 partial 里，如 `_tweet_card.md` 的 `like_tweet / repost_tweet / bookmark_tweet`），允许 `Do` 字段写 adapter-first + DOM fallback 二选一，**无需借 workflow 层 Best/Fallback 抬出去**：
+
+```yaml
+### action:like_tweet
+pre: card visible AND (tweet_url known OR card permalink anchor extractable)
+do: opencli twitter like <tweet-url> || click [data-testid="like"] (within card scope)
+post: testid 翻转 like -> unlike，icon 红色
+fail: testid 不变 | 弹 login modal
+recover: adapter_health_update: opencli twitter like -> suspect; dom_click within card scope
+evidence: opencli twitter like + opencli browser click
+```
+
+两层 routing 不冲突：
+
+- **workflow 层** `Best path / Fallback path` 处理"task 级别"（发推 vs 浏览 vs 搜索）
+- **action 层** adapter-first 处理"UI 原语级别"（点 like 按钮）
+
+不要为了 schema 纯粹性把 `like_tweet` 这种**单原子点击但 adapter 比 DOM 稳**的 action 强行抬到 workflow 层 — 那会让"喜欢一条推文"变成一个独立 workflow，跟实际 task 颗粒度脱节。
+
+### 3.4 `adapter_health_update` directive
+
+action `Recovery` 字段可包含 directive：
+
+```
+adapter_health_update: <adapter command> -> suspect | broken
+```
+
+语义：当**本 action 因为该 adapter 失败而触发 Recovery**时，consumption skill（`opencli-browser-sitemap`）必须：
+
+1. 在 local overlay 找到 reference 该 adapter 的 workflow（一般是 `Best path: adapter: <adapter command>` 的那条）
+2. 改写 workflow 的 `adapter_health` 为 directive 指定的等级
+3. **下个 agent** 读 workflow 看到 `adapter_health=suspect` → 直接走 Fallback path，不再盲 retry adapter
+
+这是 action 失败的**写侧闭环** — agent 失败后回写健康状态，避免下个 agent 重栽。
+
+不写 directive 时，Recovery 只指导当前 agent 怎么 fallback，不影响其他 agent。带 directive = "我栽了，让我把这事告诉以后的 agent"。
+
+**实现责任**：在 `opencli-browser-sitemap` skill 的 consumption loop 里。Schema 这里只 spec directive 写侧格式，不 spec 实现细节。
+
+**Recovery 回 `healthy` 不在本 schema 范围**：`adapter_health` 从 `suspect` 回 `healthy` 的路径（TTL 自动衰减 / 跑 Fallback 成功后 probe Best path / 人工 reset）留给 `opencli-browser-sitemap` skill spec 拍。本 PR 只定写侧（"failed → suspect"），不定读侧（"suspect → healthy"）的恢复策略。
+
+---
+
+## 4. 跨文件引用
+
+sitemap 内部多文件互相引用。引用格式：
+
+| 引用 | 格式 | 示例 |
+|---|---|---|
+| 引用 page | `pages/<page-id>.md` | `see pages/home.md` |
+| 引用 workflow | `workflows/<task-id>.md` | `see workflows/publish-post.md` |
+| 引用 action | `action:<stable-id> in pages/<page>.md` | `use action open_compose in pages/home.md` |
+| 引用 partial action | `action:<stable-id> in pages/_<partial>.md` | `use action like_tweet in pages/_tweet_card.md` |
+| 引用 endpoint | `endpoint:<endpoint-id> in apis.md` | `triggers endpoint:timeline_v2` |
+| 引用 pitfall | `pitfall:<pitfall-id> in pitfalls.md` | `see pitfall:login_wall_on_search` |
+| 引用 endpoints.json | endpoint_id 直接出现，假定 `endpoints.json` 有同 id | `endpoint_id: timeline_v2` |
+
+**ID 唯一性**：
+- `page_id` / `workflow_id` / `pitfall_id` 在站点内全 sitemap 唯一
+- `action:<id>` 在所在 page 内唯一（不同 page 可以重名）
+- `endpoint_id` 跟 `endpoints.json` 同 id
+
+---
+
+## 5. Two-layer storage 行为 spec
+
+| 维度 | 行为 |
+|---|---|
+| Read order | local overlay 优先 → fallback global seed |
+| Conflict | 同 stable id 存在两层时，local 赢（用户的现实更权威）|
+| Promotion | local 累积 → 显式 PR → 进 global |
+| Demotion | 不存在 — global 永远不删除 entry，只标 stale |
+| 文件 missing | 任一层 missing 该文件，自动 fallback 另一层；都 missing → 该 page/workflow 视为不存在 |
+
+**Stable IDs 跨层匹配**：local 文件 `page_id: home` 跟 global 文件 `page_id: home` 是同一个，local 字段覆盖 global 字段。
+
+### 5.1 Draft 放在 `sitemap/` 目录内
+
+agent 发现新路径 / stale 修正 / 半成品流程时写 draft。**draft 必须放在 `sitemap/` 目录内**，命名为 `sitemap/draft-<topic>.md` 或 `sitemap/pages/<page>.draft.md`。
+
+**❌ 不要**放在父目录（如 `~/.opencli/sites/<site>/sitemap.draft.md`） — `opencli browser open` 的 sitemap availability 检测只看 `sitemap/` 目录是否存在。draft 放父目录 → 检测不到 → agent 不会被提醒"有 sitemap" → 你的发现没人用。
+
+正确：
+```
+~/.opencli/sites/twitter/sitemap/
+├── SITE.md
+├── pages/home.md
+└── draft-search-filter.md       ← OK，会被检测到
+```
+
+错误：
+```
+~/.opencli/sites/twitter/
+├── sitemap.draft.md             ← 检测不到，不会触发 availability
+└── sitemap/                     ← 空 dir → 检测到但内容空
+    └── (empty)
+```
+
+### 5.2 `site-alias.json`（optional, Phase 2）
+
+`opencli browser open` 用 adapter registry 把 hostname → site 映射（如 `news.ycombinator.com → hackernews`）。如果 sitemap 先于 adapter 存在（即一个站还没人写 adapter 但有人写了 sitemap），registry 没数据，sitemap dir 检测不到。
+
+future fix：sitemap dir 内放 `site-alias.json` 声明它服务的 hostname：
+
+```json
+{
+  "hostnames": ["news.ycombinator.com", "hn.com"]
+}
+```
+
+`resolveSitemapAvailabilityForUrl` 先看 alias → 再 fallback adapter registry → 再 fallback hostname-second-part heuristic。Phase 2 加，v1 PoC 用 adapter registry 已够。
+
+---
+
+## 6. Trust Reality 红线
+
+sitemap 是 hint，browser state 是 truth。当冲突时：
+
+1. **绝不**强迫 agent 按 sitemap 操作
+2. agent 必须现场探测（用 `browser state` / `find`）
+3. 把 sitemap 项标 stale：在 local overlay 加一条覆盖（同 stable id），把 `last_verified` 倒回 30 天前，或加 `stale: true` 字段
+4. 把现实观察 dump 到 local overlay 的 `<file>.draft.md`
+
+**反模式**：
+- ❌ "sitemap 说有 Post 按钮，找不到就再找"
+- ❌ 把 sitemap workflow 当 fixed plan，遇到 diverge 不回 probe
+- ❌ silent-ignore mismatch 继续按 sitemap 操作
+
+正确：
+- ✅ "sitemap 说有 Post 按钮 → `find` 一下 → 不在 → 标 stale + 探测真实页面有没有别的发帖入口"
+
+---
+
+## 7. Validation rules（Phase 2 cron audit 用）
+
+未来自动化 audit agent 可按这些规则检查 sitemap 健康：
+
+### 7.1 File-level
+
+- `body ≤ 800 token`（每个 .md 单独检查）
+- `last_verified` 不老于 30 天 → 否则 flag `stale_age`
+- `schema_version` 字段存在且 ≤ current
+
+### 7.2 Cross-ref integrity
+
+- workflow `Best path: adapter X` → adapter X 必须存在于 `cli-manifest.json`
+- workflow `Fallback path` 引用的 `action:<id>` → 必须存在于对应 page
+- page `Linked APIs` 的 `endpoint_id` → 必须存在于 `apis.md`
+- `apis.md` 的 `endpoint_id` → 必须存在于同站 `endpoints.json`
+
+### 7.3 Reality check
+
+- action `Postconditions` 里的 `url_pattern` / `dom_anchor` → 用 `opencli browser` 实跑一遍，验证 anchor 仍可 resolve
+- workflow `State signature.url_pattern` → 同上
+
+失败 → 自动倒 `last_verified` 30 天前。
+
+### 7.4 Forbidden content
+
+- `apis.md` 不能含 endpoint URL / method / params / response（grep 检测）
+- 任何文件不能含 secret pattern（cookie value / token string / API key — 用 regex 检测）
+
+---
+
+## 8. Cross-link
+
+- [`../../opencli-adapter-author/references/strategy-selection.md`](../../opencli-adapter-author/references/strategy-selection.md) — `contract_strength` 和 `auth_strategy` 取值定义
+- [`../../opencli-adapter-author/references/api-discovery.md`](../../opencli-adapter-author/references/api-discovery.md) — `endpoint_id` 怎么发现
+- `~/.opencli/sites/<site>/endpoints.json` — endpoint 的真实 URL/method/params/response
+
+---
+
+## 9. Open questions（v1 暂未定，v2 跟数据决）
+
+1. **`state_signature` 用什么 DSL**：现在写 `url_pattern: <regex>` + `dom_anchor: <semantic>`，未来可能需要更结构化（如 JSON path / xpath / a11y tree path）。等 PoC 实践后定
+2. **多语言站 anchor**：现在建议 a11y role + name；不同 locale name 不同。是否一个 anchor 列表多 locale，还是一个 sitemap per locale？PoC 后决
+3. **Validation cron 实现位置**：作为 OpenCLI 内置命令 `opencli sitemap audit`？还是独立 GitHub Action？Phase 2 决