# 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/)