# agent-clinic 0.2.0

> **你的 Agent 体检诊所。** 只读扫描本地 Agent 会话，用**可逐条复核的证据**诊断真实发生的使用体验问题，
> 并为每个问题开出**可执行的处方**。零依赖、默认零外发、会话文件只读。

这是第一个正式版（GA）。相比 `0.1.1`，诊断能力从 12 项补到 **22 项全实现、0 项排期**。

## 亮点

**诊断：22 项指标，全部有断言守着**

- **成本类**：C1 token 消耗过快（单位请求 output vs 其余主会话基线）· C2 上下文膨胀 ·
  C3 长会话疲劳 · C5 压缩可观测性（DSH 自报的释放量，非估算）· C6 工具面成本 · C7 上下文注入量
- **执行类**：E1 死循环 · E2 反复失败 · E3 结果过大 · E4 计划脱节 · E5 冗余重复调用
- **知识记忆类（本版新增）**：K1 跨会话失忆 · K2 已解决重新排查 —— 用**本地加盐指纹快照**实现，
  正文不落盘，可 `fingerprints --clear` 删除、可用环境变量整体关闭
- **环境安全类**：N1 命令反复失败 · N2 高风险操作 · N3 权限审批摩擦 · N4 API 重试频繁
- **资产闲置类（本版新增 A1）**：A1 MCP 闲置（读 profile patch 里配置的 MCP 服务器 ×
  按 `mcp__<serverName>__*` 统计窗口内调用次数）· A2 skill 闲置 · A3 高频手动序列 ·
  A4 子代理开销 · A5 辅助 LLM 开销

**处方：每条都能动手，且记得住你的反馈**

- 配置类给**可整段粘进 profile patch 的 YAML**（含"当前值 → 建议值"与风险、验证方式、出处）；
- 插件类读本机真实目录并可联网现搜（只发问题类型关键词，不发会话内容）；
- **处方反馈闭环（本版新增）**：`./run.sh rx reject <目标 ID> --reason "…"` 之后，
  该条不再出现，报告会单独写明"已被你撤掉"（含 ID / 日期 / 理由），`rx remove|clear` 可撤销。

**证据：每个结论都能当场复核**

- 报告里每条结论都带定位符与复核命令；`./run.sh show "<file>#L101-L110"` 直接展开原始行
  （支持区间与 `--offset/--limit` 分页）；
- 没有数据时不装成"没问题"：未检测到的维度、未实现的维度、撤掉的处方、解析失败的会话都**逐条写明**。

**DSH 插件形态**：侧边栏入口 + 全页面板 + 准实时角标；也可作为 skill 用（`install.sh` 一行装）。

## 质量门（全部可复跑）

| 门 | 结果 |
|---|---|
| 自检（合成语料 · 跳过数必须为 0） | **343 条全绿** |
| 语料覆盖率（每指标至少命中 1 处） | **22/22** |
| 插件面板零依赖 DOM 桩测试 | **106 条全绿**，且自带"文档条数"核对 |
| 空数据降级 | exit 0（不冒充全绿） |
| CI | ubuntu 24.04 / ubuntu 26.04 / macOS / Windows × node 22.15 + 24 |

## 安装

```bash
npm i -g agent-clinic@0.2.0                 # npm
curl -fsSL https://raw.githubusercontent.com/1687210989/agent-clinic/main/install.sh | bash   # 一行装
# 作为 DSH 插件：侧边栏 → 插件 → 添加插件 → 粘贴仓库地址 → 立即启用 → 完全重启 Harness
```

零运行时依赖；只需要 **Node ≥ 22.15**（用于原生 zstd 解码）。

## 已知限制（如实列出，不吹全覆盖）

- 只支持 DSH v4 会话格式（v3 未验证；无压缩 `.jsonl` 已支持）；
- **WorkBuddy 只有安装、没有适配器** —— 装上会部署 skill，但扫描不到 WorkBuddy 会话；
- 配置层只解析 `cordis.patch.yml` 用到的 YAML 子集；处方里的"随附默认值"是抄录表，DSH 升级后需同步；
- 面板暂无反馈按钮（反馈用 CLI `rx`）；面板测试仍有已列明的空白（真实计时器 / CSS 布局 /
  React 语义 / 事件系统 / 网络竞态）；
- A1（MCP 闲置）需要 ≥30 天观察窗口，窗口不足时只报"还差多久"。

## 隐私

- 诊断**全流程本地**、会话文件**只读**；**默认零外发**（联网只有两个显式动作：`catalog-sync`、
  `report --live`/面板的「联网现搜」，且只发问题类型关键词）；
- 只在 `~/.agent-clinic/` 下写三份自己的状态：插件目录快照、加盐文本指纹、处方反馈
  （都不含对话正文；删除即完全重置；指纹还可用 `AGENT_CLINIC_NO_FINGERPRINT_STORE=1` 整体关闭）。

---

完整变更历史见 [CHANGELOG.md](https://github.com/1687210989/agent-clinic/blob/main/CHANGELOG.md)；
指标定义与阈值见 [docs/diagnostics.md](https://github.com/1687210989/agent-clinic/blob/main/docs/diagnostics.md)。