栈体检 LuminariSoftwares/stack-guardian

stack-guardian

家庭 AI 技术栈的健康医生。它采集节点快照（Ollama 端点、已加载模型、NVIDIA GPU、tailnet 对等节点），拿一小撮 Python 规则去跑，记住最近几次运行结果，最后给出带置信度等级的发现：只采样一次，最高只能到 LIKELY；同一个发现连续出现两次，就是 VERIFIED。每条发现可以带一个带类型的修复动作，由你手动执行，绝不自动跑。

状态：0.1.0，首个版本。 只用标准库，Python 3.11+。

安装

pip install stack-guardian

装完你会得到三个命令：stack-guardian（命令行）、stack-guardian-serve 和 stack-guardian-mcp。

先离线试一把：示例快照能让每条内置规则都触发一次。

curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json
curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json
stack-guardian doctor --snapshot snapshot.json --ctx ctx.json

也可以从克隆的仓库跑（想写规则或跑测试就用这种方式）：

git clone https://github.com/LuminariSoftwares/stack-guardian.git
cd stack-guardian
python -m venv .venv
.venv\Scripts\activate # Windows; macOS/Linux: source .venv/bin/activate
pip install -e .
stack-guardian doctor --snapshot examples/snapshot.json --ctx examples/ctx.json

给编码智能体用

- MCP 服务器（任何 MCP 客户端都能接）：stack-guardian-mcp 通过 stdio 讲 MCP，带三个只读工具：stack_health、stack_snapshot 和 explain。在 Claude Code 里：

claude mcp add stack-guardian -e STACK_GUARDIAN_NODES=/path/to/nodes.json -- stack-guardian-mcp

其他客户端：命令填 stack-guardian-mcp，参数填 ["--nodes", "/path/to/nodes.json"]。stack_health 会对照已保存的运行历史打分，但不会往历史里写；同一份快照 10 秒内复用（--ttl SECONDS）。
- DSH 插件（npm install dsh-stack-guardian，源码在 dsh/，需要 Node 20+）：当医生报出 WARN 或 FAIL 时，在 DeepSeek Harness 会话开头加一行提示，其他情况什么都不加。它跑的是 stack-guardian doctor --json --quiet，所以要在 harness 环境里把 STACK_GUARDIAN_NODES 指向你的节点文件。

它能做什么

1. doctor - 跑检查

用一个 JSON 文件描述你的节点（见 examples/nodes.json），然后实时检查：

stack-guardian doctor --nodes examples/nodes.json --ctx examples/ctx.json

--snapshot 和 --nodes 都不给时，doctor 会读 $STACK_GUARDIAN_NODES 指向的节点文件。
选项：--checks-dir DIR（你自己的规则，默认是随附的 checks.d）、--ctx FILE（规则设置，比如每个节点应持有的模型）、--state FILE（默认 $STACK_GUARDIAN_STATE 或 ~/.stack-guardian/state.json）、--json、--quiet（一切正常时不输出任何内容）。

退出码：0 全部 OK/INFO，1 出现 WARN，2 出现 FAIL，3 用法错误，4 doctor 自身崩溃。

随附规则：node.unreachable、ollama.unreachable、model.not_loaded、vram.unattributed、gpu.unavailable、tailnet.unavailable、tailnet.peer_offline、tailnet.relayed。每条规则对每个受影响的节点产生一条 finding。规则抛异常会变成 check.crashed WARN——有 bug 的规则绝不会误报整个 stack 出问题。

2. doctor --fix ID - 运行 finding 的类型化修复

规则可以给 finding 附加 fix={"action": ..., "args": {...}}。动作恰好有三种，绝不允许裸 shell 字符串：

| action | 做什么 | 需要 |
| unload_model | 向 Ollama 的 /api/generate POST keep_alive: 0 | node、url、model |
| restart_lane | 运行你为该 lane 声明的 argv 列表 | 在 --config 中声明的 lane |
| set_env | 把 NAME=value 写入 <state folder>/env，并为进程设置它 | name、value |

stack-guardian doctor --checks-dir examples/checks.d --snapshot examples/snapshot.json --fix ollama.stuck --config examples/lanes.json

这是试运行：只打印计划，不做任何改动。加上 --apply 才会真正执行。执行修复时，先把快照保存到 <state folder>/snapshots/，然后运行，再向 <state folder>/fixes.jsonl 追加一行 JSON（用 --audit FILE 可改路径）。set_env 的值绝不写入审计日志，只写它的长度。ID 是 finding 代码，多个节点抛出同一代码时用 code@node。带 --fix 时，退出码是修复本身的：0 计划成功或执行成功，1 被拒绝或失败，3 用法错误。

3. 其他命令

- stack-guardian snapshot --nodes FILE 打印规则读取的原始快照。
- stack-guardian-serve --nodes FILE [--port 8788] 在 GET /snapshot 提供最新快照（只读，默认绑定 loopback，除非你传 --host H --allow-remote），这样一台机器就能向另一台询问健康状况。
无认证：只绑定 localhost 或 tailnet IP。
- stack-guardian-mcp --nodes FILE [--ctx FILE] [--state FILE] [--ttl SECONDS]：见 For coding agents。

编写规则

from stack_guardian import finding as F

def ollama_up(snapshot, ctx):
if not snapshot["nodes"]["gpu-box"].get("reachable"):
return F.make_finding("ollama.unreachable", "missing", "FAIL", "gpu-box", "Ollama does not answer")
return None

CHECKS = [("ollama.up", ollama_up)]

把文件放进某个文件夹，让 --checks-dir 指向它。带修复的完整示例见 examples/checks.d/20_ollama_fix.py。规则也可以返回 finding 列表，每个节点一条。

示例

| file | what it is |
| examples/nodes.json | 三个节点：一个本地节点带 GPU，两个远程节点走 tailnet |
| examples/ctx.json | 规则设置：gpu-box-2 该持有哪个模型 |
| examples/snapshot.json | 一份离线快照，每条内置规则都会触发一次，用来试 doctor 和 --fix |
| examples/lanes.json | restart_lane 允许跑的 lane |
| examples/checks.d/20_ollama_fix.py | 自定义规则，它的发现结果自带修复方案 |

Test

pip install pytest
python -m pytest -q

CI 在 Ubuntu、Windows 和 macOS 上跑这套测试，Python 版本为 3.11，另外还会对每个纳入版本控制的文件做一次隐私扫描。

License

MIT