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_\x3C主题>.md。

先判断模式

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

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

A1 定范围

从用户消息确定综述主题（一个研究主题 / 关键词 / 概念名，如"强化学习控制""触觉传感"）。

• 用户说"整个知识库 / 我所有的资料"且文档不多 → 全库。
• 主题不清晰 → 先问一句"你想综述哪个主题？"，确认后再继续。

A2 读目录定位（第一阶段检索）

python3 scripts/kb_read.py --open_id \x3Copen_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。

python3 scripts/kb_read.py --open_id \x3Copen_id> --read "\x3Cfile 路径，如 concepts/力控制 或 summaries/papers/某论文>"

A4 生成综述（你自己完成）

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

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

# \x3C主题>·领域综述

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

## 领域概述
\x3C2-3 句总览>

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

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

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

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

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

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

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

写入 /tmp/paperkb/draft_review_\x3C主题>.md。

A5 保存综述（作为可重生成的概念页）

python3 scripts/save_page.py --open_id \x3Copen_id> --kind concept \
    --name "\x3C主题>·领域综述" --file "/tmp/paperkb/draft_review_\x3C主题>.md" \
    --brief "\x3C一句话：本综述覆盖什么主题、综合了几篇资料>"

• save_page 按名字 upsert：同名综述会被覆盖更新——所以用户对同一主题再次发起综述， 就是"随库重新生成"，体现知识复利。
• 若该主题综述已存在且本次是更新：先 kb_read.py --read "concepts/\x3C主题>·领域综述" 读旧版， 把新资料融合改写进全文（非简单追加）再保存。
• 命名带"·领域综述"后缀，避免与已有概念页 / 文档同名导致 wikilink 混淆。

A6 回复用户

📝 已生成《\x3C主题>·领域综述》并存入知识库

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

（综合了 \x3CN> 篇库内资料。之后这个主题再积累新资料，可以让我重新生成更新。）

若是更新已有综述，开头改"📝 已重新生成并更新《…》"。

流程 B：实验顾问

B1 读目录定位

python3 scripts/kb_read.py --open_id \x3Copen_id> --list all

据实验问题的关键词，圈出相关的方法 / 论文 / 概念页。 相关内容为空 → 告知"知识库里暂时没有和这个问题直接相关的资料"，可给通用建议但 必须标注"以下为通用建议，非来自你的知识库"，并建议先存入相关文献。

B2 精读相关页（≤8）

python3 scripts/kb_read.py --open_id \x3Copen_id> --read "\x3Cfile 路径>"

B3 生成建议（你自己完成）

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

B4 回复用户（飞书直接回答，不落库）

🔍 问题理解：\x3C1-2 句>

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

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

错误处理总则

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