mineru library

状态: Draft 读者: CLI 使用者、Agent skill 作者、核心开发者 范围: mineru 本地文档库相关命令：search、find、list、show、config、watch、scan、invalidate、forget、cleanup 非目标: SQLite schema 字段级定义；完整配置优先级规范 来源: 由根目录旧 CLI 底稿迁移整理而来

1. 定位

mineru 不只是一次性解析命令，也维护本地文档库。本页描述文档库相关 CLI 能力。

详细数据模型见 系统架构，配置主题见 配置体系。

2. search

mineru search 面向已建立内容索引的文档检索，包括解析内容和直接索引的 text 源内容。

mineru search "keyword"
mineru search "keyword" --tier basic
mineru search "keyword" --min-tier basic --type pdf

行为：

• 查询 fts_contents，未建立内容索引的文件不会命中正文检索。
• 按文档 SHA256 去重。
• 支持按 file_type、tier、min_tier 过滤。
• 返回文档大小、页数、命中片段、可空的 snippet 来源 tier，以及关联的全部 file aliases。
• text 源内容的 tier 为 null；指定 --tier 或 --min-tier 时不返回这类结果。
• JSON 返回全部 file aliases 及其状态，并按 file id 降序排列。
• 非 JSON 输出存在 active files 时只展示 active paths；没有 active file 时展示全部 inactive paths。
• 已索引的 orphan 文档仍可命中，非 JSON 输出提示文件已不存在。
• 通过 --json 提供结构化输出。

JSON 输出中的每条结果至少包含:

字段	说明
size_bytes	文件大小。
page_count	文档页数；未知时为 null。
snippet	命中的内容片段。
tier	snippet 来源解析 tier；直接索引的 text 源内容为 null。
files	与文档 SHA 关联的全部 files，包含 path、filename、ext、status。

search 不匹配 filename；按文件名定位使用 mineru find。

search 不应在 telemetry 中记录 query 或 snippet，但 CLI JSON 可以返回 snippet 供用户和 Agent 使用。

3. find

mineru find 面向文件名定位，不搜索正文内容。

mineru find "report"
mineru find "report" --ext pdf
mineru find "report" --ext pdf --limit 50 --offset 100

行为：

• 查询 fts_filenames 和文件 metadata。
• 支持按 ext 过滤。
• 默认对最后一个查询词进行前缀匹配，例如 bench 可匹配 bench1.pdf；多词查询仅最后一词匹配前缀。显式 bench* 等价。
• 支持 --limit/-n（默认 50）和 --offset（默认 0）；limit 必须为正，offset 必须非负。
• 在扩展名过滤、文件状态刷新后分页，total 表示全部有效匹配数，不受单页大小或 200 条候选上限影响。
• 按相关性及 file id 稳定排序；同一 SHA256 的不同文件路径仍是独立搜索结果。
• 可返回同一 SHA256 的多个路径。
• 可用于解析前确认目标文件。
• 超出结果末尾时返回空列表及正确的总数。

find JSON 输出中的每条结果至少包含:

字段	说明
filename	文件名。
size_bytes	文件大小。
page_count	文档页数；未知时为 null。

4. list

mineru list 列出 doclib 资源集合：

mineru list parses
mineru list scans
mineru list files
mineru list docs

当前过滤能力：

命令	过滤参数
mineru list parses	--status、--tier、--limit/-n、--offset
mineru list scans	--status、--kind、--watch-id、--limit/-n、--offset
mineru list files	--status、--ext、--watch-id、--limit/-n、--offset
mineru list docs	--file-type、--limit/-n、--offset

四个子命令都支持 --json。

5. show

mineru show file <path> 查看本地路径对应的 file/doc/parse 状态。

当前 show 子命令：

mineru show file <path>
mineru show doc <doc-id-or-sha256>
mineru show parse <parse-id>
mineru show scan <scan-id>

show file 只接受文件路径。文档、parse task、scan task 等其他对象使用各自明确的 show <resource> 入口。四个子命令都支持 --json。

输出应区分实际 tier、缓存状态、产物路径和错误状态。已解析结果使用实际 tier。

JSON 输出为 FileInfoResponse 顶层对象，至少包含:

字段	说明
file	文件对象；filename、size_bytes、path、sha256、short_id、status 等嵌套在其内。
doc	文档对象；page_count（未知时为 null）、title、author 等嵌套在其内；未关联文档时为 null。
parsed_tiers	各 tier 的解析状态摘要。
active_parses	当前 pending / parsing 的解析任务摘要。

parsed_tiers 表达当前哪些页已经被哪些 tier 解析，例如:

[
  {"tier": "flash", "page_range": "1-20", "status": "done", "done_at": 1730000000},
  {"tier": "basic", "page_range": "1-5,18-20", "status": "done", "done_at": 1730000100}
]

active_parses 表达当前文档是否有正在进行中的解析任务，元素为 parse task 摘要，例如:

[
  {"id": 123, "tier": "standard", "page_range": "6-17", "status": "parsing"}
]

6. config

mineru config 管理本地配置。

常见范围：

范围	示例
基础配置	扫描间隔、锁超时、worker 数
parse-server	local mode、managed tier、self-hosted URL、remote URL、API Key
watch	通过独立 mineru watch 命令添加、列出、删除监控目录
parsing-rules	按路径规则触发 tier、page_range、remote
exclude	排除路径模式

配置不应导致静默上传。只有规则或命令显式允许 remote 时，才可走远端解析。

当前命令：

mineru config show
mineru config get <key>
mineru config set <key> <value>
mineru config unset <key>
mineru config exclude-rules add <pattern> [--priority N]
mineru config exclude-rules list
mineru config exclude-rules remove <rule-id>
mineru config parsing-rules add <pattern> [--tier <tier>] [--pages <range>] [--remote] [--name <name>]
mineru config parsing-rules list
mineru config parsing-rules remove <rule-id>

show、get、规则 add/list 支持 --json；set/unset/remove 当前输出人类可读文本。

7. watch

watch 用于自动发现文件并建立本地索引。

关键语义：

• watch 默认使用 flash。
• watch 的目标是发现和搜索，不是最终阅读质量。
• Agent 或用户主动读取 PDF/image 文档时，应通过 mineru parse 使用默认选择策略或显式 tier；OFD/EPUB/Office/HTML/MHTML/CSV 读取按 ADR-0024 与 ADR-0028 归一为 flash 语义；其它 text 直接读取源文件。
• 可插拔设备不可达时，watch 标记为 unreachable，该 watch 下的 active 文件标记为 unreachable，而不是永久删除。
• 可插拔设备恢复时，watch 和文件恢复为 active，并立即对该 watch 执行一次 scan。
• scan 发现文件真实缺失时，文件标记为 deleted，保留 sha256。

8. cleanup

mineru cleanup 管理本地文档库中的历史记录和缓存。第一版把 deleted file cleanup 与 orphan doc cleanup 分开，两个动作互不连带。

mineru cleanup deleted-files
mineru cleanup orphan-docs
mineru cleanup temp --older-than 7

deleted file cleanup:

• 立即删除所有 status=deleted 的 file row。
• 删除 file row 时删除对应 fts_filenames。
• 不自动删除 docs、parses、parsed JSON 或 fts_contents。
• 第一版不提供 --older-than 参数；后台任务固定保留 deleted file row 7 天后再清理。
• 默认 dry-run，实际执行需要 --no-dry-run。

orphan doc cleanup:

• 只处理完全没有任何 file row 关联的 docs。
• active、unreachable 和 deleted file row 都会保护 doc。
• 执行时才删除 docs、parses、fts_contents 和 parsed JSON。
• 默认 dry-run，实际执行需要 --no-dry-run。

temp cleanup:

• 删除 doclib/temp 下早于 --older-than 天的临时文件。
• --older-than 默认 7，且必须为非负数。
• 当前不提供 dry-run。

三个子命令都支持 --json。

9. forget

mineru forget 让 doclib 忘记某个 path 的本地记录。

mineru forget ~/Documents/a.pdf
mineru forget ~/Documents/project
mineru forget ~/Documents/project --no-dry-run

关键语义:

• 不删除磁盘上的真实文件或目录。
• 不删除 docs、parses、parsed JSON 或 fts_contents。
• 删除匹配的 files row，并清理对应 fts_filenames。
• 如果 path 是文件，只忘记该文件。
• 如果 path 是目录，默认并且永远递归忘记该目录树下的已入库文件；P0 不提供 --recursive / --no-recursive。
• 如果 path 不存在，但 DB 中存在精确 file path 或 path/ 前缀匹配，也可以忘记历史记录。
• 如果 path 是已配置 watch root 且存在匹配文件，当前实现会拒绝；应先使用 mineru watch remove <path>。
• 如果 path 位于 active watch 下，允许执行，但返回 warning: 后续 scan 可能重新发现。
• 默认 dry-run，实际执行需要 --no-dry-run。
• 支持 --json。

forget 不是 ignore rule。它不会阻止 watch 未来重新发现同一路径。

10. scan

mineru scan 提交一个后台 scan task，让 doclib 扫描文件或目录并更新本地状态。

mineru scan ~/Documents/a.pdf
mineru scan ~/Documents/project
mineru scan ~/Documents/project --no-wait
mineru show scan 123
mineru list scans

关键语义:

• scan 在 doclib server 后台执行，CLI 断开不影响任务。
• scan 是一次性任务，不是 watch，不会持续监控。
• scan 不创建 watch。
• scan 不修改源文件，不上传远端。
• scan 只负责发现和刷新 files 状态，不同步等待 ingest 或 parse 完成。
• 新文件或变化文件会进入 ingest worker 的处理范围。
• 文件 scan 是显式点名文件，不应用 exclude rules。
• 目录 scan 应用 exclude rules。
• mineru scan <path> 是一次性 path scan，不创建 watch，也不更新 watch stats。
• watch initial scan、mineru watch rescan、设备恢复后的 watch scan 复用同一套 ScanWorker。
• 当前 --wait 默认 30 秒；--no-wait 创建任务后立即返回。
• 支持 --json。

P0 API / CLI 支持:

• 创建 scan。
• 查询单个 scan。
• 列出最近 scans。

完整规则见 ADR-0009。

11. watch

mineru watch 管理持久 watch target:

mineru watch add ~/Documents
mineru watch add /Volumes/SSD --removable
mineru watch list
mineru watch remove ~/Documents
mineru watch rescan ~/Documents
mineru watch rescan 3

mineru watch rescan <watch-path-or-id> 只接受已配置 watch root 或 watch id。它创建 kind=watch 的后台 scan task，会更新 watches.last_scan_at / last_scan_files。

如果只想扫描 watch 下的某个子目录或任意 path，使用 mineru scan <path>。

watch add/list/remove/rescan 都支持 --json；rescan 还支持 --wait 和 --no-wait。

12. invalidate

mineru invalidate 把已有 done parse batch 标记为 superseded，源文件和 parsed JSON 之外的其它记录不应被直接删除。

mineru invalidate ~/Documents/a.pdf
mineru invalidate ~/Documents/a.pdf --tier flash

关键语义:

• 不删除磁盘源文件。
• 省略 --tier 时作废该文档所有 tier 的 done batch。
• 指定 --tier 时只作废对应 tier。
• 作废后再次 mineru parse 会重新创建或复用新的解析任务。
• text 文件没有 parse batch，返回 parse_not_required，应直接读取源文件。
• 当前命令不暴露 --json。

13. telemetry

mineru telemetry 管理 doclib telemetry：

mineru telemetry status
mineru telemetry preview
mineru telemetry enable
mineru telemetry disable
mineru telemetry flush

所有 telemetry 子命令都支持 --json。详细数据边界见 Telemetry 最小规范。

14. parsing-rules

parsing-rules 用于按路径规则指定自动解析策略。

示例：

mineru config parsing-rules add "*/论文/*" --tier basic --pages all
mineru config parsing-rules add "*/合同/*" --tier standard --remote

parsing-rule 的 tier 和 remote 适用于 PDF 和 image，但 page_range 只适用于 PDF。image 忽略 page_range 并整文件解析；EPUB、Office、HTML、MHTML、CSV 和 TSV 命中规则时忽略 tier、page_range 和 remote，按 flash 整本解析，并且 parse row 记录为 flash；其它 text 只入库和索引，不创建 parse row。

PDF/image 命中规则时，系统必须检查本地或远端能力是否支持对应 tier。rule 未指定 tier 时，按 standard -> basic -> flash 选择可用 tier，并记录实际 tier。完整文件类型归一规则见 ADR-0024。

已收敛规则

P0 不做基于启发式的 watch 自动提示或自动排队升级。watch 默认使用 flash；后台自动升级只由用户显式配置的 parsing-rules 触发。