v0.4.0 — 脏文档预处理 recipe 层(可插拔 + baseline 5 能力)

v0.4.0 —— 脏文档预处理 recipe 层(可插拔 + baseline 5 能力)

版本范围

本 release = v0.4.0 单一功能:在 ingest pipeline 的 G16 文本主导分流之后、frontmatter 注入之前,加一个可插拔的脏文档预处理层(recipe),把 markitdown 的“半脏”输出加工成更适合 ripgrep 字面检索的干净结构化文本。

起因:vision(v0.3)已兜住 G15/G18(扫描件 / 图为主),但 G16 “半脏”文本无人管 —— 解析问题在上游、检索问题在下游,recipe 是这条分界线的代码化。

---

主要功能

可插拔 recipe 接口 + registry

scripts/recipes/__init__.py:

• Recipe(抽象基类):applicable(src_path, markitdown_text) -> bool + process(...) -> RecipeResult
• RecipeResult(dataclass):text / applied / recipe_name / notes
• get_recipe(name="baseline") -> Recipe:registry 入口(写死 dict,默认只注册 baseline,惰性 import 实现类)

tool-agnostic 落点:接口稳定,实现内部可 wrap 任何工具(subprocess / 其他 binary / 纯 Python)。不引入动态加载 / 配置驱动 / CLI 注册参数(不做插件框架,留下个 minor+)。

baseline recipe 5 能力(scripts/recipes/baseline.py,零新依赖)

纯 stdlib,对 markitdown 半脏输出做 5 项字面后处理:

1. 孤立行合并 —— 跨页表 / 跨页段被拆成的碎行,保守回接(相邻非结构行、上行行尾无标点才合;CJK 衔接不加空格)
2. 重复空白行压缩 —— 连续 ≥3 空行 → 2 空行
3. 表格行 padding —— 合并单元格拍扁后列数不齐的 | 表格行,按本块最大列数补空单元格
4. 控制字符清理 —— NBSP / 全角空格 → 普通空格;零宽字符(ZWSP / ZWNBSP)→ 删除
5. 跨页表合并(最保守一档)—— 相邻两表 列数相同 + 下表首行重复表头 + 上表末行非汇总行(合计/总计/小计),全满足才合并、删下表重复表头;判不准就不合(宁可漏合不可误合)。不做 3+ 表连续合并 / 列数不等对齐猜测 / 表头模糊匹配 / 任何语义判断。

G16 binary .md 路径接入 + recipe_applied frontmatter 字段

• recipe hook 只在 G16 binary .md 路径(markitdown 转出正文那一份)。text / image / video / G15 / G18 分支不经 recipe,frontmatter 不加 recipe_applied 字段(无 schema 污染)。
• 例外:.vsdx 正向转换路径不经 recipe。.vsdx(LibreOffice headless → PDF → markitdown)产出的 .md 虽记 vsdx+G16,但由独立代码路径写盘,不经 recipe hook、不写 recipe_applied 字段(recipe 5 能力针对表格 / 段落结构;vsdx 的 markitdown 输出为图形标签拼接,无适用结构)。
• G16 .md frontmatter 新增 recipe_applied:baseline(已加工)/ none(透传未改)/ failed(异常)。
• recipe 只动 markitdown 正文;其后 append 的 .docx 嵌入表 / 嵌入图段不经 recipe(它们是 python-docx / vision 另一条产物)。
• INGESTED_MD 的 ingest_log notes 附 recipe=<状态>(动作摘要),便于追溯做了哪几项。

recipe fail → fallback markitdown 原版(诚实降级)

recipe 抛任何异常 → ingest 捕获 → 用 markitdown 原版写盘(整段逐字保留,不阻断 ingest)+ frontmatter recipe_applied: failed + log 记降级原因。控制流保证:md_text 仅在加工成功时才被替换,异常路径下保持 markitdown 原值。

---

experimental 定位(诚实 caveat,不是缺陷)

recipe 接口提供能力齐全的 baseline 骨架;真实语料的检索增益验证 / 调参,由实际使用者用自有语料完成,不由本特性预先调好。这是沿仓库 experimental 定位的诚实 caveat。

• 本 release 只保证能力级字面变换正确性:5 能力各有确定性合成单测(合成输入 → 人工写定预期,预期值独立于实现 → 不违反 fixture-first 反自指)。
• 不编任何“真实文档识别率 / 检索增益百分比”数字。
• 真要做语义级精细化(字段抽取 / 表头语义识别 / 复杂跨页表),是未来另写独立 recipe,不撑大 baseline。

---

测试

• python scripts/recipes/test_baseline.py —— 5 能力确定性单测,5/5 全过。每能力 ≥1 正向(该变换)+ ≥1 负向(不该动,断言原样);能力 5 含 3 个“不该合”负向(列数不同 / 有汇总行 / 表头不重复)+ 非相邻负向 + 3 表 disjoint 边界。
• python scripts/smoke_test.py —— 既有 16 assert + v0.4 recipe assert(#17:接口 import + baseline 可调用)= 17/17 全过,无回归。
• 评估记录见 tests/查询记录.md C 系段(C1-C5 = 能力 1-5 变换正确性)。

---

已知限制

真实语料表现待使用者验证

baseline 5 能力的变换正确性由确定性合成单测锁定,但真实脏文档上的检索增益 / 误伤率,本 release 不提供数据——留实际使用者用自有语料验证 + 调参。recipe 是 experimental 骨架,不预调参。

能力 5 markdown 分隔行残留

源表含 markdown 分隔行(| --- |)时,跨页表合并只删下表重复表头行,下表的重复分隔行会作为内容空行残留(对 ripgrep 检索无害)。彻底清理留未来独立 recipe。

能力 1 / 能力 5 是启发式

孤立行合并、跨页表合并是保守启发式,真实语料边界 case 可能漏合(by design:宁可漏合不可误合)。漏合只是没优化,不破坏数据。

---

向后兼容

• ingest 行为变化仅限 G16 binary .md:正文经 recipe 加工(默认 baseline)+ frontmatter 多一个 recipe_applied 字段。
• text / image / video / G15 / G18 / stub 分支行为完全不变,不加 recipe_applied 字段。
• search.py 检索栈、CLAUDE.md 的 LLM 4 级降级行为契约完全不动(.md 还是 .md,scope 不变)。
• v0.3.x 已入库材料无需任何操作;重跑 ingest 时 G16 .md 会经 recipe(幂等:已干净文本 applied=False 透传)。

---

致谢

• Hugin 拍板:recipe 同步跑(ingest 阶段)/ 替代 markitdown 输出模式 / 不动 LLM 契约 / 能力 5 最保守一档钉死 / C 系评估 = 能力变换正确性(不预调真实语料参)。
• 节奏:PER 5 阶段;Phase 2 落盘前先跑 grep 矩阵与 plan 假设对账(冲突即停),Phase 2.5 字节级 review patch 放行,Codex 外审 no blockers 才 tag。

---

工作流定义(再次重申)

本项目实行 “Codex 外审通过 = release 门禁”:不强行收尾;找问题就修,修完再审;直到 “no blockers”。

v0.3.0 — tier 5 类分层 + .shelved/ 默认 search 排除

v0.3.0 — tier 5 类分层 + .shelved/ 默认 search 排除

版本范围(v0.2.3 + v0.3.0 合并发)

本 release 包含 v0.2.3 hotfix + v0.3.0 主要功能 两部分。v0.2.3 不单独 release。

---

Part A: v0.2.3 hotfix 内容(合并发布)

Codex 在 trialV3 测试仓库真实素材入库时反馈,Hugin 部分采纳(4 实质 / 拒 2 装饰):

• TEXT_EXTS 扩展(.py / .csv / .geojson / .xml / .cpg / .prj / .meta / .tfw):GIS 业务高频文本文件按原文入库,不再 ERROR_UNSUPPORTED_EXT
• IMAGE_EXTS 加 .tif / .tiff:TIFF 走 vision 路径 A(Claude Code 内置 vision 能力直接识别)
• MARKITDOWN_FAILED_STUB 降级路径:markitdown 失败不丢文件,改为"源文件 cp + stub"二件共存,装齐依赖后重跑 ingest 自动重入正文
• UNSUPPORTED_COPY_STUB 降级路径:未知扩展名(.shp / .dbf / .zip / .fcs 等)不丢文件,改为"源文件 cp + stub",LLM 检索时禁令明示"请打开源文件查看"
• smoke_test 10/10 → 12/12

设计语义变更:

• v0.2.2:失败 → ERROR_* + 不入库 + 报错
• v0.2.3:失败 → STUB_ONLY_* + 源文件 + stub + 可恢复

---

Part B: v0.3.0 主要功能

tier 5 类分层(canonical / normal / working / versions / assets)

入库时 AI 在 routing_plan 阶段判定 tier(详 CLAUDE.md §6 Step E):

• canonical / normal:主知识 / 一般材料,默认参与检索
• working / versions / assets:过程材料 / 旧版本 / 原始素材,落到 .shelved/<tier>/ 默认不检索

判定方式:AI 看文件名 + 父目录 + 内容上下文综合判(不写代码硬规则,符合 v0.2.0 AI 语义路由原则)。

.shelved/ 物理目录(三 bucket × B 分散)

projects / areas / resources 三 bucket 内每个 subdir 独立 .shelved/<tier>/。archives bucket 不走 tier。

search.py --deep flag

默认排除 .shelved/** + .archive/**。追溯过程材料 / 旧版本 / 素材时加 --deep(含 --hidden,真扫隐藏目录)。

frontmatter 3 新字段

入库时 ingest 自动注入 kb_tier / kb_default_search / family_key(versions 类才写 family_key)。

migration helper(dry-run only)

scripts/migrate_v023_to_v030.py 扫描已入库材料 → 推断 tier 候选 → 输出 logs/v030_migration_candidates_<ts>.md 候选清单。不自动 mv(自动 mv 留 v0.4+,因 mv 涉及 log / stub / .assets / frontmatter 五件套同步)。

smoke_test 12/12 → 16/16

加 4 个 assert:

• [13/16] tier 白名单拒非法 tier(Layer 6.2)
• [14/16] tier=working 端到端落 .shelved/working/
• [15/16] family_key Windows 非法字符拒(Layer 6.3)
• [16/16] search --deep 三 bucket × .shelved/ 真扫端到端(强证据断言:命中文件数 ≥ 3 + 路径含 .shelved)

Layer 6 校验(REQUIRED_FIELDS_SCHEMA 6 层)

v0.2.2 5 Layer(key / type / non_empty / field-rules / path-traversal)+ v0.3 Layer 6(tier 必填 / 白名单 / family_key Windows 非法字符)。

---

致谢

• Codex 测试仓库 trialV3 现场反馈:tier 分层 + 5 类 + 8 条 plan 修订建议
• Codex 终审反馈 4 条(中 1 + 低 3):archives tier 契约 / README 中英命令同步 / plan 状态残留 / E11 措辞精确化。全部修完, no blockers。
• Hugin 拍板修订:AI 填 tier 不写硬规则 / .shelved 命名 / 三 bucket 适用 / dry-run only migration
• v0.3 节奏:整体走完 PER 5 阶段后 Codex 一次终审,通过才 release(不沿用 v0.2.2 hotfix 每轮审)

---

已知限制

tier 判定误判

tier 判定靠 AI 推断,边界 case 可能误判(如文件名含 build 但实际是项目最终方案)。累计 ≥ 2 真实误判触发补 CLAUDE.md §6 Step E 规则(沿用 v0.2.2 W-5-W1 跟踪机制)。

migration helper 仅 dry-run

v0.3.0 第一版 migration helper 只输出候选,不自动 mv。自动 mv 留 v0.4+(mv 涉及 log / stub / .assets / frontmatter 五件套同步,复杂度等价于重做一次 ingest)。

v0.2.3 已入库材料

v0.2.3 已入库材料默认按 tier=normal 参与检索(可能包含本该 .shelved 的 working / versions / assets)。用户跑 migration helper 出候选清单,人工审 + 手动 mv + 重跑 ingest。

v0.3 阶段 3 假阳 PASS 自捉

v0.3 阶段 4A 跑 E11 fixture 时发现阶段 3 smoke [16/16] 假阳:加 --deep 时漏 --hidden,rg 默认跳隐藏目录 → --deep 实际扫不到 .shelved/。弱断言(keyword in stdout)误判通过。阶段 4A 立即修复 + 断言加强(命中文件数 + 路径双判定)。

经验落定:smoke 断言优先用结构化字段判定,跨阶段新增 flag 时端到端验证应跑真实有命中的 fixture。

详见 tests/v0.3-plan-progress.md 阶段 4A W-v0.3-阶段3-W1 段。

V1-V7 vision 路径本地无法跑回归

V 系 fixtures 需要 vision 推理 + ffmpeg/poppler 依赖。本 release 沿用 v0.2.x 阶段 5 W-2 deferred 状态,留 release 后用户实测。

archives bucket frontmatter 强制规范化

04-archives bucket 不走 tier 协议。AI 在 plan 手填的 kb_tier / kb_default_search / family_key 会被忽略,archives 落地 frontmatter 强制为 kb_tier=normal + kb_default_search=true。这是 by-design(archives 是 PARA 归档层,不再参与 tier 分类),不是 bug。

---

向后兼容

• v0.2 已入库材料 + v0.2 routing_plan 完全向后兼容
• v0.2 routing_plan 重跑:自动注入 kb_tier=normal + kb_default_search=true,不报错
• v0.2.x → v0.3.0 升级无需任何操作(除非主动跑 migration helper)

---

工作流定义(再次重申)

本项目实行 "Codex 外审通过 = release 门禁":

• 不强行收尾
• 找问题就修,修完再审
• 直到 "no blockers"
• 重新定义"可以 release"的标准

v0.3 节奏:整体走完 PER 5 阶段(含阶段 0 基线确认)+ Codex 一次终审,通过才 tag / push / release。

v0.2.2 — Hotfix: plan schema 补完 / BOM 兼容 / .claude/ 隔离

v0.2.2 — Hotfix: plan schema 补完 / BOM 兼容 / .claude/ 隔离

修复 v0.2.0 → v0.2.1 之后由 OpenAI Codex 持续六轮审查触发的 15 条问题。
v0.2.1 → v0.2.2 间隔较长,因本项目实行 "Codex 外审通过 = release 门禁" 工作流:
每个版本必须过 Codex 静态审查,通过才发版本。这一版迭代了六轮才达 "no blockers"。

修复(六轮累计 15 条)

Codex 第二轮(3 条)

• execute_plan schema 缺 target_subdir 直接 KeyError 崩溃 → ERROR_INVALID_PLAN_ITEM
• plan JSON 读取不支持 UTF-8 BOM(Windows PowerShell 默认输出)→ encoding=utf-8-sig
• .claude/ Claude Code working state 未隔离 → .gitignore

Codex 第三轮(1 条)

• README.md routing_plan schema 描述漏 target_subdir → 中英文双语同步代码必填字段

Codex 第四轮(2 条)

• REQUIRED_FIELDS 仅 4 字段必填,文档声明 6 字段 → 代码侧补齐 frontmatter + ai_reason
• smoke_test.py docstring 残留 v0.2.1 / 4 assert → 同步 v0.2.2 / 8 assert

Codex 第五轮(4 条)

• target_subdir 只校 key 存在不校非空("" 通过,落到 bucket 根)→ 三层校验
• frontmatter 只校 key 存在不校类型(str/None/list 通过,inject 阶段 .items() 崩)→ 类型强制 dict
• smoke_test 路径边界 3 case 因缺新必填字段被 REQUIRED_FIELDS 假拦截(假覆盖)→ 补齐 6 字段 + 反向断言
• smoke_test docstring 残留 "4 个 assert" → 同步 "10 assert"

系统性升级:validate_plan_schema 5 Layer 校验

第五轮反馈促成系统性升级,不再打补丁式扩字段:

Layer	维度	例
1	key 存在	missing required field: frontmatter
2	类型正确	frontmatter must be dict, got str
3	非空	ai_reason must not be empty string
4	字段特殊规则	src_abs must be absolute path / target_bucket whitelist / 01-projects bucket requires target_project
5	路径穿越	target_filename contains path traversal / absolute path prefix

校验失败统一转 ERROR_INVALID_PLAN_ITEM,不中断其他 items(沿用 v0.2.1 P0-2 同款机制)。

smoke_test.py 扩充到 10/10

• [1] install 烟测调用参数(search.py --scope all)
• [2] ingest.py scan-only 跑通
• [3] 路径边界 3 case 真实拒(反向断言验证非假覆盖)
• [4] 依赖 import(docx + yaml + markitdown)
• [5] schema Layer 1: 缺 target_subdir 拒
• [6] BOM plan 兼容
• [7] schema Layer 1: 缺 frontmatter 拒
• [8] schema Layer 1: 缺 ai_reason 拒
• [9] schema Layer 2: frontmatter 非 dict 类型拒(3 type cases)
• [10] schema Layer 3: target_subdir / ai_reason 空串拒(3 empty cases)

10/10 PASS + 手工 16 边界 case = 22 case 全覆盖。详见 tests/v0.2.2-hotfix-progress.md。

已知行为变更

旧 routing_plan.json(frontmatter=null 或 ai_reason="" 风格)在 v0.2.2 之后会被 ERROR_INVALID_PLAN_ITEM 拒。这是 by-design 严格化,不是 regression。若有本地缓存的老 plan,重新让 AI 产新 plan 即可。

致谢:六轮 Codex 审查闭环

时间	动作
2026-05-21 01:50 UTC	v0.2.0 release(PER 6 阶段 / 11 W 系)
2026-05-21 当天	Codex 第一轮 5 条 + GPT 4 条 → v0.2.1
2026-05-21 03:56 UTC	v0.2.1 release(26h 内 hotfix 完成,详见 tests/v0.2.1-hotfix-progress.md)
2026-05-21 ~ 之后	Codex 第二/三/四/五/六轮持续审查,累计 15 条
2026-05-22	v0.2.2 release(六轮迭代追下来)

本项目实行 "Codex 外审通过 = release 门禁":Codex 找问题就修,修完再审,直到 "no blockers"。没有上限,不强行收尾。

这不只是修 bug,是重新定义 "可以 release" 的标准。

v0.2 全程 PER 协议(Plan-Execute-Review)6 阶段 + 11 W 系观察点 + v0.2.1/v0.2.2 双 hotfix + 六轮 Codex 闭环,完整执行轨迹见:

• tests/v0.2-plan-progress.md(v0.2 升级 6 阶段 + W 系裁决)
• tests/v0.2.1-hotfix-progress.md(v0.2.1 hotfix 9 修复)
• tests/v0.2.2-hotfix-progress.md(v0.2.2 hotfix 六轮 + 5 Layer 校验)

v0.2.1 — Hotfix: install / 路径边界 / 文档代际同步

v0.2.1 — Hotfix: install / 路径边界 / 文档代际同步

修复 v0.2.0 发布后由 OpenAI Codex(5 条)+ ChatGPT(4 条)外部审查触发的 9 条问题。
诚实记录:这些问题大部分是 PER 协议在跨阶段重命名/删除时未追全部引用导致,已落入 handbook 防御规则(详见 tests/v0.2.1-hotfix-progress.md "顺手做" 段)。

P0 修复(必修,7 条)

• install.ps1/.bat 烟测从 --scene 同步到 --scope(阶段 3 改 search.py CLI 时未同步 install 脚本,装完会卡在 verification 步骤)
• ingest.py execute_plan 加路径边界校验:bucket 白名单 + 拒绝 .. / 绝对路径 / 路径分隔符;Path.resolve().relative_to(CORPUS) 二次防御。单 item 校验失败转 ERROR_INVALID_PLAN_ITEM,不中断其他 items
• requirements.txt 加 python-docx==1.1.2(阶段 4 plan 写了 docx 嵌入表抽取,执行漏在 requirements 里声明依赖,装新 .venv 时 ImportError)
• requirements.txt numpy 2.4.4 → 2.2.6(v0.1 latent bug:numpy 2.4+ 要求 Python 3.12+,Python 3.11.9 装不上)
• README.md 隐私边界段重写(中英):明示使用 AI 编程助手时文件会进 LLM 上下文,不是"完全离线";政企用户建议用 ollama 等本地模型助手
• scripts/README.md 全量同步 v0.2 CLI(docs/试用指南.md + tests/查询记录.md 顺手扫到的也一并修)
• README.md 加最小 routing_plan.json 样例(5 items 覆盖项目内 / 脱钩 / 留项目 / 归档 / explicit 5 路径)

P1 修复(应修,2 条)

• search.py --no-stub 命中统计走 rg 层过滤(原 Python 后处理过滤导致 per_term_hits 与 files 计数不一致,误导 LLM 回退判断)
• 新增 scripts/smoke_test.py 最小自动化测试(4 个核心 assert:install 调用参数 / scan-only / 路径边界拒绝 malformed / 关键依赖 import;不引入 pytest 重型测试栈,符合"轻量"设计前提)

兼容性 / 升级

• v0.2.1 是 v0.2.0 的 hotfix,完全兼容 v0.2.0;直接 git pull && python scripts/smoke_test.py 即可
• 从 v0.1.0 升级请先读 docs/v0.1-to-v0.2-migration.md(本次未改;v0.2.0 起的迁移指南依然适用)
• v0.2.0 已知限制中:numpy / python-docx 装包问题在本版修掉;vsdx 正向路径未实证 + ODF 走 stub + 行为识别三叠加靠推断 三条仍留 v0.2.1+ 后续跟踪(详见 tests/v0.2-plan-progress.md "v0.2 全 W 系状态盘点" 段)

顺手做(超 hotfix 范围但相关)

• 阶段 6 grep 检查只覆盖 CLAUDE.md / README.md / README.en.md,未扫 scripts/README.md + docs/试用指南.md + tests/查询记录.md 的盲点
• 本次扫全仓 .md/.py/.bat/.ps1/.sh/.yaml/.yml,所有命中都修
• 写入未来 plan 防御规则:跨阶段重命名/删除字段时,grep 必须扫全仓库,不能只挑根目录 README 类

致谢

v0.2.0 release 时间:2026-05-21 01:50 UTC
Codex + GPT 外审到达时间:2026-05-21 当天(< 24h)
v0.2.1 hotfix 完成时间:2026-05-22(release 次日)

9 条问题全采纳 + 全修 + 全验。"发了就被审 + 真回应"是开源该有的样子 — 感谢 OpenAI Codex + ChatGPT 两份独立审查意见。

v0.2 全程 PER 协议(Plan-Execute-Review)6 阶段闭环 + 11 W 系观察点裁决记录 + v0.2.1 hotfix 9 修复跟踪,完整执行轨迹见:

• tests/v0.2-plan-progress.md(v0.2 升级 6 阶段 + W 系裁决)
• tests/v0.2.1-hotfix-progress.md(v0.2.1 hotfix 9 修复 + 顺手做)

完整修复列表

每条修复的 commit SHA + 改动文件 + 验收输出,详见 tests/v0.2.1-hotfix-progress.md。

v0.2.0 — PARA + scope×behavior + AI 语义路由 + 嵌入媒体

v0.2.0 — PARA + scope×behavior + AI 语义路由 + 嵌入媒体

从 v0.1.0 升级请先读 docs/v0.1-to-v0.2-migration.md。

新增能力

• corpus 结构 → PARA 四层:01-projects / 02-areas / 03-resources / 04-archives;projects 内部 5 固定子目录(01-方案 / 02-章节 / 03-纪要 / 04-调研 / 05-附图)+ 99-其他
• ingest 范式 → AI 语义路由:python ingest.py scan-only <src> + execute-plan <plan> 两步;AI 在 agent loop 里产 routing_plan.json;path_map.yaml 退化为语义说明 + hint_subdir_keywords + explicit_mappings 兜底
• 检索 → scope × behavior 双轴:scope = PARA(由 CLAUDE.md §5 路由);behavior = 4 类行为单点定位 / 盘点 / 决策溯源 / 模糊探索(由 CLAUDE.md §2.0 识别);用户不被问任何选择题
• 新格式:docx 嵌入图三闸过滤 + vision 注入主 .md(不单建 .vision.md;G16 + frontmatter 联合验证)+ docx 嵌入表 python-docx 抽取(merged cell.text 复制,优化检索召回)+ vsdx LibreOffice 转 PDF + 降级 stub + odf stub 降级
• frontmatter 注入:ingest 时给 .md / .stub.md 自动注入 4 字段(type / date / project / tags);resources 类 project=null
• search.py 加 --project <名>:限定到 corpus/01-projects/<名>/;--scene → --scope
• 新增 scripts/archive_check.py:扫 01-projects/ 下 6 个月以上无新文件的项目作为归档候选(只展示,不自动 mv)
• 新增 16 个评估场景(11 个 v0.1 沿用 + 5 个新):E1-E10 agent loop + V1-V7 vision/视频/嵌入媒体;详见 tests/查询记录.md

不兼容点(从 v0.1.0 升级请注意)

• path_map.yaml 的 path_mappings / prefix_rules 字段在 v0.2 已废弃;新 schema 是 buckets 语义 + hint_subdir_keywords + explicit_mappings
• v0.1 4 个 prompts(场景1-历史方案查询.md 等)已删除并备份到 tests/v0.1-prompts-archive/;v0.2 是 4 个 PARA scope 文件(场景-projects.md 等);自定义修改需手动移植
• ingest.py <path> 单命令入口已替换为 scan-only + execute-plan 两步;旧调用方式不能用
• search.py --scene 01/02/03/04 已替换为 --scope projects/areas/resources/archives/all
• 首次跑 v0.2 ingest 会触发一次性全量重入(v0.1 ingest_log.jsonl 缺 src_mtime 字段 → v0.5 增量机制判 mtime 不等);第二次起增量正常生效

详见 docs/v0.1-to-v0.2-migration.md。

已知限制

• vsdx 正向路径未实证:本版 release 时本机未装 LibreOffice,只验证了 vsdx 降级路径(LibreOffice 不可用 → 永久 stub + failed_no_libreoffice 标记)。装 LibreOffice 后 vsdx 正向路径自动启用;v0.2.1 计划回归实证
• ODF (.odt/.ods/.odp) 入库走 stub 降级:markitdown 0.1.5 不带 ODF converter,走 G15 永久 stub + odf_status: failed_markitdown_no_odf_converter。需正文检索请先用 LibreOffice 转 .docx 后再入库(已有完整 docx G16 路径)。markitdown 后续版本支持 ODF 时自动生效无需改代码
• 行为识别在 3+ 触发词混合场景靠 LLM 上下文推断:CLAUDE.md §2.0 优先级规则只显式覆盖双叠加(如"哪些 + 为什么 → 盘点");三叠加(如"上次某客户那个项目里哪些章节对比过 X 和 Y")靠 LLM 推断"指向词最强者锁定"。欢迎 issue 反馈具体误判 case;累计 ≥ 2 误判触发补规则
• .venv 装包:若按 install.bat / install.ps1 装 .venv 在 numpy==2.4.4 失败,因 Python 3.11.9 无对应 wheel(v0.1 latent bug);workaround 用全局 Python + pip install --user,或 v0.2.1 修 requirements.txt(numpy → 2.2.6)
• markitdown 0.1.5 urllib3 警告:每次 import 输出一行 urllib3 (2.6.3) doesn't match a supported version;功能不受影响,markitdown 升级时自然消除

安装 / 试用

新安装:见 README.md §3 Quick Start。

从 v0.1.0 升级:见 docs/v0.1-to-v0.2-migration.md。

致谢

PER 协议(Plan-Execute-Review)6 阶段闭环执行,11 个 W 系观察点全程跟踪 + 裁决记录;详见 tests/v0.2-plan-progress.md。

v0.1.0 - Initial public release

First public release of agentic-kb-lite.

What's included

• agent loop with 4-level fallback retrieval (L1/L2/L2.5/L3)
• multi-modal support: image-heavy PPT, scanned PDF, video (via ffmpeg frame extraction)
• incremental ingest CLI (python ingest.py <path> defaults to incremental)
• bundled ripgrep (Windows) + cross-platform setup helper
• 11 reproducible evaluation fixtures (E1-E7 + V1-V4)
• bilingual README (中文 / English)

Requirements

• Python 3.10-3.12
• AI coding assistant (Claude Code / Codex / etc.)
• Optional: ffmpeg, poppler (for multi-modal)

See README.md for Quick Start.

Notes

This is the first public release. The v0.2 - v0.6 version numbers
referenced in CLAUDE.md track internal development milestones during
the trial phase before public release.