本地文献分析工具

从 IMA 文献分析 skill（ima-paper-analysis）的分析流程中剥离出来的纯本地版本。

去掉了所有 IMA API 调用和 COS 上传依赖，仅保留文献分析的核心能力。

核心设计

⛔ 强制规则

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——所有文献必须通过本地文件路径提供。

执行流程

Phase 0: 环境检查

# 检查本地知识库目录
BACKUP_DIR="$HOME/.local/share/ima-kb-backup"
mkdir -p "$BACKUP_DIR"/{raw-pdfs,paper-summaries,literature-catalog,scripts}

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

# 确保模板存在
TEMPLATE="$BACKUP_DIR/paper-summaries/TEMPLATE.md"
if [ ! -f "$TEMPLATE" ]; then
  echo "⚠️ 模板不存在，将在 Phase 4 中自动创建"
fi

Phase 1: 获取 PDF 文件

引导用户提供 PDF 文件。不接受 IMA 知识库自动拉取。

方式 A：用户提供本地路径（推荐）

# 用户直接给路径
PDF_PATH="/path/to/paper.pdf"

# 验证文件存在
test -f "$PDF_PATH" && echo "✅ 文件存在" || echo "❌ 文件不存在"

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

用户提供路径后，可以选择复制到 raw-pdfs/ 目录归档：

cp "$PDF_PATH" ~/.local/share/ima-kb-backup/raw-pdfs/

方式 B：用户从 IMA 知识库手动导出

当用户说"帮我分析IMA里的那篇论文"时，引导用户：

📋 请按以下步骤操作：

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

本地路径示例：
  - ~/Downloads/论文名称.pdf
  - ~/Desktop/论文名称.pdf

方式 C：批量扫描 raw-pdfs/ 目录

当用户说"把还没分析过的 PDF 都处理了"时：

BACKUP_DIR="$HOME/.local/share/ima-kb-backup"
RAW_DIR="$BACKUP_DIR/raw-pdfs"
SUMMARY_DIR="$BACKUP_DIR/paper-summaries"

# 列出 raw-pdfs 中所有 PDF
for pdf in "$RAW_DIR"/*.pdf; do
  [ -f "$pdf" ] || continue
  basename=$(basename "$pdf" .pdf)
  
  # 检查是否已有对应的总结
  if [ -f "$SUMMARY_DIR/${basename}*.md" ]; then
    echo "⏭️ 已分析: $basename"
    continue
  fi
  
  echo "📄 待分析: $basename"
done

Phase 2: 读取 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"
# 文件名格式：{论文简称}_{第一作者}.md
# 如果无法确定作者，使用PDF文件名作为基础
FILENAME="{论文简称}_{第一作者}.md"
OUTPUT_PATH="$OUTPUT_DIR/$FILENAME"

# 将分析结果填入模板，写入 OUTPUT_PATH
echo "📝 总结已保存: $OUTPUT_PATH"

Phase 5: 质量检查

交付前执行以下检查：

□ 每个事实性陈述有来源标注（页码/图表编号）
□ 统计数据与原文一致
□ 推断内容标注了 [推断]
□ "阅读笔记"区域与原文内容分隔
□ 没有编造或模糊表述
□ 模板各段落已填充完整（没有残留的 {占位符}）

Phase 6: 报告结果

✅ 分析完成！

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

📊 标注情况：
  - [推断] 标注：N 处
  - 引用页码：N 处

⚠️ 需要你手动确认：
  1. 检查 [推断] 标注的内容是否需要调整
  2. 在"阅读笔记"区域补充你的个人理解
  3. 如需引用，建议对照原文PDF核对关键数据

目录结构

~/.local/share/ima-kb-backup/
├── raw-pdfs/                    ← 放下载的 PDF 文件
│   └── 会展企业竞争战略.pdf
├── paper-summaries/             ← 生成的总结 MD 文件
│   ├── TEMPLATE.md              ← 总结模板
│   └── 会展企业竞争战略_张三.md ← 具体的总结文件
├── literature-catalog/          ← 文献目录索引（可选）
└── scripts/                     ← 辅助脚本（可选）

技术依赖

零外部 API 依赖。 不需要 IMA 凭证、不需要 COS 上传、不需要任何网络请求。

错误处理

使用示例

示例一：用户已有 PDF

> 你： 帮我分析这篇论文，路径是 ~/Downloads/会展企业竞争战略.pdf

>

> Agent 执行：

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

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

> 3. 按 12 要素逐项分析

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

> 5. 给出质量检查和报告

示例二：用户想分析 IMA 里的文献

> 你： 帮我分析IMA知识库里那篇关于会展竞争力的文献

>

> Agent 回应：

> ```

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

>

> 1. 打开 IMA（腾讯元宝）知识库

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

> 3. 右键点击 → 下载 PDF 到本地

> 4. 然后把文件路径发给我

>

> 例如：~/Downloads/会展企业竞争力研究.pdf

> ```

示例三：批量处理

> 你： 把 raw-pdfs 里还没分析的 PDF 都处理了

>

> Agent 执行：

> 1. 扫描 raw-pdfs/ 目录中的所有 PDF 文件

> 2. 检查 paper-summaries/ 中是否有对应总结

> 3. 逐篇分析未处理的 PDF

> 4. 生成每篇的总结文件

> 5. 汇总报告完成数量和位置