DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

kira905 /

kira905/dsh-firstaid

Topic repository only

只读急救台:起不来 / 假死 / 要撤销 / 数据被删,四类现场压成一个入口,产出能整段交给别人的现场报告 · Read-only incident console for long-running agent hosts: stuck services, frozen UI, rollbacks, data loss — one entry point, hand-off-ready report. Zero dependencies.

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

firstaid · 急救台

这是什么

一个只读的「急救台」:Agent 起不来、界面假死、刚改的东西想撤销、数据被误删 —— 四类现场压成一个入口。

它解决什么

长期跑着的助手出事时,最缺的不是修复手段,是判断依据:到底是服务挂了、端口被占、还是刚才那次改动?这个工具把进程 / 端口 / 状态文件 / 日志尾 / 崩溃次数 / 最近改动一次收齐,给出三条处置建议,并落一份能整段交给别人的现场报告。

一条命令跑起来

npm i -g @kira905/dsh-firstaid
firstaid --list            # 先看症状菜单
firstaid --symptom 5       # 不知道怎么了 → 一键生成体检包

先看它长什么样(真实输出)

firstaid v0.1(只读诊断 · 零第三方依赖)—— 出事时只有这一个入口
症状菜单:
  1) 打不开 / 起不来 —— 守护进程数 · 服务端口 · 状态文件 · 日志尾部 · 崩溃次数 → 三条处置建议
  2) 界面假死 / 一直转圈 —— 连接池与进程诊断 → 指向「完全退出 Chrome 重开」/ 重启闸门
  3) 刚改完的东西想撤销 —— 改动时间轴(选序号回滚;缺备份标红禁一键)
  4) 数据 / 文件被删 —— 指到冷盘与镜像备份,给出可恢复范围
  5) 不知道怎么了 —— 一键生成「体检包」→ 交给 agent

默认只读,不改任何东西。装法与三条只读自检见下方「装完自检」。

它不附带什么(先看清楚,省得装完失望)

这套开源出来的是能用的工具 + 装完自检 + 设计文档。有两块不在开源范围里:

  1. 「自己盯着活干」的那套引擎:定时调度、队列盯守、管家日报、自主决定要不要动手 —— 这几件还没整理出来放(整理完会陆续放)。它的设计本身是公开的,写在 ops-handoff-design 仓里,想自己实现的人照着做得到。
  2. 「出事喊到人」的通道:企业微信、语音播报这类 —— 不随开源发布。

所以:装完你拿到的是一套能用的工具,不是一个会自己上班的管家。


本仓是命令行工具,不挂宿主界面,不需要 dsh.bundle、不需要写 cordis.patch.yml。 装它 = npm i -g @kira905/dsh-firstaid(或 npx -p @kira905/dsh-firstaid firstaid)。装进 profile 也对,但那条 declares no dsh.bundle 警告是正常现象,不是故障。

装完自检(三条只读验法)

<profile> 换成你实际用的 profile(默认 web),<数据根> 换成你的 DSH 数据根(默认 ~/.dsh)。

# ① 组合树里有没有它(只读、约 0.6 秒、不启服务)
dsh --profile <profile> --dump-config | Select-String "dsh-firstaid"
# 期望:bundle 层出现一行 "# == <登记名>"、insert 层出现 "- id: <entry>"(问的都是「它挂上没」);
#       本仓包名 @kira905/dsh-firstaid —— 带 scope 装的写带 scope 名、老工装 / 手写的可能是裸名,两种都搜一遍
#       ⚠️ 若该包会 insert 一行,还要数一遍"同一个 id 出现了几次",必须 == 1

# ② 组合列表里有没有它(只读)
Get-Content <数据根>/profiles/<profile>/package.json | Select-String "@kira905/dsh-firstaid"
# 期望:dependencies 与 dsh.profile.bundles 两处都有(CLI 类只需要 dependencies;bundles 里也可能写裸名 dsh-firstaid)

# ③ 命令在不在 —— 【只查存在,不执行】
Test-Path <数据根>/profiles/<profile>/node_modules/.bin/firstaid.CMD   # 装进 profile 的
Test-Path "$env:APPDATA\npm\firstaid.CMD"                           # npm i -g 装的
# 期望:True。两条路径按你实际用的装法挑一条

探针只做存在性检查(只看命令文件在不在,不执行任何命令)。 要不要用 --help 验,见本仓当前说明与该命令的参数表。


English: README.en.md

出事时只想知道「跑哪个」——这个工具把「起不来 / 界面假死 / 要撤销改动 / 数据被删」四类现场压成一个入口, 产出一份可整段交给 AI 或同事的现场体检报告。

默认只诊断,不动手。 任何回滚/重启都是写动作,必须有人确认;而且没演练过的恢复脚本永远不会被列进「可一键执行」。

  • 零第三方依赖:只用 Node 内置模块(宿主/主包挂了,它照样能跑)
  • 只读为主:除写自己的报告/日志外,不改任何被诊断的对象
  • 三档演练:L1 沙箱(必做)/ L2 真实(造坏→恢复→还原)/ L3 需停机
  • 机读友好:每份报告都有固定字段,退出码即结论(0 正常 / 1 有异常 / 2 用法 / 3 环境不可用)

设计依据

本工具是「ops-handoff-design」所述运维体系的一个实现, 设计依据(对应文档仓约定的固定四问):

  • 它为什么存在、边界在哪 → 见《体系全景与家规》§4 家规(其中"回滚演练"那条纪律要求:没演练过的恢复脚本不许列进一键执行——本工具的 L1/L2/L3 三档演练与"只诊断优先"正是这条纪律的实现),以及《放行判据与开关矩阵》§3 执行矩阵(动作 → 风险级 → 开关 → 护栏 → 放行判据:不可逆动作必须有人确认)
  • 它与宿主版本的兼容区间 → 见《多机交接与云中继》§4.5「兼容性要求」(另见本 README 第七节「兼容性」)
  • 本组件特有的坑与实测 → 见本 README「核心纪律」与「已知限制」两节;本仓的 _test/演练脚本即"自证可用"那一环
  • 文档仓地址 → Gitee(镜像)https://gitee.com/kira905/ops-handoff-design | GitHub(主)https://github.com/kira905/ops-handoff-design (文档仓的组件索引表回指本仓;两仓互链、版本各自独立)

设计稿里不写具体仓库地址(写死即死链),实现清单统一收在文档仓的组件索引表里——本仓只负责回链章节。


一、这工具治什么病

症状 它能回答的问题
服务打不开 / 起不来 守护进程在不在、端口有没有人听、进程活着吗、日志尾部报了什么
界面假死 / 一直转圈 是服务端真故障,还是浏览器侧连接池/GPU 争用(90% 是后者)
刚改完的东西想撤销 最近几天改了什么、每条的备份还在不在、该跑哪个恢复脚本、要不要停机
数据 / 文件被删 哪些备份介质真的在位、可恢复范围是什么(不承诺不可恢复的东西)
不知道怎么了 一键生成体检包(进程/端口/日志尾/最近改动/备份可用性/演练状态)

反过来,它不做这些事:不替你回滚、不替你重启、不猜你的环境、不在没备份时假装有备份。


同源说明

本仓部分文件与一套内部生产实现同源(同一份工程长期演进下来的两处落点)。

  • 同源程度:按行级同源度口径统计(同名可比件里,仓内文件的非空行有多少能在参照件中找到,多重集扣减),本仓「≥50% 行同占比」= 93%。
  • 这意味着:本仓是那套实现的提炼导出 —— 既不是逐字副本,也不是完全重写的独立实现。拿单个文件当"独立参考实现"读之前,请先跑下面的判据。
  • 怎么复跑:同源度扫描器见 dsh-quality-toolkit 的 dsh-sim-scan.mjs(--repo <本仓> --prod-root <参照根>);分档阈值与口径写在它的 config/sim-scan.json 里,不藏在代码里。
  • 许可:本仓许可见仓根 LICENSE(有子树例外时以子树 LICENSE 为准)。

二、目录结构

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 步 · 取到本地

# 方式 A(推荐):从 npm 装(装完直接用 firstaid / firstaid-drill / firstaid-timeline / firstaid-rollback-index)
npm install -g @kira905/dsh-firstaid
firstaid --list                   # 看到症状菜单就算装好了

# 方式 B:从 git 克隆(要改源码 / 不想全局装时)
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. 不猜环境:冷盘没配就是「未配置」,日志目录没配就用默认值;宁可说"不知道",也不假装知道。

七、兼容性

项 状态 说明
DSH 主包 0.2.0-rc.2 ✅ 已在隔离实例上真跑(2026-10-16) node firstaid.mjs --symptom 1 在独立数据根下执行成功(rc=1:命中一项异常并产出体检报告 + 日志到该数据根)。⚠️ 本仓是独立 CLI 工具(零第三方依赖、不 import 任何 @deepseek-ai/dsh-* 包)⇒ 不声明 peerDependencies —— 声明会误导成"与宿主版本绑定";本行只记录实测过的环境
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),不会写进仓库。


十、许可

本仓以 AGPL-3.0-only + 商业授权(双许可)发布(全文见 LICENSE)。

  • ⚠️ AGPL-3.0 本身不禁商用:你可以自由使用、修改、再分发(含商用),条件是修改版若通过网络向他人提供,必须按 AGPL 一并提供对应源码;
  • 「+ 商业授权」= 双许可:若你需要在闭源或商业场景中使用(AGPL 的传染条款不适用),可另行取得商业授权 —— 本仓暂无公开联系邮箱,请通过本仓 Issue 联系。

许可变更记录(透明化):本仓 v0.1.0 ~ v0.1.2 以 MIT 发布;自 v0.1.3 起改为 AGPL-3.0-only + 商业授权。已经按 MIT 发布的版本,他人已获得的授权收不回 —— 许可变更只约束未来版本。三处口径(LICENSE / 本段 / package.json 的 license 字段)已同步。


十一、与内部版的默认值差异(从内部版派生而来时必读)

项 内部版默认 本仓默认 怎么恢复内部版行为
数据根 固定工作区路径 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} 命名约定、时间轴解析口径 —— 这些是设计语义,未改。


相关组件

同属 DSH 生态的伴生组件,各自独立仓、独立版本、许可各自独立;它们都回链到同一份文档仓 ops-handoff-design (Gitee 镜像 https://gitee.com/kira905/ops-handoff-design):

组件仓 做什么 与本组件的关系
dsh-firstaid 零依赖急救台:起不来 / 假死 / 要撤销改动 / 数据被删 本仓
dsh-ecosystem-panel 只读生态健康面板(六类体检一屏看完) 日常与应急的分工:它回答**「今天怎么样」(持续、只读、三色),本仓回答「现在坏了、下一步做什么」(一次性、可整段交出去的报告)——而且面板自己坏了的时候,本仓是它的兜底**
dsh-diagnostic-tools 依赖闭包 / 解耦体检 + 会话图片附件对账 同属"只诊断不动手",但场景不同:它做离线专项取证(升级前后主动跑),本仓做现场四类症状的分诊(已经出事时先跑)
dsh-butler-archive 会话归档管理(列表 / 预览 / 恢复 / 删除 + 可选自动归档) 本仓「要撤销改动 / 数据被删」两类现场里,最常撞上的就是会话与归档面;本仓只负责如实标注恢复脚本演练过没有,不替谁回滚
dsh-session-title-live 会话标题随对话实时刷新 + 回合边界状态前缀 本仓的体检报告要回答"最近哪些会话没走完",标题轴是那份清单可读性的来源
dsh-task-board-local 自维护任务看板(卡片 = 一次真实会话 + 人工验收闸) 反过来看:长跑体系的日常编排在它那儿,出事时它自己也可能卡住——本仓负责把现场压成一份能交出去的报告

组件之间没有代码依赖,也不共享运行时 —— 之所以互指,是因为它们回答的是同一类人的同一批问题 (长期在自有机器上跑 agent:装得下、找得到、看得见、查得清)。谁装谁不装,互不影响。

—/ 5

No ratings yet

Manifest verification required

Commit f575c7736a74

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