---
name: torch-query
description: "查询团队知识库。当你想看看团队有没有相关经验、做技术决策前想查历史选型、排查问题想找已知坑时使用。支持自然语言描述查询意图，遵循三级渐进式索引。"
disable-model-invocation: false
argument-hint: [查询内容，如"mqtt相关的坑"、"有哪些技术决策"]
allowed-tools: Read Grep Glob
---

# /torch-query — 查询知识库

从团队知识仓库中检索相关知识条目。

## 前置确认

1. 确认知识仓库路径（按优先级依次查找：当前项目 CLAUDE.md / AGENTS.md / .cursor/rules/torch.md 中的 `团队知识库` 段落 → 询问用户）
2. 验证知识仓库路径存在且包含 `knowledge-catalog.md`
3. 同步知识仓库：`git -C {知识仓库路径} pull --rebase --quiet`
   - **pull 失败**：不阻断查询，提示「同步失败，使用本地缓存」继续执行

## 解析查询意图

从 $ARGUMENTS 中用自然语言理解用户意图，自动推断过滤条件：

**示例**：
| 用户输入 | 推断的过滤条件 |
|---------|---------------|
| `mqtt相关的坑` | 关键词=mqtt，type=pitfall |
| `有哪些技术决策` | type=decision |
| `redis` | 关键词=redis，搜索全部类型 |
| `成熟的最佳实践` | type=guideline，maturity=proven |
| `最近新加的知识` | maturity=draft，按创建时间排序 |
| （空） | 展示知识库全貌 |

不需要用户写 `--type=xxx` 这种参数，Claude 自行从自然语言中理解意图。

## 查询流程（三级渐进）

### Step 1: 读取全景目录

读取 `{知识仓库路径}/knowledge-catalog.md`（~50 行）

如果无参数，直接展示全貌并结束：
```
📚 团队知识库概览

| 层级 | 条目数 | proven | verified | draft |
|------|--------|--------|----------|-------|
| 技术知识 | XX | X | X | X |
| 业务知识 | XX | X | X | X |

💡 查询示例：
- /torch-query mqtt相关的坑
- /torch-query 有哪些技术决策
- /torch-query 成熟的最佳实践
```

### Step 2: 读取相关 catalog

根据推断的查询意图，读取对应 catalog.md：
- 偏技术方向 → 读 `tech-wiki/catalog.md`
- 偏业务方向 → 读 `biz-wiki/{domain}/catalog.md`
- 不确定 → 两个都读

在 catalog 中按推断的条件过滤：
- **示例过滤**：跳过备注列含「📎 示例」的行，或 front matter 中 `example: true` 的条目（这些是模板自带的示例，不是团队真实知识）
- 关键词：匹配 ID、标题、tags 列
- 类型：匹配对应的 type 分组
- 成熟度：匹配成熟度列

### Step 3: 展示结果

```
🔍 查询结果：{用户原始输入}

找到 {N} 条匹配：

| # | 成熟度 | ID | 标题 | tags | 引用 |
|---|--------|-----|------|------|------|
| 1 | ✅ proven | TK-DEC-000 | 缓存选型：Redis 而非 Memcached | cache, redis | 8 |
| 2 | 🔶 verified | TK-PIT-000 | MQTT 重连风暴问题 | mqtt, reconnect | 3 |
| 3 | ⬜ draft | TK-MOD-000 | MQTT 客户端类型模型 | mqtt, architecture | 0 |

输入序号查看完整内容。
```

如果无匹配：
```
🔍 未找到匹配「{用户输入}」的知识条目。

建议：
- 换个说法试试
- 查看全景目录了解知识库有哪些内容：/torch-query
- 如果你有相关知识想沉淀：/torch-save {描述}
```

### Step 4: 查看完整条目

用户输入序号后，读取完整条目文件内容并展示。

展示完整条目后，提示：
```
---
💡 如果这条知识对你当前任务有帮助，我会自动更新它的引用记录（reference_count +1）。
```

然后更新条目的 `last_referenced` 和 `reference_count` 字段，并检查是否满足成熟度升级条件。

如果发生成熟度升级，还需：
1. 更新对应 `catalog.md` 中该条目的成熟度列
2. 在 `log.md` 末尾追加升级记录
3. 提交变更：
   ```bash
   cd {知识仓库路径}
   git add . && git commit -m "ref: 更新 {ID} 引用计数" && git push
   ```
   - **push 失败**：不阻断，提示用户稍后手动 push

## 注意事项

- 遵循三级渐进索引，不要一次性读取所有条目文件
- 查询过程是只读的，仅在用户查看完整条目时才更新引用字段
- 成熟度图标：proven=✅ verified=🔶 draft=⬜
- **示例条目过滤**：front matter 含 `example: true` 或 catalog 备注列含「📎 示例」的条目是模板自带示例，查询结果和统计计数中均应排除