opencli-browser-sitemap

opencli-browser-sitemap

当 opencli browser open 或 opencli browser analyze 报告 sitemap.available: true，或用户要求你使用网站的站点地图时，使用此技能。

站点地图是先验知识，而非事实依据。它应减少盲目点击，但绝不能覆盖实时浏览器状态。

---

消费循环

1. 运行或复用 opencli browser <session> state 以了解当前页面。
2. 仅读取最小的相关站点地图文件：
   • SITE.md 用于站点级定位。
   • 一个匹配的 pages/<page-id>.md 用于当前状态。
   • 一个匹配的 workflows/<task-id>.md 用于用户目标。
   • 仅在受阻或收到工作流警告时读取 pitfalls.md。
3. 优先使用工作流的 Best path。如果它指定了适配器，如 opencli twitter post，则优先使用该适配器，而非原始浏览器操作。
4. 如果适配器不可用或失败，则使用 Fallback path 浏览器工作流。
5. 每次导航或状态改变操作后，刷新 state 并与工作流的 state_signature 比较。
6. 如果实际情况不符，信任实际情况，继续探测，并写入本地过时注释或草稿补丁。
7. 如果某个操作恢复包含 adapter_health_update: <adapter> -> suspect|broken，则更新引用该适配器的本地覆盖工作流，以便未来代理直接使用回退路径。

---

查找顺序

先读取本地覆盖，再读取全局种子：

~/.opencli/sites/<site>/sitemap/    # 本地覆盖
sitemaps/<site>/                    # 仓库种子（顶层）

本地文件覆盖具有相同稳定 ID 的全局文件。

不要将整个大型站点地图加载到上下文中。如果目录很大，先列出文件名，然后仅读取所需的页面/工作流。

---

信任现实规则

如果站点地图显示某个按钮、URL、路由或 API 应该存在，但浏览器未显示：

• 使用语义锚点重新运行 state 或 find。
• 检查登录、语言环境、视口、A/B 测试或路由状态是否不同。
• 如果可见路径安全，则遵循实际页面。
• 在本地覆盖中将该站点地图项标记为过时。

永远不要因为“站点地图说它应该有效”而持续点击。

---

过时/草稿注释

当发现偏差时，在相关页面/工作流文件下或本地覆盖中的草稿文件中写入简短注释：

Stale note:
- observed_at: YYYY-MM-DD
- current_url:
- expected:
- actual:
- next_probe:

除非任务是明确的站点地图编写或仓库 PR 任务，否则不要编辑全局种子文件。

适配器健康回写

当适配器失败且站点地图操作或工作流指示你更新适配器健康时：

1. 在 ~/.opencli/sites/<site>/sitemap/workflows/ 下找到其 Best path 引用该适配器命令的本地工作流文件。
2. 如果不存在本地工作流，先将匹配的全局工作流复制到本地覆盖中；在浏览器任务执行期间切勿直接编辑全局种子。
3. 按指示设置 adapter_health: suspect 或 broken。
4. 添加包含观察到的错误、当前 URL 和时间戳的简短过时注释。
5. 继续使用浏览器回退路径。

此回写是记忆循环：当前代理回退一次，下一个代理不会浪费回合重试已知可疑的适配器。

---

输出规范

报告时，包括：

• 选择的路径：适配器最佳路径或浏览器回退。
• 达到的检查点：当前 URL/状态签名。
• 站点地图健康：按原样使用、标记为过时或缺少工作流。

保持报告聚焦于任务。不要总结整个站点地图。