卡住检测执行手册
何时使用
任务进行中出现以下任一信号，启动本手册判定是否"卡住"：
- 死循环型：同一命令/操作反复失败（失败 2-3 次即触发，不等时间）。
- 等待型：安装/下载/生成/渲染等正常耗时操作，单阶段超过约 15-20 分钟无实质进展。
- 外部依赖异常：网络超时、API 限流、权限/沙箱拦截、依赖缺失等。
判定卡住后：暂停当前做法，不要硬扛、不要无限重试。
卡点分类表
| 类型 | 特征 | 判定 | 处置倾向 |
|---|---|---|---|
| 死循环型 | 同一操作反复报同样错误 | 失败 2-3 次立即触发 | 换方案，重试无意义 |
| 等待型 | 操作正常但耗时（安装/生成/渲染/下载） | 15-20 分钟无进展 | 确认进度/排队状态，可放宽或并行 |
| 外部依赖型 | 网络、限流、沙箱、密钥、服务端问题 | 出现即记录，重试 1-2 次后触发 | 换源/换通道/退避/降级 |
| 逻辑卡壳 | 代码/流程逻辑走不通，非等待 | 2 次思路尝试无果即触发 | 换实现思路或问用户 |
高频卡点方案库（实战验证过，直接复用）
> 标注 [WorkBuddy 环境] 的条目为 WorkBuddy 平台的实现细节；其他平台使用时参考同行的"通用替代"。
| 卡点 | 首选方案 | 备选方案 |
|---|---|---|
| 包管理器安装慢或失败（npm/pnpm） | 换镜像源：国内 --registry=https://registry.npmmirror.com，其他平台换官方源/CDN |
依赖已装全则跳过安装直接跑；EPERM 文件锁→重试/清缓存 |
| API 限流（如 TTS 报 NoAudioReceived） | 逐条间隔 3 秒重试、降并发 | 换参数（rate/pitch）、换服务 |
| 渲染/构建失败 | 先看错误日志定位根因 | 降规格（分辨率/时长/帧率）、降级功能 |
浏览器下载失败（Remotion 等）[WorkBuddy 环境] |
手动放置 chrome-headless-shell + 写 VERSION 文件跳过下载；--browser-executable 用正斜杠路径 |
换浏览器通道、其他平台用系统已装浏览器 |
沙箱拦截文件操作（fs.rm 等）[WorkBuddy 环境] |
给目标代码包 try-catch 打补丁（失败仅警告） | 改用不触发的替代命令；通用替代：确认运行权限 |
ffmpeg 缺失 [WorkBuddy 环境] |
用 venv 内 imageio_ffmpeg 静态版 | 复制到项目 ffmpeg-bin/ 复用；其他平台直接装系统 ffmpeg |
| 等待 AI 视频/图片生成 | 确认是否在排队，问清楚预计时长 | 降时长/分辨率缩短等待；先并行做其他任务 |
| 下载大文件失败 | 换源/镜像 | 断点续传、分包拉取、手动放置 |
| 权限不足 | 检查是否需要提升权限执行 [WorkBuddy 环境: dangerouslyDisableSandbox] |
拆分命令，减少权限面；通用替代：以最小权限完成同一目标 |
> 方案库随实战持续补充：每次成功解决一个新卡点，把"卡点→方案"加进上表。
执行动作规范
交互会话（有人可问）
- 暂停当前操作。
- 给出诊断摘要（格式固定，信息一次给齐）：
[卡住诊断] 阶段：<xx>（等待型：已 xx 分钟无进展 / 死循环型：已失败 x 次）
尝试过：1) <做了什么> 2) <结果>
疑似原因：<限流/超时/权限/依赖/逻辑…>
备选方案：A) <方案+预期成本> B) <方案> C) <方案>
- 用选项卡片让用户选
[WorkBuddy 环境: AskUserQuestion 交互卡片；其他平台：用普通文字列出 2-4 个互斥选项]，推荐项放第一位并标注"（推荐）"。 - 用户选定后执行；若用户选"其他"自定义，按其输入执行。
无人值守（定时/自动化任务，无用户可问）
- 自动降级：从方案库选"风险最低、成功率最高"的方案执行（宁可保守，不可冒险）。
- 记录：在任务输出/日志中写一行触发记录（见下）。
- 事后汇报：任务完成时说明"哪个阶段卡过、怎么解决的、耗时多少"。
真实案例（看这套机制怎么用）
案例 1：npm 安装卡死 → 换镜像解决
- 场景：Windows 环境安装 Remotion 全家桶依赖。
- 卡住信号：npm install 超过 15 分钟进度停滞（等待型）。
- 诊断：默认源在国内访问慢；尝试 1 次重试仍无进展。
- 选择：A) 换 npmmirror 镜像（推荐）B) 跳过安装直接用已装依赖 C) 继续等。
- 结果：换镜像后数分钟完成；后续 EPERM 文件锁用清缓存解决。
案例 2：edge-tts 批量配音限流 → 间隔重试解决
- 场景：连续生成 4 句台词配音。
- 卡住信号：连续 2-3 次报 NoAudioReceived（外部依赖型/死循环型）。
- 诊断：连续请求触发服务端限流。
- 选择：A) 逐条间隔 3 秒重试（推荐）B) 换 rate/pitch 参数 C) 换 TTS 服务。
- 结果：间隔重试后 4 句全部成功。
案例 3：沙箱拦截文件删除 → try-catch 补丁解决
- 场景：Remotion 渲染时浏览器下载锁清理崩溃。
- 卡住信号：同一操作反复报错（死循环型）。
- 诊断：沙箱策略拦截
fs.promises.rm调用。 - 选择：A) 给目标代码包 try-catch 打补丁（推荐）B) 沙箱外执行 C) 改替代命令。
- 结果：补丁后跳过清理，仅警告不崩溃，渲染正常完成。
触发记录模板（每次触发写一行到工作日志）
[卡住] <日期> <阶段> <类型:死循环/等待/外部依赖/逻辑> 失败<x>次或<x>分钟 → 选<方案A> → 结果<成功/失败>
积累 3-5 次后复盘：哪个阶段最爱卡？阈值合不合适？方案库缺哪类？
反模式（禁止）
- 硬扛：同一操作无限重试、干等超过阈值不吭声。
- 静默换路：交互会话中不告知用户就擅自改方案。
- 无脑问：能低成本自行判断的低风险卡点（如换镜像重试），先问再说。
- 验证强迫症：对实际任务没有影响的工作（验证截图、打磨）开始前，先确认再执行。
- 忽略成本：预计耗 50 积分以上的操作
[WorkBuddy 环境；其他平台改为：预计高成本/长耗时的操作]，开始前先向用户确认。
平台迁移说明（其他平台如何使用本手册）
- 判定规则（分类表、阈值）、诊断摘要模板、无人值守策略、触发记录、反模式：与平台无关，直接照用。
- 需要替换的部分：
- 选项卡片 → 普通文字列出选项，让用户回复编号。
- 沙箱/提权/积分 → 按本平台的权限模型与成本计费换算。
- 方案库中
[WorkBuddy 环境]条目 → 用"通用替代"列的实现。
与其他机制的关系
- 与「动手前确认」（50 积分阈值）配合：一个管开始前，一个管进行中。
- 判定标准可调：用户反馈阈值不合适时，更新 MEMORY.md 与本手册后生效。
