技能最佳实践：提示词工程只是开始
第 10 章解决了“能写出来”，这一章解决“上线后别翻车”。
同样一个 Skill，有人越写越稳，有人越写越乱，差别通常不在提示词有多花，而在规则有没有写清楚、边界有没有收紧。
本章你将学会什么
Section titled “本章你将学会什么”- 把输入输出固定成可测试、可追溯的结构。
- 用“重复执行不乱套（幂等）+ 复盘重现”让问题可复盘，而不是靠猜。
- 建立重试、超时、兜底方案（降级）三层保护。
- 用工具策略、审批与循环检测控制成本和风险。
- 让失败提示对小白读者友好且可执行。
- 你已经完成第 10 章示例 Skill。
- 你能使用：
openclaw skills info <name>openclaw logs --follow11.1 结构化输入输出
Section titled “11.1 结构化输入输出”11.1.1 输入先标准化，再交给模型
Section titled “11.1.1 输入先标准化，再交给模型”建议先把输入字段收紧，再让 Skill 执行。
例如日报 Skill 的入参最少保持：
date（字符串）highlights（字符串数组）blockers（字符串数组，可选）
好处很直接：
排障时你能快速判断到底是“输入有问题”，还是“执行流程有问题”。
11.1.2 输出要同时服务“人”和“机器”
Section titled “11.1.2 输出要同时服务“人”和“机器””推荐统一返回骨架：
{ "status": "ok", "summary": "已生成日报草稿", "data": { "file": "reports/2026-02-17-daily-report.md" }, "nextAction": "请检查“阻塞与风险”是否完整"}这能直接用于：
- 前端展示（读者看得懂）；
- 日志检索（机器可筛选）；
- 自动化回归（可断言）。
11.1.3 命名与字段稳定性
Section titled “11.1.3 命名与字段稳定性”一旦发布，尽量别随手改字段名。
比如把 summary 改成 message，看起来只是小改动，但会导致下游脚本、解析器、测试全部失效。
实操建议：
- 字段名尽量短且语义稳定；
- 新字段只新增，不轻易删除旧字段；
- 删除字段前先给过渡期版本。
11.2 重复执行不乱套与复盘重现
Section titled “11.2 重复执行不乱套与复盘重现”11.2.1 防重复键（幂等键）：给每次执行一个“身份标签”
Section titled “11.2.1 防重复键（幂等键）：给每次执行一个“身份标签””幂等的核心是：同一输入重复执行，不应该越跑越乱。
常见做法是生成防重复键（例如 date + project），并把它写入输出文件名或元数据。
11.2.2 写入策略：先读后写
Section titled “11.2.2 写入策略：先读后写”建议把“先读后写”直接写进 Skill 规则：
- 先检查目标文件是否存在；
- 根据策略覆盖或追加；
- 返回实际采取的动作。
这样读者就能理解“为什么这次覆盖、不是新建”，不会觉得系统在抽风。
11.2.3 可复盘重现：为排障留证据
Section titled “11.2.3 可复盘重现：为排障留证据”最低要求：
- 保留输入快照（脱敏后）；
- 保留关键决策点（例如“为何走降级分支”）；
- 保留输出路径。
配合日志命令：
openclaw logs --follow你就能把“偶现 bug”变成“可定位问题”。
11.3 重试、超时与兜底方案
Section titled “11.3 重试、超时与兜底方案”11.3.1 错误分类：先判定，再处理
Section titled “11.3.1 错误分类：先判定，再处理”先分两类错误：
- 不可恢复：参数缺失、权限明确不足、配置错误；
- 可恢复：短时网络失败、临时 I/O 错误。
不可恢复不要重试，可恢复才重试。
11.3.2 重试与超时的推荐值
Section titled “11.3.2 重试与超时的推荐值”对初学者最稳的默认值：
- 重试次数：1~2 次；
- 超时：每步 10~30 秒；
- 退避：1s → 2s（指数退避最简版）。
超过这个强度，读者通常会感觉“它卡死了”。
11.3.3 兜底方案（降级）：失败时也要有可交付结果
Section titled “11.3.3 兜底方案（降级）：失败时也要有可交付结果”兜底策略示例：
- 首选：写入完整结构化内容；
- 兜底：只写“摘要 + 待补充项”；
- 最终：返回失败说明与可执行修复动作。
原则：就算失败，也要给读者一个“下一步还能继续做”的状态。
11.4 限流与成本边界
Section titled “11.4 限流与成本边界”11.4.1 先收工具，再谈智能
Section titled “11.4.1 先收工具，再谈智能”用 tools.profile + allow/deny 先缩小工具集合：
{ tools: { profile: "coding", deny: ["group:runtime", "group:web"], },}对大多数内容生产 Skill，这就足够。
11.4.2 高风险执行必须走审批
Section titled “11.4.2 高风险执行必须走审批”一旦 Skill 涉及 exec 或主机侧命令，建议开启审批与白名单策略（exec approvals）：
security: allowlistask: on-missaskFallback: denyautoAllowSkills: true（仅在你信任当前技能来源时打开）
推荐最小策略（按 agent 粒度）：
{ "defaults": { "security": "deny", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": false }, "agents": { "main": { "security": "allowlist", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": true } }}再配一层 safeBins，把无需落盘、仅处理 stdin 的低风险命令放行：
{ "tools": { "exec": { "safeBins": ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"] } }}默认思路是：
宁可多一次确认，也不要让系统悄悄做错一次危险动作。
11.4.3 识别“空转循环”
Section titled “11.4.3 识别“空转循环””官方提供 tools.loopDetection（默认关闭）。
当你发现 Skill 在“重复调用同类工具但没有进展”时，可以启用：
{ tools: { loopDetection: { enabled: true, repeatThreshold: 3, criticalThreshold: 6, }, },}11.5 失败可解释与用户体验
Section titled “11.5 失败可解释与用户体验”11.5.1 对小白读者的错误文案模板
Section titled “11.5.1 对小白读者的错误文案模板”推荐固定模板（照抄就能用）：
- 发生了什么；
- 系统已尝试什么；
- 你下一步怎么做（带命令或按钮路径）。
示例：
生成日报失败：目标目录没有写权限。
我已尝试写入reports/，但操作系统拒绝。
请先执行ls -ld ~/.openclaw/workspace/reports检查权限，再重试。
11.5.2 把“人工可理解”放在“技术细节”前面
Section titled “11.5.2 把“人工可理解”放在“技术细节”前面”错误信息顺序建议：
- 第一行：人话总结；
- 第二行：关键字段（文件、命令、状态码）；
- 第三行：详细诊断（必要时折叠）。
这样既照顾小白，也不会丢掉工程排障需要的信息。
11.5.3 发布前质量门禁（实操版）
Section titled “11.5.3 发布前质量门禁（实操版）”发布前至少跑一轮清单：
[ ] 正常输入能成功[ ] 缺参数能给明确提示[ ] 非法输入不会卡死[ ] 同一输入重复执行结果稳定[ ] 日志能还原关键步骤[ ] `exec approvals` 已配置 `allowlist + on-miss + askFallback: deny`[ ] `safeBins` 仅保留最小集合，未误放高危命令[ ] 无需读者猜测“下一步”- 结构化 I/O 是 Skill 可维护性的地基，不是“可有可无”。
- 重复执行不乱套（幂等）、可复盘重现、重试、兜底方案是一个整体，少一项都容易在真实环境翻车。
- 成本与风险管理要前置到工具策略层，不能只靠模型“自觉”。
- 好的失败提示能显著降低读者挫败感，这本身就是工程质量。