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. 优先采用工作流的最佳路径。若其指定了适配器（如 opencli twitter post），则先使用该适配器，再执行原始浏览器操作。
4. 若适配器不可用或执行失败，则使用备选路径的浏览器工作流。
5. 每次导航或状态变更操作后，刷新 state 并比对工作流的 state_signature。
6. 若实际情况与站点地图不符，以实际情况为准，继续探测，并在本地记录过期说明或草稿补丁。
7. 若操作恢复中包含 adapter_health_update: <adapter> -> suspect|broken，则更新引用该适配器的本地覆盖工作流，使后续 Agent 直接走备选路径。

---

查找顺序

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

~/.opencli/sites/<site>/sitemap/    # local overlay
sitemaps/<site>/                    # repo seed (top-level)

本地文件会覆盖具有相同稳定 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. 继续执行浏览器备选路径。

此回写即记忆循环：当前 Agent 只需回退一次，后续 Agent 便不会浪费一轮去重试已知存疑的适配器。

---

输出规范

汇报时应包括：

• 所选路径：适配器最佳路径或浏览器备选路径。
• 已到达的检查点：当前 URL / 状态签名。
• 站点地图健康状况：原样使用、已标记过期，或缺少工作流。

汇报应聚焦任务，不要概述整个站点地图。