Query Papers

SKILL.md

# Skill: query_papers — paper-kb 查询知识库

## 用途

用户用自然语言提问时，从其专属的 Gitea 知识库中找到相关内容，生成有依据、
带来源链接的回答。采用两阶段检索：先读目录定位，再精读相关页面，
避免知识库变大后撑爆上下文。

## 触发条件

**Activate when（满足任一）：**
- 用户在查找自己存过的内容："有没有关于……的论文/文献/资料"、"找一下……"、
  "查一查……"、"我之前存过……吗"、"知识库里有什么"。
- 用户要求基于知识库做分析："总结一下我存的关于……的方法"、
  "对比一下知识库里的几种……方案"。
- 上一轮查询后的追问："第二篇详细讲讲"、"那篇论文的结论是什么"。

**Do NOT activate when：**
- 用户在存文档（有 arxiv 链接/PDF + 存储意图）→ 交给 ingest_paper。
- 用户问的是**通用知识**而非查自己的库（如"什么是强化学习"、"帮我解释一下PID"）
  → 不调用本 Skill，直接正常回答。区分依据：问题是否指向"我存过的/知识库里的"内容。
  拿不准时可以先查库，库里没有再正常回答。
- 用户未注册 → 先走 init_user。

## 前置依赖

- **current_user_open_id**：从消息上下文 sender 获取，传给脚本 `--open_id`。
- 本 Skill 根目录需有 `.env`（GITEA_URL / GITEA_ADMIN_TOKEN / GITEA_BOT_USERNAME）。

## 完整执行流程

### Step 1：读取知识库目录（第一阶段检索）

```bash
python3 scripts/kb_read.py --open_id <open_id> --list all
```

输出包含：
- `research_direction`：用户研究方向（回答时可作为背景）
- `documents[]`：每篇文档的 title / keywords / brief / score / file
- `concepts[]`、`resources[]`：每个页面的 name / brief / file
- `base_url`：拼接页面链接用（链接 = base_url + file）
- `repo_url`：知识库首页链接

**边界处理：**
- `user_not_registered` → 转交 init_user 流程。
- `documents` 为空 → 回复："你的知识库还是空的～发一篇 arxiv 链接或 PDF
  给我就能开始积累了！" 流程终止。

### Step 2：判断相关页面（你自己完成）

根据用户问题和目录里的 title/keywords/brief，列出相关页面，**不限数量但精读
上限8个**。选择优先级：

1. **概念页优先**：问题命中某个概念（如问"力控制有哪些方法"而 concepts 里有
   "力控制"）→ 概念页本身就是跨文档综合好的答案，优先精读。
2. **资源页**：问题在找数据集/工具/开源项目时优先。
3. **summary 页**：按 keywords 和 brief 的匹配程度挑选。
4. 相关页面超过8个时：精读最相关的8个，其余的在回答中仅以"标题+一句话"列出。

如果目录里**没有任何相关内容**：诚实告知"你的知识库里暂时没有与「××」直接
相关的内容"，可以基于你自己的知识简要回答问题（明确标注"以下是通用知识，
非来自你的知识库"），并建议用户存入相关论文。**不要假装知识库里有内容。**

### Step 3：精读相关页面（第二阶段检索）

对 Step 2 选中的每个页面：
```bash
python3 scripts/kb_read.py --open_id <open_id> --read "<file路径，如 concepts/力控制>"
```
输出含 `content`（页面全文）和 `page_url`（可点击链接）。

### Step 4：生成回答（你自己完成）

基于精读的内容回答用户问题。要求：
- 全部中文，先给**综合回答**（直接回应问题，不要罗列式开头）。
- 涉及具体文档时注明来源，**每个引用的文档/页面都附上 page_url 链接**。
- 不同文档结论冲突时，如实指出冲突（概念页的"矛盾与待解决问题"一节是线索）。
- 只基于知识库内容回答；知识库没覆盖的部分明确说"知识库中未涉及"。

**回复格式参考（按实际情况灵活调整，不要生硬套模板）：**

```
📌 <直接回答用户的问题，1-3段综合论述>

📚 相关内容：
1. 《<标题>》（相关性：高）
   <这篇与问题的关系，1-2句>
   🔗 <page_url>
2. ……

（如果引用了概念页）
🧠 概念页「<概念名>」已综合了 <N> 篇文档对此主题的论述：🔗 <page_url>
```

### Step 5：记录查询历史（不阻塞）

```bash
python3 scripts/log_query.py --open_id <open_id> --question "<用户问题>"
```
无论成功失败都不影响回答。本步可与 Step 4 并行或在回复后执行。

### 追问处理

用户追问某篇文档细节时：直接用 Step 3 精读那篇（如还没读过），基于全文回答。
本次会话中已精读过的页面内容可直接复用，不必重复调用。

## 错误处理总则

- 脚本输出单行 JSON；`success: false` 时按 `message` 处理，不把原始报错给用户。
- Gitea 连不上等系统故障：告知用户"知识库暂时无法访问，请稍后再试或联系管理员"。
- 绝不编造知识库中不存在的文档、结论或链接。