Kb Review

SKILL.md

# Skill: kb_review — paper-kb 知识综述 / 实验顾问

## 用途

在用户**已积累一定资料**的知识库上做"横向分析"，而不是单点检索。两个模式：

- **领域综述 / 缺口分析**：对某个主题把库里相关资料做横向梳理——主流方法分类、
  优劣对比、矛盾点、**研究缺口**、对用户研究方向的启示——并把综述**写回知识库长期保存**
  （作为一个高层概念页，下次可重新生成、随库更新）。
- **实验顾问**：用户描述实验问题/不理想的结果，把它对照知识库里的方法，给出**有依据的、
  绑定到具体资料的改进建议**（飞书直接回答，不落库）。

> 与 query_papers 的边界（重要）：query_papers 是"找到/回忆某条内容"的检索式问答；
> 本 Skill 是"跨多篇做综合分析与建议"。综述、研究缺口、多篇对比、实验改进 → 本 Skill；
> "有没有…""找一下…""那篇结论是什么" → query_papers。

## 触发条件

**Activate when（满足任一）：**
- 综述类：「写一份关于X的综述」「综述/梳理一下我库里关于X的资料」「X领域有哪些主流方法」
  「X有什么没解决的问题 / 研究缺口」「对比一下库里几种X方案」等**跨多篇的横向分析**。
- 顾问类：「我实验遇到X / 结果不理想，库里有没有改进思路」「根据我存的资料，这个实验怎么改进」
  「针对这个问题库里有哪些可借鉴的方法」。

**Do NOT activate when：**
- 单点查找 / 回忆："有没有关于X的论文"、"找一下X"、"那篇结论是什么"、"知识库里有什么"
  → 交给 query_papers。
- 存资料（链接/文件/文本 + 存储意图）→ ingest_paper；评估 GitHub 项目 → eval_repo；
  未注册 → init_user。
- 通用知识问答、不指向"我的知识库"（如"什么是强化学习"）→ 不调用本 Skill，直接正常回答。
- 拿不准是"综述"还是"单点查找"时：若问题明显是要"综合/对比/找缺口"就用本 Skill，
  否则默认归 query_papers。

## 前置依赖

- **current_user_open_id**：从消息上下文 sender 获取，传给所有脚本的 `--open_id`。
  网页测试拿不到时用 `webchat_test`。
- 用户必须已注册（任何 paper-kb 请求第一步永远是 `init_user --check`）。
  用户记录里的 **research_direction** 在两个模式里都要用上。
- 本 Skill 根目录需有 `.env`（GITEA_URL / GITEA_ADMIN_TOKEN / GITEA_BOT_USERNAME）。

## 临时文件路径约定

中间文件放 `/tmp/paperkb/`，综述草稿写成 `/tmp/paperkb/draft_review_<主题>.md`。

## 先判断模式

读懂用户意图，分流到 **流程 A（综述/缺口）** 或 **流程 B（实验顾问）**。

---

## 流程 A：领域综述 / 缺口分析

### A1 定范围
从用户消息确定综述主题（一个研究主题 / 关键词 / 概念名，如"强化学习控制""触觉传感"）。
- 用户说"整个知识库 / 我所有的资料"且文档不多 → 全库。
- 主题不清晰 → 先问一句"你想综述哪个主题？"，确认后再继续。

### A2 读目录定位（第一阶段检索）
```bash
python3 scripts/kb_read.py --open_id <open_id> --list all
```
得到 documents[]（含 title/keywords/brief/score/file/type_key）、concepts[]、resources[]、
research_direction、base_url。据主题用 title/keywords/brief/概念名圈出相关项。

边界：
- user_not_registered → 转交 init_user。
- 相关文档与概念页都为空 / 全库就没几篇 → 诚实告知"知识库里关于「X」的资料还太少，
  综述会比较空。先发几篇相关资料入库，积累到几篇后再来做综述效果更好"，终止。
  **不要凭通用知识硬凑一篇"综述"冒充库内综合。**

### A3 精读（第二阶段，**概念页优先**）
精读顺序与上限：
1. **先读所有相关的概念页**——它们已经是"跨文档综合 + 论述对比 + 矛盾与待解决问题"，
   是综述的现成骨架，也是控制上下文的关键（一页概念页压缩了多篇论文）。
2. 再读相关的 summary 页补充细节。精读总数控制在 ~12 页以内；超出时优先覆盖
   **不同方法族 / 不同结论**的代表，其余仅用目录里的 brief。
```bash
python3 scripts/kb_read.py --open_id <open_id> --read "<file 路径，如 concepts/力控制 或 summaries/papers/某论文>"
```

### A4 生成综述（你自己完成）
**只基于精读到的库内内容**，组织成结构化综述。库未覆盖处明说"知识库尚未涉及"，
**绝不编造不存在的资料、结论或链接**。结构：

```markdown
---
标题: "<主题>·领域综述"
类型: "知识综述"
生成时间: "<今天 yyyy-MM-dd>"
覆盖资料数: "<本次综合的库内资料篇数>"
---

# <主题>·领域综述

## 综述范围
<本综述覆盖的主题与资料范围，1-2 句>

## 领域概述
<2-3 句总览>

## 主流方法分类
<按方法族分组。每组：方法思路 + 库内代表性资料（用 [[文件名]] 双链）>

## 各类方法的优势与局限
<横向对比，库内资料怎么说>

## 矛盾与争议
<不同资料结论冲突之处；概念页里的"矛盾与待解决问题"是线索；无则写"暂未发现明显冲突">

## 研究缺口 / 尚未解决的问题
<重点：当前主流方法还没解决什么、哪些方向值得探索>

## 对我研究方向的启示
<结合 research_direction>

## 已综合的库内资料
[[文件名1]] [[文件名2]] …（只列实际读过的、确实存在的页）
```

**【wikilink 格式铁律】** 所有 `[[...]]` 双链**只写文件名本身、不带目录前缀**
（对 → `[[力控制]]`；错 → `[[concepts/力控制]]`）；只链接 A2/A3 中确实存在并读过的页面。
YAML 字符串值统一加双引号。

写入 `/tmp/paperkb/draft_review_<主题>.md`。

### A5 保存综述（作为可重生成的概念页）
```bash
python3 scripts/save_page.py --open_id <open_id> --kind concept \
    --name "<主题>·领域综述" --file "/tmp/paperkb/draft_review_<主题>.md" \
    --brief "<一句话：本综述覆盖什么主题、综合了几篇资料>"
```
- save_page 按名字 upsert：**同名综述会被覆盖更新**——所以用户对同一主题再次发起综述，
  就是"随库重新生成"，体现知识复利。
- 若该主题综述已存在且本次是更新：先 `kb_read.py --read "concepts/<主题>·领域综述"` 读旧版，
  把新资料**融合改写进全文**（非简单追加）再保存。
- 命名带"·领域综述"后缀，避免与已有概念页 / 文档同名导致 wikilink 混淆。

### A6 回复用户
```
📝 已生成《<主题>·领域综述》并存入知识库

🔬 主流方法：<2-4 类，逗号分隔>
🕳 研究缺口：<1-2 条最关键的>
📄 完整综述：<save_page 返回的 page_url>

（综合了 <N> 篇库内资料。之后这个主题再积累新资料，可以让我重新生成更新。）
```
若是更新已有综述，开头改"📝 已重新生成并更新《…》"。

---

## 流程 B：实验顾问

### B1 读目录定位
```bash
python3 scripts/kb_read.py --open_id <open_id> --list all
```
据实验问题的关键词，圈出相关的方法 / 论文 / 概念页。
相关内容为空 → 告知"知识库里暂时没有和这个问题直接相关的资料"，可给通用建议但
**必须标注"以下为通用建议，非来自你的知识库"**，并建议先存入相关文献。

### B2 精读相关页（≤8）
```bash
python3 scripts/kb_read.py --open_id <open_id> --read "<file 路径>"
```

### B3 生成建议（你自己完成）
- 先用 1-2 句复述你对实验问题的理解 / 可能原因；
- 给 **2-4 条可落地的改进建议**，**每条尽量绑定到库内具体资料**：说明那篇资料里的
  方法/参数/思路如何用于解决这个问题，并附该资料的 page_url；
- 库里没有直接对应的部分，可补充通用思路，但**明确标注"以下为通用建议，非来自知识库"**；
- 不编造库里没有的资料或结论。

### B4 回复用户（飞书直接回答，不落库）
```
🔍 问题理解：<1-2 句>

💡 来自你知识库的改进建议：
1. <建议>——依据《<标题>》：<怎么用>　🔗 <page_url>
2. ……

（如有通用补充）🧩 额外通用思路（非来自知识库）：<…>
```

---

## 错误处理总则
- 脚本输出单行 JSON；success:false 时按 message 处理，不堆原始报错。
- 知识库内容不足时**如实说明，不强行拼凑综述/建议**，不冒充库内综合。
- 绝不编造知识库中不存在的资料、结论或链接。
- Gitea 连不上：告知"知识库暂时无法访问，请稍后再试或联系管理员"。