📚 docs(kb): 同步 matcher 4 字段(includeAll/excludeAny/excludeAll)完整语义与填充机制

[Lands-1203]

背景

PR #55 让 packages/core/lib/routing.js:match() 完整消费 matcher 4 字段(includeAny / includeAll / excludeAny / excludeAll),但 Flow2Spec 有两条并行的匹配路径:

• 公共 API 侧(routing.match()):PR 🐛 fix(core): matcher includeAll/excludeAny/excludeAll 字段在路由匹配中生效 #55 已修好 ✅
• Agent 侧(读规则文档自己判):Agent 只看规则文档,规则文档若还写「关键词 = includeAny」,Agent 就依然只会用 includeAny

扫盘发现本仓 Agent 侧规则(.claude / .cursor / .codex + Core templates 真源) + 知识库(.Knowledge/topics / .Knowledge/index.md)共 7 处仍是 includeAny 单字段口径。不补,Agent 拿到的说明书就还是过期的,新能力对它是隐藏功能。

本 PR 追认 PR #55 的能力,补齐 Agent 侧说明书,让两条路径口径一致。

改动范围

知识库(本仓 .Knowledge/)

• topics/kb-routing-summary.md:revision 0 → 2,新增两节
  • 「matcher 分片字段语义」:4 字段判定门 + 否决优先于 task 精确命中 + 存量兼容
  • 「4 字段填充机制」:引擎不生成 / 无 skill 自动填 / 唯一路径是按需人写 / 生产分片 0 次赋值
• index.md:3 处 includeAny 单字段口径改为 4 字段;topic 简介同步
• matchers/m-kb-routing-summary.json:includeAny 补 9 个新召回词(includeAll / excludeAny / excludeAll / matcher 字段 / matcher 4 字段 / 否决门 / 资格门 / 路由匹配 / 路由字段)
• manifest-routing.json:taskToTopicRules[kb-routing-summary].summary 由 kb build 从 topic frontmatter 机械同步

本仓规则(三端手写镜像)

• .claude/rules/f2s-topic-authoring.md:新增 §3「matcher 分片字段语义」写作准则(何时用 AND / 何时上排除词 / 阈值提示 / 打分池合并);原编号顺移,内部引用更新
• .claude/rules/f2s-flow2spec-unified-entry.md:读取顺序 / matcherPath 字段项 / 缺口处理表 三处口径改 4 字段
• .cursor/rules/*.mdc:同上镜像
• .codex/topics/*.md:同上镜像

Core templates 真源(下游 flow2spec init 分发用)

• 新建 packages/core/templates/{zh-CN,en-US}/knowledge/topics/kb-routing-summary.md(双语)
• packages/core/templates/{zh-CN,en-US}/rules/f2s-topic-authoring.md:同本仓改动
• packages/core/templates/{zh-CN,en-US}/rules/f2s-flow2spec-unified-entry.md:同本仓改动
• packages/core/templates/{zh-CN,en-US}/knowledge/index.md:同本仓改动

顺带同步(npm run sync:agents 分发产物)

同 commit 内包含少量 hooks / kb-* skill 镜像的例行同步(用户明确执行过 npm run sync:agents)。

自检门禁(全绿)

• ✅ flow2spec kb check --strict = knowledge check: ok / topics: 20 / routing drift: no
• ✅ npm run version:check = CLI 3.6.2 / Core 3.7.2 / Template 3.6.2 / Protocol 2 一致
• ✅ npm test 15 个脚本全绿(含 routing semantics tests passed)

兼容性

• 无代码改动,零运行时影响
• 存量 matcher 分片(仅有 includeAny)行为不变
• Template Version 未升(改动为「补文档、追认已有语义」)。若视为「打开下游写作能力窗口」,后续再走 npm run version:set:template 单独发一次;当前不阻塞

相关

• 修复 PR:🐛 fix(core): matcher includeAll/excludeAny/excludeAll 字段在路由匹配中生效 #55(routing.match 消费 4 字段)
• 原始 Bug:【Bug】matcher 的 includeAll / excludeAny / excludeAll 字段已在 schema 定义，但 routing.match() 未消费 #54(schema 定义 4 字段但只消费 1 个)
• 后续演进:【备忘】matcher 3 字段(includeAll/excludeAny/excludeAll)半自动填充能力 #56(半自动填充能力备忘)