fix(knowledge): 区分普通分割线与元数据头部

docs/retrospectives/阶段F-Embedding与知识库问题与解决方案.md

@@ -27,6 +27,7 @@
 | F-09 | 简单字符串比较忽略 YAML 语法 | 注释等合法写法可能关闭本地限制 | 解析 YAML 节点，非法策略明确拒绝 |
 | F-10 | 迁移 DDL 与版本号分开提交 | 中断后重启报重复列 | 原子迁移、并发重检及旧半迁移恢复 |
 | F-11 | BOM 与未闭合头部被当作无策略 | 本地限定正文可能进入普通 API 路由 | 统一 frontmatter 边界，异常头部拒绝保存 |
+| F-12 | 普通 Markdown 分割线误判为头部 | 正常笔记保存失败、重建中止 | 按元数据声明识别头部，保留普通正文 |
 
 ## 3. F-01 / F-03：模型可用不等于索引可用
 
@@ -137,6 +138,16 @@ embedding_local_only: true
 
 ## 9. 工程经验
 
+### F-12：普通分割线与元数据头部消歧
+
+F-11 修复后，`---` 和 `---\n\n# Title\n\n正文` 等合法 Markdown 被误判为未闭合 frontmatter，原先能够保存的笔记被拒绝；库中已有此类文件时全量重建也会失败。
+
+实际方案：开头分隔线仅作为候选，继续判断内容是否声明元数据。YAML 映射、以键值形式开始的头部或显式 `embedding_local_only` 声明按元数据处理，缺少结束行仍报错；普通段落、标题和代码块按正文保留，包括之后再次出现分割线的情况。已有闭合空头部继续兼容。
+
+显式本地策略即使与其他损坏的 YAML 行共存，也不能退成普通正文。无结束分隔符的键值头部仍视为错误；普通文章中有歧义的开头键值形式应避免紧随文件首行 `---`。回归覆盖分割线正文解析、真实保存和重建、BOM 与本地策略原有拒绝规则。
+
+围栏代码块中的策略示例不算真实声明，保留为 Markdown 正文。验证记录：首批修复后全量后端 542 项通过；补充围栏示例识别后，解析、迁移与检索相关 130 项通过。本轮未修改前端，未调用真实外部模型。
+
 ### F-11：frontmatter 边界与 BOM
 
 审阅通过隔离保存链路复现：普通 `---` 头部返回 `local_only=True`，加 UTF-8 BOM 或移除结束分隔线后却返回 `False`。原因是策略、元数据和正文分别使用 `startswith` 与子串查找判断头部；未识别成功时静默按无策略处理。