# 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 |

- 限制：单文件 50MB（可配置），图片超过 2000px 时压缩，会话工作区总量 2GB。
- 前端交互：拖拽、粘贴（截图直接 Ctrl+V）、点选；输入框上方显示附件条（缩略图 + 文件名 + 移除按钮）。
- 上传后计算 sha256，同一会话内去重。

## 2. 官方客户端怎么分析文档（调研结论）

详见 [research/document-analysis-approaches.md](../research/document-analysis-approaches.md)。

**结论：官方方案就是"模型原生多模态阅读 + 沙箱里执行 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、图片 |

所以本项目沿用同一套思路，不另造轮子：
1. **视觉/阅读**交给模型：截图、PDF 页面、图表图片直接给模型看。
2. **计算**交给代码：在工作区内运行 Python（pandas 等），结果可复现。
3. **产出规范**交给技能：把官方的 xlsx/docx/pdf/pptx 技能放进共享技能目录，两个引擎共用。

## 3. 运行环境与技能

### 3.1 共享 Python 环境
`/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（经过审批）。

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

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

## 4. 资料检索

### 4.1 本地资料
- **资料库（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 再按需读取原文。

### 4.2 远程资料

| 来源 | 方式 |
|---|---|
| 公网搜索 | 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` 工具，抓取行为和安全策略就只需维护一处。

## 5. M1 实现记录

- 文档格式转换由 `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 → 渲染预览图自检，全程在受限沙箱中完成。