PaperGuide · 论文导读（技能模块）
适用场景
本科生直接读原论文门槛高。本 Skill 把经典论文拆成"能啃"的六段式模块，并标注与课程章节的对应关系；同时封装为可独立调用、可复用的 Python 组件，供其它流程直接 import。
实现说明
- 模块文件：
paper_guide.py（纯 Python 标准库，无第三方依赖，无需 pip install）。 - 安全审计结论：P2（安全）。无外部代码执行、无凭证访问；网络抓取仅对用户显式传入的
url做只读 GET（超时 15s）；文件读取仅针对用户显式指定的--text路径。 - 依赖注入：LLM 通过参数
llm: Callable[[str], str]注入，组件本身不绑定任何具体大模型 API，便于在任意环境中复用。
输入参数（清晰 schema）
paper_guide(title=None, url=None, text=None, course_context=None, llm=None)
| 参数 | 类型 | 说明 |
|---|---|---|
| title | str | 论文标题。优先匹配内置库；否则作检索线索 |
| url | str | 论文链接（可选，启用只读抓取） |
| text | str | 论文全文/片段（字符串，或本地文件路径） |
| course_context | str | 课程章节上下文（可选），增强"课程关联"段 |
| llm | Callable | 可调用对象 llm(prompt)->str（可选），提供时对任意论文生成结构化导读 |
> 三者（title/url/text）至少提供一个；都为空时抛出 ValueError。
输出格式（结构化导读摘要）
返回 PaperGuide 数据类，字段：
title, contribution, background, innovation, method, experiments, limitations, course_link, key_terms(list[str]), source, confidence
- 方法：to_dict()（序列化）、to_markdown()（可读渲染）。
- source ∈ {builtin, llm, rule}；confidence ∈ {high, low}（无 LLM 且无内置库时降级为 low）。
标准调用接口（三种方式）
from paper_guide import paper_guide, guide, PaperInput, PaperGuide
# 1) 函数式便捷入口（最常用）
r1 = paper_guide(title="Attention Is All You Need")
r2 = paper_guide(url="https://arxiv.org/abs/1706.03762", llm=my_llm)
r3 = paper_guide(text=open("paper.txt").read(), course_context="第2讲")
# 2) 面向对象入口
r4 = guide(PaperInput(title="...", course_context="轻量化部署"), llm=my_llm)
# 3) 命令行
# python paper_guide.py --title "Attention Is All You Need" [--json]
# python paper_guide.py --text paper.txt
# python paper_guide.py --url https://arxiv.org/abs/1706.03762
LLM 注入示例（任何返回 JSON 的 callable 均可）：
def my_llm(prompt: str) -> str:
# 调用你自己的模型/API，返回 build_prompt 约定的 JSON 字符串
return '{"title":"...","contribution":"...","background":"...",'
'"innovation":"...","method":"...","experiments":"...",'
'"limitations":"...","course_link":"...","key_terms":["..."]}'
paper_guide(title="Any Paper", text=full_text, llm=my_llm)
内置论文库
references/papers/ 下按 slug.md 维护预结构化导读，离线可用、即查即得：
- attention-is-all-you-need.md — 《Attention Is All You Need》(2017)，对应第2讲 Transformer
- 扩展方式：按相同 frontmatter + # 段名 格式新增即可，引擎自动识别。
导读模板（六段式）
- 一句话贡献 2. 背景动机 3. 核心创新 4. 方法架构 5. 关键实验 6. 局限与后续 + 课程关联 + 关键术语。
课程关联
第2讲延伸；降低读原论文门槛，培养学术素养；与 AttnViz、ConceptFlash 形成「读论文→看机制→查术语」的联动。
在 WorkBuddy 对话中的执行步骤（对话触发时由模型执行）
当被本 Skill 触发后，按以下流程调用底层组件：
1. 解析用户输入：从对话中提取论文标题（--title）、链接（--url）、或粘贴/上传的原文（--text，文本或本地文件路径）；若用户提到课程章节，记录为 course_context。
2. 定位本 Skill 目录：本文件所在目录（含 paper_guide.py）。
3. 用 Bash 调用引擎（优先内置库 / LLM，无 LLM 时自动规则降级）：
- 按标题：python "<skill_dir>/paper_guide.py" --title "Attention Is All You Need"
- 按链接：python "<skill_dir>/paper_guide.py" --url "https://arxiv.org/abs/1706.03762"
- 按文本：python "<skill_dir>/paper_guide.py" --text "<用户原文或文件路径>"
- 需要机器可读结果时追加 --json。
4. 呈现结果：将脚本输出的 Markdown（六段式导读）直接展示给用户；若 confidence=low（规则降级），提示用户"未匹配内置库且未接入模型，已给出骨架，提供全文或接入 LLM 可得完整导读"。
5. 组件复用：若其它流程（如作业批阅、自动导读报告）需要调用，直接 from paper_guide import paper_guide，见上文"标准调用接口"。
