---
name: torch-lint
description: "知识库健康检查。当你想了解知识库质量、检查是否有过期知识需要衰减、或发现潜在的矛盾和重复条目时使用。支持自动修复模式。"
disable-model-invocation: true
argument-hint: [知识仓库路径] [--fix]
allowed-tools: Bash(python *) Bash(git *) Read Write
---

# /torch-lint — 知识库健康检查

对团队知识仓库执行全面健康检查。

## 前置确认

1. 确认知识仓库路径（按优先级依次查找：$ARGUMENTS 传入 → 当前项目 CLAUDE.md / AGENTS.md / .cursor/rules/torch.md 中的 `团队知识库` 段落 → 询问用户）
2. 验证路径存在且包含 `knowledge-catalog.md`
3. 同步知识仓库：`git -C {知识仓库路径} pull --rebase --quiet`
4. 确认 `torch_lint.py` 脚本路径（在 Torch 安装目录的 `scripts/` 下）
   - **fallback**：如果脚本不存在或 python 不可用，输出提示并终止：
     ```
     ❌ 未找到 torch_lint.py 或 python 不可用。
     请确认 Torch 已正确安装，或手动指定脚本路径。
     ```

## 执行流程

### Step 1: 运行 lint 检查

```bash
python {torch_scripts_path}/torch_lint.py {知识仓库路径}
```

如果用户指定了 `--fix`：
```bash
python {torch_scripts_path}/torch_lint.py {知识仓库路径} --fix
```

**脚本执行失败时**：展示错误信息，如果是 Python 版本问题提示 `需要 Python ≥ 3.8`；其他错误原样展示并终止。

### Step 2: 展示报告

将 lint 输出直接展示给用户，格式如下：

```
🔍 Torch Lint 知识库健康报告
========================================

📊 概况：共 XX 条知识条目
  ✅ proven: X
  🔶 verified: X
  ⬜ draft: X

❌ 格式问题：N 条
  - 文件名: 具体问题

📋 索引一致性问题：
  - ID: 文件存在但 catalog 中缺失
  - ID: catalog 中列出但文件不存在

⏳ 需衰减降级：N 条
  - ID: proven → verified（XX 个月未引用）

👻 孤儿条目（draft + 无引用）：N 条
  - ID: 标题

⚠️ 潜在矛盾：N 对
  - ID1 vs ID2（原因）

🔄 合并候选：N 对
  - ID1 vs ID2（标题相似度 X.XX, tags 重叠 X.XX）

📌 共发现 N 个问题需要关注。
```

### Step 3: 自动修复（--fix 模式）

如果指定了 `--fix`，先向用户展示将执行的修复操作：

```
🔧 即将执行以下自动修复：
- 衰减降级 N 条知识条目（详见上方报告）

确认执行？[Y/N]
```

用户确认后，脚本自动：
1. 执行衰减降级（修改条目的 maturity 字段）
2. 更新对应 catalog.md 中的成熟度标记

修复后执行 git 提交：
```bash
cd {知识仓库路径}
git add .
git commit -m "lint: 自动衰减降级 N 条知识条目"
git push
```
- **push 失败处理**：提示用户「本地 commit 已完成，请稍后手动 `git push`」

### Step 4: 建议操作

根据报告结果给出建议：
- 格式问题 → 建议手动修复
- 索引不一致 → 建议运行 --fix 或手动对齐
- 孤儿条目 → 建议补充 evidence 或归档
- 矛盾条目 → 建议人工审核合并
- 重复条目 → 建议合并为一条

## 注意事项

- lint 检查本身是只读的，不会修改任何文件
- 仅 `--fix` 模式会修改文件（衰减降级）
- 归档（draft → archived）不会自动执行，需人工确认
- 矛盾和重复仅标记，不自动处理
- **空仓库**：如果知识库条目数为 0（仅有示例条目），输出「知识库为空，建议先用 `/torch-import` 导入」，跳过后续检查
- **示例条目**（ID=000 或备注含 📎 示例）不计入检查统计