本地文献分析工具

引导用户从 IMA 知识库下载文献 PDF 到本地，然后进行纯本地的结构化分析和总结生成。

核心变更（v2.0）

⛔ MANDATORY RULES

1. 学术诚信铁律：总结中所有事实性陈述必须来自原文PDF，标注页码和图表编号。推断内容必须标注 [推断]。绝不编造数据。
2. PDF 下载后验证：下载后必须验证 magic bytes（%PDF-），非PDF文件不处理。
3. 文本提取：使用 Hermes venv 中的 pdfplumber（已安装 v0.11.9）。
4. 模板填充：使用 ~/.local/share/ima-kb-backup/paper-summaries/TEMPLATE.md 作为总结模板。
5. 不自动操作 IMA API——除非用户明确要求从 IMA 知识库拉取，否则默认走本地路径。

执行流程

Phase 0: 环境检查

# 检查本地知识库目录
BACKUP_DIR="$HOME/.local/share/ima-kb-backup"
mkdir -p "$BACKUP_DIR"/{raw-pdfs,paper-summaries,literature-catalog,scripts}
ls "$BACKUP_DIR/papers.db" && echo "✅ 本地数据库存在" || echo "⚠️ 本地数据库不存在（首次使用会自动创建）"

# 检查 pdfplumber
~/.hermes/hermes-agent/venv/bin/python3 -c "import pdfplumber; print('✅ pdfplumber:', pdfplumber.__version__)" || echo "❌ pdfplumber 缺失"

Phase 1: 引导用户下载 PDF 到本地

这是本 skill 的核心改变——不再自动调用 IMA API，而是引导用户手动操作。

方式 A：从 IMA 知识库导出（推荐）

当用户说"分析一下IMA里的某篇文献"时，引导用户：

📋 请按以下步骤操作：

1. 打开 IMA（腾讯元宝）知识库
2. 找到你要分析的文献
3. 点击下载/导出，将 PDF 保存到本地
4. 告诉我文件路径，我来分析

或者，如果你希望我直接从 IMA 知识库里拉取，需要你先配置 IMA API 凭证
（配置方式：在 ~/.config/ima/ 下创建 client_id 和 api_key 文件）

方式 B：直接提供本地 PDF 文件路径

用户也可以直接给出本地 PDF 路径：

# 把 PDF 放到 raw-pdfs 目录
cp /path/to/paper.pdf ~/.local/share/ima-kb-backup/raw-pdfs/

方式 C：用户已配置 IMA 凭证，自动拉取（可选回退）

如果用户已配置 IMA 凭证且在同一个 Hermes 环境，可以用旧流程自动下载。

# 检查是否有 IMA 凭证
if test -f ~/.config/ima/client_id && test -f ~/.config/ima/api_key; then
  echo "✅ IMA 凭证已配置，可以自动从知识库拉取"
else
  echo "⚠️ 未配置 IMA 凭证，请使用方式 A 或 B"
fi

Phase 2: 读取 PDF 并提取文本

PDF_PATH="/path/to/your/paper.pdf"

# 验证 PDF
head -c 4 "$PDF_PATH" | grep -q "%PDF" && echo "✅ 有效PDF" || echo "❌ 不是PDF文件"

# 提取文本和表格
PYTHON="$HOME/.hermes/hermes-agent/venv/bin/python3"
$PYTHON -c "
import pdfplumber, json, sys
pdf_path = sys.argv[1]
with pdfplumber.open(pdf_path) as pdf:
    text_parts = []
    tables = []
    for i, page in enumerate(pdf.pages, 1):
        text = page.extract_text()
        if text:
            text_parts.append(f'[第{i}页]\\n{text}')
        for j, table in enumerate(page.extract_tables()):
            if table:
                tables.append({'page': i, 'index': j, 'data': table})
    print('TEXT_START')
    print('\\n\\n'.join(text_parts))
    print('TABLES_START')
    print(json.dumps(tables, ensure_ascii=False))
" "$PDF_PATH"

Phase 3: 结构化分析（LLM 分析提取）

对提取的文本，按以下 12 个要素逐一分析：

Phase 4: 生成总结 MD 文件（保存在本地）

使用模板生成总结文件，保存在本地文件系统。

Step 4.1: 检查模板

TEMPLATE="$HOME/.local/share/ima-kb-backup/paper-summaries/TEMPLATE.md"
if [ ! -f "$TEMPLATE" ]; then
  # 创建默认模板
  cat > "$TEMPLATE" << 'TMPL'
# {论文标题}

> **文献类型**：{期刊/会议/学位论文}
> **来源**：{期刊名/会议名}
> **年份**：{年份}

## 基本信息

| 项目 | 内容 |
|------|------|
| 标题 | {标题} |
| 作者 | {作者} |
| 年份 | {年份} |
| 期刊/来源 | {来源} |
| 关键词 | {关键词} |

## 摘要

{原文摘要}

## 结构化分析

### 1. 研究背景

{背景}

### 2. 研究问题

{研究问题}

### 3. 研究结论

{研究结论}

### 4. 文献综合

{文献综合}

### 5. 文献批评（Research Gap）

{文献批评}

### 6. 研究方法

{研究方法}

### 7. 理论框架

{理论框架}

### 8. 一致性发现

{一致性发现}

### 9. 不一致性发现

{不一致性发现}

### 10. 研究贡献

{研究贡献}

### 11. 研究不足

{研究不足}

### 12. 未来展望

{未来展望}

## 阅读笔记

{个人笔记区域}

---

*本总结由 AI 辅助生成，所有事实性陈述均来自原文。推断内容已标注 `[推断]`。*
*生成时间：{日期}*
TMPL
  echo "✅ 已创建默认模板: $TEMPLATE"
fi

Step 4.2: 填写模板并保存

生成总结文件：

# 保存位置
OUTPUT_DIR="$HOME/.local/share/ima-kb-backup/paper-summaries"
FILENAME="{论文简称}_{第一作者}.md"
OUTPUT_PATH="$OUTPUT_DIR/$FILENAME"

# 将 LLM 分析结果填入模板，保存到 OUTPUT_PATH

Step 4.3: 同时在本地数据库记录（可选）

# 如果存在 papers.db，插入记录
DB_PATH="$HOME/.local/share/ima-kb-backup/papers.db"
python3 -c "
import sqlite3, os
db_path = '$DB_PATH'
if os.path.exists(db_path):
    conn = sqlite3.connect(db_path)
    conn.execute('''CREATE TABLE IF NOT EXISTS papers (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT,
        authors TEXT,
        year INTEGER,
        filename TEXT,
        summary_path TEXT,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )''')
    conn.execute('INSERT OR IGNORE INTO papers (title, authors, filename, summary_path) VALUES (?, ?, ?, ?)',
                 ('论文标题', '作者', '文件名.pdf', 'paper-summaries/文件名.md'))
    conn.commit()
    conn.close()
"

Phase 5: 质量检查

交付前执行以下检查：

1. 检查每个事实性陈述是否有来源标注（页码/图表编号）
2. 检查统计数据是否与原文一致
3. 检查推断内容是否正确标注 [推断]
4. 检查"阅读笔记"区域是否与原文内容分隔
5. 检查是否有编造或模糊表述

Phase 6: 报告结果

向用户报告：

✅ 分析完成！

📄 文献：{论文标题}
📁 PDF 位置：{PDF路径}
📝 总结位置：{输出路径}

[推断]标注：N 处
引用页码：N 处

⚠️ 需要你手动确认的事项：
- 检查 [推断] 标注的内容是否需要调整
- 在"阅读笔记"区域补充你的个人理解

技术配置

错误处理

与旧版本的区别

使用示例

场景一：用户已有 PDF 文件

> 用户说： "帮我分析这篇论文，路径是 ~/Downloads/paper.pdf"

>

> Agent 执行：

> 1. 检查 PDF 有效性（magic bytes）

> 2. 用 pdfplumber 提取文本和表格

> 3. 按 12 要素进行结构化分析

> 4. 生成总结 MD 文件到 paper-summaries/

> 5. 报告结果

场景二：用户从 IMA 知识库导出

> 用户说： "帮我分析一下IMA知识库里那篇关于会展竞争力的文献"

>

> Agent 回应：

> ```

> 好的，请先按以下步骤操作：

>

> 1. 打开 IMA 知识库

> 2. 搜索"会展竞争力"相关的文献

> 3. 点击下载 PDF 到本地

> 4. 然后告诉我文件路径

>

> 或者你把文件放到 ~/.local/share/ima-kb-backup/raw-pdfs/ 下

> 我来扫描并分析新增的文献

> ```

场景三：批量分析本地 PDF 文件夹

> 用户说： "把 raw-pdfs 里所有还没分析的 PDF 都处理了"

>

> Agent 执行：

> 1. 扫描 raw-pdfs/ 目录

> 2. 对比 paper-summaries/ 找出未处理的

> 3. 逐篇分析并生成总结

> 4. 报告完成情况