# ADR-0006：采用确定性本地解析、切分与出域清单

- **状态：** accepted
- **日期：** 2026-07-13

## 背景

文档进入百炼向量模型前，系统必须能证明“发送了哪段文本、来自哪个版本和页面、由什么配置
产生、是否经过明确审批”。如果解析和切分结果随运行变化，embedding cache、引用锚点、审批
manifest 和实验结果都会失去可复现性。PDF、DOCX 和扫描图件的能力也不能被模糊成同一种
“已解析”状态。

## 决策

第一版建立纯本地、无模型调用的确定性入库核心：

- 严格验证文件大小、扩展名、声明 MIME 与内容签名；用户文件名永不作为存储路径。
- TXT 支持严格 UTF-8/UTF-16；Markdown 恢复标题层级；DOCX 仅在 ZIP/XML 安全上限内提取
  标题、段落和表格行。
- 不手写 PDF 文本或空间解析。没有可靠 parser/OCR adapter 时，PDF 明确进入
  `OCR_REQUIRED`，不产生切片或出域清单。
- 规范化文本按结构块优先切分，默认 target 512、hard max 800、overlap 64。Tokenizer
  将 `ZK1203` 等字母数字地质标识符视为一个 token；块边界只能把窗口扩展到 hard max 内。
- `display_text`、`cloud_text`、`embedding_text` 分离；embedding 输入固定为版本化前缀加
  已审批 cloud text。
- parser、normalization、chunk、cloud policy 和 embedding 配置均计算 profile hash；规则变化
  生成新版本或 cache epoch，不能错误复用旧向量和审批。
- chunk ID、source anchor 和 outbound manifest 由输入 hash、配置 hash、ordinal 与源范围
  确定性派生。每个锚点保留文档版本、页、块、行和字符范围；DOCX 无渲染引擎时物理页为
  `null`，不能伪造页码。
- 任何外发必须在 manifest hash 与审核请求完全匹配后发生。上传/解析阶段无百炼调用。

## 安全限制

DOCX adapter 拒绝路径穿越、符号链接、重复条目、加密标志、宏、ActiveX、嵌入对象、DTD、
XML entity、超大条目、过多条目和异常压缩比。错误只返回稳定 code，不包含文件名、正文、
路径、密钥形态或底层异常。

凭证形态出现在上传文本时默认 fail closed，以防误把配置文件或日志当知识文档外发。未来如果
确有合法语料包含类似字符串，必须新增受审计的本地脱敏策略，不能简单关闭该门禁。

## 被否决方案

1. **按固定字符数随意切片：** 中文、地质编号、表格和章节边界不可复现，无法稳定评测。
2. **直接把原文同时用于展示、向量和生成：** 无法证明脱敏和出域审批覆盖的准确文本。
3. **用标准库或正则手写 PDF 解析：** 不能可靠处理字体映射、多栏顺序、扫描页和加密状态。
4. **把 OCR 图例视为空间理解：** OCR 只能识别局部文字，不恢复地图拓扑、比例和几何关系。

## 后续约束

- 调整 token 规则、target/max/overlap、前缀、脱敏策略或 parser 行为时，必须修改 profile hash
  版本并重跑 golden fixture、manifest、向量缓存和引用回归。
- 引入 PyMuPDF、OCR 或多模态模型需要独立 adapter、依赖/镜像评审和 ADR；不能替换 raw
  artifact，必须保留新 revision。
- 解析成功不等于可出域；只有 `CLOUD_APPROVED` 且 manifest/profile 绑定一致的 chunk 才能
  进入 Embedding、Rerank 或 Chat。