research-docs

研究文档 — 使用可视化引用进行文档问答

使用 LiteParse 解析文档，根据解析出的文本回答问题，并生成一份 HTML 报告，在页面图像上突出显示来源引用。

参数

$ARGUMENTS 应包含：

• 第一个参数（$0）：包含文档的数据目录路径
• 其余参数：要回答的问题

如果缺少其中任何一项，请询问用户提供。

第 1 步 — 解析文档

**重要：**始终使用下方捆绑的 Python 脚本进行解析。不要直接调用 lit 或 liteparse CLI 命令——只能使用 generate_report.py。

运行捆绑的解析脚本，从所有受支持的文件中提取文本和边界框：

python "${CLAUDE_SKILL_DIR}/scripts/generate_report.py" \
    --skill-dir "${CLAUDE_SKILL_DIR}" \
    --dir "$0" \
    --parse-only \
    --output /tmp/research_docs_parsed.json

此脚本会发现并解析目录中的所有受支持文件：

• LiteParse 格式：PDF、DOCX、PPTX、XLSX、图像（最多 50 个文件）
• 纯文本：.txt、.md、.rst（直接读取）

输出为 JSON 文件，其中包含已解析的文本，以及每页的边界框坐标。

如果目录中的文件超过 50 个，且用户的问题涉及前 50 个文件之外的特定文档，请使用更精确的 --dir 参数指向某个子目录后重新运行，或询问用户要重点处理哪些文件。

第 2 步 — 阅读已解析的内容

使用 Read 工具读取 /tmp/research_docs_parsed.json。重点关注：

• 每个文件的 name 和 type
• 对于 LiteParse 文件：每页的 text 字段（跳过原始 textItems——这些数据用于渲染边界框）
• 对于纯文本文件：text 字段
• 用于查看总数的 summary 对象

在回答前，先全面了解所有文档的内容。

步骤 3 — 使用引文作答

使用解析后的文本作为上下文，回答用户的问题。将回复写成 JSON 文件：

cat > /tmp/research_docs_answer.json << 'ANSWER_EOF'
{
  "question": "<the user's question>",
  "answer": "<your answer in markdown with [N] citation markers>",
  "citations": [
    {
      "file": "<filename e.g. report.pdf>",
      "page": <1-indexed page number>,
      "quote": "<exact verbatim substring from the parsed text>",
      "relevance": "<explanation of what this value/quote means and how it supports the answer>"
    }
  ]
}
ANSWER_EOF

答案的关键规则：

• 在答案文本中嵌入类似 [1]、[2] 等行内引文标记，对应 citations 数组中从 1 开始计数的位置
• 将标记放在其支持的句子或主张末尾
• 示例："储备银行信贷总额为 **$6,613,609 million** [1]，其中直接持有的证券为 $6,375,679 million [2]。"

引文内容的关键规则：

• 引用证据，而不只是标签。 用户需要核查你的主张。如果你说“收入为 $1.2B”，应引用文本中的实际数字 1,200,000，而不只是标题“收入”。如果标签和值位于同一页，也可以同时引用两者。
• 引用具体数据值，包括数字、百分比、日期、金额和数量。这些是用户需要核实的内容。
• 每个 relevance 字段都应说明“这意味着什么”，而不只是复述标签。例如，不要写“总收入”，而应写“2025 年第三季度总收入，较去年同期增长 12%，支持了上述增长趋势。”
• 添加 5–15 条引文，涵盖答案中的所有关键主张和数据点。

引文格式的关键规则：

• quote 必须与解析后的文本逐字符完全一致。它用于通过精确字符串匹配来查找边界框。不要改写、重新表述、清理或修正错字。
• 优先使用简短、精准的引文，例如单个值 $2,769.23 或简短的连续短语 Securities held outright（少于 40 个字符）。较短的引文更容易可靠地匹配边界框。
• 切勿跨表格列引用。 表格中的每个单元格都是单独的文本区域。应引用单个单元格的值（例如 $16,615.38），而不是横跨多列的一串值（例如 $2,769.23 80.00 $2,769.23 $16,615.38）。值之间的大段空白表示它们属于不同的边界框，无法作为一个整体匹配。
• 如果文本中有特殊字符、连字符或格式异常，必须按原样准确包含。
• page 从 1 开始计数（与 LiteParse 的 pageNum 一致）
• file 仅填写文件名（不是完整路径）
• 对于纯文本文件（.txt、.md），将 page 设为 0（这些文件没有页码）

步骤 4 — 生成 HTML 报告

运行捆绑脚本的生成模式，以生成可视化报告：

python "${CLAUDE_SKILL_DIR}/scripts/generate_report.py" \
    --skill-dir "${CLAUDE_SKILL_DIR}" \
    --dir "$0" \
    --answer-file /tmp/research_docs_answer.json \
    --output research_docs_output/

此操作将：

1. 仅解析并截取有引文的页面（高效，无需处理所有页面）
2. 查找每条引文对应的边界框
3. 生成包含答案、页面图像和高亮内容的独立 HTML 报告
4. 在默认浏览器中打开报告

步骤 5 — 呈现结果

告知用户：

1. 报告的保存位置（脚本输出的文件路径）
2. 答案的简要摘要（2–3 句话）
3. 找到的引文数量