Add teaching Python agent CLI with Poetry and CI

docs/13-failure-recovery.md

@@ -0,0 +1,80 @@
+# 13. 失败处理与恢复规格
+
+## 1. 目标
+
+Agent 系统不能把失败当成异常边缘情况。失败是常态，系统必须有明确恢复策略。
+
+## 2. 失败类型
+
+建议至少区分：
+
+- `tool_input_error`
+- `permission_denied`
+- `hook_blocked`
+- `shell_runtime_error`
+- `model_api_error`
+- `prompt_too_long`
+- `mcp_connect_error`
+- `task_killed`
+- `resume_load_error`
+- `session_storage_error`
+
+## 3. 各类失败处理原则
+
+### tool_input_error
+- 直接回写错误给模型
+- 不执行真实工具
+
+### permission_denied
+- 不重复原样调用
+- 引导模型调整方案
+
+### hook_blocked
+- 将阻断原因结构化返回
+- 允许模型或用户后续处理
+
+### prompt_too_long
+- 触发 compact / reactive compact
+- 必要时重建消息序列后重试
+
+### model_api_error
+- 保留错误记录
+- 可尝试有限恢复
+
+## 4. resume 恢复需求
+
+系统必须支持：
+- 读取 transcript
+- 找到 compact boundary 后有效历史
+- 恢复 session_id 与 project dir
+- 恢复活跃任务或至少恢复摘要
+
+## 5. 子任务失败需求
+
+子任务失败后不能静默消失，必须：
+- 写入任务状态
+- 通知主线程
+- 保留错误摘要
+
+## 6. 恢复策略级别
+
+### 轻恢复
+- 调整输入
+- 重新请求权限
+- 简短重试
+
+### 中恢复
+- 压缩上下文后重试
+- 重建子任务上下文
+
+### 重恢复
+- resume 会话
+- 用户介入
+- 终止并保留证据
+
+## 7. 验收标准
+
+1. 常见失败都有明确处理路径
+2. 子任务失败不会丢失
+3. prompt too long 可进入压缩恢复
+4. 会话中断后可恢复