← 返回列表
需源码安装
firstaid · 急救台
暂不能直接安装（需源码编译或环境不满足）：仓库 package.json 标记 private，未发布到 npm，需从源码安装。 · 最近上游提交 2026/9/22 · 已提供中文文档
Zero-dependency incident toolkit for long-running agent hosts: one entry point for stuck services, frozen UIs, rollbacks and data loss; emits a hand-off-ready on-site report. Read-only by default. | 零依赖急救台：起不来 / 假死 / 要撤销改动 / 数据被删四类现场压成一个入口，产出可整段交出去的体检报告
综合分
29.8
GitHub 分
29.8
用户评分
—
★ Stars
0
周下载量
—
安装插件（需先安装 dsh CLI 引擎：npm install -g @deepseek-ai/dsh）
dsh plugin --profile web add kira905/dsh-firstaid仓库 package.json 标记 private，未发布到 npm，需从源码安装，改用 GitHub 源安装
信任档位：已验证本站已于 1 天前真实安装成功
- 是什么
- dsh 原生插件 · ui
- 装得上吗
- 本站已真实安装成功（非静态推断）
- 安全吗
- 本站尚未对该插件做风险分级（暂未覆盖，不等同于无风险）
- 还在维护吗
- 活跃：最近一次提交在 4 天前
档位由下列信号合成：本站实装验证（真实安装，当前最高到 L4）· 验证所用 dsh 版本 · 静态安装检查 · 风险分级 · 仓库维护状态。下方各区块是它的证据明细。 验证判据与等级说明 →
🟢实装验证通过· 2026/9/25
由本站实装验证器在真实 dsh 环境安装成功，非静态推断。
数据截至 2026/9/23（元数据每日更新 · 实装验证按队列轮转，单条结论的验证时间见上方）
安装兼容性检查需源码安装
以下结论由程序自动检查 npm 包、engines 声明与入口文件得出，未做人工实机验证——能装不等于用着没问题。
✓npm 包firstaid @ 1.0.0
✓Node 引擎要求 >=18 · 基线 Node 22.19 满足
✓dsh CLI 依赖未声明 dsh 版本约束
✓入口文件main/exports/bin 已声明
仓库 package.json 标记 private，未发布到 npm，需从源码安装
验证方式：npm registry 存在性 + package.json 静态校验 · 最后验证 2026/9/23 21:26:57
用户评分
还没有人投票，来当第一个
订阅周报，不错过优质插件更新
每周一封 · 高评分插件 + 新用户活动
README
由 DeepSeek 最新模型翻译生成firstaid · 急救台
出事时只想知道「跑哪个」——这个工具把「起不来 / 界面假死 / 要撤销改动 / 数据被删」四类现场压成一个入口，
产出一份可整段交给 AI 或同事的现场体检报告。
默认只诊断，不动手。 任何回滚/重启都是写动作，必须有人确认；而且没演练过的恢复脚本永远不会被列进「可一键执行」。
- 零第三方依赖：只用 Node 内置模块（宿主/主包挂了，它照样能跑）
- 只读为主：除写自己的报告/日志外，不改任何被诊断的对象
- 三档演练：L1 沙箱（必做）/ L2 真实（造坏→恢复→还原）/ L3 需停机
- 机读友好：每份报告都有固定字段，退出码即结论（0 正常 / 1 有异常 / 2 用法 / 3 环境不可用）
一、这工具治什么病
| 症状 | 它能回答的问题 |
|---|---|
| 服务打不开 / 起不来 | 守护进程在不在、端口有没有人听、进程活着吗、日志尾部报了什么 |
| 界面假死 / 一直转圈 | 是服务端真故障，还是浏览器侧连接池/GPU 争用（90% 是后者） |
| 刚改完的东西想撤销 | 最近几天改了什么、每条的备份还在不在、该跑哪个恢复脚本、要不要停机 |
| 数据 / 文件被删 | 哪些备份介质真的在位、可恢复范围是什么（不承诺不可恢复的东西） |
| 不知道怎么了 | 一键生成体检包（进程/端口/日志尾/最近改动/备份可用性/演练状态） |
反过来，它不做这些事：不替你回滚、不替你重启、不猜你的环境、不在没备份时假装有备份。
二、目录结构
firstaid/
├─ firstaid.mjs 症状入口（5 个症状 → 现场体检报告）
├─ timeline.mjs 改动时间轴（变更流水 ∩ 回滚点 ∩ 演练记录）
├─ drill.mjs 恢复点演练编排器（L1 沙箱 / L2 真实）
├─ rollback-index.mjs 回滚脚本索引（症状 → 脚本 → 影响面 → 前置条件 → 是否演练过）
├─ firstaid-launch.ps1 Windows 交互菜单外壳（可选；纯 CLI 用户不需要）
├─ lib/
│ ├─ common.mjs 公共库（进程/端口/HTTP 探活、报告渲染、落盘）
│ └─ runtime-config.mjs 路径与特征解析层（所有环境相关的值都从这里来）
├─ scripts/verify-source.mjs 发布前自检（脱敏扫描 + 注入规则 + 扫描器自检）
├─ _test/ 单测与夹具（全部在临时沙箱里跑）
└─ examples/ 配置示例
三、安装（三步）
第 1 步 · 需要 Node
node --version # 需要 Node 18+（本工具只用内置模块，无构建、无 npm install）
第 2 步 · 取到本地
git clone https://github.com/kira905/dsh-firstaid.git firstaid
国内镜像：git clone https://gitee.com/kira905/dsh-firstaid.git firstaid
cd firstaid
node firstaid.mjs --list # 看到症状菜单就算装好了
第 3 步 · 告诉它你的环境（可选但强烈建议）
工具默认按「数据根 = ~/.dsh」工作。如果不对，用环境变量指一下：
例：数据根、工作区、被诊断服务的端口
export FIRSTAID_HOME=/srv/myservice/.data
export FIRSTAID_WORKSPACE=/srv/myservice
export FIRSTAID_PORT=3080
node firstaid.mjs --symptom 1
Windows PowerShell：
$env:FIRSTAID_HOME = ':\myservice\.data'
node .\firstaid.mjs --symptom 1
不想每次设环境变量，就把它们写进自己的启动脚本——本工具不读任何私有的全局配置文件，这是故意的（避免"配置漂移"导致的误诊断）。
四、怎么用
4.1 日常：跑一个症状
node firstaid.mjs --symptom 1 # 起不来
node firstaid.mjs --symptom 3 --days 14 # 想撤销改动（看 14 天时间轴）
node firstaid.mjs --symptom 5 --json # 一键体检包（含机读 JSON 段）
报告落在日志目录（默认 /logs），同时写一份 .log 流水。屏幕输出与报告内容一致（--quiet 只打判据与建议）。
4.2 出事前：把恢复点演练过
未演练的恢复脚本不会被列为「可一键执行」——这条纪律是本工具设计的核心，不是可选项。
L1 沙箱级（默认档，任何恢复点都该过）：只验证「备份源确实能还原目标」，并强断言目标文件 hash 前后一致
node drill.mjs --point "" --target ""
L2 真实级：真造坏 → 真跑恢复 → 真验活 → 无论成败都还原现场
node drill.mjs --point "" --target "" --restore "" --live --yes
演练记录 drill-record-.md/.json 落在回滚点目录内，时间轴与索引会自动读到它。
4.3 收尾：生成回滚索引
node rollback-index.mjs --write # 生成 /README-回滚索引.md
node rollback-index.mjs --check # 巡检：索引与实况是否一致（不一致退出码 3）
node rollback-index.mjs --refs # 归档/改名前的全量引用扫描
五、配置表（CLI > 环境变量 > 默认值）
数据根解析顺序：FIRSTAID_HOME > DSH_HOME > ~/.dsh（空串/纯空白一律视为未设置，逐级回落）。
| 用途 | 环境变量 | 默认值 |
|---|---|---|
| 数据根 | FIRSTAID_HOME / DSH_HOME | ~/.dsh |
| 工作区（工具链/文档树） | FIRSTAID_WORKSPACE / DSH_WORKSPACE | 未配置（不猜） |
| 日志目录 | FIRSTAID_LOGS | /logs |
| 变更流水目录 | FIRSTAID_CHANGELOG | /changelog |
| 回滚点根 | FIRSTAID_ARCHIVE_ROOT | /_archive |
| 恢复脚本落地目录 | FIRSTAID_LANDING | /landing |
| 冷盘（离线介质）上的回滚点镜像 | FIRSTAID_ROLLBACK_ROOT / ROLLBACK_POINTS_ROOT | /rollback-points |
| 被诊断服务端口 | FIRSTAID_PORT | 3080 |
| 本机其它实例端口（附带检查） | FIRSTAID_OTHER_PORTS | 空 |
| 守护进程命令行特征（正则字符串） | FIRSTAID_GUARD_PATTERN | guard |
| 守护进程状态文件 / 日志 | FIRSTAID_GUARD_STATE / FIRSTAID_GUARD_LOG | /guard/{guard-state.json,guard.log} |
| 启动日志文件名模式（正则字符串） | FIRSTAID_LOG_PATTERN | 任意 .log |
| 冷盘落点表 | FIRSTAID_COLD_ROOTS | 空（未配置时报告如实写「未配置」，不假装有备份） |
| 镜像/备份落点表 | FIRSTAID_MIRROR_ROOTS | 工作区 backups/ + 数据根 _archived-sessions/ |
| 备份来源清单（症状 4 的建议） | FIRSTAID_BACKUP_SOURCES | 三条中性提示 |
| 影响面分类规则 | FIRSTAID_IMPACT_RULES | 内置中性表（配置/依赖/数据/启动链/文档/工具链/会话） |
| 停机 / 重启判据 | FIRSTAID_STOP_PATTERNS / FIRSTAID_RESTART_PATTERNS | 内置中性默认 |
| 设备标记词表（时间轴标题剥离） | FIRSTAID_DEVICE_TAGS | 空（只剥离「通用方括号前缀」与「设备：xxx」形态） |
| 历史线索目录（自愈报告等） | FIRSTAID_KB_DIR | /repair-knowledge |
多值写法：分隔符 , ; | 三者等价，例如 FIRSTAID_COLD_ROOTS='archive=:\rollback-points;keys=:\keys'。
也接受 JSON 数组形态（[{"name":"...","root":"..."}]）。
5.1 时间轴的输入格式（变更流水）
时间轴读变更流水文件：/YYYY-MM.md。解析口径固定：
- 条目起点 = 行首 - （- 09:00 xxx），续行自动归上一条；
- 字段用全角竖线 ｜ 或半角 | 分隔；
- 条目里出现 _archive\\ 形态的路径 → 视为备份线索；
- 出现 restore-.cmd|mjs|ps1 → 视为回滚入口。
没有流水也能用：直接把它们放在回滚点根下，工具会按目录名的时间戳兜底识别，并标注为「未登记改动」。
六、核心纪律（读一遍再动手）
1. 默认只诊断：本工具除写自己的报告/日志外，不改任何文件。回滚、重启、杀进程都不做。
2. 未演练不得一键：恢复脚本没跑过演练（回滚点内没有 PASS 演练记录）→ 只登记、不列入可一键项。
3. 缺备份不得一键：备份不在本机 / 只找到一部分 → 标红并禁一键（不许假装能回滚）。
4. 失败冻结现场：任何写动作前先备份；失败不无限重试，报告里给「冷却」提示。
5. 不猜环境：冷盘没配就是「未配置」，日志目录没配就用默认值；宁可说"不知道"，也不假装知道。
七、兼容性
| 平台 | 状态 | 说明 |
|---|---|---|
| Windows 10/11 | ✅ 实测 | 进程枚举用 PowerShell CIM（回落 wmic / tasklist），端口用 netstat |
| macOS | ⚠️ 未实测 | 路径与配置层是跨平台写法，但进程/端口探针依赖 Windows 命令，需要适配 |
| Linux | ⚠️ 未实测 | 同上 |
| 依赖 | 要求 |
|---|---|
| Node.js | 18+（实测 24.x） |
| npm 包 | 零（全部用 node 内置模块；单测有运行时拦截层，加载第三方包即报错） |
八、已知限制（如实列出）
1. 非 Windows 平台的进程/端口探针未实现：tasklist / netstat / PowerShell CIM 都是 Windows 命令；其他平台会走「无法判定」分支并如实标注（不会静默当成 0）。
2. 单测里的夹具日期是固定的：_test/fixtures.mjs 的夹具条目落在 2026-09-10 附近；用默认 --days 7 跑时间轴时，若当前日期离夹具日期超过 7 天，B17/B18/B21/C19 四条会失败。这是用例的时间脆性，不是判据坏了（探针见交付报告：把窗口放大到 30 天后立即判红）。
3. --run 只做预检，不执行回滚：本版本一律拒绝真执行（红线：只读诊断）。
4. 不做跨机同步：备份是否"在别处"由你自己的备份介质回答；工具只实测本机可见的落点。
5. 变更流水格式是固定的：不按这个格式写的日志，时间轴解析不到（会记「解析提示」，不静默）。
6. 没有 GUI：Windows 下有可选的交互菜单外壳（firstaid-launch.ps1），其余平台走命令行。
7. rollback-index --refs 是浅层扫描：默认只扫工作区的 docs/、tools/ 与数据根，不做全盘搜索。
九、发布前自检
语法 + 配置层 + 脱敏扫描（注入词表只走环境变量，源码里一个字都不写）
BUILD_MACHINE_NAMES='...' BUILD_USER_NAMES='...' node scripts/verify-source.mjs .
阳性对照：故意注入一个必然存在的串，必须报红（证明规则真的在跑）
node scripts/verify-source.mjs . --positive-control
单测（全部在系统临时目录里跑，不碰真实数据）
node _test/test-firstaid-run.mjs
node _test/test-drill.mjs
node _test/test-rollback-index.mjs
注入词表里的值只存在于你的命令行（或 CI secret），不会写进仓库。
十、许可
本仓以 MIT 许可发布（全文见 LICENSE）：你可以自由使用、修改、再分发，包括嵌入自己的闭源工具与 CI，只需保留版权与许可声明。
背景说明（透明化）：本仓最初派生的草稿曾以 AGPL-3.0-only 作为占位（定稿前的临时状态）。该占位版本从未对外分发（未推送、未发布）；对外首发的即是本 MIT 版本。三处口径（LICENSE / README / package.json 的 license 字段）已同步为 MIT。
十一、与内部版的默认值差异（从内部版派生而来时必读）
| 项 | 内部版默认 | 本仓默认 | 怎么恢复内部版行为 |
|---|---|---|---|
| 数据根 | 固定工作区路径 | FIRSTAID_HOME > DSH_HOME > ~/.dsh | 设 DSH_HOME 或 FIRSTAID_HOME |
| 变更流水目录 | /docs/变更流水 | /changelog | 设 FIRSTAID_CHANGELOG |
| 恢复脚本落地目录 | 桌面上的固定目录 | /landing | 设 FIRSTAID_LANDING |
| 守护进程状态/日志 | 系统临时目录 | /guard/ | 设 FIRSTAID_GUARD_STATE / FIRSTAID_GUARD_LOG |
| 其它实例端口 | 内置一串固定端口 | 空 | 设 FIRSTAID_OTHER_PORTS |
| 冷盘 / 镜像落点 | 按主机名硬编码盘符 | 空 / 由 home+工作区推出 | 设 FIRSTAID_COLD_ROOTS / FIRSTAID_MIRROR_ROOTS |
| 影响面分类、停机判据、设备标记 | 内含具体项目与主机名 | 中性默认表 | 用 FIRSTAID_IMPACT_RULES / FIRSTAID_STOP_PATTERNS / FIRSTAID_DEVICE_TAGS 注入 |
恢复脚本自身、_archive 目录名、restore-*.{cmd,mjs,ps1} 命名约定、时间轴解析口径 —— 这些是设计语义，未改。