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

.Knowledge/index.md

@@ -10,7 +10,7 @@
 ## 推荐阅读顺序
 
 1. `.Knowledge/manifest-routing.json`（任务路由、`topicPaths`、`topicDependencies`、`fallbackTopic`）
-2. 按需：由 `matcherPath` 读取 `.Knowledge/matchers/<id>.json`（`includeAny` 关键词）
+2. 按需：由 `matcherPath` 读取 `.Knowledge/matchers/<id>.json`（`includeAny` / `includeAll` 资格词、`excludeAny` / `excludeAll` 否决词）
 3. 按需：本 `index.md`（主题语义与边界）
 4. `.Knowledge/topics/<topic>.md`（执行约束与流程）
 5. 按需：`.Knowledge/stock-docs/`、`.Knowledge/req-docs/`
@@ -41,7 +41,7 @@
 | flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh`、DeepSeek Harness 项目技能发现与 `.dsh/` 目录适配 | 用户文档：`docs/使用说明.md` / `docs/en/usage-guide.md`；实现：`lib/dshAgentsAdapter.js` |
 | flow2spec-core-package | `.Knowledge/topics/flow2spec-core-package.md` | `@double-coding/flow2spec-core` 职责边界：核心实现、发包模板真源、原生插件 API 与 CLI/legacy shim 消费关系 | 开发者文档：`packages/core/README.md`；入口：`packages/core/index.js` |
 | flow2spec-qoder-plugin | `.Knowledge/topics/flow2spec-qoder-plugin.md` | Qoder 插件构建、`build:qoder-plugin`、zip 打包与插件市场分发 | 构建脚本：`scripts/build-qoder-plugin.js`；内容源：`packages/core/index.js`（resources API） |
-| kb-routing-summary | `.Knowledge/topics/kb-routing-summary.md` | 路由初筛 `taskToTopicRules[].summary` 字段：frontmatter 唯一手写源、kb build 机械同步、kb check 质量校验与存量修复 | 引擎：`packages/core/lib/knowledgeEngine.js`；创作规范：配置根 `rules/f2s-topic-authoring.*` |
+| kb-routing-summary | `.Knowledge/topics/kb-routing-summary.md` | 路由初筛 `taskToTopicRules[].summary` 字段与 matcher 4 字段(`includeAny`/`includeAll`/`excludeAny`/`excludeAll`)语义 | 引擎：`packages/core/lib/knowledgeEngine.js`、`packages/core/lib/routing.js`；创作规范：配置根 `rules/f2s-topic-authoring.*` |
 
 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`；**`f2s-kb-feedback-closing`** 在 cases 1–3 建议执行 **`f2s-kb-distill`**。
@@ -50,7 +50,7 @@
 
 ## 命中与执行（与统一入口一致）
 
-- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片的 `includeAny`。
+- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中,详见 `topics/kb-routing-summary.md`)。
 - **依赖**：命中主主题前，按 `topicDependencies` 先读依赖主题。
 - **兜底**：`fallbackTopic` 指向分诊主题（如 `fallback-triage`），仅低置信度上下文，**不得**当作最终命中直接改代码。
 - **执行链**：`match → expand → verify → act`；`expand` 须含依赖展开，并保留次高候选做校验。
@@ -76,7 +76,7 @@
 
 | 情况 | 你怎么做 |
 | --- | --- |
-| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
+| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补路由与 matcher 词表(`includeAny` / `includeAll` / `excludeAny` / `excludeAll`)。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
 | 配到了但不够（1b） | 走依赖与次高候选 → `verify` 点名缺哪篇文档；仍缺则向用户要路径或补 `req-docs`。 |
 | 库里没有（2） | 承认缺口 → 代码下钻或请用户补需求/方案文档。 |
 | 反复读 manifest 费 token（2a） | 同一任务线内 routing 只当快照；只读命中项的单个 matcher；不遍历整个 `matchers/` 目录枚举；`index.md` 勿与 routing 循环互刷。 |

.Knowledge/manifest-routing.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.0",
+  "version": "3.6.2",
   "knowledgeRoot": ".Knowledge",
   "matcherKey": "matcherId",
   "sourceOfTruth": ".Knowledge/manifest-routing.json",
@@ -208,11 +208,11 @@
       "topics": [
         "kb-routing-summary"
       ],
-      "summary": "初筛召回 summary 字段的同步、校验与创作规范"
+      "summary": "初筛 summary 与 matcher 分片 4 字段(资格/否决门)语义"
     }
   ],
   "projectRev": 2,
-  "pkgRev": 2,
+  "pkgRev": 3,
   "topicMetadata": {
     "implement-tech-design": {
       "primary": "policy",

.Knowledge/matchers/m-kb-routing-summary.json

@@ -11,6 +11,15 @@
     "路由 miss",
     "matcher",
     "includeAny",
+    "includeAll",
+    "excludeAny",
+    "excludeAll",
+    "matcher 字段",
+    "matcher 4 字段",
+    "否决门",
+    "资格门",
+    "路由匹配",
+    "路由字段",
     "语义锚"
   ]
 }

.Knowledge/template/index.template.md

@@ -10,7 +10,7 @@
 ## 推荐阅读顺序
 
 1. `.Knowledge/manifest-routing.json`（任务路由、`topicPaths`、`topicDependencies`、`fallbackTopic`）
-2. 按需：由 `matcherPath` 读取 `.Knowledge/matchers/<id>.json`（`includeAny` 关键词）
+2. 按需：由 `matcherPath` 读取 `.Knowledge/matchers/<id>.json`（`includeAny` / `includeAll` 资格词、`excludeAny` / `excludeAll` 否决词）
 3. 按需：本 `index.md`（主题语义与边界）
 4. `.Knowledge/topics/<topic>.md`（执行约束与流程）
 5. 按需：`.Knowledge/stock-docs/`、`.Knowledge/req-docs/`
@@ -37,7 +37,7 @@
 
 ## 命中与执行（与统一入口一致）
 
-- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片的 `includeAny`。
+- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中)。
 - **依赖**：命中主主题前，按 `topicDependencies` 先读依赖主题。
 - **兜底**：`fallbackTopic` 指向分诊主题（如 `fallback-triage`），仅低置信度上下文，**不得**当作最终命中直接改代码。
 - **执行链**：`match → expand → verify → act`；`expand` 须含依赖展开，并保留次高候选做校验。
@@ -63,7 +63,7 @@
 
 | 情况 | 你怎么做 |
 | --- | --- |
-| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
+| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补路由与 matcher 词表(`includeAny` / `includeAll` / `excludeAny` / `excludeAll`)。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
 | 配到了但不够（1b） | 走依赖与次高候选 → `verify` 点名缺哪篇文档；仍缺则向用户要路径或补 `req-docs`。 |
 | 库里没有（2） | 承认缺口 → 代码下钻或请用户补需求/方案文档。 |
 | 反复读 manifest 费 token（2a） | 同一任务线内 routing 只当快照；只读命中项的单个 matcher；不遍历整个 `matchers/` 目录枚举；`index.md` 勿与 routing 循环互刷。 |

.Knowledge/topics/kb-routing-summary.md

@@ -1,7 +1,7 @@
 ---
 id: kb-routing-summary
-revision: 0
-summary: "初筛召回 summary 字段的同步、校验与创作规范"
+revision: 2
+summary: "初筛 summary 与 matcher 分片 4 字段(资格/否决门)语义"
 primary: feature
 confidence: manual
 ---
@@ -29,6 +29,29 @@ confidence: manual
 - 存量修复走 `f2s-kb-upgrade` 完整流程步骤 3a.7 / 3a.8：`kb build --fix-topics` 补占位头部 → `kb check --strict` 报 summary warning → agent 逐个 Read 正文补写语义摘要 → `kb build` 同步进 `rule.summary`。
 - `f2s-kb-upgrade` 步骤 -1 的 A 分支（包侧均为最新）**不得直接停止**：须先做项目侧对齐检查（manifest `version`/`pkgRev` 对比包 Template Version + `kb check --strict`），未对齐视同 Template 更新转完整流程；否则刚升完包的老项目会被误判「无事可做」跳过 summary 补写。
 
+## matcher 分片字段语义
+
+matcher 分片(`.Knowledge/matchers/<id>.json`)有 4 个字段参与路由匹配,按「否决门(恒胜) → 资格门(OR ∪ AND)」两级判定:
+
+- **资格门**(至少满足其一才进入候选):
+  - `includeAny`:任一短语命中(OR)——最常用
+  - `includeAll`:所有短语全部命中(AND)——表达组合词
+- **否决门**(任一门命中则整条规则出局,**优先于 `task` 精确命中**):
+  - `excludeAny`:任一短语命中(OR)
+  - `excludeAll`:所有短语全部命中(AND)——半命中不否决
+
+否决优先于 `task` 精确命中:排除词表达「此请求不属于该任务域」,语义上比精确命中更强。存量分片(仅有 `includeAny`)行为不变。
+
+字段写作规范(何时用 AND / 什么时候上排除词 / 与 12 词阈值的关系)见 `rules/f2s-topic-authoring` 「matcher 分片字段语义」一节。实现:`packages/core/lib/routing.js:match()`;契约测试:`scripts/test-routing-semantics.js`。
+
+### 4 字段填充机制(按需人写,引擎不生成)
+
+- `includeAll` / `excludeAny` / `excludeAll` **无自动填充**——引擎只做透传:`normalizeDeltaMatcher` 在 `kb apply` 写盘时保留 delta 已带字段,`kb build` 不动 matcher 分片,`flow2spec init` 分发的默认分片模板也只有 `includeAny`。
+- 赋值的**唯一路径**:用户遇到误路由 / AND 组合词需求 → Agent 依 `f2s-topic-authoring` §3 写作准则手写进对应 `matchers/<id>.json`(或用户直接手工编辑)。
+- **无 skill 会主动生成这 3 个字段**——即便用户描述含"排除/避免命中"语义,也需 Agent 观察 + 判断 + 手写,不是自动流程。
+- 定位:**逃生舱,不是默认装备**——大部分主题只用 `includeAny` 就够,git 全历史至本次同步前,生产分片对这 3 字段的赋值次数为 **0**。
+- 后续演进见 [issue #56](https://github.com/double-coding-lab/Flow2Spec/issues/56)(半自动填充能力备忘)。
+
 ## 边界
 
 - `task` 字段保持稳定 id 语义（kb 引擎按 `task` 合并规则），不承载召回语义。