在 skill 根目录调用 python -B scripts/knowledge.py。所有内容命令必须加 --root <用户指定的本地非同步私人目录> --library <库ID>；以下用 $cli 表示脚本路径，$vault 表示已选库路径。这些变量需调用方显式赋值，不能把示例当作授权。
--input 请求体合同（0.4.0-beta.2 起）：--input 只接受一个 JSON object；未知顶层字段一律以 INVALID_REQUEST_FIELD 拒绝（detail 列出未知键与该命令允许的键集），非 object 的 JSON 以 INVALID_REQUEST_BODY 拒绝。不接受请求体的命令（如 init、status、documents、health、stats）只允许 {}。示例：search 请求 {"context":"full"}；误写 {"vesion_id":1} 会被拒绝而不是被静默忽略。嵌套对象（如 sources、entries、datasets）的字段仍由各命令自行校验。
python -B $cli doctor
python -B $cli --root $vault --library company-a init --policy host-allowed
python -B $cli --root $vault --library company-a ingest --path $source
python -B $cli --root $vault --library company-a documents
python -B $cli --root $vault --library company-a evidence --id $version
python -B $cli --root $vault --library company-a source-check --id $version
python -B $cli --root $vault --library company-a search --text '入职'
python -B $cli --root $vault --library company-a status
python -B $cli --root $vault --library company-a health默认 --policy host-allowed，这只表示当前宿主允许处理该内容；若需阻断内容输出，调用方必须显式选择 --policy local-only。具体可用格式、依赖和协议以 doctor.format_capabilities 为准。doctor、TXT/CSV 最低链路和前台客户端验收记录见 安装与客户端验收。
输出单个 JSON。dev.37 起全局支持 --json-output auto|ascii|unicode（默认 auto）：stdout 为管道/重定向（非交互终端）时输出纯 ASCII（非 ASCII 字符以 \uXXXX 转义），在 GBK 代码页与任意字节管道中都不会乱码或产生 Invalid \escape；交互终端保持 UTF-8 原文；可显式传 ascii/unicode 强制。证据持久化与哈希始终用 UTF-8 canonical，不受该开关影响。failed/参数错误退出码为 2；created、updated、reused_verified、held、cancelled 分别报告。resume 的 counts 有 failed 时也退出 2。来源在读取阶段出现权限、设备或其他 OSError 时返回 SOURCE_IO_ERROR；PARSE_FAILED 只用于不带领域错误码的内容/解析器异常。
XLSX 与可信旧 XLS 的单表有效矩形上限为2,250,000个单元格；单原件仍限32MiB，Office ZIP仍限128MiB展开或10,000成员。XLSX 会记录 Excel 声明尺寸，但只镜像有值或公式的有效矩形范围，纯格式尾部空格不会占证据格；超限仍以 LIMIT_EXCEEDED 失败，不会截断入库。
source-check 只检查版本所登记的原路径，不全盘找文件。evidence 默认标 NOT_RECHECKED；latest_ingested 只表示库内最新接入版本，不保证源文件仍未变化。
python -B $cli --root $vault --library company-a render
python -B $cli --root $vault --library company-a view-audit --id <render返回路径末尾的32位ID>
python -B $cli --root $vault --library company-a healthview-audit 仅接受 skill 生成的32位视图ID，拒绝任意路径。它校验 view manifest 所列文件哈希、未列入文件、完成标记，并比对 manifest 中的证据版本/source hash/payload hash/文本与表格定位摘要；不会重读原件或修改视图、数据库。VIEW_SOURCE_NOT_CURRENT 是历史视图的提示，不等于文件篡改；旧版本视图没有证据合同，只能得到 audit_level=legacy 的有限审计。
health 汇总库存、jobs、views、batch receipts 与 .work 残留。它只读，不重试、不清理、不扫描原件；healthy 不是知识正确性、OCR准确性或原件仍可访问的保证。
python -B $cli --root $vault --library company-a reading-plan --input <JSON路径>
python -B $cli --root $vault --library company-a output-scope --input <JSON路径>
python -B $cli --root $vault --library company-a capacity-reportreading-plan 请求可为 {"version_ids":["版本ID"],"max_chars":32768,"max_rows":500}；省略 version_ids 时取 latest 版本。字符预算范围1024–1048576，物理行预算范围1–100000。span 保持完整，表格仅在行间切分，返回坐标锚点；它不是提炼任务的 synthesis-plan。
output-scope 请求为 {"mode":"metadata"|"evidence"|"methods"}。返回的是字段白名单和默认拒绝项的范围合同；调用方仍须在真正导出前选用已有三种迁移包，不能把合同当脱敏结果或分享许可。capacity-report 返回实际库与payload清点，明确未运行恢复探针，不能据此声称恢复速度或规模上限。
python -B $cli --root $vault --library company-a navigation-index --input <reading-plan同格式JSON>
python -B $cli --root $vault --library company-a client-preflightnavigation-index 用同一预算得到稳定的索引项，返回 key、block_id、原 locator/表格行区间/坐标与不可变 evidence --id 下钻路线。它不创建新的阅读视图或复制正文。client-preflight 只给源码层面的前置状态：不能替代实际客户端的安装、触发和问答验收。
大表先用 table-profile 识别物理列和结构风险，再用 project 取得本次问题真正需要的字段；不要把 search 的大量命中或整表 evidence 当作统计母体：
python -B $cli --root $vault --library company-a table-profile --input <表规格JSON>
python -B $cli --root $vault --library company-a project --input <投影JSON>
python -B $cli --root $vault --library company-a movement-analyze --input <流动分析JSON>
python -B $cli --root $vault --library company-a pdf-review-plan --input <PDF复核JSON>
python -B $cli --root $vault --library company-a client-acceptance-plan --input <可选场景JSON>
python -B $cli --root $vault --library company-a client-acceptance-record --input <前台观察JSON>table-profile 示例：{"version_id":"版本ID","table":0,"header_row":1}，只返回列名、坐标、行数、字段非空覆盖、声明/有效尺寸与质量门禁，不返回数据行。project 示例：{"dataset":{"version_id":"版本ID","table":0,"header_row":1},"columns":["姓名","岗位"],"filters":[{"column":"部门","op":"equals","value":"国际物流部"}],"limit":100,"offset":0}。列名必须来自同一个可自动分析的表；equals 不做类型/身份修复，contains 只是文本包含；输出为所选字段和这些字段的单元格坐标，count 是该表中完整命中数，matches 可受 limit 截断。命中较多时将返回 next_offset，把该值作为下一次 offset 继续取页；投影逐行扫描，不预先物化整表行对象。
movement-analyze 示例：{"current":{"version_id":"当前版本","table":0,"header_row":1},"departures":{"version_id":"离职版本","table":0,"header_row":1},"department_value":"国际物流部","as_of":"2026-09-18","fields":{"current_department":"部门","departure_department":"部门","current_entry_date":"入职日期","departure_entry_date":"入职日期","departure_date":"最后工作日","departure_reason":"离职原因"},"short_tenure_days":90}。部门比较为精确相等；日期仅按 ISO 日期前十位读取。输出的 coverage_contract 是结论的一部分：花名册只是截止日快照，不能据此得出调动历史、年初人数、年度净变化或离职原因的因果解释。
pdf-review-plan 仅接受带 PDF 布局/OCR告警的版本，可选 {"version_id":"版本ID","pages":[1,2]}。每个任务锚定真实 page:N，审核者应检查原页，再以既有 manual-add 记录自己确认的文字和所在位置；该计划不会把视觉表格或组织图转成结构数据。
前台验收先以 client-acceptance-plan 取得同一情景的检查项；完成实际客户端操作后才可写 client-acceptance-record，例如 {"client":"Codex","result":"passed","observed_by":"用户在 Codex 前台验证","notes":"能触发技能并给出版本和定位","expected_revision":12}。client 只能是 Codex、WorkBuddy、QwenWork；记录只说明此次观察，不能替代其他客户端、未来版本或源码 CLI 的验收。
先用 library-bind-save --input <JSON> 保存用户明确选择的 source_path、library_root、library 与 config_path。日常更新不必再次输入两个资料路径：
python -B $cli --root $vault --library company-a library-update-plan --input <绑定JSON路径>
python -B $cli --root $vault --library company-a library-update --input <绑定JSON路径>
python -B $cli --root $vault --library company-a review-queue --input <筛选JSON路径>
python -B $cli --root $vault --library company-a topic-rebuild --input <专题JSON路径>library-update-plan 只扫描并显示 new/modified/unchanged 等计划；library-update 才会执行写入。二者都会重验绑定并拒绝当前 --root/--library 与绑定不一致的调用。可选更新请求例如 {"config_path":"F:\\资料库\\binding.json","native_windows":true,"trusted_office":true}，旧 XLS/DOC 仍需明确 Office 信任。
review-queue 的请求可为 {"categories":["ocr","pdf_layout","word_structure","spreadsheet_structure"],"limit":50}；省略 categories 表示返回全部告警文件。它给出总量、分类计数与选中项，不修改证据。dev.37 起返回稳定字段 items/count/filtered_count/total_count/counts_by_category/truncated/filters，并默认附只读 pending_jobs 失败作业分组（详见末部 dev.37 节）。topic-rebuild 请求为 {"topic_id":"topic-views 列表中的ID"}，只接受 stale 专题，读取该专题的原问题/词项/年份重新编译，旧 JSON 不覆盖，新 JSON 的 supersedes_topic_id 指向旧历史。
library-bind-save 的请求可带 "scope":"personal"|"team"，把该条来源/库绑定写入同一个用户自选 JSON 的 bindings 下：
{"scope":"team","config_path":"F:\\资料库\\bindings.json","library":"team-knowledge",
"source_path":"F:\\团队共享\\原始文件","library_root":"F:\\团队共享\\知识解析","recursive":true}保存时除单条绑定既有校验外，还做跨 scope 校验：两个库身份必须不同（SCOPE_LIBRARY_IDENTITY_CONFLICT）、两个 library_root 互不重叠（SCOPE_LIBRARY_ROOT_OVERLAP）、两个 source_path 互不重叠（SCOPE_SOURCE_OVERLAP，含父子包含）、来源根与对方库根互不重叠（SCOPE_SOURCE_LIBRARY_OVERLAP）。dev.21 之前的旧单绑定配置首次写 scope 时自动承继为 personal，数据不搬迁；不带 scope 的旧存取行为保持不变。library-bind-load 带 scope 返回单条绑定；不带 scope 且配置为双绑定时返回 status:"loaded_multi" 与两个 scope 的绑定。
入库类命令可加 --scope personal|team --binding <绑定JSON>，写入前强制执行来源路由：
python -B $cli --root $vault --library personal-knowledge --scope personal --binding F:\资料库\bindings.json ingest --path F:\个人知识库\原始文件\a.xlsx
python -B $cli --root $vault --library team-knowledge --scope team --binding F:\资料库\bindings.json scan --path F:\团队共享\原始文件 --recursiveingest、register、scan、batch、reattach 适用：目标路径必须位于该 scope 登记的来源根之下（SCOPE_PATH_OUTSIDE_SOURCE），当前 --root/--library 必须与该 scope 绑定一致（SCOPE_STORE_MISMATCH），越界进入对方来源根的路径被拒（SCOPE_CROSS_SCOPE_PATH）；给了 --scope 却缺 --binding 报 SCOPE_BINDING_REQUIRED。成功收据带 scope 字段。未使用 --scope 的调用行为不变；双 scope 不提供"一次写两库"，同一文件要进两库需复制到另一来源根后独立入库。library-update-plan/library-update 对双绑定配置必须在请求体显式给出 scope，否则报 SCOPE_REQUIRED_FOR_MULTI_BINDING。团队 scope 仍是本机库，共享只走导出包与受控副本。
只读命令可省略 --root/--library，直接用 --scope personal|team --binding <绑定JSON> 从已保存绑定解析要解答的那一个库：
python -B $cli --scope personal --binding F:\资料库\bindings.json search --text 任职
python -B $cli --scope team --binding F:\资料库\bindings.json topic --text 差旅
python -B $cli --scope team --binding F:\资料库\bindings.json reading-plan --input <JSON>
python -B $cli --scope personal --binding F:\资料库\bindings.json stats适用命令：status、documents、evidence、source-check、search、field、analyze、compare、cards、topic、topic-compile、topic-views、topic-rebuild-plan、query-plan、quality-report、review-queue、distribution-plan、reading-plan、output-scope、capacity-report、navigation-index、client-preflight、health、view-audit、synthesis-list、synthesis-plan、coverage、lesson-list、stats。绑定每次使用前重验（来源根/库根仍须存在），scope 未登记报 SCOPE_NOT_CONFIGURED，缺 --binding 报 SCOPE_BINDING_REQUIRED。
同时显式给出 --root/--library 与 --scope 时，二者必须与绑定一致，否则 SCOPE_STORE_MISMATCH；成功输出带 scope 标注。不带 --scope 的旧调用完全不变，输出也没有 scope 字段。写入、render 与 restore 不能用 scope 解析省略库参数（仍须显式 --root/--library）。一次调用只解答一个库，v1 不做跨库联邦或混合解答；需要两个库的答案时分别查询、分别核对出处。
导出类命令 export-pack、export-method-pack、export-full-pack、export-personal-bundle 与 backup 可像只读命令一样省略 --root/--library，经 --scope+--binding 解析源库；收据带 scope：
python -B $cli --scope team --binding F:\资料库\bindings.json export-pack --input <JSON>
python -B $cli --scope team --binding F:\资料库\bindings.json export-full-pack --input <JSON>
python -B $cli --scope personal --binding F:\资料库\bindings.json backup --path F:\备份\snap.sqlite3四类包的 manifest 在 pack_format 仍为 1 的前提下新增可选 scope 字段（personal/team）；旧包没有该键，仍可正常读取。pack_id 计算不包含该字段，旧收据/幂等记录不受影响。知识包/方法包以 team 导出且未提供任何替换规则时，收据带 scope_notice，提示"未脱敏完全、只可受控分发"；team 的 full pack / personal-library bundle 本就含完整私有库镜像，收据 notice 追加 team_scope_..._is_not_desensitized_controlled_copy_only。注意 bundle 的 manifest mode 值历史上叫 personal-library，与 scope 无关，team 库导出时 scope 字段才是来源标识。
导入侧规则：
import-pack/import-method-pack写入已存在的库：仍须显式--root/--library；给--scope时必须同时给--binding且库与绑定一致（SCOPE_STORE_MISMATCH），并且包 manifest 的 scope 必须与所选 scope 相同（SCOPE_PACK_SCOPE_MISMATCH）。import-full-pack/import-personal-bundle是恢复到全新路径的镜像恢复：--scope只校验包 manifest 的 scope（SCOPE_PACK_SCOPE_MISMATCH），不需要也不读取绑定配置；库身份仍由镜像内 identity 强制一致。- 无 scope 键的旧包只能在不带
--scope时导入；带 scope 导入旧包会被拒绝，防止未标来源的包静默进入指定 scope 的库。 restore不支持 scope（裸 SQLite 快照没有 manifest），仍按显式参数恢复。
ingest/scan/batch 解析 DOCX 时，除既有 body:N 段落与 body-table:N 表格外，新增加四类独立证据 span，可经 evidence --id <version> 下钻并被 search 检索；没有新增命令行参数：
| 通道 | locator 形式 | 说明 |
|---|---|---|
| 页眉 | headerN:M（表格 headerN-table:K/RrCc） |
遍历包内全部 word/headerN.xml，N 为部件号；默认/首页/奇偶页是不同部件 |
| 页脚 | footerN:M |
同上，部件为 word/footerN.xml |
| 脚注 | footnote:<id>:M |
word/footnotes.xml 中真实注；id 为 -1/0 的分隔符/延续分隔符占位不提取 |
| 文本框 | textbox:<部件>:<框序>:<段序>，部件为 document/headerN/footerN/footnotes |
VML（v:textbox）与 DrawingML（wps:txbx）统一按文档顺序抽取 w:txbxContent；文本框文字不再混入所属正文段落，不重复计数 |
旧的固定告警 BODY_ONLY_NO_HEADERS_FOOTNOTES_TEXTBOXES_IMAGES 取消，按文件实际部件精确告警（仍进入 evidence 的 warnings 与 review-queue 的 word_structure 分类；历史版本镜像中旧告警字符串原样保留）：
MULTIPLE_HEADER_PARTS_PAGE_ATTRIBUTION_MERGED/MULTIPLE_FOOTER_PARTS_PAGE_ATTRIBUTION_MERGED：存在多个页眉/页脚部件（默认/首页/奇偶页），已全部提取但无法标注某段文字实际出现在哪一页。TEXTBOX_TEXT_EXTRACTED_ORDER_NOT_PRESERVED：文本框文字已提取，但与正文的视觉先后/环绕顺序不保留，引用时只定位到框、不定位到页面位置。TEXTBOX_TABLES_PRESENT_NOT_EXTRACTED：文本框内嵌表格，其表格文字不提取。IMAGES_PRESENT_NOT_EXTRACTED（存在word/media/）、CHARTS_PRESENT_NOT_EXTRACTED（存在word/charts/）：图片/图表不变成证据文字。ENDNOTES_PRESENT_NOT_EXTRACTED：尾注（endnotes）有实质内容但本批不提取；只有分隔符占位时不告警。
纯正文 DOCX 的 warnings 为空；正文段落与正文表格的 locator 编号与 dev.24 前完全一致。可信旧 DOC 经 --native-windows --trusted-office 转换为 DOCX 后走同一解析通道。本批不包含 PDF 表格布局核验、PPT 适配器与尾注提取。
将请求保存为 UTF-8 JSON，传 field --input <请求路径>：
{"dataset":{"version_id":"实际版本ID","table":0,"header_row":1,"exclude_rows":[]},"column":"姓名","value":"张三"}表号从 0 开始，行号从 1 开始。返回原始字段、row_id 和单元格位置；同名多行不会自动合并。字符串/数字严格区分。合计行必须由调用方审查并在 exclude_rows 显式列出，不能让模型猜一遍后无记录地删除。
aggregate --input（只读）：
{"dataset":{"version_id":"版本ID","table":0,"header_row":1,"exclude_rows":[7]},
"group_by":["部门"],
"measures":[{"op":"count","as":"人数"},
{"op":"count_distinct","column":"姓名"},
{"op":"sum","column":"工资"},{"op":"avg","column":"工资"},
{"op":"min","column":"工资"},{"op":"max","column":"工资"}]}- 表必须先过 dataset 同一道质量门禁：含公式缓存/合并格/隐藏行列的表一律拒绝（要先人工处理来源，不在聚合里绕过）。
- 数值列遇到字符串或布尔值报 NON_NUMERIC_VALUE，detail 给出行号与坐标；空值（None/空串）计入 unknown，avg 分母只用已知值，sum/min/max 跳过空值。
- 未排除的行中任一格文本含"合计/总计/小计/total"报 POSSIBLE_TOTAL_ROW；确认不是合计行才保留，是合计/小计行必须显式 exclude_rows。
- 无 group_by 时返回单组（key 为 []）；空分组键以 null 表示。每分组给 members（row_id+表内行号）供逐行复算。这是单表所选行的确定性汇总，不是自由 SQL，结果不自动代表所选范围之外的统计母体。
formula-check --input（只读，永不改写工作簿）：
{"version_id":"版本ID","table":0,"epsilon":1e-9}逐公式格输出 {coordinate, formula, cached, recomputed, status, reason?}，status ∈ matches/mismatch/unverifiable/error；支持 SUM/AVERAGE/COUNT/COUNTA/MIN/MAX 的 A1:B2 区域、A1,B2 离散格与 $ 绝对引用（COUNT 只数数值、COUNTA 数非空含空串、文本对数值函数忽略、MIN/MAX 空集为 0、AVERAGE 无数值为 error 语义）。嵌套、四则运算、跨表 !、外部链接 [、字面量参数、分号分隔、openpyxl 未存缓存值（cached=null）、错误值格一律 unverifiable/error，绝不猜测。该命令可以直接检查带 FORMULA_CACHE_UNVERIFIED 告警的表（它本身就是质量复核工具）。
header-preview --input（只读）：{"version_id":"版本ID","table":0,"rows":5} 机械返回前 N 行每格坐标与值、物理列宽、各行非空/空缺/重复列名；不做任何改名建议。
header-map --input（写，须乐观锁）：
{"version_id":"版本ID","table":0,"expected_revision":7,"header_row":1,
"columns":["成员A","部门","成员B",null]}按物理列顺序给最终列名；null 表示忽略该列（多级表头等不需要的层）；非空列名必须唯一、至少保留一列、数量必须等于表头行物理列数。映射绑定具体不可变版本（重新入库的新版本需另设）；相同内容重复提交幂等返回 unchanged 不增 revision；成功写 headermap:set/updated 事件。dataset/field/analyze/aggregate 的 dataset 参数加 "use_header_map":true 即采用映射；返回中 original_headers 保留原表头、ignored_columns 列出忽略的物理列、行 evidence 仍含全部物理单元格坐标。
协议细节见 references/synthesis.md。三个新入口均为只读或只建任务，不调用模型、不启动后台队列：
synthesis-plan --input（只读）：{"version_ids":["版本ID"],"max_units":40}；version_ids 省略时覆盖全库 latest+ready 版本。按连续 locator 贪心切块：span 各计 1 单元、表格按行数计且整块不拆，块不跨版本，超限表格独占一块并标 oversized；返回 blocks（含可直接用于 synthesis-create-batch 的 sources）、empty_versions、version_status 与 plan_hash。规划本身不建任务、不增 revision。coverage --input（只读）：{"version_ids":[...]}（省略则全库）。逐版本统计 span/表格被 candidate/confirmed/superseded 卡引用的清单、比例与总计；人工补录的 active manual span 也计入。结果只说明"来源被卡片引用过"，basis 显式声明 coverage_is_not_synthesis_completion、uncovered_locators_are_not_worthless；覆盖≠提炼完成，未覆盖≠无价值。synthesis-create-batch --input（写，须乐观锁）：{"objective":"...","blocks":<plan 的 blocks>,"expected_revision":7}。先对全部块做来源预检再逐块创建，任何一块不合法整批不留任务；同目标同范围任务复用不重建，held/cancelled 任务复用原状态不复活。收据返回 created/reused（含 block_index、task_id、state）。
synthesis-list 的 --input 新增可选筛选：state（pending/held/cancelled/done）、stale（true/false）、min_age_minutes（断后续作取停滞任务）、version_id；不带 body 时行为与 dev.4 完全一致。
协议细节见 references/packs.md、references/lessons.md。
export-pack --input：{"path":"C:/.../pack.zip","states":["confirmed"],"replacements":[{"from":"公司全称","to":"甲公司"}]}。默认且保守地只导出 confirmed 卡（states 白名单 candidate/confirmed/superseded，永不导出其他内容）；替换表由调用方显式提供，核心只做字面量确定性替换（重叠/链式规则拒绝），manifest 只记录规则 SHA256 与规则集哈希，不存明文。zip 内含 manifest.json（pack 格式版本 1、血统、源库ID、时间、条目数、逐文件 SHA256、pack_id）与 entries/*.json，不含原件字节、raw payload、spans/tables、校核与人工证据、任何任务 meta；空导出报 EMPTY_PACK。import-pack --input：{"path":"...pack.zip","expected_revision":0}。只能导入无任何卡片、未导入过包的新初始化库（否则 IMPORT_TARGET_NOT_EMPTY，绝不与本地卡合并身份）；校验血统、pack 格式、文件清单与逐文件 SHA256（篡改/夹带/路径穿越/坏 zip 分别拒绝）。导入卡保持原 state（confirmed 仍是 confirmed）并加 provenance（pack_id/源库/时间/原卡ID/原始 sources 快照）；卡上 sources 转为无 version_id 的出处文本（in_library 标记），在新库不可下钻、不产生 stale；卡 ID 按新库身份重算。同一 pack_id 重复导入返回 reused_verified。export-method-pack --input/import-method-pack --input（dev.11，D0.2 三种迁移模式之方法包）：方法包只导出 confirmed 卡的五个白名单文本字段（title/insight/conditions/limits/counterexamples），绝无 sources、版本 ID、源文件哈希、路径与任何 provenance；支持同样的调用方显式字面量替换表。manifest 标 mode=method。导入允许进入非空库与本地卡并存：同内容（源库+原卡ID+白名单内容一致）复用不计数，同原卡内容不同则 held 不覆盖，其余继续，收据逐项给 imported/reused/held；方法卡保持 confirmed、sources 为空、带 imported_method_pack provenance。知识证据包（mode=knowledge）与方法包导入器互不接受对方的包（PACK_MODE_MISMATCH）；知识证据包仍只准进空库，不做文本级去重。export-full-pack --input/import-full-pack --input（dev.12，D0.2 三种迁移模式之完整迁移包，同用户换机）：export-full-pack --input {"path":"...full.zip"}把整库做成 zip（manifest.json + library.sqlite3 一致性 SQLite 镜像），manifest 标 mode=full，含 revision、counts 清单、镜像字节数与逐成员 SHA256、pack_id；含原件镜像、payload、校核/人工证据、卡片与全部 meta，不做任何脱敏，收据 kind=full_private_pack_not_desensitized，仅 host-allowed 可导出，只能在可信边界内交接。import-full-pack --input {"path":"...full.zip"}（--root为尚不存在的新目录）按 restore 同一套闸门校验：zip 结构（恰好两个成员）、成员哈希/字节数、血统/schema=1、库身份必须与 --library 一致（LIBRARY_MISMATCH）、integrity_check、逐版本 payload_hash、foreign_key_check、manifest 清单与镜像实际计数/revision 一致；全部通过才落盘，绝不合并；body 加"verify_only":true只校验不写盘。与裸 backup 的区别：full pack 是带 manifest 的自描述交换件，backup 是裸 sqlite 文件，两者收据 kind 不同。stats（dev.12，只读库体检/容量预检）：无 --input，返回 library/policy/revision/generated_at/db_bytes 与 counts（versions、jobs、cards 及按 state 分组、events、meta、payload_bytes、spans、tables、table_rows、meta 各命名空间桶计数）；只读、不增 revision、不写任何记录，计数是清点不是质量判断，容量阈值需用代表性语料建立，核心不内置告警线。要求 host-allowed。lesson-add/lesson-list/lesson-retract --input：库内轻量教训（metalesson:独立命名空间）。add 需 text 与非空 confirmed_by、可选 context/scope，同内容复用；list 支持 q 词面检索（text/context/scope）、scope 精确过滤、include_retracted；retract 需 note 与 confirmed_by，撤回后默认不可见且同内容不能原样复活。不跨端同步、不与 review-evolution 档案互写；宿主存在 review-evolution 时优先用后者。recipe-save/recipe-list/recipe-show/recipe-run/recipe-retract --input（dev.34 LK-61）：可复用分析配方（metarecipe:<name>命名空间）。save 需唯一 name（字母数字/下划线/连字符，1..64）、kind（movement-analyze|project）、datasets（绑定 version_id+table）、params（按 kind 校验）、confirmed_by；可选 reconciliation（核对规则列表，仅信息性）、report_template、note。同一 name + 同一配置幂等复用；同 name 不同配置报RECIPE_NAME_CONFLICT。list 只返回结构元数据（不含 params/datasets 正文）；show 返回完整配置；run 读当前证据运行 movement-analyze 或 project，输出附coverage_contract（含 recipe_id、source_versions、version_snapshot、stale_versions、is_current_snapshot、reconciliation），同一库状态复现相同统计；retracted 配方不能 run。recipe 不保存源正文；stale 版本在合同中报告不修复。recipe-list/show/run 支持--scope+--binding解析库；save/retract 不适用 scope 省略库参数。
analyze --input <请求路径>：
{
"appointments":{"version_id":"任命版本ID","table":0,"header_row":1,"exclude_rows":[]},
"roster":{"version_id":"花名册版本ID","table":0,"header_row":1,"exclude_rows":[]},
"as_of":"2026-09-17",
"keys":[["组织","组织"],["工号","工号"]],
"role_column":"岗位",
"start_column":"起始",
"end_column":"结束",
"education_column":"学历"
}keys 每对是任命列、花名册列，不执行自由 SQL。截止日按生效日/终止日均包含计算；空结束日期按未给终止日期处理，缺开始日期拒绝。按完整选定表计算，输出人数/身份-岗位数/任命行数；相同人员相同岗位重复行不重复计岗位，仍保留原行数量。岗位层级/兼职类型等额外维度暂不聚合。
学历分母是全部有效管理人员；未知、未匹配、身份歧义分列。可选 birth_column、hire_column 指定花名册出生日期/入职日期列，按截止日计算整年年龄/司龄，输出已知与未知人数、最小/最大/均值。日期须ISO格式，不从已有年龄倒推生日。姓名、日期与人员能力之间不作推断；不是通用分析引擎。
compare --input：{"version_ids":["A版本","B版本"]}，返回双方证据，宿主按范围/对象/时效/条件/例外/替代依据分析，不自动裁决制度优先级。
card-add --input：
{"title":"方法标题","insight":"提炼观点","conditions":["适用条件"],"limits":["证据局限"],"counterexamples":["反例或尚待验证"],"sources":[{"version_id":"实际ID","locator":"line:1"}]}表格来源必须同时指定 table 和真实 locator（如 Excel A2，CSV R2C1，DOCX body:2/R2C1）。程序校验位置存在，不能代替人工核验语义确实支持观点。
cards 查看候选。用户已确认清单后，confirm --input：{"ids":["卡片ID"],"expected_revision":7}。revision 使用用户所审阅当前内容对应值，过期必须重新核对，不盲目改成最新数字重试。
register --path 获得 job_id；intent --id <job_id> --action hold|cancel|allow 设置意图。resume 仅重做未就绪且允许的项目，不释放 hold/cancel。就绪项源变化需再次 ingest；不后台自动扫描。
解析失败记录错误类型，无无限重试。模型工作完全在宿主，不存在后台模型队列；不能把此开发版说成模型任务断点续作已完成。
backup --path <尚不存在的快照文件> 使用 SQLite backup，含全部镜像和卡片，不含原文件字节。不得当作已脱敏方法包带往另一公司。
restore --path <本工具可信快照> --root <不存在的新库目录> --library <原库ID> 校验完整性与镜像哈希，只写新目录。暂不支持不可信交换包导入或覆盖恢复。原件失联时备份能恢复镜像但不能凭空恢复原字节。dev.12 起：收据含 revision、counts（versions/jobs/cards/by-state/events/meta/spans/tables/payload_bytes 等）与恢复文件 sha256；加 --verify-only 只跑全部校验（integrity、血统/schema、库身份、逐版本 payload_hash、外键）不创建任何目录，收据回源文件 sha256 与计数，可用于迁移前体检。
目录 scan/batch --path <来源目录> [--recursive]、原生适配和存储交互详见 输入与增量更新。快照只包含数据库，目录批次收据不包含在快照内；数据库事务事件仍保留。
--native-windows：兼容旧调用，同时为.doc/.xls选择受信任 Office 转换，并为.pdf选择 Windows OCR。--office-windows --trusted-office：只选择.doc/.xls的 Office 转换，不调用 PDF OCR。--ocr-windows：只选择.pdf的 OCR，不打开 Office 文件。--allow-wps（0.4.0-beta.3 起）：仅在--office-windows/--native-windows路径内生效的附加 opt-in。微软 ProgID（Word.Application/Excel.Application）优先；COM 不可用或由 WPS 应答时，才依次尝试 WPS ProgID（KWps.Application/wps.Application、KET.Application/et.Application）。WPS 输出证据恒附WPS_ADAPTER_REAL_MACHINE_UNVERIFIED（真机回验未完成前按人工必复核对待）。不带该旗标时，WPS 伪装应答一律结构化拒绝WPS_ENGINE_DETECTED_NOT_ALLOWED。--soffice-headless --trusted-office（0.4.0-beta.3 起）：跨平台 LibreOffice headless 路径，只对.doc/.xls生效，转换为.docx/.xlsx后走标准库解析。soffice 解析顺序为环境变量LIVED_KNOWLEDGE_SOFFICE→ PATH → 各平台知名安装路径；只探测，绝不下载、安装或捆绑。与--office-windows同时给出时 soffice 优先（不触碰 COM 面）。证据恒附SOFFICE_CONVERTED_REAL_FIDELITY_UNVERIFIED与OFFICE_TRUSTED_INPUT_ONLY；.doc另附DOC_CONVERTED_COORDINATES_NOT_ORIGINAL_PAGES（页码坐标属于转换后文档而非原件）。非 Windows 平台只能选此路径处理.doc/.xls。
这些开关可用于 ingest、scan 和 batch（两个 beta.3 新旗标同样用于 batch-preflight 的 flags_echo）。显式给出其中任一个时，本次扫描只按该选择为相应格式配置适配器，不沿用其他格式作业此前保存的原生选项；不带任何原生开关的旧调用仍会复用已保存选项。信任边界、超时与 OCR 人工复核要求不变。
宿主批量删除保护公约（0.4.0-beta.2）：使用 Office COM（.doc/.xls）或 Windows OCR 原生适配时，单个批次建议 ≤40 个文件；更大规模按 chunk_size 分片多次发起。这是会话操作公约，不是引擎硬限制，代码不强制——起因是 WorkBuddy 等宿主曾发生钩子清理误删会话临时目录的事件，超大原生批次在部分宿主会话中可能因适配器临时文件被清理而整批失败。通用长批次纪律（预检、--summary、不盯梢）仍见 SKILL.md「长任务运行公约」。
scan/batch --path <来源目录> --input <JSON> --summary：JSON 可选{"paths":["相对路径"],"only_failed":true}或{"paths":["相对路径"],"only_not_ready":true}。paths 严格相对来源根、最多10,000项，拒绝绝对/越界/重复；两个筛选不能同时开启。dev.37 起 paths 清单自带子目录遍历授权（不再要求同时传--recursive；dev.31-36 时期漏传会静默requested_missing零入库）；不带清单时目录递归仍必须显式--recursive。--summary-limit取 1–100，默认20。scan摘要不持久化完整计划；batch摘要返回receipt_path，完整逐文件回执仍在该本地文件；dev.37 起可用只读batch-progress/batch-report查询回执。adapter-clear --id <作业ID>：显式删除该作业保存的原生适配选项，返回是否实际清除及当前 revision；不删除作业、版本、证据或原件。作业 ID 可从scan、documents或既有回执取得。
doctor 与 client-preflight 的 native_environment 输出只读错误码 schema（不启动 Office/OCR）。实际适配器运行失败时，invoke() 抛出的 Problem 详情附 contract JSON，包含 error_code/mode/category/retryable/advice。结构化码与合同要点：
WORD_VERSION_UNSUPPORTED：0.4.0-beta.3 起 Word 主版本 <12（Word 2007 之前）无法运行任何转换合同；Word 2007/v12 起经旧版SaveAs（wdFormatXMLDocument=12）回退支持，v14+ 才用SaveAs2（wdFormatDocumentDefault=16）。retryable=false。EXCEL_VERSION_UNSUPPORTED（0.4.0-beta.2 起）：Excel 主版本 <11（Excel 97-2003 之前）无法运行 COM 读取；Excel 2007/v12 旧库可正常读取（.xlsCOM 读不依赖 SaveAs2）。retryable=false。OFFICE_COM_CLASS_NOT_REGISTERED（0.4.0-beta.2 F2 起）：COM HRESULT 0x80040154（REGDB_E_CLASSNOTREG）映射到此码；retryable=false。含义与处置见下方「WPS 与 Office COM 的边界」。WPS_ENGINE_DETECTED_NOT_ALLOWED/WPS_SAVE_METHOD_UNAVAILABLE/WPS_VERSION_UNPARSEABLE（0.4.0-beta.3 起）：分别表示 WPS 正在应答但本次未给--allow-wps、WPS 引擎缺 SaveAs/SaveAs2 能力、WPS 版本串不可解析；均 environment/retryable=false，处置为加--allow-wps、改用--soffice-headless或在 Office/WPS 里手动另存为 .docx/.xlsx。SOFFICE_NOT_INSTALLED/SOFFICE_VERSION_UNPARSEABLE/SOFFICE_CONVERSION_FAILED/SOFFICE_OUTPUT_MISSING/SOFFICE_TIMEOUT（0.4.0-beta.3 起）：LibreOffice headless 路径的结构化码——找不到可执行文件（设置LIVED_KNOWLEDGE_SOFFICE或自行安装，技能不下载）、版本横幅不可识别、转换被拒/失败（加密损坏等）、零退出但无产物、超时（retryable=true 但禁止同文件自动重试）；其余均 retryable=false。WORD_VERSION_UNPARSEABLE：Word 报告的版本非数字；重装或修复 Office。retryable=false。OCR_LANGUAGE_UNAVAILABLE：请求的 Windows OCR 语言未装；装语言包或换--language。retryable=false。OCR_PAGE_LIMIT：PDF 页数超过 NATIVE_MAX_OCR_PAGES（30）；拆分或显式审核后调高。retryable=false。OCR_TIMEOUT/NATIVE_TIMEOUT：Windows Runtime 步骤或 PowerShell 进程树超预算；retryable=true，但禁止对同一超大输入自动重试。LIMIT_EXCEEDED：旧 XLS 有效格超 2,250,000；拆分或筛选后重入库。retryable=false。0.4.0-beta.4 起 detail 附尺寸证据：sheet=<表名>; meaningful_cells=N; meaningful_rows=..; meaningful_cols=..; declared_rows=..; declared_cols=..——若 meaningful 尺寸远大于 declared（UsedRange 声明尺寸），说明该引擎的值边界探测可能虚高（在 WPS 兼容引擎上实测可能），把该 detail 连同文件反馈，不要自行调护栏。OCR_NO_TEXT_DETECTED：OCR 无可选文本；验证 PDF 含可选文本或换语言/源。retryable=false。WINDOWS_REQUIRED/NATIVE_PROTOCOL_ERROR/NATIVE_FORMAT_UNSUPPORTED/TRUSTED_OFFICE_REQUIRED/INVALID_NATIVE_PAGE_BUDGET：环境/协议/合同类失败，retryable=false。NATIVE_ADAPTER_FAILED：未识别失败的兜底码；查 detail 字段，先用合成样本复跑再试真实输入。retryable=false。
拒绝/失败回执的文件定位字段（0.5.0-beta.1 起）：所有 status 为 failed/held/cancelled 的单文件入库回执恒带 file_name（文件名）与 source（绝对路径）；成功回执带 file_name（路径见 input_path/resolved_path）。批量 scan 返回的每个 item（含 unsupported/scan_error/missing/held/cancelled/skipped_*）与 batch/batch-resume 的每张 receipt 恒带 name（文件名）与 path（绝对路径）。拿到任何拒绝或解析失败都可直接定位文件，无需二次扫描。
原生适配进程退出告警（0.5.0-beta.1 起）：原生操作的成功以适配器输出的结构化结果为准。结果为 OK、产物已生成但 PowerShell 进程退出码非 0（真机实测：Word 12 收尾恢复 Options.UpdateLinksAtOpen 时该属性不存在抛错）不再判失败，只在证据 warnings 附 NATIVE_PROCESS_EXIT_WARNING:returncode=N（含 stderr 末尾 300 字符）。结果本身为 failed 时仍按上述错误码失败，告警不会掩盖任何结构化失败。
WPS 与 Office COM 的边界：WPS Office（注册 KWPS.Application/KET.Application 等类、伪装 v12/v14 版本号或接管 .doc/.xls 文件关联）不等于 Microsoft Office COM 可用。本版本提供两个显式 opt-in：--allow-wps（仅在用户显式授权后允许 WPS COM 应答，证据恒附 WPS_ADAPTER_REAL_MACHINE_UNVERIFIED，真机回验完成前按必复核对待）与跨平台的 --soffice-headless（见上文）。未给 --allow-wps 时检测到 WPS 应答仍结构化拒绝（WPS_ENGINE_DETECTED_NOT_ALLOWED），绝不静默切换引擎。OFFICE_COM_CLASS_NOT_REGISTERED（0x80040154）的两义不变：桌面会话下可见的 Office 入口可能只是 WPS 伪装，服务/非交互会话下 Office 可能未对该会话注册。处置：先在前台会话用 doctor（只读元数据 native_environment.wps_precheck 与 soffice_environment，不发 COM 调用、不启动 soffice）核实，或走无适配器替代路径（.doc 另存 .docx、.xls 另存 .xlsx 后重新入库）。WPS/soffice 路径在开发机上全部 NOT_RUN，真实保真度待安装 WPS/LibreOffice 的机器回验，未回验前不宣称可用。真机新观察：存在 WPS 兼容层把 KWps.Application 的 app.Name 也报成 "Microsoft Word" 12.0 的机器——名称识别判不出 WPS 家族，--allow-wps 分支在该机实际走不到，属环境特性而非代码错误；真身 WPS（自报 KWPS/ET 身份）的机器出现前 WPS_ADAPTER_REAL_MACHINE_UNVERIFIED 不消除。
-
documents：历史版本列表新增latest_ingested、current_source、当前stage/error、retryable和固定字段的adapter摘要。latest_ingested=false说明这只是该来源的历史镜像，不能拿它替代当前版本。 -
status：每个 job 增加version_id、source、retryable和adapter，可先判断是否需要定向批次。 -
duplicate-report：只读返回当前 ready 版本中内容哈希相同、但来源作业不同的候选组。输出的relationship=...candidate_only不表示文件业务含义、版本意图或授权关系相同；命令不自动合并、删除、重挂或改写任何来源/证据。 -
reattach --input：{"version_id":"原版本","path":"移动后的绝对路径","expected_revision":7}。核验原字节哈希后重新绑定，不改历史来源。 -
card-revise --input：{"supersedes":"旧卡ID","expected_revision":7,"body":{...与card-add相同...}}。创建候选，确认后旧卡为 superseded。 -
review-ocr --input：{"version_id":"OCR版本","expected_revision":7,"confirmed_by":"用户明确确认的原话","entries":[{"locator":"ocr:page:1/line:1","text":"已校核文本","review_note":"核对原页的说明"}]}。只允许真实OCR位置，不覆盖原始文本；已有校核不可重复覆写，首次之后的修改走 review-ocr-revise。 -
review-ocr-revise --input（dev.6）：{"version_id":"OCR版本","expected_revision":7,"confirmed_by":"用户原话","entries":[{"locator":"ocr:page:1/line:1","action":"revise","text":"修订后文本","review_note":"修订依据"},{"locator":"ocr:page:1/line:2","action":"retract","review_note":"撤回原因"}]}。每个动作追加一条 history（动作、revision、时间、原话、raw_span_hash）并递增一个 revision；revise 替换生效校核，retract 撤回生效校核（检索与新卡片门禁回退到原始待校核 OCR 行），撤回后可用 revise 重新生效，连续撤回报错；返回 affected_cards 提示引用了相关行的卡片但不自动改卡。原始 OCR 行与版本永不修改。 -
manual-add --input（dev.7，dev.33 LK-59 扩展 provisional/region/cell，dev.34 LK-59 扩展 confirm 流转）：{"version_id":"版本","expected_revision":7,"confirmed_by":"用户亲核原话","entries":[{"page":5,"text":"运营部","note":"第5页组织图内漏读词，对照原图可见"}]}。用于解析/OCR 整词漏读、没有 locator 的内容；page必须是该版本真实页，或用{"anchor":"body:8",...}锚定真实 page:/body: span。生成 locatormanual:page:5#1（同锚点按序 #1/#2，撤回不复用），禁止冒充 ocr:/表格坐标。强制 confirmed_by+note；可被 search（origin=manual_user，dev.34 起附 state）与建卡门禁直接引用。条目可选provisional:true+region:"右上区域"+cell:"B3"，生成state=provisional的候选证据；provisional 候选不得支撑建卡（LOCATOR_NOT_FOUND 拒绝），evidence 输出provisional_manual_count/provisional_manual_locators，search 命中带state=provisional/review_required=true/card_support=blocked_LOCATOR_NOT_FOUND。 -
manual-revise --input（dev.7，dev.34 LK-59 扩展 confirm_provisional 与锚点保留）：{"version_id":"版本","expected_revision":7,"confirmed_by":"用户原话","entries":[{"locator":"manual:page:5#1","action":"revise","text":"运营管理部","note":"修订依据"}|{"locator":"...","action":"retract","note":"撤回原因"}|{"locator":"...","action":"revise","text":"候选部门","note":"人工已核","confirm_provisional":true}]}。规则同 review-ocr-revise：完整动作链（added/revised/retracted/重开 added）、逐动作 revision、撤回后检索与门禁失效、不可改原始 payload。dev.34 起：revise 默认保留原 state/region/cell（候选不因文本修订意外丢失锚点合同）；confirm_provisional:true把 provisional 转为 confirmed，需要显式人工意图 + revision 校验，返回附confirmed_provisional_locators；对已 confirmed 的 span 调用 confirm 报NOT_PROVISIONAL_CANNOT_CONFIRM。 -
card-ack --input（dev.7）：{"card_id":"卡片ID","expected_revision":7,"review_note":"已对照变更后的证据复核，结论不受影响"}。清除卡片上的来源复核标记（review_flags）并留 card:source_ack 事件；不改变卡片 state。无待处理标记时使用报 NO_SOURCE_FLAG_PENDING。 -
cards的effective_state=needs_review表示引用不是最新就绪来源（stale_sources）或引用的校核/人工证据发生了修订撤回（review_flags，dev.7）；review_flags给出 locator、动作类型与时间。不是后台监控所有原文件变化。先更新库才知道新版本。
duplicate-link-plan（dev.33 只读清单）给出复核字段后，用 duplicate-link-apply 把人工决定写成可审计的关系记录；记录不合并、不删除、不改挂任何证据，重挂仍走 reattach 的哈希校验：
python -B $cli --root $vault --library company-a duplicate-link-apply --input <JSON>
python -B $cli --root $vault --library company-a duplicate-link-show --input <JSON>
python -B $cli --root $vault --library company-a duplicate-link-retract --input <JSON>duplicate-link-apply 请求为 {"source_hash":"64位哈希","expected_revision":12,"confirmed_by":"人工复核原话","note":"复核依据","sources":[{"document_id":"...","version_id":"...","business_subject":"2026责任分工","document_type":"职责表","effective_version":"2026版","retention_reason":"部门留存"}],"authoritative":"可选，组内某版本ID"}。规则：sources 必须覆盖该候选组当前全部来源（DUPLICATE_LINK_SOURCE_MISMATCH），四个复核字段均为必填非空（INVALID_LINK_ENTRY）；记录为 duplink-v1，快照保留每组来源的原路径与版本号（来源链不丢）。同一组同决定重放返回 reused_verified 不加 revision；已有 active 记录时给出不同决定报 DUPLICATE_LINK_CONFLICT，须先 duplicate-link-retract（撤回保留完整 history 与最后快照）再重放。候选组消失（来源变化/不再同字节）报 DUPLICATE_GROUP_NOT_FOUND，须重新 duplicate-report 复核。duplicate-report/duplicate-link-plan 对每组标注 link_state（none/active/retracted）。记录只代表人对"同字节副本归属"的判断，不证明业务语义相同。
带 PDF 版面/OCR 告警的版本可用只读 layout-grid 从入库时保存的 OCR 词级边界框聚类出候选栅格：
python -B $cli --root $vault --library company-a layout-grid --input '{"version_id":"版本ID"}'
python -B $cli --root $vault --library company-a layout-grid --input '{"version_id":"版本ID","pages":[2,5]}'前提是入库时用了 --ocr-windows（原生 OCR 行自带 words/box 词框）。输出 status=candidate_grid_pending_review，每页给出 grid_rows/grid_columns 与 candidate_cells（cell 为 Excel 风格坐标、region 为"第R行第C列"、state=provisional、review_required=true）。栅格由词框按 y 聚类行、x 间距切段、x 起点对齐列确定性生成，不是权威表格（basis=derived_from_ocr_word_boxes_not_authoritative_table）；无词框页如实报 no_word_box_basis，全部无基础报 LAYOUT_GRID_BASIS_MISSING（该页需重入库或走 pdf-review-plan），单页超 4000 格报 LAYOUT_GRID_CELL_LIMIT。命令只读不加 revision。补录闭环：人工对照原页逐格核验后，用 manual-add（provisional:true + page + region + cell）写入候选，再以 manual-revise confirm_provisional:true 确认；确认前候选不能建卡。
doctor、init、client-preflight 的输出带只读 setup_hints 提示块，主动提示用户提供原始资料路径（source_path）、解析后库路径（library_root）与库ID，并显式区分 scope=personal（个人知识）与 scope=team（团队公用知识）：两者库ID/来源根/库根互不重叠，团队资料只进团队来源根、个人资料只进个人来源根，越界或跨 scope 入库被拒；团队库仍在本机，共享只走导出包与受控副本。提示块不提供默认盘符、不创建目录、不写任何路径。
--binding <配置JSON> 提供时如实报告绑定状态，已保存绑定不会被重复索要：
python -B $cli doctor --binding F:\资料库\bindings.json
python -B $cli --root $vault --library company-a init # 收据带 setup_hints
python -B $cli --scope personal --binding F:\资料库\bindings.json client-preflightbinding_state 取值：unknown_not_provided（未给 --binding，不猜测）、not_saved（配置文件不存在）、saved（附 scopes 与 config_path；经 --scope 解析时显示该 scope）、invalid_config（附 error，含畸形 JSON）。提示块纯只读，不改变 revision 与任何命令行为。
依据两次真实运行（333 份简历库、10,834 文件万级语料）：
documents输出信封（破坏性变更）：从裸数组改为对象{"status":"ok","library":<库ID>,"count":N,"documents":[...]}，数组每项形状不变（含latest_ingested/current_source/stage/error/retryable/adapter）。Python 层Store.documents()仍返回列表。init收据新增kind="initialized"与root（库根绝对路径）；status新增root（纯追加，既有键不变）。- pypdf 的
Ignoring wrong pointing object等噪声不再泄漏到 stderr/stdout（PDF 解析结果不变）；加密 PDF 返回ENCRYPTED_FILE并在detail说明需先在库外解密（请求内密码通道为 LK-73，尚未提供）。 review-queueschema 稳定为：items（每项version_id/source/flags/categories/action）、count（本次返回条数）、filtered_count（筛选后总数）、total_count（筛选前告警文件总数）、counts_by_category（按全部告警计）、truncated（filtered_count > limit时为 true）、filters、basis。请求新增include_pending（默认 true）与pending_limit（1-500，默认 50）：pending_jobs汇总从未入库的失败作业（jobs 表中 intent=allow、stage=failed、error 非空），含total_count/truncated/counts_by_error/counts_by_group（adapter_required=OCR_REQUIRED、FORMAT_NOT_ENABLED；blocked_input=ENCRYPTED_FILE、LIMIT_EXCEEDED、EMPTY_CONTENT、NATIVE_TIMEOUT、PARSE_FAILED、DEPENDENCY_MISSING；other）/有界items（job_id/source/error/group）/groups_legend；hold/cancel 作业不计入；只读，不启动重试。LIMIT_EXCEEDED（scan 与 ingest 两处）的detail含实际字节数、33554432 bytes (32 MiB)上限与"库外拆分/缩小后再入库"建议；scan 项、逐文件回执与--summary失败样本透传error_detail。- 显式
--input清单不再需要--recursive：清单内子目录路径在不带--recursive时也会被遍历到（此前静默变为requested_missing、零入库且complete:true）；目录的自动发现仍必须显式--recursive，清单边界仍严格限定为列出的路径。 - 新增只读
batch-progress：请求省略receipt时取batches/中最新回执，也可给回执 id/文件名/库内绝对路径（..越界拒绝：RECEIPT_OUTSIDE_BATCHES；不存在：BATCH_RECEIPT_NOT_FOUND）。返回receipts_present/receipt_path/source/complete/processed/counts/age_seconds/last_receipt；basis 明确：仅凭 age 无法区分"进行中"与"进程中断"，命令本身不启动也不重试任何作业。0.3.0 LK-103 追加（纯增量）：同时返回lease（state=alive/stale/absent、name、holder、heartbeat_age_seconds、seconds_until_expiry、ttl_seconds；只读，不清理过期行）与run_state（completed / paused_time_budget / running / other_operation_running / suspected_interrupted / pass_boundary_not_running / stopped_without_completion / unknown_not_running；空库为 never_run）。suspected_interrupted只表示租约心跳过期，命令仍不自动重启或重试任何作业。 - 新增只读
batch-report：聚合库内全部回执（请求可给failure_sample1-100，默认 20），每个唯一路径以最新一条回执为准，输出receipts（total/complete/not_complete 及每文件年龄）、sources、unique_paths、status_counts、failed_by_error、failed_by_extension、unsupported_by_extension、有界failure_sample；为路径级结果，不是去重版本盘点。 capacity-report请求新增{"top_payloads":N}（0-500，默认 0=关闭）：返回top_payloads.entries（仅当前版本，按存储 payload 字节降序：version_id/source/payload_bytes/pct_of_payload/cumulative_pct），用于识别撑大库体积的少数大文件。- batch
--summary新增counts_basis：counts 是路径级尝试计数（同字节跨路径可能复用/跳过版本），counts.created不是版本增量；去重盘点以stats.versions的前后差值为准。 - 长任务零 token 公约（0.2.2-beta.9 LK-102）：
batch-progress/batch-report是唯一推荐的进度入口——每轮最多查一次，禁止在对话内sleep轮询、tail/grep 原始日志或查进程盯梢（事故依据：2026-09-24 几 GB 资料解析中 29 次 sleep≈162 分钟、59 次监控命令、115 轮对话、单轮上下文 87 万字符，耗费数千积分；本地解析本身零 token）。交互运行 batch 一律--summary；大批量先 scan/batch-plan（chunk_size分片、请求体passes=fast/deep/all、time_budget_seconds1–86400）确认规模与适配器开关后起跑，运行中禁止杀进程改参数。细则见 SKILL.md「长任务运行公约」与 ingestion.md「长任务零 token 运行方式」。
python -B $cli --root $vault --library company-a documents
python -B $cli --root $vault --library company-a review-queue --input '{"pending_limit":100}'
python -B $cli --root $vault --library company-a batch-progress
python -B $cli --root $vault --library company-a batch-report --input '{"failure_sample":50}'
python -B $cli --root $vault --library company-a capacity-report --input '{"top_payloads":20}'
python -B $cli --root $vault --library company-a capacity-policy-plan --input <capacity-policy.json>capacity-policy-plan（0.2.2 beta）从当前不可变版本的 payload 大小分布给出 p50/p95/max 和一个仅观测的告警提议。提议为 max(minimum_warning_bytes, p95 * warning_multiplier)，不会拦截 ingest、不会改数据库，也不是跨资料库的容量承诺。选定实际告警值前先查 capacity-report top_payloads，发现 XLSX/XLSM 镜像异常大时先走 recompile-plan，不要直接把原件判为不可用。
--input 接收本地 JSON 文件路径，不是内联 JSON。最小 capacity-policy.json 内容为 {"minimum_warning_bytes":1048576,"warning_multiplier":2}。
边界总则：四个命令全部只读、本地确定性、零模型 token、无向量；PDF 文本只检测不重排，章节树 outline 优先、字号启发式恒 provisional，派生事实不存储不建卡。
python -B $cli pdf-checkup --path D:\原件\某文件.pdf --json-output ascii
python -B $cli pdf-checkup --path D:\原件\机密.pdf --password-stdin- 与 doctor 同级，不接受也不需要
--root/--library/--scope；不解析进库、不渲染、不 OCR、不新建文件。加密 PDF 只走既有--password-prompt/--password-stdin（密码不进 argv/请求文件/收据）。 - 返回
kind=pdf_checkup_read_only：file（name/path/size_bytes）、encrypted、page_count、structure（source=outline/font_heuristic_provisional/none、provisional、chapter_count）、pages[]（page/embedded_chars/empty/image_objects/multicolumn_suspected/multicolumn_reason）、summary（empty_pages/suspected_multicolumn_pages/pages_with_image_objects 页号清单）、suggested_route（embedded_text_ready / ocr_required_all_pages / mixed_or_layout_review_required）、warnings、notices。 - 双栏为几何怀疑（行首聚类：≥8 行带、两侧各≥3 行、少数比≥0.25、间隙≥0.15 页宽且居中、L/R 交错≥3 次），漏报可重读、误报浪费人工，阈值故意保守。
- 错误码：
PDF_CHECKUP_PATH_REQUIRED（未给 --path，exit 2）、SOURCE_UNAVAILABLE、LIMIT_EXCEEDED（32 MiB）、DEPENDENCY_MISSING（缺 pypdf）、ENCRYPTED_FILE（无密码/密码错）。
python -B $cli --root $vault --library company-a pdf-pages --input body.json
python -B $cli --scope personal --binding binding.json pdf-quality-report --input body.json- 请求体均为
{"version_id": "..."}；已登记为只读 scope 命令（可省略库参数走--scope/--binding）。 pdf-pages：逐页台账 page_count/pages[]（embedded.chars 与 cross_page 标记、ocr_lines、ocr_review_required_lines、dimensions、audit_actions、layout_flag、chapter）+ structure_source + cross_page_pairs。basis 明示只读聚合、不重排、页数≠质量判断。pdf-quality-report：layers.parse / layers.structure / layers.evidence 各带 status=ok/warnings/review_required；evidence_closure 每条风险（embedded_empty_pages、ocr_lines_pending_review、no_text_detected_pages、short_embedded_text_gap、multicolumn_reading_order_unverified、provisional_chapter_tree、cross_page_paragraphs、provisional_manual_spans）必带 pages/locators 与确定的人工 action；overall_status 取最差层。闭口规则：报告本身不纠正任何东西，所有 review_required 项完成对应人工动作（OCR 入库/逐行 review-ocr/人工核阅读序/确认章节/manual-revise 确认）并复检报告转为非 review_required 后，该证据才可用于引用或建卡。- 错误码：
VERSION_ID_REQUIRED、EVIDENCE_NOT_FOUND、CORRUPT_EVIDENCE。
请求体加 {"context": "full"}（search 也可只用于 search；非法值 INVALID_CONTEXT_MODE）：命中项/证据视图机械附 文档:x > 表:x > 章节:x（provisional）> 页:n > line:m > locator 头部与结构化字段（document/chapter/chapter_provisional/page/table）。纯字符串装配，不取相邻句、无向量、不参与匹配排序；无章节树降级为文档名+locator，不报错。
python -B $cli --root $vault --library company-a table-facts --input facts.json请求体：version_id（必填）、table（序号，默认 0）、header_row（默认 1；或 use_header_map=true 复用已存表头映射）、columns（白名单，1–50 列，缺省取全部表头）、units（列名→单位的显式映射）、exclude_rows（行号）、limit（1–1000，默认 100）。返回 facts[]（fact 串、column/value/unit、unit_unverified、year_context=null + year_inference=never_attached、derived/provisional/review_required 全 true、evidence={version_id,table,row,coordinate,locator}）、fact_count、truncated、basis。单位只来自 units 映射，绝不推断；数字无映射时 unit=null 且 unit_unverified=true；年份绝不机械附着；结果不写库、不建卡、不改镜像。 错误码：VERSION_ID_REQUIRED、TABLE_NOT_FOUND、INVALID_HEADER、AMBIGUOUS_HEADER（表头空/重名时须显式 header_row 或 header-map）、HEADER_MAP_STALE、FIELD_NOT_FOUND、INVALID_UNIT_MAP、INVALID_FACT_COLUMNS、INVALID_EXCLUSION、INVALID_FACT_LIMIT。
大批量起跑前的确定性闸门：以 inventory 写入关闭 的方式复刻 scan 选择（不入库、不写
inventory/scan-inventory.json、不启动任何作业），默认也不启动 Office/OCR 进程。
python -B $cli --root $vault --library company-a batch-preflight --path $source --recursive
python -B $cli --root $vault --library company-a batch-preflight --path $source --native-windows --input '{"env_probe":true}'参数与 batch/scan 同源：--path、--recursive、--native-windows、--office-windows、
--ocr-windows、--allow-wps、--soffice-headless（0.4.0-beta.3 起）、
--trusted-office、--language、--ocr-short-pages；--input 请求体支持
paths（相对清单）、only_failed、only_not_ready、env_probe（必须布尔；true 且确有
Office/OCR 候选且在 Windows 上才真实探测，超时 45 秒；soffice 候选为跨平台 soffice --version 探测）、page_sample_cap（0–1000，默认 200）。
返回 status=ready/ready_with_warnings/blocked、ready_to_start、plan_summary
（discovered/runnable/states/tier_counts/total_bytes/ocr_candidates/office_candidates 细分
（0.4.0-beta.3 起含 com/soffice/trusted/untrusted/no_adapter 分项）/
held/cancelled/unsupported/videos/archives）、blockers[] 与 warnings[]（每项
code/affected/paths_sample/advice）、environment、flags_echo。阻断码包括
OPENPYXL_MISSING、PYPDF_MISSING、TRUSTED_OFFICE_REQUIRED 及 env_probe 专属的
OFFICE_NOT_INSTALLED/OFFICE_VERSION_UNSUPPORTED/SOFFICE_NOT_INSTALLED/OCR_LANGUAGE_UNAVAILABLE/
OCR_RUNTIME_UNAVAILABLE/WINDOWS_REQUIRED；WPS 相关为告警（WPS_ENGINE_SELECTED/WPS_FALLBACK_ACTIVE）；
无适配器 DOC/XLS、视频、压缩包、超 30 页 PDF 采样
风险、扫描缺失项为 warning。status=blocked 时退出码为 2，可直接进脚本判断。
0.4.0-beta.3 起 preflight 本身可被 acceptance_harness.py 的 preflight_trust_gate
确定性复核（合成假 .doc/.xls、不传 env_probe，零 COM/soffice 启动）。
跨全部回执的真实库运行画像，每路径以最新收据为准：
python -B $cli --root $vault --library company-a batch-profile --input '{"failure_sample":50}'返回 receipts_present、unique_paths、outcomes、failed_total、failure_rate、
by_tier、by_pass、failed_by_extension、top_errors[]（code/count/share_of_all_paths/
advice/paths_sample，advice 为确定性处置建议）、incomplete_receipts[] 与 next_actions[]
（only_failed 重跑模板标 read_only=false；batch-report、batch-progress 模板标 true）。
failure_sample 1–100（默认 20），越界 INVALID_FAILURE_SAMPLE。只读，不重试任何作业。
独立脚本，不针对具体知识库；固定仓库 davidwei-evolution/lived-knowledge。子命令
check / download / verify-archive / plan-install / install 的完整授权流程与安全边界见
update.md。检查≠下载≠安装三次独立授权；否定检查结果必须以 Releases 网页交叉
复核；候选包代码绝不被导入执行；安装由当前可信 install_cover 事务切换、后验 doctor 失败自动
回滚。维护者发布打包用 release_pack.py（离线，只写 dist/）。
aggregate是 dataset 之上的确定性薄层：同一张表要么干净可用、要么被门禁拒绝，不存在"聚合时放宽质量要求"的通道；聚合结果带 plan_hash，成员逐行可追溯，但它不是统计抽样也不是跨表 JOIN，母体边界就是"该版本该表表头以下、非空、未排除"的行集合。formula-check不依赖 Excel 计算，也不信任公式文本以外的东西：重算只使用同表其他单元格的缓存现值；引用格本身也是公式时使用其缓存值（与打开工作簿时的可见值一致），循环/跨工作簿等情形落入 unverifiable。mismatch 只表示缓存值与白名单重算不一致，是否更新工作簿由用户在库外决定。header-map是用户显式提供的映射，核心不自动拼接多级表头、不猜测语义；映射存 meta（schema 仍为 1），与不可变 payload 分离。重新入库产生新 vid 后必须重新映射（旧映射不会自动迁移），这是有意的防错。
人工补录与 OCR 校核是两条独立证据线：manual 证据本身即用户确认（无需再过 OCR 校核门禁），OCR 校核门禁只对 ocr: 开头 locator 生效。任何 revise/retract 都会给引用该 locator 的现存卡片（候选与已确认一视同仁）打来源复核标记；带标记的候选不能 confirm（CARD_SOURCE_FLAG_PENDING），必须先 card-ack 或走 card-revise 替代（新候选确认后旧卡标记随 supersede 清除）。evidence 输出含 manual_spans（生效项）与 manual_history（状态+完整链）。
PDF 短文本页（dev.7）：入库加 --ocr-short-pages 才会对短嵌入文本页挂接 review_required OCR；默认只在 page_audit/warnings 给出 OCR_SHORT_PAGE_GAP 提示。scan/batch 同名透传，该选项只影响 PDF。
evidence --id <版本> 的 reviews 只包含当前生效校核（供检索与卡片门禁使用），新增 review_history 列出每个 locator 的 state（active/retracted）与完整动作链（reviewed→revised→retracted→重新 reviewed）。dev.4/5 旧库的单条校核记录读取时按 active 兼容呈现，首次修订时自动升级为状态文档；旧记录进入 history 首项，其历史 revision 无法逐条复原，显示 null，不编造。库 schema 仍为 1。
ingest --path <PDF> --native-windows 对 PDF 生成合并版本而非纯 OCR 版本：嵌入文本页保留 page:N 原文，OCR 仅挂接嵌入文本为空的页面。证据多出 page_audit（逐页 embedded_text_kept/ocr_added_pending_review/no_text_detected 与行数）和 merged_from；新告警为 OCR_ADDED_PENDING_REVIEW:page:N、OCR_NO_TEXT_DETECTED:page:N，嵌入提取失败回退 OCR-only 时为 EMBEDDED_TEXT_UNAVAILABLE。旧版本不可变且继续可按版本 ID 调阅；作业的最新版本指向合并镜像。review-ocr、卡片门禁与版本哈希规则不变。
- XLSX/XLSM 对有值或公式格按稀疏计数；若外接矩形超过 2,250,000 格但真实单元格未超限，镜像以
sparse_rows=true保存并附SPARSE_CELL_MIRROR_REVIEW_REQUIRED，只能检索和核对，不能直接作为dataset、统计或组合分析母体。超限 detail 会给出工作表、声明尺寸、有效范围、稀疏格数、矩形格数和上限。 search --text <词>优先走 SQLite FTS5 的可重建投影；返回method与index_basis。FTS5 没有命中时回退精确子串，保证中文短语和旧库的可发现性。表格行命中带document.source、table、row、locator与含表头的preview；来源文件名和路径也可检索。命中/截断只用于导航，不是统计母体。- 图片
.jpg/.jpeg/.png/.bmp/.tif/.tiff/.jfif默认失败码OCR_REQUIRED；仅传--ocr-windows才调用 Windows OCR。webp/heic/gif仍明确未启用。.xlsm由 openpyxl 只读解析，宏不执行也不保留。 doctor的install_readiness只给出依赖状态、可复制 pip 命令、国内镜像示例及自检命令；技能从不自动执行安装。仓库根的requirements.txt仅列可选openpyxl/pypdf。
ingest --path <pdf> --password-prompt通过隐藏本机提示读取一次密码；--password-stdin仅读取一行 UTF-8 标准输入。密码不能写入命令参数、JSON 请求、收据、作业、meta 或证据；批量接口不接收密码。recompile-plan --input <JSON>可选给version_ids，只读列出当前可从旧协议升级的 XLSX/XLSM 版本和不适用原因。recompile-apply必须给原计划 ID、同 revision、相同的版本清单、confirm:true和由backup生成且同库同 revision 的快照路径；旧版本保留，并在recompile-receipts写体积对比收据。schema-gap-plan返回schema_plan_id与字段候选。schema-topic-save必须给该计划 ID、同 revision、每个字段的显式 version/table/header 映射；它只保存有 locator 的分来源字段投影，跨文件关系不自动推断或连接。
- fts-status 是只读状态；fts-build 是显式本地 SQLite 索引写入，不修改版本、来源、payload 或 revision。既有库在未建索引时搜索回退精确子串，不会因读取自动建索引。
- schema-gap-plan 接受 question 和 required_fields，仅对照已有表头输出字段缺口，不推断实体或关系，也不写专题。
- upgrade-preflight 只读列出协议、索引状态与重编译边界；任何存量重编译都须另行显式授权。
- 此版本历史上曾接受
--password；0.2.1 起该入口已移除，改用隐藏提示或 stdin 单次读取。 - capacity-report 可给 top_payloads 与 payload_budget_bytes，返回预算预警和原件/镜像比，不拒绝入库。退出码：0=全部成功；2=命令完成但存在 failed 项；其他非零=参数、运行或环境错误。
当 FTS 未就绪且库超过 50,000 个证据单元时，search 默认拒绝全库线性扫描并返回 BROAD_SEARCH_CONFIRMATION_REQUIRED。先用 query-plan、documents、table-profile、project、field 或 topic 缩小范围；确认接受耗时后才增加 --allow-broad-search。fts-build 请求可传 JSON，例如 {"chunk_size":100,"max_chunks":1}；未完成返回 incomplete，只有实际索引行数与预期一致时才返回 built。批量入库与索引建立不能并发写同一库，冲突返回 OPERATION_IN_PROGRESS；batch-progress 的 operation 字段会显示批次状态。
batch-plan 支持请求 {"chunk_size":100}，只输出稳定的分片与 batch_id，不写库；将一个分片的 paths 作为后续 batch 的显式清单逐个执行。
以下工具是库外独立脚本，不经 knowledge.py 派发、不需要 --root/--library，默认只读；收据 schema 各自版本化。
- Excel 超限分诊（LK-91）：
python scripts/excel_triage.py --paths <绝对路径...> | --input <paths清单JSON> | --root <来源目录> [--recursive] [--output <收据路径>]。逐表给声明/有效尺寸、稀疏格、空行空列与远端杂点，分类为 within_limits/ghost_removable/genuinely_oversized/source_bytes_over_limit/empty_workbook/unreadable，并只输出库外清洗建议（删空行空列、复核间隙远端、外部拆分）与reingest_candidates。它绝不修改、移动、删除原件，225 万格与 32 MiB 门禁不因分诊放宽；~$锁文件计入 skipped_temporary_lock，符号链接拒绝。 - OCR 质量门槛（LK-93）：
python scripts/ocr_quality.py evaluate --labeled <人工标注JSON> --output <报告路径>。标注样本形如{"engine":"...","samples":[{"id":1,"locator":"可选定位","reference":"人工真值","hypothesis":"OCR文本","fields":{"字段名":{"reference":"...","hypothesis":"..."}}}],"thresholds":{可选}}。输出语料 CER、字准确率、全行命中率与字段精确率，判定 batch_usable/review_assist_only/not_usable/inconclusive_*；阈值可在请求中显式覆盖并标记 operator_supplied。未达批量可用时 OCR 文本只保留为待复核证据。python scripts/ocr_quality.py engine-plan [--output ...]仅给替代中文 OCR 引擎（PaddleOCR/RapidOCR）的评估计划与授权门，不联网、不下载、不安装、不执行。 - 原子化安全覆盖安装（LK-94）：
python scripts/install_cover.py --source <构建目录> --target <已装技能目录> [--output <收据路径>]。安装前独占锁探测；复制到同级 staging 并按 sha256+文件数校验；目标目录永不先删，先改名保留为时间戳备份再切换；切换或后验（CORE 可读且版本一致，可传 doctor/stats shim）失败自动回滚旧版、保留失败树；成功后备份仍留在盘上由操作者确认后处置。它只做本机文件操作，不联网拉包。
原生 Office 适配器（LK-92）：xls-read 与 doc-convert 都要求 Office 2010（v14）+，低版本分别返回 EXCEL_VERSION_UNSUPPORTED/WORD_VERSION_UNSUPPORTED 并在合同中给出"手工另存为 .xlsx/.docx 后免适配器入库"的替代路径；文件打不开（加密/锁定/损坏）返回 OFFICE_DOCUMENT_OPEN_FAILED；COM 忙（RPC_E_CALL_REJECTED）归类为可人工单次重试的 OFFICE_COM_BUSY。xls-read 每完成一张工作表在请求文件旁写 .checkpoint.json；超时时已完成表名进入 NATIVE_TIMEOUT 详情，但部分进度永不当作解析成功。
python scripts/video_pipeline.py frames-ocr --video <用户显式选定的单个视频> --output <用户选定的输出目录> [--timestamps 12.5,40,90] [--every-seconds 30] [--max-frames 240] [--ffmpeg <本机ffmpeg路径>] [--ffprobe <本机ffprobe路径>] [--language zh-Hans-CN] [--max-width 1920] [--restart]。只处理命令行点名的那一个文件，不扫描目录、不下载模型、不上传、不写知识库。
流程与边界：ffprobe 取时长 → 显式时间戳优先（排序去重、越界拒绝），否则按等分段中点排程 → 硬上限 240 帧/次不可调高 → 逐帧 ffmpeg 快速定位抽取（单帧 120 秒超时）→ Windows.Media.Ocr 逐帧识别画面文字（不是语音、不推断画面语义）。行定位锚定为 video:<文件名>@<秒数>/ocr:page:1/line:n 并保留词框，全部 review_required。每帧落盘后立即写 checkpoint.json，重跑只续做未完成帧（0.001 秒级跳过）；视频身份（size/mtime）或请求参数变化返回 NOT_RUN/CHECKPOINT_MISMATCH，需显式 --restart，旧帧保留。帧无文字是 ocr_no_text（非失败）；OCR 失败按帧隔离记 COMPLETED_WITH_OCR_FAILURES；抽帧失败记 FAILED。退出码：0=PASSED/READY/NOT_RUN，2=存在失败。输出目录下 <片名>.frames/ 保存帧图与检查点，另写 .keyframe-ocr-evidence.json 收据（计数/耗时/磁盘/帧 sha256）。画面语义识别（人物/场景/物体，LK-64c）与 ASR 均不在本阶段：ASR 仍只有 asr-plan。
scan/batch 的每个条目新增建议性字段 tier（T0 纯文本 / T1 结构化 / T2 含 OCR / T3 慢或需决策；不认识的格式为 null）与 estimated_cost_seconds；条目状态本身不变。batch 执行前按 pass→tier→预估成本→路径 确定性排序：T0–T2 与全部非解析条目（错误、missing、held、unsupported）在 fast 段，T3 在 deep 段；每条回执新增 tier 与 pass，回执文件新增 scheduling 块（模式、tier_counts、推迟计数）。显式路径清单（--input 或请求 paths）是调用方自己的顺序，一律不重排（scheduling.mode=explicit_manifest_no_reorder）。请求体可传 passes（fast/deep/all，默认 all）与 time_budget_seconds（1–86400）：到点优雅落检查点暂停（complete=false、operation.state=paused、paused.reason=TIME_BUDGET_REACHED），续跑 = 重新 scan + batch（去重由既有 jobs 保证）。batch-plan 同步按调度排序出分片。退出码语义不变。
scan/batch 默认把发现的全部文件（含 unsupported/错误）登记到 <库>/inventory/scan-inventory.json（路径/文件名/扩展名/大小/扫描状态/tier；哈希只对 scan 已经读过字节的受支持文件记录，绝不为清点去读 GB 级媒体）。新只读命令 inventory-search（需 --root/--library）：请求 {"query":"关键词","tier":"T3","limit":50} 按文件名/路径子串（大小写不敏感）过滤，输出 matches 与 total_matches；只搜文件名与路径，正文检索仍走 search。清点写入是尽力而为，失败不影响 scan 结果。无清点文件时报 INVENTORY_NOT_FOUND。
scan 发现视频后缀（.mkv/.mp4/.avi 等）不再只报 unsupported：条目带 media=video、needs_decision=true、default_decision=skip 与 channel_card（L0 元数据/L1 内嵌字幕/L2 ASR/L3 关键帧 OCR/L4 语义打标；L4 恒 batch_execution=NEVER_AUTO，availability 来自 LK-101 探测）。batch 默认对视频写 held 回执 + VIDEO_CHANNEL_SELECTION_REQUIRED（无人值守即 hold，绝不自动处理）。请求体可传仅本次调用有效的选择：video_default_channels（如 ["L0","L1"]）、video_selections（按路径覆盖）、video_output_dir（L0/L1 收据的输出目录，必填否则 VIDEO_OUTPUT_DIR_REQUIRED）。L0/L1 在 batch 内执行（L1 经本机 ffmpeg 提取第一条内嵌字幕轨后走既有字幕证据链，缺 ffmpeg 记 FFMPEG_NOT_AVAILABLE，绝不下载）；L2/L3 只写"请另行运行 video_pipeline asr-plan/frames-plan"的计划指引；选 L4 或任何未知通道分别被拒（SEMANTIC_CHANNEL_NEVER_AUTO / INVALID_VIDEO_CHANNEL）。选择不落任何全局配置。
库外独立脚本，不经 knowledge.py 派发：python scripts/archives.py archive-plan --archive <压缩包> 只读清点成员（名称/大小/是否加密/层级/是否嵌套包/危险名），zip/tar 系走标准库零依赖；.7z/.rar 探测本机 7z.exe/UnRAR.exe（PATH 或环境变量 LIVED_KNOWLEDGE_ARCHIVE_TOOLS_DIR，对外推荐 D:\解析\归档工具\），缺失时确定性 NOT_RUN + 官方下载地址，skill 永不捆绑解压器。python scripts/archives.py archive-extract --archive <包> --members <逗号分隔成员名> --sandbox <库外空目录>：zip-slip（绝对路径/盘符/..）拒 ARCHIVE_ZIP_SLIP_REFUSED；嵌套包只登记不自动递归（ARCHIVE_NESTED_NOT_EXTRACTED）；成员数 >10,000 或展开 >2 GiB 须 --authorize-limits；加密 zip 密码只经环境变量 LIVED_KNOWLEDGE_ARCHIVE_PASSWORD（RAR 加密无免 argv 通道，直接拒 RAR_PASSWORD_CHANNEL_UNSUPPORTED）；密码绝不进 argv/日志/收据。只解用户勾选的成员到沙箱，原件与库零改动，收据给"包路径+成员名"溯源与清理提示。
工具目录环境变量用法（0.4.0-beta.2 明确）：7z/UnRAR 不在 PATH 时（如 WinRAR 默认装在 C:\Program Files\WinRAR），调用前把该目录设为 LIVED_KNOWLEDGE_ARCHIVE_TOOLS_DIR 即可被探测到——PowerShell：$env:LIVED_KNOWLEDGE_ARCHIVE_TOOLS_DIR='C:\Program Files\WinRAR'；脚本只在该目录内查找 7z.exe/UnRAR.exe，不改系统 PATH、不下载、不捆绑任何归档工具。环境变量只对当次调用生效，不落任何持久配置。
库外独立脚本：python scripts/vision_probe.py [--input <JSON>]。探测根目录解析顺序：请求 vision_models_root > 环境变量 LIVED_KNOWLEDGE_VISION_MODELS_DIR > 未配置（status=path_unconfigured；对外推荐 D:\解析\视频运行时\vision-models\<引擎>\<档位>，本机沿用 F 盘现行布局，代码不写死盘符）。模型四态确定性收据：model_missing / pseudo_model（零字节、目录无清单、或未提供期望 sha256）/ model_hash_mismatch / model_ready；skill 绝不下载、不捆绑、不 pip 安装任何模型，只输出"官方地址 + 目录 + sha256"三要素提示。收据含统一调用契约（输入帧+候选标签 → 场景标签+置信度+人工复核态，ONNX Runtime CPU 优先，NEVER_AUTO）。LK-100 的 L4 选项可用性即来自本探测。
scan/batch 的 walk 层把 ~$ 前缀的 Office 临时锁文件单列为 skipped_temporary_lock（条目 reason=OFFICE_TEMPORARY_LOCK_FILE，回执 summary 有独立计数），不进 unsupported 明细与 unsupported_by_extension 分布，也不静默丢弃；库外分诊脚本 excel_triage.py 同口径。真实文件命名如 ~$演习 2.20.doc（0 字节），对失败盘点是纯噪声。
- .eml（enabled，stdlib 零依赖）：只提取信头表（From/To/Cc/Subject/Date/Message-ID）与 text/plain 正文部分（自动处理传输编码与字符集）；HTML 部分记
PART_RECORDED_NOT_EXTRACTED、附件只记文件名表并警示ATTACHMENTS_RECORDED_NOT_EXTRACTED，绝不解包附件内容、绝不取外部资源；仅头无正文时若信头也无已知字段则 EMPTY_CONTENT。 - .xmind（enabled，stdlib 零依赖）：v8+ 的 content.json 递归提取话题 title/labels/notes（locator
sheet:N/topic:M，深度上限 50）；旧版 content.xml 提取 title/plain 文本节点；非 zip 或缺 content 文件确定性 PARSE_FAILED；样式/关联线/标记不重建（XMIND_TEXT_ONLY 警示）。 - .ppt（recognized，not_enabled）：scan 纳入识别范围（tier T1，快速确定性失败在 fast 段），ingest 稳定返回 failed 收据
FORMAT_NOT_ENABLED，detail 给替代路径"PowerPoint 另存为 .pptx 后重新入库"；不再泛化为未知 unsupported。.vsd 同口径登记（导出 .vsdx 或 PDF），解码器未捆绑的 heic/webp/gif 维持既有合同。 - doctor 同步：zero_dependency_formats 增 .eml/.xmind；install_readiness 新增
optional_enhancement块（Pillow 版本/用途/精确安装命令/国内镜像/自检命令），Pillow 仅服务图片型 PDF 增强路径（LK-99），缺失不改变核心就绪状态。
knowledge.py 所有命令统一：0 = 成功（结果中无 failed 项）；2 = 其余一切非成功情形——①命令正常完成但存在失败条目（如 batch 部分文件 failed/unsupported，counts.failed>0，非崩溃）；②请求被拒或运行/环境错误（status=failed + error 码）；③argparse 参数错误。不要把退出码 2 一律当成进程崩溃：先看 JSON 输出——有 counts 且 counts.failed>0 即流程正常完成、部分文件失败，按回执排查；status=failed 才是命令级失败。batch-progress/batch-report 为只读命令，0=查询成功、2=参数或状态错误；库外独立脚本（excel_triage/archives/video_pipeline/vision_probe/pdf_enhance）的退出码见各自收据 schema 与上文各节。