07 文件、文档分析与资料检索

1. 上传：数据文件与截图

类型	处理
截图/图片（png/jpg/webp/gif）	存到 `uploads/`；发送消息时作为多模态输入直接交给模型（Claude 用 image content block，Codex 用本地图片输入），同时保留文件，方便 Agent 后续用脚本处理
数据文件（csv/xlsx/json/parquet）	存到 `uploads/`；消息中附带文件清单（路径、大小、类型），由 Agent 自行读取
文档（pdf/docx/pptx/md/txt）	同上；Claude 可以直接用 Read 工具多模态阅读 PDF

结论：官方方案就是"模型原生多模态阅读 + 沙箱里执行 Python/Node 代码 + 技能（Skills）指导"三者组合，Python 是主力。

产品	方案
Claude.ai	PDF 和图片由模型原生阅读（PDF 按页提供文本和页面图像）；计算与文件生成在服务端沙箱容器中执行代码（Python 为主）；用官方 Skills（xlsx / docx / pdf / pptx）规范操作：xlsx 用 openpyxl + pandas，并用 LibreOffice 重算公式；pdf 用 pypdf / pdfplumber；docx 用 docx-js（Node）生成、pandoc 读取
ChatGPT	Code Interpreter（Python 沙箱）做数据分析；File Search 对文档做检索；图片由模型视觉能力处理
Claude Code / Codex CLI	没有托管沙箱，在本机执行同样的工具链；Claude Code 的 Read 工具可以直接读 PDF、图片

所以本项目沿用同一套思路，不另造轮子：

/srv/agent-server/runtime/py（venv，Agent 只读；已创建，版本锁定在 runtime/requirements.lock），已安装：

用途	包
数据处理	pandas, numpy, pyarrow, duckdb（直接用 SQL 查 CSV/Parquet）
可视化	matplotlib, seaborn, plotly（交互式 HTML 图表）
Excel	openpyxl, xlsxwriter
Word / PPT	python-docx, python-pptx
PDF	pypdf, pdfplumber, reportlab
转换	markitdown（多种格式统一转 Markdown）

系统工具（均已安装）：LibreOffice、poppler-utils、pandoc、ripgrep、bubblewrap、socat、中文字体 fonts-noto-cjk。

中文图表：runtime/matplotlibrc 中已配置 Noto Sans CJK 字体，服务启动 Agent 时通过环境变量 MATPLOTLIBRC 注入（已验证中文标题和负号都能正常渲染）。

Node 侧：docx（docx-js），供 docx 技能使用，随项目依赖在 M1 安装。

Agent 不允许 pip install 到共享环境；需要临时依赖时，在工作区内创建临时 venv（经过审批）。

目录：/srv/agent-server/skills/，Claude 与 Codex 共用（Agent Skills 格式：<name>/SKILL.md + 脚本）。
初始内容：官方 xlsx、docx、pdf、pptx 技能（来自 anthropics/skills 公开仓库，使用前核对许可证）+ 自定义的"报告规范"技能（统一的报告结构、图表配色、中文字体）。
Profile 中选择启用哪些技能；适配层负责把技能目录挂到各引擎的技能加载路径。

系统提示词中约定：最终产物写入 outputs/，中间文件随意存放。outputs/ 下的新文件触发 file.changed，前端以"产出物卡片"展示（可预览、可下载）。

资料库（Knowledge Root）：在后台"资料库"页设定，字段包括名称、路径、说明（会告诉 Agent 这里放的是什么）、读写属性（默认只读）、启用状态。
保存时检测：路径是否存在、服务进程能否看到（home 下的路径受 ProtectHome 影响，见 06 §5.2）、是否命中全局禁止项。
Profile 勾选启用哪些资料库；它们会并入该 Profile 的文件访问策略（06 §4），分别映射为 Claude 的 additionalDirectories 加沙箱 allowRead，以及 Codex 权限配置中的 read 条目。
系统提示词中自动附上"可用资料库清单（名称、路径、说明）"，让 Agent 知道去哪里找资料。
检索手段，分两期：
- M1：直接检索。Agent 用 Grep/Glob/Read、ripgrep、pdftotext、markitdown 自行查找，适合资料量不大（几千个文件以内）的情况。
- M3：索引检索。MCP Gateway 提供 kb_search 工具：后台任务把资料转成文本（markitdown）后建 SQLite FTS5 全文索引（中文用 jieba 或 ICU 分词），可选再加向量检索。返回片段和出处路径，Agent 再按需读取原文。

来源	方式
公网搜索	Claude WebSearch / Codex web_search（均由厂商服务端执行）
网页抓取	Claude WebFetch（应用层拦截私网地址）；Codex 在沙箱联网审批通过后用 curl 等工具抓取，或通过 Gateway 的 `web_fetch` 工具（统一抓取、清洗为 Markdown、拦截私网）
内部平台	暂缓，预留 MCP Gateway 连接器（见 08）
远程文件存储（NAS / WebDAV / 网盘）	两种方式：(a) 用 rclone 只读挂载为资料库；(b) 写一个连接器，提供 `list/search/read` 工具

推荐两个引擎统一使用 Gateway 的 web_fetch 工具，抓取行为和安全策略就只需维护一处。

文档格式转换由 convert_document 工具完成（docx/xlsx/pptx → pdf 等），不在 Bash 中调用 soffice（原因见 06 §8）。
共享技能目录按 Claude 插件格式组织（skills/.claude-plugin/plugin.json + skills/skills/<name>/SKILL.md），仓库中的 skills/ 是源码，部署时同步到 /srv/agent-server/skills。
当前只有一个自写技能 report-conventions（报告产出规范、中文图表、Word/Excel 写法、格式转换、自检清单）。官方 xlsx/docx/pdf/pptx 技能的许可证写明"由你与 Anthropic 的协议约束"，没有复制进来（11 Q5）。
实测验收：上传 xlsx 和截图 → 模型从截图读出目标值 → pandas 分析 → 中文柱状图 → python-docx 生成报告 → 转换为 PDF → 渲染预览图自检，全程在受限沙箱中完成。