跳转至

设计决策记录

状态: 草稿 读者: 项目核心开发者、后续维护者 范围: 记录已经做出的关键设计决策、背景、替代方案和影响 非目标: 替代主题设计文档;记录所有临时讨论

何时写 ADR

当一个选择满足任一条件时,应进入本目录:

  • 会影响 API、CLI、SDK 或 middle_json 的长期兼容性。
  • 会影响模块边界、数据模型、进程边界或存储模型。
  • 有多个合理替代方案,且未来维护者需要知道为什么选了当前方案。
  • 决策一旦落地,回滚成本较高。

命名规则

使用递增编号和短标题:

0001-local-doclib-storage.md
0002-api-upload-flow.md
0003-middle-json-coordinate-system.md

已记录决策

ADR 状态 主题
ADR-0001 已接受 JSON 输出格式命名
ADR-0002 已接受 Force 与 Invalidate 缓存语义
ADR-0003 已接受 Parse 请求等待批次语义
ADR-0004 已接受 Doclib HTTP API 资源模型
ADR-0005 已接受 Doclib Interface、Client 与 Server 契约一致性
ADR-0006 提议中 Doclib 文件变化检测与重新入库语义
ADR-0007 已接受 Doclib 文件可达性生命周期
ADR-0008 已接受 Doclib Forget Path 语义
ADR-0009 已接受 Doclib Scan 后台任务
ADR-0010 已接受 Doclib Watch CLI 与 Rescan 边界
ADR-0011 已接受 Doclib Doc Short ID
ADR-0012 已接受 Doclib Block Locator
ADR-0013 已接受 Doc Content Progressive Reading
ADR-0014 已接受 MinerU Read Command
ADR-0015 已接受 CLI Output 与 JSON 组合语义
ADR-0016 已接受 MinerU Kit Parse Command
ADR-0017 已接受 MinerU Kit API Server Command
ADR-0018 已接受 MinerU Kit VLM Server Command
ADR-0019 已接受 MinerU Kit Models Command
ADR-0020 已接受 Doclib Schema Stability Boundary
ADR-0021 已接受 Doclib 本地 Transport 与 Endpoint Discovery
ADR-0022 已接受 Doclib 文件类型、Tier 与 Remote 语义
ADR-0023 已接受 CLI Runtime 输出、错误与退出码集中契约
ADR-0024 已接受 文件类型与 Tier 归一化语义
ADR-0025 已接受 模型下载与本地模型目录
ADR-0026 已接受 Remote API Usage 与 API Key 引导
ADR-0027 已接受 Doclib 视觉 Block Locator 图片引用
ADR-0028 已接受 CSV 本地结构化 Flash 解析
ADR-0029 已接受 RTF 原生语义 Flash 解析
ADR-0030 已接受 ODF 原生语义 Flash 解析
ADR-0031 已接受 HTML 原生静态语义 Flash 解析
ADR-0032 已接受 OFD 原生固定版式 Flash 解析
ADR-0033 已接受 Middle JSON 2.0 结构化行内 Span
ADR-0034 已接受 TSV 独立文件后缀

模板

# ADR-0000: 决策标题

状态: Proposed / Accepted / Deprecated / Superseded
日期: YYYY-MM-DD
相关文档: ../architecture.md

## 背景

描述为什么需要做这个决策。

## 决策

描述最终选择。

## 替代方案

列出主要替代方案,以及没有选择它们的原因。

## 影响

描述对实现、兼容性、测试、文档和用户体验的影响。

## 后续动作

列出需要跟进的具体工作。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU