# kb-autopsy

**Repository Path**: savantcat/kb-autopsy

## Basic Information

- **Project Name**: kb-autopsy
- **Description**: 知识库「尸检」MCP：给一个知识库目录做体检，输出 0-100 僵尸指数与五项病理指标。零依赖、只读。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://savantcat.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kb-autopsy · 企业知识库「尸检」

> 知识库不是买来的，是养出来的。

给一个知识库目录做体检，输出一个 **僵尸指数（0–100）** 和五项病理指标。
把「有没有人在养这套知识库」从一句感觉，变成一组可核验的数字。

**零外部依赖**，只有 Python 标准库。clone 下来就能跑。

---

## 它回答什么问题

每个上了知识库的公司都问过同一句话：**「我们那套东西，现在还有人用吗？」**

这个工具的输出就是答案。而且它故意做成**一份要转发给老板看的报告**——
因为「知识库死了」这件事，负责推系统的人往往是最早知道、也最不敢说的人。

```
$ python kb_autopsy.py ./你的知识库

## 🟠 僵尸指数 61.3 / 100 —— 濒危

> 正在变成僵尸。通常缺的不是工具，是一个明确的人。

| 指标 | 权重 | 实测 | 得分 |
|---|---|---|---|
| 陈旧度 | 30 | 中位 214.0 天未更新 | `██████░░░░` 59% |
| 孤儿率 | 25 | 41.1%（37 篇无人引用） | `████████░░` 80% |
| 空壳率 | 15 | 12.0%（11 篇少于 200 字） | `████░░░░░░` 36% |
| 重复率 | 15 | 19.6%（18 篇近重复） | `██████░░░░` 63% |
| 无结构率 | 15 | 22.8%（21 篇无标题） | `████░░░░░░` 40% |
```

## 五项指标是什么

| 指标 | 含义 | 为什么它重要 |
|---|---|---|
| **陈旧度** | 文档年龄中位数 | 没人更新的库等于没人看的库 |
| **孤儿率** | 没有任何其他文档引用它 | 进不去的孤岛，检索也捞不着 |
| **空壳率** | 只有标题没有内容 | 建库时的半成品，永远没被填完 |
| **重复率** | 同一件事写了两遍以上 | **AI 客服最容易在这里答混** |
| **无结构率** | 没有标题也没有分节 | 切块质量差，检索命中率低 |

## 安装与使用

```bash
git clone https://gitee.com/savantcat/kb-autopsy.git && cd kb-autopsy
python kb_autopsy.py ./你的知识库              # Markdown 报告
python kb_autopsy.py ./你的知识库 --json        # 结构化输出
python kb_autopsy.py ./你的知识库 --out r.md    # 写入文件
python kb_autopsy.py ./你的知识库 --stale-days 90   # 换陈旧阈值
```

作为 MCP 工具（让 Agent 直接调用）：

```bash
pip install mcp
python server.py            # stdio

# 在 Hermes / Claude Desktop / Cursor 里注册
hermes mcp add kb-autopsy --command "<python 路径>" --args "<...>/server.py"
```

暴露四个工具：

| 工具 | 作用 |
|---|---|
| `autopsy` | Markdown 报告（可直接转发给老板） |
| `autopsy_json` | 结构化输出，便于接入自有系统 |
| `zombie_index` | 只回一个数字（0–100），给「我要一眼看结论」的场景 |
| `qa_autopsy` | 对 **AI 客服问答库**（结构化 QA JSON）做同类体检：僵尸指数 + 问答层五项病理指标 |

四个工具全是只读的（`readOnlyHint` / `idempotentHint` 全部声明），不会被误判成写操作。

## 自检

```bash
python tests/selftest.py    # 造两个已知答案的语料，验证尺子没指反
python tests/mcp_smoke.py   # 真起服务、真握手、真调工具
```

`selftest` 会构造一个「健康库」和一个「僵尸库」，要求两者指数差距 ≥ 40 且**五项指标方向全部正确**。
尺子指反了会被它当场拦下——**不通过就不许拿去量客户。**

---

## 三个刻意的设计决定（都是踩过坑才加的）

### 1. 语料小于 5 篇，拒绝出分

小语料天然零交叉引用。曾经 2 篇文档的库被判「亚健康 40.6 分」，病根全是「孤儿率 100%」——
**那不是发现，那是噪声。** 而小微企业恰恰是小知识库。
所以少于 5 篇直接告知给不出有意义的指数，不硬凑一个数。

### 2. 小语料自动剔除不适用的指标

少于 15 篇剔除「孤儿率」，少于 10 篇再剔除「重复率」，权重按比例摊回其余指标，
并在报告里明写剔除了什么。**别拿小库的这两个数说事。**

### 3. 过滤构建产物与站点协议文件

对着一个静态站点目录跑，曾得出「濒危 56.2」：重复 48% 来自 `_aeo_out/llms.txt` ↔
`_aeo_stage/llms.txt`，空壳来自 `indexnow` 校验密钥，孤儿 98% 来自博客文章天然互不引用。
**尺子量错对象，比没有尺子更误导。** 现在默认跳过构建目录、隐藏文件与协议/密钥类文件
（`--all` 可关闭过滤）。

## 已知边界（诚实说）

- **它量的是「知识库」，不是博客或站点源码目录。** 独立文章页天然互不引用，孤儿率必然接近 100%，那不代表任何问题。
- **阈值是经验值，没做过大样本标定。** `stale_days=180`、近重复 `0.75` 都可以按自己情况调；判定当提示用，别当判决。
- **近重复用字符 n-gram，不做语义判重。** 换了措辞的同一份内容它抓不到——那是故意的，语义判重要么上模型要么不可靠，都不适合放进一个零依赖工具。
- **只读。** 绝不修改你的任何文件。

## License

MIT