企业官网建设流程全解析

• 金融科技
• 示例工程

导读

本文深度解析 ai_quant_trade 仓库中 Vibe Trading 技能包（vibe_trading_skills）内的doc-reader技能：一个面向 LLM Agent 的通用文档读取工具（Universal Document Reader）。它通过统一的read_document工具入口，按文件扩展名自动分发解析逻辑，覆盖 PDF、Word、Excel、PowerPoint、图片 OCR、CSV/TSV、纯文本、配置文件、标记语言与绝大多数源码文件，并以统一的 JSON 信封结构返回抽取结果。读完本文，你将掌握该工具的完整格式支持矩阵、调用规范、返回结构、编码回退与 OCR 原理，以及它在研报摘要、合同审查、表格快速预览、扫描件 OCR 等真实量化研究场景中的工作流，并了解它与trade-journal（交易日志分析）、web-reader（网页读取）等兄弟技能的分工协作关系。

一、doc-reader 在技能包中的定位

doc-reader是 Vibe Trading 技能包中category: tool类别的工具型技能，其完整定义位于 doc-reader/SKILL.md，元信息如下：

--- name: doc-reader description: Read any common document/data file — PDF, Word (.docx), Excel (.xlsx/.xls), PowerPoint (.pptx), images (OCR), CSV/TSV, plain text, JSON/YAML/TOML, HTML/XML, and most source-code files. Use the `read_document` tool. category: tool ---

技能包整体来自 HKUDS 的 Vibe-Trading 项目（见 vibe_trading_skills/README.md），其中既有面向投研分析的分析型技能（如行为金融、宏观分析、多因子），也有大量工具型技能。doc-reader属于后者：它不产出任何投资结论，职责是把各种格式的本地文件"翻译"成 LLM 可以直接阅读的文本，是其他分析型技能的输入前端。

它的核心设计理念是单一入口 + 扩展名分发（dispatch by file extension）：无论用户上传的是 PDF 研报、Excel 交割单还是扫描截图，Agent 都只调用同一个read_document工具，由工具内部按文件扩展名路由到对应解析器，最终返回一个统一结构的 JSON 信封。这让 LLM 无需记忆多套解析 API，也避免了"用 Python 脚本临时解析"这种容易出错的做法。

二、支持的格式矩阵

doc-reader的格式支持覆盖日常办公与投研场景中的绝大多数文件类型，完整矩阵如下：

值得注意的边界行为：

• HTML/XML 不做剥离（no HTML stripping）：返回的是原始标记文本而非净化后的纯文本，因此该技能不适合"提取网页正文"的任务——网页正文抽取应交给web-reader技能的read_url工具（见 web-reader/SKILL.md），后者会把 URL 转成去除广告与导航的 Markdown。
• 源码文件原样返回：不重排、不重新缩进（Source-code files are returned raw; do not re-format or re-indent），以保证代码可被原样引用。

被拦截的文件类型

以下类型在上传（/upload）阶段即被拒绝：

Blocked(rejected at/upload): executables (.exe/.dll/.so/...) and archives (.zip/.tar/...). Ask the user to unpack archives locally first.

即可执行文件（.exe、.dll、.so等）与压缩包（.zip、.tar等）不可直接读取。文档明确要求：若用户上传的是压缩包，应请用户先在本地解压，再上传解压后的文件。这是从安全与实用性两方面考虑的设计——可执行文件存在安全风险，压缩包则需要解压后才能定位目标文件。

三、调用规范：直接调用工具，不要在 bash 里跑 Python

doc-reader有一条最高优先级的使用铁律：

Always call the tool directly — do not run Python from bash.

即：Agent 必须直接调用read_document工具，而不是通过bash启动 Python 脚本自行解析。这是为了让解析逻辑保持统一、可控、可审计，也避免临时脚本在编码、依赖、异常处理上出现偏差。

标准调用示例（摘自 doc-reader/SKILL.md）：

read_document(file_path="uploads/paper.pdf") read_document(file_path="uploads/annual_report.pdf", pages="1-10") read_document(file_path="uploads/contract.docx") read_document(file_path="uploads/sales.xlsx") read_document(file_path="uploads/deck.pptx") read_document(file_path="uploads/chart.png") # image → OCR read_document(file_path="uploads/config.yaml") read_document(file_path="uploads/notes.md")

参数说明：

• file_path：必填，指向已上传文件的路径（示例中统一放在uploads/目录下）。
• pages：仅对 PDF 生效，用于按页区间切片读取（如"1-10"表示第 1～10 页）；其他格式会忽略该参数。

pages参数的价值在于 PDF 是文档中最常见的长文本载体，配合下文"15000 字符截断"机制，可以逐段读取长篇研报，避免一次性返回被截断丢失内容。

四、统一返回信封（Return envelope）

无论什么格式，read_document的返回值都遵循同一个 JSON 结构：

{ "status": "ok", "file": "paper.pdf", "format": "pdf", "char_count": 52000, "truncated": true, "text": "..." }

各字段含义：

格式专属附加字段

在统一信封之上，不同格式会追加各自的附加键：

这些附加字段为 Agent 提供了重要的上下文元数据：

• PDF 的total_pages/pages_read让 Agent 能判断"这次只读了一部分，是否需要用pages继续切片"；ocr_pages则标明其中有多少页走了 OCR 路径，帮助判断文本质量。
• Excel 的sheets数组给出每张表的名字与行列规模，即使内容被 100 行预览截断，Agent 也能知道表的整体结构。
• 文本类的encoding记录最终采用的编码，出现乱码时可据此判断是编码识别错误还是内容本身问题。

截断机制

Content longer than 15000 chars is truncated; for PDFs use thepagesparameter to read slices.

单次返回的文本内容超过 15000 字符即被截断，并在信封中标记truncated: true。对于长 PDF，正确做法是用pages参数分段读取（例如先读pages="1-20"再读pages="21-40"），而不是期望一次拿到全文。这一设计是为了控制单次上下文占用（token budget），对 LLM Agent 而言是友好的。

五、典型工作流（Workflows）

doc-reader文档给出了四类高频场景的推荐工作流，覆盖了量化研究与投顾场景中绝大多数文件输入：

1. 论文 / 研报摘要（Paper / report summary）

1. read_document(file_path="paper.pdf") → full text 2. Extract abstract, methodology, conclusion → summarize

先整篇读取 PDF 获取全文，再抽取摘要、方法、结论进行总结。若 PDF 过长被截断，应结合pages参数分片读取，或用total_pages判断总页数后按章节分批处理。

2. 合同审查（Contract review）

1. read_document(file_path="contract.docx") → paragraphs + tables 2. Flag key clauses (termination, liability, payment, IP)

读取 Word 文档获得段落与表格，然后聚焦标记关键条款：终止条款、责任条款、付款条款、知识产权条款。

3. 表格快速预览（Spreadsheet quick-look）

1. read_document(file_path="sales.xlsx") → all sheet previews 2. If user wants trade journal analysis specifically, pivot to `analyze_trade_journal` tool instead (see trade-journal skill).

用read_document拿到所有工作表的预览（每表前 100 行）用于"瞄一眼"；但如果用户的目标是交易日志（交割单）分析，应切换到analyze_trade_journal工具（见 trade-journal/SKILL.md），而不是用通用读取硬啃。这是技能包内"通用读取器"与"专用分析器"的典型分工：通用工具负责兜底读取，专用工具负责深度分析。

4. 图表 / 截图 / 扫描 PDF（Chart / screenshot / scanned PDF）

1. read_document(file_path="scan.png") → OCR text 2. If OCR returns empty, tell the user; don't fabricate.

图片与扫描版 PDF 走 OCR 提取文字。若 OCR 返回空文本，必须如实告知用户，不得编造内容——这是文档强调的诚实性红线。

六、关键实现细节与使用注意事项（Notes）

1. 编码回退顺序

Encoding fallbackorder for text: utf-8 → utf-8-sig → gbk → gb2312 → big5 → latin-1.

纯文本类文件（含未知扩展名按文本读取时）的编码识别依次尝试：

1. utf-8
2. utf-8-sig（带 BOM 的 UTF-8）
3. gbk（简体中文常用编码）
4. gb2312（GBK 的前身）
5. big5（繁体中文常用编码）
6. latin-1（兜底，永不失败）

这一设计对中国 A 股投研场景非常关键：券商的交割单、行情导出、公告文本大量使用 GBK/GB2312 编码（如 trade-journal/SKILL.md 中明确提到同花顺、东方财富的 A 股 CSV 通常为 GBK 编码，而富途的港美股 CSV 为 UTF-8），编码回退保证了这类文件无需用户手动转码即可读取。文本类返回信封中的encoding字段会标明最终命中的编码。

2. OCR 引擎与依赖

OCRuses RapidOCR; if the package is missing, image/scanned files return emptytextwith anotefield — tell the user to installrapidocr-onnxruntime.

图片与扫描件的 OCR 由RapidOCR（基于 ONNX Runtime 的 OCR 引擎）完成。依赖缺失时的降级行为是：返回空的text并在响应中附带note字段说明原因，此时应提示用户安装：

rapidocr-onnxruntime

换言之，OCR 能力不是内置的硬依赖，而是"可选增强"：装了 RapidOCR 才有 OCR 能力，没装则如实返回空并给出提示，而不是硬编造识别结果。这也再次呼应了该工具"不编造、如实反馈"的行为准则。

3. Excel 预览行数限制

Excel previewsare limited to 100 rows per sheet to stay in budget. If the user needs full data (e.g. trade journals), callanalyze_trade_journalinstead.

每个工作表最多返回前100 行作为预览，目的是控制 token 预算（stay in budget）。当用户需要全量数据（例如完整交割单做交易行为分析）时，应转向analyze_trade_journal专用工具而非依赖通用读取。结合前面"表格快速预览"工作流可以看出：Excel 的 100 行预览是"看结构"用的，深度分析要交给专业工具。

4. 源码文件原样返回

Source-code filesare returned raw; do not re-format or re-indent.

源码类文件按原样返回文本，不做格式化或重排。这对代码审查、策略代码理解场景很重要——Agent 拿到的必须是用户文件中的真实代码，任何"美化"都可能引入偏差。

七、与技能包内其他技能的协作关系

doc-reader不是孤立存在的，它在 Vibe Trading 技能包中处于"文件输入枢纽"位置：

• 与trade-journal的分工：doc-reader提供通用 Excel/CSV 预览（100 行截断），而 trade-journal/SKILL.md 中的analyze_trade_journal工具负责对同花顺/东方财富/富途/通用格式交割单做专业解析，输出交易画像与四大行为偏差诊断（处置效应、过度交易、追涨、锚定），并支持analysis_type（full/profile/behavior/strategy）与filter_expr（日期区间、标的、市场）筛选。当用户目标是"分析我的交割单"时，应直接调用后者。
• 与shadow-account的衔接：shadow-account/SKILL.md 明确要求其前提是"用户已上传交割单且analyze_trade_journal已跑过"——即交割单先经专用工具解析（而不是通用读取），再进入影子账户策略提炼与多市场回测流程。
• 与web-reader的互补：web-reader/SKILL.md 的read_url负责把 URL 转成干净 Markdown（读取在线 API 文档、研报网页、GitHub README 等），而doc-reader负责本地上传文件。二者一个管"线上 URL"，一个管"本地文件"，共同构成技能包完整的内容摄取能力。

从技能包的整体目录结构（vibe_trading_skills）看，doc-reader与web-reader、data-routing等工具型技能并列，为数十个分析型技能（如研报复现、财报分析、形态识别、情绪分析）提供文件读取底座。它不产出观点、不触发交易，只做一件事：把任意格式的文件变成 LLM 可读的、结构化的文本——这正是 Agent 化量化工作台最基础也最关键的环节。

八、小结：何时用、怎么用、注意什么

doc-reader的价值在于"一个工具、一个信封、覆盖所有格式"：对 LLM Agent 而言，读取任何文件都只需记住一个入口和一套返回结构；对技能包而言，它为下游所有需要文件输入的投研分析流程提供了统一的、诚实可靠的文本抽取层。理解它的格式矩阵、截断机制、编码回退与 OCR 降级行为，是正确使用 Vibe Trading 技能包处理研报、交割单、财报等真实文件的第一步。

• 金融科技
• 示例工程