为 OpenCLI agent 编写/维护站点…

在需要为某个网站创建或维护 OpenCLI 站点 sitemap，以供 agent 导航、执行动作、选择 adapter 和恢复失败时使用。

适用场景

解决思路

1. 明确产物是面向 agent 的任务执行图，不是 SEO sitemap；它应帮助使用 opencli browser 的 agent 决定自己在哪里、下一步走哪条路径、优先用哪个 OpenCLI adapter，以及页面与记忆不符时如何恢复。
2. 保持 sitemap 小且经过验证；不要爬整站，只捕获实际观察到的任务相关路径。
3. 使用两层存储：全局 seed 放 sitemaps/<site>/（顶层）；本地 overlay 放 ~/.opencli/sites/<site>/sitemap/。
4. 本地 overlay 按 stable id 覆盖全局；新发现先写本地，只有 review 后再 promote 到全局。
5. 采用推荐布局：sitemap/SITE.md；sitemap/pages/<page-id>.md；sitemap/pages/_<partial>.md；sitemap/workflows/<task-id>.md；sitemap/pitfalls.md。
6. 按 token 大小决策文件拆分：<1500 token 是自然 size，不动；1500-3000 看 cohesion，5 个 cohesive UI primitive 一起放 OK，mixed 内容拆；>3000 必拆 sub-file 或 partial。
7. 不要机械强拆；spec 的 800 token 是 lazy-load 优化目标 + Phase 2 audit 阈值，是 author 实战决策辅助，不替代 spec hard 限制；超 800 的文件 audit 会 flag，author 解释或拆。
8. Phase 2 cron audit 按 token count 不按 byte count；CJK 中文 token-per-char 比 English 高 30-50%。
9. Authoring Loop：先读 local overlay，再读 global seed（如存在）。
10. 用 opencli browser <session> state、find、network、analyze 验证现实；browser state 是真相。
11. 如果刚完成该站的 opencli-adapter-author session，从 ~/.opencli/sites/<site>/traces/ 保留的 browse trace 作为 seed evidence，而不是从零重新发现路径。
12. 只记录持久结构：页面目的、稳定锚点、状态签名、动作、工作流、API 引用、坑点。
13. 使用稳定 id：page/action/workflow id 应能经受 URL 参数、locale 文案漂移和轻微布局变化。
14. 写本地草稿：更新 ~/.opencli/sites/<site>/sitemap/...，除非明确要 promote 到 repo。
15. 冲突时标记 stale：如果已有 sitemap 与当前浏览器状态不一致，信任浏览器状态并将该项标 stale，而不是强制旧路径。
16. 每个 action edge 必须包含 pre、do、post、fail、recover、evidence。
17. 默认使用紧凑 action 形式；只有 action 确实需要长解释时，才用 references/sitemap-schema.md 的较长 Markdown 形式。
18. verified_at 和 source 从文件 frontmatter 继承；不要每个 action 重复。
19. 没有 evidence 不得 promote action。
20. 如果 recovery path 标记 adapter_health_update，browser-sitemap consumer 必须把该 health update 写入 local overlay，避免下一个 agent 重试已知 suspect adapter。
21. partial 文件 _<name>.md，url_patterns: []，用于跨页 UI 原语；被多 page 通过 action:<id> in pages/_<name>.md 引用。
22. partial 内所有 selector（testid/a11y/structural）必须 scoped 到 partial root，不能用 page-level first match；例如点击 like 要用 click [data-testid="like"] in article[role="article"] (card scope)，不要用 click [data-testid="like"]。
23. partial 文件顶部写明 scope root 一行，例如 ## Card scope rule，说明所有 testid selector 必须 scoped 到 article[role="article"]，不能用 page-level first match。
24. 每个 workflow 要回答 Goal、State signature、Best path、Fallback path、Avoid、Stale markers。
25. Best path 优先使用已有 opencli <site> <command> adapter（如果覆盖目标）。
26. Fallback path 在 adapter 缺失或失败时用 browser workflow。
27. Avoid 记录浪费轮次、触发 modal 或依赖不稳定 selector 的诱惑路径。
28. Stale markers 记录 last verified date 和已知 layout/API drift signals。
29. Endpoint/API 知识在有 endpoints.json 时引用其 id；不要在 sitemap 文件中复制完整 endpoint schema。
30. Fallback path 推荐第一行用 on_adapter_fail: 声明触发条件 + adapter_health_update directive，把为什么走 fallback 和标 adapter suspect 放一起。
31. on_adapter_fail 示例可包含 adapter_health_update: opencli twitter post -> suspect；opencli browser state 验证当前页；if not on /home: goto /home；action:open_compose in pages/home.md 等。
32. consumption skill 看到 on_adapter_fail: key 应知道这是 adapter-trigger 而非 entry-point fallback；先执行 directive，再走后续 steps。
33. SITE.md 的 Top-level routes 不仅列已覆盖 page，也要显式标存在但 sitemap 不导航的 route，避免 agent 默认 sitemap 没列 → 不存在。
34. 示例标法：/messages → pages/messages.md（DM，本 PoC v1 不覆盖）；/settings → 不在 sitemap scope，agent 自探。
35. 不写 route = agent 不知其存在；写 + 标 uncovered = agent 知道存在但 sitemap 帮不上忙，自己探。
36. Red line：sitemap 是提示；当前浏览器状态是真相。
37. 不要写 secrets、cookies、user-private ids、private messages、account-specific values。
38. 不要为 CAPTCHA、WAF、访问控制、rate limits、paid gates 记录绕过方法。
39. 不要存 brittle snapshot indices 如 [17] 作为持久目标；存 semantic anchors 和 recovery instructions。
40. 不要将未验证路径描述为事实；用 draft 或 stale 标签。
41. Drafts 放 sitemap/draft-<topic>.md，不要放 ~/.opencli/sites/<site>/sitemap.draft.md 父级，因为后者对 opencli browser sitemap availability detection 不可见。
42. 详细 schema 参考 references/sitemap-schema.md：SITE.md / pages/<id>.md / workflows/<id>.md / apis.md / pitfalls.md schemas、action-level state signatures、adapter_health enum (healthy / suspect / broken)、endpoint reference rules、two-layer overlay semantics、draft placement、Phase 2 validation rules。

适用边界 · 注意事项

• 不适用于制作 SEO sitemap 或 crawling 整站；只覆盖实际观察到的任务相关路径。
• 没有 opencli 浏览器状态或 trace evidence 时，不应把路径写成事实，只能标 draft/stale。
• 不要记录 secrets、cookies、用户私有 id、私信、账号特定值，也不要记录绕过 CAPTCHA、WAF、访问控制、rate limits 或 paid gates 的方法。