TXDE LLM Wiki Hub

本地多 LLM-Wiki 知识库的管理与读取中枢。它不编译任何库的内容，只回答三个问题：资料进哪个库（Route）→ 问题去哪些库读（Query）→ 多库是否健康（Lint）。库内部的摄取/编译/页面维护，一律遵循目标库自己的 SCHEMA.md 与 llm-wiki 规程（库内自治）。

> 架构原则：Hub 管"库之间"，库内自治照旧。Hub 对任何库的 wiki/ 内容只读，永不代写。

⚠️ 前置依赖：必须结合专家"知识管理专家"使用

本技能提供的是骨架、约束与编排；真正执行知识库的摄取（Ingest）／编译（Compile）／
检索（Query）／体检（Lint）流程，依赖专家 "知识管理专家"（对应技能 llm-wiki）。

• 执行任何建库/摄取相关操作前，先确认当前会话已调用专家"知识管理专家"。
• 若未调用 → 必须提示用户先添加，不得绕过专家自行编排摄取编译流程：
  > "本规范框架需结合专家『知识管理专家』使用。当前会话未检测到该专家，请先在专家中心添加并调用『知识管理专家』，再继续建库/摄取。"
• 职责边界：本技能管"库之间"（注册/路由/跨库读取/归档/新建/体检）；
  专家管"库之内"（摄取、编译、交叉引用、矛盾标注）。桥接点 = 库内 SCHEMA.md。

目录与定位

TXDE LLM Wiki Ana/            ← Hub 根（本技能位于其 wiki-hub/ 子目录）
├── registry.md               ← 多库注册表（唯一真相源：库条目 + 领域签名 + 别名）
├── routing-table.md          ← 别名/关键词 → 库 路由映射（用户可维护）
├── shared-entities.md        ← 软联邦：跨库共享实体登记（可选扩展）
└── wiki-hub/                 ← 本技能
    ├── SKILL.md
    ├── kit/                       # ← 可移植的知识库框架（新建库的规范来源）
    │   ├── KB-SCHEMA-CORE.md      # 必执行内核（新库 SCHEMA 必须继承）
    │   ├── SCHEMA-TEMPLATE.md     # 新库 SCHEMA 骨架模板
    │   ├── DISTRIBUTION.md        # 分发手册与密级边界
    │   ├── ANTI-PATTERNS.md       # 通用反例库
    │   ├── SINGLE-SOURCE-OF-TRUTH.md  # 跨文件重复治理规则（什么该收敛/什么允许重复）
    │   └── profiles/              # 可选规范（按强制力分层，现为空）
    ├── references/
    │   ├── registry-schema.md     # 注册表字段规范与加库流程
    │   ├── routing-guide.md       # 路由决策链说明
    │   └── cross-kb-links.md      # 跨库链接语法与软联邦规范
    └── scripts/
        ├── hub_registry.py        # registry 解析与路径变量解析（唯一真相源，其余脚本 import）
        ├── hub_list.py            # 列出全部库 + 每库签名
        ├── hub_validate.py        # 注册表校验（路径/字段/唯一性/变量解析）
        ├── hub_linkcheck.py       # 跨库链接与孤儿库体检
        ├── hub_archive.py         # 结论文件归档到目标库 workdir（仅保存，禁止编译）
        ├── kb_init.py             # 新建知识库（三层骨架 + SCHEMA + 注册；幂等不覆盖）
        ├── kb_lint.py             # 库内体检（机器校验清单 L01–L10；--list-checks 打印；见 kit CORE §二十一）
        ├── kb_index.py            # 索引重建与一致性校验
        └── selftest.py            # 套件自检闸门（AST 未定义名 + 常量齐备 + 语法 + --help + 共享模块 + 模板SSOT）

> 🔧 改动脚本后必跑自检：python3 "<skill>/scripts/selftest.py"
> （检查 AST 未定义名 / 护栏常量 / 语法 / --help / 共享模块依赖；退出码 0=通过。
> 防"跨文件抄代码漏常量"与"本地另抄一份解析口径"两类回归）

> 🔗 hub_registry.py 是路径解析的唯一真相源：${WORKSPACE} 与链式
> ${WORKSPACE_OF_<id>} 的解析、registry 字段白名单、kebab-case 校验、
> status 合法值全部只在此处定义。其余 7 个脚本一律 import hub_registry，
> 不得本地另抄一份（selftest.py 的 T5 闸门会拦截）。
> 这样保证：同一份 registry 在任何脚本里解析出同一个路径。

• registry.md 默认路径：本技能目录的上级目录（Hub 根）中的 registry.md。
• 若库文件位于其它盘/目录，registry 用绝对路径引用；库本体永不移动（"库不搬只引用"）。
• registry.md / routing-table.md 是数据文件：用 Write 一次性全量更新，修改前先备份。

🔒 密级边界（强制）

raw/ 与 wiki/ 内文件均不允许出本机，属于机密。

• ❌ 不上传云盘/第三方服务；❌ 不提交 git；❌ 不整段送入外部 AI。
• ✅ 分发给他人时只分发 wiki-hub/ 套件，绝不分发任何库本体。
• 详见 kit/DISTRIBUTION.md 第二节。

🔴 可执行检查点（D4 · 三道闸）

密级规则不靠"记得住"，靠脚本拦截。以下检查点已在实现中落地：

方向铁律：数据流动只能 外部 → 库内 workdir（Archive 单向）。
任何"库内机密 → 别处"的搬运都不属于本套件职责，必须走库内规程。

宽松提示（不拦截）：把 PDF/Office 等源文档归档进库时，脚本会 Warning 提示
"这属 Route 而非 Archive"——因为源文档应先进 raw/ 走编译，而不是躺进 reports/。

> ⚠️ 检查点覆盖的是本套件脚本自身的搬运动作。
> 本套件无法、也不应拦截用户手动复制/上传等库外行为——那属于操作纪律，
> 见 kit/DISTRIBUTION.md 第二节「绝对禁令」。

⛔ 适用边界：只服务新建库，不做老库诊断（强制）

本条是本技能最重要的边界，优先级高于任何"顺手检查一下"的诱惑。

能力定位

硬禁令

1. ❌ 不得用 kb_lint.py / kb_index.py 去"诊断"历史老库。
   老库建立时本套件规范尚不存在，用新规范去量它 = 跨规范误报。
   > 实测教训（务必记住）：首轮开发时用未修正的解析逻辑跑老库，报出 81 条（血氧）+ 673 条（血气）假断链。
   > 根因是解析器把 〔… #2〕 的 # 当锚点，压根不是库的问题。若当时直接拿去"修库"，会把两个健康的库改坏。
2. ❌ 不得把 kb_lint 的报错本身当作"库有质量问题"的证据。 报错先视为工具假设是否适用于该库的问题。
3. ❌ 不得对老库做任何"为通过检查"的改动。 老库的规范由老库自己的 SCHEMA.md 定义。
4. ❌ 不得因为老库"检查不过"就升级、迁移或重构该库。

允许的做法（能力积攒路径）

• ✅ 老库是规范的来源，不是规范的对象。 从老库的实战经验中提炼规则，写进 kit/（内核 / 反例库 / profiles）。
• ✅ 套件可随老库经验持续更新 —— 新规范只对未来新建的库生效，不回溯适用于老库。
• ✅ 老库可自愿采纳新规范，但必须：① 由库责任人评估；② 通过库内自己的规程修改；③ 禁止由本技能的脚本直接写库。
• ✅ 如需对老库做健康检查，走该库自有的检查脚本与 SCHEMA，不走本套件。

一句话原则

> 本套件是"新建库的模具"，不是"老库的体检仪"。
> 老库贡献经验，模具越做越好；模具不回头改已经脱模的零件。

拒诊话术模板（用户要求"顺便修一下老库"时直接复用）

> 本套件只服务新建库，不诊断历史老库。
> 老库建立时这套规范还不存在，用新规范去量它属于跨规范误报——上一轮实测报出的
> 上百条"断链"，根因在检查器，不在库（完整实测数据见本节「硬禁令 · 实测教训」）。
> 所以：① 老库的规范由它自己的 SCHEMA.md 定义，本套件不下判定；
> ② 我不会为了"让老库通过检查"而改它；
> ③ 老库的正确价值是沉淀经验 —— 我会把这些差异提炼进 kit/，只对未来新建的库生效；
> ④ 若你确实想看老库现状，我可以加 --legacy 输出差异参考（不是质量判定，也不会写库），
> 或者走该库自有的检查脚本更准。

操作

L1 · list（列出全部库）

1. 读取 Hub 根 registry.md，解析全部库条目。
2. 对每个 status=active 的库，读取其 wiki/index.md 头部与 SCHEMA.md 领域段，生成一行库签名（id / 名称 / 领域 / 页面数 / 最后更新）。
3. 用表格回给用户；dormant/archived 单列标注。

python3 "<skill>/scripts/hub_list.py"            # registry 默认取 Hub 根
python3 "<skill>/scripts/hub_list.py" --registry <path>   # 显式指定

R1 · Route（入库路由："这份资料进哪个库"）

严格按序，命中即停，禁止默认乱灌：

1. 显式指定：用户说"进血氧库/血气库/XX"→ 直接命中（支持别名）。
2. 别名/关键词匹配：按 routing-table.md，用库名、别名、领域词匹配源文件名与内容头部；命中唯一库即停。
3. 库签名判定：仍歧义时，读候选库签名摘要（index + SCHEMA 领域段），由本 agent 判断归属。
4. 兜底询问：仍不确定 → 🔴 CHECKPOINT · 🛑 STOP：列出候选库请用户选择，不得静默选择。

命中库后，内容摄取转交该库规程：先由 office-to-markdown / wiki-build-pipeline 完成提取（若源为办公文档），再按该库 SCHEMA.md 编译进其 raw/_extract/wiki。
防重复摄取：以 sources 字段 + 该库 wiki/log.md 比对源文件名与 source-id；若判定已存在 → 默认跳过并向用户报告"该源已摄入（引用已有页面）"，除非用户显式要求覆盖或补充编译。

Q1 · Query（跨库读取："查 XX 落在哪 / 跨哪"）

1. 先读 registry.md；按问题是否含别名/领域词做第一轮定向。
2. 单库明确：读该库 wiki/index.md 定位页面 → 页面级精读 → 回答带页内引用。
3. 泛问题/跨库（如"血氧项目 vs 血气竞品"）：对候选库并行读各自 index → 命中页如有 shared-entities.md 登记的跨库实体 → 联动读关联库页面。
4. 合成答案时给库级引用前缀：如 [血氧] / [血气]，跨库结论必须标注来源库。
5. 回写判定（满足全部三条才回写，否则只在对话中回答）：
   - ① 新增性：结论不在任一库现有页面中（非重复）；
   - ② 复用性：预计日后会被再次查询（非一次性问答）；
   - ③ 归属明确：能确定唯一目标库。
   三条齐备 → 按结论主体所在库的规程回写为页面（跨库双方均为主体时，分别回写两库并互相 [[kb:<id>/...]] 链接）。
   任一条不满足 → 不回写，在回答末尾提示"如需沉淀为页面请告知"。

X1 · Lint（多库体检）

执行顺序（三步，逐层递进）：

1. 库内三道闸（照旧，由各库自有脚本执行）：linkcheck / lint / orphan。
2. Hub 层检查（本套件提供，适用全部库，不涉及库内规范判定）——两款脚本分工如下，不得混用：

> ⚠️ hub_linkcheck.py 不做 registry 字段校验、不做重复源检测（v1 未实现）。需要 registry 校验请跑 hub_validate.py；重复源目前只能人工比对两库 raw/ 文件名与 source-id 字段。
> 两款脚本均逐库校验（多库 registry 全部覆盖），且除 notes 为空等 Warning 外，任一库出错即 exit 1。

3. 新建库基线自检（kb_lint.py / kb_index.py，仅对新建库）：
   断链 / 孤儿页 / frontmatter 必填缺失 / 重复标题 / 未登记标签 / index 页数一致性。

> ⛔ kb_lint.py / kb_index.py 只服务本套件新建的库（靠 SCHEMA 是否含「套件来源」标记自动识别）。
> 传入历史老库时脚本会提示并 exit 2（不执行规范判定），并提示走该库自有脚本。详见上文「适用边界」章节。
> 确需了解老库现状时加 --legacy：结果降级为"跨规范差异参考"，不构成质量判定，退出码恒为 0；
> 该模式下 kb_index --write 仍被禁止（不得由本套件改写老库）。

脚本退出码契约（用于串联流水线时判断分支）：

> 串联判据：只有 exit 0 才继续下一步；exit 2 表示"调用方式或对象不对"，需修正参数或改走其它库的脚本，不得重试同一命令。

# 新建库自检（老库会被拦截并 exit 2）
python3 "<skill>/scripts/kb_lint.py"  --kb <库id>            # 规范基线自检（L01–L10）
python3 "<skill>/scripts/kb_lint.py"  --list-checks         # 打印机器校验清单（唯一真相源）
python3 "<skill>/scripts/kb_index.py" --kb <库id> --check    # 索引一致性校验
python3 "<skill>/scripts/kb_index.py" --kb <库id> --write    # 重建索引（备份后覆盖）

# 老库仅作差异参考（不判定、不可写、恒 exit 0）
python3 "<skill>/scripts/kb_lint.py"  --kb <库id> --legacy

A1 · Archive（结论归档："这份分析结论放哪个库"）

用途：跨库检索/分析完成后产出的结论文件（HTML 报告 / MD 分析 / 导出的表格等）归档进知识库。
与 Route 的本质区别：Route 面向"待编译的源文档"（进 raw/_extract → 走 SCHEMA 编译）；Archive 面向"已完成的分析结论"——只做文件保存，禁止编译（不写 wiki/ 页面、不更新 index/log、不触碰 raw/_extract）。

流程：

1. 读取内容：读结论文件标题与内容摘要（HTML 读 <title> 与正文首段；MD 读标题与开头）。
2. 判定目标库（复用路由思路，但按"分析主题"而非"源文档类型"）：① 用户显式指定库 → 命中；② 按 routing-table 别名/领域词匹配标题与正文关键词；③ 歧义时读候选库 domain 判定"相关性最高"的库；④ 跨库对照型结论（如"血气竞品 vs 自家血氧"）若难分主次 → 🔴 CHECKPOINT · 🛑 STOP：列候选库请用户选（默认建议归档到内容占比/结论主体所在的库，但必须告知用户，不得静默）。
3. 确定落点：目标库 registry 条目 workdir 字段（相对库根，默认 reports/）。目录不存在则由归档脚本自动创建——仅建目录，不算编译。
4. 执行保存：调用 scripts/hub_archive.py <结论文件> --kb <库id> [--move]。脚本护栏：目标目录 = <库根>/<workdir> 且 workdir 不得指向 raw/_extract/wiki；重名自动加时间戳不覆盖；--move 移动源（默认复制保留源）。
5. 汇报：返回归档路径 + 一句话说明为何选该库；若选了 --move 提示源已移走。

python3 "<skill>/scripts/hub_archive.py" "D:\...\跨库对照结论.html" --kb blood-gas-analyzer
python3 "<skill>/scripts/hub_archive.py" "D:\...\TR3分析.md" --kb blood-oxygen --move

落库后不触发任何编译/索引更新——这是本操作与 Ingest 的硬边界（用户明确要求时除外）。

N1 · Init（新建知识库："我要建一个新库"）

用途：用本套件框架，在新工作空间建立一个新的 LLM-Wiki 知识库骨架（三层结构 + SCHEMA + 注册）。

前置检查（强制）：

1. ⚠️ 确认当前会话已调用专家"知识管理专家"；未调用则提示用户先添加，再继续（不得绕过）。
2. 确认库根目录位置（默认 = 新库在当前工作空间下的独立子目录，不写死绝对路径）。
   ⛔ 库根不得指向任何已登记老库目录——老库只能作为"SCHEMA 写法参照物"，不能作为 --path 目标。

流程：

1. 确认目标位置：默认建在当前工作空间目录下的新子目录；若用户指定其它位置，照用。
   若用户给出的位置落在已登记老库内 → 停下确认（不得向老库写入任何文件）。
2. 🔴 CHECKPOINT · 🛑 STOP：复述三要素并等待确认
   在动手前，把下列内容复述给用户并等其确认：
   即将新建知识库： id : <kebab-case-id> 显示名 : <名称> 库根 : <绝对路径>（确认不在任何老库目录内） 领域签名 : <一句话领域描述> 别名 : <别名1, 别名2> 确认后我先出 --dry-run 清单，再次确认才会真正写入。
3. 必须先出 --dry-run 清单（不得跳过，不得直接执行写入）：
   bash python3 "<skill>/scripts/kb_init.py" \ --id <kebab-case-id> --name "<显示名>" \ --path "<库根目录>" \ --domain "<领域签名>" --aliases "<别名1,别名2>" \ [--workspace "<当前工作空间目录>"] \ --dry-run
4. 确认清单无误后执行建库（幂等，已存在的目录/文件一律跳过，绝不覆盖）：
   bash python3 "<skill>/scripts/kb_init.py" \ --id <kebab-case-id> --name "<显示名>" \ --path "<库根目录>" \ --domain "<领域签名>" --aliases "<别名1,别名2>" \ [--workspace "<当前工作空间目录>"] \ --register --force
   - 生成：raw/ raw/_extract/ wiki/ reports/ 四层目录；
   SCHEMA.md（继承 kit/KB-SCHEMA-CORE.md 内核 + 三个生长区）；
   wiki/index.md wiki/log.md 占位；.gitignore（密级护栏）。
   - --register 时同步向 registry.md 追加条目、向 routing-table.md 插入别名占位行（均先备份）。
   - ⚠️ 未指定 --registry 时，--register 必须配 --force（防测试/误操作污染真实 Hub）。
   - --workspace 仅当路径确实在其之下时才转成 ${WORKSPACE} 变量写法，否则保留真实绝对路径并告警。
5. 验证：python3 "<skill>/scripts/hub_validate.py" 全绿（退出码 0）。
6. 后续：源文档放入 raw/ 后，按专家规程摄取编译；编译后跑 kb_index.py --write
   重建索引、kb_lint.py 体检。

示例（库根必须是新目录，⚠️ 不得填任何已登记老库路径）：

# --path 指向一个新目录（本例在工作空间下）；绝不写 "血氧开发"/"Wiki workspace" 等已登记库路径
python3 "<skill>/scripts/kb_init.py" \
  --id echem-strategy --name "电化学战略分析" \
  --path "<当前工作空间>/echem-strategy" \
  --domain "电化学产品线战略分析：市场/竞品/技术路线" --aliases "电化学战略, echem" \
  --workspace "<当前工作空间>" \
  --dry-run

> ⚠️ 老库只能作为"SCHEMA 写法参照物"（去读它的 SCHEMA.md 看规范怎么组织），
> 绝不能作为 kb_init.py --path 的目标 —— 那会把新库骨架写进老库目录。

硬边界：

• ❌ 建库只建骨架，不生成任何知识页，不代替专家做摄取编译。
• ❌ 绝不覆盖既有文件（幂等设计）。
• ❌ 不在未调用专家"知识管理专家"的情况下继续摄取。

失败模式与兜底（防呆三段式）

反例清单（不要做什么）

1. ❌ 歧义时静默选库——Route L4 / Archive 判定必须列出候选或明确询问，禁止默认乱灌。
2. ❌ 把竞品资料灌进自家项目库（反之亦然）——source 归属错误是最高频事故。
3. ❌ Hub 流程/脚本写入任何库的 wiki/、raw/、_extract/——库内编译只属于各库 SCHEMA + llm-wiki 规程。
4. ❌ Archive 后顺手"编译入库"——用户要求仅保存时，不建页、不改 index/log。
5. ❌ 物理合并/搬迁知识库——registry 只引用路径（库不搬只引用），除非用户显式要求。
6. ❌ 把不同代次/口径的实体混为一谈——如 Ucare-7000（自家）与 Ucare-6000 系（竞品）必须区分（shared-entities 口径）。
7. ❌ 未调用专家"知识管理专家"就自编摄取流程——套件只给骨架与约束，执行规程在专家内；未调用须先提示用户添加。
8. ❌ 让 raw/ 或 wiki/ 内容出本机——两者均属机密，不上传、不提交 git、不外发；分发只给 wiki-hub/ 套件。
9. ❌ 写死绝对路径——新建库用 --workspace + ${WORKSPACE} 写法，保证跨机可移植。
10. ❌ 建库时覆盖既有文件——kb_init.py 幂等设计是硬约束，已存在一律跳过。
11. ❌ 凭"链接外形"批量修链接——〔…#2〕 中的 # 是标题一部分（见 kit/ANTI-PATTERNS.md AP-03）。
12. ❌ 用本套件的 kb_lint.py / kb_index.py 去"诊断"历史老库——老库建立时本套件规范尚不存在，
    用新规范量老库 = 跨规范误报（实测数据见本文件「⛔ 适用边界 · 硬禁令」）。
    ❌ 更不得为"通过检查"而改老库。老库是规范来源，不是规范对象。
13. ❌ 因老库"检查不过"就升级/迁移/重构该库——老库规范由老库自己的 SCHEMA.md 定义。

加库流程（可扩展性核心 · 三步）

以后新增知识库（如"电化学战略分析库"），只需三步，不改任何代码：

1. 一键建库：先走 N1 · Init 流程（三要素确认 → 🔴 检查点 → --dry-run 清单 → 确认后执行）。
2. 路由：在 routing-table.md 为它补充别名/关键词映射（能唯一命中即可，可后续迭代）；
3. 验证：运行 hub_validate.py 通过，即可在 list/route/query/lint 全流程生效。

> 也可跳过 kb_init.py 手工登记：直接在 registry.md 追加条目 + routing-table.md 加别名。
> 若新库尚无 SCHEMA/index（半成型 md 目录），path 照常登记，schema/index 留空并在 notes: 标注"待补骨架"，hub_validate 按提示级放行。

## kb: <kebab-case-id>
- id: <kebab-case-id>          # 全局唯一
- name: <显示名>
- workspace: <当前工作空间目录>   # 可选；声明后 path 可用 ${WORKSPACE} 变量（推荐，换机免改）
- path: ${WORKSPACE}/<库根相对路径>   # 或写绝对路径
- schema: <相对库根的规范文件，如 SCHEMA.md>
- index: <相对库根的索引，如 wiki/index.md>
- aliases: [<逗号分隔的别名/品牌/领域词>]
- domain: <一句话领域签名（供路由判定）>
- source-id: <同源防重前缀>
- workdir: reports/          # 结论/报告归档目录（Archive 落点，默认 reports/）
- status: active              # active | dormant | archived

> 链式引用：B 库建在 A 库工作空间下时，B 的 workspace 可写 ${WORKSPACE_OF_<A库id>}/<子路径>，
> 由 hub_validate.py 递归展开（最多 8 层，自动防循环）。变量解析失败只 Warning 不 Error。

扩展与边界

• 可移植框架：kit/ 是框架本体（内核 + 模板 + 分发 + 反例 + profiles），随本技能更新而同步；
  新库加载最新 wiki-hub 即获得最新规范。存量库不自动改，需手动评审合并。
• 读取范式：v1 纯 index 导航 + 页面精读（与 llm-wiki 一致），不引入向量检索；若库/页量级上台阶，再评估为各库加语义侧道（独立增强，不改本中枢）。
• 跨库链接语法：[[kb:<库id>/<wiki内相对路径>]]，详见 references/cross-kb-links.md。
• 软联邦：shared-entities.md 登记跨库共享实体（如 Ucare-7000、POCT、pCO2），供 Query 联动；不物理合并库、不做联邦图谱/MCP（短期）。
• 安全纪律：hub 脚本与流程对任何库的 wiki 内容只读；registry/routing-table 写操作走 Write 一次性全量并先备份；绝不删除库内文件。
• 密级纪律：raw/ 与 wiki/ 内文件均不允许出本机，属于机密；分发只给套件。