用途
opencli-browser-sitemap 用于在通过 opencli 浏览器驱动网站时，借助站点 sitemap 上下文避免盲目导航。当 opencli browser open 或 opencli browser analyze 报告 sitemap.available: true，或用户要求使用某站点的 sitemap 时，应使用本技能。
核心原则：sitemap 是先验知识，不是绝对事实。它应减少盲目点击，但绝不能覆盖实时浏览器状态。
主要能力
- 提供 sitemap 消费循环，指导代理按需读取最小相关文件。
- 定义查找顺序：先读本地覆盖层，再读全局种子。
- 支持适配器优先路径与浏览器回退路径的切换。
- 提供“信任现实”规则，处理 sitemap 与实际页面不一致的情况。
- 支持过期/草稿笔记的本地记录。
- 支持适配器健康状态回写，形成记忆循环。
使用方式
消费循环
- 运行或复用 opencli browser <session> state 以了解当前页面。
- 只读取最小相关 sitemap 文件：
- SITE.md 用于站点级定位。
- 一个匹配的 pages/<page-id>.md 用于当前状态。
- 一个匹配的 workflows/<task-id>.md 用于用户目标。
- 仅在受阻或被工作流警告时读取 pitfalls.md。
- 优先采用工作流的最佳路径。如果它指定了适配器（如 opencli twitter post），先使用该适配器，再考虑原始浏览器操作。
- 如果适配器不可用或失败，使用回退路径浏览器工作流。
- 每次导航或状态变更操作后，刷新状态并比对工作流的 state_signature。
- 如果现实不一致，信任现实，继续探测，并写入本地过期笔记或草稿补丁。
- 如果操作恢复包含 adapter_health_update: <adapter> -> suspect|broken，更新引用该适配器的本地覆盖工作流，使后续代理直接走回退路径。
查找顺序
先读本地覆盖层，再读全局种子：
- ~/.opencli/sites/<site>/sitemap/ # 本地覆盖层
- sitemaps/<site>/ # 仓库种子（顶层）
本地文件覆盖具有相同稳定 id 的全局文件。
不要将整个大型 sitemap 加载到上下文中。如果目录很大，先列出文件名，然后只读取所需的页面/工作流。
信任现实规则
如果 sitemap 声称某个按钮、URL、路由或 API 应存在，但浏览器未显示：
- 重新运行 state 或使用语义锚点查找。
- 检查登录、语言环境、视口、A/B 测试或路由状态是否不同。
- 如果可见安全路径，跟随真实页面。
- 在本地覆盖层中将该 sitemap 项标记为过期。
- 绝不要因为“sitemap 说它应该能用”而持续点击。
过期/草稿笔记
当发现漂移时，在相关页面/工作流文件下或本地覆盖层中的草稿文件里写入小型本地笔记：
Stale note:
- observed_at: YYYY-MM-DD
- current_url:
- expected:
- actual:
- next_probe:
除非任务明确是 sitemap 编写或仓库 PR 任务，否则不要编辑全局种子文件。
适配器健康回写
当适配器失败且 sitemap 操作或工作流指示更新适配器健康状态时：
- 在 ~/.opencli/sites/<site>/sitemap/workflows/ 下找到最佳路径引用该适配器命令的本地工作流文件。
- 如果不存在本地工作流，先将匹配的全局工作流复制到本地覆盖层；在浏览器任务执行期间，绝不要直接编辑全局种子。
- 按指示设置 adapter_health: suspect 或 broken。
- 添加简短过期笔记，包含观察到的错误、当前 URL 和时间戳。
- 继续使用浏览器回退路径。
此回写是记忆循环：当前代理回退一次，下一个代理就不会浪费轮次重试已知可疑的适配器。
输出纪律
报告时包含：
- 所选路径：适配器最佳路径或浏览器回退。
- 到达的检查点：当前 URL/状态签名。
- Sitemap 健康状态：按原样使用、标记过期或缺失工作流。
保持报告聚焦任务。不要总结整个 sitemap。
适用场景
- 使用 opencli 浏览器驱动网站，且 sitemap 可用、被请求或需要以避免盲目导航时。
- 需要按站点 sitemap 结构（页面、工作流、陷阱）指导代理操作时。
- 需要在适配器与浏览器回退之间切换并记录健康状态时。
限制
- sitemap 不是绝对事实，必须服从实时浏览器状态。
- 不应将整个大型 sitemap 加载到上下文。
- 除非明确为 sitemap 编写或仓库 PR 任务，否则不应编辑全局种子文件。
- 关于具体站点、适配器列表、安装命令等细节，资料中暂未提供。