From 324e5db5319401399da75752495f7842bf3c2312 Mon Sep 17 00:00:00 2001 From: liguochuan <292761894@qq.com> Date: Fri, 28 Aug 2026 11:53:50 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=80=20feat(kb):=20=E8=B7=AF=E7=94=B1?= =?UTF-8?q?=E5=88=9D=E7=AD=9B=20summary=20=E5=8F=AC=E5=9B=9E=E9=94=9A?= =?UTF-8?q?=E4=B8=8E=E8=B4=A8=E9=87=8F=E6=A0=A1=E9=AA=8C=EF=BC=88Core=203.?= =?UTF-8?q?7.0=20/=20CLI=203.6.1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Core knowledgeEngine：topic frontmatter summary 同步进 taskToTopicRules[].summary（build/apply/status 三点位）；kb check 新增缺失/占位/超长 warning 与 rule.summary 类型 issue - CLI：kb check 文本输出打印前 10 条 warning 明细 - 模板（zh+en，Template 3.6.0 / projectRev 3）：manifest rule 定稿 summary；统一入口初筛证据 + verify 错命中闸门；topic-authoring 初筛召回规范；addRules/kb-build/kb-sync/kb-distill 对齐；feedback-closing 路由 miss 反哺；kb-upgrade 3a.8 summary 补写 - 本仓 .Knowledge：13 个占位摘要补写 + 新增 kb-routing-summary topic - 测试：summary 同步断言；test-cli-update/test-package-install 版本断言动态化 - 版本：Core 3.7.0、CLI 3.6.1（core range ^3.6.0 不变） --- .Knowledge/index.md | 1 + .Knowledge/manifest-routing.json | 70 ++++++++++++----- .Knowledge/matchers/m-kb-routing-summary.json | 16 ++++ .Knowledge/topics/f2s-config-precheck.md | 2 +- .Knowledge/topics/f2s-fallback-triage.md | 2 +- .Knowledge/topics/f2s-flow2spec-milestones.md | 2 +- .../topics/f2s-flow2spec-presentations.md | 2 +- .Knowledge/topics/f2s-git-commit.md | 2 +- .../topics/f2s-implement-tech-design.md | 2 +- .Knowledge/topics/f2s-init-defaults.md | 2 +- .Knowledge/topics/f2s-req-plan.md | 2 +- .Knowledge/topics/f2s-req-tech.md | 2 +- .../topics/f2s-stock-docs-vs-req-docs.md | 2 +- .Knowledge/topics/f2s-task.md | 2 +- .Knowledge/topics/flow2spec-qoder-plugin.md | 2 +- .Knowledge/topics/kb-routing-summary.md | 41 ++++++++++ .Knowledge/topics/skill-authoring.md | 2 +- package-lock.json | 4 +- packages/cli/cli.js | 3 + packages/cli/package.json | 2 +- packages/core/lib/knowledgeEngine.js | 75 ++++++++++++++++++- packages/core/package.json | 4 +- .../en-US/knowledge/manifest-routing.json | 26 ++++--- .../knowledge/topics/f2s-config-precheck.md | 2 +- .../knowledge/topics/f2s-fallback-triage.md | 2 +- .../topics/f2s-implement-tech-design.md | 2 +- .../en-US/knowledge/topics/f2s-req-plan.md | 2 +- .../topics/f2s-stock-docs-vs-req-docs.md | 2 +- .../en-US/knowledge/topics/f2s-task.md | 2 +- .../rules/f2s-flow2spec-unified-entry.md | 7 +- .../en-US/rules/f2s-kb-feedback-closing.md | 6 ++ .../en-US/rules/f2s-topic-authoring.md | 9 +++ .../en-US/skills/f2s-kb-addRules/SKILL.md | 2 +- .../en-US/skills/f2s-kb-build/SKILL.md | 3 +- .../en-US/skills/f2s-kb-distill/SKILL.md | 6 +- .../en-US/skills/f2s-kb-sync/SKILL.md | 2 +- .../en-US/skills/f2s-kb-upgrade/SKILL.md | 6 +- .../zh-CN/knowledge/manifest-routing.json | 26 ++++--- .../knowledge/topics/f2s-config-precheck.md | 2 +- .../knowledge/topics/f2s-fallback-triage.md | 2 +- .../topics/f2s-implement-tech-design.md | 2 +- .../zh-CN/knowledge/topics/f2s-req-plan.md | 2 +- .../topics/f2s-stock-docs-vs-req-docs.md | 2 +- .../zh-CN/knowledge/topics/f2s-task.md | 2 +- .../rules/f2s-flow2spec-unified-entry.md | 7 +- .../zh-CN/rules/f2s-kb-feedback-closing.md | 6 ++ .../zh-CN/rules/f2s-topic-authoring.md | 9 +++ .../zh-CN/skills/f2s-kb-addRules/SKILL.md | 2 +- .../zh-CN/skills/f2s-kb-build/SKILL.md | 3 +- .../zh-CN/skills/f2s-kb-distill/SKILL.md | 6 +- .../zh-CN/skills/f2s-kb-sync/SKILL.md | 2 +- .../zh-CN/skills/f2s-kb-upgrade/SKILL.md | 6 +- scripts/test-cli-update.js | 31 ++++++-- scripts/test-knowledge-engine.js | 6 ++ scripts/test-package-install.js | 3 +- 55 files changed, 343 insertions(+), 97 deletions(-) create mode 100644 .Knowledge/matchers/m-kb-routing-summary.json create mode 100644 .Knowledge/topics/kb-routing-summary.md diff --git a/.Knowledge/index.md b/.Knowledge/index.md index 0caf550..57c1edd 100644 --- a/.Knowledge/index.md +++ b/.Knowledge/index.md @@ -41,6 +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.*` | 每主题保留 **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`**。 diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index c39addc..f5ceecb 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -34,7 +34,8 @@ "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md", "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md", "flow2spec-core-package": ".Knowledge/topics/flow2spec-core-package.md", - "flow2spec-qoder-plugin": ".Knowledge/topics/flow2spec-qoder-plugin.md" + "flow2spec-qoder-plugin": ".Knowledge/topics/flow2spec-qoder-plugin.md", + "kb-routing-summary": ".Knowledge/topics/kb-routing-summary.md" }, "taskToTopicRules": [ { @@ -43,7 +44,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", "topics": [ "config-precheck" - ] + ], + "summary": "f2s 技能执行前必读 flow2spec.config.json 的开关口径" }, { "task": "implement-from-spec", @@ -52,7 +54,8 @@ "topics": [ "f2s-doc-routing", "implement-tech-design" - ] + ], + "summary": "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪；按技术方案/需求文档实现代码的流程与门禁" }, { "task": "doc-routing", @@ -60,7 +63,8 @@ "matcherPath": ".Knowledge/matchers/m-doc-routing.json", "topics": [ "f2s-doc-routing" - ] + ], + "summary": "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪" }, { "task": "change-tracking", @@ -68,7 +72,8 @@ "matcherPath": ".Knowledge/matchers/m-change-tracking.json", "topics": [ "f2s-task" - ] + ], + "summary": "任务清单 .task 目录的创建、续作与归档规则" }, { "task": "req-plan", @@ -76,7 +81,8 @@ "matcherPath": ".Knowledge/matchers/m-req-plan.json", "topics": [ "f2s-req-plan" - ] + ], + "summary": "需求/变更的任务规划拆解与并行实现流程" }, { "task": "flow2spec-dsh-adapter", @@ -84,7 +90,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", "topics": [ "flow2spec-dsh-adapter" - ] + ], + "summary": "DeepSeek Harness 项目级技能初始化与目录适配" }, { "task": "git-commit", @@ -92,7 +99,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-git-commit.json", "topics": [ "f2s-git-commit" - ] + ], + "summary": "Git 提交流程：变更检查、提交信息生成与知识库覆盖检查" }, { "task": "flow2spec-presentations", @@ -100,7 +108,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-presentations.json", "topics": [ "flow2spec-presentations" - ] + ], + "summary": "对外网站与 HTML 演示稿的位置、预览与维护边界" }, { "task": "flow2spec-milestones", @@ -108,7 +117,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-milestones.json", "topics": [ "flow2spec-milestones" - ] + ], + "summary": "Flow2Spec 产品自身的版本演进与里程碑时间线" }, { "task": "skill-authoring", @@ -116,7 +126,8 @@ "matcherPath": ".Knowledge/matchers/m-skill-authoring.json", "topics": [ "skill-authoring" - ] + ], + "summary": "本仓 f2s-* SKILL 的小标题命名与排列顺序规范" }, { "task": "req-tech", @@ -124,7 +135,8 @@ "matcherPath": ".Knowledge/matchers/m-req-tech.json", "topics": [ "f2s-req-tech" - ] + ], + "summary": "基于需求与知识库生成技术方案文档，落盘 req-docs" }, { "task": "dev-workflow-constraints", @@ -132,7 +144,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-dev-workflow-constraints.json", "topics": [ "f2s-dev-workflow-constraints" - ] + ], + "summary": "Flow2Spec 本仓的模板真源、配置根、版本发布与分发边界" }, { "task": "kb-distill", @@ -140,7 +153,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-kb-distill.json", "topics": [ "f2s-kb-distill" - ] + ], + "summary": "f2s-kb-distill：Q&A 驱动知识提取与入库" }, { "task": "flow2spec-init-defaults", @@ -148,7 +162,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-init-defaults.json", "topics": [ "flow2spec-init-defaults" - ] + ], + "summary": "init 写入 flow2spec.config.json 的默认值与字段语义" }, { "task": "flow2spec-collaboration", @@ -156,7 +171,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-collaboration.json", "topics": [ "flow2spec-collaboration" - ] + ], + "summary": "任务状态本地隔离、共享知识 delta 合入与 revision 冲突处理" }, { "task": "flow2spec-doctor", @@ -164,7 +180,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-doctor.json", "topics": [ "flow2spec-doctor" - ] + ], + "summary": "只读检查 Flow2Spec 环境、初始化、协作上下文与知识库健康" }, { "task": "flow2spec-core-package", @@ -172,7 +189,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-core-package.json", "topics": [ "flow2spec-core-package" - ] + ], + "summary": "Core/CLI 所有权、公共 API、独立版本、独立发布与更新兼容契约" }, { "task": "flow2spec-qoder-plugin", @@ -180,7 +198,17 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-qoder-plugin.json", "topics": [ "flow2spec-qoder-plugin" - ] + ], + "summary": "Qoder 插件的构建、zip 打包与插件市场分发" + }, + { + "task": "kb-routing-summary", + "matcherId": "m-kb-routing-summary", + "matcherPath": ".Knowledge/matchers/m-kb-routing-summary.json", + "topics": [ + "kb-routing-summary" + ], + "summary": "初筛召回 summary 字段的同步、校验与创作规范" } ], "projectRev": 2, @@ -279,6 +307,10 @@ "tags": [ "module" ] + }, + "kb-routing-summary": { + "primary": "feature", + "confidence": "manual" } } } diff --git a/.Knowledge/matchers/m-kb-routing-summary.json b/.Knowledge/matchers/m-kb-routing-summary.json new file mode 100644 index 0000000..84772a9 --- /dev/null +++ b/.Knowledge/matchers/m-kb-routing-summary.json @@ -0,0 +1,16 @@ +{ + "id": "m-kb-routing-summary", + "version": "1.0.0", + "schema": "flow2spec.matcher.v1", + "includeAny": [ + "summary", + "初筛", + "召回", + "路由摘要", + "命中率", + "路由 miss", + "matcher", + "includeAny", + "语义锚" + ] +} diff --git a/.Knowledge/topics/f2s-config-precheck.md b/.Knowledge/topics/f2s-config-precheck.md index 4d617a1..2236af5 100644 --- a/.Knowledge/topics/f2s-config-precheck.md +++ b/.Knowledge/topics/f2s-config-precheck.md @@ -1,7 +1,7 @@ --- id: config-precheck revision: 0 -summary: "config-precheck（路由摘要）" +summary: "f2s 技能执行前必读 flow2spec.config.json 的开关口径" primary: config confidence: manual tags: [policy] diff --git a/.Knowledge/topics/f2s-fallback-triage.md b/.Knowledge/topics/f2s-fallback-triage.md index a186210..aad160c 100644 --- a/.Knowledge/topics/f2s-fallback-triage.md +++ b/.Knowledge/topics/f2s-fallback-triage.md @@ -1,7 +1,7 @@ --- id: fallback-triage revision: 0 -summary: fallback-triage +summary: "路由未命中时的兜底分诊与补召回流程" primary: policy confidence: manual --- diff --git a/.Knowledge/topics/f2s-flow2spec-milestones.md b/.Knowledge/topics/f2s-flow2spec-milestones.md index dcc6e47..4dc9c7d 100644 --- a/.Knowledge/topics/f2s-flow2spec-milestones.md +++ b/.Knowledge/topics/f2s-flow2spec-milestones.md @@ -1,7 +1,7 @@ --- id: flow2spec-milestones revision: 1 -summary: flow2spec-milestones +summary: "Flow2Spec 产品自身的版本演进与里程碑时间线" primary: feature confidence: inferred --- diff --git a/.Knowledge/topics/f2s-flow2spec-presentations.md b/.Knowledge/topics/f2s-flow2spec-presentations.md index 1043fb5..0c481aa 100644 --- a/.Knowledge/topics/f2s-flow2spec-presentations.md +++ b/.Knowledge/topics/f2s-flow2spec-presentations.md @@ -1,7 +1,7 @@ --- id: flow2spec-presentations revision: 0 -summary: flow2spec-presentations +summary: "对外网站与 HTML 演示稿的位置、预览与维护边界" primary: feature confidence: inferred --- diff --git a/.Knowledge/topics/f2s-git-commit.md b/.Knowledge/topics/f2s-git-commit.md index 6ef7714..3b2fb86 100644 --- a/.Knowledge/topics/f2s-git-commit.md +++ b/.Knowledge/topics/f2s-git-commit.md @@ -1,7 +1,7 @@ --- id: f2s-git-commit revision: 0 -summary: "f2s-git-commit（路由摘要）" +summary: "Git 提交流程：变更检查、提交信息生成与知识库覆盖检查" primary: policy confidence: manual --- diff --git a/.Knowledge/topics/f2s-implement-tech-design.md b/.Knowledge/topics/f2s-implement-tech-design.md index 2479f3a..feac332 100644 --- a/.Knowledge/topics/f2s-implement-tech-design.md +++ b/.Knowledge/topics/f2s-implement-tech-design.md @@ -1,7 +1,7 @@ --- id: implement-tech-design revision: 0 -summary: "implement-tech-design（路由摘要）" +summary: "按技术方案/需求文档实现代码的流程与门禁" dependsOn: [f2s-doc-routing] primary: policy confidence: manual diff --git a/.Knowledge/topics/f2s-init-defaults.md b/.Knowledge/topics/f2s-init-defaults.md index ba13519..bdf7303 100644 --- a/.Knowledge/topics/f2s-init-defaults.md +++ b/.Knowledge/topics/f2s-init-defaults.md @@ -1,7 +1,7 @@ --- id: flow2spec-init-defaults revision: 2 -summary: "flow2spec-init-defaults（路由摘要）" +summary: "init 写入 flow2spec.config.json 的默认值与字段语义" primary: config confidence: inferred tags: [policy] diff --git a/.Knowledge/topics/f2s-req-plan.md b/.Knowledge/topics/f2s-req-plan.md index fee78cf..de2d151 100644 --- a/.Knowledge/topics/f2s-req-plan.md +++ b/.Knowledge/topics/f2s-req-plan.md @@ -1,7 +1,7 @@ --- id: f2s-req-plan revision: 0 -summary: "f2s-req-plan（路由摘要）" +summary: "需求/变更的任务规划拆解与并行实现流程" dependsOn: [f2s-task] primary: policy confidence: manual diff --git a/.Knowledge/topics/f2s-req-tech.md b/.Knowledge/topics/f2s-req-tech.md index 1432c26..e9954cb 100644 --- a/.Knowledge/topics/f2s-req-tech.md +++ b/.Knowledge/topics/f2s-req-tech.md @@ -1,7 +1,7 @@ --- id: f2s-req-tech revision: 0 -summary: "f2s-req-tech（路由摘要）" +summary: "基于需求与知识库生成技术方案文档，落盘 req-docs" primary: policy confidence: inferred --- diff --git a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md index 19ae76b..bd9bd48 100644 --- a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md +++ b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md @@ -1,7 +1,7 @@ --- id: f2s-doc-routing revision: 0 -summary: "f2s-doc-routing（路由摘要）" +summary: "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪" primary: policy confidence: manual --- diff --git a/.Knowledge/topics/f2s-task.md b/.Knowledge/topics/f2s-task.md index ed13c47..1d4726e 100644 --- a/.Knowledge/topics/f2s-task.md +++ b/.Knowledge/topics/f2s-task.md @@ -1,7 +1,7 @@ --- id: f2s-task revision: 0 -summary: "f2s-task（路由摘要）" +summary: "任务清单 .task 目录的创建、续作与归档规则" primary: policy confidence: manual --- diff --git a/.Knowledge/topics/flow2spec-qoder-plugin.md b/.Knowledge/topics/flow2spec-qoder-plugin.md index 1a35dd1..3e6187d 100644 --- a/.Knowledge/topics/flow2spec-qoder-plugin.md +++ b/.Knowledge/topics/flow2spec-qoder-plugin.md @@ -1,7 +1,7 @@ --- id: flow2spec-qoder-plugin revision: 2 -summary: "Qoder 原生插件构建：从 Core 全量生成 skills/rules/hooks 并打包 zip" +summary: "Qoder 插件的构建、zip 打包与插件市场分发" primary: feature confidence: inferred tags: [module] diff --git a/.Knowledge/topics/kb-routing-summary.md b/.Knowledge/topics/kb-routing-summary.md new file mode 100644 index 0000000..f577ce7 --- /dev/null +++ b/.Knowledge/topics/kb-routing-summary.md @@ -0,0 +1,41 @@ +--- +id: kb-routing-summary +revision: 0 +summary: "初筛召回 summary 字段的同步、校验与创作规范" +primary: feature +confidence: manual +--- +# 路由初筛 summary 字段（初筛召回锚） + +## 适用场景 + +路由初筛命中率、`taskToTopicRules[].summary` 字段语义、rule.summary 同步机制、路由 miss 排查、summary/includeAny 创作与校验问题。 + +## 机制 + +- `taskToTopicRules[].summary` 是初筛阶段的常驻语义锚；初筛证据 = `task` 名 + `summary` + topic id + 依赖 + metadata（`includeAny` 仅在命中后打开的 matcher 分片中）。 +- **唯一手写源 = topic frontmatter `summary`**；manifest 侧由 `kb build` 经 `normalizeRoutingWithGraph` 机械同步：多 topic 规则按全角「；」拼接，topic 无 summary 时保留规则既有值不清空。 +- 同步点位复用：`kb build` / `kb apply` / `kb status`（drift 检测）三点位走同一函数；手改 manifest 的 `rule.summary` 会被判 routing drift。 + +## 质量校验（kb check） + +- **warning**（`--strict` 才影响结果）：summary 缺失；占位（`（路由摘要）` / `routing summary` / TODO / TBD / 待补充 / 占位 / 与 topicId 相同）；超长（含 CJK 时 > 40 字符，纯英文 > 20 词）。 +- **issue**（直接失败）：`rule.summary` 非字符串。 +- CLI `kb check` 文本输出打印前 10 条 warning 明细。 + +## 创作与存量修复 + +- 写法规范（软 30 字 / 硬 40 字、职责 + 用户会问的核心名词、`includeAny` 单概念词优先、落盘前模拟问句自测）以 `f2s-topic-authoring`「初筛召回规范」为准，本 topic 不复述。 +- 存量修复走 `f2s-kb-upgrade` 完整流程步骤 3a.7 / 3a.8：`kb build --fix-topics` 补占位头部 → `kb check --strict` 报 summary warning → agent 逐个 Read 正文补写语义摘要 → `kb build` 同步进 `rule.summary`。 + +## 边界 + +- `task` 字段保持稳定 id 语义（kb 引擎按 `task` 合并规则），不承载召回语义。 +- 禁止手写 manifest 的 `rule.summary`，一律由 `kb build` 生成。 +- verify 错命中闸门（命中正文未覆盖问句核心名词时并读次高候选）属统一入口规则条文，见 `rules/f2s-flow2spec-unified-entry`。 + +## 实现位置 + +- 引擎：`packages/core/lib/knowledgeEngine.js`（`deriveRoutingOverlayFromGraph.topicSummaries`、`normalizeRoutingWithGraph`、`validateKnowledgeGraph` 的 summary 校验）。 +- CLI：`packages/cli/cli.js` kb check 的 warning 明细输出。 +- 模板：Template 3.6.0 / projectRev 3 起，双语言 manifest 与 7 个 topic 均带定稿 summary。 diff --git a/.Knowledge/topics/skill-authoring.md b/.Knowledge/topics/skill-authoring.md index 4782430..ca5bba8 100644 --- a/.Knowledge/topics/skill-authoring.md +++ b/.Knowledge/topics/skill-authoring.md @@ -1,7 +1,7 @@ --- id: skill-authoring revision: 0 -summary: "skill-authoring（路由摘要）" +summary: "本仓 f2s-* SKILL 的小标题命名与排列顺序规范" primary: policy confidence: inferred --- diff --git a/package-lock.json b/package-lock.json index de76c19..18b71de 100644 --- a/package-lock.json +++ b/package-lock.json @@ -25,7 +25,7 @@ }, "packages/cli": { "name": "@double-coding/flow2spec", - "version": "3.6.0", + "version": "3.6.1", "license": "ISC", "dependencies": { "@double-coding/flow2spec-core": "^3.6.0" @@ -39,7 +39,7 @@ }, "packages/core": { "name": "@double-coding/flow2spec-core", - "version": "3.6.0", + "version": "3.7.0", "license": "ISC", "engines": { "node": ">=16" diff --git a/packages/cli/cli.js b/packages/cli/cli.js index 9924d8a..022fb98 100755 --- a/packages/cli/cli.js +++ b/packages/cli/cli.js @@ -526,6 +526,9 @@ if (sub === "kb") { } if (result.warnings.length) { console.log(`warnings: ${result.warnings.length}`); + for (const warning of result.warnings.slice(0, 10)) { + console.log(`- ${warning}`); + } } } process.exit(result.ok ? 0 : 1); diff --git a/packages/cli/package.json b/packages/cli/package.json index a551244..2da41a2 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@double-coding/flow2spec", - "version": "3.6.0", + "version": "3.6.1", "description": "在业务仓库初始化文档驱动、可写回知识库的 AI 协作骨架", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { diff --git a/packages/core/lib/knowledgeEngine.js b/packages/core/lib/knowledgeEngine.js index 0bf2cc4..aacc683 100644 --- a/packages/core/lib/knowledgeEngine.js +++ b/packages/core/lib/knowledgeEngine.js @@ -19,6 +19,29 @@ const ALLOWED_TOPIC_PRIMARY = new Set(["policy", "config", "feature", "module"]) const ALLOWED_TOPIC_CONFIDENCE = new Set(["manual", "inferred"]); const TOPIC_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/; const MATCHER_ID_RE = /^m-[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/; +// topic summary 作为初筛召回字段的质量约束：含 CJK 按字符数上限 40，纯英文按词数上限 20。 +const SUMMARY_CJK_RE = /[\u3400-\u9fff\uf900-\ufaff]/; +const SUMMARY_MAX_CJK_CHARS = 40; +const SUMMARY_MAX_WORDS = 20; +const SUMMARY_PLACEHOLDER_RE = /^(todo|tbd|待补充|占位)/i; + +function isPlaceholderSummary(summary, topicId) { + const value = String(summary || "").trim(); + if (!value) return false; + if (value === topicId) return true; + if (value.includes("路由摘要")) return true; + if (/routing summary/i.test(value)) return true; + return SUMMARY_PLACEHOLDER_RE.test(value); +} + +function isSummaryTooLong(summary) { + const value = String(summary || "").trim(); + if (!value) return false; + if (SUMMARY_CJK_RE.test(value)) { + return Array.from(value).length > SUMMARY_MAX_CJK_CHARS; + } + return value.split(/\s+/).filter(Boolean).length > SUMMARY_MAX_WORDS; +} function ensureDir(dir) { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); @@ -333,9 +356,15 @@ function loadKnowledgeGraph(cwd) { function deriveRoutingOverlayFromGraph(graph) { const topicMetadata = {}; const topicDependencies = {}; + const topicSummaries = {}; for (const topic of graph.topics) { if (!topic.exists) continue; const fm = topic.frontmatter || {}; + const summary = + typeof fm.summary === "string" ? fm.summary.trim() : ""; + if (summary) { + topicSummaries[topic.topicId] = summary; + } const entry = {}; if (Object.prototype.hasOwnProperty.call(fm, "primary")) { const primary = String(fm.primary || "").trim(); @@ -364,7 +393,7 @@ function deriveRoutingOverlayFromGraph(graph) { topicDependencies[topic.topicId] = normalizeStringArray(fm.dependsOn); } } - return { topicMetadata, topicDependencies }; + return { topicMetadata, topicDependencies, topicSummaries }; } function normalizeRoutingWithGraph(graph) { @@ -409,6 +438,23 @@ function normalizeRoutingWithGraph(graph) { changed = true; } } + // taskToTopicRules[].summary：初筛召回字段，唯一手写源为 topic frontmatter summary， + // 此处机械同步（多 topic 规则按“；”拼接）；topic 无 summary 时保留规则既有值不清空。 + if (Array.isArray(next.taskToTopicRules)) { + next.taskToTopicRules = next.taskToTopicRules.map((rule) => { + if (!rule || typeof rule !== "object" || !Array.isArray(rule.topics)) { + return rule; + } + const parts = rule.topics + .map((topicId) => overlay.topicSummaries[topicId]) + .filter(Boolean); + if (parts.length === 0) return rule; + const summary = parts.join("；"); + if (rule.summary === summary) return rule; + changed = true; + return { ...rule, summary }; + }); + } return { routing: next, changed }; } @@ -474,6 +520,25 @@ function validateKnowledgeGraph(graph, options = {}) { } } } + // summary 质量：仅 warning（不阻断旧项目）；--strict 时才影响 check 结果。 + const summaryValue = + typeof fm.summary === "string" ? fm.summary.trim() : ""; + if (!summaryValue) { + warnings.push( + `topic summary missing (初筛召回依赖此字段，建议补写): ${topic.topicId}`, + ); + } else { + if (isPlaceholderSummary(summaryValue, topic.topicId)) { + warnings.push( + `topic summary placeholder (需改写为含核心名词的一句话): ${topic.topicId} -> ${summaryValue}`, + ); + } + if (isSummaryTooLong(summaryValue)) { + warnings.push( + `topic summary too long (上限 ${SUMMARY_MAX_CJK_CHARS} 字 / ${SUMMARY_MAX_WORDS} 词): ${topic.topicId}`, + ); + } + } } if (!routing.topicPaths || typeof routing.topicPaths !== "object") { @@ -558,6 +623,14 @@ function validateKnowledgeGraph(graph, options = {}) { if (!rule.task || typeof rule.task !== "string") { issues.push("taskToTopicRules entry missing task"); } + if ( + Object.prototype.hasOwnProperty.call(rule, "summary") && + typeof rule.summary !== "string" + ) { + issues.push( + `taskToTopicRules(${rule.task || "unknown"}) summary must be a string`, + ); + } if (!Array.isArray(rule.topics) || rule.topics.length === 0) { issues.push(`taskToTopicRules(${rule.task || "unknown"}) must contain topics`); } else { diff --git a/packages/core/package.json b/packages/core/package.json index d267a94..15cc401 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,7 +1,7 @@ { "name": "@double-coding/flow2spec-core", - "version": "3.6.0", - "templateVersion": "3.5.0", + "version": "3.7.0", + "templateVersion": "3.6.0", "description": "Flow2Spec Core APIs, knowledge engine, project initialization and shared resources", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { diff --git a/packages/core/templates/en-US/knowledge/manifest-routing.json b/packages/core/templates/en-US/knowledge/manifest-routing.json index b2e80e3..764adc0 100644 --- a/packages/core/templates/en-US/knowledge/manifest-routing.json +++ b/packages/core/templates/en-US/knowledge/manifest-routing.json @@ -1,6 +1,6 @@ { - "version": "3.5.0", - "projectRev": 2, + "version": "3.6.0", + "projectRev": 3, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", "sourceOfTruth": ".Knowledge/manifest-routing.json", @@ -44,7 +44,9 @@ "flow2spec-dsh-adapter": { "primary": "feature", "confidence": "inferred", - "tags": ["module"] + "tags": [ + "module" + ] } }, "topicPaths": { @@ -63,7 +65,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", "topics": [ "config-precheck" - ] + ], + "summary": "Read flow2spec.config.json switches before running any f2s skill" }, { "task": "implement-from-spec", @@ -72,7 +75,8 @@ "topics": [ "f2s-doc-routing", "implement-tech-design" - ] + ], + "summary": "Directory split between stock-docs and req-docs: where requirements, designs, and distilled docs live；Workflow and gates for implementing code from tech designs and requirement docs" }, { "task": "doc-routing", @@ -80,7 +84,8 @@ "matcherPath": ".Knowledge/matchers/m-doc-routing.json", "topics": [ "f2s-doc-routing" - ] + ], + "summary": "Directory split between stock-docs and req-docs: where requirements, designs, and distilled docs live" }, { "task": "change-tracking", @@ -88,7 +93,8 @@ "matcherPath": ".Knowledge/matchers/m-change-tracking.json", "topics": [ "f2s-task" - ] + ], + "summary": "Rules for creating, resuming, and archiving .task checklists" }, { "task": "req-plan", @@ -96,7 +102,8 @@ "matcherPath": ".Knowledge/matchers/m-req-plan.json", "topics": [ "f2s-req-plan" - ] + ], + "summary": "Task planning breakdown and parallel implementation for requirements and changes" }, { "task": "flow2spec-dsh-adapter", @@ -104,7 +111,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", "topics": [ "flow2spec-dsh-adapter" - ] + ], + "summary": "DeepSeek Harness project skill initialization and directory adapter" } ] } diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-config-precheck.md b/packages/core/templates/en-US/knowledge/topics/f2s-config-precheck.md index 7e54f3a..30f0d6c 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-config-precheck.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-config-precheck.md @@ -1,7 +1,7 @@ --- id: config-precheck revision: 0 -summary: "config-precheck (routing summary)" +summary: "Read flow2spec.config.json switches before running any f2s skill" primary: config confidence: manual tags: [policy] diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-fallback-triage.md b/packages/core/templates/en-US/knowledge/topics/f2s-fallback-triage.md index a3d0cad..87daac8 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-fallback-triage.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-fallback-triage.md @@ -1,7 +1,7 @@ --- id: fallback-triage revision: 0 -summary: fallback-triage +summary: "Fallback triage and recall recovery when task routing misses" primary: policy confidence: manual --- diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-implement-tech-design.md b/packages/core/templates/en-US/knowledge/topics/f2s-implement-tech-design.md index ef1d5d5..529ff61 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-implement-tech-design.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-implement-tech-design.md @@ -1,7 +1,7 @@ --- id: implement-tech-design revision: 0 -summary: "implement-tech-design (routing summary)" +summary: "Workflow and gates for implementing code from tech designs and requirement docs" dependsOn: [f2s-doc-routing] primary: policy confidence: manual diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-req-plan.md b/packages/core/templates/en-US/knowledge/topics/f2s-req-plan.md index a0f52b0..3423e4e 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-req-plan.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-req-plan.md @@ -1,7 +1,7 @@ --- id: f2s-req-plan revision: 0 -summary: "f2s-req-plan (routing summary)" +summary: "Task planning breakdown and parallel implementation for requirements and changes" dependsOn: [f2s-task] primary: policy confidence: manual diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-stock-docs-vs-req-docs.md b/packages/core/templates/en-US/knowledge/topics/f2s-stock-docs-vs-req-docs.md index a8ea3e5..f62f14d 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-stock-docs-vs-req-docs.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-stock-docs-vs-req-docs.md @@ -1,7 +1,7 @@ --- id: f2s-doc-routing revision: 0 -summary: "f2s-doc-routing (routing summary)" +summary: "Directory split between stock-docs and req-docs: where requirements, designs, and distilled docs live" primary: policy confidence: manual --- diff --git a/packages/core/templates/en-US/knowledge/topics/f2s-task.md b/packages/core/templates/en-US/knowledge/topics/f2s-task.md index a69359a..7af6b9a 100644 --- a/packages/core/templates/en-US/knowledge/topics/f2s-task.md +++ b/packages/core/templates/en-US/knowledge/topics/f2s-task.md @@ -1,7 +1,7 @@ --- id: f2s-task revision: 0 -summary: "f2s-task (routing summary)" +summary: "Rules for creating, resuming, and archiving .task checklists" primary: policy confidence: manual --- diff --git a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md index bda6d66..86e618f 100644 --- a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md @@ -29,7 +29,7 @@ Some environments create an **independent `git worktree`** or equivalent isolate ## Read Order (Mandatory) -1. First read `.Knowledge/manifest-routing.json`, prefer routing by `taskToTopicRules`; as needed, read the matcher shard from `matcherPath` to obtain `includeAny` keywords. If nothing matches, enter fallback recall. +1. First read `.Knowledge/manifest-routing.json`, prefer routing by `taskToTopicRules`; first-pass evidence is each rule's `task` name and `summary` (one-line intent digest); as needed, read the matcher shard from `matcherPath` to obtain `includeAny` keywords. If nothing matches, enter fallback recall. - If the matched topic has dependencies in `topicDependencies`, read dependency topics first, then the main topic. - Routing manifests are maintained only by `f2s-*` skill flows and do not depend on extra CLI subcommands. 2. Read `.Knowledge/index.md` only as needed to confirm topic semantics and boundaries. @@ -37,9 +37,9 @@ Some environments create an **independent `git worktree`** or equivalent isolate 4. If background is needed, read `.Knowledge/stock-docs/.md`. 5. Drill into business source code only when the first four steps are insufficient. 6. After a match, always run `match -> expand -> verify -> act`: - - `match`: take the primary candidate first; + - `match`: pick the primary candidate by semantic matching against each rule's `task` name and `summary`; both `summary` and `includeAny` are semantic anchors, not literal allowlists—near-synonym hits are allowed; - `expand`: expand `topicDependencies` and keep the next-highest candidate for supplementary verification; - - `verify`: check gaps before acting (missing key topics, boundaries, or context); + - `verify`: check gaps before acting (missing key topics, boundaries, or context); **if the matched topic body does not cover the core nouns of the user's question, you must also read the next-highest candidate's `summary` and matcher shard before deciding—do not answer directly**; - `act`: act only when confidence is sufficient; clarify first when confidence is low. 7. A full cross-matcher supplemental search (top-k) is allowed only when one of these conditions is true: - `taskToTopicRules` has no match; @@ -55,6 +55,7 @@ Some environments create an **independent `git worktree`** or equivalent isolate ## Machine-Readable Source-of-Truth Semantics (Rule Layer) - `taskToTopicRules`: first-priority task routing. +- `taskToTopicRules[].summary`: first-pass recall field (one-line intent digest), mechanically synced by `flow2spec kb build` from the topic frontmatter `summary`; never handwritten on the manifest side; participates in `match` as a semantic anchor. - `taskToTopicRules[].matcherPath`: direct path to the matcher-word shard; read a single matcher file as needed. - `taskToTopicRules[].matcherId`: stable matcher identifier; must match `id` inside the matcher shard. - `topicDependencies`: load dependency topics first after the main topic matches. diff --git a/packages/core/templates/en-US/rules/f2s-kb-feedback-closing.md b/packages/core/templates/en-US/rules/f2s-kb-feedback-closing.md index 49630de..a85f682 100644 --- a/packages/core/templates/en-US/rules/f2s-kb-feedback-closing.md +++ b/packages/core/templates/en-US/rules/f2s-kb-feedback-closing.md @@ -109,6 +109,12 @@ Other `f2s-kb-*` skills (e.g., `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync`) **s This avoids misjudging "already has a topic but still suggests add". +## Routing-Miss Backfill (Mandatory) + +- **Judgment**: the core facts of this turn's answer were provided by some topic, but that topic was **not the first-pass primary match** (it was found only via a full supplemental search, by co-reading the next-highest candidate, or because the user named it) → count this as a routing miss. +- **Action**: in addition to the four-case closing, backfill the user's original phrasing into that topic's recall anchors — per the "first-pass recall" rules in `f2s-topic-authoring`, add the core nouns to the frontmatter `summary` or single-concept terms to the matcher `includeAny`, then run `flow2spec kb build` to sync `rule.summary`. This is a minimal fix written directly to disk; it does not depend on the user running distill. +- Even when the closing uses case 4 (KB already covers it), if the hit path was a post-miss rescue, this backfill must still run, and append one line after the closing block: `Routing backfilled: summary/includeAny added ""`. + ## Output Format - Cases 1-3: output one Markdown blockquote containing, in order, the `f2s-kb-distill` command + one blank line + the **This turn will ingest** summary (one line, see "Summary requirement" above). diff --git a/packages/core/templates/en-US/rules/f2s-topic-authoring.md b/packages/core/templates/en-US/rules/f2s-topic-authoring.md index 61ecb62..7473ff3 100644 --- a/packages/core/templates/en-US/rules/f2s-topic-authoring.md +++ b/packages/core/templates/en-US/rules/f2s-topic-authoring.md @@ -39,6 +39,15 @@ Every topic must include at least: 5. **Boundaries and prohibited items** (avoid expanding into neighboring topics); 6. **Long-form background / detailed materials reference** (when the topic needs to carry business background): list only clickable Markdown links to `.Knowledge/stock-docs/*_终稿.md` (1–3 links); **do not** list `.Knowledge/req-docs/*` here. If no stock-doc has been consolidated yet, **generate the stock-doc first** and then fill this section. +### Authoring rules for frontmatter `summary` and `includeAny` (first-pass recall, hard constraint) + +The topic frontmatter `summary` is synced by `flow2spec kb build` into `manifest-routing.taskToTopicRules[].summary`—the always-resident semantic anchor for the Agent's first-pass routing. Its quality directly decides whether the topic can be hit by natural phrasing: + +- **`summary`**: one sentence stating "responsibility + the core nouns users will actually ask with", covering all of the topic's responsibility domains (e.g. if it carries both "scope boundary" and "asset locations", both must appear); soft limit 15 words (30 CJK chars), hard limit 20 words / 40 chars (validated by `kb check`); placeholder styles like ` (routing summary)` or `TODO` are prohibited. +- **`includeAny`**: prefer single-concept core words (the smallest words that appear standalone in natural questions, e.g. "prototype", "flowchart" rather than "prototype location", "business flowchart"); compound words are supplements only; when distilling from user dictation, add 1–2 "future natural phrasing" words instead of copying the dictation verbatim. +- **Self-test (mandatory before writing to disk)**: simulate 2–3 natural user questions (imagine how users would ask, without looking at the word list) and check each hits at least one of `summary` or `includeAny`; revise on miss. +- **`taskToTopicRules[].task`**: keep stable id semantics (the kb engine merges by `task`); do not stuff long phrases into it—recall semantics live in `summary`, and the manifest side is generated by `kb build`, never handwritten. + ## 3. topicMetadata Decision Criteria `topicMetadata` is governance metadata. It only affects inventory, audit, and reading expectations; it does not participate in matcher hits, does not decide whether a topic is read, and does not change execution mandatoryness. Execution mandatoryness comes from explicit requirements in `AGENTS.md`, rules, skills, and topic bodies. diff --git a/packages/core/templates/en-US/skills/f2s-kb-addRules/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-addRules/SKILL.md index a00a729..bb1c786 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-addRules/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-addRules/SKILL.md @@ -83,7 +83,7 @@ When merging into an existing topic, if the change only refines an existing rule - Add `manifest-routing.topicPaths`: ` -> .Knowledge/topics/.md`. - Add `manifest-routing.topicMetadata` as needed: spoken-rule topics are usually `{ "primary": "policy", "confidence": "inferred" }`; write `manual` when the user explicitly confirms the classification. If it also contains config/module/capability characteristics, write `tags` that do not duplicate `primary`; if evidence is insufficient, do not write metadata and list it as pending confirmation in the summary. Classification is only for governance, audit, and reading expectations; it does not participate in route matching or execution requirements. - Add `taskToTopicRules[]` only when this rule should be matched as **user task routing** (see `f2s-topic-authoring` section 5 criteria); internal rules that are only referenced by other rules / SKILLs **do not enter** `taskToTopicRules`. - - If `taskToTopicRules[]` is added, create `.Knowledge/matchers/.json`, extracting `includeAny` keywords from the user's wording (the original words + 1-2 obvious synonyms; prefer missing terms over over-broad terms). + - If `taskToTopicRules[]` is added, create `.Knowledge/matchers/.json`, extracting `includeAny` per the "first-pass recall" rules in `f2s-topic-authoring`: **single-concept core terms first**, compound terms only as supplements; besides the user's original wording, add 1-2 terms matching "how the user would naturally ask later", and self-test with 2-3 simulated questions; write the topic frontmatter `summary` per the same rules (kb build syncs it into `rule.summary` as the first-pass anchor). - **Merge into existing topic**: - `topicPaths` does not change. - Fill this topic's `topicMetadata` as needed, but do not create, rename, or split topics for classification. diff --git a/packages/core/templates/en-US/skills/f2s-kb-build/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-build/SKILL.md index b031e98..8c4683b 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-build/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-build/SKILL.md @@ -47,9 +47,10 @@ description: Generate knowledge-routing topics and indexes from `.Knowledge/stoc Extract from the document: - Topic name and topic intent (can form a topic id) +- Frontmatter `summary` (first-pass recall anchor: responsibility + core nouns the user would ask about, written per the "first-pass recall" rules in `f2s-topic-authoring`; kb build syncs it into manifest `rule.summary`) - Core concepts and key flows - Business rules and boundary conditions -- Task trigger terms (write to the corresponding `matchers/.json` `includeAny`) +- Task trigger terms (write to the corresponding `matchers/.json` `includeAny`; single-concept core terms first, compound terms only as supplements) - Dependencies on existing topics (for `topicDependencies`) > **Authoring-side guideline**: this step involves adding/modifying topics and `topicDependencies`, so first Read the full `rules/f2s-topic-authoring.*` (**Cursor/Claude**: `rules/f2s-topic-authoring.mdc`; **Codex**: `.codex/topics/f2s-topic-authoring.md`) before continuing to step 3 / step 5. Naming, skeleton, dependency judgment, DAG minimization, and judgment timing all follow that guideline; this SKILL does not repeat them. diff --git a/packages/core/templates/en-US/skills/f2s-kb-distill/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-distill/SKILL.md index db1d5db..f880467 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-distill/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-distill/SKILL.md @@ -278,12 +278,14 @@ If strategy is "create independent module topic": - Create corresponding `matchers/.json`, including: - Keywords extracted from user question - Terms extracted from answer - - Suggested `includeAny`: 5-10 trigger words + - Suggested `includeAny`: 5-10 trigger words (single-concept core terms first, compound terms only as supplements; see the "first-pass recall" rules in `f2s-topic-authoring`) - Add routing rule in `taskToTopicRules` + - Write topic frontmatter `summary` per the "first-pass recall" rules (responsibility + core nouns the user would ask about; kb build syncs it into `rule.summary`) - If updating existing topic: - Check if matcher needs new trigger words - Extract uncovered keywords from user question, append to `includeAny` + - If this turn's phrasing is not covered by the topic's `summary`, revise the frontmatter `summary` to add the core nouns #### 5.2 Update index.md @@ -366,7 +368,7 @@ Self-check list: - No user confirmation needed (Q&A already verified knowledge correctness) - Keep lightweight, single Q&A knowledge extraction complete within 30 seconds - Avoid over-splitting: unless drill-down depth ≥ deep and knowledge description depth ≥ detailed level, prioritize appending to existing topic -- Generated matcher includeAny should cover expressions users actually use, not just technical terms +- Generated matcher includeAny should cover expressions users actually use, not just technical terms; the topic frontmatter `summary` should likewise cover the core nouns of this turn's phrasing ## Self-Check After Completion diff --git a/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md index f00caa7..2e91a96 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md @@ -87,7 +87,7 @@ Update according to the outline, item by item: - `.Knowledge/topics/*.md` - `.Knowledge/index.md` (sync the "Associated documents (summary)" column in the topic routing table) -- Routing manifest (as needed). When creating a new topic, also sync `topicPaths` and necessary `taskToTopicRules` / matcher shards. Write `topicMetadata` only when evidence is clear; classification is only for governance, audit, and reading expectations, does not participate in route matching or execution requirements, and must not be used to create, rename, or split topics. +- Routing manifest (as needed). When creating a new topic, also sync `topicPaths` and necessary `taskToTopicRules` / matcher shards; write the frontmatter `summary` and matcher `includeAny` of new/updated topics per the "first-pass recall" rules in `f2s-topic-authoring` (`summary` is synced into `rule.summary` by kb build). Write `topicMetadata` only when evidence is clear; classification is only for governance, audit, and reading expectations, does not participate in route matching or execution requirements, and must not be used to create, rename, or split topics. - `.Knowledge/stock-docs/*.md` (add source documents as needed) ### Step 4: Closing Summary diff --git a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md index 7640eb2..9209b74 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md @@ -229,7 +229,8 @@ After this skill's step 2 `flow2spec init` succeeds, first perform "old file cle - `includeAny` has more than **12 terms**. - The topic body contains second-level headings covering more than **3 unrelated responsibility domains**. - The topic is frequently matched by multiple unrelated task types (can be judged from `taskToTopicRules` and matcher term breadth). -7. **Automatic old-topic frontmatter repair**: in the full flow, the agent must run `flow2spec kb build --fix-topics` (or the equivalent internal capability) to add `id`, `revision`, and `summary` to existing topics that lack frontmatter / `revision`, and to fill `dependsOn` / `primary` / `confidence` / `tags` from `manifest-routing.json`. Then run `flow2spec kb check --strict`; if strict validation fails, stop and list the concrete topic / reason in the summary. Do not ask the user to manually add topic headers one by one. +7. **Automatic old-topic frontmatter repair**: in the full flow, the agent must run `flow2spec kb build --fix-topics` (or the equivalent internal capability) to add `id`, `revision`, and `summary` to existing topics that lack frontmatter / `revision`, and to fill `dependsOn` / `primary` / `confidence` / `tags` from `manifest-routing.json`. Then run `flow2spec kb check --strict`; if the failing items are **summary quality warnings** (missing / placeholder / too long), go to item 8 to rewrite them; for any other failure, stop and list the concrete topic / reason in the summary. Do not ask the user to manually add topic headers one by one. +8. **Summary first-pass anchor rewrite (required; only the agent can write semantic summaries)**: for each summary quality warning reported by `kb check --strict`, Read the corresponding `.Knowledge/topics/.md` body one by one and write the frontmatter `summary` per the "first-pass recall" rules in `f2s-topic-authoring` (responsibility + core nouns the user would ask about; soft limit 15 words / hard limit 20 words). After all are written, run `flow2spec kb build` to sync them into `rule.summary`, then rerun `flow2spec kb check --strict` until no summary warnings remain. Do not pass with placeholder text (` (routing summary)` / TODO). ### Step 3b: `index.md` Merge and `template/index.template.md` (Required) @@ -317,6 +318,7 @@ Output: - **index (snapshot + merge)**: `snapshot copied` / `index.md merged` / `not executed on fast path` / `pending (see notes)` - **topicMetadata (existing audit)**: `filled` / `pending user confirmation` / `not executed on fast path`; list added / fixed / deleted topicIds - **topic frontmatter**: `auto-filled N topics` / `already complete` / `strict validation failed` / `not executed on fast path` +- **summary first-pass anchor**: `rewrote N summaries (synced into rule.summary via kb build)` / `already compliant` / `not executed on fast path` - **f2s-kb-upgrade SKILL**: `unchanged after init` / `reran N rounds from step 2c per new SKILL (no second init)` / `loop skipped on fast path` / `pending confirmation` - **`projectRev` write-back**: `written to project manifest (value=pkgRev)` / `not executed on fast path` / `pkgRev=null, field untouched` - manifest-routing / matcher shards: `aligned with template` / `already latest` / `reset overwrite` @@ -345,7 +347,7 @@ Output: 6. Incremental or reset mode was clearly labeled. 7. **On full flow**: old topic-file cleanup and `index/manifest` reference fixes were handled (step 3). 8. **On full flow**: **Step 3a** was executed: `topicMetadata` audited, with no orphan keys / illegal primary / illegal confidence; missing old topics were filled with `inferred` based on evidence or listed as pending confirmation. -9. **On full flow**: `flow2spec kb build --fix-topics` or an equivalent internal capability was executed, followed by `flow2spec kb check --strict`, ensuring existing topics have `revision`. +9. **On full flow**: `flow2spec kb build --fix-topics` or an equivalent internal capability was executed, followed by `flow2spec kb check --strict`, ensuring existing topics have `revision`; summary quality warnings were rewritten to zero per step 3a.8 and synced into `rule.summary` via `kb build`. 10. **On full flow**: **Step 3b** was executed: `index.md` was **merged** (from **`Topic Overview`** section through before "Match and Execute" is project-maintained; the rest matches the package version), and `topicPaths` were checked; **at the end of full flow**, the project-side `projectRev` was **written back** to `pkgRev` (if `pkgRev=null`, the field was left unchanged). 11. **On fast path**: steps 3 / 3a / 3b were actually skipped (no unrelated scans), and the summary explicitly labels "not executed on fast path". 12. Manifest and key-path verification results were output. diff --git a/packages/core/templates/zh-CN/knowledge/manifest-routing.json b/packages/core/templates/zh-CN/knowledge/manifest-routing.json index b2e80e3..cd90bff 100644 --- a/packages/core/templates/zh-CN/knowledge/manifest-routing.json +++ b/packages/core/templates/zh-CN/knowledge/manifest-routing.json @@ -1,6 +1,6 @@ { - "version": "3.5.0", - "projectRev": 2, + "version": "3.6.0", + "projectRev": 3, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", "sourceOfTruth": ".Knowledge/manifest-routing.json", @@ -44,7 +44,9 @@ "flow2spec-dsh-adapter": { "primary": "feature", "confidence": "inferred", - "tags": ["module"] + "tags": [ + "module" + ] } }, "topicPaths": { @@ -63,7 +65,8 @@ "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", "topics": [ "config-precheck" - ] + ], + "summary": "f2s 技能执行前必读 flow2spec.config.json 的开关口径" }, { "task": "implement-from-spec", @@ -72,7 +75,8 @@ "topics": [ "f2s-doc-routing", "implement-tech-design" - ] + ], + "summary": "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪；按技术方案/需求文档实现代码的流程与门禁" }, { "task": "doc-routing", @@ -80,7 +84,8 @@ "matcherPath": ".Knowledge/matchers/m-doc-routing.json", "topics": [ "f2s-doc-routing" - ] + ], + "summary": "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪" }, { "task": "change-tracking", @@ -88,7 +93,8 @@ "matcherPath": ".Knowledge/matchers/m-change-tracking.json", "topics": [ "f2s-task" - ] + ], + "summary": "任务清单 .task 目录的创建、续作与归档规则" }, { "task": "req-plan", @@ -96,7 +102,8 @@ "matcherPath": ".Knowledge/matchers/m-req-plan.json", "topics": [ "f2s-req-plan" - ] + ], + "summary": "需求/变更的任务规划拆解与并行实现流程" }, { "task": "flow2spec-dsh-adapter", @@ -104,7 +111,8 @@ "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", "topics": [ "flow2spec-dsh-adapter" - ] + ], + "summary": "DeepSeek Harness 项目级技能初始化与目录适配" } ] } diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-config-precheck.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-config-precheck.md index c8947f3..3d630a4 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-config-precheck.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-config-precheck.md @@ -1,7 +1,7 @@ --- id: config-precheck revision: 0 -summary: "config-precheck（路由摘要）" +summary: "f2s 技能执行前必读 flow2spec.config.json 的开关口径" primary: config confidence: manual tags: [policy] diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-fallback-triage.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-fallback-triage.md index f27ffaa..65bbc10 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-fallback-triage.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-fallback-triage.md @@ -1,7 +1,7 @@ --- id: fallback-triage revision: 0 -summary: fallback-triage +summary: "路由未命中时的兜底分诊与补召回流程" primary: policy confidence: manual --- diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-implement-tech-design.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-implement-tech-design.md index 6c13e8b..9e1eb2f 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-implement-tech-design.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-implement-tech-design.md @@ -1,7 +1,7 @@ --- id: implement-tech-design revision: 0 -summary: "implement-tech-design（路由摘要）" +summary: "按技术方案/需求文档实现代码的流程与门禁" dependsOn: [f2s-doc-routing] primary: policy confidence: manual diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-req-plan.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-req-plan.md index bf3781e..f58da07 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-req-plan.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-req-plan.md @@ -1,7 +1,7 @@ --- id: f2s-req-plan revision: 0 -summary: "f2s-req-plan（路由摘要）" +summary: "需求/变更的任务规划拆解与并行实现流程" dependsOn: [f2s-task] primary: policy confidence: manual diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-stock-docs-vs-req-docs.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-stock-docs-vs-req-docs.md index 19ae76b..bd9bd48 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-stock-docs-vs-req-docs.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-stock-docs-vs-req-docs.md @@ -1,7 +1,7 @@ --- id: f2s-doc-routing revision: 0 -summary: "f2s-doc-routing（路由摘要）" +summary: "stock-docs 与 req-docs 目录分工：需求、方案、沉淀文档放哪" primary: policy confidence: manual --- diff --git a/packages/core/templates/zh-CN/knowledge/topics/f2s-task.md b/packages/core/templates/zh-CN/knowledge/topics/f2s-task.md index ed13c47..1d4726e 100644 --- a/packages/core/templates/zh-CN/knowledge/topics/f2s-task.md +++ b/packages/core/templates/zh-CN/knowledge/topics/f2s-task.md @@ -1,7 +1,7 @@ --- id: f2s-task revision: 0 -summary: "f2s-task（路由摘要）" +summary: "任务清单 .task 目录的创建、续作与归档规则" primary: policy confidence: manual --- diff --git a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md index 5c8b409..b35cb67 100644 --- a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md @@ -29,7 +29,7 @@ alwaysApply: true ## 读取顺序（必须） -1. 先读 `.Knowledge/manifest-routing.json`，优先按 `taskToTopicRules` 路由；按需根据 `matcherPath` 读取 matcher 分片获取 `includeAny` 关键词；无法命中时进入补召回阶段。 +1. 先读 `.Knowledge/manifest-routing.json`，优先按 `taskToTopicRules` 路由；初筛证据为每条规则的 `task` 名与 `summary`（一句话意图摘要）；按需根据 `matcherPath` 读取 matcher 分片获取 `includeAny` 关键词；无法命中时进入补召回阶段。 - 若命中主题在 `topicDependencies` 中存在依赖，先读依赖主题，再读主主题。 - 路由清单仅通过 `f2s-*` 技能流程维护，不依赖额外 CLI 子命令。 2. `.Knowledge/index.md` 按需读取，仅用于确认主题语义与边界。 @@ -37,9 +37,9 @@ alwaysApply: true 4. 若需要背景，再读 `.Knowledge/stock-docs/.md`。 5. 仅在前四步不足时下钻业务源码。 6. 命中后必须执行 `match -> expand -> verify -> act`： - - `match`：先取主候选； + - `match`：以规则的 `task` 名与 `summary` 做语义匹配取主候选；`summary` 与 `includeAny` 均为语义锚而非字面白名单，允许近义命中； - `expand`：展开 `topicDependencies`，并保留次高候选做补充校验； - - `verify`：执行前做缺口检查（关键主题/边界/上下文是否缺失）； + - `verify`：执行前做缺口检查（关键主题/边界/上下文是否缺失）；**若命中主题正文未覆盖用户问句的核心名词，必须并读次高候选的 `summary` 与 matcher 分片再定，不得直接作答**； - `act`：仅在置信度足够时执行；低置信度必须先澄清。 7. 仅在以下条件之一成立时，允许执行跨 matcher 全量补检索（top-k）： - `taskToTopicRules` 无命中； @@ -55,6 +55,7 @@ alwaysApply: true ## 机读事实源口径（规则层） - `taskToTopicRules`：任务路由第一优先级。 +- `taskToTopicRules[].summary`：初筛召回字段（一句话意图摘要），由 `flow2spec kb build` 从 topic frontmatter `summary` 机械同步，不手写 manifest 侧；作语义锚参与 match 初筛。 - `taskToTopicRules[].matcherPath`：匹配词分片直链路径，按需读取单个 matcher 文件。 - `taskToTopicRules[].matcherId`：matcher 的稳定标识，需与 matcher 分片内 `id` 一致。 - `topicDependencies`：主主题命中后先加载依赖主题。 diff --git a/packages/core/templates/zh-CN/rules/f2s-kb-feedback-closing.md b/packages/core/templates/zh-CN/rules/f2s-kb-feedback-closing.md index 857f904..c9f815c 100644 --- a/packages/core/templates/zh-CN/rules/f2s-kb-feedback-closing.md +++ b/packages/core/templates/zh-CN/rules/f2s-kb-feedback-closing.md @@ -107,6 +107,12 @@ description: 普通问答读取源码后的知识库补充建议收口规则； 这样能避免"已有 topic 还建议 add"的误判。 +## 路由 miss 反哺（强制） + +- **判定**：本轮答案的核心事实由某 topic 提供，但该 topic **不是初筛主命中**（靠全量补检索、次高候选并读或用户点名才找到）→ 计为一次路由 miss。 +- **动作**：在四 case 收口之外，把本轮用户的原始问法回填该 topic 的召回锚——按 `f2s-topic-authoring`「初筛召回规范」补 frontmatter `summary` 的核心名词或 matcher `includeAny` 的单概念词，并跑 `flow2spec kb build` 同步 rule.summary。此项是直接落盘的最小修复，不依赖用户再跑 distill。 +- 即使收口走 case 4（知识库已覆盖），只要命中路径是 miss 后补救，仍须执行本反哺，并在收口块后追加一行：`已回填路由： 的 summary/includeAny 补「<词>」`。 + ## 输出格式 - case 1～3：输出一个 Markdown 引用块，依次写 `f2s-kb-distill` 命令 + 一行空行 + **本轮将入库**概要（一句话，见上文「概要要求」）。 diff --git a/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md b/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md index e454ec9..4e975c1 100644 --- a/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md +++ b/packages/core/templates/zh-CN/rules/f2s-topic-authoring.md @@ -38,6 +38,15 @@ alwaysApply: false 5. **边界与禁止项**（避免膨胀到隔壁 topic）； 6. **长文背景 / 详细资料引用**（如需承载业务背景）：只列 `.Knowledge/stock-docs/*_终稿.md` 的可点击 Markdown 链接（1–3 条即可）；**禁止**直接列 `.Knowledge/req-docs/*` 作为长文背景来源；无对应终稿时**先生成终稿**再回填此小节。 +### frontmatter `summary` 与 `includeAny` 创作规范（初筛召回，硬约束） + +topic frontmatter 的 `summary` 会被 `flow2spec kb build` 同步进 `manifest-routing.taskToTopicRules[].summary`，是 Agent 初筛的常驻语义锚——写作质量直接决定该 topic 能否被自然问法命中： + +- **`summary`**：一句话写清「职责 + 用户会问的核心名词」，覆盖 topic 的全部职责域（如同时承担“职责边界”与“资料入口”，两者都要出现）；软上限 30 字（英文 15 词），硬上限 40 字 / 20 词（`kb check` 校验）；禁止 `（路由摘要）`、`TODO` 等占位写法。 +- **`includeAny`**：单概念核心词优先（自然问法中会独立出现的最小词，如「原型」「流程图」而非「原型位置」「业务流程图」）；复合词仅作补充；从用户口述沉淀时须补 1–2 个“日后自然问法”词，不只抄口述原文。 +- **自测（落盘前必做）**：模拟 2–3 个用户自然问句（凭空想“用户会怎么问”，不看词表），检查每句至少命中 `summary` 或 `includeAny` 之一；不命中则回改。 +- **`taskToTopicRules[].task`**：保持稳定 id 语义（kb 引擎按 `task` 合并），不塞长短语；召回语义由 `summary` 承载，manifest 侧由 `kb build` 生成，不手写。 + ## 3. topicMetadata 判定准则 `topicMetadata` 是治理元数据，只影响盘点、审计和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性。执行强制性以 `AGENTS.md`、rules、skills 与 topic 正文明确要求为准。 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-addRules/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-addRules/SKILL.md index 93bc55f..f62b94d 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-addRules/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-addRules/SKILL.md @@ -83,7 +83,7 @@ description: 把用户口述的规则沉淀进知识库，自动判定「新建 - 补 `manifest-routing.topicPaths`：` -> .Knowledge/topics/.md`； - 按需补 `manifest-routing.topicMetadata`：口述规则主题通常为 `{ "primary": "policy", "confidence": "inferred" }`；用户明确确认分类可写 `manual`；如同时包含配置项 / 模块 / 能力性质，可写入不与 `primary` 重复的 `tags`；证据不足则不写 metadata，并在摘要列为待确认。分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性； - 视情况补 `taskToTopicRules[]`——**仅当**该规则会作为**用户任务路由命中**（参见 `f2s-topic-authoring` 第 5 节判据）才补；纯被其它规则 / SKILL 引用的内部规则**不进** `taskToTopicRules`； - - 若补了 `taskToTopicRules[]`，须新建 `.Knowledge/matchers/.json`，从用户口述中抽取 `includeAny` 关键词（用户原话 + 1–2 个明显近义说法，宁缺勿滥）； + - 若补了 `taskToTopicRules[]`，须新建 `.Knowledge/matchers/.json`，`includeAny` 按 `f2s-topic-authoring`「初筛召回规范」抽取：**单概念核心词优先**，复合词仅作补充；除用户口述原词外须补 1–2 个“日后自然问法”词，并用 2–3 个模拟问句自测命中；topic frontmatter `summary` 同步按该规范写（kb build 会将其同步进 rule.summary 作初筛锚）； - **并入存量主题**： - `topicPaths` 不变； - 可按需补齐该 topic 的 `topicMetadata`，但不得为了分类创建、重命名或拆分 topic； diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-build/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-build/SKILL.md index bda9c7b..15b5ec2 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-build/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-build/SKILL.md @@ -47,9 +47,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索 从文档中提炼： - 主题名与主题意图（可形成 topic id） +- frontmatter `summary`（初筛召回锚：职责 + 用户会问的核心名词，按 `f2s-topic-authoring`「初筛召回规范」写；kb build 会同步进 manifest rule.summary） - 核心概念与关键流程 - 业务规则与边界条件 -- 任务触发词（写入对应 `matchers/.json` 的 `includeAny`） +- 任务触发词（写入对应 `matchers/.json` 的 `includeAny`；单概念核心词优先，复合词仅作补充） - 与现有主题的依赖关系（用于 `topicDependencies`） > **创作侧准则**：本步骤涉及新增 / 修改 topic 与 `topicDependencies`，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再继续步骤 3 / 步骤 5。命名、骨架、依赖判定、DAG 最小化、判定时机均以该条为准，本 SKILL 不复述。 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-distill/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-distill/SKILL.md index c2f923b..496ebf5 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-distill/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-distill/SKILL.md @@ -285,12 +285,14 @@ description: 从问答过程中提取可复用知识事实并自动入库；根 - 创建对应的 `matchers/.json`，包含： - 从用户问题中提取的关键词 - 从回答中提取的术语 - - 建议 `includeAny`：5-10 个触发词 + - 建议 `includeAny`：5-10 个触发词（单概念核心词优先，复合词仅作补充；见 `f2s-topic-authoring`「初筛召回规范」） - 在 `taskToTopicRules` 中添加路由规则 + - topic frontmatter `summary` 按「初筛召回规范」写（职责 + 用户会问的核心名词；kb build 会同步进 rule.summary） - 如果更新既有 topic： - 检查 matcher 是否需要补充新的触发词 - 从用户问题中提取未覆盖的关键词，追加到 `includeAny` + - 若本轮问法未被该 topic 的 `summary` 覆盖，回改 frontmatter `summary` 补上核心名词 #### 5.2 更新 index.md @@ -373,7 +375,7 @@ description: 从问答过程中提取可复用知识事实并自动入库；根 - 不需要用户确认（问答已验证知识的正确性） - 保持轻量，单次问答的知识提取在 30 秒内完成 - 避免过度拆分：除非下钻深度 ≥ 深且知识描述深度 ≥ 详细级，否则优先补充既有 topic -- 生成的 matcher includeAny 应覆盖用户实际会用的表述，不只是技术术语 +- 生成的 matcher includeAny 应覆盖用户实际会用的表述，不只是技术术语；topic frontmatter `summary` 同步覆盖本轮问法的核心名词 ## 完成后自检 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md index 6d69ea2..922569a 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md @@ -87,7 +87,7 @@ description: 可显式给出能力或零输入推断；先输出知识库更新 - `.Knowledge/topics/*.md` - `.Knowledge/index.md`（同步主题路由表的“关联文档（摘要）”列） -- 路由清单（按需）；若创建新 topic，须同步 `topicPaths`、必要的 `taskToTopicRules` / matcher 分片；可在证据明确时写 `topicMetadata`，但分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性，不得为了分类创建、重命名或拆分 topic +- 路由清单（按需）；若创建新 topic，须同步 `topicPaths`、必要的 `taskToTopicRules` / matcher 分片；新建 / 更新 topic 的 frontmatter `summary` 与 matcher `includeAny` 按 `f2s-topic-authoring`「初筛召回规范」写（summary 由 kb build 同步进 rule.summary）；可在证据明确时写 `topicMetadata`，但分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性，不得为了分类创建、重命名或拆分 topic - `.Knowledge/stock-docs/*.md`（按需补充索源文档） ### 步骤 4：收尾摘要 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md index 2ae6011..b5d31a7 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md @@ -229,7 +229,8 @@ flow2spec update --check - `includeAny` 词数超过 **12 个**； - topic 正文包含超过 **3 个不相干职责域**的二级标题； - 该 topic 同时被多种不相干任务类型频繁命中（可从 `taskToTopicRules` 和 matcher 词宽度判断）。 -7. **旧 topic frontmatter 自动补齐**：完整流程中必须由 agent 自行执行 `flow2spec kb build --fix-topics`（或等价内部能力），为缺少 frontmatter / `revision` 的存量 topic 补 `id`、`revision`、`summary`，并按 `manifest-routing.json` 补 `dependsOn` / `primary` / `confidence` / `tags`。随后执行 `flow2spec kb check --strict`；若 strict 失败，停止并在摘要中列出具体 topic / reason。不得要求用户手动逐个 topic 添加头部。 +7. **旧 topic frontmatter 自动补齐**：完整流程中必须由 agent 自行执行 `flow2spec kb build --fix-topics`（或等价内部能力），为缺少 frontmatter / `revision` 的存量 topic 补 `id`、`revision`、`summary`，并按 `manifest-routing.json` 补 `dependsOn` / `primary` / `confidence` / `tags`。随后执行 `flow2spec kb check --strict`；若失败项为 **summary 质量 warning**（缺失 / 占位 / 超长），转第 8 条补写；其余失败停止并在摘要中列出具体 topic / reason。不得要求用户手动逐个 topic 添加头部。 +8. **summary 初筛锚补写（必须，agent 才能写出语义摘要）**：对 `kb check --strict` 报出的每个 summary 质量 warning，逐个 Read 对应 `.Knowledge/topics/.md` 正文，按 `f2s-topic-authoring`「初筛召回规范」补写 frontmatter `summary`（职责 + 用户会问的核心名词，软 30 字 / 硬 40 字）；全部补完后执行 `flow2spec kb build` 同步进 `rule.summary`，再跑 `flow2spec kb check --strict` 直至无 summary warning。禁止用占位文案（`（路由摘要）` / TODO）敷衍通过。 ### 步骤 3b：`index.md` 融合与 `template/index.template.md`（必须执行） @@ -317,6 +318,7 @@ flow2spec update --check - **index（快照 + 融合）**：`快照已复制` / `index.md 已融合` / `快速路径下未执行` / `待处理（见备注）` - **topicMetadata（存量审计）**：`已补齐` / `待用户确认` / `快速路径下未执行`；列出新增 / 修正 / 删除的 topicId - **topic frontmatter**：`已自动补齐 N 个` / `已完整无需补齐` / `strict 校验失败` / `快速路径下未执行` +- **summary 初筛锚**：`已补写 N 个（已 kb build 同步 rule.summary）` / `已合规无需补写` / `快速路径下未执行` - **f2s-kb-upgrade SKILL**：`init 后无变化` / `已按新版从 2c 起重跑 N 轮（不再次 init）` / `快速路径下跳过该闭环` / `待确认` - **`projectRev` 回写**：`已写入项目 manifest（值=pkgRev）` / `快速路径下未执行` / `pkgRev=null 未动` - manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖` @@ -345,7 +347,7 @@ flow2spec update --check 6. 是否明确标注增量 or reset 模式。 7. **完整流程时**：是否已处理旧主题文件清理与 `index/manifest` 引用修复（步骤 3）。 8. **完整流程时**：是否已执行 **步骤 3a**：审计 `topicMetadata`，确保无孤儿 key / 非法 primary / 非法 confidence；缺失旧主题已按证据补 `inferred` 或列为待确认。 -9. **完整流程时**：是否已执行 `flow2spec kb build --fix-topics` 或等价内部能力，并随后执行 `flow2spec kb check --strict`，确保存量 topic 已具备 `revision`。 +9. **完整流程时**：是否已执行 `flow2spec kb build --fix-topics` 或等价内部能力，并随后执行 `flow2spec kb check --strict`，确保存量 topic 已具备 `revision`；summary 质量 warning 是否已按步骤 3a.8 补写清零并 `kb build` 同步 `rule.summary`。 10. **完整流程时**：是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`；**完整流程末尾**是否已**回写** 项目侧 `projectRev = pkgRev`（`pkgRev=null` 则保留原值）。 11. **快速路径时**：步骤 3 / 3a / 3b 是否真的跳过（未做无关扫描），摘要中明确标注「快速路径下未执行」。 12. 是否输出了 manifest 与关键路径校验结果。 diff --git a/scripts/test-cli-update.js b/scripts/test-cli-update.js index 39b5f66..92e2e94 100644 --- a/scripts/test-cli-update.js +++ b/scripts/test-cli-update.js @@ -9,13 +9,28 @@ const { spawnSync } = require("child_process"); const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "flow2spec-cli-update-")); const cliPath = path.resolve(__dirname, "..", "cli.js"); +// 动态读取本地版本，stub 返回「补丁号 +1」的新版本，避免发版后钉死 fixture +const cliPkg = require(path.resolve(__dirname, "..", "packages", "cli", "package.json")); +const corePkg = require(path.resolve(__dirname, "..", "packages", "core", "package.json")); +const cliVersion = cliPkg.version; +const coreVersion = corePkg.version; +const templateVersion = corePkg.templateVersion; +const coreRange = cliPkg.dependencies["@double-coding/flow2spec-core"]; +const bumpPatch = (v) => { + const [major, minor, patch] = v.split(".").map(Number); + return `${major}.${minor}.${patch + 1}`; +}; +const latestCli = bumpPatch(cliVersion); +const latestCore = bumpPatch(coreVersion); +const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + if (process.platform === "win32") { fs.writeFileSync(path.join(tempDir, "npm.cmd"), [ "@echo off", "if \"%2\"==\"@double-coding/flow2spec-core\" (", - " echo {\"version\":\"3.6.1\",\"templateVersion\":\"3.5.0\"}", + ` echo {"version":"${latestCore}","templateVersion":"${templateVersion}"}`, ") else (", - " echo 3.6.1", + ` echo ${latestCli}`, ")", "", ].join("\r\n"), "utf8"); @@ -24,9 +39,9 @@ if (process.platform === "win32") { fs.writeFileSync(npmPath, [ "#!/usr/bin/env sh", "if [ \"$2\" = \"@double-coding/flow2spec-core\" ]; then", - " echo '{\"version\":\"3.6.1\",\"templateVersion\":\"3.5.0\"}'", + ` echo '{"version":"${latestCore}","templateVersion":"${templateVersion}"}'`, "else", - " echo '3.6.1'", + ` echo '${latestCli}'`, "fi", "", ].join("\n"), { encoding: "utf8", mode: 0o755 }); @@ -43,10 +58,10 @@ const check = spawnSync(process.execPath, [cliPath, "update", "--check"], { encoding: "utf8", }); assert.strictEqual(check.status, 0, check.stderr); -assert.match(check.stdout, /CLI:\s+3\.6\.0 -> 3\.6\.1/); -assert.match(check.stdout, /Core:\s+3\.6\.0 -> 3\.6\.1/); -assert.match(check.stdout, /Template:\s+3\.5\.0 -> 3\.5\.0/); -assert.match(check.stdout, /\^3\.6\.0 \(compatible\)/); +assert.match(check.stdout, new RegExp(`CLI:\\s+${escapeRe(cliVersion)} -> ${escapeRe(latestCli)}`)); +assert.match(check.stdout, new RegExp(`Core:\\s+${escapeRe(coreVersion)} -> ${escapeRe(latestCore)}`)); +assert.match(check.stdout, new RegExp(`Template:\\s+${escapeRe(templateVersion)} -> ${escapeRe(templateVersion)}`)); +assert.match(check.stdout, new RegExp(`${escapeRe(coreRange)} \\(compatible\\)`)); const invalid = spawnSync(process.execPath, [cliPath, "update", "--unknown"], { cwd: path.resolve(__dirname, ".."), diff --git a/scripts/test-knowledge-engine.js b/scripts/test-knowledge-engine.js index f0b04bc..8ddcaae 100644 --- a/scripts/test-knowledge-engine.js +++ b/scripts/test-knowledge-engine.js @@ -79,6 +79,7 @@ try { "---", "id: topic-a", "revision: 0", + "summary: test capability rules and boundaries", "primary: policy", "confidence: manual", "---", @@ -94,6 +95,7 @@ try { "---", "id: topic-b", "revision: 0", + "summary: helper topic for dependency checks", "primary: feature", "confidence: manual", "---", @@ -163,6 +165,10 @@ try { fs.readFileSync(path.join(tmpRoot, ".Knowledge", "manifest-routing.json"), "utf8"), ); assert.deepStrictEqual(routing.topicDependencies["topic-a"], ["topic-b"]); + assert.strictEqual( + routing.taskToTopicRules[0].summary, + "test capability rules and boundaries", + ); const staleDelta = { taskId: "task-2", diff --git a/scripts/test-package-install.js b/scripts/test-package-install.js index b65a4fb..41dd61d 100644 --- a/scripts/test-package-install.js +++ b/scripts/test-package-install.js @@ -44,11 +44,12 @@ run("npm", [ ], { cwd: tempDir }); const coreProbe = path.join(tempDir, "core-probe.js"); +const expectedTemplateVersion = require(path.resolve(__dirname, "..", "packages", "core", "package.json")).templateVersion; fs.writeFileSync( coreProbe, "const core = require('@double-coding/flow2spec-core');\n" + "if (core.getCapabilities().protocolVersion !== 2) process.exit(1);\n" + - "if (core.getVersions().templateVersion !== '3.5.0') process.exit(1);\n" + + `if (core.getVersions().templateVersion !== '${expectedTemplateVersion}') process.exit(1);\n` + "if (typeof core.createFlow2Spec({ cwd: process.cwd() }).resources.skillCatalog !== 'function') process.exit(1);\n", "utf8", );