知识系统的六个工程反模式

概述

在构建 LLM Wiki Plugin（AI 驱动的个人知识操作系统）过程中，v3.3 重构暴露了六个反复出现的工程反模式。这些模式不仅适用于知识管理系统，也适用于任何由多个脚本/微服务组成的数据管线。

同一逻辑（如 YAML frontmatter 解析）在 6 个脚本中独立实现，每个实现行为略有不同（regex vs string-find vs yaml.safe_load）。表面上系统工作正常，但一个 bug 修复不会传播到其他副本，且边界行为不一致导致间歇性数据丢失。

诊断信号：grep 发现同名函数 >3 处。 修复模式：提取共享模块，确立"canonical implementation"。

当系统的一部分（Claude 引擎）是上下文感知的，而另一部分（Qwen API）是无状态的，两者产出质量差距巨大。无状态 API 不知道已有哪些页面、不知道正确的 wikilink 目标、不知道哪些实体已经存在。

诊断信号：API 调用方比内部引擎产出更多重复/断链。 修复模式：在 API 调用前注入上下文（--context-pages），在 API 返回后做本地去重（scan_existing_pages）。

当 pipeline 在入口处拒绝有问题的数据（如 YAML 格式错误），数据被静默丢弃，没有错误日志，没有恢复路径。用户不知道发生了什么，也无法修复。

诊断信号：continue 语句在循环中跳过条目，没有对应的错误记录。 修复模式：入口宽容（always save + error annotation），后续修复（lint/manual fix），持久错误日志。

一个命令写入路径 A（qa/），另一个命令从路径 B（raw/qa/）读取。两条路径永远不交叉，导致数据孤岛。

诊断信号：grep 写入路径和读取路径，发现零交集。 修复模式：统一为单一数据流 + snapshot 跟踪文件。

PostToolUse hook 在设计时（10 个 wiki 页面）很轻量，但数据量增长到 188 个页面后，每次编辑触发全量图谱重建（读取所有文件），成为隐性性能瓶颈。

诊断信号：hook 执行时间随页面数线性增长。 修复模式：mtime 防抖 / 增量更新 / 批量延迟重建。

图谱边使用 sorted([src, tgt]) 去重，对无向关系（wikilink）正确，但对有向关系（contradicts, supersedes）丢失了方向信息。A 矛盾 B ≠ B 矛盾 A。

诊断信号：去重后的数据无法还原出原始方向。 修复模式：按关系类型选择去重策略（有向保序，无向排序）。