flyenv-failure-boundaries

FlyEnv Failure Boundaries

先确定用户要求完成的结果，再决定一个步骤的失败能影响谁。一次附加动作失败不能 否定已完成的主操作，一个候选不合格不能阻断其他有效候选；必要依赖的失败仍要如实报告。

本项目通过根目录 AGENTS.md 指定读取本技能，实施前和 review 时都适用，不依赖自动发现。

实施前的判断

阅读实际调用者、共享执行器及终态处理，不只看发生异常的函数。对本次调整的步骤，在 现有计划/实现说明中记录：成功条件、是否必要、影响范围、失败处理以及已发生的副作用。 如果没有独立计划，在修改理由中写清这些判断，不为简单修复新增框架或配置。

步骤类别	判断依据	失败的影响范围
必要依赖	没完成就无法实现请求结果，或后续步骤缺少可靠输入	阻断依赖它的步骤，保留已完成结果
独立单项	与其他项可以独立判断和执行	记录该项失败/跳过，继续其他有效项
附加动作	主结果已经成立，只改善体验、观测或后续状态	记录自己的失败，保持主结果

不能只因为步骤位于主流程的中间/最后，就判定它必要或可忽略。DNS 刷新是 hosts 写入后的附加动作；hosts 写入本身是必要操作。停止是否成功、是否删除 PID 文件，遵守 对应生命周期约定；不能用“清理”这个名称把失败全部吞掉。

实现规则

• 候选逐项过滤：缺字段、身份不符、PID 已退出等只影响该候选；记 PID/跳过原因， 继续其他有效候选。共同前置条件失败（例如没有可靠进程列表）才影响所有依赖它的项。 无候选应区分“本来没有目标”和“全部无法确认”，不能把后者宣称为全部停止成功。
• 校验放在归属所有者：复用已经获取的进程表和既有身份判断。执行器按契约执行已 选目标，不另建重复校验、查询或排序，不重新扩大目标范围。过滤不等于允许操作未确认项。
• 附加动作隔离错误：使用窄范围 catch，在共同执行器/所有者处统一记录并返回明确 状态；不要每个模块复制处理。后台错误也要有接收者，不产生未处理 rejection。 日志失败不能反过来阻断主操作，也不要求为日志等待磁盘写入。
• 终态保留事实：主结果已完成时，附加动作失败不能进入主失败回调、覆盖主结果或触发 重放。必要项有失败时报告部分完成/失败；未知结果保持未知，不擅自重试。
• 批量等待与单项结果分开：独立并行项不因第一项拒绝而提前结束整个批次的结果收集。 使用已有的逐项错误处理或合适的聚合方式，记录每项终态；这不授权把启动组串行改为并行。
• 不追加补救链路：附加动作失败不自动安装帮助程序、弹 UAC、查询所有进程或重试主 操作。必要操作的授权/补救仍遵守原契约，不借本技能改变业务要求。

提交前 review

逐个检查本次新增/调整的 throw、reject、提前 return、循环内异常、批量聚合及成功/失败回调：

1. 它改变的是哪一个结果：单项、主操作、整批，还是退出流程？调用者是否会扩大这个影响？
2. 是否已经完成写入/kill 等副作用？后续失败会不会把它显示为没执行，或者导致重复执行？
3. 一个坏候选与一个有效候选并存时，有效候选是否仍能执行？必要项失败是否仍会如实报告？
4. 失败只是记录，还是偷偷引入了等待、查询、重试或提权？日志自身失败是否也被隔离？
5. 是否复用了共同策略？UI、退出、MCP、模块、Helper 的调用结果是否与各自原契约一致？

以下情形用于检查设计及代码路径；是否新增/运行测试遵守用户要求和会话测试约束：

• hosts 写入成功、DNS 启动失败：文件结果保持成功，有刷新失败日志，无写入重放。
• hosts 写入失败：请求仍失败，不继续发起以成功写入为前提的动作。
• 三个候选中一个不合格：只跳过该项，两个有效项继续；日志说明每项选择/跳过原因。
• 批量中一个必要停止失败：其他独立服务继续，汇总保留失败项，不假报全部停止成功。
• 主操作完成、通知或诊断记录失败：不改变主终态，不引入未处理异步异常。

本技能约束失败传播和结果语义；它不能替代实际 review 或证明实现无缺陷。