DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

kira905 /

kira905/dsh-firstaid

Topic repository only

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. | 零依赖急救台：起不来 / 假死 / 要撤销改动 / 数据被删四类现场压成一个入口，产出可整段交出去的体检报告

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@0ba303f0

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 "<恢复脚本.mjs>" --live --yes

演练记录 drill-record-<ts>.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。解析口径固定：

  • 条目起点 = 行首 - <HH:MM>（- 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} 命名约定、时间轴解析口径 —— 这些是设计语义，未改。

—/ 5

No ratings yet

Manifest verification required

Commit 0ba303f004d0

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout