文档加载器与本地文件摄取

结论

Document Loader 把不同数据源统一成 Document，共同接口是 load() 与 loadAndSplit()；加载与切分应在架构上分层，便于重跑、换切分策略和追踪来源。
文件加载器只适用于 Node.js。目录、文件路径、符号链接、压缩炸弹和超大文件都需要应用侧限制，不能让模型提供任意路径。
/document_loaders 与 /document_loaders/index 是同正文别名；两条 source 保留、知识不重复。本组共 9 条原始路由。

统一数据契约

一个可维护的摄取管道应至少保留：

pageContent：规范化后的正文；
metadata.source：稳定、可追溯的 URI 或受控路径；
原始对象版本、内容哈希、采集时间、MIME/type、权限标签；
parser/normalizer/splitter 的版本。

loadAndSplit() 适合快速试验，生产更推荐 load() 后显式调用 splitter：原文只需摄取一次，切分策略变化时无需重新访问源系统。

本地文件加载器

Loader	输入语义	关键边界
`TextLoader`	单个纯文本路径	Node-only；一文件通常得到一个 Document
`DirectoryLoader`	目录 + 扩展名到 loader factory 的映射	递归范围、符号链接和未知扩展名需明确策略
`MultiFileLoader`	多个独立路径 + 扩展名映射	输入顺序、失败隔离与部分成功要可观测
`JSONLoader`	JSON，可选 JSON Pointer	无 pointer 时抽取所有字符串，可能丢失结构上下文
`JSONLinesLoader`	每行一个 JSON + JSON Pointer	每个 JSON 对象生成一个 Document，适合流式批处理
`OracleDocLoader`	Oracle 表、文件或目录	Node-only；借助 Oracle Text 处理 150+ 格式

DirectoryLoader 与 MultiFileLoader 的文档示例仍引入 @langchain/community 的 CSV/PDF loader，页面明确警告该包不再维护，示例可能过时或损坏。新增项目应寻找受维护的独立 integration package，或将相关解析器隔离并固定版本。

JSON 与 JSONL

JSON Pointer 决定抽取哪个字段；pointer 不应由外部用户任意控制，以免越权读取对象的其他部分。
无 pointer 的 JSONLoader 会遍历并加载发现的字符串。它适合小型内容文件，不适合直接处理含敏感字段或巨大嵌套结构的业务 JSON。
JSONL 每行独立，天然适合 checkpoint、失败行隔离和并行；应保存行号/record id 到 metadata，以便恢复和去重。
摄取前先做字节大小、深度、编码和 schema 验证；坏记录进入隔离队列，而不是让整批静默丢失。

Oracle 数据库内摄取

OracleDocLoader 可从数据库行、单文件或目录加载，并配合 OracleTextSplitter 在数据库能力附近切分。优势是能把 Oracle 的安全、事务、HA 与文档/向量流程放在同一系统；代价是 Node driver、数据库版本、Oracle Text/Vector 能力和连接池运维。

生产要点：

不使用 SYSTEM；为摄取创建最小权限账户。
凭据由 secret manager 注入，不出现在代码、日志或 metadata。
数据库连接使用池并在任务结束释放；长文件解析设置 statement/request timeout。
150+ 格式支持不代表每种格式都能无损提取；对目标格式建立 golden corpus，验证正文、页码、表格与编码。

可恢复摄取流程

发现：只枚举 allowlist 根目录或受控对象列表。
指纹：记录 source、mtime/version、size 和 content hash，跳过未变化对象。
加载：限制单文件与批次资源；一个对象失败不吞掉整个批次。
规范化：统一编码、换行与 metadata，不修改权威原件。
持久化原始 Document，再独立切分、embedding、upsert。
只有当目标索引提交成功才推进 checkpoint；重跑按稳定 id 幂等覆盖。