文档写作契约

公开文档是 Agent 和用户都会执行的产品契约，不是交付报告。

页面职责

• 首页解释产品为什么存在，只提供一条首次成功路径。
• 使用页先给一句话意图或可复制的对话提示，再说明用户看什么结果、下一句怎么说。
• 普通用户不从命令行开始；命令、参数和协议字段集中放在明确面向 Agent 或开发者的参考页。
• 案例使用 oh-my-* 名称并附中文场景。已有运行记录保留证据与进度；示例场景明确标注，不冒充已完成的工作。
• Concepts 解释为什么，不承担命令速查。
• Reference 以当前 CLI、Schema 和包内容为事实源。
• Records 只保存长期验收与可复现实验，不保存工作总结。

写作门禁

• 可以编写供用户复制的提示词，不虚构已经发生的 Agent 回复或执行结果。
• 不使用未经测量的“30 秒”“一键完成”。
• 不用“真实、完整、专业、智能”代替验收证据。
• 不复制会变化的 Provider、Skill 或命令数量；指向动态状态或当前事实源。
• 截图只证明截图中可观察的状态，不证明后台流程或业务结论。
• SIMULATED、REPLAYED、partial、failed 和 skipped 必须保持原义。
• 删除或移动页面前检查入链、锚点和 Pages 路由。

案例模板

示例场景按“遇到什么事 → 交给 Agent 的提示 → 在哪里看结果 → 下一句”组织。已有运行记录另保留实际来源、产物、证据、当前状态与未完成部分。

截图优先展示状态变化；命令和文本输出优先使用可复制代码块。任何本机路径、用户名、凭据或私人界面在提交前都必须清理。