fix(knowledge): 统一frontmatter边界并拒绝未闭合策略

2026-09-04 20:04:45 +08:00
parent cec89494f9
commit 233e156061
3 changed files with 91 additions and 13 deletions
@@ -26,6 +26,7 @@
 | F-08 | 将不同处理策略误判为配置漂移 | 普通与仅本地笔记共存时不能重建 | 按策略校验覆盖，独立检索并融合排名 |
 | F-09 | 简单字符串比较忽略 YAML 语法 | 注释等合法写法可能关闭本地限制 | 解析 YAML 节点，非法策略明确拒绝 |
 | F-10 | 迁移 DDL 与版本号分开提交 | 中断后重启报重复列 | 原子迁移、并发重检及旧半迁移恢复 |
+| F-11 | BOM 与未闭合头部被当作无策略 | 本地限定正文可能进入普通 API 路由 | 统一 frontmatter 边界，异常头部拒绝保存 |

 ## 3. F-01 / F-03：模型可用不等于索引可用

@@ -136,6 +137,16 @@ embedding_local_only: true

 ## 9. 工程经验

+### F-11：frontmatter 边界与 BOM
+
+审阅通过隔离保存链路复现：普通 `---` 头部返回 `local_only=True`，加 UTF-8 BOM 或移除结束分隔线后却返回 `False`。原因是策略、元数据和正文分别使用 `startswith` 与子串查找判断头部；未识别成功时静默按无策略处理。
+
+实际方案：三处改用 `_frontmatter` 统一识别。允许一个文件起始 BOM，开头分隔符须为独立的 `---` 行，结束分隔符支持独立的 `---` 或 `...` 行及尾部空白；支持 LF、CRLF、CR。`---metadata`、`----` 等前缀不会被误当成结束分隔符。已识别开头但没有结束行时返回 `INVALID_EMBEDDING_POLICY`，不继续索引。
+
+原 Markdown 不做去 BOM 或换行转换，正文偏移仍由原文计算 UTF-16 code unit，保证来源定位。保存和重建使用同一解析路径；更新失败恢复原文件。测试覆盖 BOM 的本地限定保存与重建，未闭合更新不触发模型调用且文件、数据库正文保持原值。
+
+F-11 修复后完整后端回归：533 项通过，新增 17 个参数化用例。普通 API 与本地回退、分区检索及迁移测试均通过，未调用真实外部模型。
+
 ### F-09：本地限制标记的 YAML 解析

 再次审阅复现：`embedding_local_only: true # keep local` 被旧字符串比较解析为 `False`。加注释没有改变用户意图，却可能使保存或重建发送正文到远程 Embedding。