auto backup 2026-07-02 11:00

skills/dws/references/recovery-guide.md

@@ -0,0 +1,94 @@
+# Recovery Guide
+
+`dws` 的 recovery 闭环以 `dws recovery execute` 为正式入口。主入口仍是 [SKILL.md](../SKILL.md)，错误分类与排查细节可结合 [error-codes.md](./error-codes.md) 和 [global-reference.md](./global-reference.md) 一起使用。
+
+## 标准流程
+
+1. 原始 `dws` 命令失败后，从 stderr 提取 `RECOVERY_EVENT_ID=<event_id>`
+2. 执行 `dws recovery execute --event-id <event_id> --format json`
+3. 读取返回的 `RecoveryBundle`
+4. 先查看 `plan.decision_owner`
+5. 当 `decision_owner == "agent"` 时，把完整 `RecoveryBundle` 视为事实包，由 Agent 基于事实包、对应产品文档和 `dws` skill 做整体判断，再决定是否组织下一次 grounded 的 `dws` 恢复尝试
+6. 恢复尝试结束后，执行 `dws recovery finalize --event-id <event_id> --outcome recovered|failed|handoff --execution-file <file.json> --format json`
+
+CLI 会把 recovery 过程文件保存在 `DWS_CONFIG_DIR/recovery/` 下，并自动清理 30 天前的旧文件与旧事件记录。
+
+## 如何阅读 `RecoveryBundle`
+
+`RecoveryBundle` 重点字段：
+
+- `status`：`needs_agent_action` 或 `analysis_failed`
+- `context`：原始失败上下文
+- `replay`：可重放的脱敏命令信息和工具参数
+- `plan`：规则分类、`decision_owner`、`agent_route`、`doc_search`、`kb_hits`、`doc_actions`、`human_actions`
+- `doc_search.request`：CLI 实际发起的开放平台文档检索请求参数
+- `doc_search.response`：CLI 收到的原始文档检索返回内容块
+- `probe_results`：CLI 已完成的只读探测和上下文审计结果
+- `agent_task`：给 Agent 的明确工作单
+- `finalize_hint`：最终必须回写的 `finalize` 命令模板和 `execution-file` 要求
+
+当 `status == "analysis_failed"` 时，不要假设 CLI 已经修复问题；应先读取 `analysis_error`、`doc_search`、`probe_results`，再判断是否还能继续 grounded 尝试。
+
+当 `plan.decision_owner == "agent"` 时：
+
+- 必须把 CLI 返回内容视为事实包，而不是已定案的恢复结论
+- 优先基于完整 `RecoveryBundle` 做判断；若只能读取 `agent_route.payload`，也必须使用其中的 `context`、`replay`、`doc_search`、`kb_hits`、`doc_actions`、`probe_results`
+- unknown 场景里，不要把 `should_retry`、`should_stop`、`human_actions` 当作 CLI 已经替 Agent 作出的最终决定
+
+## Agent 允许做什么
+
+- 读取 [global-reference.md](./global-reference.md)、[error-codes.md](./error-codes.md) 和对应产品文档
+- 基于完整 `RecoveryBundle`，尤其是 `doc_actions`、`kb_hits`、`probe_results`、`context`、`replay` 做整体判断
+- 仅在依据明确时重新发起新的 `dws` 命令
+- 将真实尝试过程记录进 `execution-file`，再调用 `finalize`
+
+## Agent 禁止做什么
+
+- 编造 taskId、recordId、threadId、UUID、token、URL 或其他业务参数
+- 绕过 `dws` 改用 curl、HTTP API、浏览器或其他未授权手段
+- 未确认前把失败命令替换成另一套业务流程
+- 因为 `human_actions` 里提到用户步骤，就跳过 bundle 里的其余分析信息
+
+## `execution-file` 最小要求
+
+`execution-file` 必须至少包含：
+
+- `actions`
+- `attempts`
+- `result`
+- `error_summary`
+
+`attempts` 是数组，每次尝试至少记录：
+
+- `command_summary`
+- `result`
+- `error_summary`
+- `source`
+
+兼容旧格式：
+
+- `action` 会被归一化成单元素 `actions`
+- 数值型 `attempts` 会被展开为 `legacy_execution_file` 来源的 attempts 记录
+- `error` 会被归一化到 `error_summary`
+
+## unknown 参数错误处理
+
+如果 `execute` 进入 unknown 场景，且 `probe_results` 已给出 CLI 检查过的上下文来源，Agent 应：
+
+- 先检查上一步输出、已有上下文、产品文档或 `probe_results` 里是否存在真实参数来源
+- 若没有可靠来源，就回写 `handoff`
+- 不要盲猜新的 ID、UUID、URL、token 或其他业务参数
+
+对应标准闭环：
+
+```bash
+dws recovery execute --event-id <event_id> --format json
+dws recovery finalize --event-id <event_id> --outcome handoff --execution-file execution.json --format json
+```
+
+## 必读参考
+
+- [error-codes.md](./error-codes.md)
+- [global-reference.md](./global-reference.md)
+- [intent-guide.md](./intent-guide.md)
+- [products/](./products/)