From 46d86bda69ca5866e7529c29a853810210620187 Mon Sep 17 00:00:00 2001 From: liguochuan <37566390+liguochuan00@users.noreply.github.com> Date: Fri, 7 Aug 2026 18:48:59 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20fix(kb):=20=E8=A1=A5?= =?UTF-8?q?=E9=BD=90=E6=97=A7=20topic=20revision=20=E5=85=83=E6=95=B0?= =?UTF-8?q?=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .Knowledge/manifest-routing.json | 414 +++++++++--------- .Knowledge/topics/f2s-config-precheck.md | 102 +++-- .../topics/f2s-dev-workflow-constraints.md | 107 ++--- .Knowledge/topics/f2s-fallback-triage.md | 53 ++- .Knowledge/topics/f2s-flow2spec-milestones.md | 55 ++- .../topics/f2s-flow2spec-presentations.md | 67 +-- .Knowledge/topics/f2s-git-commit.md | 73 +-- .../topics/f2s-implement-tech-design.md | 62 +-- .Knowledge/topics/f2s-init-defaults.md | 242 +++++----- .Knowledge/topics/f2s-kb-distill.md | 217 ++++----- .Knowledge/topics/f2s-req-plan.md | 62 +-- .Knowledge/topics/f2s-req-tech.md | 99 +++-- .../topics/f2s-stock-docs-vs-req-docs.md | 57 +-- .Knowledge/topics/f2s-task.md | 113 ++--- .Knowledge/topics/skill-authoring.md | 173 ++++---- 15 files changed, 997 insertions(+), 899 deletions(-) diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index 5159835..3aa9fbf 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -1,153 +1,149 @@ -{ - "version": "3.2.7", - "knowledgeRoot": ".Knowledge", - "matcherKey": "matcherId", - "sourceOfTruth": ".Knowledge/manifest-routing.json", - "fallbackTopic": "fallback-triage", - "topicDependencies": { +{ + "version": "3.2.7", + "knowledgeRoot": ".Knowledge", + "matcherKey": "matcherId", + "sourceOfTruth": ".Knowledge/manifest-routing.json", + "fallbackTopic": "fallback-triage", + "topicDependencies": { "implement-tech-design": [ - "f2s-doc-routing", - "stock-docs-vs-req-docs" - ], - "f2s-req-plan": [ - "f2s-task" - ], - "flow2spec-collaboration": [ - "f2s-task" - ] - }, - "topicPaths": { - "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md", - "f2s-doc-routing": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md", - "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", - "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", - "f2s-task": ".Knowledge/topics/f2s-task.md", - "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", + "f2s-doc-routing" + ], + "f2s-req-plan": [ + "f2s-task" + ], + "flow2spec-collaboration": [ + "f2s-task" + ] + }, + "topicPaths": { + "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md", + "f2s-doc-routing": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md", + "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", + "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", + "f2s-task": ".Knowledge/topics/f2s-task.md", + "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", "f2s-git-commit": ".Knowledge/topics/f2s-git-commit.md", - "stock-docs-vs-req-docs": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md", - "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md", - "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md", - "skill-authoring": ".Knowledge/topics/skill-authoring.md", - "f2s-req-tech": ".Knowledge/topics/f2s-req-tech.md", - "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md", - "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", - "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", + "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md", + "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md", + "skill-authoring": ".Knowledge/topics/skill-authoring.md", + "f2s-req-tech": ".Knowledge/topics/f2s-req-tech.md", + "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md", + "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", + "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md", "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md" - }, - "taskToTopicRules": [ - { - "task": "f2s-config-precheck", - "matcherId": "m-f2s-config-precheck", - "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", - "topics": [ - "config-precheck" - ] - }, - { - "task": "implement-from-spec", - "matcherId": "m-implement-from-spec", - "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json", - "topics": [ - "f2s-doc-routing", - "implement-tech-design", - "stock-docs-vs-req-docs" - ] - }, - { - "task": "doc-routing", - "matcherId": "m-doc-routing", - "matcherPath": ".Knowledge/matchers/m-doc-routing.json", + }, + "taskToTopicRules": [ + { + "task": "f2s-config-precheck", + "matcherId": "m-f2s-config-precheck", + "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", + "topics": [ + "config-precheck" + ] + }, + { + "task": "implement-from-spec", + "matcherId": "m-implement-from-spec", + "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json", "topics": [ "f2s-doc-routing", - "stock-docs-vs-req-docs" - ] - }, - { - "task": "change-tracking", - "matcherId": "m-change-tracking", - "matcherPath": ".Knowledge/matchers/m-change-tracking.json", - "topics": [ - "f2s-task" - ] - }, - { - "task": "req-plan", - "matcherId": "m-req-plan", - "matcherPath": ".Knowledge/matchers/m-req-plan.json", + "implement-tech-design" + ] + }, + { + "task": "doc-routing", + "matcherId": "m-doc-routing", + "matcherPath": ".Knowledge/matchers/m-doc-routing.json", "topics": [ - "f2s-req-plan" - ] - }, - { - "task": "git-commit", - "matcherId": "m-f2s-git-commit", - "matcherPath": ".Knowledge/matchers/m-f2s-git-commit.json", - "topics": [ - "f2s-git-commit" - ] - }, - { - "task": "flow2spec-presentations", - "matcherId": "m-flow2spec-presentations", - "matcherPath": ".Knowledge/matchers/m-flow2spec-presentations.json", - "topics": [ - "flow2spec-presentations" - ] - }, - { - "task": "flow2spec-milestones", - "matcherId": "m-flow2spec-milestones", - "matcherPath": ".Knowledge/matchers/m-flow2spec-milestones.json", - "topics": [ - "flow2spec-milestones" - ] - }, - { - "task": "skill-authoring", - "matcherId": "m-skill-authoring", - "matcherPath": ".Knowledge/matchers/m-skill-authoring.json", - "topics": [ - "skill-authoring" - ] - }, - { - "task": "req-tech", - "matcherId": "m-req-tech", - "matcherPath": ".Knowledge/matchers/m-req-tech.json", - "topics": [ - "f2s-req-tech" - ] - }, - { - "task": "dev-workflow-constraints", - "matcherId": "m-f2s-dev-workflow-constraints", - "matcherPath": ".Knowledge/matchers/m-f2s-dev-workflow-constraints.json", - "topics": [ - "f2s-dev-workflow-constraints" - ] - }, - { - "task": "kb-distill", - "matcherId": "m-f2s-kb-distill", - "matcherPath": ".Knowledge/matchers/m-f2s-kb-distill.json", - "topics": [ - "f2s-kb-distill" - ] - }, - { - "task": "flow2spec-init-defaults", - "matcherId": "m-flow2spec-init-defaults", - "matcherPath": ".Knowledge/matchers/m-flow2spec-init-defaults.json", - "topics": [ - "flow2spec-init-defaults" - ] - }, + "f2s-doc-routing" + ] + }, + { + "task": "change-tracking", + "matcherId": "m-change-tracking", + "matcherPath": ".Knowledge/matchers/m-change-tracking.json", + "topics": [ + "f2s-task" + ] + }, + { + "task": "req-plan", + "matcherId": "m-req-plan", + "matcherPath": ".Knowledge/matchers/m-req-plan.json", + "topics": [ + "f2s-req-plan" + ] + }, + { + "task": "git-commit", + "matcherId": "m-f2s-git-commit", + "matcherPath": ".Knowledge/matchers/m-f2s-git-commit.json", + "topics": [ + "f2s-git-commit" + ] + }, + { + "task": "flow2spec-presentations", + "matcherId": "m-flow2spec-presentations", + "matcherPath": ".Knowledge/matchers/m-flow2spec-presentations.json", + "topics": [ + "flow2spec-presentations" + ] + }, + { + "task": "flow2spec-milestones", + "matcherId": "m-flow2spec-milestones", + "matcherPath": ".Knowledge/matchers/m-flow2spec-milestones.json", + "topics": [ + "flow2spec-milestones" + ] + }, + { + "task": "skill-authoring", + "matcherId": "m-skill-authoring", + "matcherPath": ".Knowledge/matchers/m-skill-authoring.json", + "topics": [ + "skill-authoring" + ] + }, + { + "task": "req-tech", + "matcherId": "m-req-tech", + "matcherPath": ".Knowledge/matchers/m-req-tech.json", + "topics": [ + "f2s-req-tech" + ] + }, + { + "task": "dev-workflow-constraints", + "matcherId": "m-f2s-dev-workflow-constraints", + "matcherPath": ".Knowledge/matchers/m-f2s-dev-workflow-constraints.json", + "topics": [ + "f2s-dev-workflow-constraints" + ] + }, + { + "task": "kb-distill", + "matcherId": "m-f2s-kb-distill", + "matcherPath": ".Knowledge/matchers/m-f2s-kb-distill.json", + "topics": [ + "f2s-kb-distill" + ] + }, + { + "task": "flow2spec-init-defaults", + "matcherId": "m-flow2spec-init-defaults", + "matcherPath": ".Knowledge/matchers/m-flow2spec-init-defaults.json", + "topics": [ + "flow2spec-init-defaults" + ] + }, { "task": "flow2spec-collaboration", - "matcherId": "m-flow2spec-collaboration", - "matcherPath": ".Knowledge/matchers/m-flow2spec-collaboration.json", - "topics": [ + "matcherId": "m-flow2spec-collaboration", + "matcherPath": ".Knowledge/matchers/m-flow2spec-collaboration.json", + "topics": [ "flow2spec-collaboration" ] }, @@ -158,72 +154,72 @@ "topics": [ "flow2spec-doctor" ] - } - ], - "pkgRev": 1, - "topicMetadata": { - "implement-tech-design": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-doc-routing": { - "primary": "policy", - "confidence": "manual" - }, - "fallback-triage": { - "primary": "policy", - "confidence": "manual" - }, - "config-precheck": { - "primary": "config", - "confidence": "manual", - "tags": [ - "policy" - ] - }, - "f2s-task": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-req-plan": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-git-commit": { - "primary": "policy", - "confidence": "manual" - }, - "flow2spec-presentations": { - "primary": "feature", - "confidence": "inferred" - }, - "flow2spec-milestones": { - "primary": "feature", - "confidence": "inferred" - }, - "skill-authoring": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-req-tech": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-dev-workflow-constraints": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-kb-distill": { - "primary": "policy", - "confidence": "manual" - }, - "flow2spec-init-defaults": { - "primary": "config", - "confidence": "inferred", - "tags": [ - "policy" - ] - }, + } + ], + "pkgRev": 1, + "topicMetadata": { + "implement-tech-design": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-doc-routing": { + "primary": "policy", + "confidence": "manual" + }, + "fallback-triage": { + "primary": "policy", + "confidence": "manual" + }, + "config-precheck": { + "primary": "config", + "confidence": "manual", + "tags": [ + "policy" + ] + }, + "f2s-task": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-req-plan": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-git-commit": { + "primary": "policy", + "confidence": "manual" + }, + "flow2spec-presentations": { + "primary": "feature", + "confidence": "inferred" + }, + "flow2spec-milestones": { + "primary": "feature", + "confidence": "inferred" + }, + "skill-authoring": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-req-tech": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-dev-workflow-constraints": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-kb-distill": { + "primary": "policy", + "confidence": "manual" + }, + "flow2spec-init-defaults": { + "primary": "config", + "confidence": "inferred", + "tags": [ + "policy" + ] + }, "flow2spec-collaboration": { "primary": "feature", "confidence": "manual", @@ -238,5 +234,5 @@ "module" ] } - } -} + } +} diff --git a/.Knowledge/topics/f2s-config-precheck.md b/.Knowledge/topics/f2s-config-precheck.md index 2def7c5..504ffca 100644 --- a/.Knowledge/topics/f2s-config-precheck.md +++ b/.Knowledge/topics/f2s-config-precheck.md @@ -1,47 +1,55 @@ -# config-precheck（路由摘要） - -## 本主题作用 - -- 供 `manifest-routing.topicPaths` 锚定主题 id **`config-precheck`**。 -- 与执行任意 **`f2s-*` 技能**前读取项目根 **`flow2spec.config.json`**（`subAgent`、`switchAgentVerification`、`changeTracking`、`intentRecognition`、`updateCheck`）相关；语义与 **`AGENTS.md`** 顶部、「统一入口」一致。 -- 同时记录 Claude / Cursor / Codex 三端对“配置读取提醒”和“自动更新检测”的分工，避免把 hooks 注入误认为替代显式 Read。 - -## 完整条令（按需，勿在 `.Knowledge` 再维护第二份正文） - -| 侧 | 路径 | -| --- | --- | -| Codex | 仓库根 `.codex/topics/f2s-config-check.md`（init 镜像，与模板同源）；SessionStart：`.codex/hooks/f2s-config-session.js` | -| Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） | -| Claude | `.claude/rules/f2s-config-check.md`；SessionStart：`.claude/hooks/f2s-config-session.js`；PreToolUse 守门：`.claude/hooks/f2s-config-inject.js` | -| 包模板 | `templates/rules/f2s-config-check.mdc` | - -## 必备步骤 - -1. 用 **Read** 打开项目根 **`flow2spec.config.json`**（须在 `f2s-*` 技能正文任何步骤之前）。 -2. **`AGENTS.md`** / `.codex/topics/f2s-config-check.md` 中的配置表仅说明字段语义；当前值以 **Read** 结果为准。 -3. Claude / Codex 的 `SessionStart` 配置摘要与 Claude 的 `PreToolUse Skill` 提醒只做注入 / 提醒；不得替代第 1 步的显式读取。 - -## 三端分工 - -| 侧 | 配置读取约束 | 自动更新检测 | -| --- | --- | --- | -| Claude | `SessionStart` 输出配置摘要；`PreToolUse Skill` 提醒技能前先 Read `flow2spec.config.json` | `SessionStart` 执行 `.claude/hooks/f2s-update-check.js` | -| Cursor | 通过 `.cursor/rules/f2s-config-check.mdc` 文本约束技能前先读配置 | `sessionStart` 执行 `.cursor/hooks/f2s-update-check.js`，通过 `additional_context` 注入提示 | -| Codex | `SessionStart` 输出配置摘要；通过根 `AGENTS.md` 与 `.codex/topics/f2s-config-check.md` 文本约束技能前先读配置 | `SessionStart`（`startup|resume`）执行 `.codex/hooks/f2s-update-check.js`，通过 `hookSpecificOutput.additionalContext` 注入提示 | - -## intentRecognition（意图识别自动分流） - -| 字段 | 行为 | -| --- | --- | -| `intentRecognition: true` | 启用意图识别：高置信操作意图按 `rules/f2s-intent-routing.*` 自动进入对应 Skill；讨论 / 评估 / 低置信输入不得自动调用 | -| `intentRecognition: false` | 不启用自动分流；仅显式 `$f2s-*` / 明确要求执行某技能时进入对应 Skill | -| 字段不存在 | 视为 `false` | - -- 完整路由规则：`rules/f2s-intent-routing.*`（Claude/Cursor）；`.codex/topics/f2s-intent-routing.md`（Codex）。 -- `f2s-intent-routing` 属内部行为规则，不作为独立 topic 路由，不写入 `topicPaths` / `taskToTopicRules`。 - -## 禁止项 - -- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。 -- 禁止因为 hooks 已输出配置摘要，就跳过技能开始时的 `flow2spec.config.json` 显式读取。 -- 禁止在 `intentRecognition` 未读取或为 `false` 时自动调用任何 Skill。 +--- +id: config-precheck +revision: 0 +summary: "config-precheck（路由摘要）" +primary: config +confidence: manual +tags: [policy] +--- +# config-precheck（路由摘要） + +## 本主题作用 + +- 供 `manifest-routing.topicPaths` 锚定主题 id **`config-precheck`**。 +- 与执行任意 **`f2s-*` 技能**前读取项目根 **`flow2spec.config.json`**（`subAgent`、`switchAgentVerification`、`changeTracking`、`intentRecognition`、`updateCheck`）相关；语义与 **`AGENTS.md`** 顶部、「统一入口」一致。 +- 同时记录 Claude / Cursor / Codex 三端对“配置读取提醒”和“自动更新检测”的分工，避免把 hooks 注入误认为替代显式 Read。 + +## 完整条令（按需，勿在 `.Knowledge` 再维护第二份正文） + +| 侧 | 路径 | +| --- | --- | +| Codex | 仓库根 `.codex/topics/f2s-config-check.md`（init 镜像，与模板同源）；SessionStart：`.codex/hooks/f2s-config-session.js` | +| Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） | +| Claude | `.claude/rules/f2s-config-check.md`；SessionStart：`.claude/hooks/f2s-config-session.js`；PreToolUse 守门：`.claude/hooks/f2s-config-inject.js` | +| 包模板 | `templates/rules/f2s-config-check.mdc` | + +## 必备步骤 + +1. 用 **Read** 打开项目根 **`flow2spec.config.json`**（须在 `f2s-*` 技能正文任何步骤之前）。 +2. **`AGENTS.md`** / `.codex/topics/f2s-config-check.md` 中的配置表仅说明字段语义；当前值以 **Read** 结果为准。 +3. Claude / Codex 的 `SessionStart` 配置摘要与 Claude 的 `PreToolUse Skill` 提醒只做注入 / 提醒；不得替代第 1 步的显式读取。 + +## 三端分工 + +| 侧 | 配置读取约束 | 自动更新检测 | +| --- | --- | --- | +| Claude | `SessionStart` 输出配置摘要；`PreToolUse Skill` 提醒技能前先 Read `flow2spec.config.json` | `SessionStart` 执行 `.claude/hooks/f2s-update-check.js` | +| Cursor | 通过 `.cursor/rules/f2s-config-check.mdc` 文本约束技能前先读配置 | `sessionStart` 执行 `.cursor/hooks/f2s-update-check.js`，通过 `additional_context` 注入提示 | +| Codex | `SessionStart` 输出配置摘要；通过根 `AGENTS.md` 与 `.codex/topics/f2s-config-check.md` 文本约束技能前先读配置 | `SessionStart`（`startup|resume`）执行 `.codex/hooks/f2s-update-check.js`，通过 `hookSpecificOutput.additionalContext` 注入提示 | + +## intentRecognition（意图识别自动分流） + +| 字段 | 行为 | +| --- | --- | +| `intentRecognition: true` | 启用意图识别：高置信操作意图按 `rules/f2s-intent-routing.*` 自动进入对应 Skill；讨论 / 评估 / 低置信输入不得自动调用 | +| `intentRecognition: false` | 不启用自动分流；仅显式 `$f2s-*` / 明确要求执行某技能时进入对应 Skill | +| 字段不存在 | 视为 `false` | + +- 完整路由规则：`rules/f2s-intent-routing.*`（Claude/Cursor）；`.codex/topics/f2s-intent-routing.md`（Codex）。 +- `f2s-intent-routing` 属内部行为规则，不作为独立 topic 路由，不写入 `topicPaths` / `taskToTopicRules`。 + +## 禁止项 + +- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。 +- 禁止因为 hooks 已输出配置摘要，就跳过技能开始时的 `flow2spec.config.json` 显式读取。 +- 禁止在 `intentRecognition` 未读取或为 `false` 时自动调用任何 Skill。 diff --git a/.Knowledge/topics/f2s-dev-workflow-constraints.md b/.Knowledge/topics/f2s-dev-workflow-constraints.md index f5c3513..72ede2a 100644 --- a/.Knowledge/topics/f2s-dev-workflow-constraints.md +++ b/.Knowledge/topics/f2s-dev-workflow-constraints.md @@ -1,50 +1,57 @@ -# f2s-dev-workflow-constraints（路由摘要） - -> **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓，**不进 `templates/`**。 - -## 作用 - -约束在 Flow2Spec 本仓内开发时的写盘边界与分发口径，避免「手改配置根被 init 覆盖」「未经用户同意主动跑 init」。 - -## 长文位置（本仓配置根手写，不进 templates） - -- **Cursor**：`.cursor/rules/repo-dev-workflow-constraints.mdc` -- **Claude**：`.claude/rules/repo-dev-workflow-constraints.md` -- **Codex**：`.codex/topics/repo-dev-workflow-constraints.md` - -三份为同源手写副本；执行时按当前 agent 打开对应端。 - -## 核心约束（一句一条） - -1. **只改 `templates/`**：所有下游会用到的规则/技能/主题/matcher/manifest 模板改动，只落 `templates/zh-CN/` 与 `templates/en-US/`。 -2. **不改配置根（下游会用到的产物）**：`.claude/rules/` 等中在 `templates/` 有对应源的文件属 `init` 产物，手改会被覆盖。 -3. **本仓专属手写例外**：`f2s-dev-workflow-constraints`、`repo-dev-check` 等**只**在本仓的规则/技能，直接落配置根，**不进** `templates/`。 -4. **用户驱动分发**：Agent **不主动**跑 `flow2spec init` / `npm run sync:agents`；由用户执行。 - -## 分发命令(用户执行) - -```bash -npm run sync:agents -# 或 -node ./cli.js init codex claude cursor -# 或全局装了 -flow2spec init codex claude cursor -``` - -## 自查技能 - -`repo-dev-check` 用于本仓提交前自查写盘边界与分发口径。触发词见该 SKILL。 - -## 适用场景 / 触发词 - -- 用户提到「templates vs 配置根」「模板 vs 落盘」 -- 用户说「不要改配置根 / 只改 templates / 我来跑 init / 我会自己 sync:agents」 -- Agent 打算改配置根下与 `templates/` 有对应源的文件时须先读本 topic 与对应 rules 长文 -- 分发口径澄清 - -## 边界与禁止项 - -- **仅本仓适用**：下游项目不承担本 topic 约束，不 `Read` 也不生效。 -- **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。 -- `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件，不视为配置根。 - +--- +id: f2s-dev-workflow-constraints +revision: 0 +summary: "f2s-dev-workflow-constraints（路由摘要）" +primary: policy +confidence: inferred +--- +# f2s-dev-workflow-constraints（路由摘要） + +> **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓，**不进 `templates/`**。 + +## 作用 + +约束在 Flow2Spec 本仓内开发时的写盘边界与分发口径，避免「手改配置根被 init 覆盖」「未经用户同意主动跑 init」。 + +## 长文位置（本仓配置根手写，不进 templates） + +- **Cursor**：`.cursor/rules/repo-dev-workflow-constraints.mdc` +- **Claude**：`.claude/rules/repo-dev-workflow-constraints.md` +- **Codex**：`.codex/topics/repo-dev-workflow-constraints.md` + +三份为同源手写副本；执行时按当前 agent 打开对应端。 + +## 核心约束（一句一条） + +1. **只改 `templates/`**：所有下游会用到的规则/技能/主题/matcher/manifest 模板改动，只落 `templates/zh-CN/` 与 `templates/en-US/`。 +2. **不改配置根（下游会用到的产物）**：`.claude/rules/` 等中在 `templates/` 有对应源的文件属 `init` 产物，手改会被覆盖。 +3. **本仓专属手写例外**：`f2s-dev-workflow-constraints`、`repo-dev-check` 等**只**在本仓的规则/技能，直接落配置根，**不进** `templates/`。 +4. **用户驱动分发**：Agent **不主动**跑 `flow2spec init` / `npm run sync:agents`；由用户执行。 + +## 分发命令(用户执行) + +```bash +npm run sync:agents +# 或 +node ./cli.js init codex claude cursor +# 或全局装了 +flow2spec init codex claude cursor +``` + +## 自查技能 + +`repo-dev-check` 用于本仓提交前自查写盘边界与分发口径。触发词见该 SKILL。 + +## 适用场景 / 触发词 + +- 用户提到「templates vs 配置根」「模板 vs 落盘」 +- 用户说「不要改配置根 / 只改 templates / 我来跑 init / 我会自己 sync:agents」 +- Agent 打算改配置根下与 `templates/` 有对应源的文件时须先读本 topic 与对应 rules 长文 +- 分发口径澄清 + +## 边界与禁止项 + +- **仅本仓适用**：下游项目不承担本 topic 约束，不 `Read` 也不生效。 +- **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。 +- `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件，不视为配置根。 + diff --git a/.Knowledge/topics/f2s-fallback-triage.md b/.Knowledge/topics/f2s-fallback-triage.md index feec874..fb2ccd9 100644 --- a/.Knowledge/topics/f2s-fallback-triage.md +++ b/.Knowledge/topics/f2s-fallback-triage.md @@ -1,23 +1,30 @@ -# fallback-triage - -## 执行目的 - -- 本主题仅用于未命中或低置信度场景的分诊与澄清，不用于直接实施业务改动。 -- 当 `fallbackTopic` 被读取时，先补召回与提问，再决定后续执行路径。 - -## 分诊步骤（必须） - -1. 补召回：保留次高候选并补读其依赖主题，检查是否存在更合理主题。 -2. 缺口检查：确认关键主题、边界条件、上下文文档是否齐备。 -3. 澄清提问：向用户确认目标模块、范围、预期行为后再继续。 - -## 澄清问题模板 - -- 你当前要处理的是哪个模块/业务线？ -- 这次改动更偏向“按方案实现”还是“目录与路由分流”？ -- 你希望优先保证完整性还是执行速度（是否需要全量检查）？ - -## 禁止项 - -- 禁止将本主题作为最终命中依据直接实施改动。 -- 禁止跳过澄清直接进入大范围代码修改。 +--- +id: fallback-triage +revision: 0 +summary: fallback-triage +primary: policy +confidence: manual +--- +# fallback-triage + +## 执行目的 + +- 本主题仅用于未命中或低置信度场景的分诊与澄清，不用于直接实施业务改动。 +- 当 `fallbackTopic` 被读取时，先补召回与提问，再决定后续执行路径。 + +## 分诊步骤（必须） + +1. 补召回：保留次高候选并补读其依赖主题，检查是否存在更合理主题。 +2. 缺口检查：确认关键主题、边界条件、上下文文档是否齐备。 +3. 澄清提问：向用户确认目标模块、范围、预期行为后再继续。 + +## 澄清问题模板 + +- 你当前要处理的是哪个模块/业务线？ +- 这次改动更偏向“按方案实现”还是“目录与路由分流”？ +- 你希望优先保证完整性还是执行速度（是否需要全量检查）？ + +## 禁止项 + +- 禁止将本主题作为最终命中依据直接实施改动。 +- 禁止跳过澄清直接进入大范围代码修改。 diff --git a/.Knowledge/topics/f2s-flow2spec-milestones.md b/.Knowledge/topics/f2s-flow2spec-milestones.md index f145623..56aa2f6 100644 --- a/.Knowledge/topics/f2s-flow2spec-milestones.md +++ b/.Knowledge/topics/f2s-flow2spec-milestones.md @@ -1,24 +1,31 @@ -# flow2spec-milestones - -## 执行边界 - -- 本主题用于回答 **Flow2Spec 产品仓自身** 的版本演进、阶段划分与能力落地时间线。 -- **禁止**将里程碑正文当作业务实现的 `req-docs`；归属 `stock-docs` 索源。 - -## 目标 - -当用户询问「项目里程碑」「版本演进」「开源和内部仓区别」「双语 PPT」「Cursor 插件提交」时： - -1. 读 [项目里程碑](../stock-docs/项目里程碑.md)：**版本能力表** + M1–M18（最新阶段在前）。 -2. 演示路径：内部 `flow2spec-intro-draft` + `sync-pages.sh`；开源 `flow2spec-intro-public`（中）与 `-public-en`（英）+ `sync-gh-pages.sh`。 -3. 架构细节 → `flow2spec架构说明_终稿.md`；演示约定 → `flow2spec-presentations` 主题。 - -## 格式约定（f2s-doc-milestone 生成物） - -- 阶段**最新在前**（MN → M1）；不含索源行、commit hash 或内部运维状态 -- 每阶段只列已交付功能点；「待确认」仅写功能/交付层面缺口 - -## 下一步 - -- 全文：[项目里程碑](../stock-docs/项目里程碑.md) -- 架构：[flow2spec架构说明_终稿](../stock-docs/flow2spec架构说明_终稿.md) +--- +id: flow2spec-milestones +revision: 0 +summary: flow2spec-milestones +primary: feature +confidence: inferred +--- +# flow2spec-milestones + +## 执行边界 + +- 本主题用于回答 **Flow2Spec 产品仓自身** 的版本演进、阶段划分与能力落地时间线。 +- **禁止**将里程碑正文当作业务实现的 `req-docs`；归属 `stock-docs` 索源。 + +## 目标 + +当用户询问「项目里程碑」「版本演进」「开源和内部仓区别」「双语 PPT」「Cursor 插件提交」时： + +1. 读 [项目里程碑](../stock-docs/项目里程碑.md)：**版本能力表** + M1–M18（最新阶段在前）。 +2. 演示路径：内部 `flow2spec-intro-draft` + `sync-pages.sh`；开源 `flow2spec-intro-public`（中）与 `-public-en`（英）+ `sync-gh-pages.sh`。 +3. 架构细节 → `flow2spec架构说明_终稿.md`；演示约定 → `flow2spec-presentations` 主题。 + +## 格式约定（f2s-doc-milestone 生成物） + +- 阶段**最新在前**（MN → M1）；不含索源行、commit hash 或内部运维状态 +- 每阶段只列已交付功能点；「待确认」仅写功能/交付层面缺口 + +## 下一步 + +- 全文：[项目里程碑](../stock-docs/项目里程碑.md) +- 架构：[flow2spec架构说明_终稿](../stock-docs/flow2spec架构说明_终稿.md) diff --git a/.Knowledge/topics/f2s-flow2spec-presentations.md b/.Knowledge/topics/f2s-flow2spec-presentations.md index 4e64335..f2199e2 100644 --- a/.Knowledge/topics/f2s-flow2spec-presentations.md +++ b/.Knowledge/topics/f2s-flow2spec-presentations.md @@ -1,30 +1,37 @@ -# flow2spec-presentations - -## 执行边界 - -- 本主题用于说明本仓库内 Flow2Spec 对外网站与遗留 HTML 演示稿的位置、预览方式和维护边界。 -- 对外材料归属 `stock-docs` 索源说明，不作为 `req-docs` 驱动业务实现。 - -## 目标 - -当用户询问「宣传网站」「Astro 官网」「对外演示」「presentations 目录」时，命中本主题后： - -1. 网站源码位于 `website/`，使用 Astro 构建；中文入口为 `/`，英文入口为 `/en/`。 -2. 网站采用滚动式产品叙事：首页 Hero 独立占满顶部导航以下的首屏，正文区从下一屏开始并提供固定章节侧栏；移动端提供可展开导航；视觉方向为 `mailchimp-freddie` 暖人文风格。 -3. `presentations/flow2spec-intro-public/` 与 `presentations/flow2spec-intro-public-en/` 保留为旧演示稿和内容素材。 -4. 首版网站不接管 `scripts/sync-gh-pages.sh`；确认设计后再切换线上发布链路。 -5. 需要架构级背景时，可再读 `f2s-flow2spec-architecture` 主题。 - -## 边界 - -- `docs/` 与 `docs/en/` 中的 Markdown 是完整参考的唯一内容源；Astro 构建时读取原文，统一套用文章布局、目录、代码块、表格、图片和链接样式，不复制或重写正文。 -- 顶部导航指向网站内部的文档文章页；构建阶段把 Markdown 内部 `.md` 链接与 `docs/images/` 图片改写为站内路径。 -- 首页和文章页左侧目录由页面标题生成，并按滚动位置自动高亮当前章节；目录只保留章节链接，不显示标题、说明或分割线；移动端目录收进顶部可展开导航。 -- 首页 Hero 结束后才显示正文区和左侧目录；文章页不显示参考计数，Markdown 顶部的中英文切换段由构建阶段移除，语言入口统一位于右上角。 -- 桌面文档侧栏的间距按侧栏自身宽度计算，横向溢出隐藏；低高度视口内容实际溢出时才启用纵向滚动。 -- 遗留演示稿仍依赖 `.claude/skills/html-ppt/assets/`，移动或独立发布时须同步处理资源路径。 - -## 下一步 - -- 索源与路径表：[对外网站与演示](../stock-docs/Flow2Spec-对外介绍演示.md) -- 架构总览：`.Knowledge/topics/f2s-flow2spec-architecture.md` +--- +id: flow2spec-presentations +revision: 0 +summary: flow2spec-presentations +primary: feature +confidence: inferred +--- +# flow2spec-presentations + +## 执行边界 + +- 本主题用于说明本仓库内 Flow2Spec 对外网站与遗留 HTML 演示稿的位置、预览方式和维护边界。 +- 对外材料归属 `stock-docs` 索源说明，不作为 `req-docs` 驱动业务实现。 + +## 目标 + +当用户询问「宣传网站」「Astro 官网」「对外演示」「presentations 目录」时，命中本主题后： + +1. 网站源码位于 `website/`，使用 Astro 构建；中文入口为 `/`，英文入口为 `/en/`。 +2. 网站采用滚动式产品叙事：首页 Hero 独立占满顶部导航以下的首屏，正文区从下一屏开始并提供固定章节侧栏；移动端提供可展开导航；视觉方向为 `mailchimp-freddie` 暖人文风格。 +3. `presentations/flow2spec-intro-public/` 与 `presentations/flow2spec-intro-public-en/` 保留为旧演示稿和内容素材。 +4. 首版网站不接管 `scripts/sync-gh-pages.sh`；确认设计后再切换线上发布链路。 +5. 需要架构级背景时，可再读 `f2s-flow2spec-architecture` 主题。 + +## 边界 + +- `docs/` 与 `docs/en/` 中的 Markdown 是完整参考的唯一内容源；Astro 构建时读取原文，统一套用文章布局、目录、代码块、表格、图片和链接样式，不复制或重写正文。 +- 顶部导航指向网站内部的文档文章页；构建阶段把 Markdown 内部 `.md` 链接与 `docs/images/` 图片改写为站内路径。 +- 首页和文章页左侧目录由页面标题生成，并按滚动位置自动高亮当前章节；目录只保留章节链接，不显示标题、说明或分割线；移动端目录收进顶部可展开导航。 +- 首页 Hero 结束后才显示正文区和左侧目录；文章页不显示参考计数，Markdown 顶部的中英文切换段由构建阶段移除，语言入口统一位于右上角。 +- 桌面文档侧栏的间距按侧栏自身宽度计算，横向溢出隐藏；低高度视口内容实际溢出时才启用纵向滚动。 +- 遗留演示稿仍依赖 `.claude/skills/html-ppt/assets/`，移动或独立发布时须同步处理资源路径。 + +## 下一步 + +- 索源与路径表：[对外网站与演示](../stock-docs/Flow2Spec-对外介绍演示.md) +- 架构总览：`.Knowledge/topics/f2s-flow2spec-architecture.md` diff --git a/.Knowledge/topics/f2s-git-commit.md b/.Knowledge/topics/f2s-git-commit.md index 95edaf3..03f7afd 100644 --- a/.Knowledge/topics/f2s-git-commit.md +++ b/.Knowledge/topics/f2s-git-commit.md @@ -1,33 +1,40 @@ -# f2s-git-commit（路由摘要） - -> 长文见配置根 **`skills/f2s-git-commit/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-git-commit/SKILL.md`**。 - -## 作用 - -提交代码时统一执行 Git 提交流程：读取变更、检查冲突、按实际 diff 生成提交信息、精确 add 文件并执行 `git commit`。默认模式会检查知识库覆盖；快捷提交模式只跳过这一步。 - -## 适用场景 / 触发词 - -- 用户触发 `f2s-git-commit`、`git commit`、提交代码、帮我提交。 -- 用户明确说“快捷提交”“快速提交”或 “quick commit”。 -- 用户询问提交流程、知识库覆盖检查、`--no-verify`、`git add -A` 等提交流程约束。 - -## 核心规则 - -1. **默认模式**：步骤 2 必须检查知识库覆盖，从 `git diff HEAD` 与 untracked 文件推断能力模块，并对照 `.Knowledge/topics/` 与 `.Knowledge/stock-docs/`。 -2. **快捷提交模式**：仅当用户本轮明确说“快捷提交”“快速提交”或 “quick commit” 时，跳过步骤 2 知识库覆盖检查。 -3. 快捷提交不跳过变更读取、merge conflict 标记检查、提交信息首行展示、精确 `git add <文件列表>`、正常 `git commit` 和 git hooks。 -4. 提交信息首行必须展示后再 commit，格式为 ` [(scope)]: <简述>`。 - -## 禁止项 - -- 禁止因为快捷提交而使用 `git add -A` 或 `git add .`。 -- 禁止因为快捷提交而使用 `--no-verify` 跳过 hooks。 -- 禁止自动 push。 -- 禁止为 commit 静默执行 `git pull` / `git pull --rebase`；涉及拉取必须先取得用户明确确认。 - -## 下一步 - -- 技能全文：`skills/f2s-git-commit/SKILL.md` -- 模板源：`templates/skills/f2s-git-commit/SKILL.md` -- 命令说明：`docs/命令说明.md` +--- +id: f2s-git-commit +revision: 0 +summary: "f2s-git-commit（路由摘要）" +primary: policy +confidence: manual +--- +# f2s-git-commit（路由摘要） + +> 长文见配置根 **`skills/f2s-git-commit/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-git-commit/SKILL.md`**。 + +## 作用 + +提交代码时统一执行 Git 提交流程：读取变更、检查冲突、按实际 diff 生成提交信息、精确 add 文件并执行 `git commit`。默认模式会检查知识库覆盖；快捷提交模式只跳过这一步。 + +## 适用场景 / 触发词 + +- 用户触发 `f2s-git-commit`、`git commit`、提交代码、帮我提交。 +- 用户明确说“快捷提交”“快速提交”或 “quick commit”。 +- 用户询问提交流程、知识库覆盖检查、`--no-verify`、`git add -A` 等提交流程约束。 + +## 核心规则 + +1. **默认模式**：步骤 2 必须检查知识库覆盖，从 `git diff HEAD` 与 untracked 文件推断能力模块，并对照 `.Knowledge/topics/` 与 `.Knowledge/stock-docs/`。 +2. **快捷提交模式**：仅当用户本轮明确说“快捷提交”“快速提交”或 “quick commit” 时，跳过步骤 2 知识库覆盖检查。 +3. 快捷提交不跳过变更读取、merge conflict 标记检查、提交信息首行展示、精确 `git add <文件列表>`、正常 `git commit` 和 git hooks。 +4. 提交信息首行必须展示后再 commit，格式为 ` [(scope)]: <简述>`。 + +## 禁止项 + +- 禁止因为快捷提交而使用 `git add -A` 或 `git add .`。 +- 禁止因为快捷提交而使用 `--no-verify` 跳过 hooks。 +- 禁止自动 push。 +- 禁止为 commit 静默执行 `git pull` / `git pull --rebase`；涉及拉取必须先取得用户明确确认。 + +## 下一步 + +- 技能全文：`skills/f2s-git-commit/SKILL.md` +- 模板源：`templates/skills/f2s-git-commit/SKILL.md` +- 命令说明：`docs/命令说明.md` diff --git a/.Knowledge/topics/f2s-implement-tech-design.md b/.Knowledge/topics/f2s-implement-tech-design.md index 7a22f2e..388e34e 100644 --- a/.Knowledge/topics/f2s-implement-tech-design.md +++ b/.Knowledge/topics/f2s-implement-tech-design.md @@ -1,27 +1,35 @@ -# implement-tech-design（路由摘要） - -> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。 -> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-implement-tech-design.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 - -## 本文件作用 - -- 供 `manifest-routing.topicPaths` 与 `index.md` 锚定主题 id **`implement-tech-design`**。 -- 仅保留**路径与角色**记忆点，避免与 `rules/` 双份维护长文。 - -## 路径与角色（须与规则一致） - -- 技术方案输入：`.Knowledge/req-docs/*.md`（及 PDF 经 `f2s-doc-pdf` 落入同目录的 MD）。 -- 存量沉淀：`.Knowledge/stock-docs/` — **不**作为「按方案写代码」的直接输入。 - -## changeTracking 集成 - -若 `flow2spec.config.json` 中 `changeTracking.implement: true`： -- 步骤 2.5 输出任务列表后，同步写入 `.task/active//task.md` -- 步骤 5 收尾时归档至 `.task/completed/-/`，并从 `todo.json` 删除条目 - -## 下一步读什么 - -| 环境 | 下一步 | -| --- | --- | -| Cursor / Claude | 打开或 @ **`rules/f2s-implement-tech-design`**，按其中步骤执行。 | -| Codex | 读 **`.codex/topics/f2s-implement-tech-design.md`**。 | +--- +id: implement-tech-design +revision: 0 +summary: "implement-tech-design（路由摘要）" +dependsOn: [f2s-doc-routing] +primary: policy +confidence: manual +--- +# implement-tech-design（路由摘要） + +> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。 +> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-implement-tech-design.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 + +## 本文件作用 + +- 供 `manifest-routing.topicPaths` 与 `index.md` 锚定主题 id **`implement-tech-design`**。 +- 仅保留**路径与角色**记忆点，避免与 `rules/` 双份维护长文。 + +## 路径与角色（须与规则一致） + +- 技术方案输入：`.Knowledge/req-docs/*.md`（及 PDF 经 `f2s-doc-pdf` 落入同目录的 MD）。 +- 存量沉淀：`.Knowledge/stock-docs/` — **不**作为「按方案写代码」的直接输入。 + +## changeTracking 集成 + +若 `flow2spec.config.json` 中 `changeTracking.implement: true`： +- 步骤 2.5 输出任务列表后，同步写入 `.task/active//task.md` +- 步骤 5 收尾时归档至 `.task/completed/-/`，并从 `todo.json` 删除条目 + +## 下一步读什么 + +| 环境 | 下一步 | +| --- | --- | +| Cursor / Claude | 打开或 @ **`rules/f2s-implement-tech-design`**，按其中步骤执行。 | +| Codex | 读 **`.codex/topics/f2s-implement-tech-design.md`**。 | diff --git a/.Knowledge/topics/f2s-init-defaults.md b/.Knowledge/topics/f2s-init-defaults.md index 1567a8c..e0c6f32 100644 --- a/.Knowledge/topics/f2s-init-defaults.md +++ b/.Knowledge/topics/f2s-init-defaults.md @@ -1,117 +1,125 @@ -# flow2spec-init-defaults（路由摘要） - -## 作用 - -`flow2spec init` 写入项目根 `flow2spec.config.json` 时使用的默认值与字段语义；老项目缺字段时按本表补写。本主题只描述「生产侧」（init 写什么），不涉及「消费侧」（技能执行前如何 Read），后者见 `config-precheck`。 - -## 默认值的四处一致性 - -`flow2spec init` 的默认值与字段语义由 npm 包源码四处共同决定，四处必须保持一致： - -| 落点 | 角色 | 路径 | -| --- | --- | --- | -| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `lib/flow2specConfig.js` | -| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `lib/flow2specConfig.js` | -| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `templates/{zh-CN,en-US}/flow2spec.config.json` | -| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `lib/codexAgentsAdapter.js` | - -不一致的后果： - -- `DEFAULTS` 与 `CONFIG_FIELDS[].default` 不一致 → 交互回车值与「缺字段时实际生效值」不一致，调试时令人困惑。 -- `CONFIG_FIELDS[].default` 与模板不一致 → 同一字段在「首次 init」和「老项目补字段 init」两条路径下落盘值不同。 -- 包源/模板与 `renderProjectConfigBlock` 不一致 → Codex `AGENTS.md` 表中宣称的「init 默认」与实际落盘值脱节，用户读文档与读 config 看到不同结论。 - -修改默认值时必须四处同步改；如需追加新字段，按 `CONFIG_FIELDS` 注释要求在该数组追加描述项即可，`cli.js` 会自动对缺失字段发起提问；同时也要在 `renderProjectConfigBlock` 表中追加一行（含「init 默认」列）。 - -## 字段语义与默认值（与包模板同源） - -| 字段 | 类型 | 当前默认值 | 语义 | -| --- | --- | --- | --- | -| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 `templates//` | -| `subAgent` | boolean | `true` | 是否允许技能拆子 agent；`false` 时主 agent 全流程；详见 `f2s-flow2spec-unified-entry` | -| `switchAgentVerification` | boolean | `true` | 切换 agent 校验；`true` 且技能正文绑定时启用交叉校验；旧键 `subAgentVerification` 仍兼容 | -| `intentRecognition` | boolean | `true` | 高置信操作意图是否按 `f2s-intent-routing` 自动进入对应 `f2s-*` 技能 | -| `changeTracking.feat` | boolean | `true` | `f2s-kb-feat` 是否走 `.task/` 变更追踪 | -| `changeTracking.fix` | boolean | `false` | `f2s-kb-fix` 是否走 `.task/` 变更追踪 | -| `changeTracking.implement` | boolean | `true` | `f2s-implement-tech-design` 是否走 `.task/` 变更追踪 | -| `updateCheck.enabled` | boolean | `true` | 是否启用每日版本更新提示 | - -「当前默认值」一栏以包模板 `templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。 - -### 默认值变更记录 - -- **2026-06**：`subAgent` / `switchAgentVerification` / `intentRecognition` 三项默认值由 `false` 翻面为 `true`。新项目 init 默认即开启子 agent 编排、交叉校验与意图识别自动分流。老项目（已写过这三项）不受影响；仅在升级时**仍缺该字段**的老项目会按新默认 `true` 补齐。`changeTracking.fix` 维持 `false`（显式排除翻面）。 - -## 旧值与字段兼容 - -`loadFlow2specConfig` 在解析既有 `flow2spec.config.json` 时做了两类回退： - -- **`changeTracking` 顶层布尔**：旧版本可能写 `changeTracking: true` / `false`，会展开为 `{ feat, fix, implement }` 三子项同值，便于一次性升级。 -- **`subAgentVerification`（旧键）**：仍读为 `switchAgentVerification` 的值；**新落盘必须用 `switchAgentVerification`**，旧键不再写出。 - -## 老项目 init 升级路径 - -`flow2spec init` 在已有 `flow2spec.config.json` 时走 `getMissingConfigFields`： - -1. 解析既有文件；非对象或解析失败 → 不打扰，仅做规则与目录骨架对齐。 -2. 与 `CONFIG_FIELDS` 比对： - - 已在文件中（含旧版顶层布尔的 `changeTracking`）→ 跳过，不重复询问、不覆盖用户值。 - - 缺失的字段 → 重新询问（默认值按 `CONFIG_FIELDS[].default`），用户确认后写入。 -3. 已有字段的取值**始终不被 init 覆盖**；用户手工改过的值（如把 `false` 改成 `true`）会被保留。 - -含义：升级 npm 包后新增的字段，会以「当前 `CONFIG_FIELDS` 默认值」补齐到老项目；如新版本默认值翻面（例如某字段由 `false` 改为 `true`），**只影响**升级时**仍缺该字段**的老项目，已写过该字段的项目不变。 - -### 跑 `f2s-kb-upgrade` 时怎么让全局 flow2spec 保持最新 - -`f2s-kb-upgrade` SKILL 的「步骤 -1」（先于一切）**先做前台探测再决定是否升级**：主 agent 顺序跑 `flow2spec --version` + `npm view @double-coding/flow2spec version` + `command -v npx`，按 3 分支处理： - -- **A. 已装且是 latest** → **完全跳过**升级；步骤 2 命令首选 `flow2spec init `。 -- **B. 已装但落后** → 派**独立子 agent** 后台跑 `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；步骤 2 命令用 `npx @double-coding/flow2spec@latest init ` 保证本次拿到 latest 模板。 -- **C. 未装 / latest 未知** → 同 B 处理；探测全部失败时可放弃步骤 -1，由 cli.js 兜底。 - -口径： - -- **仅** B/C 时才派子 agent；派子**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）； -- 派子是 fire-and-forget，结果不进入 SKILL 结论摘要——失败也只是"下次再升一次"； -- 与 `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 不冲突：前者是 SKILL 入口按需异步派工，后者是 `init` 收尾兜底；两次都成功就是 no-op。 -- 用户自查用 `flow2spec --version`（当前全局版本）和 `flow2spec update`（CLI 内置自更新）。 - -## init 不动哪些目录 - -`flow2spec init` 仅对齐： - -- 配置根（Claude `.claude/` / Cursor `.cursor/` / Codex `.codex/`）下的 **rules / skills / hooks 模板** 与 SessionStart / PreToolUse 钩子注册； -- 包级 **manifest 路由结构骨架**（`flow2spec init` 通过 `manifest-matchers.json` 作为种子合并 matcher 分片）； -- 项目根 `flow2spec.config.json` 的缺失字段； -- 项目侧 `.Knowledge/manifest-routing.json` 的 `pkgRev` 顶层字段（每次 init 覆盖；详见下节「manifest 中的两个版本字段」）。 - -`init` **不修改**业务知识库内容： - -- `.Knowledge/stock-docs/`、`.Knowledge/req-docs/` -- `.Knowledge/topics/.md` 的路由摘要正文 -- `.Knowledge/matchers/.json` 的 `includeAny` 词条 - -这些由 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` 等 `f2s-*` 技能维护。把 `flow2spec init` 当作「业务知识库已更新」是常见误判（见统一入口 2a）。 - -## manifest 中的两个版本字段 - -`.Knowledge/manifest-routing.json` 同时存在两个顶层整数字段，对应 `f2s-kb-upgrade` 步骤 2c 的两侧： - -| 字段 | 语义 | 写入方 | -| --- | --- | --- | -| `projectRev` | **本项目已基线对齐到的包模板修订号** | `f2s-kb-upgrade` 完整流程末尾（3b）；首次 init 也按模板写入一次 | -| `pkgRev` | **本次 init 用的包模板修订号** | `flow2spec init`（每次都按当前包模板覆盖） | - -人读对照： - -- 两值**相等** → 主题层未变，`f2s-kb-upgrade` 走快速路径 -- `projectRev` 缺失 / `pkgRev` 大于 `projectRev` → 完整流程 -- `pkgRev` 缺失 → 包模板自身未声明该字段，SKILL 走兜底完整流程 - -`f2s-kb-upgrade` 步骤 2c 直接 `Read` 同一文件取这两个字段比对。 - -## 禁止项 - -- 禁止只改 `lib/flow2specConfig.js` 的 `DEFAULTS` 或 `CONFIG_FIELDS`、不同步改 `templates/{locale}/flow2spec.config.json` 与 `lib/codexAgentsAdapter.js` 的 `renderProjectConfigBlock`（四处必须同步）。 -- 禁止在新落盘中写出旧键 `subAgentVerification`。 -- 禁止把 `init` 作为业务知识库同步的入口；新增 / 修改 stock-docs / topics / matchers 走 `f2s-*` 技能。 +--- +id: flow2spec-init-defaults +revision: 0 +summary: "flow2spec-init-defaults（路由摘要）" +primary: config +confidence: inferred +tags: [policy] +--- +# flow2spec-init-defaults（路由摘要） + +## 作用 + +`flow2spec init` 写入项目根 `flow2spec.config.json` 时使用的默认值与字段语义；老项目缺字段时按本表补写。本主题只描述「生产侧」（init 写什么），不涉及「消费侧」（技能执行前如何 Read），后者见 `config-precheck`。 + +## 默认值的四处一致性 + +`flow2spec init` 的默认值与字段语义由 npm 包源码四处共同决定，四处必须保持一致： + +| 落点 | 角色 | 路径 | +| --- | --- | --- | +| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `lib/flow2specConfig.js` | +| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `lib/flow2specConfig.js` | +| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `templates/{zh-CN,en-US}/flow2spec.config.json` | +| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `lib/codexAgentsAdapter.js` | + +不一致的后果： + +- `DEFAULTS` 与 `CONFIG_FIELDS[].default` 不一致 → 交互回车值与「缺字段时实际生效值」不一致，调试时令人困惑。 +- `CONFIG_FIELDS[].default` 与模板不一致 → 同一字段在「首次 init」和「老项目补字段 init」两条路径下落盘值不同。 +- 包源/模板与 `renderProjectConfigBlock` 不一致 → Codex `AGENTS.md` 表中宣称的「init 默认」与实际落盘值脱节，用户读文档与读 config 看到不同结论。 + +修改默认值时必须四处同步改；如需追加新字段，按 `CONFIG_FIELDS` 注释要求在该数组追加描述项即可，`cli.js` 会自动对缺失字段发起提问；同时也要在 `renderProjectConfigBlock` 表中追加一行（含「init 默认」列）。 + +## 字段语义与默认值（与包模板同源） + +| 字段 | 类型 | 当前默认值 | 语义 | +| --- | --- | --- | --- | +| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 `templates//` | +| `subAgent` | boolean | `true` | 是否允许技能拆子 agent；`false` 时主 agent 全流程；详见 `f2s-flow2spec-unified-entry` | +| `switchAgentVerification` | boolean | `true` | 切换 agent 校验；`true` 且技能正文绑定时启用交叉校验；旧键 `subAgentVerification` 仍兼容 | +| `intentRecognition` | boolean | `true` | 高置信操作意图是否按 `f2s-intent-routing` 自动进入对应 `f2s-*` 技能 | +| `changeTracking.feat` | boolean | `true` | `f2s-kb-feat` 是否走 `.task/` 变更追踪 | +| `changeTracking.fix` | boolean | `false` | `f2s-kb-fix` 是否走 `.task/` 变更追踪 | +| `changeTracking.implement` | boolean | `true` | `f2s-implement-tech-design` 是否走 `.task/` 变更追踪 | +| `updateCheck.enabled` | boolean | `true` | 是否启用每日版本更新提示 | + +「当前默认值」一栏以包模板 `templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。 + +### 默认值变更记录 + +- **2026-06**：`subAgent` / `switchAgentVerification` / `intentRecognition` 三项默认值由 `false` 翻面为 `true`。新项目 init 默认即开启子 agent 编排、交叉校验与意图识别自动分流。老项目（已写过这三项）不受影响；仅在升级时**仍缺该字段**的老项目会按新默认 `true` 补齐。`changeTracking.fix` 维持 `false`（显式排除翻面）。 + +## 旧值与字段兼容 + +`loadFlow2specConfig` 在解析既有 `flow2spec.config.json` 时做了两类回退： + +- **`changeTracking` 顶层布尔**：旧版本可能写 `changeTracking: true` / `false`，会展开为 `{ feat, fix, implement }` 三子项同值，便于一次性升级。 +- **`subAgentVerification`（旧键）**：仍读为 `switchAgentVerification` 的值；**新落盘必须用 `switchAgentVerification`**，旧键不再写出。 + +## 老项目 init 升级路径 + +`flow2spec init` 在已有 `flow2spec.config.json` 时走 `getMissingConfigFields`： + +1. 解析既有文件；非对象或解析失败 → 不打扰，仅做规则与目录骨架对齐。 +2. 与 `CONFIG_FIELDS` 比对： + - 已在文件中（含旧版顶层布尔的 `changeTracking`）→ 跳过，不重复询问、不覆盖用户值。 + - 缺失的字段 → 重新询问（默认值按 `CONFIG_FIELDS[].default`），用户确认后写入。 +3. 已有字段的取值**始终不被 init 覆盖**；用户手工改过的值（如把 `false` 改成 `true`）会被保留。 + +含义：升级 npm 包后新增的字段，会以「当前 `CONFIG_FIELDS` 默认值」补齐到老项目；如新版本默认值翻面（例如某字段由 `false` 改为 `true`），**只影响**升级时**仍缺该字段**的老项目，已写过该字段的项目不变。 + +### 跑 `f2s-kb-upgrade` 时怎么让全局 flow2spec 保持最新 + +`f2s-kb-upgrade` SKILL 的「步骤 -1」（先于一切）**先做前台探测再决定是否升级**：主 agent 顺序跑 `flow2spec --version` + `npm view @double-coding/flow2spec version` + `command -v npx`，按 3 分支处理： + +- **A. 已装且是 latest** → **完全跳过**升级；步骤 2 命令首选 `flow2spec init `。 +- **B. 已装但落后** → 派**独立子 agent** 后台跑 `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；步骤 2 命令用 `npx @double-coding/flow2spec@latest init ` 保证本次拿到 latest 模板。 +- **C. 未装 / latest 未知** → 同 B 处理；探测全部失败时可放弃步骤 -1，由 cli.js 兜底。 + +口径： + +- **仅** B/C 时才派子 agent；派子**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）； +- 派子是 fire-and-forget，结果不进入 SKILL 结论摘要——失败也只是"下次再升一次"； +- 与 `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 不冲突：前者是 SKILL 入口按需异步派工，后者是 `init` 收尾兜底；两次都成功就是 no-op。 +- 用户自查用 `flow2spec --version`（当前全局版本）和 `flow2spec update`（CLI 内置自更新）。 + +## init 不动哪些目录 + +`flow2spec init` 仅对齐： + +- 配置根（Claude `.claude/` / Cursor `.cursor/` / Codex `.codex/`）下的 **rules / skills / hooks 模板** 与 SessionStart / PreToolUse 钩子注册； +- 包级 **manifest 路由结构骨架**（`flow2spec init` 通过 `manifest-matchers.json` 作为种子合并 matcher 分片）； +- 项目根 `flow2spec.config.json` 的缺失字段； +- 项目侧 `.Knowledge/manifest-routing.json` 的 `pkgRev` 顶层字段（每次 init 覆盖；详见下节「manifest 中的两个版本字段」）。 + +`init` **不修改**业务知识库内容： + +- `.Knowledge/stock-docs/`、`.Knowledge/req-docs/` +- `.Knowledge/topics/.md` 的路由摘要正文 +- `.Knowledge/matchers/.json` 的 `includeAny` 词条 + +这些由 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` 等 `f2s-*` 技能维护。把 `flow2spec init` 当作「业务知识库已更新」是常见误判（见统一入口 2a）。 + +## manifest 中的两个版本字段 + +`.Knowledge/manifest-routing.json` 同时存在两个顶层整数字段，对应 `f2s-kb-upgrade` 步骤 2c 的两侧： + +| 字段 | 语义 | 写入方 | +| --- | --- | --- | +| `projectRev` | **本项目已基线对齐到的包模板修订号** | `f2s-kb-upgrade` 完整流程末尾（3b）；首次 init 也按模板写入一次 | +| `pkgRev` | **本次 init 用的包模板修订号** | `flow2spec init`（每次都按当前包模板覆盖） | + +人读对照： + +- 两值**相等** → 主题层未变，`f2s-kb-upgrade` 走快速路径 +- `projectRev` 缺失 / `pkgRev` 大于 `projectRev` → 完整流程 +- `pkgRev` 缺失 → 包模板自身未声明该字段，SKILL 走兜底完整流程 + +`f2s-kb-upgrade` 步骤 2c 直接 `Read` 同一文件取这两个字段比对。 + +## 禁止项 + +- 禁止只改 `lib/flow2specConfig.js` 的 `DEFAULTS` 或 `CONFIG_FIELDS`、不同步改 `templates/{locale}/flow2spec.config.json` 与 `lib/codexAgentsAdapter.js` 的 `renderProjectConfigBlock`（四处必须同步）。 +- 禁止在新落盘中写出旧键 `subAgentVerification`。 +- 禁止把 `init` 作为业务知识库同步的入口；新增 / 修改 stock-docs / topics / matchers 走 `f2s-*` 技能。 diff --git a/.Knowledge/topics/f2s-kb-distill.md b/.Knowledge/topics/f2s-kb-distill.md index 8506c31..a380bba 100644 --- a/.Knowledge/topics/f2s-kb-distill.md +++ b/.Knowledge/topics/f2s-kb-distill.md @@ -1,105 +1,112 @@ -# f2s-kb-distill：Q&A 驱动知识提取与入库 - -Q&A 驱动知识提取技能，从普通问答中自动萃取可复用知识事实并入库；根据下钻深度与描述层次自动判断创建新 topic 或追加到现有 topic。 - -## 适用场景 - -- 用户提问 → Agent 下钻源码回答 → 需要将发现的知识固化到知识库 -- 通常由 `f2s-kb-feedback-closing` 规则自动建议，也可用户手动调用 -- 与 `f2s-kb-sync` 区别：`sync` 用于批量同步多个能力；`distill` 专注单次 Q&A 知识提取 - -## 执行前依赖 - -本技能执行前须先读以下主题： - -- **`f2s-kb-feedback-closing`**：定义"可复用知识事实"边界（核心机制、状态流转、契约、配置影响、失败回退、模块边界、数据模型） -- **`f2s-topic-authoring`**：创建/修改 topic 时的命名、骨架、metadata、dependencies 准则 - -## 核心流程 - -### 执行挡位（agent 自动判，无命令参数） - -- **轻量挡**：跳过下钻评分 / 既有 topic 描述程度评估 / 决策矩阵 / 风格对齐；直接采上游 `f2s-kb-feedback-closing` 的「本轮将入库」概要做策略与目标 topicId 判定；步骤 5 路由 / 步骤 6 落盘照常执行 -- **严格挡**：跑完整 6 步 - -判挡 4 维度（**全满足**才走轻量挡，否则严格挡）：上游 case 必须是 case 2 / case 3；本轮 Read 业务源码 ≤ 3 个；本轮回答引用函数 / 类名 ≤ 5 个；用户追问未否定上游结论。 - -「业务源码」定义：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数。 - -### 输入（自动提取） - -- 用户问题：从对话历史自动提取 -- Agent 回答：完整回答内容 -- 已匹配 topic：若由 `f2s-kb-feedback-closing` 触发则携带 -- 下钻文件：从回答中提取引用的文件路径、函数名、行号 - -### 判断逻辑 - -**下钻深度评分**（0-50 分，累加）： -- 读文件数：0 / 1-2 / 3-5 / 6+ → 0 / 3 / 7 / 10 分 -- 分段读次数：0-1 / 2-4 / 5-8 / 9+ → 0 / 3 / 7 / 10 分 -- 函数引用数：0-2 / 3-5 / 6-10 / 11+ → 0 / 3 / 7 / 10 分 -- 代码片段长度：0-50 / 51-150 / 151-300 / 301+ 行 → 0 / 3 / 7 / 10 分 -- 回答长度：0-200 / 201-500 / 501-1000 / 1001+ 字符 → 0 / 3 / 7 / 10 分 - -**深度分类**： -- **浅层**（0-15 分）：简单问答，源码引用少 -- **中层**（16-30 分）：中等复杂度，多文件查阅 -- **深层**（31-50 分）：深入探索，大量源码分析 - -**知识描述层次**（按内容特征判断，非长度）： -- **摘要级**：仅结论性描述（"是什么"/"做什么"），无条件/流程/函数细节 -- **详细级**：含机制解释、流程步骤、关键判断条件（"当 X"、"若 Y 则"、"首先...然后..."） -- **实现级**：含函数调用关系、状态转换细节、边界条件处理、代码示例 - -**策略决策矩阵**： - -| 下钻深度 | 已匹配 topic | 现有 topic 描述层次 | 提取知识描述层次 | 策略 | -|---------|-------------|-------------------|-----------------|------| -| 浅层 | 匹配 | 摘要 | 摘要 | **追加到现有** | -| 浅层 | 匹配 | 摘要/详细 | 详细 | **追加到现有** | -| 浅层 | 匹配 | 摘要 | 实现 | **创建子 topic** | -| 浅层 | 未匹配 | - | 任意 | **创建新 topic** | -| 中层 | 匹配 | 摘要 | 摘要/详细 | **追加到现有** | -| 中层 | 匹配 | 摘要 | 实现 | **创建子 topic** | -| 中层 | 匹配 | 详细/实现 | 详细/实现 | **追加到现有** | -| 中层 | 未匹配 | - | 任意 | **创建新 topic** | -| 深层 | 匹配 | 摘要 | 任意 | **创建子 topic** | -| 深层 | 匹配 | 详细/实现 | 详细/实现 | **追加现有或创建子 topic** | -| 深层 | 未匹配 | - | 任意 | **创建独立模块 topic** | - -**决策关键**： -- 描述层次差距 ≥ 2 级（摘要 vs 实现）→ 强制创建子 topic -- 描述层次差距 = 1 级（摘要 vs 详细，或详细 vs 实现）→ 可追加 -- 描述层次匹配（同级）→ 正常追加 -- 深层下钻 ≥ 深层 → 优先创建子 topic - -### 落盘与路由同步 - -- **追加到现有 topic**：读取 2-3 个近邻 topic 样本对齐风格，在相关段落后追加内容 -- **创建子 topic**：生成新 topicId（基于父 topic + 焦点），更新父 topic 添加链接，写入 `topicDependencies` -- **创建独立模块 topic**：深层下钻时可选创建 stock-doc，topic 作为摘要 + 指针 -- **同步 manifest**：新 topic 写入 `topicPaths`、`taskToTopicRules`、matcher 分片；已有 topic 检查是否需补 `includeAny` -- **同步 index.md**：新 topic 添加条目，格式保持一致 - -### topicMetadata 处理 - -有明确证据时写入： -- 核心机制/状态流转/失败回退 → `policy` -- 配置开关影响 → `config` -- 模块边界/调用约定 → `module` -- 已实现能力/业务逻辑 → `feature` -- `confidence` 设为 `inferred` -- 无明确证据时不写，摘要中列为"待分类" - -## 边界与禁止项 - -- 只维护 `.Knowledge`，不改配置根 `rules/skills` -- 无需用户确认（Q&A 已验证知识正确性） -- 保持轻量，单次 Q&A 知识提取 30 秒内完成 -- 避免过度拆分：除非下钻深度 ≥ 深层且知识描述层次 ≥ 详细级，优先追加到现有 topic -- 生成的 matcher `includeAny` 应覆盖用户实际使用的表达，不仅是技术术语 - -## 指向长文 - -完整执行条令见配置根 `skills/f2s-kb-distill/SKILL.mdc`（Cursor/Claude）或 `.codex/skills/f2s-kb-distill/SKILL.mdc`（Codex）。 +--- +id: f2s-kb-distill +revision: 0 +summary: "f2s-kb-distill：Q&A 驱动知识提取与入库" +primary: policy +confidence: manual +--- +# f2s-kb-distill：Q&A 驱动知识提取与入库 + +Q&A 驱动知识提取技能，从普通问答中自动萃取可复用知识事实并入库；根据下钻深度与描述层次自动判断创建新 topic 或追加到现有 topic。 + +## 适用场景 + +- 用户提问 → Agent 下钻源码回答 → 需要将发现的知识固化到知识库 +- 通常由 `f2s-kb-feedback-closing` 规则自动建议，也可用户手动调用 +- 与 `f2s-kb-sync` 区别：`sync` 用于批量同步多个能力；`distill` 专注单次 Q&A 知识提取 + +## 执行前依赖 + +本技能执行前须先读以下主题： + +- **`f2s-kb-feedback-closing`**：定义"可复用知识事实"边界（核心机制、状态流转、契约、配置影响、失败回退、模块边界、数据模型） +- **`f2s-topic-authoring`**：创建/修改 topic 时的命名、骨架、metadata、dependencies 准则 + +## 核心流程 + +### 执行挡位（agent 自动判，无命令参数） + +- **轻量挡**：跳过下钻评分 / 既有 topic 描述程度评估 / 决策矩阵 / 风格对齐；直接采上游 `f2s-kb-feedback-closing` 的「本轮将入库」概要做策略与目标 topicId 判定；步骤 5 路由 / 步骤 6 落盘照常执行 +- **严格挡**：跑完整 6 步 + +判挡 4 维度（**全满足**才走轻量挡，否则严格挡）：上游 case 必须是 case 2 / case 3；本轮 Read 业务源码 ≤ 3 个；本轮回答引用函数 / 类名 ≤ 5 个；用户追问未否定上游结论。 + +「业务源码」定义：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数。 + +### 输入（自动提取） + +- 用户问题：从对话历史自动提取 +- Agent 回答：完整回答内容 +- 已匹配 topic：若由 `f2s-kb-feedback-closing` 触发则携带 +- 下钻文件：从回答中提取引用的文件路径、函数名、行号 + +### 判断逻辑 + +**下钻深度评分**（0-50 分，累加）： +- 读文件数：0 / 1-2 / 3-5 / 6+ → 0 / 3 / 7 / 10 分 +- 分段读次数：0-1 / 2-4 / 5-8 / 9+ → 0 / 3 / 7 / 10 分 +- 函数引用数：0-2 / 3-5 / 6-10 / 11+ → 0 / 3 / 7 / 10 分 +- 代码片段长度：0-50 / 51-150 / 151-300 / 301+ 行 → 0 / 3 / 7 / 10 分 +- 回答长度：0-200 / 201-500 / 501-1000 / 1001+ 字符 → 0 / 3 / 7 / 10 分 + +**深度分类**： +- **浅层**（0-15 分）：简单问答，源码引用少 +- **中层**（16-30 分）：中等复杂度，多文件查阅 +- **深层**（31-50 分）：深入探索，大量源码分析 + +**知识描述层次**（按内容特征判断，非长度）： +- **摘要级**：仅结论性描述（"是什么"/"做什么"），无条件/流程/函数细节 +- **详细级**：含机制解释、流程步骤、关键判断条件（"当 X"、"若 Y 则"、"首先...然后..."） +- **实现级**：含函数调用关系、状态转换细节、边界条件处理、代码示例 + +**策略决策矩阵**： + +| 下钻深度 | 已匹配 topic | 现有 topic 描述层次 | 提取知识描述层次 | 策略 | +|---------|-------------|-------------------|-----------------|------| +| 浅层 | 匹配 | 摘要 | 摘要 | **追加到现有** | +| 浅层 | 匹配 | 摘要/详细 | 详细 | **追加到现有** | +| 浅层 | 匹配 | 摘要 | 实现 | **创建子 topic** | +| 浅层 | 未匹配 | - | 任意 | **创建新 topic** | +| 中层 | 匹配 | 摘要 | 摘要/详细 | **追加到现有** | +| 中层 | 匹配 | 摘要 | 实现 | **创建子 topic** | +| 中层 | 匹配 | 详细/实现 | 详细/实现 | **追加到现有** | +| 中层 | 未匹配 | - | 任意 | **创建新 topic** | +| 深层 | 匹配 | 摘要 | 任意 | **创建子 topic** | +| 深层 | 匹配 | 详细/实现 | 详细/实现 | **追加现有或创建子 topic** | +| 深层 | 未匹配 | - | 任意 | **创建独立模块 topic** | + +**决策关键**： +- 描述层次差距 ≥ 2 级（摘要 vs 实现）→ 强制创建子 topic +- 描述层次差距 = 1 级（摘要 vs 详细，或详细 vs 实现）→ 可追加 +- 描述层次匹配（同级）→ 正常追加 +- 深层下钻 ≥ 深层 → 优先创建子 topic + +### 落盘与路由同步 + +- **追加到现有 topic**：读取 2-3 个近邻 topic 样本对齐风格，在相关段落后追加内容 +- **创建子 topic**：生成新 topicId（基于父 topic + 焦点），更新父 topic 添加链接，写入 `topicDependencies` +- **创建独立模块 topic**：深层下钻时可选创建 stock-doc，topic 作为摘要 + 指针 +- **同步 manifest**：新 topic 写入 `topicPaths`、`taskToTopicRules`、matcher 分片；已有 topic 检查是否需补 `includeAny` +- **同步 index.md**：新 topic 添加条目，格式保持一致 + +### topicMetadata 处理 + +有明确证据时写入： +- 核心机制/状态流转/失败回退 → `policy` +- 配置开关影响 → `config` +- 模块边界/调用约定 → `module` +- 已实现能力/业务逻辑 → `feature` +- `confidence` 设为 `inferred` +- 无明确证据时不写，摘要中列为"待分类" + +## 边界与禁止项 + +- 只维护 `.Knowledge`，不改配置根 `rules/skills` +- 无需用户确认（Q&A 已验证知识正确性） +- 保持轻量，单次 Q&A 知识提取 30 秒内完成 +- 避免过度拆分：除非下钻深度 ≥ 深层且知识描述层次 ≥ 详细级，优先追加到现有 topic +- 生成的 matcher `includeAny` 应覆盖用户实际使用的表达，不仅是技术术语 + +## 指向长文 + +完整执行条令见配置根 `skills/f2s-kb-distill/SKILL.mdc`（Cursor/Claude）或 `.codex/skills/f2s-kb-distill/SKILL.mdc`（Codex）。 diff --git a/.Knowledge/topics/f2s-req-plan.md b/.Knowledge/topics/f2s-req-plan.md index b441791..031b0da 100644 --- a/.Knowledge/topics/f2s-req-plan.md +++ b/.Knowledge/topics/f2s-req-plan.md @@ -1,27 +1,35 @@ -# f2s-req-plan（路由摘要） - -> 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。 -> **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。 -> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。 - -## 依赖 - -执行本主题前须先读依赖主题 **`f2s-task`**（`manifest-routing.topicDependencies`）。 - -## 作用 - -从技术方案或需求描述出发：**续作分诊 → 草稿确认 → 按 f2s-task 落盘 → 实现 → 归档**。 - -1. 步骤 0：`flow2spec.config.json` + **`f2s-task` 全文** -2. `f2s-task`「任务开始」：检查 `todo.json` / keywords 续作 -3. 草稿确认（主 agent） -4. 落盘 `task.md` / `context.md` / `user-todos.md` / `todo.json`（`linkedSkill: f2s-req-plan`） -5. 实现并按步打钩；用户代办写 `user-todos.md` -6. 满足归档门禁后移入 `completed/-/` - -不依赖 `changeTracking`，但 **始终** 服从 `f2s-task`。 - -## 下一步 - -- 技能全文：`skills/f2s-req-plan/SKILL.md` -- 任务规则：`rules/f2s-task.*` 或 `.codex/topics/f2s-task.md` +--- +id: f2s-req-plan +revision: 0 +summary: "f2s-req-plan（路由摘要）" +dependsOn: [f2s-task] +primary: policy +confidence: manual +--- +# f2s-req-plan（路由摘要） + +> 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。 +> **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。 +> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。 + +## 依赖 + +执行本主题前须先读依赖主题 **`f2s-task`**（`manifest-routing.topicDependencies`）。 + +## 作用 + +从技术方案或需求描述出发：**续作分诊 → 草稿确认 → 按 f2s-task 落盘 → 实现 → 归档**。 + +1. 步骤 0：`flow2spec.config.json` + **`f2s-task` 全文** +2. `f2s-task`「任务开始」：检查 `todo.json` / keywords 续作 +3. 草稿确认（主 agent） +4. 落盘 `task.md` / `context.md` / `user-todos.md` / `todo.json`（`linkedSkill: f2s-req-plan`） +5. 实现并按步打钩；用户代办写 `user-todos.md` +6. 满足归档门禁后移入 `completed/-/` + +不依赖 `changeTracking`，但 **始终** 服从 `f2s-task`。 + +## 下一步 + +- 技能全文：`skills/f2s-req-plan/SKILL.md` +- 任务规则：`rules/f2s-task.*` 或 `.codex/topics/f2s-task.md` diff --git a/.Knowledge/topics/f2s-req-tech.md b/.Knowledge/topics/f2s-req-tech.md index a1da0d8..2d99c88 100644 --- a/.Knowledge/topics/f2s-req-tech.md +++ b/.Knowledge/topics/f2s-req-tech.md @@ -1,46 +1,53 @@ -# f2s-req-tech（路由摘要） - -> 长文见配置根 **`skills/f2s-req-tech/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-req-tech/SKILL.md`**。 - -## 作用 - -基于已澄清的需求和项目知识库，生成可直接用于实现的技术方案文档，落盘 `.Knowledge/req-docs/`。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。 - -## 适用场景 / 触发词 - -- 用户触发 `f2s-req-tech`、生成技术方案、技术方案文档。 -- 用户完成 `f2s-req-clarify` 后请求出方案。 -- 用户提供需求描述或 PRD 路径，要求生成后端技术方案、接口设计、数据模型等。 - -## 核心规则 - -1. **澄清前置门禁**：进入撰写前先判定需求是否已澄清；未澄清（有 3+ 未答关键问题 / 含"待定 / 大概 / 我打算"类模糊语，且**不是**从 `f2s-req-clarify` 衔接进入）则**先走 `f2s-req-clarify`**，由 clarify 落盘后自动衔接回本技能同轮继续，不打断用户。 -2. **允许的单跳同轮衔接**：`f2s-req-clarify` 澄清文档落盘 → 自动衔接 `f2s-req-tech`（同轮直连）；本技能落盘后**不再**自动衔接 `f2s-req-plan` / `implement-tech-design`。 -3. **先读模板**：执行前必须读取 `.Knowledge/template/技术方案模版.md` 作为结构参考。 -4. **章节积木原则**：模板章节为可选积木，按需取用；不硬套，不为套模板强行生成无关章节。 -5. **交付物与流程合一**：每个交付单元小节内同时写契约（输入/输出）与处理流程，禁止拆章重复。 -6. **对齐项目约定**：读取 `.Knowledge/topics/` 和 `stock-docs/` 中相关约定，命名/结构/错误码与现有项目一致。 -7. **拆子前置**：`subAgent=true` 时，主 agent 必须先产出「项目约定摘要」（< 80 行，含 6 类条款）方可拆子；未完成前置禁止拆子。 -8. **落盘停步**：方案落盘后**只输出一行提示**"技术方案已就绪：`<路径>`；如需继续可用 `f2s-req-plan` / `implement-tech-design`"，然后**停止**；同一轮内不得再自动衔接下一 `f2s-*` 技能，不得追加 `f2s-kb-distill` 收口块（过程编排型技能落盘不触发 distill，见 `rules/f2s-kb-feedback-closing.*` 禁止段）。 - -## 输出 - -- 默认路径：`.Knowledge/req-docs/<方案名>_技术方案.md` -- 完成后提示可据此进行代码实现（衔接 `implement-tech-design`）。 - -## 禁止项 - -- 禁止未读 `.Knowledge/template/技术方案模版.md` 直接生成文档。 -- 禁止在需求含明显未决问题 / 未澄清且非 clarify 衔接进入时直接撰写（应先走 `f2s-req-clarify` 由其自动衔接回本技能）。 -- 禁止为套模板强行填写与需求无关的章节（如无消息队列时强行写消息队列章节）。 -- 禁止拆章重复描述同一交付单元的流程。 -- 禁止臆造与项目不符的约定；不确定时标注「待与项目约定确认」。 -- 禁止方案落盘后在同一轮内自动衔接 `f2s-req-plan` / `implement-tech-design`（`f2s-req-clarify` → `f2s-req-tech` 是仅有的允许单跳，方案之后须新一轮触发）。 -- 禁止在方案文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示。 - -## 下一步 - -- 技能全文：`skills/f2s-req-tech/SKILL.md` -- 模板：`.Knowledge/template/技术方案模版.md` -- 前置澄清：`f2s-req-clarify` -- 实现：`implement-tech-design`（`rules/f2s-implement-tech-design.*`） +--- +id: f2s-req-tech +revision: 0 +summary: "f2s-req-tech（路由摘要）" +primary: policy +confidence: inferred +--- +# f2s-req-tech（路由摘要） + +> 长文见配置根 **`skills/f2s-req-tech/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-req-tech/SKILL.md`**。 + +## 作用 + +基于已澄清的需求和项目知识库，生成可直接用于实现的技术方案文档，落盘 `.Knowledge/req-docs/`。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。 + +## 适用场景 / 触发词 + +- 用户触发 `f2s-req-tech`、生成技术方案、技术方案文档。 +- 用户完成 `f2s-req-clarify` 后请求出方案。 +- 用户提供需求描述或 PRD 路径，要求生成后端技术方案、接口设计、数据模型等。 + +## 核心规则 + +1. **澄清前置门禁**：进入撰写前先判定需求是否已澄清；未澄清（有 3+ 未答关键问题 / 含"待定 / 大概 / 我打算"类模糊语，且**不是**从 `f2s-req-clarify` 衔接进入）则**先走 `f2s-req-clarify`**，由 clarify 落盘后自动衔接回本技能同轮继续，不打断用户。 +2. **允许的单跳同轮衔接**：`f2s-req-clarify` 澄清文档落盘 → 自动衔接 `f2s-req-tech`（同轮直连）；本技能落盘后**不再**自动衔接 `f2s-req-plan` / `implement-tech-design`。 +3. **先读模板**：执行前必须读取 `.Knowledge/template/技术方案模版.md` 作为结构参考。 +4. **章节积木原则**：模板章节为可选积木，按需取用；不硬套，不为套模板强行生成无关章节。 +5. **交付物与流程合一**：每个交付单元小节内同时写契约（输入/输出）与处理流程，禁止拆章重复。 +6. **对齐项目约定**：读取 `.Knowledge/topics/` 和 `stock-docs/` 中相关约定，命名/结构/错误码与现有项目一致。 +7. **拆子前置**：`subAgent=true` 时，主 agent 必须先产出「项目约定摘要」（< 80 行，含 6 类条款）方可拆子；未完成前置禁止拆子。 +8. **落盘停步**：方案落盘后**只输出一行提示**"技术方案已就绪：`<路径>`；如需继续可用 `f2s-req-plan` / `implement-tech-design`"，然后**停止**；同一轮内不得再自动衔接下一 `f2s-*` 技能，不得追加 `f2s-kb-distill` 收口块（过程编排型技能落盘不触发 distill，见 `rules/f2s-kb-feedback-closing.*` 禁止段）。 + +## 输出 + +- 默认路径：`.Knowledge/req-docs/<方案名>_技术方案.md` +- 完成后提示可据此进行代码实现（衔接 `implement-tech-design`）。 + +## 禁止项 + +- 禁止未读 `.Knowledge/template/技术方案模版.md` 直接生成文档。 +- 禁止在需求含明显未决问题 / 未澄清且非 clarify 衔接进入时直接撰写（应先走 `f2s-req-clarify` 由其自动衔接回本技能）。 +- 禁止为套模板强行填写与需求无关的章节（如无消息队列时强行写消息队列章节）。 +- 禁止拆章重复描述同一交付单元的流程。 +- 禁止臆造与项目不符的约定；不确定时标注「待与项目约定确认」。 +- 禁止方案落盘后在同一轮内自动衔接 `f2s-req-plan` / `implement-tech-design`（`f2s-req-clarify` → `f2s-req-tech` 是仅有的允许单跳，方案之后须新一轮触发）。 +- 禁止在方案文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示。 + +## 下一步 + +- 技能全文：`skills/f2s-req-tech/SKILL.md` +- 模板：`.Knowledge/template/技术方案模版.md` +- 前置澄清：`f2s-req-clarify` +- 实现：`implement-tech-design`（`rules/f2s-implement-tech-design.*`） diff --git a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md index ab74945..832e7ad 100644 --- a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md +++ b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md @@ -1,25 +1,32 @@ -# f2s-doc-routing（路由摘要） - -> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。 -> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 - -## 本文件作用 - -- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。 -- 仅保留**目录分工**记忆点。 - -## 目录分工（须与规则一致） - -| 目录 | 用途 | -| --- | --- | -| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 | -| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 | - -**原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。 - -## 下一步读什么 - -| 环境 | 下一步 | -| --- | --- | -| Cursor / Claude | 打开或 @ **`rules/f2s-stock-docs-vs-req-docs`**。 | -| Codex | 读 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**。 | +--- +id: f2s-doc-routing +revision: 0 +summary: "f2s-doc-routing（路由摘要）" +primary: policy +confidence: manual +--- +# f2s-doc-routing（路由摘要） + +> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。 +> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 + +## 本文件作用 + +- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。 +- 仅保留**目录分工**记忆点。 + +## 目录分工（须与规则一致） + +| 目录 | 用途 | +| --- | --- | +| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 | +| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 | + +**原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。 + +## 下一步读什么 + +| 环境 | 下一步 | +| --- | --- | +| Cursor / Claude | 打开或 @ **`rules/f2s-stock-docs-vs-req-docs`**。 | +| Codex | 读 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**。 | diff --git a/.Knowledge/topics/f2s-task.md b/.Knowledge/topics/f2s-task.md index 2e23c6f..d3247fe 100644 --- a/.Knowledge/topics/f2s-task.md +++ b/.Knowledge/topics/f2s-task.md @@ -1,53 +1,60 @@ -# f2s-task（路由摘要） - -> 长文见配置根 **`rules/f2s-task.*`**。 -> 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。 - -## 作用 - -变更追踪规则（`alwaysApply: true`）。当对应技能的 `changeTracking.*` 为 `true` 时，技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。 - -## 生效范围 - -| 配置项 | 对应技能 | -| --- | --- | -| `changeTracking.feat` | `f2s-kb-feat` | -| `changeTracking.fix` | `f2s-kb-fix` | -| `changeTracking.implement` | `f2s-implement-tech-design` | - -`f2s-req-plan` 不受配置约束，始终创建任务清单。 - -## 任务根 `TASK_ROOT`（多人） - -- 解析顺序：`collaboration.developerId`（config）→ git email/name → legacy `.task` -- 非 legacy 时目录为 `.task//…`；只读写当前 `TASK_ROOT`，禁止扫其他人的 todo（防串戏） -- `.Knowledge/` 仍全员共享 - -## 目录结构 - -``` -TASK_ROOT/ ← `.task` 或 `.task/` -├── todo.json ← 活跃任务索引（仅主 agent 写） -├── active// -│ ├── task.md ← checklist（执行步骤） -│ ├── context.md ← 涉及文件、文档链接 -│ ├── user-todos.md ← 须用户执行的代办（改库、配环境等） -│ └── acceptance.md ← 验收清单：task.md 全部 [x] 后、归档前生成 -└── completed/-/ - ├── task.md - ├── context.md - ├── user-todos.md - └── acceptance.md -``` - -用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**；归档前**必须**生成与 `task.md` 同目录的 **`acceptance.md`**（验收清单），二者职责分离。细则见配置根 **`rules/f2s-task.*`**。 - -## 跨会话续作 - -新会话先解析 `TASK_ROOT`；若存在该根下 `todo.json`，将用户首条消息与**仅该文件**内 `keywords` 匹配： -- 命中 → 展示剩余 checklist，摘要 user-todos / acceptance，加载 `linkedSkill`，提示是否继续 -- 无命中 → 不打扰 - -## 下一步 - -读配置根 `rules/f2s-task.*` 获取完整规则（目录结构、todo.json 格式、任务生命周期、Hook 配置）。 +--- +id: f2s-task +revision: 0 +summary: "f2s-task（路由摘要）" +primary: policy +confidence: manual +--- +# f2s-task（路由摘要） + +> 长文见配置根 **`rules/f2s-task.*`**。 +> 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。 + +## 作用 + +变更追踪规则（`alwaysApply: true`）。当对应技能的 `changeTracking.*` 为 `true` 时，技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。 + +## 生效范围 + +| 配置项 | 对应技能 | +| --- | --- | +| `changeTracking.feat` | `f2s-kb-feat` | +| `changeTracking.fix` | `f2s-kb-fix` | +| `changeTracking.implement` | `f2s-implement-tech-design` | + +`f2s-req-plan` 不受配置约束，始终创建任务清单。 + +## 任务根 `TASK_ROOT`（多人） + +- 解析顺序：`collaboration.developerId`（config）→ git email/name → legacy `.task` +- 非 legacy 时目录为 `.task//…`；只读写当前 `TASK_ROOT`，禁止扫其他人的 todo（防串戏） +- `.Knowledge/` 仍全员共享 + +## 目录结构 + +``` +TASK_ROOT/ ← `.task` 或 `.task/` +├── todo.json ← 活跃任务索引（仅主 agent 写） +├── active// +│ ├── task.md ← checklist（执行步骤） +│ ├── context.md ← 涉及文件、文档链接 +│ ├── user-todos.md ← 须用户执行的代办（改库、配环境等） +│ └── acceptance.md ← 验收清单：task.md 全部 [x] 后、归档前生成 +└── completed/-/ + ├── task.md + ├── context.md + ├── user-todos.md + └── acceptance.md +``` + +用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**；归档前**必须**生成与 `task.md` 同目录的 **`acceptance.md`**（验收清单），二者职责分离。细则见配置根 **`rules/f2s-task.*`**。 + +## 跨会话续作 + +新会话先解析 `TASK_ROOT`；若存在该根下 `todo.json`，将用户首条消息与**仅该文件**内 `keywords` 匹配： +- 命中 → 展示剩余 checklist，摘要 user-todos / acceptance，加载 `linkedSkill`，提示是否继续 +- 无命中 → 不打扰 + +## 下一步 + +读配置根 `rules/f2s-task.*` 获取完整规则（目录结构、todo.json 格式、任务生命周期、Hook 配置）。 diff --git a/.Knowledge/topics/skill-authoring.md b/.Knowledge/topics/skill-authoring.md index 4088c46..1a90c98 100644 --- a/.Knowledge/topics/skill-authoring.md +++ b/.Knowledge/topics/skill-authoring.md @@ -1,85 +1,92 @@ -# skill-authoring（路由摘要） - -> 适用范围：在 **本仓**（Flow2Spec 产品开发仓）新增或重构 `f2s-*` SKILL 时遵循。**不下发**到下游业务仓——下游不写 `f2s-*` SKILL，本主题对其无意义。 - -## 作用 - -统一 `templates/skills/f2s-*/SKILL.md` 的小标题命名与排列顺序，避免同类信息出现多种写法（`## 输入` / `## 入参` / `## 传参`；`## 步骤` / `## 执行流程` / `## 强制流程`）造成跨 SKILL 维护心智成本。本主题**只规定命名与顺序**，不限制正文风格。 - -## SKILL 骨架（必填段标 ✱，可选段标 ◇） - -``` --- -name: f2s- -description: <一句话 + 「；触发：<词1>、<词2>、<词3>」> +id: skill-authoring +revision: 0 +summary: "skill-authoring（路由摘要）" +primary: policy +confidence: inferred --- - -> 执行口径：<本技能维护什么 / 不动什么 / 是否绑配置开关；一段话> - -# <主标题> - -## 与既有技能的边界 ◇ ← 触发词高度近似时建议写 -## 适用范围 ✱ ← 替代旧版「使用时机/何时使用/适用场景」 -## 编排 ✱ ← 主 / 子 agent 切分；指向 unified-entry 取 subAgent / switchAgentVerification 语义 -## 输入 ✱ ← 替代旧版「入参/传参」 -## 强制前置 ◇ ← 本技能在步骤前必须 Read 的 rule / 配置文件 -## 流程 ✱ ← 替代旧版「步骤/执行步骤/执行流程/强制流程」 - ### 步骤 N: <动词短语> ← 子标题统一「步骤 N」前缀；编号与正文顺序一致 -## 输出摘要 ✱ ← 替代旧版「输出摘要格式/模板（建议）」 -## 约束与禁止项 ✱ ← 合并旧版「约束 / 路径与引用约束 / 禁止项」 -## 复杂场景示例 ◇ ← 易踩坑的技能写 1–3 个 -## 完成后自检 ✱ ← 编号列表；每条对应可校验的事实 -``` - -## 字段约定 - -### `description` - -- 一句话说明做什么 + 半句话触发条件，末尾接 `；触发：<词1>、<词2>、<词3>`。 -- 触发词与同名 `matchers/.json` 的 `includeAny` 保持口径一致。 -- 不写实现细节 / 模型选择 / 提示工程技巧。 - -### `执行口径`（顶部 blockquote） - -- 一段话讲清三件事：**维护哪些路径** / **不动哪些路径** / **是否绑某个 `flow2spec.config.json` 字段**。 -- 例：「本技能只维护 `.Knowledge`，不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`。」 - -### `编排` - -- `subAgent` / `switchAgentVerification` 语义统一指向 `f2s-flow2spec-unified-entry`，**不复述定义**——只写本技能在该字段为 `true` / `false` 时的差异化行为。 -- 写权硬约束（哪些文件恒由主 agent 落盘）单独成一行。 -- 验证策略（落盘侧自验 / 交叉校验）单独成一行。 - -### `流程` - -- 子标题统一 `### 步骤 N: <动词短语>`，全文冒号风格统一。 -- 编号从 1 起；`0` / `0.5` 是历史包袱，新 SKILL 避免使用——前置改放 `## 强制前置`。 -- 每步开头一句"做什么"，再列约束 / 落盘文件 / 输出形态。 - -### `约束与禁止项` - -- 列表式，肯定式优先（参见 `f2s-flow2spec-unified-entry`「知识库落盘文风」）。 -- 排他性选择例外。 -- 写权硬约束已在「编排」写过则不复述，本节仅列领域级禁止项（如"不动配置根 `rules/skills`"）。 - -### `完成后自检` - -- 每条对应可校验的事实（agent 能用 `Read` / `Grep` 验证），避免"是否合理 / 是否充分"这类主观项。 -- 命中本技能特有风险点（例：`f2s-kb-addRules` 必检"是否在用户未确认前提前落盘"）。 - -## 不规定的事 - -- **正文风格**：每个 SKILL 按场景需要写散文 / 表格 / 流程图，本主题不限定。 -- **小节内部顺序**：例如「编排」节内各点的排列，按 SKILL 实际重要性排。 -- **是否复述配置开关**：默认指向 unified-entry 不复述；若需强调某字段对自身的特殊影响（如 `f2s-doc-milestone` 不受 `flow2spec.config` 编排开关影响），可在「编排」节单独写一句。 - -## 参考实现 - -- 最近按本模板写的：`templates/skills/f2s-kb-addRules/SKILL.md`（含「与既有技能的边界」「强制前置」「步骤 1–5」「输出摘要」「约束」「复杂场景示例」「完成后自检」）。 -- 风格接近的旧 SKILL：`templates/skills/f2s-kb-build/SKILL.md`（小标题用「步骤 N：xxx」而非子标题，下次维护时顺手降级即可）。 - -## 演进策略 - -- **新 SKILL**：必须按本模板写。 -- **存量 SKILL**：不强制批量改名；下次维护到某个 SKILL 时顺手对齐到本模板。 -- **离群严重**（`f2s-doc-arch` / `f2s-doc-final` / `f2s-kb-merge` / `f2s-req-clarify` 等缺多个必填段）单独立项重构，不与日常维护混在一起。 +# skill-authoring（路由摘要） + +> 适用范围：在 **本仓**（Flow2Spec 产品开发仓）新增或重构 `f2s-*` SKILL 时遵循。**不下发**到下游业务仓——下游不写 `f2s-*` SKILL，本主题对其无意义。 + +## 作用 + +统一 `templates/skills/f2s-*/SKILL.md` 的小标题命名与排列顺序，避免同类信息出现多种写法（`## 输入` / `## 入参` / `## 传参`；`## 步骤` / `## 执行流程` / `## 强制流程`）造成跨 SKILL 维护心智成本。本主题**只规定命名与顺序**，不限制正文风格。 + +## SKILL 骨架（必填段标 ✱，可选段标 ◇） + +``` +--- +name: f2s- +description: <一句话 + 「；触发：<词1>、<词2>、<词3>」> +--- + +> 执行口径：<本技能维护什么 / 不动什么 / 是否绑配置开关；一段话> + +# <主标题> + +## 与既有技能的边界 ◇ ← 触发词高度近似时建议写 +## 适用范围 ✱ ← 替代旧版「使用时机/何时使用/适用场景」 +## 编排 ✱ ← 主 / 子 agent 切分；指向 unified-entry 取 subAgent / switchAgentVerification 语义 +## 输入 ✱ ← 替代旧版「入参/传参」 +## 强制前置 ◇ ← 本技能在步骤前必须 Read 的 rule / 配置文件 +## 流程 ✱ ← 替代旧版「步骤/执行步骤/执行流程/强制流程」 + ### 步骤 N: <动词短语> ← 子标题统一「步骤 N」前缀；编号与正文顺序一致 +## 输出摘要 ✱ ← 替代旧版「输出摘要格式/模板（建议）」 +## 约束与禁止项 ✱ ← 合并旧版「约束 / 路径与引用约束 / 禁止项」 +## 复杂场景示例 ◇ ← 易踩坑的技能写 1–3 个 +## 完成后自检 ✱ ← 编号列表；每条对应可校验的事实 +``` + +## 字段约定 + +### `description` + +- 一句话说明做什么 + 半句话触发条件，末尾接 `；触发：<词1>、<词2>、<词3>`。 +- 触发词与同名 `matchers/.json` 的 `includeAny` 保持口径一致。 +- 不写实现细节 / 模型选择 / 提示工程技巧。 + +### `执行口径`（顶部 blockquote） + +- 一段话讲清三件事：**维护哪些路径** / **不动哪些路径** / **是否绑某个 `flow2spec.config.json` 字段**。 +- 例：「本技能只维护 `.Knowledge`，不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`。」 + +### `编排` + +- `subAgent` / `switchAgentVerification` 语义统一指向 `f2s-flow2spec-unified-entry`，**不复述定义**——只写本技能在该字段为 `true` / `false` 时的差异化行为。 +- 写权硬约束（哪些文件恒由主 agent 落盘）单独成一行。 +- 验证策略（落盘侧自验 / 交叉校验）单独成一行。 + +### `流程` + +- 子标题统一 `### 步骤 N: <动词短语>`，全文冒号风格统一。 +- 编号从 1 起；`0` / `0.5` 是历史包袱，新 SKILL 避免使用——前置改放 `## 强制前置`。 +- 每步开头一句"做什么"，再列约束 / 落盘文件 / 输出形态。 + +### `约束与禁止项` + +- 列表式，肯定式优先（参见 `f2s-flow2spec-unified-entry`「知识库落盘文风」）。 +- 排他性选择例外。 +- 写权硬约束已在「编排」写过则不复述，本节仅列领域级禁止项（如"不动配置根 `rules/skills`"）。 + +### `完成后自检` + +- 每条对应可校验的事实（agent 能用 `Read` / `Grep` 验证），避免"是否合理 / 是否充分"这类主观项。 +- 命中本技能特有风险点（例：`f2s-kb-addRules` 必检"是否在用户未确认前提前落盘"）。 + +## 不规定的事 + +- **正文风格**：每个 SKILL 按场景需要写散文 / 表格 / 流程图，本主题不限定。 +- **小节内部顺序**：例如「编排」节内各点的排列，按 SKILL 实际重要性排。 +- **是否复述配置开关**：默认指向 unified-entry 不复述；若需强调某字段对自身的特殊影响（如 `f2s-doc-milestone` 不受 `flow2spec.config` 编排开关影响），可在「编排」节单独写一句。 + +## 参考实现 + +- 最近按本模板写的：`templates/skills/f2s-kb-addRules/SKILL.md`（含「与既有技能的边界」「强制前置」「步骤 1–5」「输出摘要」「约束」「复杂场景示例」「完成后自检」）。 +- 风格接近的旧 SKILL：`templates/skills/f2s-kb-build/SKILL.md`（小标题用「步骤 N：xxx」而非子标题，下次维护时顺手降级即可）。 + +## 演进策略 + +- **新 SKILL**：必须按本模板写。 +- **存量 SKILL**：不强制批量改名；下次维护到某个 SKILL 时顺手对齐到本模板。 +- **离群严重**（`f2s-doc-arch` / `f2s-doc-final` / `f2s-kb-merge` / `f2s-req-clarify` 等缺多个必填段）单独立项重构，不与日常维护混在一起。 From a6c6129ebf94205ed8f58f95abfac5713488fccd Mon Sep 17 00:00:00 2001 From: liguochuan <37566390+liguochuan00@users.noreply.github.com> Date: Fri, 7 Aug 2026 18:50:28 +0800 Subject: [PATCH 2/2] chore: normalize knowledge file line endings --- .Knowledge/manifest-routing.json | 404 +++++++++--------- .Knowledge/topics/f2s-config-precheck.md | 94 ++-- .../topics/f2s-dev-workflow-constraints.md | 100 ++--- .Knowledge/topics/f2s-fallback-triage.md | 46 +- .Knowledge/topics/f2s-flow2spec-milestones.md | 48 +-- .../topics/f2s-flow2spec-presentations.md | 60 +-- .Knowledge/topics/f2s-git-commit.md | 66 +-- .../topics/f2s-implement-tech-design.md | 54 +-- .Knowledge/topics/f2s-init-defaults.md | 234 +++++----- .Knowledge/topics/f2s-kb-distill.md | 210 ++++----- .Knowledge/topics/f2s-req-plan.md | 54 +-- .Knowledge/topics/f2s-req-tech.md | 92 ++-- .../topics/f2s-stock-docs-vs-req-docs.md | 50 +-- .Knowledge/topics/f2s-task.md | 106 ++--- .Knowledge/topics/skill-authoring.md | 170 ++++---- 15 files changed, 894 insertions(+), 894 deletions(-) diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index 3aa9fbf..0bf4f32 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -1,149 +1,149 @@ -{ - "version": "3.2.7", - "knowledgeRoot": ".Knowledge", - "matcherKey": "matcherId", - "sourceOfTruth": ".Knowledge/manifest-routing.json", - "fallbackTopic": "fallback-triage", - "topicDependencies": { +{ + "version": "3.2.7", + "knowledgeRoot": ".Knowledge", + "matcherKey": "matcherId", + "sourceOfTruth": ".Knowledge/manifest-routing.json", + "fallbackTopic": "fallback-triage", + "topicDependencies": { "implement-tech-design": [ "f2s-doc-routing" - ], - "f2s-req-plan": [ - "f2s-task" - ], - "flow2spec-collaboration": [ - "f2s-task" - ] - }, - "topicPaths": { - "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md", - "f2s-doc-routing": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md", - "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", - "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", - "f2s-task": ".Knowledge/topics/f2s-task.md", - "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", + ], + "f2s-req-plan": [ + "f2s-task" + ], + "flow2spec-collaboration": [ + "f2s-task" + ] + }, + "topicPaths": { + "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md", + "f2s-doc-routing": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md", + "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", + "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", + "f2s-task": ".Knowledge/topics/f2s-task.md", + "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", "f2s-git-commit": ".Knowledge/topics/f2s-git-commit.md", - "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md", - "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md", - "skill-authoring": ".Knowledge/topics/skill-authoring.md", - "f2s-req-tech": ".Knowledge/topics/f2s-req-tech.md", - "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md", - "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", - "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", + "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md", + "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md", + "skill-authoring": ".Knowledge/topics/skill-authoring.md", + "f2s-req-tech": ".Knowledge/topics/f2s-req-tech.md", + "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md", + "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", + "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md", "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md" - }, - "taskToTopicRules": [ - { - "task": "f2s-config-precheck", - "matcherId": "m-f2s-config-precheck", - "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", - "topics": [ - "config-precheck" - ] - }, - { - "task": "implement-from-spec", - "matcherId": "m-implement-from-spec", - "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json", + }, + "taskToTopicRules": [ + { + "task": "f2s-config-precheck", + "matcherId": "m-f2s-config-precheck", + "matcherPath": ".Knowledge/matchers/m-f2s-config-precheck.json", + "topics": [ + "config-precheck" + ] + }, + { + "task": "implement-from-spec", + "matcherId": "m-implement-from-spec", + "matcherPath": ".Knowledge/matchers/m-implement-from-spec.json", "topics": [ "f2s-doc-routing", "implement-tech-design" - ] - }, - { - "task": "doc-routing", - "matcherId": "m-doc-routing", - "matcherPath": ".Knowledge/matchers/m-doc-routing.json", + ] + }, + { + "task": "doc-routing", + "matcherId": "m-doc-routing", + "matcherPath": ".Knowledge/matchers/m-doc-routing.json", "topics": [ "f2s-doc-routing" - ] - }, - { - "task": "change-tracking", - "matcherId": "m-change-tracking", - "matcherPath": ".Knowledge/matchers/m-change-tracking.json", - "topics": [ - "f2s-task" - ] - }, - { - "task": "req-plan", - "matcherId": "m-req-plan", - "matcherPath": ".Knowledge/matchers/m-req-plan.json", - "topics": [ - "f2s-req-plan" - ] - }, - { - "task": "git-commit", - "matcherId": "m-f2s-git-commit", - "matcherPath": ".Knowledge/matchers/m-f2s-git-commit.json", - "topics": [ - "f2s-git-commit" - ] - }, - { - "task": "flow2spec-presentations", - "matcherId": "m-flow2spec-presentations", - "matcherPath": ".Knowledge/matchers/m-flow2spec-presentations.json", - "topics": [ - "flow2spec-presentations" - ] - }, - { - "task": "flow2spec-milestones", - "matcherId": "m-flow2spec-milestones", - "matcherPath": ".Knowledge/matchers/m-flow2spec-milestones.json", - "topics": [ - "flow2spec-milestones" - ] - }, - { - "task": "skill-authoring", - "matcherId": "m-skill-authoring", - "matcherPath": ".Knowledge/matchers/m-skill-authoring.json", - "topics": [ - "skill-authoring" - ] - }, - { - "task": "req-tech", - "matcherId": "m-req-tech", - "matcherPath": ".Knowledge/matchers/m-req-tech.json", - "topics": [ - "f2s-req-tech" - ] - }, - { - "task": "dev-workflow-constraints", - "matcherId": "m-f2s-dev-workflow-constraints", - "matcherPath": ".Knowledge/matchers/m-f2s-dev-workflow-constraints.json", - "topics": [ - "f2s-dev-workflow-constraints" - ] - }, - { - "task": "kb-distill", - "matcherId": "m-f2s-kb-distill", - "matcherPath": ".Knowledge/matchers/m-f2s-kb-distill.json", - "topics": [ - "f2s-kb-distill" - ] - }, - { - "task": "flow2spec-init-defaults", - "matcherId": "m-flow2spec-init-defaults", - "matcherPath": ".Knowledge/matchers/m-flow2spec-init-defaults.json", - "topics": [ - "flow2spec-init-defaults" - ] - }, + ] + }, + { + "task": "change-tracking", + "matcherId": "m-change-tracking", + "matcherPath": ".Knowledge/matchers/m-change-tracking.json", + "topics": [ + "f2s-task" + ] + }, + { + "task": "req-plan", + "matcherId": "m-req-plan", + "matcherPath": ".Knowledge/matchers/m-req-plan.json", + "topics": [ + "f2s-req-plan" + ] + }, + { + "task": "git-commit", + "matcherId": "m-f2s-git-commit", + "matcherPath": ".Knowledge/matchers/m-f2s-git-commit.json", + "topics": [ + "f2s-git-commit" + ] + }, + { + "task": "flow2spec-presentations", + "matcherId": "m-flow2spec-presentations", + "matcherPath": ".Knowledge/matchers/m-flow2spec-presentations.json", + "topics": [ + "flow2spec-presentations" + ] + }, + { + "task": "flow2spec-milestones", + "matcherId": "m-flow2spec-milestones", + "matcherPath": ".Knowledge/matchers/m-flow2spec-milestones.json", + "topics": [ + "flow2spec-milestones" + ] + }, + { + "task": "skill-authoring", + "matcherId": "m-skill-authoring", + "matcherPath": ".Knowledge/matchers/m-skill-authoring.json", + "topics": [ + "skill-authoring" + ] + }, + { + "task": "req-tech", + "matcherId": "m-req-tech", + "matcherPath": ".Knowledge/matchers/m-req-tech.json", + "topics": [ + "f2s-req-tech" + ] + }, + { + "task": "dev-workflow-constraints", + "matcherId": "m-f2s-dev-workflow-constraints", + "matcherPath": ".Knowledge/matchers/m-f2s-dev-workflow-constraints.json", + "topics": [ + "f2s-dev-workflow-constraints" + ] + }, + { + "task": "kb-distill", + "matcherId": "m-f2s-kb-distill", + "matcherPath": ".Knowledge/matchers/m-f2s-kb-distill.json", + "topics": [ + "f2s-kb-distill" + ] + }, + { + "task": "flow2spec-init-defaults", + "matcherId": "m-flow2spec-init-defaults", + "matcherPath": ".Knowledge/matchers/m-flow2spec-init-defaults.json", + "topics": [ + "flow2spec-init-defaults" + ] + }, { "task": "flow2spec-collaboration", - "matcherId": "m-flow2spec-collaboration", - "matcherPath": ".Knowledge/matchers/m-flow2spec-collaboration.json", - "topics": [ + "matcherId": "m-flow2spec-collaboration", + "matcherPath": ".Knowledge/matchers/m-flow2spec-collaboration.json", + "topics": [ "flow2spec-collaboration" ] }, @@ -154,72 +154,72 @@ "topics": [ "flow2spec-doctor" ] - } - ], - "pkgRev": 1, - "topicMetadata": { - "implement-tech-design": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-doc-routing": { - "primary": "policy", - "confidence": "manual" - }, - "fallback-triage": { - "primary": "policy", - "confidence": "manual" - }, - "config-precheck": { - "primary": "config", - "confidence": "manual", - "tags": [ - "policy" - ] - }, - "f2s-task": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-req-plan": { - "primary": "policy", - "confidence": "manual" - }, - "f2s-git-commit": { - "primary": "policy", - "confidence": "manual" - }, - "flow2spec-presentations": { - "primary": "feature", - "confidence": "inferred" - }, - "flow2spec-milestones": { - "primary": "feature", - "confidence": "inferred" - }, - "skill-authoring": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-req-tech": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-dev-workflow-constraints": { - "primary": "policy", - "confidence": "inferred" - }, - "f2s-kb-distill": { - "primary": "policy", - "confidence": "manual" - }, - "flow2spec-init-defaults": { - "primary": "config", - "confidence": "inferred", - "tags": [ - "policy" - ] - }, + } + ], + "pkgRev": 1, + "topicMetadata": { + "implement-tech-design": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-doc-routing": { + "primary": "policy", + "confidence": "manual" + }, + "fallback-triage": { + "primary": "policy", + "confidence": "manual" + }, + "config-precheck": { + "primary": "config", + "confidence": "manual", + "tags": [ + "policy" + ] + }, + "f2s-task": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-req-plan": { + "primary": "policy", + "confidence": "manual" + }, + "f2s-git-commit": { + "primary": "policy", + "confidence": "manual" + }, + "flow2spec-presentations": { + "primary": "feature", + "confidence": "inferred" + }, + "flow2spec-milestones": { + "primary": "feature", + "confidence": "inferred" + }, + "skill-authoring": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-req-tech": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-dev-workflow-constraints": { + "primary": "policy", + "confidence": "inferred" + }, + "f2s-kb-distill": { + "primary": "policy", + "confidence": "manual" + }, + "flow2spec-init-defaults": { + "primary": "config", + "confidence": "inferred", + "tags": [ + "policy" + ] + }, "flow2spec-collaboration": { "primary": "feature", "confidence": "manual", @@ -234,5 +234,5 @@ "module" ] } - } -} + } +} diff --git a/.Knowledge/topics/f2s-config-precheck.md b/.Knowledge/topics/f2s-config-precheck.md index 504ffca..4d617a1 100644 --- a/.Knowledge/topics/f2s-config-precheck.md +++ b/.Knowledge/topics/f2s-config-precheck.md @@ -6,50 +6,50 @@ primary: config confidence: manual tags: [policy] --- -# config-precheck（路由摘要） - -## 本主题作用 - -- 供 `manifest-routing.topicPaths` 锚定主题 id **`config-precheck`**。 -- 与执行任意 **`f2s-*` 技能**前读取项目根 **`flow2spec.config.json`**（`subAgent`、`switchAgentVerification`、`changeTracking`、`intentRecognition`、`updateCheck`）相关；语义与 **`AGENTS.md`** 顶部、「统一入口」一致。 -- 同时记录 Claude / Cursor / Codex 三端对“配置读取提醒”和“自动更新检测”的分工，避免把 hooks 注入误认为替代显式 Read。 - -## 完整条令（按需，勿在 `.Knowledge` 再维护第二份正文） - -| 侧 | 路径 | -| --- | --- | -| Codex | 仓库根 `.codex/topics/f2s-config-check.md`（init 镜像，与模板同源）；SessionStart：`.codex/hooks/f2s-config-session.js` | -| Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） | -| Claude | `.claude/rules/f2s-config-check.md`；SessionStart：`.claude/hooks/f2s-config-session.js`；PreToolUse 守门：`.claude/hooks/f2s-config-inject.js` | -| 包模板 | `templates/rules/f2s-config-check.mdc` | - -## 必备步骤 - -1. 用 **Read** 打开项目根 **`flow2spec.config.json`**（须在 `f2s-*` 技能正文任何步骤之前）。 -2. **`AGENTS.md`** / `.codex/topics/f2s-config-check.md` 中的配置表仅说明字段语义；当前值以 **Read** 结果为准。 -3. Claude / Codex 的 `SessionStart` 配置摘要与 Claude 的 `PreToolUse Skill` 提醒只做注入 / 提醒；不得替代第 1 步的显式读取。 - -## 三端分工 - -| 侧 | 配置读取约束 | 自动更新检测 | -| --- | --- | --- | -| Claude | `SessionStart` 输出配置摘要；`PreToolUse Skill` 提醒技能前先 Read `flow2spec.config.json` | `SessionStart` 执行 `.claude/hooks/f2s-update-check.js` | -| Cursor | 通过 `.cursor/rules/f2s-config-check.mdc` 文本约束技能前先读配置 | `sessionStart` 执行 `.cursor/hooks/f2s-update-check.js`，通过 `additional_context` 注入提示 | -| Codex | `SessionStart` 输出配置摘要；通过根 `AGENTS.md` 与 `.codex/topics/f2s-config-check.md` 文本约束技能前先读配置 | `SessionStart`（`startup|resume`）执行 `.codex/hooks/f2s-update-check.js`，通过 `hookSpecificOutput.additionalContext` 注入提示 | - -## intentRecognition（意图识别自动分流） - -| 字段 | 行为 | -| --- | --- | -| `intentRecognition: true` | 启用意图识别：高置信操作意图按 `rules/f2s-intent-routing.*` 自动进入对应 Skill；讨论 / 评估 / 低置信输入不得自动调用 | -| `intentRecognition: false` | 不启用自动分流；仅显式 `$f2s-*` / 明确要求执行某技能时进入对应 Skill | -| 字段不存在 | 视为 `false` | - -- 完整路由规则：`rules/f2s-intent-routing.*`（Claude/Cursor）；`.codex/topics/f2s-intent-routing.md`（Codex）。 -- `f2s-intent-routing` 属内部行为规则，不作为独立 topic 路由，不写入 `topicPaths` / `taskToTopicRules`。 - -## 禁止项 - -- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。 -- 禁止因为 hooks 已输出配置摘要，就跳过技能开始时的 `flow2spec.config.json` 显式读取。 -- 禁止在 `intentRecognition` 未读取或为 `false` 时自动调用任何 Skill。 +# config-precheck（路由摘要） + +## 本主题作用 + +- 供 `manifest-routing.topicPaths` 锚定主题 id **`config-precheck`**。 +- 与执行任意 **`f2s-*` 技能**前读取项目根 **`flow2spec.config.json`**（`subAgent`、`switchAgentVerification`、`changeTracking`、`intentRecognition`、`updateCheck`）相关；语义与 **`AGENTS.md`** 顶部、「统一入口」一致。 +- 同时记录 Claude / Cursor / Codex 三端对“配置读取提醒”和“自动更新检测”的分工，避免把 hooks 注入误认为替代显式 Read。 + +## 完整条令（按需，勿在 `.Knowledge` 再维护第二份正文） + +| 侧 | 路径 | +| --- | --- | +| Codex | 仓库根 `.codex/topics/f2s-config-check.md`（init 镜像，与模板同源）；SessionStart：`.codex/hooks/f2s-config-session.js` | +| Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） | +| Claude | `.claude/rules/f2s-config-check.md`；SessionStart：`.claude/hooks/f2s-config-session.js`；PreToolUse 守门：`.claude/hooks/f2s-config-inject.js` | +| 包模板 | `templates/rules/f2s-config-check.mdc` | + +## 必备步骤 + +1. 用 **Read** 打开项目根 **`flow2spec.config.json`**（须在 `f2s-*` 技能正文任何步骤之前）。 +2. **`AGENTS.md`** / `.codex/topics/f2s-config-check.md` 中的配置表仅说明字段语义；当前值以 **Read** 结果为准。 +3. Claude / Codex 的 `SessionStart` 配置摘要与 Claude 的 `PreToolUse Skill` 提醒只做注入 / 提醒；不得替代第 1 步的显式读取。 + +## 三端分工 + +| 侧 | 配置读取约束 | 自动更新检测 | +| --- | --- | --- | +| Claude | `SessionStart` 输出配置摘要；`PreToolUse Skill` 提醒技能前先 Read `flow2spec.config.json` | `SessionStart` 执行 `.claude/hooks/f2s-update-check.js` | +| Cursor | 通过 `.cursor/rules/f2s-config-check.mdc` 文本约束技能前先读配置 | `sessionStart` 执行 `.cursor/hooks/f2s-update-check.js`，通过 `additional_context` 注入提示 | +| Codex | `SessionStart` 输出配置摘要；通过根 `AGENTS.md` 与 `.codex/topics/f2s-config-check.md` 文本约束技能前先读配置 | `SessionStart`（`startup|resume`）执行 `.codex/hooks/f2s-update-check.js`，通过 `hookSpecificOutput.additionalContext` 注入提示 | + +## intentRecognition（意图识别自动分流） + +| 字段 | 行为 | +| --- | --- | +| `intentRecognition: true` | 启用意图识别：高置信操作意图按 `rules/f2s-intent-routing.*` 自动进入对应 Skill；讨论 / 评估 / 低置信输入不得自动调用 | +| `intentRecognition: false` | 不启用自动分流；仅显式 `$f2s-*` / 明确要求执行某技能时进入对应 Skill | +| 字段不存在 | 视为 `false` | + +- 完整路由规则：`rules/f2s-intent-routing.*`（Claude/Cursor）；`.codex/topics/f2s-intent-routing.md`（Codex）。 +- `f2s-intent-routing` 属内部行为规则，不作为独立 topic 路由，不写入 `topicPaths` / `taskToTopicRules`。 + +## 禁止项 + +- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。 +- 禁止因为 hooks 已输出配置摘要，就跳过技能开始时的 `flow2spec.config.json` 显式读取。 +- 禁止在 `intentRecognition` 未读取或为 `false` 时自动调用任何 Skill。 diff --git a/.Knowledge/topics/f2s-dev-workflow-constraints.md b/.Knowledge/topics/f2s-dev-workflow-constraints.md index 72ede2a..a789772 100644 --- a/.Knowledge/topics/f2s-dev-workflow-constraints.md +++ b/.Knowledge/topics/f2s-dev-workflow-constraints.md @@ -5,53 +5,53 @@ summary: "f2s-dev-workflow-constraints（路由摘要）" primary: policy confidence: inferred --- -# f2s-dev-workflow-constraints（路由摘要） - -> **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓，**不进 `templates/`**。 - -## 作用 - -约束在 Flow2Spec 本仓内开发时的写盘边界与分发口径，避免「手改配置根被 init 覆盖」「未经用户同意主动跑 init」。 - -## 长文位置（本仓配置根手写，不进 templates） - -- **Cursor**：`.cursor/rules/repo-dev-workflow-constraints.mdc` -- **Claude**：`.claude/rules/repo-dev-workflow-constraints.md` -- **Codex**：`.codex/topics/repo-dev-workflow-constraints.md` - -三份为同源手写副本；执行时按当前 agent 打开对应端。 - -## 核心约束（一句一条） - -1. **只改 `templates/`**：所有下游会用到的规则/技能/主题/matcher/manifest 模板改动，只落 `templates/zh-CN/` 与 `templates/en-US/`。 -2. **不改配置根（下游会用到的产物）**：`.claude/rules/` 等中在 `templates/` 有对应源的文件属 `init` 产物，手改会被覆盖。 -3. **本仓专属手写例外**：`f2s-dev-workflow-constraints`、`repo-dev-check` 等**只**在本仓的规则/技能，直接落配置根，**不进** `templates/`。 -4. **用户驱动分发**：Agent **不主动**跑 `flow2spec init` / `npm run sync:agents`；由用户执行。 - -## 分发命令(用户执行) - -```bash -npm run sync:agents -# 或 -node ./cli.js init codex claude cursor -# 或全局装了 -flow2spec init codex claude cursor -``` - -## 自查技能 - -`repo-dev-check` 用于本仓提交前自查写盘边界与分发口径。触发词见该 SKILL。 - -## 适用场景 / 触发词 - -- 用户提到「templates vs 配置根」「模板 vs 落盘」 -- 用户说「不要改配置根 / 只改 templates / 我来跑 init / 我会自己 sync:agents」 -- Agent 打算改配置根下与 `templates/` 有对应源的文件时须先读本 topic 与对应 rules 长文 -- 分发口径澄清 - -## 边界与禁止项 - -- **仅本仓适用**：下游项目不承担本 topic 约束，不 `Read` 也不生效。 -- **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。 -- `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件，不视为配置根。 - +# f2s-dev-workflow-constraints（路由摘要） + +> **仅适用于 Flow2Spec 本仓自身**。**不给下游使用**——本 topic 与对应 rules / skill 都**只**存在于本仓，**不进 `templates/`**。 + +## 作用 + +约束在 Flow2Spec 本仓内开发时的写盘边界与分发口径，避免「手改配置根被 init 覆盖」「未经用户同意主动跑 init」。 + +## 长文位置（本仓配置根手写，不进 templates） + +- **Cursor**：`.cursor/rules/repo-dev-workflow-constraints.mdc` +- **Claude**：`.claude/rules/repo-dev-workflow-constraints.md` +- **Codex**：`.codex/topics/repo-dev-workflow-constraints.md` + +三份为同源手写副本；执行时按当前 agent 打开对应端。 + +## 核心约束（一句一条） + +1. **只改 `templates/`**：所有下游会用到的规则/技能/主题/matcher/manifest 模板改动，只落 `templates/zh-CN/` 与 `templates/en-US/`。 +2. **不改配置根（下游会用到的产物）**：`.claude/rules/` 等中在 `templates/` 有对应源的文件属 `init` 产物，手改会被覆盖。 +3. **本仓专属手写例外**：`f2s-dev-workflow-constraints`、`repo-dev-check` 等**只**在本仓的规则/技能，直接落配置根，**不进** `templates/`。 +4. **用户驱动分发**：Agent **不主动**跑 `flow2spec init` / `npm run sync:agents`；由用户执行。 + +## 分发命令(用户执行) + +```bash +npm run sync:agents +# 或 +node ./cli.js init codex claude cursor +# 或全局装了 +flow2spec init codex claude cursor +``` + +## 自查技能 + +`repo-dev-check` 用于本仓提交前自查写盘边界与分发口径。触发词见该 SKILL。 + +## 适用场景 / 触发词 + +- 用户提到「templates vs 配置根」「模板 vs 落盘」 +- 用户说「不要改配置根 / 只改 templates / 我来跑 init / 我会自己 sync:agents」 +- Agent 打算改配置根下与 `templates/` 有对应源的文件时须先读本 topic 与对应 rules 长文 +- 分发口径澄清 + +## 边界与禁止项 + +- **仅本仓适用**：下游项目不承担本 topic 约束，不 `Read` 也不生效。 +- **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。 +- `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件，不视为配置根。 + diff --git a/.Knowledge/topics/f2s-fallback-triage.md b/.Knowledge/topics/f2s-fallback-triage.md index fb2ccd9..a186210 100644 --- a/.Knowledge/topics/f2s-fallback-triage.md +++ b/.Knowledge/topics/f2s-fallback-triage.md @@ -5,26 +5,26 @@ summary: fallback-triage primary: policy confidence: manual --- -# fallback-triage - -## 执行目的 - -- 本主题仅用于未命中或低置信度场景的分诊与澄清，不用于直接实施业务改动。 -- 当 `fallbackTopic` 被读取时，先补召回与提问，再决定后续执行路径。 - -## 分诊步骤（必须） - -1. 补召回：保留次高候选并补读其依赖主题，检查是否存在更合理主题。 -2. 缺口检查：确认关键主题、边界条件、上下文文档是否齐备。 -3. 澄清提问：向用户确认目标模块、范围、预期行为后再继续。 - -## 澄清问题模板 - -- 你当前要处理的是哪个模块/业务线？ -- 这次改动更偏向“按方案实现”还是“目录与路由分流”？ -- 你希望优先保证完整性还是执行速度（是否需要全量检查）？ - -## 禁止项 - -- 禁止将本主题作为最终命中依据直接实施改动。 -- 禁止跳过澄清直接进入大范围代码修改。 +# fallback-triage + +## 执行目的 + +- 本主题仅用于未命中或低置信度场景的分诊与澄清，不用于直接实施业务改动。 +- 当 `fallbackTopic` 被读取时，先补召回与提问，再决定后续执行路径。 + +## 分诊步骤（必须） + +1. 补召回：保留次高候选并补读其依赖主题，检查是否存在更合理主题。 +2. 缺口检查：确认关键主题、边界条件、上下文文档是否齐备。 +3. 澄清提问：向用户确认目标模块、范围、预期行为后再继续。 + +## 澄清问题模板 + +- 你当前要处理的是哪个模块/业务线？ +- 这次改动更偏向“按方案实现”还是“目录与路由分流”？ +- 你希望优先保证完整性还是执行速度（是否需要全量检查）？ + +## 禁止项 + +- 禁止将本主题作为最终命中依据直接实施改动。 +- 禁止跳过澄清直接进入大范围代码修改。 diff --git a/.Knowledge/topics/f2s-flow2spec-milestones.md b/.Knowledge/topics/f2s-flow2spec-milestones.md index 56aa2f6..4c02aaf 100644 --- a/.Knowledge/topics/f2s-flow2spec-milestones.md +++ b/.Knowledge/topics/f2s-flow2spec-milestones.md @@ -5,27 +5,27 @@ summary: flow2spec-milestones primary: feature confidence: inferred --- -# flow2spec-milestones - -## 执行边界 - -- 本主题用于回答 **Flow2Spec 产品仓自身** 的版本演进、阶段划分与能力落地时间线。 -- **禁止**将里程碑正文当作业务实现的 `req-docs`；归属 `stock-docs` 索源。 - -## 目标 - -当用户询问「项目里程碑」「版本演进」「开源和内部仓区别」「双语 PPT」「Cursor 插件提交」时： - -1. 读 [项目里程碑](../stock-docs/项目里程碑.md)：**版本能力表** + M1–M18（最新阶段在前）。 -2. 演示路径：内部 `flow2spec-intro-draft` + `sync-pages.sh`；开源 `flow2spec-intro-public`（中）与 `-public-en`（英）+ `sync-gh-pages.sh`。 -3. 架构细节 → `flow2spec架构说明_终稿.md`；演示约定 → `flow2spec-presentations` 主题。 - -## 格式约定（f2s-doc-milestone 生成物） - -- 阶段**最新在前**（MN → M1）；不含索源行、commit hash 或内部运维状态 -- 每阶段只列已交付功能点；「待确认」仅写功能/交付层面缺口 - -## 下一步 - -- 全文：[项目里程碑](../stock-docs/项目里程碑.md) -- 架构：[flow2spec架构说明_终稿](../stock-docs/flow2spec架构说明_终稿.md) +# flow2spec-milestones + +## 执行边界 + +- 本主题用于回答 **Flow2Spec 产品仓自身** 的版本演进、阶段划分与能力落地时间线。 +- **禁止**将里程碑正文当作业务实现的 `req-docs`；归属 `stock-docs` 索源。 + +## 目标 + +当用户询问「项目里程碑」「版本演进」「开源和内部仓区别」「双语 PPT」「Cursor 插件提交」时： + +1. 读 [项目里程碑](../stock-docs/项目里程碑.md)：**版本能力表** + M1–M18（最新阶段在前）。 +2. 演示路径：内部 `flow2spec-intro-draft` + `sync-pages.sh`；开源 `flow2spec-intro-public`（中）与 `-public-en`（英）+ `sync-gh-pages.sh`。 +3. 架构细节 → `flow2spec架构说明_终稿.md`；演示约定 → `flow2spec-presentations` 主题。 + +## 格式约定（f2s-doc-milestone 生成物） + +- 阶段**最新在前**（MN → M1）；不含索源行、commit hash 或内部运维状态 +- 每阶段只列已交付功能点；「待确认」仅写功能/交付层面缺口 + +## 下一步 + +- 全文：[项目里程碑](../stock-docs/项目里程碑.md) +- 架构：[flow2spec架构说明_终稿](../stock-docs/flow2spec架构说明_终稿.md) diff --git a/.Knowledge/topics/f2s-flow2spec-presentations.md b/.Knowledge/topics/f2s-flow2spec-presentations.md index f2199e2..1043fb5 100644 --- a/.Knowledge/topics/f2s-flow2spec-presentations.md +++ b/.Knowledge/topics/f2s-flow2spec-presentations.md @@ -5,33 +5,33 @@ summary: flow2spec-presentations primary: feature confidence: inferred --- -# flow2spec-presentations - -## 执行边界 - -- 本主题用于说明本仓库内 Flow2Spec 对外网站与遗留 HTML 演示稿的位置、预览方式和维护边界。 -- 对外材料归属 `stock-docs` 索源说明，不作为 `req-docs` 驱动业务实现。 - -## 目标 - -当用户询问「宣传网站」「Astro 官网」「对外演示」「presentations 目录」时，命中本主题后： - -1. 网站源码位于 `website/`，使用 Astro 构建；中文入口为 `/`，英文入口为 `/en/`。 -2. 网站采用滚动式产品叙事：首页 Hero 独立占满顶部导航以下的首屏，正文区从下一屏开始并提供固定章节侧栏；移动端提供可展开导航；视觉方向为 `mailchimp-freddie` 暖人文风格。 -3. `presentations/flow2spec-intro-public/` 与 `presentations/flow2spec-intro-public-en/` 保留为旧演示稿和内容素材。 -4. 首版网站不接管 `scripts/sync-gh-pages.sh`；确认设计后再切换线上发布链路。 -5. 需要架构级背景时，可再读 `f2s-flow2spec-architecture` 主题。 - -## 边界 - -- `docs/` 与 `docs/en/` 中的 Markdown 是完整参考的唯一内容源；Astro 构建时读取原文，统一套用文章布局、目录、代码块、表格、图片和链接样式，不复制或重写正文。 -- 顶部导航指向网站内部的文档文章页；构建阶段把 Markdown 内部 `.md` 链接与 `docs/images/` 图片改写为站内路径。 -- 首页和文章页左侧目录由页面标题生成，并按滚动位置自动高亮当前章节；目录只保留章节链接，不显示标题、说明或分割线；移动端目录收进顶部可展开导航。 -- 首页 Hero 结束后才显示正文区和左侧目录；文章页不显示参考计数，Markdown 顶部的中英文切换段由构建阶段移除，语言入口统一位于右上角。 -- 桌面文档侧栏的间距按侧栏自身宽度计算，横向溢出隐藏；低高度视口内容实际溢出时才启用纵向滚动。 -- 遗留演示稿仍依赖 `.claude/skills/html-ppt/assets/`，移动或独立发布时须同步处理资源路径。 - -## 下一步 - -- 索源与路径表：[对外网站与演示](../stock-docs/Flow2Spec-对外介绍演示.md) -- 架构总览：`.Knowledge/topics/f2s-flow2spec-architecture.md` +# flow2spec-presentations + +## 执行边界 + +- 本主题用于说明本仓库内 Flow2Spec 对外网站与遗留 HTML 演示稿的位置、预览方式和维护边界。 +- 对外材料归属 `stock-docs` 索源说明，不作为 `req-docs` 驱动业务实现。 + +## 目标 + +当用户询问「宣传网站」「Astro 官网」「对外演示」「presentations 目录」时，命中本主题后： + +1. 网站源码位于 `website/`，使用 Astro 构建；中文入口为 `/`，英文入口为 `/en/`。 +2. 网站采用滚动式产品叙事：首页 Hero 独立占满顶部导航以下的首屏，正文区从下一屏开始并提供固定章节侧栏；移动端提供可展开导航；视觉方向为 `mailchimp-freddie` 暖人文风格。 +3. `presentations/flow2spec-intro-public/` 与 `presentations/flow2spec-intro-public-en/` 保留为旧演示稿和内容素材。 +4. 首版网站不接管 `scripts/sync-gh-pages.sh`；确认设计后再切换线上发布链路。 +5. 需要架构级背景时，可再读 `f2s-flow2spec-architecture` 主题。 + +## 边界 + +- `docs/` 与 `docs/en/` 中的 Markdown 是完整参考的唯一内容源；Astro 构建时读取原文，统一套用文章布局、目录、代码块、表格、图片和链接样式，不复制或重写正文。 +- 顶部导航指向网站内部的文档文章页；构建阶段把 Markdown 内部 `.md` 链接与 `docs/images/` 图片改写为站内路径。 +- 首页和文章页左侧目录由页面标题生成，并按滚动位置自动高亮当前章节；目录只保留章节链接，不显示标题、说明或分割线；移动端目录收进顶部可展开导航。 +- 首页 Hero 结束后才显示正文区和左侧目录；文章页不显示参考计数，Markdown 顶部的中英文切换段由构建阶段移除，语言入口统一位于右上角。 +- 桌面文档侧栏的间距按侧栏自身宽度计算，横向溢出隐藏；低高度视口内容实际溢出时才启用纵向滚动。 +- 遗留演示稿仍依赖 `.claude/skills/html-ppt/assets/`，移动或独立发布时须同步处理资源路径。 + +## 下一步 + +- 索源与路径表：[对外网站与演示](../stock-docs/Flow2Spec-对外介绍演示.md) +- 架构总览：`.Knowledge/topics/f2s-flow2spec-architecture.md` diff --git a/.Knowledge/topics/f2s-git-commit.md b/.Knowledge/topics/f2s-git-commit.md index 03f7afd..6ef7714 100644 --- a/.Knowledge/topics/f2s-git-commit.md +++ b/.Knowledge/topics/f2s-git-commit.md @@ -5,36 +5,36 @@ summary: "f2s-git-commit（路由摘要）" primary: policy confidence: manual --- -# f2s-git-commit（路由摘要） - -> 长文见配置根 **`skills/f2s-git-commit/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-git-commit/SKILL.md`**。 - -## 作用 - -提交代码时统一执行 Git 提交流程：读取变更、检查冲突、按实际 diff 生成提交信息、精确 add 文件并执行 `git commit`。默认模式会检查知识库覆盖；快捷提交模式只跳过这一步。 - -## 适用场景 / 触发词 - -- 用户触发 `f2s-git-commit`、`git commit`、提交代码、帮我提交。 -- 用户明确说“快捷提交”“快速提交”或 “quick commit”。 -- 用户询问提交流程、知识库覆盖检查、`--no-verify`、`git add -A` 等提交流程约束。 - -## 核心规则 - -1. **默认模式**：步骤 2 必须检查知识库覆盖，从 `git diff HEAD` 与 untracked 文件推断能力模块，并对照 `.Knowledge/topics/` 与 `.Knowledge/stock-docs/`。 -2. **快捷提交模式**：仅当用户本轮明确说“快捷提交”“快速提交”或 “quick commit” 时，跳过步骤 2 知识库覆盖检查。 -3. 快捷提交不跳过变更读取、merge conflict 标记检查、提交信息首行展示、精确 `git add <文件列表>`、正常 `git commit` 和 git hooks。 -4. 提交信息首行必须展示后再 commit，格式为 ` [(scope)]: <简述>`。 - -## 禁止项 - -- 禁止因为快捷提交而使用 `git add -A` 或 `git add .`。 -- 禁止因为快捷提交而使用 `--no-verify` 跳过 hooks。 -- 禁止自动 push。 -- 禁止为 commit 静默执行 `git pull` / `git pull --rebase`；涉及拉取必须先取得用户明确确认。 - -## 下一步 - -- 技能全文：`skills/f2s-git-commit/SKILL.md` -- 模板源：`templates/skills/f2s-git-commit/SKILL.md` -- 命令说明：`docs/命令说明.md` +# f2s-git-commit（路由摘要） + +> 长文见配置根 **`skills/f2s-git-commit/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-git-commit/SKILL.md`**。 + +## 作用 + +提交代码时统一执行 Git 提交流程：读取变更、检查冲突、按实际 diff 生成提交信息、精确 add 文件并执行 `git commit`。默认模式会检查知识库覆盖；快捷提交模式只跳过这一步。 + +## 适用场景 / 触发词 + +- 用户触发 `f2s-git-commit`、`git commit`、提交代码、帮我提交。 +- 用户明确说“快捷提交”“快速提交”或 “quick commit”。 +- 用户询问提交流程、知识库覆盖检查、`--no-verify`、`git add -A` 等提交流程约束。 + +## 核心规则 + +1. **默认模式**：步骤 2 必须检查知识库覆盖，从 `git diff HEAD` 与 untracked 文件推断能力模块，并对照 `.Knowledge/topics/` 与 `.Knowledge/stock-docs/`。 +2. **快捷提交模式**：仅当用户本轮明确说“快捷提交”“快速提交”或 “quick commit” 时，跳过步骤 2 知识库覆盖检查。 +3. 快捷提交不跳过变更读取、merge conflict 标记检查、提交信息首行展示、精确 `git add <文件列表>`、正常 `git commit` 和 git hooks。 +4. 提交信息首行必须展示后再 commit，格式为 ` [(scope)]: <简述>`。 + +## 禁止项 + +- 禁止因为快捷提交而使用 `git add -A` 或 `git add .`。 +- 禁止因为快捷提交而使用 `--no-verify` 跳过 hooks。 +- 禁止自动 push。 +- 禁止为 commit 静默执行 `git pull` / `git pull --rebase`；涉及拉取必须先取得用户明确确认。 + +## 下一步 + +- 技能全文：`skills/f2s-git-commit/SKILL.md` +- 模板源：`templates/skills/f2s-git-commit/SKILL.md` +- 命令说明：`docs/命令说明.md` diff --git a/.Knowledge/topics/f2s-implement-tech-design.md b/.Knowledge/topics/f2s-implement-tech-design.md index 388e34e..2479f3a 100644 --- a/.Knowledge/topics/f2s-implement-tech-design.md +++ b/.Knowledge/topics/f2s-implement-tech-design.md @@ -6,30 +6,30 @@ dependsOn: [f2s-doc-routing] primary: policy confidence: manual --- -# implement-tech-design（路由摘要） - -> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。 -> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-implement-tech-design.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 - -## 本文件作用 - -- 供 `manifest-routing.topicPaths` 与 `index.md` 锚定主题 id **`implement-tech-design`**。 -- 仅保留**路径与角色**记忆点，避免与 `rules/` 双份维护长文。 - -## 路径与角色（须与规则一致） - -- 技术方案输入：`.Knowledge/req-docs/*.md`（及 PDF 经 `f2s-doc-pdf` 落入同目录的 MD）。 -- 存量沉淀：`.Knowledge/stock-docs/` — **不**作为「按方案写代码」的直接输入。 - -## changeTracking 集成 - -若 `flow2spec.config.json` 中 `changeTracking.implement: true`： -- 步骤 2.5 输出任务列表后，同步写入 `.task/active//task.md` -- 步骤 5 收尾时归档至 `.task/completed/-/`，并从 `todo.json` 删除条目 - -## 下一步读什么 - -| 环境 | 下一步 | -| --- | --- | -| Cursor / Claude | 打开或 @ **`rules/f2s-implement-tech-design`**，按其中步骤执行。 | -| Codex | 读 **`.codex/topics/f2s-implement-tech-design.md`**。 | +# implement-tech-design（路由摘要） + +> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-implement-tech-design.md(c)`** 为准。 +> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-implement-tech-design.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 + +## 本文件作用 + +- 供 `manifest-routing.topicPaths` 与 `index.md` 锚定主题 id **`implement-tech-design`**。 +- 仅保留**路径与角色**记忆点，避免与 `rules/` 双份维护长文。 + +## 路径与角色（须与规则一致） + +- 技术方案输入：`.Knowledge/req-docs/*.md`（及 PDF 经 `f2s-doc-pdf` 落入同目录的 MD）。 +- 存量沉淀：`.Knowledge/stock-docs/` — **不**作为「按方案写代码」的直接输入。 + +## changeTracking 集成 + +若 `flow2spec.config.json` 中 `changeTracking.implement: true`： +- 步骤 2.5 输出任务列表后，同步写入 `.task/active//task.md` +- 步骤 5 收尾时归档至 `.task/completed/-/`，并从 `todo.json` 删除条目 + +## 下一步读什么 + +| 环境 | 下一步 | +| --- | --- | +| Cursor / Claude | 打开或 @ **`rules/f2s-implement-tech-design`**，按其中步骤执行。 | +| Codex | 读 **`.codex/topics/f2s-implement-tech-design.md`**。 | diff --git a/.Knowledge/topics/f2s-init-defaults.md b/.Knowledge/topics/f2s-init-defaults.md index e0c6f32..b44cb0e 100644 --- a/.Knowledge/topics/f2s-init-defaults.md +++ b/.Knowledge/topics/f2s-init-defaults.md @@ -6,120 +6,120 @@ primary: config confidence: inferred tags: [policy] --- -# flow2spec-init-defaults（路由摘要） - -## 作用 - -`flow2spec init` 写入项目根 `flow2spec.config.json` 时使用的默认值与字段语义；老项目缺字段时按本表补写。本主题只描述「生产侧」（init 写什么），不涉及「消费侧」（技能执行前如何 Read），后者见 `config-precheck`。 - -## 默认值的四处一致性 - -`flow2spec init` 的默认值与字段语义由 npm 包源码四处共同决定，四处必须保持一致： - -| 落点 | 角色 | 路径 | -| --- | --- | --- | -| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `lib/flow2specConfig.js` | -| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `lib/flow2specConfig.js` | -| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `templates/{zh-CN,en-US}/flow2spec.config.json` | -| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `lib/codexAgentsAdapter.js` | - -不一致的后果： - -- `DEFAULTS` 与 `CONFIG_FIELDS[].default` 不一致 → 交互回车值与「缺字段时实际生效值」不一致，调试时令人困惑。 -- `CONFIG_FIELDS[].default` 与模板不一致 → 同一字段在「首次 init」和「老项目补字段 init」两条路径下落盘值不同。 -- 包源/模板与 `renderProjectConfigBlock` 不一致 → Codex `AGENTS.md` 表中宣称的「init 默认」与实际落盘值脱节，用户读文档与读 config 看到不同结论。 - -修改默认值时必须四处同步改；如需追加新字段，按 `CONFIG_FIELDS` 注释要求在该数组追加描述项即可，`cli.js` 会自动对缺失字段发起提问；同时也要在 `renderProjectConfigBlock` 表中追加一行（含「init 默认」列）。 - -## 字段语义与默认值（与包模板同源） - -| 字段 | 类型 | 当前默认值 | 语义 | -| --- | --- | --- | --- | -| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 `templates//` | -| `subAgent` | boolean | `true` | 是否允许技能拆子 agent；`false` 时主 agent 全流程；详见 `f2s-flow2spec-unified-entry` | -| `switchAgentVerification` | boolean | `true` | 切换 agent 校验；`true` 且技能正文绑定时启用交叉校验；旧键 `subAgentVerification` 仍兼容 | -| `intentRecognition` | boolean | `true` | 高置信操作意图是否按 `f2s-intent-routing` 自动进入对应 `f2s-*` 技能 | -| `changeTracking.feat` | boolean | `true` | `f2s-kb-feat` 是否走 `.task/` 变更追踪 | -| `changeTracking.fix` | boolean | `false` | `f2s-kb-fix` 是否走 `.task/` 变更追踪 | -| `changeTracking.implement` | boolean | `true` | `f2s-implement-tech-design` 是否走 `.task/` 变更追踪 | -| `updateCheck.enabled` | boolean | `true` | 是否启用每日版本更新提示 | - -「当前默认值」一栏以包模板 `templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。 - -### 默认值变更记录 - -- **2026-06**：`subAgent` / `switchAgentVerification` / `intentRecognition` 三项默认值由 `false` 翻面为 `true`。新项目 init 默认即开启子 agent 编排、交叉校验与意图识别自动分流。老项目（已写过这三项）不受影响；仅在升级时**仍缺该字段**的老项目会按新默认 `true` 补齐。`changeTracking.fix` 维持 `false`（显式排除翻面）。 - -## 旧值与字段兼容 - -`loadFlow2specConfig` 在解析既有 `flow2spec.config.json` 时做了两类回退： - -- **`changeTracking` 顶层布尔**：旧版本可能写 `changeTracking: true` / `false`，会展开为 `{ feat, fix, implement }` 三子项同值，便于一次性升级。 -- **`subAgentVerification`（旧键）**：仍读为 `switchAgentVerification` 的值；**新落盘必须用 `switchAgentVerification`**，旧键不再写出。 - -## 老项目 init 升级路径 - -`flow2spec init` 在已有 `flow2spec.config.json` 时走 `getMissingConfigFields`： - -1. 解析既有文件；非对象或解析失败 → 不打扰，仅做规则与目录骨架对齐。 -2. 与 `CONFIG_FIELDS` 比对： - - 已在文件中（含旧版顶层布尔的 `changeTracking`）→ 跳过，不重复询问、不覆盖用户值。 - - 缺失的字段 → 重新询问（默认值按 `CONFIG_FIELDS[].default`），用户确认后写入。 -3. 已有字段的取值**始终不被 init 覆盖**；用户手工改过的值（如把 `false` 改成 `true`）会被保留。 - -含义：升级 npm 包后新增的字段，会以「当前 `CONFIG_FIELDS` 默认值」补齐到老项目；如新版本默认值翻面（例如某字段由 `false` 改为 `true`），**只影响**升级时**仍缺该字段**的老项目，已写过该字段的项目不变。 - -### 跑 `f2s-kb-upgrade` 时怎么让全局 flow2spec 保持最新 - -`f2s-kb-upgrade` SKILL 的「步骤 -1」（先于一切）**先做前台探测再决定是否升级**：主 agent 顺序跑 `flow2spec --version` + `npm view @double-coding/flow2spec version` + `command -v npx`，按 3 分支处理： - -- **A. 已装且是 latest** → **完全跳过**升级；步骤 2 命令首选 `flow2spec init `。 -- **B. 已装但落后** → 派**独立子 agent** 后台跑 `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；步骤 2 命令用 `npx @double-coding/flow2spec@latest init ` 保证本次拿到 latest 模板。 -- **C. 未装 / latest 未知** → 同 B 处理；探测全部失败时可放弃步骤 -1，由 cli.js 兜底。 - -口径： - -- **仅** B/C 时才派子 agent；派子**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）； -- 派子是 fire-and-forget，结果不进入 SKILL 结论摘要——失败也只是"下次再升一次"； -- 与 `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 不冲突：前者是 SKILL 入口按需异步派工，后者是 `init` 收尾兜底；两次都成功就是 no-op。 -- 用户自查用 `flow2spec --version`（当前全局版本）和 `flow2spec update`（CLI 内置自更新）。 - -## init 不动哪些目录 - -`flow2spec init` 仅对齐： - -- 配置根（Claude `.claude/` / Cursor `.cursor/` / Codex `.codex/`）下的 **rules / skills / hooks 模板** 与 SessionStart / PreToolUse 钩子注册； -- 包级 **manifest 路由结构骨架**（`flow2spec init` 通过 `manifest-matchers.json` 作为种子合并 matcher 分片）； -- 项目根 `flow2spec.config.json` 的缺失字段； -- 项目侧 `.Knowledge/manifest-routing.json` 的 `pkgRev` 顶层字段（每次 init 覆盖；详见下节「manifest 中的两个版本字段」）。 - -`init` **不修改**业务知识库内容： - -- `.Knowledge/stock-docs/`、`.Knowledge/req-docs/` -- `.Knowledge/topics/.md` 的路由摘要正文 -- `.Knowledge/matchers/.json` 的 `includeAny` 词条 - -这些由 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` 等 `f2s-*` 技能维护。把 `flow2spec init` 当作「业务知识库已更新」是常见误判（见统一入口 2a）。 - -## manifest 中的两个版本字段 - -`.Knowledge/manifest-routing.json` 同时存在两个顶层整数字段，对应 `f2s-kb-upgrade` 步骤 2c 的两侧： - -| 字段 | 语义 | 写入方 | -| --- | --- | --- | -| `projectRev` | **本项目已基线对齐到的包模板修订号** | `f2s-kb-upgrade` 完整流程末尾（3b）；首次 init 也按模板写入一次 | -| `pkgRev` | **本次 init 用的包模板修订号** | `flow2spec init`（每次都按当前包模板覆盖） | - -人读对照： - -- 两值**相等** → 主题层未变，`f2s-kb-upgrade` 走快速路径 -- `projectRev` 缺失 / `pkgRev` 大于 `projectRev` → 完整流程 -- `pkgRev` 缺失 → 包模板自身未声明该字段，SKILL 走兜底完整流程 - -`f2s-kb-upgrade` 步骤 2c 直接 `Read` 同一文件取这两个字段比对。 - -## 禁止项 - -- 禁止只改 `lib/flow2specConfig.js` 的 `DEFAULTS` 或 `CONFIG_FIELDS`、不同步改 `templates/{locale}/flow2spec.config.json` 与 `lib/codexAgentsAdapter.js` 的 `renderProjectConfigBlock`（四处必须同步）。 -- 禁止在新落盘中写出旧键 `subAgentVerification`。 -- 禁止把 `init` 作为业务知识库同步的入口；新增 / 修改 stock-docs / topics / matchers 走 `f2s-*` 技能。 +# flow2spec-init-defaults（路由摘要） + +## 作用 + +`flow2spec init` 写入项目根 `flow2spec.config.json` 时使用的默认值与字段语义；老项目缺字段时按本表补写。本主题只描述「生产侧」（init 写什么），不涉及「消费侧」（技能执行前如何 Read），后者见 `config-precheck`。 + +## 默认值的四处一致性 + +`flow2spec init` 的默认值与字段语义由 npm 包源码四处共同决定，四处必须保持一致： + +| 落点 | 角色 | 路径 | +| --- | --- | --- | +| `DEFAULTS` 常量 | `loadFlow2specConfig` 兜底值，缺字段时回填 | `lib/flow2specConfig.js` | +| `CONFIG_FIELDS[].default` | init 交互问答按回车的默认值 | `lib/flow2specConfig.js` | +| 包模板 `flow2spec.config.json` | 新项目首次落盘的整文件模板（按 `locale` 选择） | `templates/{zh-CN,en-US}/flow2spec.config.json` | +| `renderProjectConfigBlock()` | Codex `AGENTS.md` 中字段语义表的「init 默认」列 | `lib/codexAgentsAdapter.js` | + +不一致的后果： + +- `DEFAULTS` 与 `CONFIG_FIELDS[].default` 不一致 → 交互回车值与「缺字段时实际生效值」不一致，调试时令人困惑。 +- `CONFIG_FIELDS[].default` 与模板不一致 → 同一字段在「首次 init」和「老项目补字段 init」两条路径下落盘值不同。 +- 包源/模板与 `renderProjectConfigBlock` 不一致 → Codex `AGENTS.md` 表中宣称的「init 默认」与实际落盘值脱节，用户读文档与读 config 看到不同结论。 + +修改默认值时必须四处同步改；如需追加新字段，按 `CONFIG_FIELDS` 注释要求在该数组追加描述项即可，`cli.js` 会自动对缺失字段发起提问；同时也要在 `renderProjectConfigBlock` 表中追加一行（含「init 默认」列）。 + +## 字段语义与默认值（与包模板同源） + +| 字段 | 类型 | 当前默认值 | 语义 | +| --- | --- | --- | --- | +| `locale` | `"zh-CN"` / `"en-US"` | `"zh-CN"` | 模板语言；决定首次落盘读哪份 `templates//` | +| `subAgent` | boolean | `true` | 是否允许技能拆子 agent；`false` 时主 agent 全流程；详见 `f2s-flow2spec-unified-entry` | +| `switchAgentVerification` | boolean | `true` | 切换 agent 校验；`true` 且技能正文绑定时启用交叉校验；旧键 `subAgentVerification` 仍兼容 | +| `intentRecognition` | boolean | `true` | 高置信操作意图是否按 `f2s-intent-routing` 自动进入对应 `f2s-*` 技能 | +| `changeTracking.feat` | boolean | `true` | `f2s-kb-feat` 是否走 `.task/` 变更追踪 | +| `changeTracking.fix` | boolean | `false` | `f2s-kb-fix` 是否走 `.task/` 变更追踪 | +| `changeTracking.implement` | boolean | `true` | `f2s-implement-tech-design` 是否走 `.task/` 变更追踪 | +| `updateCheck.enabled` | boolean | `true` | 是否启用每日版本更新提示 | + +「当前默认值」一栏以包模板 `templates/zh-CN/flow2spec.config.json` 为锚，作变更前先核对该文件。 + +### 默认值变更记录 + +- **2026-06**：`subAgent` / `switchAgentVerification` / `intentRecognition` 三项默认值由 `false` 翻面为 `true`。新项目 init 默认即开启子 agent 编排、交叉校验与意图识别自动分流。老项目（已写过这三项）不受影响；仅在升级时**仍缺该字段**的老项目会按新默认 `true` 补齐。`changeTracking.fix` 维持 `false`（显式排除翻面）。 + +## 旧值与字段兼容 + +`loadFlow2specConfig` 在解析既有 `flow2spec.config.json` 时做了两类回退： + +- **`changeTracking` 顶层布尔**：旧版本可能写 `changeTracking: true` / `false`，会展开为 `{ feat, fix, implement }` 三子项同值，便于一次性升级。 +- **`subAgentVerification`（旧键）**：仍读为 `switchAgentVerification` 的值；**新落盘必须用 `switchAgentVerification`**，旧键不再写出。 + +## 老项目 init 升级路径 + +`flow2spec init` 在已有 `flow2spec.config.json` 时走 `getMissingConfigFields`： + +1. 解析既有文件；非对象或解析失败 → 不打扰，仅做规则与目录骨架对齐。 +2. 与 `CONFIG_FIELDS` 比对： + - 已在文件中（含旧版顶层布尔的 `changeTracking`）→ 跳过，不重复询问、不覆盖用户值。 + - 缺失的字段 → 重新询问（默认值按 `CONFIG_FIELDS[].default`），用户确认后写入。 +3. 已有字段的取值**始终不被 init 覆盖**；用户手工改过的值（如把 `false` 改成 `true`）会被保留。 + +含义：升级 npm 包后新增的字段，会以「当前 `CONFIG_FIELDS` 默认值」补齐到老项目；如新版本默认值翻面（例如某字段由 `false` 改为 `true`），**只影响**升级时**仍缺该字段**的老项目，已写过该字段的项目不变。 + +### 跑 `f2s-kb-upgrade` 时怎么让全局 flow2spec 保持最新 + +`f2s-kb-upgrade` SKILL 的「步骤 -1」（先于一切）**先做前台探测再决定是否升级**：主 agent 顺序跑 `flow2spec --version` + `npm view @double-coding/flow2spec version` + `command -v npx`，按 3 分支处理： + +- **A. 已装且是 latest** → **完全跳过**升级；步骤 2 命令首选 `flow2spec init `。 +- **B. 已装但落后** → 派**独立子 agent** 后台跑 `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；步骤 2 命令用 `npx @double-coding/flow2spec@latest init ` 保证本次拿到 latest 模板。 +- **C. 未装 / latest 未知** → 同 B 处理；探测全部失败时可放弃步骤 -1，由 cli.js 兜底。 + +口径： + +- **仅** B/C 时才派子 agent；派子**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）； +- 派子是 fire-and-forget，结果不进入 SKILL 结论摘要——失败也只是"下次再升一次"； +- 与 `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 不冲突：前者是 SKILL 入口按需异步派工，后者是 `init` 收尾兜底；两次都成功就是 no-op。 +- 用户自查用 `flow2spec --version`（当前全局版本）和 `flow2spec update`（CLI 内置自更新）。 + +## init 不动哪些目录 + +`flow2spec init` 仅对齐： + +- 配置根（Claude `.claude/` / Cursor `.cursor/` / Codex `.codex/`）下的 **rules / skills / hooks 模板** 与 SessionStart / PreToolUse 钩子注册； +- 包级 **manifest 路由结构骨架**（`flow2spec init` 通过 `manifest-matchers.json` 作为种子合并 matcher 分片）； +- 项目根 `flow2spec.config.json` 的缺失字段； +- 项目侧 `.Knowledge/manifest-routing.json` 的 `pkgRev` 顶层字段（每次 init 覆盖；详见下节「manifest 中的两个版本字段」）。 + +`init` **不修改**业务知识库内容： + +- `.Knowledge/stock-docs/`、`.Knowledge/req-docs/` +- `.Knowledge/topics/.md` 的路由摘要正文 +- `.Knowledge/matchers/.json` 的 `includeAny` 词条 + +这些由 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` 等 `f2s-*` 技能维护。把 `flow2spec init` 当作「业务知识库已更新」是常见误判（见统一入口 2a）。 + +## manifest 中的两个版本字段 + +`.Knowledge/manifest-routing.json` 同时存在两个顶层整数字段，对应 `f2s-kb-upgrade` 步骤 2c 的两侧： + +| 字段 | 语义 | 写入方 | +| --- | --- | --- | +| `projectRev` | **本项目已基线对齐到的包模板修订号** | `f2s-kb-upgrade` 完整流程末尾（3b）；首次 init 也按模板写入一次 | +| `pkgRev` | **本次 init 用的包模板修订号** | `flow2spec init`（每次都按当前包模板覆盖） | + +人读对照： + +- 两值**相等** → 主题层未变，`f2s-kb-upgrade` 走快速路径 +- `projectRev` 缺失 / `pkgRev` 大于 `projectRev` → 完整流程 +- `pkgRev` 缺失 → 包模板自身未声明该字段，SKILL 走兜底完整流程 + +`f2s-kb-upgrade` 步骤 2c 直接 `Read` 同一文件取这两个字段比对。 + +## 禁止项 + +- 禁止只改 `lib/flow2specConfig.js` 的 `DEFAULTS` 或 `CONFIG_FIELDS`、不同步改 `templates/{locale}/flow2spec.config.json` 与 `lib/codexAgentsAdapter.js` 的 `renderProjectConfigBlock`（四处必须同步）。 +- 禁止在新落盘中写出旧键 `subAgentVerification`。 +- 禁止把 `init` 作为业务知识库同步的入口；新增 / 修改 stock-docs / topics / matchers 走 `f2s-*` 技能。 diff --git a/.Knowledge/topics/f2s-kb-distill.md b/.Knowledge/topics/f2s-kb-distill.md index a380bba..f545ca6 100644 --- a/.Knowledge/topics/f2s-kb-distill.md +++ b/.Knowledge/topics/f2s-kb-distill.md @@ -5,108 +5,108 @@ summary: "f2s-kb-distill：Q&A 驱动知识提取与入库" primary: policy confidence: manual --- -# f2s-kb-distill：Q&A 驱动知识提取与入库 - -Q&A 驱动知识提取技能，从普通问答中自动萃取可复用知识事实并入库；根据下钻深度与描述层次自动判断创建新 topic 或追加到现有 topic。 - -## 适用场景 - -- 用户提问 → Agent 下钻源码回答 → 需要将发现的知识固化到知识库 -- 通常由 `f2s-kb-feedback-closing` 规则自动建议，也可用户手动调用 -- 与 `f2s-kb-sync` 区别：`sync` 用于批量同步多个能力；`distill` 专注单次 Q&A 知识提取 - -## 执行前依赖 - -本技能执行前须先读以下主题： - -- **`f2s-kb-feedback-closing`**：定义"可复用知识事实"边界（核心机制、状态流转、契约、配置影响、失败回退、模块边界、数据模型） -- **`f2s-topic-authoring`**：创建/修改 topic 时的命名、骨架、metadata、dependencies 准则 - -## 核心流程 - -### 执行挡位（agent 自动判，无命令参数） - -- **轻量挡**：跳过下钻评分 / 既有 topic 描述程度评估 / 决策矩阵 / 风格对齐；直接采上游 `f2s-kb-feedback-closing` 的「本轮将入库」概要做策略与目标 topicId 判定；步骤 5 路由 / 步骤 6 落盘照常执行 -- **严格挡**：跑完整 6 步 - -判挡 4 维度（**全满足**才走轻量挡，否则严格挡）：上游 case 必须是 case 2 / case 3；本轮 Read 业务源码 ≤ 3 个；本轮回答引用函数 / 类名 ≤ 5 个；用户追问未否定上游结论。 - -「业务源码」定义：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数。 - -### 输入（自动提取） - -- 用户问题：从对话历史自动提取 -- Agent 回答：完整回答内容 -- 已匹配 topic：若由 `f2s-kb-feedback-closing` 触发则携带 -- 下钻文件：从回答中提取引用的文件路径、函数名、行号 - -### 判断逻辑 - -**下钻深度评分**（0-50 分，累加）： -- 读文件数：0 / 1-2 / 3-5 / 6+ → 0 / 3 / 7 / 10 分 -- 分段读次数：0-1 / 2-4 / 5-8 / 9+ → 0 / 3 / 7 / 10 分 -- 函数引用数：0-2 / 3-5 / 6-10 / 11+ → 0 / 3 / 7 / 10 分 -- 代码片段长度：0-50 / 51-150 / 151-300 / 301+ 行 → 0 / 3 / 7 / 10 分 -- 回答长度：0-200 / 201-500 / 501-1000 / 1001+ 字符 → 0 / 3 / 7 / 10 分 - -**深度分类**： -- **浅层**（0-15 分）：简单问答，源码引用少 -- **中层**（16-30 分）：中等复杂度，多文件查阅 -- **深层**（31-50 分）：深入探索，大量源码分析 - -**知识描述层次**（按内容特征判断，非长度）： -- **摘要级**：仅结论性描述（"是什么"/"做什么"），无条件/流程/函数细节 -- **详细级**：含机制解释、流程步骤、关键判断条件（"当 X"、"若 Y 则"、"首先...然后..."） -- **实现级**：含函数调用关系、状态转换细节、边界条件处理、代码示例 - -**策略决策矩阵**： - -| 下钻深度 | 已匹配 topic | 现有 topic 描述层次 | 提取知识描述层次 | 策略 | -|---------|-------------|-------------------|-----------------|------| -| 浅层 | 匹配 | 摘要 | 摘要 | **追加到现有** | -| 浅层 | 匹配 | 摘要/详细 | 详细 | **追加到现有** | -| 浅层 | 匹配 | 摘要 | 实现 | **创建子 topic** | -| 浅层 | 未匹配 | - | 任意 | **创建新 topic** | -| 中层 | 匹配 | 摘要 | 摘要/详细 | **追加到现有** | -| 中层 | 匹配 | 摘要 | 实现 | **创建子 topic** | -| 中层 | 匹配 | 详细/实现 | 详细/实现 | **追加到现有** | -| 中层 | 未匹配 | - | 任意 | **创建新 topic** | -| 深层 | 匹配 | 摘要 | 任意 | **创建子 topic** | -| 深层 | 匹配 | 详细/实现 | 详细/实现 | **追加现有或创建子 topic** | -| 深层 | 未匹配 | - | 任意 | **创建独立模块 topic** | - -**决策关键**： -- 描述层次差距 ≥ 2 级（摘要 vs 实现）→ 强制创建子 topic -- 描述层次差距 = 1 级（摘要 vs 详细，或详细 vs 实现）→ 可追加 -- 描述层次匹配（同级）→ 正常追加 -- 深层下钻 ≥ 深层 → 优先创建子 topic - -### 落盘与路由同步 - -- **追加到现有 topic**：读取 2-3 个近邻 topic 样本对齐风格，在相关段落后追加内容 -- **创建子 topic**：生成新 topicId（基于父 topic + 焦点），更新父 topic 添加链接，写入 `topicDependencies` -- **创建独立模块 topic**：深层下钻时可选创建 stock-doc，topic 作为摘要 + 指针 -- **同步 manifest**：新 topic 写入 `topicPaths`、`taskToTopicRules`、matcher 分片；已有 topic 检查是否需补 `includeAny` -- **同步 index.md**：新 topic 添加条目，格式保持一致 - -### topicMetadata 处理 - -有明确证据时写入： -- 核心机制/状态流转/失败回退 → `policy` -- 配置开关影响 → `config` -- 模块边界/调用约定 → `module` -- 已实现能力/业务逻辑 → `feature` -- `confidence` 设为 `inferred` -- 无明确证据时不写，摘要中列为"待分类" - -## 边界与禁止项 - -- 只维护 `.Knowledge`，不改配置根 `rules/skills` -- 无需用户确认（Q&A 已验证知识正确性） -- 保持轻量，单次 Q&A 知识提取 30 秒内完成 -- 避免过度拆分：除非下钻深度 ≥ 深层且知识描述层次 ≥ 详细级，优先追加到现有 topic -- 生成的 matcher `includeAny` 应覆盖用户实际使用的表达，不仅是技术术语 - -## 指向长文 - -完整执行条令见配置根 `skills/f2s-kb-distill/SKILL.mdc`（Cursor/Claude）或 `.codex/skills/f2s-kb-distill/SKILL.mdc`（Codex）。 +# f2s-kb-distill：Q&A 驱动知识提取与入库 + +Q&A 驱动知识提取技能，从普通问答中自动萃取可复用知识事实并入库；根据下钻深度与描述层次自动判断创建新 topic 或追加到现有 topic。 + +## 适用场景 + +- 用户提问 → Agent 下钻源码回答 → 需要将发现的知识固化到知识库 +- 通常由 `f2s-kb-feedback-closing` 规则自动建议，也可用户手动调用 +- 与 `f2s-kb-sync` 区别：`sync` 用于批量同步多个能力；`distill` 专注单次 Q&A 知识提取 + +## 执行前依赖 + +本技能执行前须先读以下主题： + +- **`f2s-kb-feedback-closing`**：定义"可复用知识事实"边界（核心机制、状态流转、契约、配置影响、失败回退、模块边界、数据模型） +- **`f2s-topic-authoring`**：创建/修改 topic 时的命名、骨架、metadata、dependencies 准则 + +## 核心流程 + +### 执行挡位（agent 自动判，无命令参数） + +- **轻量挡**：跳过下钻评分 / 既有 topic 描述程度评估 / 决策矩阵 / 风格对齐；直接采上游 `f2s-kb-feedback-closing` 的「本轮将入库」概要做策略与目标 topicId 判定；步骤 5 路由 / 步骤 6 落盘照常执行 +- **严格挡**：跑完整 6 步 + +判挡 4 维度（**全满足**才走轻量挡，否则严格挡）：上游 case 必须是 case 2 / case 3；本轮 Read 业务源码 ≤ 3 个；本轮回答引用函数 / 类名 ≤ 5 个；用户追问未否定上游结论。 + +「业务源码」定义：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数。 + +### 输入（自动提取） + +- 用户问题：从对话历史自动提取 +- Agent 回答：完整回答内容 +- 已匹配 topic：若由 `f2s-kb-feedback-closing` 触发则携带 +- 下钻文件：从回答中提取引用的文件路径、函数名、行号 + +### 判断逻辑 + +**下钻深度评分**（0-50 分，累加）： +- 读文件数：0 / 1-2 / 3-5 / 6+ → 0 / 3 / 7 / 10 分 +- 分段读次数：0-1 / 2-4 / 5-8 / 9+ → 0 / 3 / 7 / 10 分 +- 函数引用数：0-2 / 3-5 / 6-10 / 11+ → 0 / 3 / 7 / 10 分 +- 代码片段长度：0-50 / 51-150 / 151-300 / 301+ 行 → 0 / 3 / 7 / 10 分 +- 回答长度：0-200 / 201-500 / 501-1000 / 1001+ 字符 → 0 / 3 / 7 / 10 分 + +**深度分类**： +- **浅层**（0-15 分）：简单问答，源码引用少 +- **中层**（16-30 分）：中等复杂度，多文件查阅 +- **深层**（31-50 分）：深入探索，大量源码分析 + +**知识描述层次**（按内容特征判断，非长度）： +- **摘要级**：仅结论性描述（"是什么"/"做什么"），无条件/流程/函数细节 +- **详细级**：含机制解释、流程步骤、关键判断条件（"当 X"、"若 Y 则"、"首先...然后..."） +- **实现级**：含函数调用关系、状态转换细节、边界条件处理、代码示例 + +**策略决策矩阵**： + +| 下钻深度 | 已匹配 topic | 现有 topic 描述层次 | 提取知识描述层次 | 策略 | +|---------|-------------|-------------------|-----------------|------| +| 浅层 | 匹配 | 摘要 | 摘要 | **追加到现有** | +| 浅层 | 匹配 | 摘要/详细 | 详细 | **追加到现有** | +| 浅层 | 匹配 | 摘要 | 实现 | **创建子 topic** | +| 浅层 | 未匹配 | - | 任意 | **创建新 topic** | +| 中层 | 匹配 | 摘要 | 摘要/详细 | **追加到现有** | +| 中层 | 匹配 | 摘要 | 实现 | **创建子 topic** | +| 中层 | 匹配 | 详细/实现 | 详细/实现 | **追加到现有** | +| 中层 | 未匹配 | - | 任意 | **创建新 topic** | +| 深层 | 匹配 | 摘要 | 任意 | **创建子 topic** | +| 深层 | 匹配 | 详细/实现 | 详细/实现 | **追加现有或创建子 topic** | +| 深层 | 未匹配 | - | 任意 | **创建独立模块 topic** | + +**决策关键**： +- 描述层次差距 ≥ 2 级（摘要 vs 实现）→ 强制创建子 topic +- 描述层次差距 = 1 级（摘要 vs 详细，或详细 vs 实现）→ 可追加 +- 描述层次匹配（同级）→ 正常追加 +- 深层下钻 ≥ 深层 → 优先创建子 topic + +### 落盘与路由同步 + +- **追加到现有 topic**：读取 2-3 个近邻 topic 样本对齐风格，在相关段落后追加内容 +- **创建子 topic**：生成新 topicId（基于父 topic + 焦点），更新父 topic 添加链接，写入 `topicDependencies` +- **创建独立模块 topic**：深层下钻时可选创建 stock-doc，topic 作为摘要 + 指针 +- **同步 manifest**：新 topic 写入 `topicPaths`、`taskToTopicRules`、matcher 分片；已有 topic 检查是否需补 `includeAny` +- **同步 index.md**：新 topic 添加条目，格式保持一致 + +### topicMetadata 处理 + +有明确证据时写入： +- 核心机制/状态流转/失败回退 → `policy` +- 配置开关影响 → `config` +- 模块边界/调用约定 → `module` +- 已实现能力/业务逻辑 → `feature` +- `confidence` 设为 `inferred` +- 无明确证据时不写，摘要中列为"待分类" + +## 边界与禁止项 + +- 只维护 `.Knowledge`，不改配置根 `rules/skills` +- 无需用户确认（Q&A 已验证知识正确性） +- 保持轻量，单次 Q&A 知识提取 30 秒内完成 +- 避免过度拆分：除非下钻深度 ≥ 深层且知识描述层次 ≥ 详细级，优先追加到现有 topic +- 生成的 matcher `includeAny` 应覆盖用户实际使用的表达，不仅是技术术语 + +## 指向长文 + +完整执行条令见配置根 `skills/f2s-kb-distill/SKILL.mdc`（Cursor/Claude）或 `.codex/skills/f2s-kb-distill/SKILL.mdc`（Codex）。 diff --git a/.Knowledge/topics/f2s-req-plan.md b/.Knowledge/topics/f2s-req-plan.md index 031b0da..fee78cf 100644 --- a/.Knowledge/topics/f2s-req-plan.md +++ b/.Knowledge/topics/f2s-req-plan.md @@ -6,30 +6,30 @@ dependsOn: [f2s-task] primary: policy confidence: manual --- -# f2s-req-plan（路由摘要） - -> 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。 -> **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。 -> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。 - -## 依赖 - -执行本主题前须先读依赖主题 **`f2s-task`**（`manifest-routing.topicDependencies`）。 - -## 作用 - -从技术方案或需求描述出发：**续作分诊 → 草稿确认 → 按 f2s-task 落盘 → 实现 → 归档**。 - -1. 步骤 0：`flow2spec.config.json` + **`f2s-task` 全文** -2. `f2s-task`「任务开始」：检查 `todo.json` / keywords 续作 -3. 草稿确认（主 agent） -4. 落盘 `task.md` / `context.md` / `user-todos.md` / `todo.json`（`linkedSkill: f2s-req-plan`） -5. 实现并按步打钩；用户代办写 `user-todos.md` -6. 满足归档门禁后移入 `completed/-/` - -不依赖 `changeTracking`，但 **始终** 服从 `f2s-task`。 - -## 下一步 - -- 技能全文：`skills/f2s-req-plan/SKILL.md` -- 任务规则：`rules/f2s-task.*` 或 `.codex/topics/f2s-task.md` +# f2s-req-plan（路由摘要） + +> 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。 +> **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。 +> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。 + +## 依赖 + +执行本主题前须先读依赖主题 **`f2s-task`**（`manifest-routing.topicDependencies`）。 + +## 作用 + +从技术方案或需求描述出发：**续作分诊 → 草稿确认 → 按 f2s-task 落盘 → 实现 → 归档**。 + +1. 步骤 0：`flow2spec.config.json` + **`f2s-task` 全文** +2. `f2s-task`「任务开始」：检查 `todo.json` / keywords 续作 +3. 草稿确认（主 agent） +4. 落盘 `task.md` / `context.md` / `user-todos.md` / `todo.json`（`linkedSkill: f2s-req-plan`） +5. 实现并按步打钩；用户代办写 `user-todos.md` +6. 满足归档门禁后移入 `completed/-/` + +不依赖 `changeTracking`，但 **始终** 服从 `f2s-task`。 + +## 下一步 + +- 技能全文：`skills/f2s-req-plan/SKILL.md` +- 任务规则：`rules/f2s-task.*` 或 `.codex/topics/f2s-task.md` diff --git a/.Knowledge/topics/f2s-req-tech.md b/.Knowledge/topics/f2s-req-tech.md index 2d99c88..1432c26 100644 --- a/.Knowledge/topics/f2s-req-tech.md +++ b/.Knowledge/topics/f2s-req-tech.md @@ -5,49 +5,49 @@ summary: "f2s-req-tech（路由摘要）" primary: policy confidence: inferred --- -# f2s-req-tech（路由摘要） - -> 长文见配置根 **`skills/f2s-req-tech/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-req-tech/SKILL.md`**。 - -## 作用 - -基于已澄清的需求和项目知识库，生成可直接用于实现的技术方案文档，落盘 `.Knowledge/req-docs/`。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。 - -## 适用场景 / 触发词 - -- 用户触发 `f2s-req-tech`、生成技术方案、技术方案文档。 -- 用户完成 `f2s-req-clarify` 后请求出方案。 -- 用户提供需求描述或 PRD 路径，要求生成后端技术方案、接口设计、数据模型等。 - -## 核心规则 - -1. **澄清前置门禁**：进入撰写前先判定需求是否已澄清；未澄清（有 3+ 未答关键问题 / 含"待定 / 大概 / 我打算"类模糊语，且**不是**从 `f2s-req-clarify` 衔接进入）则**先走 `f2s-req-clarify`**，由 clarify 落盘后自动衔接回本技能同轮继续，不打断用户。 -2. **允许的单跳同轮衔接**：`f2s-req-clarify` 澄清文档落盘 → 自动衔接 `f2s-req-tech`（同轮直连）；本技能落盘后**不再**自动衔接 `f2s-req-plan` / `implement-tech-design`。 -3. **先读模板**：执行前必须读取 `.Knowledge/template/技术方案模版.md` 作为结构参考。 -4. **章节积木原则**：模板章节为可选积木，按需取用；不硬套，不为套模板强行生成无关章节。 -5. **交付物与流程合一**：每个交付单元小节内同时写契约（输入/输出）与处理流程，禁止拆章重复。 -6. **对齐项目约定**：读取 `.Knowledge/topics/` 和 `stock-docs/` 中相关约定，命名/结构/错误码与现有项目一致。 -7. **拆子前置**：`subAgent=true` 时，主 agent 必须先产出「项目约定摘要」（< 80 行，含 6 类条款）方可拆子；未完成前置禁止拆子。 -8. **落盘停步**：方案落盘后**只输出一行提示**"技术方案已就绪：`<路径>`；如需继续可用 `f2s-req-plan` / `implement-tech-design`"，然后**停止**；同一轮内不得再自动衔接下一 `f2s-*` 技能，不得追加 `f2s-kb-distill` 收口块（过程编排型技能落盘不触发 distill，见 `rules/f2s-kb-feedback-closing.*` 禁止段）。 - -## 输出 - -- 默认路径：`.Knowledge/req-docs/<方案名>_技术方案.md` -- 完成后提示可据此进行代码实现（衔接 `implement-tech-design`）。 - -## 禁止项 - -- 禁止未读 `.Knowledge/template/技术方案模版.md` 直接生成文档。 -- 禁止在需求含明显未决问题 / 未澄清且非 clarify 衔接进入时直接撰写（应先走 `f2s-req-clarify` 由其自动衔接回本技能）。 -- 禁止为套模板强行填写与需求无关的章节（如无消息队列时强行写消息队列章节）。 -- 禁止拆章重复描述同一交付单元的流程。 -- 禁止臆造与项目不符的约定；不确定时标注「待与项目约定确认」。 -- 禁止方案落盘后在同一轮内自动衔接 `f2s-req-plan` / `implement-tech-design`（`f2s-req-clarify` → `f2s-req-tech` 是仅有的允许单跳，方案之后须新一轮触发）。 -- 禁止在方案文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示。 - -## 下一步 - -- 技能全文：`skills/f2s-req-tech/SKILL.md` -- 模板：`.Knowledge/template/技术方案模版.md` -- 前置澄清：`f2s-req-clarify` -- 实现：`implement-tech-design`（`rules/f2s-implement-tech-design.*`） +# f2s-req-tech（路由摘要） + +> 长文见配置根 **`skills/f2s-req-tech/SKILL.md`**；本仓模板源见 **`templates/skills/f2s-req-tech/SKILL.md`**。 + +## 作用 + +基于已澄清的需求和项目知识库，生成可直接用于实现的技术方案文档，落盘 `.Knowledge/req-docs/`。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。 + +## 适用场景 / 触发词 + +- 用户触发 `f2s-req-tech`、生成技术方案、技术方案文档。 +- 用户完成 `f2s-req-clarify` 后请求出方案。 +- 用户提供需求描述或 PRD 路径，要求生成后端技术方案、接口设计、数据模型等。 + +## 核心规则 + +1. **澄清前置门禁**：进入撰写前先判定需求是否已澄清；未澄清（有 3+ 未答关键问题 / 含"待定 / 大概 / 我打算"类模糊语，且**不是**从 `f2s-req-clarify` 衔接进入）则**先走 `f2s-req-clarify`**，由 clarify 落盘后自动衔接回本技能同轮继续，不打断用户。 +2. **允许的单跳同轮衔接**：`f2s-req-clarify` 澄清文档落盘 → 自动衔接 `f2s-req-tech`（同轮直连）；本技能落盘后**不再**自动衔接 `f2s-req-plan` / `implement-tech-design`。 +3. **先读模板**：执行前必须读取 `.Knowledge/template/技术方案模版.md` 作为结构参考。 +4. **章节积木原则**：模板章节为可选积木，按需取用；不硬套，不为套模板强行生成无关章节。 +5. **交付物与流程合一**：每个交付单元小节内同时写契约（输入/输出）与处理流程，禁止拆章重复。 +6. **对齐项目约定**：读取 `.Knowledge/topics/` 和 `stock-docs/` 中相关约定，命名/结构/错误码与现有项目一致。 +7. **拆子前置**：`subAgent=true` 时，主 agent 必须先产出「项目约定摘要」（< 80 行，含 6 类条款）方可拆子；未完成前置禁止拆子。 +8. **落盘停步**：方案落盘后**只输出一行提示**"技术方案已就绪：`<路径>`；如需继续可用 `f2s-req-plan` / `implement-tech-design`"，然后**停止**；同一轮内不得再自动衔接下一 `f2s-*` 技能，不得追加 `f2s-kb-distill` 收口块（过程编排型技能落盘不触发 distill，见 `rules/f2s-kb-feedback-closing.*` 禁止段）。 + +## 输出 + +- 默认路径：`.Knowledge/req-docs/<方案名>_技术方案.md` +- 完成后提示可据此进行代码实现（衔接 `implement-tech-design`）。 + +## 禁止项 + +- 禁止未读 `.Knowledge/template/技术方案模版.md` 直接生成文档。 +- 禁止在需求含明显未决问题 / 未澄清且非 clarify 衔接进入时直接撰写（应先走 `f2s-req-clarify` 由其自动衔接回本技能）。 +- 禁止为套模板强行填写与需求无关的章节（如无消息队列时强行写消息队列章节）。 +- 禁止拆章重复描述同一交付单元的流程。 +- 禁止臆造与项目不符的约定；不确定时标注「待与项目约定确认」。 +- 禁止方案落盘后在同一轮内自动衔接 `f2s-req-plan` / `implement-tech-design`（`f2s-req-clarify` → `f2s-req-tech` 是仅有的允许单跳，方案之后须新一轮触发）。 +- 禁止在方案文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示。 + +## 下一步 + +- 技能全文：`skills/f2s-req-tech/SKILL.md` +- 模板：`.Knowledge/template/技术方案模版.md` +- 前置澄清：`f2s-req-clarify` +- 实现：`implement-tech-design`（`rules/f2s-implement-tech-design.*`） diff --git a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md index 832e7ad..19ae76b 100644 --- a/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md +++ b/.Knowledge/topics/f2s-stock-docs-vs-req-docs.md @@ -5,28 +5,28 @@ summary: "f2s-doc-routing（路由摘要）" primary: policy confidence: manual --- -# f2s-doc-routing（路由摘要） - -> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。 -> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 - -## 本文件作用 - -- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。 -- 仅保留**目录分工**记忆点。 - -## 目录分工（须与规则一致） - -| 目录 | 用途 | -| --- | --- | -| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 | -| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 | - -**原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。 - -## 下一步读什么 - -| 环境 | 下一步 | -| --- | --- | -| Cursor / Claude | 打开或 @ **`rules/f2s-stock-docs-vs-req-docs`**。 | -| Codex | 读 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**。 | +# f2s-doc-routing（路由摘要） + +> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。 +> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。 + +## 本文件作用 + +- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。 +- 仅保留**目录分工**记忆点。 + +## 目录分工（须与规则一致） + +| 目录 | 用途 | +| --- | --- | +| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 | +| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 | + +**原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。 + +## 下一步读什么 + +| 环境 | 下一步 | +| --- | --- | +| Cursor / Claude | 打开或 @ **`rules/f2s-stock-docs-vs-req-docs`**。 | +| Codex | 读 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**。 | diff --git a/.Knowledge/topics/f2s-task.md b/.Knowledge/topics/f2s-task.md index d3247fe..ed13c47 100644 --- a/.Knowledge/topics/f2s-task.md +++ b/.Knowledge/topics/f2s-task.md @@ -5,56 +5,56 @@ summary: "f2s-task（路由摘要）" primary: policy confidence: manual --- -# f2s-task（路由摘要） - -> 长文见配置根 **`rules/f2s-task.*`**。 -> 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。 - -## 作用 - -变更追踪规则（`alwaysApply: true`）。当对应技能的 `changeTracking.*` 为 `true` 时，技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。 - -## 生效范围 - -| 配置项 | 对应技能 | -| --- | --- | -| `changeTracking.feat` | `f2s-kb-feat` | -| `changeTracking.fix` | `f2s-kb-fix` | -| `changeTracking.implement` | `f2s-implement-tech-design` | - -`f2s-req-plan` 不受配置约束，始终创建任务清单。 - -## 任务根 `TASK_ROOT`（多人） - -- 解析顺序：`collaboration.developerId`（config）→ git email/name → legacy `.task` -- 非 legacy 时目录为 `.task//…`；只读写当前 `TASK_ROOT`，禁止扫其他人的 todo（防串戏） -- `.Knowledge/` 仍全员共享 - -## 目录结构 - -``` -TASK_ROOT/ ← `.task` 或 `.task/` -├── todo.json ← 活跃任务索引（仅主 agent 写） -├── active// -│ ├── task.md ← checklist（执行步骤） -│ ├── context.md ← 涉及文件、文档链接 -│ ├── user-todos.md ← 须用户执行的代办（改库、配环境等） -│ └── acceptance.md ← 验收清单：task.md 全部 [x] 后、归档前生成 -└── completed/-/ - ├── task.md - ├── context.md - ├── user-todos.md - └── acceptance.md -``` - -用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**；归档前**必须**生成与 `task.md` 同目录的 **`acceptance.md`**（验收清单），二者职责分离。细则见配置根 **`rules/f2s-task.*`**。 - -## 跨会话续作 - -新会话先解析 `TASK_ROOT`；若存在该根下 `todo.json`，将用户首条消息与**仅该文件**内 `keywords` 匹配： -- 命中 → 展示剩余 checklist，摘要 user-todos / acceptance，加载 `linkedSkill`，提示是否继续 -- 无命中 → 不打扰 - -## 下一步 - -读配置根 `rules/f2s-task.*` 获取完整规则（目录结构、todo.json 格式、任务生命周期、Hook 配置）。 +# f2s-task（路由摘要） + +> 长文见配置根 **`rules/f2s-task.*`**。 +> 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。 + +## 作用 + +变更追踪规则（`alwaysApply: true`）。当对应技能的 `changeTracking.*` 为 `true` 时，技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。 + +## 生效范围 + +| 配置项 | 对应技能 | +| --- | --- | +| `changeTracking.feat` | `f2s-kb-feat` | +| `changeTracking.fix` | `f2s-kb-fix` | +| `changeTracking.implement` | `f2s-implement-tech-design` | + +`f2s-req-plan` 不受配置约束，始终创建任务清单。 + +## 任务根 `TASK_ROOT`（多人） + +- 解析顺序：`collaboration.developerId`（config）→ git email/name → legacy `.task` +- 非 legacy 时目录为 `.task//…`；只读写当前 `TASK_ROOT`，禁止扫其他人的 todo（防串戏） +- `.Knowledge/` 仍全员共享 + +## 目录结构 + +``` +TASK_ROOT/ ← `.task` 或 `.task/` +├── todo.json ← 活跃任务索引（仅主 agent 写） +├── active// +│ ├── task.md ← checklist（执行步骤） +│ ├── context.md ← 涉及文件、文档链接 +│ ├── user-todos.md ← 须用户执行的代办（改库、配环境等） +│ └── acceptance.md ← 验收清单：task.md 全部 [x] 后、归档前生成 +└── completed/-/ + ├── task.md + ├── context.md + ├── user-todos.md + └── acceptance.md +``` + +用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**；归档前**必须**生成与 `task.md` 同目录的 **`acceptance.md`**（验收清单），二者职责分离。细则见配置根 **`rules/f2s-task.*`**。 + +## 跨会话续作 + +新会话先解析 `TASK_ROOT`；若存在该根下 `todo.json`，将用户首条消息与**仅该文件**内 `keywords` 匹配： +- 命中 → 展示剩余 checklist，摘要 user-todos / acceptance，加载 `linkedSkill`，提示是否继续 +- 无命中 → 不打扰 + +## 下一步 + +读配置根 `rules/f2s-task.*` 获取完整规则（目录结构、todo.json 格式、任务生命周期、Hook 配置）。 diff --git a/.Knowledge/topics/skill-authoring.md b/.Knowledge/topics/skill-authoring.md index 1a90c98..4782430 100644 --- a/.Knowledge/topics/skill-authoring.md +++ b/.Knowledge/topics/skill-authoring.md @@ -5,88 +5,88 @@ summary: "skill-authoring（路由摘要）" primary: policy confidence: inferred --- -# skill-authoring（路由摘要） - -> 适用范围：在 **本仓**（Flow2Spec 产品开发仓）新增或重构 `f2s-*` SKILL 时遵循。**不下发**到下游业务仓——下游不写 `f2s-*` SKILL，本主题对其无意义。 - -## 作用 - -统一 `templates/skills/f2s-*/SKILL.md` 的小标题命名与排列顺序，避免同类信息出现多种写法（`## 输入` / `## 入参` / `## 传参`；`## 步骤` / `## 执行流程` / `## 强制流程`）造成跨 SKILL 维护心智成本。本主题**只规定命名与顺序**，不限制正文风格。 - -## SKILL 骨架（必填段标 ✱，可选段标 ◇） - -``` ---- -name: f2s- -description: <一句话 + 「；触发：<词1>、<词2>、<词3>」> ---- - -> 执行口径：<本技能维护什么 / 不动什么 / 是否绑配置开关；一段话> - -# <主标题> - -## 与既有技能的边界 ◇ ← 触发词高度近似时建议写 -## 适用范围 ✱ ← 替代旧版「使用时机/何时使用/适用场景」 -## 编排 ✱ ← 主 / 子 agent 切分；指向 unified-entry 取 subAgent / switchAgentVerification 语义 -## 输入 ✱ ← 替代旧版「入参/传参」 -## 强制前置 ◇ ← 本技能在步骤前必须 Read 的 rule / 配置文件 -## 流程 ✱ ← 替代旧版「步骤/执行步骤/执行流程/强制流程」 - ### 步骤 N: <动词短语> ← 子标题统一「步骤 N」前缀；编号与正文顺序一致 -## 输出摘要 ✱ ← 替代旧版「输出摘要格式/模板（建议）」 -## 约束与禁止项 ✱ ← 合并旧版「约束 / 路径与引用约束 / 禁止项」 -## 复杂场景示例 ◇ ← 易踩坑的技能写 1–3 个 -## 完成后自检 ✱ ← 编号列表；每条对应可校验的事实 -``` - -## 字段约定 - -### `description` - -- 一句话说明做什么 + 半句话触发条件，末尾接 `；触发：<词1>、<词2>、<词3>`。 -- 触发词与同名 `matchers/.json` 的 `includeAny` 保持口径一致。 -- 不写实现细节 / 模型选择 / 提示工程技巧。 - -### `执行口径`（顶部 blockquote） - -- 一段话讲清三件事：**维护哪些路径** / **不动哪些路径** / **是否绑某个 `flow2spec.config.json` 字段**。 -- 例：「本技能只维护 `.Knowledge`，不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`。」 - -### `编排` - -- `subAgent` / `switchAgentVerification` 语义统一指向 `f2s-flow2spec-unified-entry`，**不复述定义**——只写本技能在该字段为 `true` / `false` 时的差异化行为。 -- 写权硬约束（哪些文件恒由主 agent 落盘）单独成一行。 -- 验证策略（落盘侧自验 / 交叉校验）单独成一行。 - -### `流程` - -- 子标题统一 `### 步骤 N: <动词短语>`，全文冒号风格统一。 -- 编号从 1 起；`0` / `0.5` 是历史包袱，新 SKILL 避免使用——前置改放 `## 强制前置`。 -- 每步开头一句"做什么"，再列约束 / 落盘文件 / 输出形态。 - -### `约束与禁止项` - -- 列表式，肯定式优先（参见 `f2s-flow2spec-unified-entry`「知识库落盘文风」）。 -- 排他性选择例外。 -- 写权硬约束已在「编排」写过则不复述，本节仅列领域级禁止项（如"不动配置根 `rules/skills`"）。 - -### `完成后自检` - -- 每条对应可校验的事实（agent 能用 `Read` / `Grep` 验证），避免"是否合理 / 是否充分"这类主观项。 -- 命中本技能特有风险点（例：`f2s-kb-addRules` 必检"是否在用户未确认前提前落盘"）。 - -## 不规定的事 - -- **正文风格**：每个 SKILL 按场景需要写散文 / 表格 / 流程图，本主题不限定。 -- **小节内部顺序**：例如「编排」节内各点的排列，按 SKILL 实际重要性排。 -- **是否复述配置开关**：默认指向 unified-entry 不复述；若需强调某字段对自身的特殊影响（如 `f2s-doc-milestone` 不受 `flow2spec.config` 编排开关影响），可在「编排」节单独写一句。 - -## 参考实现 - -- 最近按本模板写的：`templates/skills/f2s-kb-addRules/SKILL.md`（含「与既有技能的边界」「强制前置」「步骤 1–5」「输出摘要」「约束」「复杂场景示例」「完成后自检」）。 -- 风格接近的旧 SKILL：`templates/skills/f2s-kb-build/SKILL.md`（小标题用「步骤 N：xxx」而非子标题，下次维护时顺手降级即可）。 - -## 演进策略 - -- **新 SKILL**：必须按本模板写。 -- **存量 SKILL**：不强制批量改名；下次维护到某个 SKILL 时顺手对齐到本模板。 -- **离群严重**（`f2s-doc-arch` / `f2s-doc-final` / `f2s-kb-merge` / `f2s-req-clarify` 等缺多个必填段）单独立项重构，不与日常维护混在一起。 +# skill-authoring（路由摘要） + +> 适用范围：在 **本仓**（Flow2Spec 产品开发仓）新增或重构 `f2s-*` SKILL 时遵循。**不下发**到下游业务仓——下游不写 `f2s-*` SKILL，本主题对其无意义。 + +## 作用 + +统一 `templates/skills/f2s-*/SKILL.md` 的小标题命名与排列顺序，避免同类信息出现多种写法（`## 输入` / `## 入参` / `## 传参`；`## 步骤` / `## 执行流程` / `## 强制流程`）造成跨 SKILL 维护心智成本。本主题**只规定命名与顺序**，不限制正文风格。 + +## SKILL 骨架（必填段标 ✱，可选段标 ◇） + +``` +--- +name: f2s- +description: <一句话 + 「；触发：<词1>、<词2>、<词3>」> +--- + +> 执行口径：<本技能维护什么 / 不动什么 / 是否绑配置开关；一段话> + +# <主标题> + +## 与既有技能的边界 ◇ ← 触发词高度近似时建议写 +## 适用范围 ✱ ← 替代旧版「使用时机/何时使用/适用场景」 +## 编排 ✱ ← 主 / 子 agent 切分；指向 unified-entry 取 subAgent / switchAgentVerification 语义 +## 输入 ✱ ← 替代旧版「入参/传参」 +## 强制前置 ◇ ← 本技能在步骤前必须 Read 的 rule / 配置文件 +## 流程 ✱ ← 替代旧版「步骤/执行步骤/执行流程/强制流程」 + ### 步骤 N: <动词短语> ← 子标题统一「步骤 N」前缀；编号与正文顺序一致 +## 输出摘要 ✱ ← 替代旧版「输出摘要格式/模板（建议）」 +## 约束与禁止项 ✱ ← 合并旧版「约束 / 路径与引用约束 / 禁止项」 +## 复杂场景示例 ◇ ← 易踩坑的技能写 1–3 个 +## 完成后自检 ✱ ← 编号列表；每条对应可校验的事实 +``` + +## 字段约定 + +### `description` + +- 一句话说明做什么 + 半句话触发条件，末尾接 `；触发：<词1>、<词2>、<词3>`。 +- 触发词与同名 `matchers/.json` 的 `includeAny` 保持口径一致。 +- 不写实现细节 / 模型选择 / 提示工程技巧。 + +### `执行口径`（顶部 blockquote） + +- 一段话讲清三件事：**维护哪些路径** / **不动哪些路径** / **是否绑某个 `flow2spec.config.json` 字段**。 +- 例：「本技能只维护 `.Knowledge`，不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`。」 + +### `编排` + +- `subAgent` / `switchAgentVerification` 语义统一指向 `f2s-flow2spec-unified-entry`，**不复述定义**——只写本技能在该字段为 `true` / `false` 时的差异化行为。 +- 写权硬约束（哪些文件恒由主 agent 落盘）单独成一行。 +- 验证策略（落盘侧自验 / 交叉校验）单独成一行。 + +### `流程` + +- 子标题统一 `### 步骤 N: <动词短语>`，全文冒号风格统一。 +- 编号从 1 起；`0` / `0.5` 是历史包袱，新 SKILL 避免使用——前置改放 `## 强制前置`。 +- 每步开头一句"做什么"，再列约束 / 落盘文件 / 输出形态。 + +### `约束与禁止项` + +- 列表式，肯定式优先（参见 `f2s-flow2spec-unified-entry`「知识库落盘文风」）。 +- 排他性选择例外。 +- 写权硬约束已在「编排」写过则不复述，本节仅列领域级禁止项（如"不动配置根 `rules/skills`"）。 + +### `完成后自检` + +- 每条对应可校验的事实（agent 能用 `Read` / `Grep` 验证），避免"是否合理 / 是否充分"这类主观项。 +- 命中本技能特有风险点（例：`f2s-kb-addRules` 必检"是否在用户未确认前提前落盘"）。 + +## 不规定的事 + +- **正文风格**：每个 SKILL 按场景需要写散文 / 表格 / 流程图，本主题不限定。 +- **小节内部顺序**：例如「编排」节内各点的排列，按 SKILL 实际重要性排。 +- **是否复述配置开关**：默认指向 unified-entry 不复述；若需强调某字段对自身的特殊影响（如 `f2s-doc-milestone` 不受 `flow2spec.config` 编排开关影响），可在「编排」节单独写一句。 + +## 参考实现 + +- 最近按本模板写的：`templates/skills/f2s-kb-addRules/SKILL.md`（含「与既有技能的边界」「强制前置」「步骤 1–5」「输出摘要」「约束」「复杂场景示例」「完成后自检」）。 +- 风格接近的旧 SKILL：`templates/skills/f2s-kb-build/SKILL.md`（小标题用「步骤 N：xxx」而非子标题，下次维护时顺手降级即可）。 + +## 演进策略 + +- **新 SKILL**：必须按本模板写。 +- **存量 SKILL**：不强制批量改名；下次维护到某个 SKILL 时顺手对齐到本模板。 +- **离群严重**（`f2s-doc-arch` / `f2s-doc-final` / `f2s-kb-merge` / `f2s-req-clarify` 等缺多个必填段）单独立项重构，不与日常维护混在一起。