起飞前检查 Dank1ng6667/agent-preflight

agent-preflight · 起飞前检查

⛔ 本仓库已冻结（2026-10-16）

原计划做「动手 / 重启前的安检」。写完 M1（4 个命令、30 项测试全过、CI 全绿）后做了竞品调研，结论是：生态里已经有更成熟、用户多得多的同类工具。所以代码停止开发，这个仓库留下来的价值是那份规范（SAFETY.md）和一次诚实的调研记录。

👉 如果你现在就需要这类工具，建议优先用这些

按实用度排序（均非本项目，据 2026-10-16 实测）：

| 工具 | 干什么 | 月下载 |
| @noob-stupid/dsh-plugin-console | 框架升级安全 + 插件升级门控 + 失败自动回滚 + 多源插件市场 | 20,395 |
| dsh-doctor | 事后诊断 / 检查点 / 回滚 / 自动恢复 | 3,060 |
| dsh-compat-vet | 启动时插件兼容体检 + 页面上的一键修复 | 881 |
| dsh-rescue-toolbox | DSH 起不来时的独立急救（找坏插件 / 禁用 / 恢复） | 754 |

本项目与上述项目无关联、无背书关系，只是把调研结果如实放在这里，免得你再走一遍。

那这个仓库还剩什么值得看？

护栏三问 + 五条硬规矩（SAFETY.md）—— 它们是通用的，装不装任何工具都成立：动手前谁负责存点？出事后谁点得动？回滚时会不会把现状也毁掉？

代码部分（M1）仍然可用，但不再继续开发、也不再承诺维护：

| 命令 | 一句话 | 状态 |
| snapshot | 按预设清单存点，每个文件记 SHA-256 | ✅ 可用（冻结） |
| restore | 校验哈希 → 先把现状另存 → 才覆盖（默认干跑） | ✅ 可用（冻结） |
| doctor | 检查清单路径、快照完整性、磁盘占用 | ✅ 可用（冻结） |
| sentinel | 探测「下次启动会不会自动装东西」 | ✅ 可用（冻结） |

验收测试：30 项全过（tests\run-tests.ps1）；细节与决策记录见 docs/roadmap.md。

护栏三问

在让 AI 助手动你的配置、插件、工作环境之前，先回答三个问题：

| # | 问题 | 答不出来的后果 |
| 1 | 动手之前，谁负责存点？ | 出事时没有可回退的状态 |
| 2 | 出事之后，谁点得动？ | 只有命令行的恢复方案 = 没有方案 |
| 3 | 回滚之时，现状会不会一起被毁？ | 恢复动作本身变成第二次事故 |

完整规范在 SAFETY.md。

它是什么

一套规范 + 一个参考实现。

| 命令 | 一句话 | 状态 |
| snapshot | 按预设清单存点，每个文件记 SHA-256 | ✅ 可用 |
| restore | 校验哈希 → 先把现状另存 → 才覆盖（默认干跑） | ✅ 可用 |
| doctor | 检查清单路径、快照完整性、磁盘占用 | ✅ 可用 |
| sentinel | 探测「下次启动会不会自动装东西」（由预设声明） | ✅ 可用 |

快速开始

0) 自测（不需要真配置，凭空造一个假客户端跑一遍） powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\run-tests.ps1

1) 动手之前：存一个点 powershell -NoProfile -ExecutionPolicy Bypass -File .\src\seatbelt.ps1 snapshot -Preset dsh -Note "装插件前"

2) 出事了：先干跑，看看会覆盖哪些文件（默认不写任何东西） powershell -NoProfile -ExecutionPolicy Bypass -File .\src\seatbelt.ps1 restore -Preset dsh

3) 确认没问题，真恢复（会先把现状另存到 _before-restore，再覆盖） powershell -NoProfile -ExecutionPolicy Bypass -File .\src\seatbelt.ps1 restore -Preset dsh -Apply

4) 平时：体检 + 哨兵 powershell -NoProfile -ExecutionPolicy Bypass -File .\src\seatbelt.ps1 doctor -Preset dsh powershell -NoProfile -ExecutionPolicy Bypass -File .\src\seatbelt.ps1 sentinel -Preset dsh

核心不认识任何具体产品 —— 所有产品知识都在 presets/*.json 里。
这是它有望活得比某个客户端更久的原因。

它不是什么

- ❌ 不是通用备份 / 版本软件（那是另一类工具，已经很多）
- ❌ 不管你的代码（代码交给 git）
- ❌ 不做云同步、账号体系、插件市场
- ❌ 不做系统级加固（注册表 / 服务 / 权限 / 驱动那一类，本项目一律不碰）

为什么会有它

一句话：在一次真实的插件事故之后。

2026 年 10 月的一次插件安装，让宿主客户端在重启后再也打不开、无法对话。
当时手上没有任何「点一下就恢复」的东西，只有一堆命令和路径 ——这个项目就是把那次事故里补出来的东西，做成别人也能用的形状。

同类工具（agent_settings_backup_script、safesandbox、bak-cli、memgovern 等）都是给开发者用的；这个项目补的是另一头：给普通人的一键逃生舱 + 更新前哨兵 + 改动前准入检查，并且把它写成规范。

支持的目标（预设）

| 预设 | 状态 |
| presets/dsh.json · DeepSeek Harness | ✅ 已在真机上用同一套逻辑跑过，M1 落地代码 |
| Claude Code / Codex / Cursor | 🕓 欢迎 PR（照着 presets/example.json 填） |

环境要求

- Windows 10 / 11
- Windows PowerShell 5.1（系统自带）或 PowerShell 7+

发布前自检

powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\scan-secrets.ps1

检查有没有把密钥、本机个人路径、大文件带进仓库（只读，不改任何文件）。

许可证

MIT —— 见 LICENSE。

本项目是社区工具，非官方：与任何客户端厂商均无隶属、赞助或背书关系。