内容
<div align="center">
# <span style="color:#00d992">⚡ agent-vitals</span>
### <span style="color:#f2f2f2">给你的AI代理一个属于自己的基础设施记忆。</span>
<p>
<a href="https://github.com/anirudhprashant/agent-vitals/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-00d992?style=flat-square" alt="许可证"></a>
<a href="https://github.com/anirudhprashant/agent-vitals/releases"><img src="https://img.shields.io/badge/version-v0.5.0-3d3a39?style=flat-square" alt="版本"></a>
<a href="https://github.com/anirudhprashant/agent-vitals"><img src="https://img.shields.io/badge/python-3.11%2B-2fd6a1?style=flat-square" alt="Python"></a>
<a href="https://github.com/anirudhprashant/agent-vitals"><img src="https://img.shields.io/badge/LOC-%7E2700-8b949e?style=flat-square" alt="LOC"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-stdio-00d992?style=flat-square" alt="MCP"></a>
</p>
<p>
<code style="color:#00d992">5 MCP 工具 · 6 CLI 工具</code>
·
<code style="color:#b8b3b0">wires pi · Claude Code · Cursor · OpenCode · Codex CLI</code>
·
<code style="color:#b8b3b0">~2700 LOC · 200 测试 · MIT · 无守护进程 · 无云</code>
</p>
<p>
<a href="https://anirudhprashant.github.io/agent-vitals/" style="color:#00d992">→ 官方网站 (anirudhprashant.github.io/agent-vitals)</a>
</p>
</div>
---
## <span style="color:#00d992">▍</span> 代理可见的内容
当你的代理（pi、Claude Code、OpenCode、Cursor、Codex）调用 `vitals_summary` 时，它会得到：
```text
▄▀ agent-vitals — 本地代理堆栈健康状况
shadow: 13 个自主事物已配置（mcp: 8, systemd: 5）
子代理 burnout（7天）：5次运行，100%完成 ✓
claude code（7天）：170次会话，45,626次事件，⚠ 36次卡住
- 最大的卡住会话：7,118次事件
```
这不是一个CLI命令。你看到的是一个工具，你的代理在自己的循环中调用它 - 在执行任何有风险的操作之前。
---
## <span style="color:#00d992">▍</span> 前后对比
<table>
<tr>
<th width="50%" align="left"><span style="color:#fb565b">▍ 没有 agent-vitals</span></th>
<th width="50%" align="left"><span style="color:#00d992">▍ 有 agent-vitals</span></th>
</tr>
<tr>
<td valign="top">
```text
用户：每天凌晨2点安排一个备份
代理：好的，已经完成。
0 2 * * * /home/me/backup.sh
>> /tmp/backup.log 2>&1
```
… 而 `/home/me/backup.sh` 文件不存在。Crontab 静默失败，永久失效。
</td>
<td valign="top">
```text
用户：每天凌晨2点安排一个备份
代理：稍等，正在验证。
→ shadow_stale （无其他cron损坏）
→ 检查 backup.sh （存在？可写？）
→ 编写 crontab 条目
→ shadow_stale （确认无损坏）
✓ crontab 已更新。
```
</td>
</tr>
<tr>
<td valign="top">
```text
用户：我的代理设置健康吗？
代理：看起来不错。
```
（盲目猜测）
</td>
<td valign="top">
```text
用户：我的代理设置健康吗？
代理：→ vitals_summary
shadow: 13 个自主事物已配置
claude code（7天）：⚠ 36次卡住会话
- 最大：7,118次事件
⚠ 36个会话看起来卡住了。您要我进行故障排除吗？
```
</td>
</tr>
</table>
差异是 **氛围 vs. 数据**。
---
## <span style="color:#00d992">▍</span> 安装
```bash
uv tool install git+https://github.com/anirudhprashant/agent-vitals
av init # 检测您主机上的所有代理并连接它们
# 重启您的代理主机以使其获取新的MCP服务器
```
这就是整个设置过程。<span style="color:#00d992">30秒。</span>
---
## <span style="color:#00d992">▍</span> 预动作钩子（v0.3.0）
预备过程询问代理调用vitals。**钩子拒绝操作**，如果它没有。
```bash
av hooks install # 一次性设置（~3秒）
av hooks status # 检查新鲜度
av hooks disable # 暂时关闭（重命名为*.disabled）
av hooks uninstall # 完全移除
```
在 `av hooks install` 后，上述一行代码将被追加到您的 `~/.bashrc` / `~/.zshrc` 中。打开一个新的终端并运行 `crontab -e` 或 `systemctl --user enable foo` 将在**操作系统级别**被**拒绝**，除非一个代理（或 `av doctor`）在最近60秒内刷新了vitals时间戳。
```text
⚡ agent-vitals 钩子：拒绝 `crontab -e`
原因： vitals 时间戳是5m12s旧的 - 超过60s窗口。
时间戳： 5m12s前
刷新： 调用任意vitals工具或运行 `av doctor`
绕过： VITALS_BYPASS=1 crontab -e
```
**被阻止的内容：** `crontab -e/-r/-i/<file>/-` 和 `systemctl --user {enable,disable,start,stop,restart,reload,mask,unmask,daemon-reload,...}`.
**未被阻止的内容：** `crontab -l`（读取），`systemctl status / list-* / is-active / show / cat`（读取），以及电源管理（`reboot`，`poweroff`，`suspend`）- 旧时间戳永远不会阻止重启。
**紧急情况的绕过：** `VITALS_BYPASS=1 crontab -e` 跳过检查。
## <span style="color:#00d992">▍</span> `av init` 的作用
```text
$ av init
检测到 3 个代理主机
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ 主机 ┃ 配置 ┃ 状态 ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ pi │ /home/anirudh/.pi/agent/mcp.json │ 检测到 │
│ Claude Code │ /home/anirudh/.claude/.mcp.json │ 检测到 │
│ Codex CLI │ /home/anirudh/.codex/config.toml │ 检测到 │
└─────────────┴──────────────────────────────────┴────────━━┘
安装中：
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ 主机 ┃ mcp 配置 ┃ 技能/规则 ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ pi │ 已添加 │ 已安装 ┃
│ Claude Code │ 已添加 │ 已安装 ┃
│ Codex CLI │ 已添加 │ 已安装 ┃
└─────────────┴────────────────────┴────────────────━━━┛
✓ 完成。重启您的代理主机。
```
| 主机 | MCP 配置 | 预备 |
|---|---|---|
| <span style="color:#00d992">**pi**</span> | `~/.pi/agent/mcp.json` | `~/.claude/skills/agent-vitals/SKILL.md` |
| <span style="color:#00d992">**Claude Code**</span> | `~/.claude/.mcp.json` | `~/.claude/skills/agent-vitals/SKILL.md` |
| <span style="color:#00d992">**Cursor**</span> | `~/.cursor/mcp.json` | `~/.cursor/rules/agent-vitals.md` |
| <span style="color:#00d992">**OpenCode**</span> | `~/.config/opencode/mcp.json` | `~/.config/opencode/AGENTS.md` |
| <span style="color:#00d992">**Codex CLI**</span> | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
> [!NOTE]
> 幂等。随时重新运行 `av init` - 现有条目被跳过，永远不会重复。TOML 配置（Codex CLI）获取 TOML 部分；JSON 配置获取 JSON 条目。
---
## <span style="color:#00d992">▍</span> 五种工具
| 工具 | 返回 | 代理应该何时调用它 |
|---|---|---|
| `vitals_summary()` | 普通文本 | **总是首先** - 健康检查，任务前，卡住时 |
| `shadow_list()` | JSON 数组 | 基础设施更改前 - 查看用户代表下运行的所有内容 |
| `shadow_stale()` | JSON 数组 | 在声称“您的crontab正常”或调度新cron工作之前 |
| `burnout_summary(days=7)` | JSON 对象 | 长任务后，与基线进行比较 |
| `burnout_stuck_sessions(days=7, limit=10)` | JSON 数组 | 当怀疑循环时，查看其他会话是否也卡住 |
所有工具都是**仅本地，只读，安全调用多次**。它们都不修改状态。
---
## <span style="color:#00d992">▍</span> 触发器表
`av init` 安装的表格到您的预备技能中 - 以便代理知道何时调用每个工具 **而无需您询问：**
| 触发器 | 工具 |
|---|---|
| 启动任何非琐碎任务 | `vitals_summary` |
| 即将安排cron / timer / systemd工作 | `shadow_stale` |
| 长任务完成后 | `burnout_summary` |
| 怀疑自己处于循环中 | `vitals_summary` + `burnout_stuck_sessions` |
| 用户询问“X是否正常？” | `shadow_list` 或 `vitals_summary` |
| 即将声称“所有cron都正常” | `shadow_stale`（先验证） |
| 即将推荐MCP安装 | `shadow_list`（检查重复项） |
| 用户询问“什么坏了？” | `vitals_summary` → `shadow_stale` + `burnout_stuck_sessions` |
> [!WARNING]
> **诚实笔记。** 预备不是强制的。SKILL.md 将这些触发器放在代理的面前，但代理仍然需要**记住**遵循它们。实际上，这可以捕获 ~30–40% 的情况 - 比没有更好，而不是一个神奇的子弹。
>
> **v0.3.0 更改此内容。** `av hooks install` 部署 `crontab` 和 `systemctl --user` 周围的 PATH 级包装器，它们在vitals时间戳超过60秒时**拒绝**任何更改。读取操作（`crontab -l`，`systemctl status`等）永远不会被阻止。参见下面的 [预动作钩子](#预动作钩子-v030)。
---
## <span style="color:#fb565b">▍</span> 此工具防止的反模式
> [!IMPORTANT]
> 这些是导致我们构建 agent-vitals 的故障模式。如果您看到代理执行以下任何操作，则表明预备措施没有达到代理 - 或者他们需要 **v0.3.0 钩子**。
- ❌ **“您的crontab正常”** - 在调用 `shadow_stale` 之前
- ❌ **调度cron / systemd工作** - 在验证目标二进制文件是否存在之前
- ❌ **启动4小时任务** - 同时其他6个会话卡在同一台机器上
- ❌ **假装任务完成** - 在检查 `burnout_summary` 之前
- ❌ **推荐MCP安装** - 在使用 `shadow_list` 检查重复项之前
- ❌ **调试缓慢** - 在首先检查 `vitals_summary` 之前
---
## <span style="color:#00d992">▍</span> 它扫描的内容
| 来源 | 路径 | 它发现的内容 |
|---|---|---|
| Crontab | `crontab -l` | 标记不再存在的目标 |
| systemd 用户计时器 | `systemctl --user list-timers` | systemd-v255 怪癖抵抗性（自己计算 `next - now`） |
| MCP 配置 | `~/.pi/agent/mcp.json`，`~/.claude/.mcp.json`，`~/.cursor/mcp.json`，`~/.config/opencode/mcp.json` | 每个主机注册一个条目 |
| Codex CLI | `~/.codex/config.toml` | TOML 感知，追加 `[mcp_servers.agent-vitals]` |
| 技能前言 | `~/.claude/skills/*/SKILL.md` | 出现具有 `schedule:` / `cron:` / `interval:` 触发器 |
| pi 子代理历史记录 | `~/.pi/agent/run-history.jsonl` | 每个代理完成 + 趋势 |
| Claude Code 会话 | `~/.claude/projects/*/*.jsonl` | 会话计数 + 卡住循环启发式 |
---
## <span style="color:#00d992">▍</span> CLI（仅限人类 - 用于验证）
```bash
av # 一次性健康摘要
av doctor # 摘要 + 可行建议
av shadow # 您的主机上配置了什么
av shadow --watch # 每2秒实时刷新
av burnout # 完成度指标，过去 7 天
av burnout --days 30
av detect # 列出检测到的代理主机
av init # 将 agent-vitals 连接到每个检测到的主机
av mcp # 启动MCP服务器（stdio）
av --help
```
---
## <span style="color:#00d992">▍</span> 堆栈
```
Python 3.11+ ── 类型提示，tomllib，asyncio
uv ── 一键安装 / 构建 / 发布
typer ── CLI
rich ── 终端渲染
pyyaml ── SKILL.md 前言解析
mcp (FastMCP) ── MCP 服务器，stdio 传输
pytest ── 3个模块上104个测试
```
~1200行Python代码 + 预备 `SKILL.md` + 104个测试。MIT 许可。
---
## <span style="color:#00d992">▍</span> 路线图
- [x] **v0.1.0** - `shadow` 和 `burnout` CLI 命令
- [x] **v0.2.0** - MCP 服务器 + `av init` 支持 5 种主机类型
- [x] **v0.2.1** - 修复跨主机检测假阳性
- [x] **v0.3.0** - <span style="color:#00d992">**预动作钩子**</span> 用于 crontab + systemctl（预备 → 强制执行，带有绕过）
- [x] **v0.4.0** - **完整套件**：交互式 `av install`，`av drift`，`av cost`，`av sessions`，`av snapshot`
- [x] **v0.5.0** - **效率套件**：`av loops`（doom-loop 检测），`av unused`（已注册但未使用的MCP工具检测器），GitHub 的有效令牌（ET）指标在 `av cost` 中。 200 个测试。
- [ ] **v0.6.0** - 将 drift / cost / sessions / snapshot / loops / unused 暴露为MCP工具（目前仅限CLI）
- [ ] **v0.7.0** - `shadow live`（正在运行的代理进程，ps-tree 视图）
- [ ] **v0.8.0** - 跨会话“agent déjà vu”检测器（您3周前研究过此代码库）
---
## <span style="color:#00d992">▍</span> 贡献
欢迎提出问题和PR。两件事要知道：
1. `src/agent_vitals/scanners.py` 中的**扫描器**是独立的并且可以容错。添加新的源代码只需编写一个 `scan_*()` 函数并将其添加到 `scan_all()` 即可。
2. **MCP 工具文档字符串是产品。** `vitals_summary` 上的文档字符串是代理读取的指令。像指令一样写它（“总是先调用此...），不是API文档。
当您打开PR时，请粘贴您的盒子的 `av shadow` 输出，以便我们看到在您的环境中显示的内容。
---
## <span style="color:#00d992">▍</span> 许可证
MIT。参见 [`LICENSE`](LICENSE)。
<br/>
<sub>
<span style="color:#3d3a39">─────────────────────────────────────────────</span>
<br/>
<span style="color:#8b949e">由</span> <span style="color:#f2f2f">anirudh prashant</span> <span style="color:#8b949e">·</span> <span style="color:#00d992">agent-vitals v0.2.1</span> <span style="color:#8b949e">·</span> <span style="color:#b8b3b0">·</span> <span style="color:#b8b3b0">2026</span>
</sub>
