diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index a8f5118..8b1d82e 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -1,7 +1,5 @@ { "version": "3.2.12", - "projectRev": 2, - "pkgRev": 2, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", "sourceOfTruth": ".Knowledge/manifest-routing.json", @@ -24,6 +22,7 @@ "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", "f2s-task": ".Knowledge/topics/f2s-task.md", "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", + "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.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", @@ -33,8 +32,7 @@ "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", - "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md" + "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md" }, "taskToTopicRules": [ { @@ -78,6 +76,14 @@ "f2s-req-plan" ] }, + { + "task": "flow2spec-dsh-adapter", + "matcherId": "m-flow2spec-dsh-adapter", + "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", + "topics": [ + "flow2spec-dsh-adapter" + ] + }, { "task": "git-commit", "matcherId": "m-f2s-git-commit", @@ -157,16 +163,10 @@ "topics": [ "flow2spec-doctor" ] - }, - { - "task": "flow2spec-dsh-adapter", - "matcherId": "m-flow2spec-dsh-adapter", - "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", - "topics": [ - "flow2spec-dsh-adapter" - ] } ], + "projectRev": 2, + "pkgRev": 2, "topicMetadata": { "implement-tech-design": { "primary": "policy", diff --git a/.Knowledge/template/index.template.md b/.Knowledge/template/index.template.md index 8f6f507..bce6b9d 100644 --- a/.Knowledge/template/index.template.md +++ b/.Knowledge/template/index.template.md @@ -28,6 +28,7 @@ | config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关 | Codex 长文：仓库根 `.codex/topics/f2s-config-check.md`；[路由摘要](topics/f2s-config-precheck.md) | | f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话续作 | 长文：配置根 `rules/f2s-task.*`；Codex：`.codex/topics/f2s-task.md` | | f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现；始终维护 `.task/` | 技能：`skills/f2s-req-plan/SKILL.md`；依赖 `f2s-task` | +| flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh` 与 DeepSeek Harness 项目技能发现 | 用户文档：`docs/使用说明.md`；实现：`lib/dshAgentsAdapter.js` | 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`。 diff --git a/.dsh/AGENTS.md b/.dsh/AGENTS.md new file mode 100644 index 0000000..e0013e0 --- /dev/null +++ b/.dsh/AGENTS.md @@ -0,0 +1,6 @@ +# Flow2Spec（`.dsh/` 目录说明） + +DeepSeek Harness 从仓库根 [`AGENTS.md`](../AGENTS.md) 加载完整项目说明。 + +- `skills/`：DeepSeek Harness 可发现的 Flow2Spec `f2s-*` 技能 +- `topics/`：按需读取的规则长文镜像 diff --git a/.dsh/skills/f2s-doc-arch/SKILL.md b/.dsh/skills/f2s-doc-arch/SKILL.md new file mode 100644 index 0000000..23b7c76 --- /dev/null +++ b/.dsh/skills/f2s-doc-arch/SKILL.md @@ -0,0 +1,128 @@ +--- +name: f2s-doc-arch +description: 根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿 +--- +> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-kb-build`）同步到 `.Knowledge/topics/index/manifest`。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 +- 当 `subAgent=true` 时，从以下两种子策略择一： + - **B 模式（默认，单轮并行）**：主先产出「inventory（入口 + 核心模块名，主手写）」+「扫描契约（可读路径 / 禁扫目录 / 统一产出字段）」→ 子 agent 并行只读扫表 → 主一轮合并去重 → 写 `stock-docs` 初稿 → 用户确认与验收在主 agent 内完成。 + - **C 模式（多轮纠偏）**：切换判据为以下任一 —— 多 workspace / monorepo、目录极深或源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合 / 矛盾严重。 +- **子交付硬约束**：子 agent 不得自行裁剪目录范围，必须按主手写 inventory 执行；子交付按「子交付 YAML schema」（字段：`source` / `scope` / `cross_refs` / `pending`），禁止散文式回传。 +- **写权硬约束**：`.Knowledge/index.md` / `manifest-routing.json` 恒由主 agent 落盘，子 agent 不得触碰。 +- 落盘侧自验；本 SKILL 不绑定交叉校验。 + +# 生成项目架构说明（初稿） + +本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。 + +**与 f2s-kb-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-kb-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-kb-add`**，**勿用本技能冒充该流程**。 + +--- + +## 入参（均可选） + +| 参数 | 说明 | +| -------------- | -------------------------- | +| **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 | +| **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 | + +**注意**：不传任何说明或文档时，将使用 **AI 扫描项目代码与目录** 生成架构说明初稿，**不保证质量**。执行时**必须先提示用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才继续。 + +--- + +## 执行流程 + +### 1. 若用户提供了说明或文档 + +1. **读取与理解** + - 若第一参数是**文档路径**：在配置根的父目录下按路径读取该文件内容（支持 .md、.txt 等文本格式）。 + - 若第一参数是**纯文字说明**：直接以用户输入为「用户说明」。 +2. **结合项目补充** + - 根据用户说明中的**代码路径、模块名、入口**等线索，结合配置根的父目录下的实际目录结构、关键文件（如 package.json、入口文件、配置文件）进行**归纳与补全**。 + - 若用户说明较宽泛（如只说了「一个后台系统」），**主动引导**用户补充：主要代码路径、模块/包划分、入口与启动方式、与外部系统的边界等，便于生成更贴合的架构说明。 +3. **生成初稿** + - 若启用拆子（B 模式），子 agent 必须按主手写 inventory 执行扫描，交付遵循子交付 YAML schema。 + - 产出一份**项目架构说明**：可包含但不限于：项目定位、技术栈、目录/模块划分、关键路径与入口、配置与部署要点、与文档产物阶段的对应说明（若适用）。 + - **无固定格式**：采用清晰的标题与段落即可，不强制套用《终稿模版》。 +4. **输出** + - 默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`；若用户传入第二参数则写入该路径。 + - 若目录不存在则先创建。 + +### 2. 若用户未提供任何说明或文档 + +1. **提醒并确认** + - 明确说明：「**未收到任何参数。** 不传递说明或文档时，将使用 AI 扫描项目代码与目录生成架构说明初稿，**不保证质量**，且易遗漏重点、难以区分主次。建议先提供一段简要说明或已有文档（如 README、设计 doc）再执行本技能。」 + - **必须询问用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」 + - 仅当用户**明确确认**（如回复「确认」「是」「直接扫描」等）后，才继续步骤 2；若用户未确认或表示取消，则不再执行扫描与生成。 +2. **扫描与生成** + - 基于配置根的父目录：列出主要目录与代表性文件（可结合 package.json、常见入口与配置文件名），归纳出「目录结构、疑似模块、入口与配置」等。 + - 生成一份**架构说明初稿**，并在文中注明「本初稿由扫描项目结构生成，建议结合业务说明与代码细节进一步补充」。 +3. **输出** + - 同上，默认 `.Knowledge/stock-docs/架构说明_初稿.md`，或用户指定的第二参数。 + +--- + +## 引导与迭代 + +- 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。 + +## 大功能拆分建议 + +扫描或理解完源码/说明后，若识别出以下任一信号，须在初稿**末尾**输出「拆分建议」段落，供用户参考（不阻断生成）： + +- 源码总量超过 **~5000 行**，或涉及文件超过 **20 个**； +- 能明显识别出 **3 个以上不相干职责域**（如接口层 / 核心规则 / 数据模型 / 外部依赖各自独立）； +- 用户说明本身已提到「多个子模块」或「多个功能」。 + +**拆分建议格式**（写在初稿末尾，独立节）： + +``` +## 拆分建议 + +当前功能体量较大，建议拆成多份 focused stock-doc，各自对应一个独立 topic： + +| 建议文档 | 主要内容 | 建议 topic primary | +|---|---|---| +| <功能名>-概述_初稿.md | 入口边界、子模块关系、快速索引 | feature | +| <功能名>-业务规则_初稿.md | 核心流程、门禁、状态机 | policy | +| <功能名>-数据模型_初稿.md | 表结构、枚举、模型约定 | module | +| <功能名>-外部依赖_初稿.md | SOA/QMQ/Redis/风控封装 | config | + +拆分后各子 topic 通过各自 matcher 独立命中，主 topic 正文写导航链接； +不通过 topicDependencies 串联"概述 → 详情"（见 f2s-topic-authoring 第 5 节）。 +``` + +用户可选择：**A) 按拆分建议分别执行 `f2s-doc-arch`**（推荐），或 **B) 继续用当前单份初稿**进入后续流程。 + +## 完成后的下一步（硬约束） + +本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-kb-build`： + +1. 告知初稿路径，建议用户先审阅、补充内容。 +2. **下一步必须为 `f2s-doc-final`**：以初稿路径为入参，产出 `.Knowledge/stock-docs/<方案名>_终稿.md`（《终稿模版》规范格式）。 +3. **仅在终稿落盘后**再引导 **`f2s-kb-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。 +4. **禁止**在完成回复中单独写「请执行 `f2s-kb-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-kb-build` 与 `f2s-doc-final` 并列成「二选一」。 +5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-kb-build`。 + +**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-kb-build`，且 ctx-build 在终稿之后）： + +> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-kb-build <终稿路径>`** 同步知识路由主题与索引。 + +--- + +## 路径与输出约定 + +- 所有路径均相对于**配置根的父目录**。 +- **默认输出**：`.Knowledge/stock-docs/架构说明_初稿.md`；项目名取自 `package.json` 的 `name`（去掉 scope 与非法字符）或当前目录名。 +- 若用户传入第二参数为输出路径，则优先使用该路径；若目录不存在则先创建。 + +--- + +## 约束与注意 + +- **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。 +- **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。 +- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-kb-build`**；不得仅推荐 build。 diff --git a/.dsh/skills/f2s-doc-final/SKILL.md b/.dsh/skills/f2s-doc-final/SKILL.md new file mode 100644 index 0000000..27d804f --- /dev/null +++ b/.dsh/skills/f2s-doc-final/SKILL.md @@ -0,0 +1,92 @@ +--- +name: f2s-doc-final +description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-kb-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版 +--- + +> 执行口径：初稿/终稿统一写入 `.Knowledge/stock-docs/`；模板优先读取 `.Knowledge/template/终稿模版.md`。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 +- **默认不拆子**：MD / PDF → 终稿模版的连贯性最好，由主会话一气呵成完成理解、套模版与定稿。 +- **可选拆子**（仅当 `subAgent=true` 且大体量 / 多文件，阈值：PDF **> 50 页** 或 **> ~5MB 文本**）：子 agent 做「套模版、排版与结构搬运」**草稿**；主 agent 对照终稿模版、识别缺口并向用户追问、与用户对齐并**定稿 / 验收**；**子 agent 不得单独宣称终稿已合规**。 +- 不为「格式转换可独立」默认拆子：终稿合规依赖模版语义 + 业务表述，主侧验收成本通常仍在。 +- 校验：落盘侧 agent 自验，本 SKILL 不绑定交叉校验。 + +# 将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context） + +用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-kb-build** 技能消费的终稿风格 Markdown 文档。 + +**终稿模版仅作提示**：若存在 `.Knowledge/template/终稿模版.md`，可读取作为结构参考；不强制套用。 + +## 内嵌模板结构（当项目内无 `.Knowledge/template/终稿模版.md` 时使用） + +规范要求： + +- **一级标题**：方案名（如 `# xxx 技术方案设计`）。 +- **二级标题至少包含**：`## 核心概念`、`## 业务规则`、`## 关键流程`；其余可按需增删（如 状态与流转、接口、配置/表设计/错误码、实现位置与对接方式）。 +- **核心概念**：用表格列出术语、实体、关键 ID（列：概念、说明）。 +- **状态与流转**：若有状态机，用列表写状态及流转；若无可简述或省略。 +- **业务规则**：列表写约束、校验、配置项。 +- **关键流程**：按「用户侧或系统侧」主流程，列表写流程名、步骤简述、入口接口/方法、结果。 +- **可选章节**：接口、配置/表设计/错误码、实现位置与对接方式，按需保留并填写。 + +--- + +## 流程一：用户传入的是 Markdown（.md） + +1. **读取**用户传入的 `.md` 文件内容。 +2. **参考格式**（不强制）：若存在 `.Knowledge/template/终稿模版.md`，可读取作为结构提示；否则可参考下方内嵌模板结构。 +3. **分析与转换**： + - 理解原文主题与结构，提炼「方案名」「核心概念」「业务规则」「关键流程」及与原文相关的其他章节（如状态与流转、接口、配置/表设计/错误码、实现位置等）。 + - 将内容重组为结构清晰的终稿风格 Markdown：一级标题为方案名；建议至少包含 核心概念、业务规则、关键流程 三个二级标题，其余按原文有无与需要增删；表格/列表格式可参考模版，不必完全一致。 + - 若原文缺少某节，可标「（待补充）」或根据原文推断补全；若原文结构已清晰，可保留原文章节命名。 +4. **输出**： + - 默认写入 `.Knowledge/stock-docs/<方案名>_终稿.md`（最终产物带 `_终稿` 标识）。 + - 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。 +5. **回复**：告知用户已生成 `.Knowledge/stock-docs/<方案名>_终稿.md`，并提示可按 `f2s-kb-build` 继续同步 `.Knowledge/topics`、`.Knowledge/index.md`（必要时 `manifest`）。 + +--- + +## 流程二：用户传入的是 PDF（.pdf） + +分两步完成：**先 PDF → 初稿 MD，用户确认后再 初稿 MD → 模板格式 MD**。 + +### 步骤 A：首次执行（传入 PDF 路径） + +1. **尝试读取 PDF**：按用户传入路径读取 PDF（可为绝对路径，或相对项目根；如 `.Knowledge/stock-docs/xxx.pdf`）。 + - 若当前环境可解析 PDF 文本：提取正文，转为 Markdown 初稿（保留标题层级、列表、段落，表格若可识别则保留）。 + - 若无法直接读取 PDF（如仅能拿到二进制）：回复用户可将 PDF 内容转存为 `.Knowledge/stock-docs/xxx.md` 后再执行。 +2. **生成初稿**： + - 将提取出的内容保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`（方案名可从 PDF 文件名或首标题推断）。 + - 在回复中**展示初稿的全文或主要结构**，并明确说明： + - 「初稿已保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`，请检查并修改。」 + - 「确认无误后，请执行：`f2s-doc-final .Knowledge/stock-docs/<方案名>_初稿.md`。」 +3. **本轮不进行模板格式转换**，仅完成 PDF → 初稿 MD。 + +### 步骤 B：用户确认后再次执行（传入初稿 .md 路径） + +当用户**再次执行本技能并传入初稿的 .md 路径**（如 `.Knowledge/stock-docs/技术方案设计_初稿.md`）时： + +- 按 **「流程一：用户传入的是 Markdown」** 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。 +- **输出建议**：生成 `.Knowledge/stock-docs/<方案名>_终稿.md`。 +- **回复**：告知已生成规范版，并提示可按 `f2s-kb-build` 继续同步 `.Knowledge/topics` 与索引。 + +--- + +## 路径与输出约定 + +- 所有路径均相对于项目根；初稿/终稿统一放在 `.Knowledge/stock-docs/`。 +- **输入**：第一个参数为文件路径（必填），如 `.Knowledge/stock-docs/方案.pdf` 或 `.Knowledge/stock-docs/方案_初稿.md`；第二个参数可选。 +- **输出**： + - PDF 首次：`.Knowledge/stock-docs/<方案名>_初稿.md` + - MD 或初稿 MD：`.Knowledge/stock-docs/<方案名>_终稿.md` +- 若 `.Knowledge/stock-docs/` 目录不存在，先创建再写入。 + +--- + +## 约束与注意 + +- 转换时**不要照抄原文**，要按模板**提炼、归纳、补全**，使核心概念、业务规则、关键流程清晰可查。 +- 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。 +- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-kb-build` 同步知识路由主题与索引。 diff --git a/.dsh/skills/f2s-doc-milestone/SKILL.md b/.dsh/skills/f2s-doc-milestone/SKILL.md new file mode 100644 index 0000000..f4789bc --- /dev/null +++ b/.dsh/skills/f2s-doc-milestone/SKILL.md @@ -0,0 +1,148 @@ +--- +name: f2s-doc-milestone +description: 据 req-docs、git log、.task 与知识库主题语义生成里程碑（《项目里程碑模版》）；触发：f2s-doc-milestone、生成项目里程碑、里程碑。命令后可附语义化范围。本技能固定子 agent 生成、主 agent 验证，不受 flow2spec.config 编排开关影响 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> 执行口径：读 `.Knowledge/template/项目里程碑模版.md`；落盘 **仅** `.Knowledge/stock-docs/<范围名>里程碑.md`（无第二路径参数）。 + +## 编排（固定，不受项目配置影响） + +**本技能不受** `flow2spec.config.json` 中 **`subAgent`**、**`switchAgentVerification`**（及旧键 `subAgentVerification`）**影响**：无论其为 `true` 或 `false`，**一律**按下述分工执行，**禁止**因配置改为「全主会话」或「子 agent 自验即结束」。 + +| 角色 | 步骤 | 职责 | +| --- | --- | --- | +| **主 agent** | 0、3、4 | 读模版与知识库主题索引、解析范围、派子、**验证**、必要时修订、回复用户 | +| **子 agent** | 1、2 | 采集四源、套模版、**Write 初稿** | + +1. **主 agent**：步骤 0 → 下发「采集契约」→ 子 agent 步骤 1–2 落盘初稿。 +2. **主 agent**：步骤 3 对照四源与「重要节点清单」验证（不全文重写；补缺、纠偏、「待确认」）→ 步骤 4 回复。 +3. 子 agent **禁止**宣称「里程碑已验收完成」；终稿以主 agent 验证后为准。 + +> 步骤 0 仍 **`Read("flow2spec.config.json")`**（满足 `f2s-config-check` 前置），但**不得**用其中的 `subAgent` / `switchAgentVerification` 改变本技能编排。 + +**子 agent 采集契约（主 agent 派子前写入 prompt）** + +| 字段 | 内容 | +| --- | --- | +| `scope` | 用户语义范围一句 | +| `outputPath` | `stock-docs/<范围名>里程碑.md` | +| `sources` | 见下文「四源」；**须含知识库主题语义** | +| `template` | `.Knowledge/template/项目里程碑模版.md`（不写模版顶部说明 blockquote） | +| `delivery` | 完整 Markdown，可直接 `Write` 至 `outputPath` | +| `stagePolicy` | 见下文「阶段粒度」；契约中须复述一句 | + +## 阶段粒度（必须，写入契约） + +里程碑 **Mx 仅记录功能/能力变更**：当前仓库（或用户指定范围内）**已落地或可核验**的交付，例如模块/接口/数据模型/领域行为/知识库路由等，且须在四源中有依据。 + +**不得**单独占一行总览或独立 `## Mx ·` 的阶段类型（无四源交付支撑时禁止臆造；有交付也不得拆成「纯测试/纯联调」阶段）： + +- 联调、集成测试、UAT、回归、验收、提测、上线检查（仅过程、无功能 diff） +- 仅环境/运维动作（执行 DDL、填配置、发版窗口、跨仓排期）且**无**本范围功能交付 +- 以「稳定化 / 工程化 / 收尾」为名、实质仅为上述过程性工作的阶段 + +**合并规则**：同一次能力迭代内的工程性改动（如 id 类型对齐、分页格式、锁与并发）**并入**对应功能阶段正文，不另起「联调 / 测试 / 验收」阶段。 + +**缺口处理**：四源仅提及待联调、待验收、环境待补齐而无本范围功能交付 → **不写**对应 Mx；可在 **待确认** 列一句，**禁止**用「计划项」填充总览表。 + +## 四源（采集与验证均须覆盖） + +| 源 | 读什么 | 里程碑里怎么用 | +| --- | --- | --- | +| **req-docs** | 范围内 `.Knowledge/req-docs/*.md` | 需求/方案节点、交付摘要 | +| **git** | `git log --no-merges`、`git tag -l`、`package.json` 版本 | 时间线、大版本/tag、提交锚点 | +| **`.task`** | `todo.json`、`active/`、`completed/` 下 `task.md` 等 | 任务闭环、已交付步骤 | +| **知识库主题（语义）** | 见下「主题索源」 | 与 index/manifest 已登记能力对齐，避免漏写「库里已有语义」的阶段 | + +### 主题索源（知识库语义，主 agent 步骤 0 须读；子 agent 步骤 1 须读） + +1. **`Read(".Knowledge/manifest-routing.json")`**：提取 `topicPaths`、`taskToTopicRules`（及与范围相关的 `topicDependencies`）。 +2. **`Read(".Knowledge/index.md")`**：至少「**主题一览**」表（主题 id、适用场景、关联文档摘要）。 +3. **按需 `Read` `.Knowledge/topics/.md`**：与范围或 manifest 命中相关的摘要（**禁止**为枚举遍历整个 `topics/`；仅读 manifest/index 已点名的主题，通常 ≤ 全表行数）。 +4. 将主题语义归纳为「能力/场景节点」列表，供子 agent 写入契约；里程碑阶段须能覆盖或于「待确认」说明与某主题相关的缺口。 + +> **索源内容仅用于采集与验证，禁止写入生成文档**；生成文档不含「索源」行、topic 路径或 manifest 内部名称。 + +## 入参（仅一个，可选） + +命令名之后可跟**一段语义化范围**（自然语言）： + +| 用户意图 | 示例 | 落盘文件名 | +| --- | --- | --- | +| 整个项目（默认） | 不传 / `整个项目` / `全项目` | `项目里程碑.md` | +| 某一需求或能力 | `回调改造` / `登录模块` | `<简述>里程碑.md` | + +**文件名规则**：后缀 `里程碑.md`；整个项目 → 前缀 `项目`；单一需求 → 语义或 req 标题简述（≤ 20 字）。 + +**范围收窄**：在四源上按关键词、路径、日期过滤；未传范围则四源全量可追溯（主题索源读 index 全表 + manifest，topics 按需展开）。 + +## 步骤 0：前置（主 agent） + +1. **`Read("flow2spec.config.json")`**（不采纳其 `subAgent` / `switchAgentVerification` 编排本技能） +2. **`Read(".Knowledge/template/项目里程碑模版.md")`** +3. **主题索源**（见上：manifest → index 主题一览 → 按需 topics 摘要） +4. 解析范围 → 确定默认路径 **`stock-docs/<范围名>里程碑.md`**。 +5. **相似文件检查（落盘前必做）**：列出 `.Knowledge/stock-docs/` 下已有 `*里程碑*.md`（含 `*里程碑.md`）。若存在与本次**目标路径相同**或**语义相近**的文件（例如同为「整个项目」的 `项目里程碑.md` 与另一份全项目里程碑、或前缀/范围关键词高度重叠），**须先询问用户**，**禁止**静默覆盖或擅自另存： + - **覆盖**：沿用原路径，子 agent 写入时覆盖该文件（验证后仍以该路径为终稿）。 + - **另生成一份**：改用新路径（建议：范围简述 + `_YYYYMMDD` + `里程碑.md`，或用户指定的 `<简述>里程碑.md`），并在契约中更新 `outputPath`。 + - 无相似文件，或仅有一个且与目标路径完全一致且用户本轮已明确要「重新生成/覆盖」→ 可不再追问，按默认路径继续。 +6. 向用户复述：范围、**最终** `outputPath`、已读主题数量；若做了相似文件询问，待用户选择后再继续。 +7. 组装「采集契约」（含最终 `outputPath`、主题节点列表）并 **派子 agent** 执行步骤 1–2 + +## 步骤 1：采集索源（子 agent） + +- 按契约完成 **四源** 采集；git **须** 对照 tag 与主版本/semver 跃迁（以本仓库 `git tag` / `package.json` 为准）。 +- 主题语义：核对 manifest/index 中能力与 git/req/task 是否同窗出现；暂无法对齐的记入内部备注供「待确认」。 + +索源为空：仍生成文档，「待确认」说明缺口；**禁止**训练数据填交付。 + +## 步骤 2：套模版并落盘（子 agent） + +**生成原则：面向读者，不暴露内部信息。** + +1. 文首只写：标题 `# （范围名）里程碑`、范围、更新时间。**不写** 索源行、topic 路径、manifest 内部名称、commit hash、npm 发布状态、环境状态等任何内部信息。 +2. **阶段倒序**：总览表与各 `## Mx ·` 均按**最新在前**排列（MN → … → M1）；每阶段标题体现功能变更，不得用「联调 / 测试 / 验收」命名（见「阶段粒度」）。 +3. 每阶段正文：仅列**已交付的功能点**，每条一行，可验证；不写时间细节、过程说明或背景铺垫。 +4. **待确认**：只列功能/交付层面的缺口或不一致；**禁止**写内部运维/发布/环境状态。若无缺口写「无」。 +5. 不写模版顶部说明 blockquote。 +6. **`Write`** 至 `outputPath`。 + +## 步骤 3：验证（主 agent，须执行） + +子 agent 落盘后 **必须**验证：**重要节点**是否错误、遗漏或合并过度。 + +1. **重读四源要点**：git tag/commit、req/task、**index 主题一览 + 已读 topics** 与文稿对照。 +2. **对照「重要节点清单」**： + +| 类别 | 检查什么 | +| --- | --- | +| 版本 / tag | 四源中的 major tag、`package.json` 版本跃迁是否在总览或 Mx 中体现 | +| 路线/架构转折 | 四源中出现的目录重组、技术路线替换等重大变更是否单独或合并体现 | +| 功能交付 | req/git/task 中可核验的能力是否在 Mx 中有对应阶段 | +| **知识库主题** | 若存在 manifest/index：与范围相关的主题是否覆盖或列入「待确认」 | +| 任务闭环 | 若存在 `.task/`：已归档任务是否在相关 Mx 中体现 | +| 依据可追溯 | 每 Mx 交付能否在四源中找到 | +| 时间线 | 先后合理；同窗多版本是否需拆分 | +| **排序** | 总览表与各 Mx 是否均为最新在前；若不是则调整 | +| **阶段粒度** | 是否存在仅联调/测试/验收/环境而无功能交付的 Mx；若有 **删除或并入** 相邻功能阶段 | +| **内部信息** | 文档中是否含索源行、commit hash、topic 路径、npm/环境状态等内部信息；若有**删除** | + +3. 遗漏 → 补 Mx（**须为功能变更**）；错误 → 按四源修正；无法确认 → 「待确认」（**禁止**用假 Mx 代替）。 +4. 验证或修订完成后方可步骤 4。 + +## 步骤 4：回复（主 agent） + +落盘路径、阶段数、验证结论（一句）、「待确认」摘要。 + +## 禁止项 + +- 禁止用 `subAgent` / `switchAgentVerification` 跳过子生成或跳过主验证。 +- 禁止在 `stock-docs/` 已存在**相似里程碑**且用户未选择「覆盖 / 另生成一份」前派子 agent 或 `Write`。 +- 禁止第二参数改输出路径（路径由范围 + 相似文件询问结果确定）；禁止写入 `req-docs`。 +- 禁止未读四源写交付；禁止子 agent 未经验证即宣称完成。 +- 禁止遍历整个 `matchers/` 或全仓 topics 代替「manifest + index + 按需 topics」。 +- 禁止用训练数据或其它项目的里程碑结构替代**当前仓库**四源；禁止代写与本次 `outputPath` 无关的其它 `stock-docs` 文档。 +- 禁止单独设立联调 / 集成测试 / UAT / 验收 / 纯环境运维类 Mx；禁止在无四源功能交付时写「计划项」阶段。 diff --git a/.dsh/skills/f2s-doc-pdf/SKILL.md b/.dsh/skills/f2s-doc-pdf/SKILL.md new file mode 100644 index 0000000..170a320 --- /dev/null +++ b/.dsh/skills/f2s-doc-pdf/SKILL.md @@ -0,0 +1,70 @@ +--- +name: f2s-doc-pdf +description: 将 PDF 技术方案转为 Markdown 并保存到 req-docs，可补全流程说明；触发：PDF转MD、按方案实现前的 PDF +--- + +> 执行口径：技术方案文档统一落在 `.Knowledge/req-docs/`；规则能力仍由配置根 `rules/skills` 加载。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本文不复述。 +- **默认不拆子**：追问-落盘必须在主 agent 内完成（子 agent 无法向用户追问）。 +- **可选拆子**：仅当 `subAgent=true` 且 PDF 规模超阈值（**> 50 页 或 > ~5MB 文本**）时启用；子 agent 仅负责 PDF→MD 首稿并落盘 `.Knowledge/req-docs/<名>.md`，**不向用户追问、不写「流程说明」章节**；主 agent 接手后续追问与流程图补写。 +- 校验默认由落盘侧 agent 自验；本 SKILL 不绑定交叉校验。 + +# 将 PDF 技术方案文档转为 Markdown（并补全流程说明） + +用户会在本技能后附带**一个参数**：**PDF 技术方案文档的本地路径**（如 `~/Downloads/技术方案.pdf`，或 `.Knowledge/req-docs/某草稿.pdf`）。请按以下步骤执行，将 PDF 转为 Markdown 并保存到 `.Knowledge/req-docs/`，必要时引导用户补全流程说明。 + +## 步骤 1：读取 PDF 并转为 Markdown + +1. 若启用拆子（PDF > 50 页 或 > ~5MB），子 agent 仅负责 PDF→MD 首稿并落盘 `req-docs/<名>.md`，不追问、不写流程说明；主 agent 接手后续步骤。**读取**用户传入的 PDF 文件，提取其中的**文字内容**（表格、章节、列表、代码块等尽量保留结构），整理为 Markdown 格式。 +2. **保存到** `.Knowledge/req-docs/`，推荐路径：`.Knowledge/req-docs/<方案名>.md`。文件名为原 PDF 文件名去掉 `.pdf` 后加 `.md`。 +3. 若目录不存在，先创建再写入。 +4. 保存后告知用户：「已将该 PDF 转为 Markdown 并保存为 `xxx.md`。」 + +--- + +## 步骤 2：向用户提问获取流程图（可选但推荐） + +PDF 内嵌的**流程图**无法被直接解析为步骤与分支，若需按图实现代码，需用户配合提供。 + +1. 向用户说明：「文档中可能包含流程图，我无法从 PDF 中解析图中的步骤与分支。若您后续会根据技术方案实现代码（见 `implement-tech-design` 规则），建议补全流程说明： + - **方式一**：将相关流程图以**图片形式**发到本次对话中，我将解析后以文字形式写入上述 MD； + - **方式二**：直接以**文字描述**每个接口/流程的步骤（如：1. 是否登录 2. 查某表 3. 判断某字段 → 返回结果），我将原样写入上述 MD。 + 若文档无流程图或暂不提供，可回复「跳过」，我将结束本技能。」 +2. **若用户回复「跳过」或明确表示无需流程说明**：告知用户「在对话中提供上述 MD 路径并说明按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」并结束。 +3. **若用户提供流程图（图片或文字）**：进入步骤 3。 + +--- + +## 步骤 3：将流程说明写入该 MD + +1. 若用户提供的是**图片**：解析图片中的步骤、判断分支与返回，整理为文字步骤。 +2. 若用户提供的是**文字**：直接采用。 +3. 在该 MD 文件末尾（或新增「流程说明」章节）**追加**流程内容，格式示例： + +```markdown +## 流程说明（由用户提供 / 由流程图解析） + +### 示例接口 A +1. 前端发起请求 +2. 后端：查询某表最后一条记录 +3. 判断：是否有某 ID？是 → 返回 true，否 → 返回 false +4. 返回结果 + +### 示例接口 B +1. 是否登录 → 否 返回 401 +2. 是否过期 → 是 返回 403 +… +``` + +1. 保存后告知用户：「流程说明已写入 `xxx.md`。接下来请在对话中提供该 MD 路径并说明要按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」 + +--- + +## 约束与小结 + +- **路径**：用户传入的 PDF 路径可为绝对路径或相对项目根。输出 MD 建议保存在 `.Knowledge/req-docs/<方案名>.md`（`req-docs` 放实现文档，`stock-docs` 放知识沉淀源文档）。 +- **本技能仅负责**：PDF → Markdown 转换 + 可选流程说明补全；不执行代码实现。完成后可提示用户：在对话中提供生成的 MD 路径并说明按技术方案实现，AI 将按 **f2s-implement-tech-design.mdc** 执行。 + diff --git a/.dsh/skills/f2s-git-commit/SKILL.md b/.dsh/skills/f2s-git-commit/SKILL.md new file mode 100644 index 0000000..286d389 --- /dev/null +++ b/.dsh/skills/f2s-git-commit/SKILL.md @@ -0,0 +1,251 @@ +--- +name: f2s-git-commit +description: 代码写完后提交 Git：默认检查变更与知识库覆盖；用户明确要求“快捷提交”时跳过知识库覆盖检查；**改动全为纯文档 / 知识库自身**或**近 30 分钟内已跑过 kb-sync/kb-feat/kb-fix** 时自动跳过覆盖检查；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、快捷提交、git commit、帮我提交 +--- + +> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。用户明确要求“快捷提交”时，仅跳过步骤 2 知识库覆盖检查，其余安全步骤照常执行。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`。 +- 本技能全程在主 agent 完成（**pull 的确认**不可下放子 agent；`git commit` 不要求单独一轮用户确认，见步骤 3–4）。 + +# f2s-git-commit（提交代码） + +## 强制流程 + +### 快捷提交模式 + +当用户本轮明确说出 **“快捷提交”**、**“快速提交”** 或 **“quick commit”** 时，进入快捷提交模式： + +- 跳过 **步骤 2：知识库覆盖检查**，不读取 `.Knowledge/topics/` / `.Knowledge/stock-docs/` 做覆盖判断。 +- 不提示用户先运行 `f2s-kb-sync` / `f2s-kb-feat`。 +- **不跳过**步骤 1 的变更读取与冲突标记检查。 +- **不跳过**步骤 3 的提交信息生成与展示。 +- **不跳过**步骤 4 的精确 `git add <文件列表>`、正常 `git commit` 与 git hooks。 +- **不得**因快捷提交使用 `git add -A` / `git add .` / `--no-verify` / 自动 push。 + +### 步骤 1：读取变更（只读） + +```bash +git status --short +git diff HEAD +``` + +- 从 `git status --short` 区分三类文件： + - **Staged**：已 `git add`，前缀为 `M `、`A `、`D `（首列非空） + - **Unstaged**：已追踪但未 add，前缀为 ` M`、` D`（次列非空） + - **Untracked**：`??` 前缀，新文件尚未追踪 +- 若三类均为空（nothing to commit），直接告知用户并结束。 + +**冲突检查（必须，先于一切）**： + +扫描所有变更文件内容，若任意文件包含 `<<<<<<<`、`=======`、`>>>>>>>` 冲突标记，立即终止并提示： + +``` +❌ 检测到未解决的 merge conflict： + - <文件路径> + +请先解决冲突后再提交。 +``` + +### 步骤 2：知识库覆盖检查（默认必须；三种情况可跳过） + +若处于**快捷提交模式**，本步骤直接跳过，并在步骤 5 收尾提示中说明“已按快捷提交跳过知识库覆盖检查”。 + +**先判断 `.Knowledge/` 是否存在：** + +- 若 `.Knowledge/manifest-routing.json` 不存在：跳过本步骤，在步骤 5 收尾提示「项目尚未初始化 Flow2Spec 知识库，建议运行 flow2spec init」，继续步骤 3。 + +**跳过判定 A：改动纯文档 / 知识库自身**（进入覆盖检查前先判定） + +若步骤 1 收集到的 pending 文件路径**全部**命中以下模式,直接跳过本步骤（在步骤 5 说明「本次改动纯文档,已跳过覆盖检查」）： + +- `.Knowledge/**`（改的就是知识库自己,检自己无意义） +- `docs/**` / `docs/en/**` +- `README*.md` / `LICENSE` / `CHANGELOG*` +- `.claude/**` / `.cursor/**` / `.codex/**`（agent 配置根,由 flow2spec init 分发,与业务能力覆盖无关） +- `presentations/**` / `assets/**` / 其他纯静态资源 + +**任一**文件落在 `src/` / `lib/` / `cli.js` / `templates/` / 业务代码目录时,本捷径**不生效**,继续走覆盖检查。 + +**跳过判定 B：近期已同步过知识库** + +读取 `.Knowledge/.last-sync.json`（若不存在直接跳过本判定）： + +```json +{ + "syncedAt": "2026-08-04T10:30:00.000Z", + "skill": "f2s-kb-sync", + "developerId": "<可选>" +} +``` + +- 若 `Date.now() - Date.parse(syncedAt) < 30 * 60 * 1000`（30 分钟内）→ 直接跳过本步骤,在步骤 5 说明「近 30 分钟内已跑过 ,已跳过覆盖检查」。 +- 若时间戳过期或文件损坏 → 忽略,正常走覆盖检查。 +- 该文件由 `f2s-kb-sync` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-add` / `f2s-kb-addRules` / `f2s-kb-distill` 等**知识库写入类技能**在成功完成后写入,`f2s-git-commit` **只读**不写。 +- 用户显式说「重新检查一次覆盖」/「不要跳过覆盖检查」→ 本判定失效,强制走覆盖检查。 + +**存在时执行覆盖检查：** + +**先执行 KB 自动合并预检（必须，不让用户手动跑命令）：** + +1. Agent 在本步骤内部执行 `flow2spec kb check --json` 与 `flow2spec kb status --json`，或使用等价的内置 KB 引擎能力；不得把这些命令变成用户要手动执行的提交前置工作。 +2. 若 `check` 返回知识库结构错误、matcher 缺失、routing drift 等健康问题：终止本次 commit，报告具体问题与建议修复动作；不要把损坏的知识库一起提交。 +3. 若 `status.tasks` 中存在当前 developer 任务根下的 `kb-delta.json`： + - 能唯一定位当前任务线且 `mergeable=true`：自动执行 `plan → apply → build → check`（CLI 或等价内置能力均可），并把被写入的 `.Knowledge/**` 文件纳入本次提交文件列表。 + - `mergeable=false`、delta 解析失败，或存在多个 active delta 且无法判断哪个属于本次提交：停止自动写入，列出 `topic / reason / deltaPath`，提示用户需要语义合并或选择任务线；不得猜测合并。 +4. 若没有当前任务线的 active `kb-delta.json`，才进入下面的粗粒度覆盖判断。 + +**没有可自动应用的 delta 时，执行粗粒度覆盖检查：** + +1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（以仓库内目录/包名为准，勿臆测未出现的业务名）。 +2. 读取 `.Knowledge/topics/` 目录列表与 `.Knowledge/stock-docs/` 目录列表。 +3. 对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。 +4. 得出结论：**已覆盖 / 部分覆盖 / 未覆盖**。 + +> 判断粗粒度即可：有对应 topic 或 stock-docs 文档即视为已覆盖；若知识库为空或找不到相关文档则视为未覆盖。 + +**未覆盖或部分覆盖时（必须提示）：** + +``` +⚠️ 本次变更涉及以下能力尚未入知识库： + - <能力描述> + +建议在提交前同步知识库，可选： + A) 现在运行 f2s-kb-sync 补录，完成后自动继续提交流程 + B) 先提交，稍后手动补录（输入 B 确认） + C) 取消本次提交（输入 C） +``` + +- 选 **A**：提示用户运行 `f2s-kb-sync` 或 `f2s-kb-feat` 补录；用户补录完成后在**同一会话声明已补录**或**再次触发本技能**时，从步骤 1 或步骤 3 继续（**不要求**为「继续 commit」单独打字确认，与步骤 3–4 一致）。 +- 选 **B**：记录未覆盖能力描述，在步骤 5 收尾提示中输出。 +- 选 **C**：终止本技能。 + +### 步骤 3：生成提交信息草稿（必须） + +读取 `git diff HEAD`（内容过长时取前 300 行），基于实际变更内容生成提交信息。 + +#### 首行格式（必须）：类型图标 + Conventional Commits + +**首行**须同时满足： + +1. **以一个 emoji 开头**（与下表 `type` 对应，**禁止**用多个装饰 emoji 堆叠）。 +2. 紧跟 **一个 ASCII 空格**，再写 **小写 `type`**、英文冒号 `:`、**一个空格**、**中文或英文简述**。 +3. **可选 scope**：使用 Conventional 的 `type(scope):`，紧跟在 `type` 之后、冒号之前，例如 `🐛 fix(auth): 修复登录态丢失`。 +4. 首行总长度建议 **≤ 72 个字符**（含 emoji；过宽时优先缩短描述）。 + +**推荐模板（单行）**： + +```text + [(scope)]: <简述> +``` + +无 scope 时省略括号段，例如：`🚀 feat: 简述`。 + +**`type` → 首字符 emoji（固定选用下表，便于检索与发布说明）**： + +| `type` | emoji | 典型场景 | +|--------|--------|----------| +| `feat` | 🚀 | 新功能、对用户可见的能力增量 | +| `fix` | 🐛 | 缺陷修复、线上/测试问题 | +| `docs` | 📚 | 仅文档、注释、README、知识库正文类 | +| `style` | 💄 | 纯格式、缩进、分号等不改变行为的排版 | +| `refactor` | ♻️ | 重构、改名、无行为变化的结构调整 | +| `perf` | ⚡ | 性能优化 | +| `test` | 🧪 | 测试用例、测试桩、快照 | +| `build` | 🏗️ | 打包、依赖、编译脚本、artifact | +| `ci` | 👷 | CI 配置、流水线、自动化脚本 | +| `chore` | 🔧 | 杂项、工具脚本、非 build/ci 的维护性改动 | +| `revert` | ↩️ | 回滚某次提交 | + +**示例**： + +```text +🚀 feat: 支持xxx活动缓存预热 +🐛 fix(coupon): 领券窗口边界条件错误 +📚 docs: 补充公共模块 QConfig 说明 +♻️ refactor: 提取拼团校验为独立函数 +🔧 chore: 升级 ESLint 配置 +``` + +**正文（可选）**：第二行起可为列表或段落，**不要求**每行再加 emoji；若需条目，用 `- ` 即可。 + +**用户已给出首行时**：若已含上表之一且 emoji 与 `type` 一致，**尊重用户文案**；若仅有 `type:` 无 emoji，**须补全 emoji** 再进入步骤 4。 + +**与 `git commit` 的确认策略（必须）**： + +- 在**同一条 assistant 回复**中：**先**展示拟提交说明的**首行**（及可选正文），**随后立即**执行步骤 4（`git add` 逐项 + `git commit`）。**不要求**用户再回复「确认」才允许 commit。 +- 若用户在该轮对话中**已先写明**提交说明且合规，可直接使用并进入步骤 4，仍须在执行前**复述首行**再 commit。 +- 用户若明确表示「改提交说明 / 换一个 type」：改稿后仍在本策略下**展示即提交**，不增加「请回复确认」门槛。 + +### 步骤 4：执行提交（展示说明后立即执行） + +根据步骤 1 的三类文件分别处理： + +```bash +# 1. Unstaged 文件：需先 add +git add + +# 2. Untracked 文件：需先 add +git add + +# 3. Staged 文件：已 add，无需重复操作 + +# 执行提交 +git commit -m "<步骤 3 定稿的完整提交信息>" +``` + +- 禁止使用 `git add -A` / `git add .`，仅 add 步骤 1 中明确列出的文件。 +- 若 pre-commit hook 失败：输出完整错误信息，提示用户修复后重新触发本技能，**不**使用 `--no-verify` 绕过。 +- 若 commit 成功：读取 commit hash（`git rev-parse --short HEAD`）并进入步骤 5。 + +### 步骤 5：收尾提示 + +``` +✅ commit 完成 + <提交信息首行> + +[若步骤 2 选了 B] +📌 提醒：以下能力仍未入知识库，建议在合并前补录： + - <能力描述> + 可运行：f2s-kb-sync 或 f2s-kb-feat + +[若跳过了步骤 2（.Knowledge 不存在）] +💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init + +[若快捷提交跳过了步骤 2] +⚡ 已按快捷提交跳过知识库覆盖检查。 + +[若命中跳过判定 A：改动纯文档] +📄 本次改动纯文档 / 知识库自身,已跳过覆盖检查。 + +[若命中跳过判定 B：近 30 分钟内已同步] +🔄 近 30 分钟内已跑过 ,已跳过覆盖检查（.Knowledge/.last-sync.json）。 +``` + +## 约束 + +- 禁止使用 `git add -A` / `git add .`，只 add 已确认的变更文件。 +- 禁止 `--no-verify`，hook 失败须修复后重试。 +- 禁止 `--amend` 已推送的 commit，除非用户明确要求。 +- 禁止自动 push，commit 完成后停止。 +- 默认模式下知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）；快捷提交模式下跳过知识库覆盖检查，不提示补录选项。 +- **`git pull` / `git pull --rebase` / 会改写当前分支工作区内容的 `git fetch` 后续合并操作**：**必须**先向用户说明目的与风险，**取得用户对「拉取」的明确确认**（如用户回复「确认 pull」）后再执行；**禁止**为 commit 而顺带静默 pull。 +- **`git commit`**：**不要求**用户单独回复「确认」；但**禁止完全不展示**拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。 +- 提交信息**首行**须符合步骤 3 的 **emoji + type** 格式（用户已合规给出时可保留）。 +- 存在 merge conflict 标记时必须终止，不得继续。 + +## 完成后自检 + +1. 步骤 1 是否检查了 merge conflict（必须为是）。 +2. 是否区分了 staged / unstaged / untracked 三类文件（必须为是）。 +3. 是否用了 `git add -A` / `git add .`（必须为否）。 +4. 知识库检查是否执行或有明确跳过理由（快捷提交 / `.Knowledge` 不存在）（必须为是）；若存在 active `kb-delta.json`，是否已自动 plan/apply/build/check 或明确报告冲突（必须为是）。 +5. 步骤 3 是否基于 `git diff` 实际内容生成提交信息（必须为是，而非仅 `--stat`）。 +6. 执行 commit 前是否在当条回复中**展示了拟提交首行**（必须为是）；**不得**要求用户单独「确认 commit」才执行（与策略一致）。 +7. 提交信息**首行**是否为 ` [(scope)]: <简述>` 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。 +8. 若 pre-commit 失败，是否跳过了 hook（必须为否）。 +9. 若步骤 2 选 B，收尾提示是否包含未补录提醒。 +10. 若步骤 2 选 A，是否在用户补录或再次触发后继续流程（**不要求**为继续 commit 单独要确认）。 +11. 若本流程中曾需要 `git pull`：是否在执行前取得用户对 **pull** 的明确确认（必须为是）；未涉及 pull 则标 N/A。 diff --git a/.dsh/skills/f2s-kb-add/SKILL.md b/.dsh/skills/f2s-kb-add/SKILL.md new file mode 100644 index 0000000..eb323a4 --- /dev/null +++ b/.dsh/skills/f2s-kb-add/SKILL.md @@ -0,0 +1,132 @@ +--- +name: f2s-kb-add +description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-kb-add、已有能力进知识库、多文件生成上下文 +--- + +> 执行口径：本技能只维护 `.Knowledge`，不改配置根 `rules/skills`。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。 +- 默认不拆子：主会话全流程完成；低于阈值时拆子收益低于 context 切换成本。 +- 拆子阈值（仅当 `subAgent=true` 且任一满足）：① 输入路径 ≥ 5；② 单源文件 > ~3000 行；③ 多路径总量 > ~10000 行。 +- **拆子策略（仅在达到拆子阈值且 `subAgent=true` 时启用）**： + - **B 模式（默认，单轮并行）**：主先产出「inventory（待解析源文档路径清单 + 核心能力名，主手写，禁止子 agent 自行增删）」+「扫描契约（每个源读哪些章节 / 行号范围、禁扫目录、统一产出字段与表头）」→ 子 agent 并行只读按表填写 → 主一轮合并 + 去重 → 写 `.Knowledge/stock-docs/<方案名>_初稿.md` → 主做用户确认与验收。适合源边界较清晰、中等规模、希望尽快出一版。 + - **C 模式（大仓 / 高风险，多轮纠偏）**：在 B 之前或替代 B 首轮 —— 主先做 inventory → 子并行交表 → 主专做一轮**对表**（标重合 / 矛盾 / 缺依赖 / 跨源边界）→ 必要时对矛盾点补派小任务或主自读关键点 → 最后主写 / 改定稿。适合多 workspace / monorepo、目录极深、源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合或矛盾严重的场景。 + - **切换判据**（任一成立即切到 C）：多 workspace / monorepo；目录极深或源路径 > 20 条；首轮子表矛盾 / 空洞明显；多源叙述重合 / 矛盾严重。 +- **子交付硬约束**：子 agent 不得自行裁剪源路径范围，必须按主手写 inventory 执行；交付按「子交付 YAML schema」（字段：`source` / `scope` / `capabilities` / `cross_refs` / `pending`），禁止散文式回传；子不得写 `manifest-routing.json` / `.Knowledge/index.md`；子不得单独宣布「已进知识库」。 +- 主必控：重合判定、终稿定稿、`f2s-kb-build` 调度、整体验收。 +- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。 +- 落盘侧自验。 + +# f2s-kb-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步 + +## 使用时机 + +- 某能力已在代码中落地，但信息分散在多个文件，需沉淀为可检索知识。 +- 与 `f2s-doc-arch` 区分：`doc-arch` 产出架构初稿；`doc-add` 产出“已落地能力”知识沉淀链路。 + +## 输入 + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| 文件路径列表 | 是 | 一个或多个路径（空格/换行/`@`）；支持源码、配置、文档 | +| 方案名 | 否 | 用于生成 `<方案名>_初稿.md`、`<方案名>_终稿.md` | +| 初稿/终稿路径 | 否 | 默认放 `.Knowledge/stock-docs/` | + +无有效路径时中止并要求用户补充。 + +## 步骤 0：重合判定（重要） + +执行前先对照： + +- `.Knowledge/index.md` +- `.Knowledge/topics/*.md` +- `.Knowledge/stock-docs/*.md` + +若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。 + +## 步骤 0.5：多模块检测（输入路径 ≥ 2 时必须执行） + +1. **目录聚合**：按路径中的功能层目录（如 `src/<模块名>/`、顶层目录名）对文件分组。 +2. **判定规则**（满足任一即判定为「多模块」）： + - 文件分属 ≥ 2 个不同顶层功能目录（如 `auth/`、`payment/`）； + - 用户在输入中明确提及「多个功能 / 不同模块 / 分别处理」等； + - 文件名前缀明显不同且无共同父目录。 +3. **单模块（未触发判定）**：不中断，继续步骤 1，按现有单输出逻辑生成 `<方案名>_初稿.md`。 +4. **多模块（触发判定）**：**暂停**，向用户展示分组结果，并询问： + - **方案 A（推荐）**：按模块分别生成知识文件 → 每组独立走步骤 1→2→3→4，各自产出 `<模块名>_初稿.md` / `<模块名>_终稿.md`； + - **方案 B（合并）**：忽略模块边界，合并生成一份 `<方案名>_初稿.md`（原有行为）。 + - **禁止**在未获用户明确选择前默认走方案 B 继续执行。 +5. **单模块但 stock-doc 体量大**：若单份输入文档或聚合后的源码超过 **300–500 行**，或涵盖 **3 个以上不相干职责域**，建议向用户提示"可拆成多份 focused stock-doc，各自对应独立 topic"；用户确认继续则不阻断，但在输出摘要中记录"建议后续拆分"。 + +## 步骤 1：适度深度解析 + +- 小文件通读； +- 大文件优先结构与关键片段（导出、接口、配置、流程）； +- 不确定内容显式标注”待确认”，禁止编造。 +- 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。** + +## 步骤 2：生成初稿 + +- 默认输出：`.Knowledge/stock-docs/<方案名>_初稿.md` +- 初稿建议结构： + - 概述 + - 来源清单（含不可读文件） + - 分模块归纳 + - 交叉关系 + - 待确认项 + +## 步骤 3：生成终稿 + +- 参考 `.Knowledge/template/终稿模版.md` +- 输出：`.Knowledge/stock-docs/<方案名>_终稿.md` +- **必须填写 `## 来源文件` 小节**，列出步骤 1 实际读取的原始源文件路径 +- 若用户要求”先审初稿”，则停在初稿并等待确认 + +## 步骤 4：同步知识路由 + +基于终稿调用 `f2s-kb-build` 口径，更新： + +- `.Knowledge/topics/` +- `.Knowledge/index.md` +- 路由清单（必要时） +- `manifest-routing.json.topicMetadata`（按需）：仅给已存在或本次确认创建的 topicId 写入 `primary` / `tags` / `confidence`；`tags` 可省略，且不得与 `primary` 重复。分类只用于治理、审计和阅读预期，不参与路由或执行强制性；证据不足时不写 metadata，并在摘要列为待确认；不得为了分类单独创建、重命名或拆分 topic。 + +> **创作侧准则**：本步骤会触发新增 / 修改 topic 与 `topicDependencies`，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再调用 `f2s-kb-build` 口径同步。 + +## 输出摘要（必须） + +1. 初稿/终稿路径 +2. 更新的 topic/index/路由清单 路径 +3. 未完成项与原因（如路径无效、信息不足） + +## 复杂场景示例 + +用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。 + +- 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。 +- 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。 +- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-kb-build` 同步。 + +用户输入 3 个文件：`src/auth/login.ts`、`src/payment/checkout.ts`、`src/notification/email.ts`。 + +- 步骤 0.5 检测到文件分属 `auth/`、`payment/`、`notification/` 三个不同顶层功能目录，判定为「多模块」。 +- 向用户展示分组：`auth` 组 1 个文件、`payment` 组 1 个文件、`notification` 组 1 个文件；询问方案 A（分别生成）或方案 B（合并）。 +- 用户选方案 A：按 `auth`、`payment`、`notification` 三组各走步骤 1→2→3→4，分别产出 `auth_初稿.md`、`payment_初稿.md`、`notification_初稿.md`。 +- **禁止**在用户选择前直接合并三个模块生成 `综合_初稿.md`。 + +## 约束 + +- 终稿 `sourceDoc` 仅指向 `.Knowledge/stock-docs/*` +- 不改配置根 `rules/skills` +- 同主题优先更新，不平行新建重复知识 +- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束），子 agent 不得触碰 + +## 完成后自检 + +1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。 +2. 同主题是否避免重复新建。 +3. topic/index/manifest 是否与终稿语义一致。 +4. 若写入 `topicMetadata`：是否只覆盖已存在或本次已创建的 topicId；`primary` / `tags` / `confidence` 是否合法；是否避免类型前缀命名与重命名。 +5. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。 diff --git a/.dsh/skills/f2s-kb-addRules/SKILL.md b/.dsh/skills/f2s-kb-addRules/SKILL.md new file mode 100644 index 0000000..93bc55f --- /dev/null +++ b/.dsh/skills/f2s-kb-addRules/SKILL.md @@ -0,0 +1,168 @@ +--- +name: f2s-kb-addRules +description: 把用户口述的规则沉淀进知识库，自动判定「新建主题 / 并入存量主题」并同步路由；不写代码、不创建 .task/；触发：f2s-kb-addRules、新增规则、口述规则、把这条记到知识库 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`（口述规则属于元配置变更，不是业务变更追踪）。 + +# f2s-kb-addRules：用户口述规则进知识库 + +## 与既有技能的边界 + +- 与 `f2s-kb-feat` 区分：`f2s-kb-feat` 强绑「代码实现 + KB 同步」，命中 `changeTracking.feat` 会创建 `.task/`；本技能**只沉淀规则**，不改代码、不追踪任务。 +- 与 `f2s-kb-build` 区分：`f2s-kb-build` 输入是 `.Knowledge/stock-docs/_终稿.md`；本技能输入是**用户当场口述的规则文本**。 +- 与 `f2s-kb-add` 区分：`f2s-kb-add` 输入是「多文件源码 / 配置」聚合到 stock-docs；本技能跳过 stock-docs，直接落 topic。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源（**Cursor/Claude** 读 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`）。本 SKILL 不复述。 +- 默认主 agent 全流程执行——口述规则单条短文，拆子收益低于 context 切换成本。 +- **写权硬约束**：`.Knowledge/manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘。 +- 落盘侧自验。 + +## 输入 + +- 一条或一段用户口述的规则文本（自由文本即可，无固定格式）。 +- 用户**不需要**指定目标主题、文件名、`alwaysApply` 等参数；由本技能判定与提议。 + +## 强制前置：Read 创作侧准则 + +执行任何步骤前，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），后续命名 / 骨架 / 依赖判定 / DAG 最小化 / 写盘权属均以该条为准。 + +## 步骤 1：意图归一 + +把用户口述文本归一为可落盘的"规则单元"： + +- 抽取**约束句式**（"做 X 时必须 / 禁止 / 优先 Y"）或**流程描述**（"X 的处理顺序是 A→B→C"）； +- 标识规则**适用场景**（触发条件、文件路径范围、生命周期阶段等）； +- 不替用户引申、不补未说的边界——口述什么写什么，模糊处保留并在步骤 3 询问。 + +## 步骤 2：扫存量主题（必须） + +- Read `.Knowledge/manifest-routing.json` 取 `topicPaths` 全集； +- Read `.Knowledge/index.md` 主题表，按主题 id + 一句话意图扫一遍； +- 必要时按规则正文中的**关键词**逐个 Read 候选 `topics/.md` 头部 10–30 行（不要全文加载所有 topic）； +- 输出**候选清单**（重合度高 → 低，至多 3 个）作为步骤 3 的输入。 + +## 步骤 3：新建 vs 并入判定（必须，与用户确认） + +向用户**展示候选**，按下列分支提议： + +- **高重合**（口述规则明显是某存量主题的细化 / 补充 / 例外）→ 提议「**并入** `topics/.md`」，并指出拟插入位置（章节名 / 段落锚点）。 +- **无重合 / 低重合**（找不到合适宿主）→ 提议「**新建** `topics/<新 id>.md`」；新 id 由本技能按规则正文生成 **kebab-case**，遵循 `f2s-topic-authoring` 命名约束（无版本后缀、无个人花名、与 `index.md` 既有标题不冲突）。 +- **跨多个主题**（一条口述同时约束 ≥2 个主题）→ **暂停**，向用户呈现拆分选项： + - 选项 A：拆为 ≥2 条规则单元，分别并入对应主题； + - 选项 B：选主归并到一个主题，其它主题以一行交叉引用提示； + - 选项 C：新建一个**总纲性**主题统辖，旧主题加引用——仅在该规则确实横切多个领域时使用。 + +> 用户未确认前**禁止**落盘 `topics/` / `manifest-routing.json` / `index.md`。 + +## 步骤 4：落盘（用户确认后执行） + +### 4a. 写 `topics/.md` + +- **新建**：按 `f2s-topic-authoring` 第 2 节"topic 正文骨架"五点逐项写入（标题与一句话意图 / 适用场景 / 核心规则 / 依赖声明 / 边界与禁止项）； +- **并入**：在用户确认的章节 / 段落处**手术式插入**——只增加与本次规则直接相关的句段，禁止整文件重写或借机重述背景； +- 行文遵守 `f2s-flow2spec-unified-entry`「知识库落盘文风」**肯定式优先**；排他性选择例外。 + +### 4b. `topicDependencies` 判定（必须） + +按 `f2s-topic-authoring` 第 4 节四问 + 反向排除 + DAG 最小化，扫新写正文中**反引号引用的其他 topic id / 规则文件名**，逐个判定是否声明依赖： + +- 命中 → 在 `manifest-routing.topicDependencies` 增加边，**且**在新 / 改 topic 正文显式写一句「执行前须先读依赖主题 ``」； +- 未命中 → 不写依赖，靠 `taskToTopicRules` 次高候选 + `expand` 补召回。 + +并入存量主题时，若仅是细化既有规则、未引入对新 topic 的强引用，**通常不需要**新增依赖边。 + +### 4c. 同步路由（仅主 agent 落盘） + +- **新建主题**： + - 补 `manifest-routing.topicPaths`：` -> .Knowledge/topics/.md`； + - 按需补 `manifest-routing.topicMetadata`：口述规则主题通常为 `{ "primary": "policy", "confidence": "inferred" }`；用户明确确认分类可写 `manual`；如同时包含配置项 / 模块 / 能力性质，可写入不与 `primary` 重复的 `tags`；证据不足则不写 metadata，并在摘要列为待确认。分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性； + - 视情况补 `taskToTopicRules[]`——**仅当**该规则会作为**用户任务路由命中**（参见 `f2s-topic-authoring` 第 5 节判据）才补；纯被其它规则 / SKILL 引用的内部规则**不进** `taskToTopicRules`； + - 若补了 `taskToTopicRules[]`，须新建 `.Knowledge/matchers/.json`，从用户口述中抽取 `includeAny` 关键词（用户原话 + 1–2 个明显近义说法，宁缺勿滥）； +- **并入存量主题**： + - `topicPaths` 不变； + - 可按需补齐该 topic 的 `topicMetadata`，但不得为了分类创建、重命名或拆分 topic； + - 仅当口述规则**新增了触发场景**时，最小更新对应 `matchers/.json` 的 `includeAny`；否则不动 matcher。 + +### 4d. 更新 `index.md` + +- 新建主题：在主题表新增一行（同主题单行原则）；「关联文档（摘要）」列填「无」或「待补充」（口述规则通常无 stock-docs / req-docs 锚定文档），禁止留空； +- 并入存量主题：仅在主题意图发生变化时更新该行的「主题意图」摘要列，否则不动。 + +## 步骤 5：输出摘要（必须） + +```markdown +## 规则捕获结果 + +### 口述规则 +> <用户原文，1–3 行> + +### 落盘决策 +- 模式：新建 / 并入 / 跨主题拆分 +- 目标：.Knowledge/topics/.md（章节：<可选>） + +### 知识库变更 +- .Knowledge/topics/.md：<新增 / 修订说明> +- .Knowledge/manifest-routing.json： +- .Knowledge/matchers/.json：<是否更新 includeAny 与原因> +- .Knowledge/index.md：<是否更新与原因> + +### 待用户后续 +- <如无 taskToTopicRules，提示"该规则当前不会被任务路由命中，需要时可补"；其它跟进项一并列出> +``` + +## 约束 + +- 不写代码、不动配置根 `rules/skills`、不创建 `.task/`。 +- 用户未确认「新建 / 并入 / 跨主题拆分」前禁止落盘。 +- 同主题优先并入，避免新建近似主题（参见 `f2s-topic-authoring` 命名"不要"项）。 +- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）。 +- 路由清单仅做最小改动，不重写无关字段。 +- 行文遵守统一入口「知识库落盘文风」与单文件篇幅软约束（口述规则通常 ≤ 30 行新增正文足矣）。 + +## 复杂场景示例 + +**场景 A：高重合并入** + +用户口述：「写 commit message 时，第一行必须中文 emoji 开头」。 +扫描发现已存在 `topics/f2s-git-commit.md`（描述 git commit 流程）。 +- 步骤 3 提议：**并入** `topics/f2s-git-commit.md` 的「commit 文风」章节； +- 步骤 4a 在该章节追加规则段，不改其他章节； +- 步骤 4b 不新增依赖； +- 步骤 4c manifest 不动，仅在该 topic 对应 matcher（若存在）中补 1–2 个关键词； +- 步骤 4d index 不动。 + +**场景 B：新建主题** + +用户口述：「所有面向用户的错误提示必须以动词开头，如『重试』『检查 X』而非『错误：X 失败』」。 +扫描未找到合适宿主。 +- 步骤 3 提议：**新建** `topics/error-message-style.md`； +- 步骤 4a 按骨架写入； +- 步骤 4b 评估是否依赖 i18n / 文案规范类既有 topic，命中则声明； +- 步骤 4c 判断「用户日常对话中是否会触发"错误提示文案"任务路由」——若会，补 `taskToTopicRules` + 新建 matcher；若仅作为内部规范被其它 SKILL 引用，则**不进** `taskToTopicRules`； +- 步骤 4d index 新增一行。 + +**场景 C：跨主题拆分** + +用户口述：「按方案实现时不能边写边改文档；提交 PR 时必须先跑测试」。 +明显涉及 `f2s-implement-tech-design`（实现纪律）和 `f2s-git-commit`（提交流程）两个主题。 +- 步骤 3 暂停，呈现 A / B / C 三选项； +- 用户选 A → 拆为两条规则单元，分别并入两个主题； +- 步骤 4 在两个 topic 中分别落盘，输出摘要列出两条变更。 + +## 完成后自检 + +1. 是否在落盘前 Read 了 `rules/f2s-topic-authoring.*` 全文。 +2. 是否在用户未确认「新建 / 并入 / 跨主题拆分」前提前落盘（必须为否）。 +3. 新建 topic：`topicPaths` 是否补全；正文是否含五点骨架；`taskToTopicRules` 与 matcher 的 `includeAny` 是否符合「rule 是否需建对应 topic 路由」判据。 +4. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类改 topicId / 文件名。 +5. 并入 topic：是否仅做手术式插入；是否未借机改写无关章节。 +6. `topicDependencies` 是否经四问判定；是否引入冗余传递边或环。 +7. `index.md` 与 `topics/` 文件集合是否一一对应；新建主题是否补「关联文档（摘要）」列。 +8. 是否未触碰配置根 `rules/skills`；是否未创建 `.task/`。 +9. 输出摘要是否齐全（口述原文 / 决策 / 变更 / 待跟进）。 diff --git a/.dsh/skills/f2s-kb-build/SKILL.md b/.dsh/skills/f2s-kb-build/SKILL.md new file mode 100644 index 0000000..bda9c7b --- /dev/null +++ b/.dsh/skills/f2s-kb-build/SKILL.md @@ -0,0 +1,113 @@ +--- +name: f2s-kb-build +description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-kb-build、终稿生成上下文 +--- + +> 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。 + +# 根据文档生成项目上下文（topics/index/路由清单） + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本 SKILL 不复述。 +- **首选分支（小变更 → 主全流程）**：当本次改动 **≤ 2 个新 / 改主题**，**且 ≤ 1 个新 matcher**，**且无跨主题批量引用调整** 时，全流程在主 agent 完成，不拆子。 +- **中大变更分支**（`subAgent=true` 且超出上述阈值）： + - 主 agent 在主会话中列出**文件级契约**：子 A 只写 `.Knowledge/topics/.md`，子 B 只写 `.Knowledge/matchers/.json`，路径互不重叠； + - 子 agent 仅落盘契约内文件，不跨边界； + - **主 agent 单点**编辑 `.Knowledge/manifest-routing.json` / `.Knowledge/index.md`（补 `taskToTopicRules`、`topicPaths`、`matcherPath`、`topicDependencies`、`topicMetadata`）； + - 主 agent 做整体验收。 +- **不推荐**：单个子 agent 同时改 manifest / index / 多份 topics / matchers；以及「子 A 写、子 B 验」。 +- **「一子写、主验」**：仅在交付边界极窄（例如只产出 1 个新 matcher 分片草稿，manifest 引用仍由主写）时可接受。 +- **写权硬约束**：`.Knowledge/manifest-routing.json`（含 `topicMetadata`）/ `.Knowledge/index.md` **恒由主 agent 落盘**，子 agent 不得触碰。 +- 默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。 + +## 输入 + +- 接收一个参数：URL 或本地路径。 +- 本地路径必须位于 `.Knowledge/stock-docs/`。 +- **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。 +- 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。 +- 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。 + +## 生成原则 + +1. **拆解**：文档较长或包含多块独立能力时，拆分为多个 topic；避免把无关能力塞到同一主题。 +2. **分工**： + - `topics/`：规则与流程正文（可执行知识） + - `index.md`：主题索引与语义说明（人读入口） + - `manifest-routing.json` + `taskToTopicRules[].matcherPath` 指向的 `matchers/*.json`：任务路由与关键词词表（机读入口） + +## 步骤 1：获取文档内容 + +- URL：抓取正文；无法访问时提示用户先落地到 `.Knowledge/stock-docs/*.md`。 +- 本地路径：读取 Markdown 文档，提炼主题与能力边界。 + +## 步骤 2：语义分析（必须） + +从文档中提炼： + +- 主题名与主题意图（可形成 topic id） +- 核心概念与关键流程 +- 业务规则与边界条件 +- 任务触发词（写入对应 `matchers/.json` 的 `includeAny`） +- 与现有主题的依赖关系（用于 `topicDependencies`） + +> **创作侧准则**：本步骤涉及新增 / 修改 topic 与 `topicDependencies`，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再继续步骤 3 / 步骤 5。命名、骨架、依赖判定、DAG 最小化、判定时机均以该条为准，本 SKILL 不复述。 + +> **拆分评估**：若输入 stock-doc 超过 **300–500 行**，或语义分析后发现覆盖 **3 个以上不相干职责域**，须在输出摘要中说明：建议拆成多份 focused stock-doc（各自对应一个独立 topic），用户确认后再分批执行；若用户选择继续生成单个大 topic，不阻断，但在摘要中记录"主题偏大，建议后续拆分"。大功能主 topic 写业务闭环/入口/子模块 stock-doc 导航链接；子模块 topic 各自独立命中，**不通过 `topicDependencies` 串联概述与详情**。 + +## 步骤 3：写入 topics + +- 目标路径：`.Knowledge/topics/.md` +- 若已存在同主题：优先增量更新，避免重复主题。 +- 若为新主题：新增文件并补充清晰标题、适用场景、规则与流程。 + +## 步骤 4：更新 index + +- 更新 `.Knowledge/index.md` 的主题路由表。 +- 保证“同主题单行”。 +- 主题路由表需维护“关联文档（摘要）”列：每个主题补充 1-3 条关键文档**可点击 Markdown 链接**（格式：`[标题](相对路径)`，优先 `stock-docs/req-docs`）。 +- 若某主题暂无可公开文档，写“无”或“待补充”，禁止留空导致歧义。 +- 若新增/删除主题，索引同步调整，避免孤儿路径。 + +## 步骤 5：更新路由清单（按需） + +- 本步骤由主 agent 落盘（写权硬约束），子 agent 不得执行。 +- 更新 `manifest-routing.topicPaths`（topicId -> topic 文件路径） +- 更新 `manifest-routing.taskToTopicRules[]`（任务到主题集合 + matcherId） +- 更新 `manifest-routing.topicDependencies`（先读依赖后读主主题） +- 更新 `manifest-routing.topicMetadata`（按需）：仅给已存在或本次确认创建的 topicId 写入 `{ "primary": "feature|module|config|policy", "tags": ["..."], "confidence": "manual|inferred" }`；`tags` 可省略，且不得与 `primary` 重复。分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性。新建 topic 时有明确证据可写 `inferred`；用户确认后才写 `manual`；证据不足时不写 metadata，并在摘要列为待确认。不得为了分类创建、重命名或拆分 topic。 +- 更新 `matchers/.json` 的 `includeAny`（关键词词表；路径须与 `taskToTopicRules[].matcherPath` 一致） +- 校验 `fallbackTopic`、`topicPaths`、`matcherId` 引用有效 +- 仅做最小改动，不重写无关字段 + +## 路径与引用约束 + +- `sourceDoc` 或文档引用统一指向 `.Knowledge/stock-docs/<文件名>.md` +- 禁止把 `.Knowledge/req-docs/` 作为 topic 的 `sourceDoc` +- 禁止改写配置根 `rules/skills` + +## 输出摘要（必须） + +- 新增/更新的 topic 文件 +- `index` 更新项 +- 路由清单更新项（如有） +- 失败或跳过项及原因 + +## 复杂场景示例 + +用户输入：`f2s-kb-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。 + +- 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。 +- 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。 +- 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。 + +## 完成后自检 + +1. `.Knowledge/topics/*.md` 与 `manifest-routing.topicPaths` 一一对应。 +2. `index.md` 主题表与 topics 文件集合一致，且每个主题都包含“关联文档（摘要）”。 +3. 每个 `taskToTopicRules[].matcherPath` 文件存在且其中 `id` 与 `matcherId` 一致。 +4. 若写入 `topicMetadata`：key 是否均存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；`tags` 是否未与 `primary` 重复；是否未因分类改 topicId / 文件名。 +5. 未触碰配置根 `rules/skills`。 +6. 中大变更时是否按文件级契约拆子（子 A / 子 B 路径互不重叠）。 +7. `manifest-routing.json` / `.Knowledge/index.md` 由主 agent 单点落盘，无子 agent 越权写入。 diff --git a/.dsh/skills/f2s-kb-distill/SKILL.md b/.dsh/skills/f2s-kb-distill/SKILL.md new file mode 100644 index 0000000..c2f923b --- /dev/null +++ b/.dsh/skills/f2s-kb-distill/SKILL.md @@ -0,0 +1,387 @@ +--- +name: f2s-kb-distill +description: 从问答过程中提取可复用知识事实并自动入库；根据下钻深度与命中主题判断新增主题或补充既有主题；触发：f2s-kb-distill、问答知识提取、从对话中提取知识 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> 执行口径：本技能只维护 `.Knowledge`，默认不改配置根 `rules/skills`。 + +## KB 自动合并协议（必须） + +本技能不得把“人工执行命令”作为用户流程。用户触发本技能后，由 agent 自己完成知识候选生成、合并、构建与校验： + +1. 若本轮存在可沉淀知识，先在当前任务上下文中形成 `kb-delta` 草稿，记录 `taskId`、`developerId`、`baseRevisions`、`changes` 与证据摘要；没有显式任务目录时可在内存中形成等价对象，不强制为了本技能创建 `.task`。`changes` 可使用 `appendBody` / `replaceBody` / `updateFrontmatter`；确需新主题时使用 `createTopic`，并可携带 `taskRule` 与 `matcher` 让路由一并接入。 +2. 写入 `.Knowledge` 前，必须用 `flow2spec kb plan ` 或等价内部能力预演；若 topic revision 不一致，停止自动写入，转入语义合并说明。 +3. 可自动合并时，由 agent 调用 `flow2spec kb apply ` 或等价内部能力写入 topic，并随后执行 `flow2spec kb build` 与 `flow2spec kb check`。 +4. 用户只看到“知识库已同步 / 有语义冲突需确认 / 已跳过入库及原因”，不要求用户手动执行 `kb plan/apply/build/check`。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。 +- 本技能默认不拆子：问答知识提取是单轮聚焦任务，由主 agent 全流程完成效率更高。 +- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 单点落盘。 +- 校验：落盘侧自验。 + +# f2s-kb-distill：问答驱动的知识提取与入库 + +## 使用时机 + +- 用户提问 → agent 下钻源码回答 → 需要将发现的知识沉淀到 KB +- 通常由 `f2s-kb-feedback-closing` 规则自动建议，也可用户主动调用 +- 与 `f2s-kb-sync` 区分：`sync` 适合批量同步多个能力；`distill` 专注单次问答的知识提取 + +## 输入 + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| 用户问题 | 自动获取 | 上一轮用户的提问（自动从对话历史提取） | +| agent 回答 | 自动获取 | 上一轮 agent 的回答内容（自动从对话历史提取） | +| 命中主题 | 可选 | 如由 `f2s-kb-feedback-closing` 触发，会携带命中的 topicId | +| 下钻文件 | 自动分析 | 从回答中提取引用的文件/函数（自动分析） | + +无有效问答上下文时中止并提示用户。 + +## 执行挡位（轻量 / 严格，agent 自动判） + +`f2s-kb-distill` 只有**一个**入口（无 `--fast` 参数），进入流程第一件事是**判挡**： + +### 判挡依据（4 个维度，全满足才走轻量挡） + +| 维度 | 取值方式 | 走「轻量挡」的条件 | +| --- | --- | --- | +| 上游 `f2s-kb-feedback-closing` case | 看本轮 / 上一轮 agent 回答末尾的收口块 | **case 2 或 case 3**（case 1 / 无收口 → 严格挡） | +| 本轮 Read 业务源码文件数 | agent 回顾本轮自己的工具调用 | **≤ 3 个** | +| 本轮回答引用的函数 / 类名数 | 数回答里反引号包裹的 `xxx()` / 类名 | **≤ 5 个** | +| 用户追问是否否定上游结论 | 看用户最新输入是否含"不对 / 重新分析 / 那条不准"等 | **否** | + +**4 项全满足** → **轻量挡**：跳过步骤 2.1（量化打分）/ 2.4（既有 topic 描述程度评估）/ 步骤 3（决策矩阵）/ 步骤 4.1 的「读近邻 topic 风格对齐」；直接采上游「本轮将入库：<概要>」做策略与目标 topicId 判定，进入步骤 4 生成内容。 + +**任一不满足** → **严格挡**：跑完整 6 步。 + +> **业务源码定义**：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数；规则文件 / topic / config / 任务清单都不算。 + +### 为什么这几个维度够（设计意图） + +- **case 类型**挡掉「新增 topic」场景：新建必须读近邻 topic 学风格、必须配 matcher `includeAny`、必须更新 `taskToTopicRules`，跳不得； +- **Read 文件数 + 函数引用数**反映本轮知识够不够"轻"：轻量补充才能跳决策，深度入库（多文件 + 多函数）跳了会撞「描述程度差 ≥ 2 级」事故； +- **用户否定信号**兜底"上游 case 判错了"的边界。 + +### 步骤 5 / 6 永不省 + +无论哪一挡，**步骤 5 路由 / matcher / index 同步**与**步骤 6 落盘 + 自检**都跑完整版——这是入库正确性的硬约束。 + +## 强制流程（不可颠倒） + +### 步骤 0：读取配置与规则 + +1. 读取 `flow2spec.config.json`（获取 `subAgent` / `switchAgentVerification`） +2. 读取 `.codex/topics/f2s-kb-feedback-closing.md`（获取"可复用知识事实"定义） +3. 读取 `.codex/topics/f2s-topic-authoring.md`（获取 topic 创作准则） + +### 步骤 1：提取问答上下文 + +从上一轮对话中提取： + +1. **用户问题**：原始问题文本 +2. **agent 回答**：完整回答内容 +3. **命中主题**：如果 `f2s-kb-feedback-closing` 已分析，提取命中的 topicId；否则根据问题重新路由 +4. **下钻文件**：从回答中提取所有引用的文件路径、函数名、行号 +5. **引用源码**：提取回答中引用的代码片段 + +### 步骤 2：分析下钻深度与知识性质 + +> ****轻量挡**跳过**：本步骤的 2.1 / 2.4 整段跳过；2.2（提取知识事实）必须执行；2.3（本次知识描述深度）改为**简短标注**（一行写"摘要级 / 详细级 / 实现级"即可，不再多维评估）。 + +#### 2.1 计算下钻深度得分 + +累加以下指标（每项 0-10 分，总分 0-50）： + +- **读取文件数**： + - 0 个文件：0 分 + - 1-2 个文件：3 分 + - 3-5 个文件：7 分 + - 6+ 个文件：10 分 + +- **分段读取次数**（同一文件多次读取不同行范围）： + - 0-1 次：0 分 + - 2-4 次：3 分 + - 5-8 次：7 分 + - 9+ 次：10 分 + +- **函数/类引用数**： + - 0-2 个：0 分 + - 3-5 个：3 分 + - 6-10 个：7 分 + - 11+ 个：10 分 + +- **代码片段长度**： + - 0-50 行：0 分 + - 51-150 行：3 分 + - 151-300 行：7 分 + - 301+ 行：10 分 + +- **回答篇幅**： + - 0-200 字：0 分 + - 201-500 字：3 分 + - 501-1000 字：7 分 + - 1001+ 字：10 分 + +**下钻深度分级**： +- **浅**（0-15 分）：简单问答，少量源码引用 +- **中**（16-30 分）：中等复杂度，多文件查阅 +- **深**（31-50 分）：深度探索，大量源码分析 + +#### 2.2 提取可复用知识事实 + +从回答中提取以下类型的知识（参考 `f2s-kb-feedback-closing`）： + +- 核心机制（缓存语义、重试策略、降级逻辑） +- 状态流转（状态机、生命周期） +- 返回值/错误码契约 +- 配置开关影响 +- 失败回退策略 +- 模块边界或调用约定 +- 数据模型与字段语义 + +**提取结果**： +- 每条知识事实包含：类型、描述、来源（文件:行号） +- 按重要性排序 + +#### 2.3 判断本次提取知识的描述深度 + +评估提取出的知识事实的详细程度（与长度无关，看内容特征）： + +- **摘要级**：只有结论性描述（"是什么"、"做什么"），无条件、流程、函数细节 + - 示例：`缓存优先、失败回退 OCR` +- **详细级**：包含机制说明、流程步骤、关键判断条件（"当X时"、"如果Y则"、"先...再..."） + - 示例：`缓存优先：坐标缓存命中时直接使用；失败回退条件：弹窗未消失、坐标超出边界` +- **实现级**：包含函数调用关系、状态转换细节、边界条件处理、代码示例 + - 示例：`缓存读取：调用 _get_cached_point_in_bounds("chat.input")，返回 None 时回退；失败判定：VisualSearchPopup.find(timeout=0.08) is None` + +#### 2.4 评估既有 topic 的描述程度（仅当"有命中"时） + +如果命中了既有 topic，需要评估它的描述程度（与长度无关）： + +1. **读取目标 topic 内容** +2. **随机抽取 3-5 条内容**（不同段落） +3. **判断每条的描述程度**： + - **摘要级特征**：只说"是什么"、"做什么"，列举式，无条件/流程/函数细节 + - **详细级特征**：包含"当X时"、"如果Y则"、"先...再..."、判断条件、机制说明 + - **实现级特征**：包含函数名 `xxx()`、类名、文件路径、参数、代码示例、状态转换逻辑 +4. **大部分条目的级别 = topic 的整体描述程度** + +**判断示例**： + +| Topic 内容 | 判定 | 原因 | +|-----------|------|------| +| `- 缓存优先、失败回退 OCR`
`- 发送消息动作链判定` | 摘要级 | 只说"做什么"，无细节 | +| `- 缓存优先：坐标缓存命中时直接使用`
`- 失败回退：弹窗未消失时清除缓存并重新 OCR` | 详细级 | 有条件说明（"当...时"） | +| `- 缓存读取：_get_cached_point_in_bounds("chat.input")`
`- 失败判定：VisualSearchPopup.find(timeout=0.08) is None` | 实现级 | 有函数名、参数 | + +**重要**：一个 300+ 行的 topic，如果每条都是"模块 X：负责 YYY"，仍然是摘要级；一个 50 行的 topic，如果每条都有"条件判断 + 函数调用"，就是实现级。 + +### 步骤 3：决策入库策略 + +> ****轻量挡**跳过整段决策矩阵**：直接采用上游 `f2s-kb-feedback-closing`「本轮将入库：<概要>」给出的结论： +> - 概要含「补充 / 补到 / 补齐 `` 的某段」→ 策略 = **补充既有 topic**，目标 topicId = 概要点名的 topic； +> - 概要含「首次入库」「新增 `<能力>`」「新增 `<模块>`」→ 策略 = **新增 topic**（默认小型 topic；下钻深 + 模块独立时升级为「新增独立模块 topic」由步骤 4.3 内部判断）； +> - 概要含「修正 `` 的某条」→ 策略 = **补充既有 topic**（覆盖式追加，原表述在生成内容时改写）。 + +根据以下决策矩阵判断： + +| 下钻深度 | 命中主题情况 | 既有 topic 描述程度 | 本次知识描述深度 | 策略 | +|---------|------------|------------------|----------------|------| +| 浅 | 有命中 | 摘要级 | 摘要级 | **补充既有 topic**（追加简短说明） | +| 浅 | 有命中 | 摘要级/详细级 | 详细级 | **补充既有 topic**（追加详细段落） | +| 浅 | 有命中 | 摘要级 | 实现级 | **新增子主题**（既有太简短，本次太详细） | +| 浅 | 无命中 | - | 任意 | **新增 topic**（小型 topic） | +| 中 | 有命中 | 摘要级 | 摘要级/详细级 | **补充既有 topic**（追加详细段落） | +| 中 | 有命中 | 摘要级 | 实现级 | **新增子主题**（差距 ≥ 2 级） | +| 中 | 有命中 | 详细级/实现级 | 详细级/实现级 | **补充既有 topic**（级别匹配） | +| 中 | 无命中 | - | 任意 | **新增 topic**（中型 topic） | +| 深 | 有命中 | 摘要级 | 任意 | **新增子主题**（独立 topic + stock-doc） | +| 深 | 有命中 | 详细级/实现级 | 详细级/实现级 | **补充既有 topic** 或 **新增子主题**（根据语义聚焦度判断） | +| 深 | 无命中 | - | 任意 | **新增独立模块 topic**（完整 topic + stock-doc） | + +**决策关键**： +- **描述程度差距 ≥ 2 级**（摘要 vs 实现）→ 强制新增子主题，避免风格不协调 +- **描述程度差距 = 1 级**（摘要 vs 详细，或详细 vs 实现）→ 可以追加，但要写详细段落 +- **描述程度匹配**（同级）→ 正常追加 +- **下钻深度 ≥ 深** → 倾向新增子主题，除非既有 topic 已经很详细且语义完全重合 + +**决策输出**： +- 策略类型：`补充既有 topic` / `新增子主题` / `新增独立模块 topic` +- 目标 topicId：既有 topic 的 id 或新 topic 的建议 id +- 更新内容：要追加的内容或新 topic 的结构 +- 描述程度匹配度：同级 / 差 1 级 / 差 ≥ 2 级 + +### 步骤 4：生成知识内容 + +> **创作侧准则**：本步骤会触发新增 / 修改 topic 与可能的 `topicDependencies`，须遵循已读取的 `f2s-topic-authoring` 准则。 + +#### 4.1 补充既有 topic + +如果策略是"补充既有 topic"： + +1. 读取目标 topic 当前内容 +2. 读取近邻 2-3 个 topic 的风格样例（用于风格对齐） + ****轻量挡**跳过**：不读近邻 topic，仅参考目标 topic 自身的列表 / 段落形态保持一致即可。 +3. 生成要追加的内容： + - **位置**：找到最相关的段落，在其后追加 + - **格式**：保持与既有 topic 一致的列表/段落风格 + - **长度**：根据知识描述深度决定： + - 摘要级：1-3 行 + - 详细级：5-10 行，包含机制说明 + - 实现级：10-20 行，包含流程步骤与关键函数 +4. 追加内容示例： + ```markdown + - 【机制】缓存只用于坐标定位与快速路径；缓存命中不等同于步骤完成 + - 【判定】添加好友在缓存点击后仍通过窗口出现、资料页状态、提交后状态分类判断进度 + - 【边界】发送消息在按 Enter 后返回成功，当前无 OCR 校验消息气泡或发送状态 + ``` + +#### 4.2 新增子主题 + +如果策略是"新增子主题"： + +1. 生成新 topicId（基于父 topic + 聚焦点）： + - 例如：`wxautocontrol-architecture` → `wxautocontrol-completion-detection` +2. 创建新 topic 内容： + - 标题与一句话意图 + - 适用场景/触发词 + - 核心机制详述（从提取的知识事实生成） + - 依赖声明（依赖父 topic） + - 边界与禁止项 +3. 同步更新父 topic： + - 在相关段落追加指向子 topic 的链接 + - 说明子 topic 的聚焦点 +4. 更新 `topicDependencies`： + - 添加 `子 topic → 父 topic` 的依赖边 + +#### 4.3 新增独立模块 topic + +如果策略是"新增独立模块 topic"： + +1. 生成新 topicId（基于模块名或问题域） +2. 判断是否需要创建 stock-doc： + - 下钻深度 ≥ 深：创建 stock-doc（`_终稿.md`） + - 下钻深度 < 深：仅创建 topic，不创建 stock-doc +3. 如果创建 stock-doc： + - 结构：概述、核心机制、来源文件、关键函数与流程 + - 内容：基于提取的知识事实与引用的代码片段生成 + - 长度：根据下钻深度，100-500 行 +4. 创建 topic： + - 如有 stock-doc，topic 作为摘要 + 指针 + - 如无 stock-doc，topic 包含完整的机制说明 + +### 步骤 5：同步路由与索引 + +#### 5.1 更新 manifest 与 matcher + +- 如果新增 topic： + - 在 `manifest-routing.json.topicPaths` 中添加条目 + - 创建对应的 `matchers/.json`，包含： + - 从用户问题中提取的关键词 + - 从回答中提取的术语 + - 建议 `includeAny`：5-10 个触发词 + - 在 `taskToTopicRules` 中添加路由规则 + +- 如果更新既有 topic： + - 检查 matcher 是否需要补充新的触发词 + - 从用户问题中提取未覆盖的关键词，追加到 `includeAny` + +#### 5.2 更新 index.md + +- 如果新增 topic： + - 在 `.Knowledge/index.md` 中添加新条目 + - 格式：`- **[topic 标题](topics/.md)** - 一句话说明 | 关联文档：[终稿](stock-docs/.md)`（如有） +- 如果更新既有 topic： + - 检查 index 中的描述是否需要更新 + - 如果新增了 stock-doc，更新"关联文档"列 + +#### 5.3 处理 topicMetadata（可选） + +如果有明确证据，写入 `topicMetadata`： + +- 从提取的知识事实判断 `primary` 类型： + - 核心机制/状态流转/失败回退 → `policy` + - 配置开关影响 → `config` + - 模块边界/调用约定 → `module` + - 已落地能力/业务逻辑 → `feature` +- `confidence` 设为 `inferred` +- 无明确证据时不写，在输出摘要中列为"未分类" + +### 步骤 6：落盘与自检 + +按以下顺序落盘： + +1. 如果有 stock-doc：写入 `.Knowledge/stock-docs/.md` +2. 写入或更新 `.Knowledge/topics/.md` +3. 更新 `.Knowledge/manifest-routing.json` +4. 更新 `.Knowledge/matchers/.json` +5. 更新 `.Knowledge/index.md` + +自检清单： + +1. topic 内容是否包含了提取的核心知识事实 +2. 新增 topic 是否在 index.md 中有对应条目 +3. manifest 中的 topicPaths / taskToTopicRules 是否引用有效路径 +4. matcher 的 includeAny 是否覆盖用户问题的关键词 +5. 如果新增子主题，topicDependencies 是否正确设置 +6. 追加内容是否保持了既有 topic 的风格（如已读近邻 topic） + +## 输出摘要格式 + +```markdown +## 知识提取与入库结果 + +- 执行挡位：`严格挡（完整流程）` / `轻量挡（已跳过 2.1 / 2.4 / 3 / 4.1）` / `轻量挡 → 严格挡（降级原因：<原因>）` + +### 问答分析 +- 用户问题：<问题摘要> +- 命中主题： +- 下钻深度：<浅/中/深> (<得分>) ← **轻量挡**：`未评估` +- 知识描述深度：<摘要级/详细级/实现级> + +### 提取的知识事实 +- 【核心机制】<描述> (来源：<文件:行号>) +- 【状态流转】<描述> (来源：<文件:行号>) +- ... + +### 入库策略 +- 策略：<补充既有 topic / 新增子主题 / 新增独立模块 topic> +- 目标 topic： +- 操作说明：<追加内容 / 新建 topic + stock-doc> + +### 已修改文件 +- .Knowledge/topics/.md：<修改说明> +- .Knowledge/index.md：<修改说明或"未改动"> +- .Knowledge/manifest-routing.json：<修改说明或"未改动"> +- .Knowledge/matchers/.json：<修改说明或"未改动"> +- .Knowledge/stock-docs/.md：<修改说明或"未改动"> + +### 验证建议 +- 下次遇到类似问题"<问题>"时，应命中 topic： +- 建议验证触发词：<关键词列表> +``` + +## 约束 + +- 只维护 `.Knowledge`，不改配置根 `rules/skills` +- 不需要用户确认（问答已验证知识的正确性） +- 保持轻量，单次问答的知识提取在 30 秒内完成 +- 避免过度拆分：除非下钻深度 ≥ 深且知识描述深度 ≥ 详细级，否则优先补充既有 topic +- 生成的 matcher includeAny 应覆盖用户实际会用的表述，不只是技术术语 + +## 完成后自检 + +1. 是否正确分析了下钻深度与知识描述深度（**轻量挡**：是否正确从上游概要解析出策略与目标 topicId） +2. 是否提取了所有"可复用知识事实"（参考 `f2s-kb-feedback-closing` 定义） +3. 入库策略是否符合决策矩阵（**轻量挡**：是否与上游概要点名的 case 一致） +4. 新增或更新的 topic 是否在 index.md 中有条目 +5. manifest / matcher 是否正确配置路由规则 +6. 生成内容是否保持了既有 topic 的风格（**轻量挡**：是否至少与目标 topic 自身列表/段落形态对齐） +7. **轻量挡专项**：摘要顶部是否写明「调用模式」；若中途降级，是否注明降级原因 +8. 本次回复末尾**没有**追加 `f2s-kb-feedback-closing` 的 case 1～4 任何一种收口块（必须为是；本技能就是 distill 入库本身，自指地再贴一遍提示既冗余又会让用户误以为没入库——`f2s-kb-feedback-closing`「适用范围」对此有专项禁令） diff --git a/.dsh/skills/f2s-kb-feat/SKILL.md b/.dsh/skills/f2s-kb-feat/SKILL.md new file mode 100644 index 0000000..b7c5560 --- /dev/null +++ b/.dsh/skills/f2s-kb-feat/SKILL.md @@ -0,0 +1,115 @@ +--- +name: f2s-kb-feat +description: 新增能力时补全实现与知识库；已实现则仅同步知识库；触发：f2s-kb-feat、新增能力 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> 执行口径：`f2s-kb-feat` 默认同步 `.Knowledge`，无需用户额外提出"请同步知识库"。 + +## KB 自动合并协议（必须） + +本技能不得把“人工执行命令”作为用户流程。代码实现完成或确认已有实现后，由 agent 自己完成知识候选生成、合并、构建与校验： + +1. 将本次能力变更转换为 `kb-delta` 草稿，记录 `taskId`、`developerId`、`baseRevisions`、`changes` 与实现证据；若 `changeTracking.feat=true` 且已有任务目录，可把 delta 落在当前 `TASK_ROOT/active//kb-delta.json`，否则可在内存中形成等价对象。`changes` 可使用 `appendBody` / `replaceBody` / `updateFrontmatter`；确需新主题时使用 `createTopic`，并可携带 `taskRule` 与 `matcher` 让路由一并接入。 +2. 写入 `.Knowledge` 前，必须用 `flow2spec kb plan ` 或等价内部能力预演；若 topic revision 不一致，停止自动写入，转入语义合并说明。 +3. 可自动合并时，由 agent 调用 `flow2spec kb apply ` 或等价内部能力写入 topic，并随后执行 `flow2spec kb build` 与 `flow2spec kb check`。 +4. 用户只看到“能力与知识库已同步 / 有语义冲突需确认 / 已跳过入库及原因”，不要求用户手动执行 `kb plan/apply/build/check`。 + +## 编排（主 / 子 agent） + +- `subAgent` 与 `switchAgentVerification` 的语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。 +- **代码子包**（新增 / 修改实现代码）：`subAgent=true` 时可外包给子 agent 执行。 +- **文档子包**（rules / skills / topics / stock-docs 文风类改动）：默认不拆，由主 agent 写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。 +- 若确需外包文档改动：子侧只输出「原位替换 diff」（before / after 小段），不得整文件重写；主合并落盘。 +- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。 +- 落盘侧自验。 + +# /新增能力（f2s-kb-feat） + +## 输入 + +- 用户描述新增能力、场景、边界、可选路径。 + +## 步骤 + +**步骤 0：变更追踪（仅当 `changeTracking.feat: true`）** + +执行前读取 `flow2spec.config.json`，若 `changeTracking.feat: true`： + +- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。 +- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。 +- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。 +- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止把打钩积压到「收尾/归档」一步、禁止口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。 +- **用户代办**：凡须用户改库、配环境、点平台等项，**同会话内**追加写入 `.task/active//user-todos.md`（见 `f2s-task`）；新建任务时若尚无代办，仍应创建该文件（可占位）。 + +1. 判断能力状态：未实现 / 部分实现 / 已实现。 +2. 补齐代码实现（已实现则跳过此步）。 +3. 同步知识库（默认执行）： + - `.Knowledge/stock-docs/`：能力说明与使用方式 + - `.Knowledge/topics/`：新增/修订主题规则与流程 + - `.Knowledge/index.md`：主题索引 + - 路由清单：路由、依赖或 `topicMetadata` 变化时最小更新 + - **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 +4. 输出摘要（能力点、实现、知识库变更）。 + +## 输出摘要格式（建议） + +```markdown +## 新增能力：<能力名> + +### 能力范围 +- <能力点1> +- <能力点2> + +### 实现 +- <文件路径>：<改动说明>（若未改代码则写"已有实现"） + +### 知识库 +- .Knowledge/stock-docs/<文件>.md：<新增/修订说明> +- .Knowledge/topics/.md：<新增/修订说明> +- .Knowledge/index.md：<更新说明> +- .Knowledge/manifest-routing.json：<是否更新与原因> +- .Knowledge/matchers/.json：<是否更新 includeAny 与原因> +``` + +## 复杂场景示例 + +用户要求"新增失败重试队列能力"，且代码中已有半成品实现。 + +- 先判断为"部分实现"，补齐缺口代码而非重做整模块。 +- 同步新增或修订 `topics/retry-queue.md`，并更新 `index` 入口说明。 +- 若该能力需任务路由命中（如"重试队列改造"），补充 `manifest.taskToTopicRules`。 + +## 约束 + +- 与旧约定冲突时：**改写到当前真值**，不要另起「（不再与某 X 有关）」等历史否定句。 +- 与现有主题重合时优先原位更新。 +- 至少落一处知识库更新，避免"代码有了但不可检索"。 +- 不改配置根 `rules/skills`。 +- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。 + +## 知识库落盘文风（必须，防赘述） + +写 `stock-docs` / `topics` / `index` 时遵守： + +1. **增量最小**：只追加或改写与**本次能力**直接相关的句段；禁止因「同步知识库」而全文重述背景、需求复述、与实现无关的教程式铺垫。 +2. **肯定式优先（见统一入口「知识库落盘文风」）**：直接写出正确描述，禁止用否定旧版来传达新约定；排他性选择除外。 +3. **不重复叙事**：同一事实在 `stock-docs` 与 `topics` **不要各写一长篇**；择一处写清可执行约定，另一处用短段落 + 链接指向，或仅列要点与引用路径。 +4. **条文化优先**：`topics` 以规则、边界、步骤、错误与配置要点为主；能用列表/表格表达的不用长段落。 +5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增正文合计不宜超过约 **80 行**（不含代码块行）；超出则拆分为新 topic、或先写「摘要 + 详见代码路径/另一文档」，禁止单文件堆叠重复说明。 +6. **`index.md`**：只改与本次主题相关的行/表项，禁止整表或整节复制粘贴式刷新。 +7. **禁止**：重复解释 Flow2Spec 目录分工、重复贴用户对话全文、与本次 diff 无关的「历史回顾」大段。 + +## 完成后自检 + +1. 能力描述与代码实现是否一致。 +2. 新增能力是否可通过 topic 被检索。 +3. `index` 与 `manifest` 是否同步更新。 +4. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类创建、重命名或拆分 topic。 +5. 知识库变更是否可再压缩：删掉与本次变更无关的套话后，规则与链接是否仍完整。 +6. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：若现行规则已写清，此类句应删或并入用户要求的迁移小节。 +7. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。 +8. 若 `changeTracking.feat: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才将 `.task/active//` 归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。 +9. 若 `changeTracking.feat: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。 diff --git a/.dsh/skills/f2s-kb-fix/SKILL.md b/.dsh/skills/f2s-kb-fix/SKILL.md new file mode 100644 index 0000000..dbed698 --- /dev/null +++ b/.dsh/skills/f2s-kb-fix/SKILL.md @@ -0,0 +1,112 @@ +--- +name: f2s-kb-fix +description: 根据用户指出的实现或规则错误修正代码，并默认同步知识库；触发：f2s-kb-fix、修正实现规则 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> 执行口径：`f2s-kb-fix` 默认"修代码 + 同步 `.Knowledge`"，无需用户额外要求"请同步知识库"。 + +## KB 自动合并协议（必须） + +本技能不得把“人工执行命令”作为用户流程。修复完成后，由 agent 自己完成知识候选生成、合并、构建与校验： + +1. 将本次修复后的正确规则/实现边界转换为 `kb-delta` 草稿，记录 `taskId`、`developerId`、`baseRevisions`、`changes` 与修复证据；若 `changeTracking.fix=true` 且已有任务目录，可把 delta 落在当前 `TASK_ROOT/active//kb-delta.json`，否则可在内存中形成等价对象。`changes` 可使用 `appendBody` / `replaceBody` / `updateFrontmatter`；确需新主题时使用 `createTopic`，并可携带 `taskRule` 与 `matcher` 让路由一并接入。 +2. 写入 `.Knowledge` 前，必须用 `flow2spec kb plan ` 或等价内部能力预演；若 topic revision 不一致，停止自动写入，转入语义合并说明。 +3. 可自动合并时，由 agent 调用 `flow2spec kb apply ` 或等价内部能力写入 topic，并随后执行 `flow2spec kb build` 与 `flow2spec kb check`。 +4. 用户只看到“修复与知识库已同步 / 有语义冲突需确认 / 已跳过入库及原因”，不要求用户手动执行 `kb plan/apply/build/check`。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。 +- 代码子包（bug 修复类实现代码）：`subAgent=true` 时可外包给子 agent 执行。 +- 文档子包（rules / skills / topics / stock-docs 等文风类改动）：默认不拆，由主 agent 直接编写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。 +- 若确需外包文档改动：子侧**只输出「原位替换 diff」**（before / after 小段），**不得整文件重写**；由主 agent 合并落盘。 +- 写权硬约束：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。 +- 落盘侧自验。 + +# /修正能力（f2s-kb-fix） + +## 输入 + +- 用户描述违规点、正确写法、可选范围。 + +## 步骤 + +**步骤 0：变更追踪（仅当 `changeTracking.fix: true`）** + +执行前读取 `flow2spec.config.json`，若 `changeTracking.fix: true`： + +- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。 +- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。 +- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。 +- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止积压打钩或口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。 +- **用户代办**：凡须用户改库、配环境、回归验证等项，**同会话内**追加写入 `.task/active//user-todos.md`（见 `f2s-task`）；新建任务时若无代办可写占位说明。 + +1. 明确违规点与影响范围（不清先追问）。 +2. 修复代码实现。 +3. 同步知识库（默认执行）： + - `.Knowledge/stock-docs/`：修订约定说明 + - `.Knowledge/topics/`：修订对应主题规则/流程 + - `.Knowledge/index.md`：更新主题索引 + - 路由清单：若路由、依赖或 `topicMetadata` 受影响则最小更新 + - **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 +4. 输出摘要（代码改动 + 知识库改动）。 + +## 输出摘要格式（建议） + +```markdown +## 修正结果：<约定简述> + +### 代码 +- <文件路径>：<改动说明> + +### 知识库 +- .Knowledge/stock-docs/<文件>.md：<新增/修订说明> +- .Knowledge/topics/.md：<新增/修订说明> +- .Knowledge/index.md：<更新说明> +- .Knowledge/manifest-routing.json：<是否更新与原因> +- .Knowledge/matchers/.json：<是否更新与原因> +``` + +## 复杂场景示例 + +用户指出「某回调接口幂等实现错误」，但未给明确文件范围。 + +- 先按最小可行范围修复已定位的回调处理链路，并在摘要中说明"可继续扩展全仓同类修复"。 +- 同步更新 `topics` 中幂等规则段落，避免后续再次生成错误实现。 +- 若该修复影响任务路由（例如新增"幂等修复"主题），再最小更新 `manifest`。 + +## 约束 + +- 与旧约定冲突时：**改写到当前真值**，不要叠写「（不再与某 X 有关）」等对照旧版的赘句。 +- 同主题优先原位更新。 +- 范围不明时按最小可行范围修复并说明。 +- 不改配置根 `rules/skills`。 +- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。 + +## 知识库落盘文风（必须，防赘述） + +写 `stock-docs` / `topics` / `index` 时遵守： + +1. **增量最小**：只改与**本次修复**直接相关的段落或列表项；禁止借机重述整份方案、整段历史背景或与修复无关的说明。 +2. **肯定式优先（见统一入口「知识库落盘文风」）**：直接写出正确描述，禁止用否定旧版来传达新约定；排他性选择除外。 +3. **不重复叙事**：`stock-docs` 与 `topics` 不就同一修复各写长篇；一处写清「错因 / 正确约定 / 注意点」，另一处简短引用或链到该段。 +4. **条文化优先**：以「错误表现 → 根因 → 正确行为 / 边界」为序的短列表为主，避免散文式展开。 +5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增或替换正文合计不宜超过约 **60 行**（不含代码块行）；超出则只保留与修复相关的最小说明，其余用「见提交/见某路径」代替。 +6. **`index.md`**：仅更新受影响的索引行或摘要列，禁止无关整表重写。 +7. **禁止**：重复粘贴用户报错全文（可摘一行标识 + 链接）、重复解释 Flow2Spec 用法。 + +## 完成后自检 + +1. 代码修复是否覆盖用户点名范围。 +2. 主题文档是否与修复后的实现一致。 +3. `index` 是否指向正确主题。 +4. 若更新了 `manifest`，路由字段是否仍可解析。 +5. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类创建、重命名或拆分 topic。 +6. 知识库变更是否可再压缩：删套话后约定是否仍清晰。 +7. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：现行规则已写清则应删。 +8. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。 +9. 若 `changeTracking.fix: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。 +10. 若 `changeTracking.fix: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。 diff --git a/.dsh/skills/f2s-kb-merge/SKILL.md b/.dsh/skills/f2s-kb-merge/SKILL.md new file mode 100644 index 0000000..0cc79d5 --- /dev/null +++ b/.dsh/skills/f2s-kb-merge/SKILL.md @@ -0,0 +1,80 @@ +--- +name: f2s-kb-merge +description: 解决 Git 合并后编辑器上下文冲突；可选传入冲突文件；实现侧冲突仅罗列待用户确认；触发：合并上下文冲突、f2s-kb-merge +--- + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。 +- **子 agent 职责**（仅当 `subAgent=true`）：只做**冲突扫描 + 按类别对照表**，每条包含五字段 —— `file` / `category`（文档索引 / 总览规则 / 模块规则 / 技能 / 说明文档 / 实现类 / 依赖元数据）/ `ours_summary` / `theirs_summary` / `recommendation`（并集 / 保留某侧 / 并入必须项 / 待用户选）。 +- **子 agent 不出成品合并稿**，避免主 agent 二次重写。 +- **主 agent 职责**：按策略落盘 + 实现类决策 + 验收。 +- 默认落盘侧自验，本技能不绑定交叉校验。 + +# /合并上下文冲突（f2s-kb-merge） + +在 **rebase / merge** 后出现 `<<<<<<<` / `=======` / `>>>>>>>` 时，优先**自动合并「AI 与开发者上下文」相关文件**，保证索引、规则、技能与说明文档互相对齐；**涉及可执行实现、部署或依赖声明的冲突不擅自合并**，需**向用户展示双方差异并等待确认**后再改。 + +## 传参（可选） + +- **不传参**：在工作区内**自行检索**仍存在冲突标记的文件，再按本技能分类与策略处理（含全量扫描后的摘要）。 +- **传参**：用户可指定**一个或多个仍含冲突的文件**（随消息 @ 文件或列出路径均可）。助手**优先只处理这些文件**中的冲突；若其中含「禁止自动合并」类别，仍只罗列差异与建议，**不擅自写入**。指定文件处理完毕后，可询问用户是否需要对工作区做**补充扫描**。 + +## 适用范围（可自动合并） + +以下**类别**内的冲突，按本技能**合并策略**处理，**无需**逐行征求确认（除非两侧表述**互斥**且无法判断应以何为准）： + +| 类别 | 说明 | +| -------------------- | -------------------------------------------------------------------- | +| 文档索引 | 承载「文档 ↔ 规则 / 技能」映射的索引表文件 | +| 项目总览规则 | 规则目录中的总入口文件 | +| 模块规则 | 同套规则目录下的其余规则片段 | +| 技能 | 技能目录下的 SKILL 说明文件 | +| 上下文说明文档 | 与规则、技能配套的说明类 Markdown | +| 索引联动的纯说明文档 | 由项目约定存放、仅被索引或规则引用、**不含可执行实现语义**的说明文档 | + +## 禁止自动合并（须用户确认） + +以下冲突**不得**在未获用户明确选择前合并： + +- **应用或服务实现源码**（业务逻辑、接口实现、数据访问等） +- **会改变对外暴露行为**的配置（路由、函数注册、中间件链、运行入口等） +- **依赖与构建元数据**（依赖声明、锁文件、构建与部署脚本等） +- **集中维护外部资源清单的实现模块**：若两侧**条目集合或注册内容不同**，属运行行为差异，须用户确认保留范围（助手可建议「并集 + 去重」，**待用户同意**后再写入） + +**处理方式**：列出冲突文件、简述两侧意图，给出推荐方案，**请用户选定**后再改上述范围中的文件。 + +## 合并策略（上下文类） + +1. **删除所有** Git 冲突标记（`<<<<<<<` / `=======` / `>>>>>>>`），不得残留。 +2. **索引表** + - 同一索引行的 **Rules / Skills / 链接列**：做**并集**，路径去重、空格分隔。 + - 仅在一侧出现的**独立索引行**：合并后**保留**，避免丢失条目。 +3. **总览规则** + - 同一主题下多条 bullet：合并为**信息完整的单条或并列多条**，**不丢弃**任一侧独有的约束或引用。 +4. **长文档中的表格** + - 描述**不同维度能力**的行：**并集保留**。 + - 描述**同一主题**的重复行：合并为**一条**连贯表述，涵盖两侧要点。 +5. **rules / skills** + - 优先保留**更具体、约束更清晰**的表述；另一侧独有的**必须 / 禁止**条款**并入**，避免规则回退。 +6. **链接与路径** + - 统一为仓库内可解析的相对路径，并与总览规则中的索引入口一致。 + +## 执行步骤 + +1. **确定范围**：若用户已指定冲突文件，仅以这些文件为范围；否则全工作区检索冲突标记（或结合 IDE 冲突列表）。再按**适用范围**分类。 + - 若启用拆子，子 agent 按子交付对照表 schema（`file` / `category` / `ours_summary` / `theirs_summary` / `recommendation` 五字段）产出分类表；主 agent 接手后续落盘 / 决策 / 验收步骤。 +2. **上下文类**：按合并策略直接修改并保存。 +3. **实现类**：只输出对比摘要与建议，**不修改文件**直至用户确认。 +4. **输出摘要**（Markdown）：已解决文件 + 要点；待确认文件 + 两侧差异 + 建议。 +5. 对**已处理文件**再次确认**无**冲突标记残留；若未做全量扫描，可提示用户是否补充扫描。 + +## 与相关命令的关系 + +- **`/修正实现规则`（f2s-kb-fix）**：用户已指明问题点后的**定向修正**与文档/规则同步。 +- **本技能**：合并产生的**批量冲突**，侧重**编辑器上下文与说明文档**同**实现侧**分离处理。 + +## 何时使用 + +- merge / rebase 后，**规则 / 技能 / 索引 / 配套说明文档**出现冲突（可全量处理，也可只处理用户指定的冲突文件）。 +- 需要一次性对齐「索引 ↔ 规则 ↔ 技能 ↔ 说明文档」，且**避免误合并实现或部署相关改动**时。 diff --git a/.dsh/skills/f2s-kb-migrate/SKILL.md b/.dsh/skills/f2s-kb-migrate/SKILL.md new file mode 100644 index 0000000..72ba035 --- /dev/null +++ b/.dsh/skills/f2s-kb-migrate/SKILL.md @@ -0,0 +1,358 @@ +--- +name: f2s-kb-migrate +description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移 +--- + +> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含： +> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json` +> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs` +> +> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。 +> +> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 +- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。 +- **主必控**： + - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）； + - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加； + - **删除清单确认**与闭环收尾必主完成。 +- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。 +- 默认落盘侧自验；本 SKILL 不绑定交叉校验。 + +# f2s-kb-migrate（旧版知识库 -> 新版知识库） + +## 与 `f2s-kb-upgrade` 为何并存 + +| 技能 | 解决的问题 | +| --- | --- | +| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 | +| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 | + +- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。 +- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。 + +**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步**当前语言对应的技能内容。 + +## 本命令做什么（对外口径） + +把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。 + +必须覆盖的对象： + +1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。 +2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。 +3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。 +4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。 + +对“索引未覆盖”的对象： + +- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。 +- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。 + +迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）： + +- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。 +- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。 +- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。 +- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。 + +**用户确认的含义（重要）**： + +- **不是**询问「要不要做清理」；清理是流程的一部分。 +- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能： + - 回复「**确认清单**」按当前清单执行删除；或 + - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。 +- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。 + +## 适用场景 + +- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。 +- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。 +- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。 + +## 输入 + +- 可选输入： + - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`） + - 旧版 `index-doc.md`（或 `docs-index.md`）路径 + - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`） + - 旧版需求文档目录（如 `req-docs/`、`docs/req/`） + - 迁移范围（全部主题 / 指定主题） +- 不提供时，先在仓库中定位上述文件并向用户确认。 + +## 断点续迁状态文件（必须启用） + +- 状态文件路径：`.Knowledge/.migrate-state.json` +- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。 +- 初始化时机：用户确认“开始迁移”后立即创建。 +- 结束时机： + - 全部迁移完成且用户确认结束：删除状态文件。 + - 用户主动“停止”：保留状态文件，等待下次恢复。 +- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。 + +建议字段（最小集）： + +```json +{ + "version": "1", + "status": "running", + "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup", + "topicQueue": [], + "topicDone": [], + "bizRuleQueue": [], + "bizRuleDone": [], + "bizSkillQueue": [], + "bizSkillDone": [], + "stockQueue": [], + "stockDone": [], + "reqQueue": [], + "reqDone": [], + "pendingManual": [], + "failed": [], + "notes": [], + "updatedAt": "ISO-8601" +} +``` + +更新规则（必须执行）： + +1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。 +2. 收到“重试 ”时，先回滚该项状态，再执行重试。 +3. 收到“继续”时，优先读取状态文件，从未完成队列继续。 +4. 收到“停止”时，写入 `status=paused` 并结束本轮。 +5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。 + +## 强制流程（分阶段执行） + +### 步骤 1：读取旧版映射 + +1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。 +2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。 +3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）： + - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名） + - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)` +4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。 +5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。 +6. 生成待迁移清单并展示给用户确认： + - 主题清单（去重、排序） + - 业务规则文件清单（`bizRuleQueue`） + - 业务技能目录清单（`bizSkillQueue`） + - `stock-docs` 文件清单 + - `req-docs` 文件清单 +7. 文档分类口径（必须明确）： + - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs` + - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs` + - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移 +8. 计算“索引外候选”（`orphans`）： + - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件 + - `bizSkillQueue` 中未被索引映射覆盖的目录 + - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。 +9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。 + +### 步骤 2：逐主题迁移（结构层核心） + +对每个主题按以下顺序执行： + +1. 汇总该主题旧资料： + - 相关 `rules/*.md(c)`（业务规则） + - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件） + - 索引映射中的**业务文档**路径 + - **不得**包含 `skills/f2s-*` 下任何文件 +2. 生成或更新 `.Knowledge/topics/.md`： + - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。 + - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。 + - **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 +3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。 +4. 按需更新路由清单： + - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic` + - `.Knowledge/matchers/.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致） +5. 输出本主题迁移摘要并**暂停**，提示用户： + - 回复“继续”迁移下一个主题 + - 或回复“停止”终止本轮 + - 或回复“重试 ”重做当前主题 + +> 未收到“继续”前，不得迁移下一个主题。 +> 每完成一个主题，必须先更新状态文件再进入等待。 + +### 步骤 3：迁移 `stock-docs`（文档层） + +当步骤 2 全部完成后，执行： + +1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/`，不做平铺。 +2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 +3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 +4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。 + +> 未收到“继续”前，不得迁移下一个文件。 +> 每完成一个文件，必须先更新状态文件再进入等待。 + +### 步骤 4：迁移 `req-docs`（文档层） + +当 `stock-docs` 阶段完成后，执行： + +1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/`，不做平铺。 +2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。 +3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。 +4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。 + +> 未收到“继续”前，不得迁移下一个文件。 +> 每完成一个文件，必须先更新状态文件再进入等待。 + +### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认） + +当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。 + +#### 5.0 迁移报告（必选：写入项目 Markdown） + +1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。 +2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）： + - **「迁移对照表」**： + - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。 + - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。 + - **`req-docs`**：同上。 + - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。 +3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。 +4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。 +5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。 + +> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。 + +#### 5.1 总摘要（对话内，可与报告摘要一致） + +- 已迁移主题列表 +- 新增/更新的 `.Knowledge` 文件 +- 已迁移 `stock-docs` 文件 +- 已迁移 `req-docs` 文件 +- 未迁移或失败项 + +#### 5.2 必选清理阶段（删除清单确认，不得跳过） + +1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含： + - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则） + - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`） + - 旧版 **`docs-index.md` / `index-doc.md`** + - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。 +2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。 +3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。 +4. 收尾完成后处理状态文件： + - 本轮完整完成：删除 `.Knowledge/.migrate-state.json` + - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因 + +## 输出摘要格式（建议） + +```markdown +## 主题迁移完成： + +### 来源 +- rules: <旧路径...> +- 业务文档: <索引映射中的文档路径...> +- 映射: + +### 已写入 +- .Knowledge/topics/.md +- .Knowledge/index.md（更新 行） +- .Knowledge/manifest-routing.json（更新字段：...） +- .Knowledge/matchers/.json（更新 `includeAny` 等：...） + +### 下一步 +- 回复“继续”迁移下一个主题 +- 回复“停止”结束迁移 +``` + +```markdown +## 文档迁移完成：/ + +### 来源 +- source: <旧路径...> + +### 已写入 +- .Knowledge// + +### 下一步 +- 回复“继续”迁移下一个文件 +- 回复“停止”结束迁移 +``` + +## 约束 + +- 必须逐主题确认，不可批量跳过确认直接全量迁移。 +- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。 +- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。 +- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。** +- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。 +- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。 +- 未完成文档迁移前，禁止删除旧文档目录。 +- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。 +- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。 +- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。 +- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。 +- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。 + +## 迁移报告模板（落盘 `migration-report.md` 时建议结构） + +以下骨架可直接复制后填空；路径均为相对项目根。 + +```markdown +# 知识库迁移报告 + +- **生成时间（ISO-8601）**：<...> +- **配置根（如 `.cursor/`）**：<...> + +## 迁移对照表 + +### 主题（旧来源 → 新路径） + +| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 | +| --- | --- | --- | +| | <...> | `.Knowledge/topics/.md` | + +### stock-docs（源 → 目标） + +| 源路径 | 目标路径 | 备注 | +| --- | --- | --- | +| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 | + +### req-docs（源 → 目标） + +| 源路径 | 目标路径 | 备注 | +| --- | --- | --- | +| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 | + +## 拟删除路径清单（默认全选；与对话内清单一致） + +- [ ] `<路径>`（`rules/` 下逐文件） +- [ ] `<路径>`（业务 `skills/`，不含 `f2s-*`） +- [ ] `.cursor/docs-index.md`（或实际路径） +- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录 + +## 用户排除项（如有） + +- （无则写「无」） + +## 失败或未迁移项（如有） + +- （无则写「无」） + +## 删除执行记录 + +（仅在执行物理删除后追加：时间、已删列表、未删及原因） +``` + +## 完成后自检 + +1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。 +2. `manifest.topics[].path` 是否都存在。 +3. `index` 是否可定位到每个已迁移主题。 +4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。 +5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。 +6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。 +7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。 +8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。 +9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。 +10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。 +11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。 +12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。 +13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。 diff --git a/.dsh/skills/f2s-kb-rm/SKILL.md b/.dsh/skills/f2s-kb-rm/SKILL.md new file mode 100644 index 0000000..6981d9c --- /dev/null +++ b/.dsh/skills/f2s-kb-rm/SKILL.md @@ -0,0 +1,61 @@ +--- +name: f2s-kb-rm +description: 删除某 stock-docs 文档对应的知识主题与索引映射；触发：删除项目上下文、f2s-kb-rm +--- + +> 执行口径：仅维护 `.Knowledge`，不改配置根 `rules/skills`。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。不在此复述。 +- 默认主 agent 全流程执行（单点删除拆子收益低）。 +- 拆子阈值：仅当 `subAgent=true` 且**批量删除一次 ≥ 5 主题**时，才拆子执行删除与清引用。 +- 主必控：范围确认、`fallbackTopic` 重指。 +- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。 +- 验证：默认落盘侧自验；本 SKILL 不绑定交叉校验。 + +# 删除文档对应的项目上下文 + +## 输入 + +- 一个参数：`.Knowledge/stock-docs/<文件名>.md` 路径，或可匹配文件名片段。 + +## 执行步骤 + +1. 读取 `.Knowledge/index.md`，匹配目标文档相关主题。 +2. 删除对应 `.Knowledge/topics/.md` 文件。 +3. 从 `.Knowledge/index.md` 移除匹配项并写回。 +4. 更新路由清单： + - `.Knowledge/manifest-routing.json`：移除失效 `topicPaths`、`taskToTopicRules`、`topicDependencies`、`topicMetadata` 引用 + - 对应 `matchers/.json`：移除失效规则或 `includeAny` 词条（与已删 `task`/`matcherId` 对齐） + - 若删除了 `fallbackTopic`，必须指定新的兜底主题 + - **创作侧准则**：本步会调整 `topicDependencies`（删除被依赖主题或孤儿边），须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），核对 DAG 与最小化约束后再落盘。 + +## 输出摘要（必须） + +- 已删除的 topic 文件列表 +- `.Knowledge/index.md` 删除的条目 +- 路由清单调整的字段 +- 未执行项（若有） + +## 复杂场景示例 + +用户输入文件名片段「回调」，匹配到 2 个主题文档。 + +- 先列出两个候选并要求用户确认删除范围，避免误删。 +- 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。 +- 最终摘要中写清：删除了哪些 topic、保留了哪些 topic、为什么。 + +## 约束 + +- 匹配多义时先询问用户确认。 +- 仅删除命中主题，不影响其它主题。 +- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）；范围确认与 `fallbackTopic` 重指不可下放给子 agent。 + +## 完成后自检 + +1. 被删 topic 是否仍被 `manifest` 引用（必须为否）。 +2. `index` 是否仍存在失效主题路径（必须为否）。 +3. `topicMetadata` 是否仍引用已删除 topic（必须为否）。 +4. `fallbackTopic` 是否仍有效。 +5. 未在低于拆子阈值（< 5 主题）时强行拆子；manifest / index 由主单点落盘。 diff --git a/.dsh/skills/f2s-kb-sync/SKILL.md b/.dsh/skills/f2s-kb-sync/SKILL.md new file mode 100644 index 0000000..6d69ea2 --- /dev/null +++ b/.dsh/skills/f2s-kb-sync/SKILL.md @@ -0,0 +1,160 @@ +--- +name: f2s-kb-sync +description: 可显式给出能力或零输入推断；先输出知识库更新大纲，确认后写入 topics/index/manifest；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力 +--- + +> 执行口径：本技能只维护 `.Knowledge`，默认不改配置根 `rules/skills`。 + +## KB 自动合并协议（必须） + +本技能不得把“人工执行命令”作为用户流程。用户确认同步大纲后，由 agent 自己完成知识候选生成、合并、构建与校验： + +1. 将已确认的大纲转换为一个或多个 `kb-delta` 草稿，记录 `taskId`、`developerId`、`baseRevisions`、`changes` 与证据摘要；没有显式任务目录时可在内存中形成等价对象，不强制为了本技能创建 `.task`。`changes` 可使用 `appendBody` / `replaceBody` / `updateFrontmatter`；确需新主题时使用 `createTopic`，并可携带 `taskRule` 与 `matcher` 让路由一并接入。 +2. 写入 `.Knowledge` 前，必须用 `flow2spec kb plan ` 或等价内部能力预演；若 topic revision 不一致，停止自动写入，转入语义合并说明。 +3. 可自动合并时，由 agent 调用 `flow2spec kb apply ` 或等价内部能力写入 topic，并随后执行 `flow2spec kb build` 与 `flow2spec kb check`。 +4. 用户只看到“知识库已同步 / 有语义冲突需确认 / 已跳过入库及原因”，不要求用户手动执行 `kb plan/apply/build/check`。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。 +- 步骤 1（素材汇总）：`subAgent=true` 时可拆子并行，仅只读汇总，不得落盘。 +- 步骤 2（大纲 + 用户确认）：必主 agent 完成，确认权不可下放子 agent。 +- 步骤 3（落盘）：`subAgent=true` 时可按已确认大纲拆子逐项落盘；硬约束：子落盘前必须前置加载近邻 2–3 个主题的开头摘要，做叙事风格对齐。 +- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 单点落盘，禁止下放。 +- 校验：默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。 + +# f2s-kb-sync（先大纲后写入） + +## 输入（可选） + +1. 用户显式给出“已实现能力列表” +2. 零输入：由 Agent 基于当前上下文推断 +3. 辅助材料：`@` 文件、需求文档、架构说明等 + +## 强制流程（不可颠倒） + +### 步骤 1：收集素材（只读） + +- 汇总用户目标、范围、优先级 +- 汇总已实现能力（用户指定 + Agent 推断） +- 对照现有知识库： + - `.Knowledge/topics/` + - `.Knowledge/index.md` + - `.Knowledge/manifest-routing.json` + - `.Knowledge/matchers/*.json`（与路由中 `matcherPath` 对应的分片） + - `.Knowledge/stock-docs/` +- **主题粒度扫描**：对已有 topic 粗扫以下信号，命中时在步骤 2 大纲中列为"建议拆分"（不阻断同步流程）： + - 对应 stock-doc 超过 **300–500 行**； + - `includeAny` 词数超过 **12 个**； + - topic 正文包含超过 **3 个不相干职责域**的二级标题。 + +### 步骤 2：输出《更新大纲》（必须） + +大纲至少包含： + +1. 同步目标 +2. 能力清单（用户指定 / Agent 推断 / 合并结果） +3. 信息来源 +4. 拟改文件清单（精确到路径） +5. 主题同步计划：说明每个能力是"更新已有主题"还是"创建新主题"，并列出 topicId、topic 文件、index 行、manifest/matcher 变更；如涉及 `topicMetadata`，列出 `primary` / `tags` / `confidence` 候选和证据；无明确证据时写"不分类 / 暂不写入" +6. **终稿沉淀计划（硬约束）**：对每一个"新建 / 更新"的 topic，判断其「长文背景 / 详细资料」引用槽位是否已有对应 `.Knowledge/stock-docs/*_终稿.md`： + - **已有** → 直接引用； + - **没有但本次同步的能力已经代码落地** → 大纲**必须列出**"待生成 `stock-docs/<能力名>_终稿.md`"，并注明沉淀来源（对应 `req-docs/*_技术方案.md` + 已实现代码 + 澄清文档），由本 SKILL 步骤 3 之前先触发 `f2s-doc-final` 沉淀（或由用户确认后手写），**再**让 topic 指向终稿； + - **能力仍在 req-docs 待实现阶段、尚无代码** → topic「长文背景」小节暂写占位说明「待代码落地后由 `f2s-doc-final` 生成 stock-doc 终稿」，**禁止**在此槽位直接列 `req-docs/*`。 + - 依据见 `rules/f2s-topic-authoring.*`「长文背景引用的目录边界（硬约束）」。 +7. 不改动范围 +8. 等待用户确认提示 + +> 未确认前禁止落盘修改。 + +### 步骤 2.5：终稿沉淀（若步骤 2 列出待生成终稿） + +用户确认大纲后、`.Knowledge/topics/` 落盘前，先按大纲第 6 项**逐个沉淀 `stock-docs/*_终稿.md`**： + +- 优先调用 **`f2s-doc-final`**（在同一会话内直接进入，不需要用户重新触发）； +- 或按 `.Knowledge/template/`（若有终稿模版）手写并落盘； +- 沉淀完成、终稿路径确定后，再进入步骤 3 让 topic 的「长文背景」小节指向该终稿。 + +**禁止**：跳过本步直接落 topic，把 `req-docs/*` 挂进 topic 的「长文背景 / 相关资料」整节槽位。 + +### 步骤 3：确认后写入 + +> 硬约束：若启用拆子，子 agent 落盘前必须读取近邻 2–3 个主题的开头摘要，确保叙事风格一致；`manifest-routing.json` 与 `.Knowledge/index.md` 由主 agent 单点落盘，子 agent 无写权。 +> +> **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。 + +按大纲逐项更新： + +- `.Knowledge/topics/*.md` +- `.Knowledge/index.md`（同步主题路由表的“关联文档（摘要）”列） +- 路由清单（按需）；若创建新 topic，须同步 `topicPaths`、必要的 `taskToTopicRules` / matcher 分片；可在证据明确时写 `topicMetadata`，但分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性，不得为了分类创建、重命名或拆分 topic +- `.Knowledge/stock-docs/*.md`（按需补充索源文档） + +### 步骤 4：收尾摘要 + +- 列出已修改路径与目的 +- 列出未执行项与原因 + +### 步骤 5：写入同步时间戳（必须,f2s-git-commit 依赖） + +本技能成功完成写入后（步骤 3 有实际文件落盘时）,由主 agent 落盘 `.Knowledge/.last-sync.json`,格式： + +```json +{ + "syncedAt": "", + "skill": "f2s-kb-sync", + "developerId": "<按 f2s-task 规则解析的 developerId,legacy 时可省略>" +} +``` + +- 该文件由 `f2s-git-commit` 在**默认覆盖检查**前读取,若 `syncedAt` 距今 < 30 分钟则跳过覆盖检查,避免刚同步完知识库又被要求同步一次。 +- **写入时机**：仅在本轮真正写盘（步骤 3 有 topic / index / manifest / stock-docs 变更）时才写；纯"读一遍 kb 什么也没改"的场景**不**写。 +- 覆盖式写入,不追加历史。 +- 落盘失败（磁盘只读、权限不足等）不阻塞本技能主流程,在收尾摘要中列一行 warning 即可。 +- 同类知识库写入技能（`f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-add` / `f2s-kb-addRules` / `f2s-kb-distill`）成功写盘后也应遵守相同约定,`skill` 字段填自己的 id。 + +## 输出摘要格式（建议） + +```markdown +## 知识库同步结果 + +### 已确认能力范围 +- <能力1> +- <能力2> + +### 已修改文件 +- .Knowledge/topics/.md：<修改说明> +- .Knowledge/index.md：<修改说明> +- .Knowledge/manifest-routing.json：<修改说明或“未改动”> +- .Knowledge/matchers/.json：<修改说明或“未改动”> +- .Knowledge/stock-docs/.md：<修改说明或“未改动”> + +### 未执行项 +- <项>：<原因> +``` + +## 复杂场景示例 + +用户仅说“/f2s-kb-sync 同步一下”，未给能力清单。 + +- 步骤 1 先做最小推断（例如从 `git diff` / 目录名归纳 1～2 个能力域），并给出推断依据。 +- 步骤 2 必须输出大纲并等待“确认”；未确认前禁止写入任何 `.Knowledge` 文件。 +- 用户确认后只执行大纲内条目；若用户中途缩小范围，未执行项写入收尾摘要。 + +## 约束 + +- 先大纲，后写入 +- 小步增补，避免整文件重写 +- 同主题优先原位更新 +- `index.md` 每个主题需包含 `stock-docs/req-docs` 的摘要级**可点击 Markdown 链接**（格式：`[标题](相对路径)`，1-3 条，允许写“无”） +- 不改配置根 `rules/skills` + +## 完成后自检 + +1. 是否存在未确认即写入（必须为否）。 +2. topic 文件与 index 行是否一一对应，且"关联文档（摘要）"已同步更新。 +3. manifest 中 `topics` / `taskToTopicRules` / `topicDependencies` 是否仍引用有效路径。 +4. 若写入 `topicMetadata`：key 是否均存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否避免类型前缀命名。 +5. 是否误改配置根 `rules/skills`（必须为否）。 +6. 步骤 2 大纲 + 用户确认未下放子 agent；步骤 3 子落盘前已加载近邻 2–3 主题摘要；manifest / index 由主单点落盘。 +7. **每个新建 / 更新的 topic**，其「长文背景 / 详细资料 / 相关资料 / 长文来源 / 参考文档」整节引用槽位**是否仅指向 `.Knowledge/stock-docs/*_终稿.md`**（或已定型的 stock-doc）；**不得**直接列 `.Knowledge/req-docs/*` 作为长文事实源。若代码已落地但对应终稿尚缺，是否已在步骤 2.5 完成沉淀。 diff --git a/.dsh/skills/f2s-kb-upgrade/SKILL.md b/.dsh/skills/f2s-kb-upgrade/SKILL.md new file mode 100644 index 0000000..3cc064d --- /dev/null +++ b/.dsh/skills/f2s-kb-upgrade/SKILL.md @@ -0,0 +1,363 @@ +--- +name: f2s-kb-upgrade +description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。 +--- + +> 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。 + +# f2s-kb-upgrade（知识库模板升级技能） + +**术语（必须）**：**「升级」「升级命令」「知识库升级」** 仅指按本文件 **`f2s-kb-upgrade`** 执行的完整技能流程。**`flow2spec init`** 是 CLI **初始化/落盘**命令；本技能 **步骤 2** 会代跑它，**禁止**把用户单独执行的 `init` 或 CLI 帮助里的 `init` 表述为「升级命令」。 + +## 边界（避免误区） + +- **`flow2spec init` 不写业务知识**：不替代 `f2s-kb-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-kb-build` 等对 `stock-docs` / `req-docs` / `topics` 正文与业务向路由词条的维护。 +- 本技能跑通的是 **包版本下的目录、模板占位、路由结构对齐**；用户若说「把新能力写进知识库」，应引导 **`f2s-kb-sync` / `f2s-kb-add`** 等，而非仅 `f2s-kb-upgrade`。 +- 本技能负责存量 `topicMetadata` 审计：`primary` / `tags` 仅用于治理、审计、盘点和阅读预期，不参与路由命中或执行强制性；执行强制性仍以 `AGENTS.md`、rules、skills 与 topic 正文为准。 + +## 包侧发版纪律（`projectRev` 必须正确 bump） + +**字段位置**：`templates/{zh-CN,en-US}/knowledge/manifest-routing.json` 的根级整数字段 `projectRev`（起始 `1`）。 + +**字段写入语义（必读）**： +- **包侧**：维护者按下文规则手动 bump（包模板自身的 `projectRev` 永远是最新值）。 +- **项目侧**（落盘到 `.Knowledge/manifest-routing.json`）： + - **首次 init**：项目 `.Knowledge/manifest-routing.json` 不存在 → `init` 把模板原值落盘，等同首次落地即基线对齐。 + - **后续 init**：项目 `.Knowledge/manifest-routing.json` 已存在 → `init` **不再覆盖该字段**（保留项目原值）；该字段只由本技能完整流程末尾 3b 写入（见步骤 3b「回写 `projectRev`」）。 + - 这使「项目侧 `projectRev`」语义清晰：**「本项目已基线对齐到的包模板修订号」**，而非"上次 init 时碰到的"。 + +**必须 bump 的修改**（每次发版至少 `+1`）： +- 包模板 `templates//knowledge/topics/.md` 任一文件的**正文**修改、新增、删除或改名； +- 包模板 `templates//knowledge/matchers/.json` 的 `includeAny` 词条、`id` 或新增 / 删除 matcher 文件； +- 包模板 `templates//knowledge/manifest-routing.json` 的 `topicPaths` / `taskToTopicRules` / `topicDependencies` / `fallbackTopic` / `topicMetadata` 任一段修改； +- 包模板 `templates//knowledge/index.md` 「主题一览」节或包级章节修改。 + +**不需要 bump 的修改**： +- 包源码（`lib/`、`cli.js`、`scripts/`）、`AGENTS.md`、`README*` 文档； +- `templates//flow2spec.config.json` 默认值； +- `templates//rules/*` / `templates//skills/*` 仅规则与技能正文修改（这些与主题层无关，无需触发完整流程）。 + +**判定准则一句话**：模板里 `knowledge/` 目录下 topic / matcher / manifest / index 任一**主题层产物**变了 → 必 bump；否则不动。漏 bump 会让用户的 `f2s-kb-upgrade` 跑快速路径，错过包带来的主题变更。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。 +- **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。 +- **主必控**（主 agent 不可下放）： + 1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。 + 2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。 + 3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。 + 4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。 + 5. **校验摘要**：校验结论与输出摘要由主 agent 汇总。 +- **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。 +- 本 SKILL 不绑定交叉校验；落盘侧自验。 + +## 与 `f2s-kb-migrate` 为何并存 + +| 技能 | 解决的问题 | +| --- | --- | +| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 | +| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**，刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将当前语言的 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 | + +- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 +- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 + +**为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** +各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 + +## 目标 + +当用户说「帮我升级知识库模板 / 跑 f2s-kb-upgrade / 同步最新 Flow2Spec」时，Agent **按本技能 `f2s-kb-upgrade` 全文流程执行**（含代跑 `flow2spec init`、清理、校验、摘要）；**勿**把仅执行 `init` 等同于完成本技能。 + +## 默认行为 + +1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。 +2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。 +3. 优先写入用户指定的 agent；未指定时使用包的默认客户端选择。 + +## init 与技能自更新（必须） + +本技能在 **步骤 2** 会执行 **`flow2spec init`**；`init` 会把当前语言对应的技能内容同步到各 agent **配置根**，因此 **`init` 成功结束后**，本仓库里的 **`skills/f2s-kb-upgrade/SKILL.md`** **可能被新版本覆盖**，与当前对话里已缓存的旧说明不一致。 + +**闭环（防旧条令）**： + +1. **`init` 前**（推荐）：记下当前配置根内 **`skills/f2s-kb-upgrade/SKILL.md`** 的标识（如 `mtime`、文件大小或正文 hash）。 +2. **`init` 成功结束后**：**重新读取磁盘上** 该 **`SKILL.md` 全文**（Cursor：`.cursor/skills/f2s-kb-upgrade/SKILL.md`；Claude：`.claude/skills/...`；Codex：`.codex/skills/...`，与本次 `init` 写入的 agent 一致）。 +3. **若相对步骤 1 有变化**（或刚升级 Flow2Spec 包、无法确认是否无变）：**必须以最新 SKILL 为准**，按新版字面**重跑评估与落盘**（即从下文「步骤 2c」开始：重新读 `projectRev` / `pkgRev`、按新版判定表决定快速路径或完整流程、跑步骤 3 / 3a / 3b / 4 / 5）。**重跑时不再次执行 `flow2spec init`**——本轮已在步骤 2 跑过；再 init 不会带来新信息，反而会让 SKILL 自更新闭环陷入循环。可循环至**连续两轮**读到的 SKILL **无变化**，或用户明确要求停止。 +4. **若无变化**：继续执行步骤 2c 及以后。 + +> **快速路径例外**：若步骤 2c 判定为「快速路径」（`projectRev == pkgRev`，主题层未变），即便 SKILL.md 字面有变化，也**不要求**按新版重跑——重跑后仍会再次判定为快速路径，徒增开销。仅在「完整流程」分支下保留闭环。 + +> 口径：**本技能步骤 2 执行 `init` 后** → 再读最新 `f2s-kb-upgrade/SKILL.md` → 有变 + 走完整流程时才**按新版字面从步骤 2c 起重跑**（**不再次 init**）；不要仅凭会话记忆执行 **本技能**。 + +## 强制流程 + +### 步骤 -1：全局 flow2spec 版本预检（必须，先于一切，主 agent 前台探测） + +**目的**：让「能用全局 `flow2spec` 就用全局」，只在**没装**或**版本过旧**时才动手升级；已装且已是 latest 时**完全跳过**升级动作，同时决定步骤 2 命令的**默认形态**（用 `flow2spec init` 还是 `npx @latest init`）。 + +**动作**：主 agent 在进入步骤 0 **之前**，**顺序、前台**执行以下 3 条探测（都是纯查询，无副作用，秒级返回；无需拆子 agent）： + +```bash +# 1. 探测本机全局是否装了 flow2spec +flow2spec --version 2>/dev/null || echo __F2S_NOT_INSTALLED__ +# 2. 查询 npm 上 latest 版本号（网络受限时可能失败，允许失败） +npm view @double-coding/flow2spec version 2>/dev/null || echo __F2S_NPM_UNREACHABLE__ +# 3. （备用）若第 1 步返回 __F2S_NOT_INSTALLED__，用来确认 npx 可用 +command -v npx >/dev/null 2>&1 && echo __NPX_OK__ || echo __NPX_MISSING__ +``` + +**判定 3 分支**（按结果选一条，写入本轮上下文并影响步骤 2 与步骤 5 摘要）： + +| 情况 | 判定条件 | 行动 | 步骤 2 命令默认形态 | +| --- | --- | --- | --- | +| **A. 已装且是 latest** | 第 1 步返回版本号 `V`，第 2 步返回版本号 `L`，且 `V === L` | **完全跳过升级**，本轮不派子 agent、不跑 `npm i -g` | **`flow2spec init `**（用全局） | +| **B. 已装但落后** | 第 1 步返回版本号 `V`，第 2 步返回版本号 `L`，且 `V !== L`（`V < L` 或 semver 不等） | **派独立子 agent 后台跑** `npm i -g @double-coding/flow2spec@latest`（fire-and-forget，不等待，不阻塞主流程）；本轮步骤 2 仍用 `npx @latest` 保证本次拿到 latest 模板 | **`npx @double-coding/flow2spec@latest init `** | +| **C. 未装 or 版本无法确认** | 第 1 步命中 `__F2S_NOT_INSTALLED__`，或第 2 步命中 `__F2S_NPM_UNREACHABLE__` 且第 1 步也未拿到版本号 | 若 A 情况「已装 latest」不成立且**未装**：派独立子 agent 后台跑 `npm i -g ...@latest`（同 B）；若第 2 步失败但第 1 步已装某版本：视作 B 且无法比对 latest，**不派**升级、仅提示「latest 未知，保守用 npx」 | **`npx @double-coding/flow2spec@latest init `** | + +**编排（必须）**： + +- **A 分支**：主 agent 直接跳过所有升级动作，**不派**子 agent；本轮步骤 2 命令首选 `flow2spec init`。 +- **B / C 分支**：若确需升级（未装或版本落后），派**独立子 agent** fire-and-forget 执行 `npm i -g @double-coding/flow2spec@latest`，**不等待完成**、**不阻塞**主流程；成败均不进入 SKILL 结论。该派子**强制**执行，**不受** `flow2spec.config.json.subAgent` 字段约束（全局 npm 装包不属业务拆分范畴）。 +- **写权**：子 agent 仅执行该 shell，**不**触碰 `.Knowledge` / `manifest-routing.json` / `index.md` 等任何项目文件；写权硬约束不变。 +- **探测失败兜底**：若 3 条探测全部失败（无 shell 权限、极端受限环境），按 C 分支处理并用 `npx @latest`；此时也可以直接放弃步骤 -1、把升级留给 `cli.js` 的 `maybeAutoUpdateGlobalInstall()` 收尾兜底。 + +**与 cli.js 的关系**： + +- `cli.js` 内 `maybeAutoUpdateGlobalInstall()` 是 `init` 收尾兜底逻辑，**与本步不冲突**：本步在前台 init 之前完成探测/派工，cli 那段在 init 收尾时再兜一次；两次都成功就是 no-op，第一次失败第二次还能补救。 + +### 步骤 0：版本判定与分流（必须，先于 init） + +> **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 + +**V1 — 旧版知识组织（须先迁移再 init）** +命中**任一**强信号则按 V1： + +- 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或 +- 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。 + +**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。 + +**现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）** +同时满足： + +- 存在 **`.Knowledge/manifest-routing.json`**，且 **`topicPaths` / `taskToTopicRules`** 可用； +- 业务文档已以 **`.Knowledge/stock-docs`、`req-docs`、`topics`** 为主（可与 V1 刚结束状态衔接）。 + +**历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。 + +**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。 + +### 步骤 1：确认本技能内 `init` 模式（必须） + +- 若用户未明确「覆盖重置」，本技能步骤 2 默认 **增量 `init`**。 +- 若用户提到「全部按模板覆盖/重置」，二次确认后再使用 `--reset-knowledge`。 +- **locale 规则**：普通升级沿用项目 `flow2spec.config.json.locale`；字段不存在时按 `zh-CN` 补齐。禁止在本技能中顺手切换语言；只有用户显式要求 `--locale en-US` / `--locale zh-CN` 时才传入对应参数。 + +### 步骤 2：执行命令（代用户跑 shell） + +**步骤 2 开始前**：读取项目侧 **`.Knowledge/manifest-routing.json`** 的 `projectRev` 字段（**字段不存在则记为 `null`**），将该值记为 **`projectRev`**。`projectRev` 表示**「本项目已基线对齐到的包模板修订号」**（由本技能完整流程跑完步骤 3 / 3a / 3b 后写入；首次 init 时 init 会以模板值落盘）；**`init` 在 manifest 已存在时不再覆盖该字段**，因此 `projectRev` 反映的是本项目最近一次完整流程对齐到的版本，而非"上次 init 时包带过来的"。`projectRev` 将用于步骤 2c 与 `pkgRev` 对比。 + +在目标项目根目录执行以下命令（**按步骤 -1 的分支结论选默认形态**）： + +1. **步骤 -1 判定为 A（已装且是 latest）**：直接用全局 CLI（**首选**）： + - `flow2spec init ` +2. **步骤 -1 判定为 B/C（未装 / 落后 / latest 未知）**：拉 npm latest 跑（**保证本次拿到最新模板**）： + - `npx @double-coding/flow2spec@latest init ` +3. 覆盖重置时： + - 在上述命令末尾追加 `--reset-knowledge` +4. 用户显式要求切换模板语言时： + - 在上述命令末尾追加 `--locale ` +5. **手动 override**：若用户明确说「就用全局」或「就用 npx」，按用户意愿选定；不再走步骤 -1 分支自动匹配。 + +> `` 示例：`cursor claude codex`。 + +> **辅助命令（用户可自查）**：`flow2spec --version` 看当前全局版本；`flow2spec update` 触发 CLI 内置的自更新。这两条**不**替代本 SKILL 的完整流程——它们只是「让全局 CLI 保鲜」，主题层对齐仍须走本 SKILL 步骤 2 及以后。 + +**步骤 2 完成后**：立刻执行上文 **「init 与技能自更新」**：重读 **`skills/f2s-kb-upgrade/SKILL.md`**；若有更新则**按新版字面从步骤 2c 起重跑**（**不再次 init**；避免用旧版 SKILL 做后续校验）。 + +### 步骤 2c：主题层变更判定（必须，决定走快速路径或完整流程） + +**目的**：包升级若**未带主题层变更**（topic / matcher / index 模板正文未改），跳过步骤 3 / 3a / 3b 与"整技能重跑"闭环，直接进入步骤 4 轻量校验。仅当包侧明确 bump 了 `projectRev` 才走完整流程。 + +**判定方法**： + +1. **`init` 跑完后**，从**项目侧 manifest**取 `pkgRev`。**口径**：直接 `Read` 项目根 **`.Knowledge/manifest-routing.json`** 的 **`pkgRev`** 顶层字段。该字段由本次 `init` 写入，记录"本次 init 用的包模板 projectRev"——是包侧最新值，与同文件里的 `projectRev`（= `projectRev`，"本项目已基线对齐到的包模板修订号"）形成「包侧 / 项目侧」对照，无需新增文件。 + + - 字段存在且为整数 → `pkgRev = <整数>`； + - 字段缺失或非整数 → `pkgRev = null`（包模板自身未声明 `projectRev`）； + - 项目侧 manifest 文件本身缺失 → 不在本步处理，应在步骤 2 / 步骤 1 自检阶段就报错。 + +2. 比对 `projectRev`（步骤 2 开始前记录）与 `pkgRev`： + +| `projectRev` | `pkgRev` | 判定 | 后续 | +| --- | --- | --- | --- | +| 任意值 | `null` | **完整流程**（包未声明字段，走旧逻辑兜底） | 走完整步骤 3 / 3a / 3b | +| `null` | 任意整数 | **完整流程**（项目首次接入或老项目升级，需走完整流程做基线对齐） | 走完整步骤 3 / 3a / 3b | +| 整数 X | 整数 X（相等） | **快速路径**（主题层未变） | **跳过** 步骤 3 / 3a / 3b 及"整技能重跑"闭环，**直接进入步骤 4** | +| 整数 X | 整数 Y（不等） | **完整流程**（包带来主题层变更） | 走完整步骤 3 / 3a / 3b | + +3. **`--reset-knowledge` 例外**：用户显式 reset 时，**强制走完整流程**，忽略本步判定（reset 必须走完整 3b 重建）。 + +4. **本步判定结论必须写入步骤 5 摘要**，形如「`projectRev`：项目 `X` vs 包 `Y` → 快速路径 / 完整流程 / 字段缺失走兜底」。 + +> **盲点声明**：本判定只看 `projectRev`，**信任包侧维护者在改了 topic / matcher 模板正文时按规矩 bump**。若包侧未守纪律，可能漏判；用户主观觉得不对时可显式追加 `--full` 语义（口头要求"完整流程"即可），技能侧应忽略快速路径直接走完整流程。 + +### 步骤 3：旧主题模板清理与引用修复（若存在则必须执行） + +> **快速路径跳过**：若步骤 2c 判定为「快速路径」，**本步骤整段跳过**，直接进入步骤 4。仅在「完整流程」时执行以下内容。 + +**本技能步骤 2** `flow2spec init` 成功后，先执行「旧文件清理 + 引用修复」： + +> **skill 目录自动对齐**：`flow2spec init` 现已自动删除配置根 `skills/` 中当前版本不再提供的旧目录（重命名/删除的 skill 如 `f2s-ctx-build`、`f2s-doc-add`、`f2s-rule-capture`、`stock-docs-vs-req-docs` 等），**无需 Agent 手动清理**。 + +1. 清理旧命名主题文件（仅在文件存在时删除，均为无 `f2s-` 前缀的旧版遗留）： + - `.Knowledge/topics/flow2spec-architecture.md` + - `.Knowledge/topics/implement-tech-design.md` +2. 修复引用（仅在文件存在时更新；**`.Knowledge/index.md` 正文不由 init 改写**，见步骤 3b）： + - `.Knowledge/index.md`（按需人工或技能侧改路径/段落） + - `.Knowledge/manifest-routing.json` +3. 引用更新目标（确认使用新名）： + - `.Knowledge/topics/f2s-flow2spec-architecture.md` + - `.Knowledge/topics/f2s-implement-tech-design.md` + - `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` + +> 口径：只清理”旧命名主题文件”，不删除带 `f2s-` 前缀的现行主题文件。 + +### 步骤 3a：`topicMetadata` 存量审计（必须执行） + +> **快速路径跳过**：若步骤 2c 判定为「快速路径」，**本步骤整段跳过**。仅在「完整流程」时执行。 + +1. 读取 `.Knowledge/manifest-routing.json`，以 `topicPaths` 为主题全集。 +2. 校验 `topicMetadata`：key 必须存在于 `topicPaths`；`primary` 仅允许 `feature` / `module` / `config` / `policy`；`tags` 若存在须为数组，元素取值同 `primary` 且不得与 `primary` 重复；`confidence` 仅允许 `manual` / `inferred`。 +3. 对 `topicPaths` 中缺少 metadata 的主题做分类分析：**必须 Read 对应 `.Knowledge/topics/.md` 正文**，禁止仅凭 topicId 名称推断。证据明确则写入 `inferred`；证据不足时**不写 metadata**，但须在摘要中列出推断方向与依据（如「建议 policy，正文含多处强制约束」），供用户确认后手动补写 `manual`。 +4. 分类判断以 `f2s-topic-authoring` 准则第 3 节为准，Agent 基于 topic 正文判断主要性质，写 `primary`；同时覆盖多个性质时其余写 `tags`（可选）。 +5. 禁止因为补分类创建、重命名或拆分 topic。 +6. **主题粒度审计**（不阻断升级，仅列入摘要）：逐项检查，命中任一信号时在步骤 5 摘要中列为「建议拆分」： + - 对应 stock-doc 超过 **300–500 行**； + - `includeAny` 词数超过 **12 个**； + - topic 正文包含超过 **3 个不相干职责域**的二级标题； + - 该 topic 同时被多种不相干任务类型频繁命中（可从 `taskToTopicRules` 和 matcher 词宽度判断）。 +7. **旧 topic frontmatter 自动补齐**：完整流程中必须由 agent 自行执行 `flow2spec kb build --fix-topics`（或等价内部能力），为缺少 frontmatter / `revision` 的存量 topic 补 `id`、`revision`、`summary`，并按 `manifest-routing.json` 补 `dependsOn` / `primary` / `confidence` / `tags`。随后执行 `flow2spec kb check --strict`；若 strict 失败，停止并在摘要中列出具体 topic / reason。不得要求用户手动逐个 topic 添加头部。 + +### 步骤 3b：`index.md` 融合与 `template/index.template.md`（必须执行） + +> **快速路径跳过**：若步骤 2c 判定为「快速路径」，**本步骤整段跳过**（包模板的「主题一览」节未变 → 现有 `index.md` 仍是对的）。仅在「完整流程」时执行。 + +> **范围**：本条「融合」**仅在本技能内由 Agent 落盘 `.Knowledge/index.md`**；**不要求、也不假设**修改 Flow2Spec 包内 **`cli.js` / `lib/init.js`** 等 JS。`init` 行为仍以仓库现行为准（仅复制快照等）。 + +**`flow2spec init` 在本流程中的角色**：把当前语言的 `index.md` 快照复制到 **`.Knowledge/template/index.template.md`**，作为**包版外壳对照**；**不**替代本步骤对 **`index.md`** 的融合书写。 + +#### 融合规则（必须遵守） + +0. **写权归属**：本步骤的 `.Knowledge/index.md` 融合恒由主 agent 执行并落盘；子 agent 不得直接写入（写权硬约束）。 +1. **对照源** + - **包版全文**：**`.Knowledge/template/index.template.md`**。 + - **项目现状**：**`.Knowledge/index.md`**。 + +2. **项目自身维护区（锚点：`.Knowledge/template/index.template.md` 中的 `## 主题一览`）** + - 以 `.Knowledge/template/index.template.md` 为参照：**从二级标题 `## 主题一览` 起**，**直至本节结束**：即到 **紧挨在 `## 命中与执行`（含括号说明）之前的那个 `---` 之前**的整块内容（含「主题一览」下的表格、节内说明段落等）。 + - 该整块 **必须保留来自当前项目 `.Knowledge/index.md` 的正文**（由业务与 **f2s-*** 维护）；**禁止**用包模板同一段落**整体替换**覆盖（避免丢失业务主题行与摘要列）。 + - **允许**在该块内做**最小必要修补**：例如为新增的 `topicPaths` 主题**补行**、按 **`manifest-routing.json` 的 `topicPaths`** 改正「路径」列、与快照对比后补上新增的表格列说明——仍以保留项目已有行为主。 + +3. **必须与包模板一致的部分** + - **上述维护区之外**的所有内容（含 **`## 主题一览` 之前**从文件开头到该节前、以及 **`## 命中与执行` 及之后**直到文件结尾）：须与 **`.Knowledge/template/index.template.md`** 中对应段落 **一致**（以包版为准；diff 后以模板覆盖项目侧旧文）。 + +4. **产出** + - 将融合后的完整 **`index.md`** 写回 **`.Knowledge/index.md`**。 + - **diff** 结论与是否改动写入步骤 5 摘要。 + +5. **与 `--reset-knowledge` 的关系** + - 若用户已 `reset`，`.Knowledge/index.md` 可能被模板整文件覆盖，仍须按本条 **2** 从备份或版本控制恢复「主题一览」块后再与包外壳做 **3** 的合并（若仓库无备份，则按 `topicPaths` + 快照**重建**主题表并让用户确认）。 + +#### 完整流程末尾：回写 `projectRev`（必须） + +完整流程跑完上述步骤 3 / 3a / 3b 之后（**仅完整流程，快速路径不执行**），由主 agent 把项目侧 **`.Knowledge/manifest-routing.json`** 的 `projectRev` 字段**改写为 `pkgRev`**（步骤 2c 取到的整数；若 `pkgRev` 为 `null` 则**不动**该字段）： + +- 这是 `projectRev` 的**唯一**写入路径（除首次 init 模板默写之外）； +- 下一次 `f2s-kb-upgrade` 据此判定 `projectRev == pkgRev` 走快速路径，避免重复跑 3 / 3a / 3b； +- 写入与 `manifest-routing.json` 其余字段同属主 agent 写权（写权硬约束）。 + +### 步骤 4：校验本技能执行结果（必须） + +至少校验： + +1. 步骤 2 的 `flow2spec init` 是否成功退出（exit code = 0）。 +2. init 输出是否包含 **路由清单与 `.Knowledge` 的结论**（已对齐/已最新/reset 覆盖等），以及 **`index.template.md` 已复制** 一行（若包内缺 `index.md` 则无此行）。 +3. `manifest-routing` 与各 `matcherPath` 分片是否可解析，且 `topicPaths` / `matcherId` 引用均有效。 +4. 存在 **`.Knowledge/template/index.template.md`**；已按步骤 **3b** 完成 **`index.md` 融合**（维护区保留 + 其余与包版一致）或写明待用户处理原因。 +5. 配置根产物是否存在： + - Cursor/Claude：`rules/`、`skills/` + - Codex：`.codex/AGENTS.md`、`skills/` +6. 本技能成功完成后，删除 `.Knowledge/update-check.json`（若存在），让下一次新会话重新检测并清除旧升级提示；若删除失败，在步骤 5 摘要中写明。 + +### 步骤 5：输出结果摘要（必须） + +输出以下信息： + +- **步骤 -1 全局版本预检**：分支结论（`A 已装且是 latest（跳过升级） / B 已装但落后（已派子 agent 后台升级） / C 未装或 latest 未知（已派或提示）`）+ 当前全局版本 + npm latest 版本（若拿到） +- 执行命令（含 agent 与是否 reset） +- 是否成功 +- **`projectRev` 判定**：`projectRev` X vs `pkgRev` Y → 快速路径 / 完整流程 / 字段缺失走兜底（步骤 2c） +- 旧主题模板清理结论（删了哪些 / 哪些本就不存在；**快速路径下：未执行**） +- `index/manifest` 引用修复结论（**快速路径下：未执行**） +- **index**：`index.template.md` 是否已生成；**`index.md` 融合**是否完成（锚点 **18–19「主题一览」节**保留、其余与包版一致）及 `topicPaths` / diff 结论（步骤 3b；**快速路径下：未执行**） +- **`projectRev` 回写**：完整流程跑完后是否已把项目侧 `projectRev` 改写为 `pkgRev`（步骤 3b 末「回写 `projectRev`」；**快速路径下：未执行**） +- **SKILL 自更新**：`init` 后是否重读 `f2s-kb-upgrade/SKILL.md`；是否因文件变化**按新版字面从步骤 2c 起重跑**及轮次（**不再次 init**；见「init 与技能自更新」；**快速路径下：跳过该闭环**） +- manifest / matchers 对齐结论（随 init 输出） +- 关键文件校验结论 +- `.Knowledge/update-check.json` 清理结论（已删除 / 不存在 / 删除失败） +- 如失败，给出下一步可执行修复建议 + +## 输出摘要模板（建议） + +```markdown +## f2s-kb-upgrade 执行结果 + +- **步骤 -1 全局版本预检**：`A 已装且是 latest（跳过升级） / B 已装但落后（已派子 agent 后台升级 npm i -g） / C 未装或 latest 未知（已派 / 保守用 npx）`；当前版本=``，latest=`` +- 本技能内代跑命令：`<实际执行的 flow2spec init ... 或 npx @latest init ...>` +- init 模式：`增量` / `覆盖重置（--reset-knowledge）` +- 执行结果：`成功` / `失败` +- **主题层判定**：`projectRev=` vs `pkgRev=` → `快速路径（已跳过 3/3a/3b）` / `完整流程` / `字段缺失走兜底` + +### 核心校验 +- 旧主题文件：`已清理` / `无需清理` / `快速路径下未执行` +- 引用修复：`已更新` / `已一致` / `快速路径下未执行` +- **index（快照 + 融合）**：`快照已复制` / `index.md 已融合` / `快速路径下未执行` / `待处理（见备注）` +- **topicMetadata（存量审计）**：`已补齐` / `待用户确认` / `快速路径下未执行`；列出新增 / 修正 / 删除的 topicId +- **topic frontmatter**：`已自动补齐 N 个` / `已完整无需补齐` / `strict 校验失败` / `快速路径下未执行` +- **f2s-kb-upgrade SKILL**：`init 后无变化` / `已按新版从 2c 起重跑 N 轮（不再次 init）` / `快速路径下跳过该闭环` / `待确认` +- **`projectRev` 回写**：`已写入项目 manifest（值=pkgRev）` / `快速路径下未执行` / `pkgRev=null 未动` +- manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖` +- topics.path：`全部存在` / `存在缺失（见下）` +- agent 产物：`通过` / `异常（见下）` +- update-check 缓存：`已删除` / `不存在` / `删除失败` + +### 备注 +- <失败原因或后续建议> +``` + +## 约束 + +- 不把“请用户自行运行命令”作为默认方案；优先由 Agent 直接执行。 +- 未经明确同意，不执行 `--reset-knowledge`。 +- 不修改业务代码；仅按 **本技能 `f2s-kb-upgrade`** 流程与结果做校验。 +- 步骤 3b `.Knowledge/index.md` 融合与 `manifest-routing.json` 均恒由主 agent 落盘（写权硬约束）；子 agent 仅可代跑 shell 命令。 + +## 完成后自检 + +1. 是否已做 **步骤 -1**：在进入步骤 0 前**已顺序前台执行 3 条探测**（`flow2spec --version` / `npm view ... version` / `npx` 可用性），并按 A/B/C 分支得出结论；仅在 B/C 时才**派独立子 agent**后台跑 `npm i -g @double-coding/flow2spec@latest`（不等待），A 分支**未派**任何升级动作；步骤 2 命令默认形态是否随分支选定（A→`flow2spec init`，B/C→`npx @latest init`）；摘要中已写清分支与版本对比。 +2. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。 +3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 +4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 +5. 是否已实际执行 shell 命令（而非只给建议）。 +6. 是否明确标注增量 or reset 模式。 +7. **完整流程时**：是否已处理旧主题文件清理与 `index/manifest` 引用修复（步骤 3）。 +8. **完整流程时**：是否已执行 **步骤 3a**：审计 `topicMetadata`，确保无孤儿 key / 非法 primary / 非法 confidence；缺失旧主题已按证据补 `inferred` 或列为待确认。 +9. **完整流程时**：是否已执行 `flow2spec kb build --fix-topics` 或等价内部能力，并随后执行 `flow2spec kb check --strict`，确保存量 topic 已具备 `revision`。 +10. **完整流程时**：是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`；**完整流程末尾**是否已**回写** 项目侧 `projectRev = pkgRev`（`pkgRev=null` 则保留原值）。 +11. **快速路径时**：步骤 3 / 3a / 3b 是否真的跳过（未做无关扫描），摘要中明确标注「快速路径下未执行」。 +12. 是否输出了 manifest 与关键路径校验结果。 +13. 若失败，是否给出下一步具体命令建议。 +14. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入（仅在完整流程时适用）。 +15. 成功升级后是否删除 `.Knowledge/update-check.json`，避免当天新会话继续提示旧升级信息。 diff --git a/.dsh/skills/f2s-req-clarify/SKILL.md b/.dsh/skills/f2s-req-clarify/SKILL.md new file mode 100644 index 0000000..9a23245 --- /dev/null +++ b/.dsh/skills/f2s-req-clarify/SKILL.md @@ -0,0 +1,32 @@ +--- +name: f2s-req-clarify +description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-tech 出技术方案；触发：需求澄清、PRD 澄清 +--- + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。 +- 本技能默认**不拆子**：无论 `subAgent` 真值，澄清流程全程在主会话进行（追问与用户对齐强依赖连续同会话，拆子必断上下文）。 +- 校验口径为**落盘侧自验**，本技能不绑定交叉校验。 + +# 需求澄清 + +> 执行口径：澄清文档统一落盘到 `.Knowledge/req-docs/`。 + +**入参**：可选。PRD 全文、需求描述或文档路径（如 `.Knowledge/req-docs/xxx.md`）；不传则按当前对话内容澄清。后续回复可补需求条件。 + +**行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。 + +**结束（澄清文档落盘 → 自动衔接技术方案）**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`（推荐命名 `<能力名>_需求澄清.md`）。 + +**澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`**：以刚落盘的澄清文档路径为输入直接进入技术方案生成，无需等用户再次触发；进入前给用户一行提示「澄清文档已就绪：`<路径>`；正在按 `f2s-req-tech` 生成技术方案」，然后继续。 + +**例外——停在澄清、不自动衔接技术方案**（任一命中即停）： +- 澄清文档「未决问题」小节仍有影响方案结构的关键项未回答（如库/表/接口/状态机主契约缺定义），此时输出一段说明列出待答项，等用户回答后再落盘并衔接； +- 用户在澄清过程中明确说「先只出澄清 / 别急着做方案 / 先讨论」等停步语； +- 用户显式指定了不同的后续动作（如「澄清完就停」「先给我拆任务」）。 + +**禁止**： +- 在澄清文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示（见 `rules/f2s-kb-feedback-closing.*` 禁止段——过程编排型技能落盘不触发 distill）； +- 未落盘澄清文档就自动衔接 `f2s-req-tech`（自动衔接的前提是磁盘上已有澄清文档路径）； +- 越级自动衔接 `f2s-req-plan` / `implement-tech-design` / 其他 `f2s-*` 技能（同轮只允许接到 `f2s-req-tech` 一步，后续仍须用户新一轮触发）。 diff --git a/.dsh/skills/f2s-req-plan/SKILL.md b/.dsh/skills/f2s-req-plan/SKILL.md new file mode 100644 index 0000000..0232fd5 --- /dev/null +++ b/.dsh/skills/f2s-req-plan/SKILL.md @@ -0,0 +1,150 @@ +--- +name: f2s-req-plan +description: 根据技术方案/需求描述/变更描述规划并实现任务；始终按 f2s-task 维护 .task/；支持子 agent 并行实现；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单 +--- + +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +# 需求任务规划与实现（f2s-req-plan） + +从需求/技术方案出发，完整覆盖「规划 → 实现」链路。**不依赖** `changeTracking.*`，但 **`.task/` 全生命周期必须以 `f2s-task` 为唯一真值源**（目录、格式、续作、打钩、归档、user-todos）。知识库同步由用户后续按需调用 `f2s-kb-feat` / `f2s-kb-sync`。 + +## 与 f2s-task 的关系（硬约束） + +| 项 | 说明 | +| --- | --- | +| **真值源** | 配置根 **`rules/f2s-task.*`**（`alwaysApply: true`）；Codex 读 **`.codex/topics/f2s-task.md`**（init 镜像，与 rules 同源） | +| **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 | +| **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 | + +**所有已为项目初始化的客户端都必须读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**。请从当前客户端生成的 rules、`AGENTS.md` 或 topics 入口读取，不得用本技能摘要代替全文。 + +## 编排（主 / 子 agent） + +- `subAgent` / `switchAgentVerification` 以统一入口为唯一事实源：**Cursor/Claude** → `rules/f2s-flow2spec-unified-entry.*`；**Codex** → `.codex/topics/f2s-flow2spec-unified-entry.md`。 +- **步骤 1（续作分诊 + 解析）**：主 agent 必做 `f2s-task`「任务开始」1–2；解析文档可拆子 agent（只读）。 +- **步骤 2（草稿确认）**：必须主 agent；未确认前禁止创建 `.task/` 或写业务代码。 +- **步骤 3（落盘）**：按 `f2s-task`「任务开始」3.a–3.f；`todo.json` **仅主 agent**；`task.md` / `context.md` / `user-todos.md` 初稿可子 agent，`user-todos.md` 执行中追加由主 agent 合并。 +- **步骤 4（实现）**：子 agent 只写业务代码；**禁止**子 agent 写 `todo.json`、改 `task.md` checkbox；打钩由主 agent 在合并后当步完成。 +- **步骤 5（归档）**：主 agent；**仅**满足 `f2s-task`「任务完成」归档门禁后执行。 +- worktree 卫生见 `f2s-flow2spec-unified-entry`；中断/结束见 `f2s-task`「中断与会话结束」。 + +## 输入（任选其一） + +- 技术方案路径（`.Knowledge/req-docs/*.md` 或 PDF） +- 需求 / 变更描述（自由文本） + +## 步骤 + +### 步骤 0：前置（强制，任何步骤之前） + +1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。 +2. **`Read` 当前客户端生成入口中的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 +3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。 + +### 步骤 1：续作分诊 + 解析输入 + +#### 1a. 续作分诊（`f2s-task`「任务开始」1–2，主 agent） + +1. 若存在 **`.task/todo.json`**，`Read` 并将**用户本条输入**与各条目 **`keywords`** 匹配。 +2. **命中 1 个** → `Read` 对应 `task.md`、`context.md`；若存在则 `Read` **`user-todos.md`**；向用户展示剩余 checklist 与未勾用户代办；询问是否**续作**该任务。 + - 用户确认续作 → **加载本 SKILL 全文**（`linkedSkill` 应为 `f2s-req-plan`），从 `task.md` 首个 `[ ]` 继续；**禁止**新建重复 `active/` 目录；**跳至步骤 4**（若仍需补充规划，先在「## 备注」记录后再实现）。 + - 用户明确要**新任务** → 进入 1b。 +3. **命中多个** → 列出候选，让用户选择续作哪一个或新建。 +4. **无命中** → 检查**孤儿 `active/`**（`f2s-task`）：若有未归档且含 `[ ]` 的 `task.md`，提示是否续作或恢复 `todo.json`；否则进入 1b。 +5. **无 `todo.json`** → 进入 1b。 + +#### 1b. 解析输入（新任务或待草稿） + +`subAgent=true` 时可拆子 agent 并行只读： + +- 读取方案/需求全文，提取目标、范围、工作项、涉及文件 +- 读取 `.Knowledge/stock-docs/` 等对齐上下文 +- PDF 先 `f2s-doc-pdf` 转 MD + +子 agent 只交「解析摘要」；`subAgent=false` 时主 agent 完成。→ **步骤 2**。 + +### 步骤 2：输出草稿并确认（必须主 agent） + +主 agent 输出： + +1. **任务名称**（snake_case） +2. **实现清单草稿**（每步可 checkbox，将写入 `task.md` 的「## 步骤」） +3. **涉及文件列表**（将写入 `context.md`） +4. **建议 `keywords`**（2–5 个，供 `todo.json` 续作匹配） +5. **等待用户确认** + +> **未确认前**禁止：创建 `.task/`、写 `todo.json`、写业务代码。 + +### 步骤 3：落盘任务清单（`f2s-task`「任务开始」3.a–3.f） + +用户确认后，**严格按 `f2s-task` 执行**（格式以该规则正文为准，不得省略文件）： + +| 子步 | 动作 | 写权 | +| --- | --- | --- | +| 3.a | 确认 ``（snake_case） | 主 | +| 3.b | 创建 `.task/active//` | 主或子（初稿） | +| 3.c | 写入 **`task.md`**：`# 任务名` + `## 步骤` + `- [ ]` 列表 + 空 `## 备注` | 主或子 | +| 3.d | 写入 **`context.md`**：涉及文件、`.Knowledge` 资料链接；用户代办指向 `user-todos.md` | 主或子 | +| 3.e | 创建 **`user-todos.md`**（固定文件名；无代办时写占位说明） | 主或子 | +| 3.f | **`todo.json` 新增条目**：`name`、`folder`、`keywords`（含步骤 2 建议词）、`linkedSkill: "f2s-req-plan"`、`createdAt` | **仅主 agent** | + +**禁止**：只建 `task.md` 不写 `todo.json`；省略 `user-todos.md`；使用 `completed/-` 旧式归档名。 + +### 步骤 4：实现代码 + +遵守 `f2s-task`「**执行中**」「**中断与会话结束**」： + +- 按 `task.md` 顺序实现；**每真实完成一步**，主 agent **立即** `Edit` 该步 `[ ]` → `[x]`（禁止批量勾选、禁止仅口头完成）。 +- 凡须用户改库/配环境/审批等，**同会话**追加 **`user-todos.md`**（按日期分节）；禁止只写在对话或 `task.md` 正文。 +- `subAgent=true`：子 agent 只改业务源码；回报后由主 agent 打钩与写 `user-todos.md`。 +- 合并子 agent 后清理 **git worktree**（见统一入口）。 + +### 步骤 5：归档任务（`f2s-task`「任务完成」） + +**归档门禁**（自检通过后才移动目录）： + +- `task.md`「## 步骤」中与本次交付相关项 **全部为 `[x]`**（取消项已在「## 备注」说明）。 +- 仍有 `[ ]` → **禁止**移入 `completed/`、**禁止**删 `todo.json` 条目。 + +通过后： + +1. `.task/active//` → `.task/completed/-/`（**日期 8 位在前**） +2. 从 `todo.json` 删除该条；空数组则删文件 +3. `user-todos.md` 随目录一并归档 + +### 步骤 6：输出摘要 + +```markdown +## f2s-req-plan 完成：<任务名> + +### 实现 +- <文件路径>：<改动说明> + +### 任务清单 +- 已归档：`.task/completed/-/`（或仍 active 时写明路径与剩余 `[ ]`） + +### 待办（知识库） +- 可后续调用 f2s-kb-sync / f2s-kb-feat + +### 用户代办 +- 见 `user-todos.md`（归档后在 completed 同路径） +``` + +## 约束 + +- **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** +- **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 +- 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） +- 步骤 2 必须主 agent；未确认禁止落盘 +- `todo.json` 仅主 agent；子 agent 禁止写入 +- 禁止批量勾选；禁止跳过 `user-todos.md` + +## 完成后自检 + +1. 是否已读 **`f2s-task` 全文** 且落盘格式与其一致。 +2. `task.md` 步骤是否均已磁盘 `[x]`（非口头）。 +3. 归档门禁满足时目录在 `completed/-/`，`todo.json` 已更新。 +4. `user-todos.md` 与会话中用户代办一致（无则占位）。 +5. worktree 已清理或已交接删除命令（N/A 则注明）。 diff --git a/.dsh/skills/f2s-req-tech/SKILL.md b/.dsh/skills/f2s-req-tech/SKILL.md new file mode 100644 index 0000000..88bacaf --- /dev/null +++ b/.dsh/skills/f2s-req-tech/SKILL.md @@ -0,0 +1,82 @@ +--- +name: f2s-req-tech +description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成技术方案文档；触发：生成技术方案、技术方案、f2s-req-tech +--- +> 执行口径：业务文档统一在 `/.Knowledge/`，本技能只产出 `.Knowledge/req-docs` 方案文档并参考 `.Knowledge` 内知识，不修改配置根 `rules/skills`。 + +## 编排（主 / 子 agent） + +- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。 +- **拆子前提（硬约束）**：当 `subAgent=true` 时，主 agent **必须先**抽取一份「项目约定摘要」作为子 agent 的强制上下文，覆盖：对外契约规范、错误与返回约定、异步/集成规范、数据与存储约定、工程结构、模块边界，合计 **< 80 行**。若未做该前置，**不拆子**——验收返工成本 > 拆子收益，强行拆子得不偿失。 +- **子职责**：多源只读（`.Knowledge/topics`、`stock-docs`、澄清后的 `req-docs`、模版）+ 按 `.Knowledge/template/技术方案模版.md` 写 `req-docs` 方案初稿。 +- **主职责**：契约定稿、对照模版与澄清文档验收、处理交付单元/流程一致性。 +- **校验**：默认落盘侧自验；本技能不绑定交叉校验。 + +# 根据需求生成技术方案文档 + +用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、端侧限定、优先级等）。你需要基于业务知识文档（`.Knowledge/`）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的技术方案文档。 + +**用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。不用于生成 Rules/Skills。 + +**结构范本**：技术方案按 `.Knowledge/template/技术方案模版.md` 中的**可选积木**按需组装输出。**不要硬套固定章节**：只写本次实现真正需要的交付单元、数据结构、配置、依赖、流程或异常处理；每个交付单元小节内同时说明契约/输入输出与必要处理流程，避免再单独拆「接口及流程说明」「关联调用流程」「流程说明」等大章重复描述同一单元。 + +--- + +## 输入 + +- **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 `.Knowledge/req-docs/xxx.md`、`.Knowledge/stock-docs/需求_终稿.md`）。 +- **后续参数或用户补充（可选）**：需求条件与约束，例如： + - 范围（只做某模块、某端） + - 必须/禁止使用的技术栈、接口风格 + - 与现有某模块的边界 + - 性能、安全、合规要求 + +--- + +## 输出结构 + +生成文档时，**先读取 `.Knowledge/template/技术方案模版.md`** 作为结构参考，按需选用其中的章节积木；与需求无关的整节可省略，也可根据项目实际增加未列出的章节。 + +--- + +## 拆子前置（可选，仅当 `subAgent=true`） + +主 agent 在拆子前，必须产出「项目约定摘要」作为子 agent 的**强制输入**，否则**不拆子**。摘要篇幅上限 **< 80 行**，必须包含以下 6 类条款（技术栈无关，按项目实际填具体值）： + +1. **对外契约规范**：接口 / 事件 / 消息 / 组件 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。 +2. **错误与返回约定**：错误码体系来源、前缀 / 分段规则、必选字段（如 code / message / data）、状态分层。 +3. **异步 / 集成规范**：消息队列 / 事件总线 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。 +4. **数据与存储约定**：库 / 表 / 字段 / 缓存 / 文件 / 搜索等命名规范、主键 / 索引 / 时间字段约定、分库分表策略（若有）。 +5. **工程结构**：模块分层（如 controller / service / dao / domain，或前端的 pages / components / hooks / store，或等价命名）与包路径 / 目录约定。 +6. **模块边界**：本方案涉及的既有模块与其他模块的调用 / 数据边界。 + +未完成该前置即拆子，视为违反硬约束；摘要完成后方可将子任务交付子 agent。 + +--- + +## 步骤 + +1. **澄清完备性前置门禁（硬约束）**：进入撰写前必须先判定当前需求是否**已澄清**： + - **已澄清**判据（满足其一即可）：① **本轮由 `f2s-req-clarify` 自动衔接进入**，且澄清文档已落盘并作为输入路径传入（这是首选路径——用户可直接从 `f2s-req-clarify` 一路走到方案，同轮完成）；② 用户显式提供 `.Knowledge/req-docs/*_需求澄清.md` 或等价澄清文档路径；③ 用户显式声明"已澄清 / 需求已明确 / 直接出方案"；④ 用户提供的输入本身即完整 PRD（含范围、关键流程、边界、验收标准），且**当轮**不含明显未定义概念或矛盾。 + - **未澄清**信号（任一命中即视为未澄清）：需求描述含"我理解为 / 我打算 / 大概 / 应该 / 待定 / 还没确定"等模糊语；接口 / 表 / 状态机 / 与既有模块的联动只给了"要做什么"未给"怎么算完"；用户输入中已被 agent 或用户自己列出但未回答的 3 个及以上关键问题；且**本轮不是**从 `f2s-req-clarify` 衔接进入。 + - **未澄清则改走 clarify**：**禁止**在同一轮内直接进入撰写；应先转入 `f2s-req-clarify` 完成澄清落盘，然后按其自动衔接规则**回到本技能同轮继续**（这是设计的直连路径，不打断用户）。如无法转入 clarify（例如用户明确说"先只做技术方案 / 别做澄清"），列 3～6 条最影响方案落笔的澄清问题清单等用户回答，**不生成方案**。 +2. **读取需求**：从用户提供的路径或正文（或 `f2s-req-clarify` 衔接传入的澄清文档路径）获取需求内容；若有需求条件，一并纳入。 +3. **加载项目上下文**：主动读取并运用： + - `.Knowledge/topics/` 下与本次需求相关的主题规则/流程； + - `.Knowledge/stock-docs/` 下的背景文档与历史技术方案； + - **结构对照 `.Knowledge/template/技术方案模版.md`**。 +4. **对齐项目约定**：命名规范、目录结构、配置约定、消息队列、错误码、数据模型等与现有项目一致。 +5. **撰写文档**：按 `.Knowledge/template/技术方案模版.md` 按需选用章节积木书写；交付单元涉及行为逻辑时，在同一小节写清处理流程，避免交付物与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。 +6. **输出位置**：默认 `.Knowledge/req-docs/<方案名>_技术方案.md`；若用户指定路径则用该路径。 +7. **收口停步（硬约束）**：技术方案落盘后**只输出一行提示**「技术方案已就绪：`<路径>`；如需继续，可用 `f2s-req-plan` 拆任务、`implement-tech-design` 落地」，然后**停止**。**禁止**： + - 在同一轮内自动衔接 `f2s-req-plan` / `implement-tech-design` / 任何后续 `f2s-*` 技能（`f2s-req-clarify` → `f2s-req-tech` 是允许的**单跳**衔接，方案之后须由用户在**新一轮**触发下一步）； + - 在方案文档尾部或紧随其后追加 `f2s-kb-distill` 收口提示（见 `rules/f2s-kb-feedback-closing.*` 禁止段——过程编排型技能落盘不触发 distill）； + - 主动列"下一步 A/B/C 选一个"式路径清单诱导用户立即进入下一技能。 + +--- + +## 约束 + +- 所有路径相对于项目根目录（与 `.Knowledge` 同级）。 +- 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。 +- **原则**：交付单元小节按需包含契约（输入/输出）与处理流程，二者不拆章重复；结构以 `.Knowledge/template/技术方案模版.md` 为参考，按需取用，不硬套。 diff --git a/.dsh/topics/f2s-config-check.md b/.dsh/topics/f2s-config-check.md new file mode 100644 index 0000000..2ee1c48 --- /dev/null +++ b/.dsh/topics/f2s-config-check.md @@ -0,0 +1,45 @@ +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +# f2s 技能前置强制步骤 + +**执行任何 `f2s-*` 技能的第一个动作，必须用 Read 工具读取项目根 `flow2spec.config.json`**，获取 `subAgent` 与 `switchAgentVerification` 的实际值，再决定后续编排方式。 + +``` +必须执行：Read("flow2spec.config.json") ← 技能正文任何步骤之前 +``` + +| 读取结果 | 行为 | +|---------|------| +| `subAgent: true` | 先显式判断当前技能是否满足拆子前提 / 规模阈值；满足时按技能 SKILL.md 的 B/C 模式派子 agent，并在回复或执行记录中写明「本次是否拆子、拆给谁、为什么」；不满足时主 agent 继续完成，但也必须输出不拆原因 | +| `subAgent: false` | 全部在主 agent 内完成，不得拆子 agent | +| `switchAgentVerification: true` | 子 agent 落盘的由主 agent 校验；主 agent 落盘的由子 agent 校验（须 subAgent=true 且已拆子任务） | +| `switchAgentVerification: false` | 落盘侧自验，不交叉 | +| 文件不存在 | 所有字段均视为 `false` | + +**Claude Code**：`f2s-config-session` 在 `SessionStart` 注入一次配置摘要；`f2s-config-inject` 在 `PreToolUse` 仅作为守门提示，提醒调用 `f2s-*` Skill 前首步必须 `Read("flow2spec.config.json")`。两者都**不替代**本条 Read 要求。 + +**Cursor**：配置读取仍走文本约束（本规则 `alwaysApply`），不依赖 hook 自动读取配置。 + +**Codex**：`SessionStart` 会注入一次配置摘要；进入 `f2s-*` Skill 正文前仍必须 `Read("flow2spec.config.json")`，且当 `subAgent=true` 时，主 agent **必须先显式判断**当前技能是否满足拆子前提 / 阈值，再决定是否派子；即使判断不拆，也必须输出不拆原因。Codex **没有** Claude 的 `PreToolUse Skill` 守门，不能把“拆子判断”留给隐式心证。 + +### changeTracking（变更追踪） + +| 字段 | 生效技能 | 行为 | +|------|---------|------| +| `changeTracking.feat: true` | `f2s-kb-feat` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 | +| `changeTracking.feat: false` | `f2s-kb-feat` | 步骤 0 跳过，不创建 `.task/` 目录 | +| `changeTracking.fix: true` | `f2s-kb-fix` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 | +| `changeTracking.fix: false` | `f2s-kb-fix` | 步骤 0 跳过，不创建 `.task/` 目录 | +| `changeTracking.implement: true` | `f2s-implement-tech-design` | **步骤 2.5 写入任务清单、步骤 2.6 随实现同步打钩 `task.md`、步骤 5 满足归档门禁后归档** | +| `changeTracking.implement: false` | `f2s-implement-tech-design` | 步骤 2.5、2.6 和步骤 5 的变更追踪部分跳过 | + +### intentRecognition（意图识别） + +| 字段 | 行为 | +|------|------| +| `intentRecognition: true` | 启用意图识别：高置信操作意图按 `rules/f2s-intent-routing.*` 自动进入对应 Skill；讨论 / 评估 / 低置信输入不得自动调用 | +| `intentRecognition: false` | 不启用自动分流；仅显式 `$f2s-*` / 明确要求执行某技能时进入对应 Skill | +| 字段不存在 | 视为 `false` | + +**禁止在未读该文件的情况下进入技能正文的任何执行步骤。** diff --git a/.dsh/topics/f2s-flow2spec-unified-entry.md b/.dsh/topics/f2s-flow2spec-unified-entry.md new file mode 100644 index 0000000..7a7c33e --- /dev/null +++ b/.dsh/topics/f2s-flow2spec-unified-entry.md @@ -0,0 +1,112 @@ +# Flow2Spec 统一入口规则 + +本项目知识库已统一到 `.Knowledge/`，请按以下顺序读取，避免无范围检索。 + +## 项目根 CLI 开关（必须按需读取） + +业务仓库**项目根** `flow2spec.config.json`（`flow2spec init` 在文件缺失时补齐）含布尔字段 **`subAgent`**、**`switchAgentVerification`**（**切换 agent 校验**），默认 `false`。执行任意 **`f2s-*` 技能**或与 Flow2Spec 初始化相关的说明前，须读取该文件；技能或规则中凡写「仅当 `subAgent` / `switchAgentVerification` 为 true」的步骤，**必须按文件实际值决定是否执行**；缺失字段或文件不存在时均视为 `false`。 + +> **`init` 与择路**：**`flow2spec init`** 会把统一入口写入当前仓库；**Cursor / Claude** 读取配置根 **`rules/f2s-flow2spec-unified-entry.*`**，**Codex** 读取 **`.codex/topics/f2s-flow2spec-unified-entry.md`**。两处正文同源，按当前工具读取对应入口即可；技能引「统一入口」时，在 **Codex** 以 **`.codex/topics/f2s-flow2spec-unified-entry.md`** 为准。 + +### 两字段语义（模板约定） + +- **`subAgent`**：`f2s-*` 技能若规定某步骤「用子 agent 执行」，则 **`true`** 时按技能使用子 agent，**`false`** 时在主 agent 内完成。用户可在对话中要求「**仅当**本项为 **`true`** 时，由主 agent **动态判断**哪些子任务适合交给子 agent」——**仅当配置为 `true` 时该要求有效**；配置为 `false` 时凡依赖拆子 agent 的该段说明**不生效**，全部在主 agent 完成。`subAgent=true` 时，主 agent 必须在技能正文前段显式判断本次是否拆子；即使判断不拆，也必须输出不拆原因。**各 `f2s-*` 在工作哪一阶段必须或建议使用子 agent** 由技能正文逐步约定；技能未写明时不默认拆子。 +- **`switchAgentVerification`（切换 agent 校验）**：落盘或变更后的**验证/复核**（对照清单、diff、自检）**不是**「一律在主 agent」；默认以**落盘侧所在 agent 为「当前 agent」**，在该会话内完成校验（**子 agent 落盘的就在子 agent 内验，主 agent 落盘的就在主 agent 内验**）。**仅当**① 配置 **`switchAgentVerification` 为 `true`**，**且** ② **当前 `f2s-*` 技能正文**对该步骤**明确写出**「当 **`switchAgentVerification`** 为 **`true`**」时，才启用**交叉校验**：**子 agent 落盘的 → 由主 agent 校验**；**主 agent 落盘的 → 由子 agent 校验**（**须**已存在子 agent 会话，即 **`subAgent` 为 `true`** 且实际拆出子任务；若 **`subAgent` 为 `false`**，无子侧可承接，**「主落盘→子验」不发生**，校验**全部在主 agent 内**完成）。配置为 `false`、或技能未写依赖本项、或用户仅泛泛要求「给对方验」的：**不**启用交叉，仍在**落盘侧 agent**内完成验证。 + +### Git worktree 与子任务工作目录卫生（`subAgent: true` 或并行子任务时必读） + +部分环境会为子 agent / 并行尝试创建 **独立 `git worktree`** 或等价隔离目录。规则如下： + +1. **谁创建谁收尾**：子侧创建则子侧在返回前尽量清理；若子会话已结束无法清理，**主 agent 合并结果后**必须执行清理，**禁止**依赖「稍后自动回收」。 +2. **收尾动作（必须）**：对**仅为本次子任务**添加的 worktree，在合并或丢弃该子任务结果后执行 `git worktree remove `（工作区干净仍失败时再用 `git worktree remove --force `，**须确认**该路径无他人未提交修改）；随后 `git worktree list` 自检，**禁止**留下已知孤儿路径。 +3. **中断 / 用户换题前**：若本会话曾添加 worktree，在结束前**必须**完成上述移除或在 `task.md`「## 备注」写明残留路径与删除命令，并视情况写入 **`user-todos.md`** 请用户本地执行（见 `f2s-task`）。 +4. **禁止**：子任务已结束、主分支已继续开发，仍长期保留仅用于尝试的 worktree 目录（易造成混淆提交、磁盘堆积）。 + +## 读取顺序（必须） + +1. 先读 `.Knowledge/manifest-routing.json`，优先按 `taskToTopicRules` 路由；按需根据 `matcherPath` 读取 matcher 分片获取 `includeAny` 关键词；无法命中时进入补召回阶段。 + - 若命中主题在 `topicDependencies` 中存在依赖，先读依赖主题，再读主主题。 + - 路由清单仅通过 `f2s-*` 技能流程维护，不依赖额外 CLI 子命令。 +2. `.Knowledge/index.md` 按需读取，仅用于确认主题语义与边界。 +3. 再读 `.Knowledge/topics/.md`（**路由摘要**：主题 id、路径约定、下一步指针）；若主题为 **`implement-tech-design`** 或 **`f2s-doc-routing`**，**必须继续读取**配置根 **`rules/f2s-implement-tech-design.*` / `rules/f2s-stock-docs-vs-req-docs.*` 全文**作为执行依据（`.Knowledge/topics` 内同名文件不重复长文）。 +4. 若需要背景，再读 `.Knowledge/stock-docs/.md`。 +5. 仅在前四步不足时下钻业务源码。 +6. 命中后必须执行 `match -> expand -> verify -> act`： + - `match`：先取主候选； + - `expand`：展开 `topicDependencies`，并保留次高候选做补充校验； + - `verify`：执行前做缺口检查（关键主题/边界/上下文是否缺失）； + - `act`：仅在置信度足够时执行；低置信度必须先澄清。 +7. 仅在以下条件之一成立时，允许执行跨 matcher 全量补检索（top-k）： + - `taskToTopicRules` 无命中； + - 主候选与次候选分差过小（低置信度）； + - 缺口检查失败（关键主题/依赖/上下文缺失）； + - 用户明确要求“全量检查/不要遗漏”。 + +## 任务分流 + +- 技术方案实现：先读 `.Knowledge/topics/f2s-implement-tech-design.md`（摘要），再读 **`rules/f2s-implement-tech-design.*` 全文**；需求文档默认位于 `.Knowledge/req-docs/`。 +- 目录边界判断：先读 `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md`（摘要），再读 **`rules/f2s-stock-docs-vs-req-docs.*` 全文**。 + +## 机读事实源口径（规则层） + +- `taskToTopicRules`：任务路由第一优先级。 +- `taskToTopicRules[].matcherPath`：匹配词分片直链路径，按需读取单个 matcher 文件。 +- `taskToTopicRules[].matcherId`：matcher 的稳定标识，需与 matcher 分片内 `id` 一致。 +- `topicDependencies`：主主题命中后先加载依赖主题。 +- `topicMetadata`：主题治理元数据，只影响阅读预期，不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性；执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。读到 `topicMetadata[topicId].primary` / `tags` 时：`config` 关注配置项、开关、默认值、初始化参数；`policy` 优先检查正文中的必须/禁止/门禁/流程约束；`feature` 作为已落地业务/产品能力背景；`module` 作为目录、包、模块边界与工程结构背景。`confidence` 仅允许 `manual` / `inferred`；无明确分类证据时不写 metadata。 +- `matcherPath(includeAny)`：任务关键词匹配词表。 +- `fallbackTopic`：任务与关键词都未命中时必须读取，但仅作低置信度兜底，不是最终执行依据。 +- `.Knowledge/manifest-routing.json + matcherPath 分片文件` 是机读事实源（关键词仅在 `matchers/*.json`）。 +- `.Knowledge/index.md` 不是机读事实源，仅作人读导航与语义边界校验。 +- 进入 `fallbackTopic` 后，必须先补召回或澄清，再决定是否执行改动。 + +## 知识缺口与对策（分场景） + +| 情况 | 对策 | +| --- | --- | +| **1a 库里有文档但未配路由** | 用 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补 `taskToTopicRules`、`matcherPath` 分片、`topicPaths`；扩充 `includeAny` 覆盖用户常用说法。Agent 侧：走 `fallbackTopic` 分诊并提示「需补路由」，**不**靠全仓扫文件代替配置。 | +| **1b 命中了但上下文不够** | 先 `expand`（`topicDependencies` + 次高候选），再 `verify` 点名缺哪份 `stock-docs`/`req-docs` 或哪段 topic；仍不足则 **向用户要文档或路径**，不要无门槛跨 matcher 全量补检索。**Agent 若需下钻源码**：须先对用户做**可见的缺口说明**（已读 KB、缺什么、拟读哪 1～2 个文件），见 **`f2s-knowledge-preflight`**「缺口闸门」；**禁止**无说明地连续 `Grep`/乱序探源。 | +| **2 库里没有对应文档** | 一次读完 routing + 已命中 matcher + 相关 topic 后，在回复中 **明确承认知识库无覆盖**，再选：下钻业务代码 / 请用户补充 `req-docs` 或 PRD。**禁止**用反复读清单假装「再找一遍就会有」。**下钻源码前**同样须满足 **`f2s-knowledge-preflight`**「缺口闸门」的可见说明。 | +| **2a 反复读清单耗 token** | **同一任务线内** `manifest-routing.json` 视为稳定快照：再次全文读取须说明理由（例如用户声明已通过 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 等更新路由或知识、或**手动编辑**了 manifest/matcher）。**勿将**仅执行 **`flow2spec init`** 等同于「业务知识库已更新」：`init` 以配置根落盘、目录补齐与包级路由结构对齐为主；**stock-docs / req-docs、topics 路由摘要、matchers 词条**由 **`f2s-*` 技能流程**维护；`init` 会把规则写入配置根 **`rules/*`**（或等价扩展名），并为 Codex 写入 **`.codex/topics/*.md`**。只读 **当前规则对应的单个** `matcherPath`；不要为枚举而遍历整个 `matchers/` 目录。`index.md` 仅在需核对主题语义时打开，禁止与 manifest 交替「刷清单」。 | + +### 知识缺口的执行层要点（避免「表里有写、行为没做」） + +- **「向用户说明」「明确承认无覆盖」必须是用户可见的自然语言**，不得仅在内部分析或工具链中隐含带过；细则与停步条件见 **`f2s-knowledge-preflight`**（缺口闸门、探索次数上限）。 +- **禁止**在命中 **1b / 2** 后，未做上述可见说明便进入「多文件 + 依赖目录」的链式探源；每出现一个新的「入口符号」就再 `Grep` 一轮，属于典型反模式。 +- **HTTP 状态、错误正文、重定向与否**等事实，**不得以训练数据或他库经验代答**；须以当前仓库内**本次已读到的实现**为准。 +- 普通问答下钻源码并据此补答时，先按 **`f2s-knowledge-preflight`** 完成首读与缺口闸门，再按 **`f2s-kb-feedback-closing`** 完成最终知识库补充建议收口；只提示，不自动落盘。 + +## 知识库落盘文风（全局，写 stock-docs / topics / index 时适用） + +**肯定式优先**：表述正确信息时，直接说"是什么 / 在哪里 / 怎么做"，禁止用"不是 X / 非 X / 不再是 X"来传达——即使旧描述是错的，否定旧版也会让读者在脑中锚定错误前提。 + +- 错：`随包 import，非 window 注入` +- 对：`通过 import { <符号> } from '<包名>' 引入` + +**例外（应显式否定）**：A、B 两种做法在逻辑上均正确，但项目已做出**排他性选择**时，须写出「不用 B」——不说清楚，读者无法判断 B 是否仍可选。 + +## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时） + +各已初始化客户端在支持时使用自身的启动 / 更新机制，具体以生成的客户端入口为准。不提供 hooks 的客户端继续通过生成的 rules、skills、`AGENTS.md` 或 topics 镜像工作。版本检查脚本在客户端支持时完成版本比对并注入升级提示；项目级技能发现客户端通过 `flow2spec init dsh` 使用 `.dsh/skills/` 与 `.dsh/topics/`。 + +**规则层双保险**（与脚本缓存互为备份）： + +1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。 +3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON： + - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。 + - 无输出或解析失败：静默，不提示。 +4. 以上步骤出现任何错误，静默跳过，不影响正常对话。 + +## 主题创作（Topic Authoring）指针 + +新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。 + +## 禁止项 + +- **下发内容中性约束**：技能、规则、知识正文中的示例须**中性**——勿写特定业务域名称、单一组织 npm 包名、仅 Flow2Spec 产品仓存在的 `docs/` 路径；用 `<能力>`、`src/<模块>/` 等占位。 +- 使用 `git worktree` 或隔离目录跑子任务后，**禁止**在未 `git worktree remove` / 未交接删除命令的情况下结束会话（见上文「Git worktree 与子任务工作目录卫生」）。 +- 未查看 `.Knowledge/manifest-routing.json` 前，禁止进行全仓无范围扫描；`.Knowledge/index.md` 在需确认主题语义时再读，禁止与 manifest 交替重复读取以代替决策。 +- 禁止把 `stock-docs` 作为直接编码输入文档；按方案实现应使用 `req-docs`。 +- 禁止把 `fallbackTopic` 当作最终命中直接实施改动。 +- 禁止在不满足触发门槛时执行跨 matcher 全量补检索。 diff --git a/.dsh/topics/f2s-implement-tech-design.md b/.dsh/topics/f2s-implement-tech-design.md new file mode 100644 index 0000000..27943e2 --- /dev/null +++ b/.dsh/topics/f2s-implement-tech-design.md @@ -0,0 +1,140 @@ +> **任务路径**：凡 `.task/` 落盘与续作，**必须以 `rules/f2s-task` 解析的 `TASK_ROOT` 为准（`.task` 或 `.task/`；config → git → legacy）。下文若仍出现 `.task/todo.json` / `.task/active/`，均视为 **`TASK_ROOT/...` 的简写**。 + + +> **唯一长文**：本文件为 **implement-tech-design** 的完整执行条令。`.Knowledge/topics/f2s-implement-tech-design.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-implement-tech-design.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。 + +> 执行口径：统一知识库路径为 `/.Knowledge/`。下文所有路径均按 `.Knowledge` 约定解释。 + +# 基于技术方案实现交付物（通用） + +当用户要求根据**技术方案文档**实现可运行交付物时（用户会提供文档路径，如 `.Knowledge/req-docs/xxx.md` 或 PDF），按以下约定执行。 + +**目录约定**：`.Knowledge/req-docs/` 放“用于实现”的技术方案；`.Knowledge/stock-docs/` 放沉淀文档，不作为直接编码输入。 + +**触发说明**：本规则在打开 `req-docs` 下 `.md` 时自动加载（`**/req-docs/**/*.md`）。若对话前未打开技术方案，可在对话中 @ 本规则后再提供路径。 + +- 若用户提供的是 PDF：先执行 `f2s-doc-pdf`，将 PDF 转为 `.Knowledge/req-docs/` 下 MD，再继续。 +- 若用户提供的是 MD/文本：直接读取并进入实现流程。 + +--- + +## 一、目标与原则 + +- **目标**：基于技术方案实现可运行交付物，并与项目现有约定保持一致。交付物可以是前端页面/组件、后端接口/服务、数据处理逻辑、任务编排、脚本与配置等（按方案实际范围裁剪）。 +- **原则**： + 1. **先列任务再动手**：先输出「实现任务列表」，再提问与实现。 + 2. **先读后做**：先完整理解方案、边界、依赖、验收标准，再编码。 + 3. **对齐项目约定**：目录、命名、依赖、封装方式、错误处理与项目既有风格一致。 + 4. **缺项即问**：文档未明确的关键决策先向用户确认；未回复项进入待完成列表。 + 5. **实现后可执行**：必须给出验证方式与外部待办，确保用户可落地验收。 + +--- + +## 二、方案要素与实现映射（通用） + +| 技术方案内容 | 实现动作（按项目约定落地） | +| --- | --- | +| 需求目标 / 范围 / 非目标 | 明确本次实现边界，避免超范围开发。 | +| 关键流程 / 状态流转 / 时序 | 实现主流程与分支，关键判断处加简短注释。 | +| 数据结构 / 协议 / 字段约束 | 落地类型定义、模型、校验器或契约层。 | +| 接口 / 事件 / 消息 | 实现调用入口、事件处理、订阅或回调（按方案涉及项选择）。 | +| 页面 / 组件 / 交互 | 实现 UI 结构、状态管理、交互流程与容错提示（若方案涉及）。 | +| 配置 / 开关 / 环境差异 | 在项目约定位置注册并读取，补齐默认值和降级策略。 | +| 错误码 / 异常策略 / 重试 | 统一错误返回与日志策略，保持与现有封装一致。 | +| 发布 / 路由 / 权限 / 任务调度 | 实现对应代码并提醒用户完成平台侧配置（若方案涉及）。 | + +### 流程图处理（重要） + +- 若流程图是 PDF/图片且无文字步骤，先向用户索要文字版流程或补充文档； +- 若已有文字步骤，严格按顺序和分支实现； +- 无法确认分支时先提问，或按默认策略实现并写入待完成列表。 + +--- + +## 三、执行步骤 + +### 步骤 1：输入标准化 + +- PDF 输入：先执行 `f2s-doc-pdf`，得到 `.Knowledge/req-docs/*.md`。 +- MD/文本输入：直接读取。 + +### 步骤 2：理解方案与上下文 + +1. 读取技术方案全文，提取：目标、范围、流程、接口/交互、数据、配置、依赖、验收条件。 +2. 读取项目约定（如 README、`.Knowledge/stock-docs/`、架构说明、既有模块）以对齐实现风格。 +3. 若流程图缺文字说明，先记录缺口，进入步骤 3 一并向用户确认。 + +### 步骤 2.5：先输出实现任务列表（必做） + +在提问或编码前，必须先输出任务列表（可按方案裁剪）： + +```markdown +## 实现任务列表（基于《xxx》技术方案） + +| 序号 | 任务项 | 说明 | +| --- | --- | --- | +| 1 | 核心结构与数据契约 | 落地类型/模型/校验规则，明确输入输出。 | +| 2 | 业务流程实现 | 按流程图/文字步骤实现主链路与分支。 | +| 3 | 对外能力接入 | 接口/事件/页面交互等对外入口实现。 | +| 4 | 配置与异常处理 | 配置注册、错误处理、重试/降级策略。 | +| 5 | 验证与收尾 | 自测说明、待完成列表、平台侧提醒。 | +``` + +若 `changeTracking.implement: true`，在输出任务列表后，按 `f2s-task` 规则将本清单写入 `.task/active//task.md`。 + +### 步骤 2.6：变更追踪与 `task.md` / `user-todos.md` 同步（仅当 `changeTracking.implement: true`） + +- 每完成实现任务列表中一项对应工作，**同一会话内**用 `Edit` 更新 `.task/active//task.md` 中对应 `[ ]`→`[x]`，禁止积压到收尾、禁止口头完成代替写盘（见 `f2s-task`「执行中」「中断与会话结束」）。 +- 执行过程中每出现**须用户执行**的项（改库、配环境等），**同会话内**追加到 `.task/active//user-todos.md`（见 `f2s-task`「user-todos.md」）。 + +### 步骤 3：实现前提问（必做，不可跳过） + +进入编码前，必须一次性列出未明确项并请用户确认。常见问题： + +- **范围与验收**：本次必须交付什么，哪些明确不做； +- **技术边界**：实现在哪个模块/端（前端、后端、脚本、数据任务等）； +- **依赖与契约**：外部接口、消息协议、数据源、鉴权方式； +- **配置与环境**：配置 key、环境差异、默认值与灰度策略； +- **流程图缺口**：分支条件、失败回退、超时与重试策略； +- **发布约束**：路由、权限、调度、部署步骤是否已具备。 + +若用户未回复某项：按合理默认或占位实现，并在待完成列表中标注“需用户确认”。 + +### 步骤 4：按任务列表实现 + +按方案与项目实际裁剪顺序，建议： + +1. 先落地数据/契约与公共抽象； +2. 再实现主流程与核心能力； +3. 再接入入口层（接口/页面/事件/任务）； +4. 最后补齐配置、异常处理、日志与测试辅助。 + +要求：复用现有依赖与封装；与项目命名/目录/风格一致；关键分支要可读、可维护。 + +### 步骤 5：收尾输出（必做） + +1. **待完成列表（必须）**：列出所有待用户或平台补齐项； +2. **实现后提醒清单（必须）**：按实际涉及内容提醒配置、依赖、数据、发布、权限、调度等； +3. **验证建议（建议）**：给出最小可执行验证步骤（本地、测试环境或回归路径）。 +4. **用户代办落盘（仅当 `changeTracking.implement: true`）**：将步骤 5 第 1–2 点中**须用户亲自执行**的条目（改库脚本、配置、审批等）**同步追加**到 `.task/active//user-todos.md`（若尚无该文件则先创建，见 `f2s-task`）；禁止仅出现在对话或方案尾部的列表而不写入该文件。 +5. 若 `changeTracking.implement: true`：**先确认** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项），满足 `f2s-task` 归档门禁后，再将 `.task/active//` 移至 `.task/completed/-/`，并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时归档。 + +--- + +## 四、可选补充 + +- 若方案命名不明确，可先给出命名建议并请用户确认； +- 若方案跨度大，可按“最小可用版本 -> 增量迭代”拆分阶段交付； +- 若用户希望沉淀知识库，可提醒后续用 `f2s-kb-build` 同步主题与路由。 + +--- + +## 五、约束与小结 + +- PDF 必须先转 MD，再进入实现流程； +- 不得跳过步骤 2.5（任务列表）与步骤 3（实现前提问）直接编码； +- 若 `changeTracking.implement: true`：不得跳过步骤 2.6（随实现进度写回 `task.md` checkbox，并追加 `user-todos.md`）；归档须满足 `f2s-task` 归档门禁； +- 输出中必须包含待完成列表与实现后提醒清单；若 `changeTracking.implement: true`，其中用户侧项须同步写入 `user-todos.md`； +- 内容保持通用，不预设“仅后端”场景，按方案实际范围裁剪实现对象。 + +完成时可用一句话总结：已基于《xxx》技术方案完成本轮实现并给出待完成与验证建议，请按清单补齐平台与环境侧配置后验收。 diff --git a/.dsh/topics/f2s-intent-routing.md b/.dsh/topics/f2s-intent-routing.md new file mode 100644 index 0000000..c343435 --- /dev/null +++ b/.dsh/topics/f2s-intent-routing.md @@ -0,0 +1,85 @@ +# f2s 意图识别路由 + +## 前置 + +**执行本条前必须读 `flow2spec.config.json`**： + +- `intentRecognition: true` → 继续执行本条 +- `intentRecognition: false` 或字段不存在 → **跳过本条全部逻辑**，不做任何自动调用 + +## 优先级 + +1. 用户显式 `$f2s-*` 命令最高优先级，按显式命令执行。 +2. 用户明确说「只讨论 / 先别改 / 不要执行 / 先评估 / 先聊方案」时，禁止自动调用 Skill。 +3. 当前已进入某个 `f2s-*` 流程时，保持当前流程；不得自动切到其他流程，除非用户明确说「停止当前流程，改走 X」。 +4. **需求不完整禁自动进入撰写类技能**：用户要求改代码但需求不完整时，优先 `f2s-req-clarify`，不得直接进入 `f2s-kb-feat` / `f2s-kb-fix`；同理，用户要"出方案 / 生成技术方案"但需求含明显未决问题时，优先 `f2s-req-clarify`，**不得**直接进入 `f2s-req-tech`；用户要"拆任务 / 实现"但方案尚未落盘时，优先 `f2s-req-tech`，**不得**直接进入 `f2s-req-plan` / `implement-tech-design`。 +5. **过程编排型技能落盘后本轮不自动衔接下一技能（一处允许的单跳例外）**：`f2s-req-clarify` / `f2s-req-tech` / `f2s-req-plan` / `f2s-doc-*` 完成落盘后，**本轮**默认只输出"文档已就绪 + 下一步指引"一行提示即停止；**下一技能须由用户在新一轮明确触发**再由本条分流。**唯一允许的同轮单跳**：`f2s-req-clarify` 澄清文档落盘后直接自动衔接 `f2s-req-tech`（详见 `skills/f2s-req-clarify/SKILL.md` 结束段），此后不得再跳；`f2s-req-tech` 落盘后不得自动衔接 `f2s-req-plan` / `implement-tech-design`。 +6. 用户只是在询问、比较、评估、解释时，不调用 Skill。 +7. 低置信度或多意图冲突时，先用一句话说明候选分流并反问，不调用 Skill。 + +## 意图 → Skill 映射 + +用户输入**明确触发**以下操作意图，且不违反上文优先级时，Agent 可直接进入对应 Skill，不需要等用户二次确认： + +| 意图信号（示例） | 调用 Skill | +|----------------|-----------| +| 需求澄清、PRD 澄清、帮我理清需求、澄清一下 | `f2s-req-clarify` | +| 生成技术方案、出方案、技术设计 | `f2s-req-tech` | +| 提交代码、git commit、帮我提交、快捷提交 | `f2s-git-commit` | +| 新增能力、加功能、f2s-kb-feat | `f2s-kb-feat` | +| 修正实现规则、规则错了、f2s-kb-fix | `f2s-kb-fix` | +| 任务规划、创建任务 | `f2s-req-plan` | +| 知识库同步、全局同步、已实现能力同步 | `f2s-kb-sync` | +| 已有能力进知识库、多文件生成上下文 | `f2s-kb-add` | +| 新增规则、口述规则、把这条记到知识库 | `f2s-kb-addRules` | +| 生成项目上下文、终稿生成上下文 | `f2s-kb-build` | +| 合并上下文冲突、解决知识库冲突 | `f2s-kb-merge` | +| 知识库迁移、旧版迁移 | `f2s-kb-migrate` | +| 删除项目上下文 | `f2s-kb-rm` | +| 知识库模板升级、知识库升级、一键升级迁移 | `f2s-kb-upgrade` | +| 项目架构说明、架构初稿 | `f2s-doc-arch` | +| 转成终稿模版、f2s-doc-final | `f2s-doc-final` | +| 生成项目里程碑、里程碑 | `f2s-doc-milestone` | +| PDF 转 MD| `f2s-doc-pdf` | + +## 判断边界 + +**调用**：用户明确发起操作意图，且置信度高。 + +- "帮我做需求澄清" → 调用 `f2s-req-clarify` +- "生成一份技术方案" → 调用 `f2s-req-tech` +- "修复这个 bug，表现是 X，期望是 Y" → 调用 `f2s-kb-fix` +- "新增这个配置开关，默认 false，影响范围是 X" → 调用 `f2s-kb-feat` + +**不调用**：用户在询问或讨论，而非发起操作。 + +- "这个需求需要澄清吗？" → 先回答问题 +- "技术方案一般怎么写？" → 先回答问题 +- "f2s-req-tech 是干什么的？" → 先回答问题 +- "我们讨论一下这个能力怎么做" → 先讨论，不进入实现 +- "我想加一个能力，但还没想清楚" → 走澄清或反问，不进入 feat + +**判断依据**：有无明确的「帮我做 X」「执行 X」「开始 X」等动作性语义；仅询问、讨论、评估不触发。 + +## 分流说明 + +自动进入 Skill 前，先用一句话说明分流原因： + +```text +我按 处理：<一句话原因>。 +``` + +低置信度时只输出候选与反问： + +```text +这可能是 或 ，当前缺 <关键信息>，先确认后再进入流程。 +``` + +## 禁止项 + +- 在 `intentRecognition` 未读取或为 `false` 时自动调用任何 Skill +- 把询问类输入误判为操作意图 +- 在需求澄清未结束时自动跳到 feat/fix/plan/tech +- 在技术方案未落盘时自动跳到 `f2s-req-plan` / `implement-tech-design` +- 在过程编排型技能（`f2s-req-clarify` / `f2s-req-tech` / `f2s-req-plan` / `f2s-doc-*`）落盘的**同一轮**内自动衔接下一 `f2s-*` 技能（**唯一例外**：`f2s-req-clarify` → `f2s-req-tech` 单跳；`f2s-req-tech` 落盘后不得再自动衔接） +- 在当前流程未结束时自动切换到另一个 Skill diff --git a/.dsh/topics/f2s-karpathy-guidelines.md b/.dsh/topics/f2s-karpathy-guidelines.md new file mode 100644 index 0000000..bdf5667 --- /dev/null +++ b/.dsh/topics/f2s-karpathy-guidelines.md @@ -0,0 +1,72 @@ +# Karpathy 式编码行为准则 + +> 与项目内 Flow2Spec / `f2s-*` 规则**并行**；若某条与 f2s 强制步骤冲突，**以 f2s 与项目约定为准**。 + +用于减少常见「模型写代码」失误的行为约定。 + +**取舍：** 这些准则偏向**稳妥而非一味求快**；对明显琐碎的修改（如单行笔误）可自行把握，不必条条刻板执行。 + +## 1. 先想清楚再写代码 + +**不要默认、不要藏困惑、把权衡摆到台面上。** + +动手实现前： + +- **假设要说清楚**；不确定就问，不要猜。 +- **有多种理解时并列说明**，不要悄悄选一种就跑。 +- **若有更简单做法**，主动提出；该反对时要反对。 +- **说不清就停**：点名哪里困惑，再向用户要信息。 + +## 2. 简单优先 + +**用最少代码解决问题，不做臆测性扩展。** + +- 不要超出需求加功能。 +- 不要为只用一次的代码抽抽象。 +- 不要加未被要求的「灵活性」「可配置」。 +- 不要为几乎不可能的场景堆错误处理。 +- 若写了 200 行其实 50 行就够，**重写**。 + +自问：「资深工程师会不会觉得过度设计？」若是，就简化。 + +## 3. 手术式修改 + +**只动该动的；只收拾自己弄乱的。** + +改已有代码时： + +- 不要顺手「优化」相邻代码、注释或格式。 +- 不要重构没坏的东西。 +- **风格对齐现有代码**，即使你个人偏好不同。 +- 若发现与任务无关的死代码，**可以提一嘴，不要擅自删**。 + +若你的改动产生了孤儿引用/变量： + +- **删掉因你这次改动而不再使用的** import、变量、函数。 +- **不要**在用户未要求时删除**原本就存在**的死代码。 + +检验标准：**每一行改动都能追溯到用户的明确诉求。** + +## 4. 目标驱动执行 + +**先定义成功标准，再循环直到可验证地达成。** + +把任务变成可验证目标，例如： + +- 「加校验」→「先写非法入参测试，再改到通过」 +- 「修 bug」→「先写能复现的测试，再改到通过」 +- 「重构 X」→「前后测试套件均通过」 + +多步骤任务可写简短计划： + +``` +1. [步骤] → 验证：[检查方式] +2. [步骤] → 验证：[检查方式] +3. [步骤] → 验证：[检查方式] +``` + +成功标准越具体，越能独立迭代；含糊的「跑通就行」会逼出反复追问。 + +--- + +**准则在起作用的信号：** diff 里无关改动变少、因过度设计返工变少、**澄清问题出现在实现之前**而不是做错之后。 diff --git a/.dsh/topics/f2s-kb-feedback-closing.md b/.dsh/topics/f2s-kb-feedback-closing.md new file mode 100644 index 0000000..64065cd --- /dev/null +++ b/.dsh/topics/f2s-kb-feedback-closing.md @@ -0,0 +1,112 @@ +# Flow2Spec 知识库反馈收口 + +本条专管普通问答读取业务源码后的知识库补充建议。只决定最终回答是否需要追加一条极简提示。 + +## 适用范围 + +仅当同时满足以下条件时执行： + +- 本轮是**普通问答 / 排查 / 解释**； +- 本轮**未进入** `f2s-*` 技能、`implement-tech-design`、`f2s-git-commit` 或其他已有后续流程； +- 本轮读取过业务源码，且最终答案引用了源码事实。 + +**禁止**：以下两类情形不得输出本规则 case 1～4 中**任何一个**收口块—— + +1. **本轮已进入 `f2s-kb-distill`**：`f2s-kb-distill` 本身就是把本轮知识入库的技能，再贴自己的入库提示既冗余又自指。 +2. **本轮进入过程编排型技能**：`f2s-req-clarify` / `f2s-req-tech` / `f2s-req-plan` / `f2s-doc-arch` / `f2s-doc-final` / `f2s-doc-milestone` / `f2s-doc-pdf`。这些技能的产物是**面向本次交付的 `.Knowledge/req-docs/*`、`docs/*` 或任务规划物**，读源码是为了产出这些产物本身，不是"顺手补一条通用知识"。哪怕读了源码并将事实写进了澄清 / 方案 / 规划文档，也**不追加** distill 提示（澄清 / 方案文档本身归 `req-docs`，不是 `topics` / `stock-docs` 的入库对象；规划物随任务归档；文档类技能已有各自的落盘目标）。 + +其他 `f2s-kb-*` 技能（如 `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` 等）跑完之后**仍按四 case 正常判定**：若本轮回答里包含**主路径之外**、本次 SKILL **未入库**的可复用知识事实（典型场景：修 bug 时顺带读了另一模块源码、回答了与本次 SKILL 主体无关的衍生追问），照常输出收口块；agent 据本轮实际写入情况判断，不一刀切。 + +## 判断时机与依据 + +**判断时机**：在生成最终回答后，基于回答实际包含的知识内容判断，而非读取过程。 + +**判断依据**： +- 最终回答中补充了哪些 KB 未写或不够细的知识 +- 这些知识是否属于"可复用知识事实" +- 而非：读取过程中接触到的所有文件/信息 + +**可复用知识事实**包括： +- 核心机制（如：缓存语义、重试策略、降级逻辑） +- 状态流转（如：订单状态机、会话生命周期） +- 返回值 / 错误码契约（如：HTTP 状态码语义、业务错误码含义） +- 配置开关影响（如：开关 X 影响行为 Y） +- 失败回退策略（如：主路径失败时的降级方案） +- 模块边界或调用约定（如：模块 A 调用模块 B 的契约） +- 数据模型与字段语义（如：关键字段的业务含义） + +**仅作证据，不触发同步**的包括： +- 行号（如：`client.py:51`） +- 函数名（如：`send_message_to_session()`） +- 代码片段（用于演示的具体实现代码） +- 调用路径（如：`A → B → C` 的调用链） +- 为了回答用户追问而展开的局部实现 +- 对 topic 已写事实做源码核验（KB 已写清楚，源码只是印证） + +## 机械门禁 + +- 读完首个业务源码文件后，视为本轮已触发 `sourceFallbackUsed=true`。 +- `sourceFallbackUsed=true` 且最终答案引用源码事实时，发出回答前必须执行本条四 case 自检。 +- **四 case 必须显式表态**：每轮收口必须从 case 1～4 中选一个**明确输出对应块**，不允许悄悄跳过整个收口流程。 +- 判定逻辑： + - topic 命中 + 最终回答补充了"可复用知识事实" → 走 **case 2** + - topic 未命中 + 最终回答补充了"可复用知识事实" → 走 **case 1** + - topic 命中 + 最终回答仅包含"证据性内容"（行号/函数名/调用路径） + KB 已写清核心事实 → 走 **case 4** + - 若下钻前说明的是**机制/契约/流程类知识缺口**，答后走 **case 2** + - 若下钻前说明的只是**证据/源码位置/行号/实现出处缺口**，且 topic 已覆盖核心事实，可走 **case 4** + +## 四种收口 + +1. **KB 未覆盖 + 源码找到答案**：在答案末尾追加： + ```md + > 💡 可用 `f2s-kb-distill` 将本轮知识入库 + > + > **本轮将入库**：<一句话概要，点名「是什么能力 / 哪个模块 / 哪类知识」，例如：模块 X 的重试机制（首次入库）> + ``` + **判定条件**：没有 topic 覆盖该能力 / 模块 / 问题域，且最终回答补充了可复用知识事实。 + +2. **KB 已覆盖但不够细 + 源码补齐答案**：在答案末尾追加： + ```md + > 💡 可用 `f2s-kb-distill` 将本轮知识入库 + > + > **本轮将入库**：<一句话概要，点名「补到哪个 topic 的哪段」，例如:补充 `` 的「失败回退逻辑」一节> + ``` + **判定条件**：已有 topic 覆盖方向但缺少细节，且最终回答补充了可复用知识事实（核心机制、状态流转、契约等）。 + +3. **KB 与源码不一致**：以源码事实回答，并在答案末尾追加： + ```md + > 💡 可用 `f2s-kb-distill` 将本轮知识入库 + > + > **本轮将入库**：<一句话概要，点名「修正 `` 的哪条与源码不符的描述」> + ``` + +4. **KB 已完整覆盖，源码仅核验**：在答案末尾追加： + ```md + > **知识库已覆盖**：本轮答案核心事实已由 `` 完整提供，源码读取仅作核验。 + ``` + **判定条件**： + - KB 相关 topic 已写明本问题核心答案（机制、流转、契约等可复用知识事实） + - 本轮最终回答未引入 KB 之外的新的可复用知识事实 + - 回答中引用源码仅作为证据（行号、函数名、调用路径）或核验 KB 已写内容 + - 若下钻前说明缺口时提到的是机制/契约/流程类知识缺口，禁止走 case 4 + +> **概要要求（case 1~3 必填）**：必须一句话写明"这次跑 distill 会把什么入库"——能力 / 模块名 + 知识类型（机制 / 流转 / 契约 / 配置等）+ 是首次入库还是补充某 topic。**禁止**只贴命令不写概要；用户看了概要才能判断要不要接着跑 distill。 + +## case 1 和 case 2 的边界 + +- **case 1**（`f2s-kb-distill` 未覆盖场景）：没有 topic 覆盖该能力 / 模块 / 问题域 + - 示例：用户问"模块 X 的重试机制"，但 manifest 中没有任何 topic 与模块 X 相关 + - 示例：用户问"新功能 Y 的实现"，KB 中完全没有功能 Y 的文档或 topic + +- **case 2**（`f2s-kb-distill` 补充场景）：已有 topic 覆盖方向，但缺少细节 + - 示例：topic 写了"缓存优先策略"，但没写具体的失败回退逻辑 + - 示例：topic 写了"动作链判定"，但没写具体的状态检查方式 + +这样能避免"已有 topic 还建议 add"的误判。 + +## 输出格式 + +- case 1～3：输出一个 Markdown 引用块，依次写 `f2s-kb-distill` 命令 + 一行空行 + **本轮将入库**概要（一句话，见上文「概要要求」）。 +- case 4：输出一个 Markdown 引用块，标明"知识库已覆盖"+ 关联 topicId。 +- 禁止省略本块；禁止输出已读 KB 路径列表、覆盖对照表、原因解释或多行背景。 +- 只提示，不自动执行 `f2s-kb-distill`。 diff --git a/.dsh/topics/f2s-knowledge-preflight.md b/.dsh/topics/f2s-knowledge-preflight.md new file mode 100644 index 0000000..4b85a3c --- /dev/null +++ b/.dsh/topics/f2s-knowledge-preflight.md @@ -0,0 +1,67 @@ +# Flow2Spec 知识库首读（KB Preflight） + +本条与 `f2s-flow2spec-unified-entry` **并存**；凡涉及**当前仓库**内实现、配置、排错与 Flow2Spec 知识路由的回答，**以本条约束「何时必须先读磁盘上的知识库」为准**。统一入口中的读取顺序在**满足本条之后**继续适用。 + +## 适用范围（须执行首读） + +用户问题若可能依赖下列任一类信息，即视为「须先走知识库」： + +- 当前仓库中的**实现代码**、目录与模块约定、构建/部署/运行时行为、`.Knowledge/`、`f2s-*` 技能、`manifest-routing` 所描述的主题路由等； +- 用户未明确声明「与当前仓库无关」、但语境明显依赖本仓库事实时。 + +## 硬约束：首工具调用 + +在给出实质性结论或修改建议之前： + +1. **在本轮用户消息下**，若尚未用工具读取过 **`.Knowledge/manifest-routing.json`**，则 **第一个** 使用的代码/知识库类工具 **必须** 为： + + `Read` → 路径 **`.Knowledge/manifest-routing.json`**（项目根相对路径，与统一入口一致）。 + +2. 读完 manifest 后，再按 `taskToTopicRules` / `matcherPath` **按需** `Read` **单个** matcher 分片与 **`.Knowledge/topics/.md`**（及 `topicDependencies`），然后才允许对 **除 `.Knowledge/` 以外的业务源码路径** 使用 `SemanticSearch`、`Grep` 或 `Read`。 + +3. **禁止**：在未执行步骤 1 的情况下，用「凭记忆/凭训练数据」直接断言本仓库特有的路径、配置或行为；若 manifest 或 topic 已明确覆盖，**须以 KB 为准**，源码用于印证或补全 KB 未写细节。 + +4. **回答末尾（简短一行即可）**：注明本轮依据的 KB 路径（例如「已读 manifest + `topics/.md`」）；若 manifest 无命中且已读 `fallbackTopic` 对应 topic，写明「走 fallback 分诊」。 + +## 可跳过首读（极少数） + +- 用户仅询问 **IDE/编辑器本身**用法、且与当前仓库目录无关； +- 用户给出 **绝对路径 + 明确指令**（例如「只把该行改为 x」）且与业务知识无关的纯机械编辑； +- **同一会话内**已对当前工作区执行过 `Read(".Knowledge/manifest-routing.json")` 且用户未要求「重新路由/全量检查」的**直接续问**：可在回答首句写「manifest 已读本会话，沿用上次路由」，**不再重复 Read** manifest。 + +## 回答收口检查（源码补答后） + +普通问答读取业务源码后的知识库补充建议，以 **`f2s-kb-feedback-closing`** 为单一规则源。本条只保留触发关系：读完首个业务源码文件后，视为本轮已触发 `sourceFallbackUsed=true`；若最终答案引用源码事实，发出回答前必须执行 `f2s-kb-feedback-closing` 的四 case 自检。若本轮已经进入 `f2s-*` 技能、`implement-tech-design`、`f2s-git-commit` 或其他已有后续流程，不重复提示。 + +与 **`f2s-flow2spec-unified-entry`** 中 **「知识缺口与对策」** 一致；命中 **1b（命中但上下文不够）** 或 **2（库里没有对应文档）** 时，还须遵守： + +1. **先对用户说明，再扩工具**：在已读 `manifest-routing.json` 与应读的 `topics/*.md`（及依赖 topic）之后，若仍**无法仅凭 KB** 精确回答用户问题，**必须先**用自然语言说明：**已读哪些 KB 路径**、**仍缺哪类信息**、**你打算只读哪 1～2 个源码文件**或**请用户补哪篇文档**；不得沉默地连续堆叠「再找入口」式探索。 +2. **探索次数上限**：在未向用户发出上述缺口说明前，**禁止**连续发起 **4 次及以上**仅以扩大搜索面为目的的 `Grep` / 无明确目标的 `SemanticSearch`。说明并获用户默许（或问题明确要求追到底）后，再有序下钻。 +3. **单点下钻优先**：若仅需确认行为细节，应优先 **Read 一个**与问题最相关的实现文件并据此作答；**禁止**为同一子问题在无新假设的情况下链式深入第三方依赖目录中多文件，除非用户明确要求通读依赖。 + +### 缺口闸门（针对「规则有写、执行跳过」） + +当且仅当已读完 **manifest + 应读 topics** 后，仍判定为 **1b / 2**、且**下一步**要使用指向**业务源码树**（非 `.Knowledge/`）的 `Read` / `Grep` / `SemanticSearch` 时： + +- **必须先**产出一段**终端用户可见**的自然语言（可与简短结论同屏），且至少包含：**(a)** 已读的 KB 路径；**(b)** 缺口一句（topic 缺哪类信息或库中无文档）；**(c)** 拟打开的 **1～2 个具体文件路径**或征询用户是否先补 `req-docs`/stock-docs。 +- **禁止**在**从未**输出过满足 (a)(b)(c) 的可见说明的情况下，连续发起多轮仅用于「再找入口」的源码侧工具调用（此即「规则已写但未先做缺口说明」的执行层遗漏）。 +- 下钻后给出**行为、状态码、错误文案**等事实时，**须以本次实际读到的源码与契约为准**；不得凭推测或与当前仓库无关的外部项目经验填写。 + +上述 (a)(b)(c) 与 **`f2s-flow2spec-unified-entry`** 表中「向用户要文档或路径」「明确承认知识库无覆盖」**同一语义**：不得用「已在内心判定为 1b」代替**已对用户写出**的缺口说明。 + +### 与执行环境的交互（权限、确认类噪音） + +在带沙箱或权限门控的 IDE 中，**短时间连续**发起多轮 `Grep` / `SemanticSearch` / 大范围读盘，常表现为**对同类权限或确认的重复询问**。这与 Flow2Spec 规则是否写明无直接关系，多由**探索链过长、无停止条件**放大。遵守本节「缺口闸门」「探索次数上限」与下文「检索体积与作答节奏」、优先单文件 `Read`，可显著减少此类打扰。 + +## 检索体积与作答节奏（降低多轮扫描、体感变慢） + +本节针对 **Codex / 终端 IDE** 等环境中「一次问答多轮 `grep`、输出量巨大、总耗时长」的常见根因，与「首读 manifest」**不冲突**：仍须先 `Read` manifest，再收窄搜索面。 + +1. **`Grep` / 文本搜索范围**：在已读命中 topic 且其中给出**具体文件或目录路径**时，搜索**不得**大于该路径；无路径时再缩到**单一**最可能目录（如 `src/utils/` 或 `src/functions/<活动目录>/`）。**禁止**在无用户明确要求「全仓检查」且未满足统一入口「全量补检索触发门槛」时，对 **`src/` 根、`src/functions` 全域、`.Knowledge` 等多处并列**做一次超大范围扫描。 +2. **大命中量时**：若单次搜索命中行数明显过多，应**停止扩大关键词或路径**，改为优先 **`Read` topic 或 stock-docs 已点名的 1～2 个主文件**；仍不足再缩小模式或目录做**第二次**窄 `Grep`。 +3. **两阶段作答**：用户未明确要求「列出全部实现细节 / 通读依赖 / 审计全链路」时，在 manifest + 应读 topics（及 stock/req 中 topic 已指明的材料）已足以形成结论时，**可先输出对用户有用的短答案**；实现细节、额外文件清单仅在用户追问依据或「展开」时再下钻，**禁止**仅为自验完备而拉长探索链。 +4. **避免重复读盘**：本会话内已对某文件做过**全文** `Read` 且无新用户指令或新假设时，**禁止**再次对该文件发起等价全文 `Read`。 + +## 对 Agent 自检 + +若你发现自己在回答当前仓库相关问题时尚未 `Read` manifest，**须立即停止补写**，先 `Read` manifest 与命中 topic，再更正或续答。若本轮读取过业务源码并引用源码事实，发出回答前须继续执行 `f2s-kb-feedback-closing`。 diff --git a/.dsh/topics/f2s-stock-docs-vs-req-docs.md b/.dsh/topics/f2s-stock-docs-vs-req-docs.md new file mode 100644 index 0000000..e149506 --- /dev/null +++ b/.dsh/topics/f2s-stock-docs-vs-req-docs.md @@ -0,0 +1,8 @@ +> **唯一长文**：本文件为 **f2s-doc-routing** 的完整约定。`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-stock-docs-vs-req-docs.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。 + +# stock-docs 与 req-docs + +- **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-kb-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-kb-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。 +- **`.Knowledge/req-docs/`**：需求澄清、技术方案（前后端/数据/任务等）、`f2s-doc-pdf` 输出的「按方案实现」MD；`implement-tech-design` 的触发范围为 `.Knowledge/req-docs/**/*.md`。 + +完整约定见本规则与 **`skills/f2s-doc-routing/SKILL.md`**；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。 diff --git a/.dsh/topics/f2s-task.md b/.dsh/topics/f2s-task.md new file mode 100644 index 0000000..dc7a1da --- /dev/null +++ b/.dsh/topics/f2s-task.md @@ -0,0 +1,298 @@ +# f2s-task（变更追踪规则） + +## 生效条件 + +各技能按自身子项判断： + +- `f2s-kb-feat`：读 `changeTracking.feat` +- `f2s-kb-fix`：读 `changeTracking.fix` +- `f2s-implement-tech-design`：读 `changeTracking.implement` + +若对应子项为 `false` 或字段不存在，**该技能内的变更追踪步骤不执行**，直接跳过。 + +> `f2s-req-plan` 命令不受此条件约束，始终执行（见 `skills/f2s-req-plan/SKILL.md`）。 + +## 多人协作与任务根 `TASK_ROOT`（必须先解析） + +进入本规则任何「读/写 `.task`」步骤前，**必须** `Read("flow2spec.config.json")`，并解析 **`TASK_ROOT`**（本会话内固定，禁止中途改 id）： + +| 条件 | `TASK_ROOT` | `developerId` 来源 | +| --- | --- | --- | +| `collaboration.enabled === false` | `.task` | legacy（强制单人根） | +| `collaboration.developerId` 非空（trim 后） | `.task/` | **config** | +| 否则能读到 `git config user.email` | `.task/` | **git-email** | +| 否则能读到 `git config user.name` | `.task/` | **git-name** | +| 仍无 | `.task` | **legacy**（单人旧布局；须在回复中提示：建议配置 `collaboration.developerId`） | + +**sanitize**：小写；若含 `@` 只取本地部分；非 `[a-z0-9]` 收成 `-`；去首尾 `-`；长度 1–64，否则视为无 id。 + +**路径一律用 `TASK_ROOT` 前缀**（下面凡写 `TASK_ROOT/...` 均指解析结果）： + +- 索引：`TASK_ROOT/todo.json` +- 进行中：`TASK_ROOT/active//` +- 已完成：`TASK_ROOT/completed/-/` + +**防串戏（硬约束）**： + +1. **只**读写当前会话的 `TASK_ROOT`；**禁止**为续作/匹配去遍历 `.task/*/todo.json` 或其他 developer 目录。 +2. keywords 匹配范围 **仅** 当前 `TASK_ROOT/todo.json` 内条目。 +3. 创建任务时 `todo.json` 的 `folder` 必须写成当前 `TASK_ROOT/active//`（posix 相对路径）。 +4. 可选在任务开始时向用户回显一行：`[task] developerId= TASK_ROOT=`。 +5. **`.Knowledge/` 仍为全员共享**；本规则不按人拆分知识库。 + +> 实现参考（CLI/工具）：包内 `lib/developerId.js` 的 `resolveDeveloperContext` / `taskRootFor`（与上表同口径）。 + +## f2s-req-plan 调用时的绑定 + +执行 **`f2s-req-plan`**（或续作命中 `linkedSkill: "f2s-req-plan"`）时： + +- **不受** `changeTracking.feat` / `fix` / `implement` 限制，但 **必须** 按本规则「任务开始 / 执行中 / 中断与会话结束 / 任务完成 / 新会话续作」维护 **`TASK_ROOT`** 下任务树； +- 技能 **步骤 0** 须 `Read` 本规则全文（**Cursor/Claude**：`rules/f2s-task.*`；**Codex**：`.codex/topics/f2s-task.md`）； +- 落盘、打钩、归档、`user-todos.md` / `acceptance.md` 格式 **以本规则为准**；技能正文不得省略 `todo.json` / `user-todos.md` / `acceptance.md`，不得改写归档目录命名（`-`）。 + +## 目录结构 + +``` +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 ← 随任务一并归档，便于用户最终核对 +``` + +**归档目录命名**：`completed/` 下文件夹名为 **`-`**（**本地日历日期 8 位在前**，`` 与 `active/` 下一致、为 snake_case；便于按时间排序）。**新归档一律使用本格式**；仓库中已有的旧式 `-` 目录可保留，择机人工重命名即可。 + +**从单人布局迁移**：若磁盘仍有根级 `.task/active/` 与 `.task/todo.json`，而当前已解析出非 legacy 的 `TASK_ROOT=.task/`，可在用户确认后将旧 `active/*` 与条目迁入新根（一次性）；未确认前 **不要** 自动挪动他人可能共用的根目录。 + +## todo.json 结构 + +```json +[ + { + "name": "任务名称", + "folder": "TASK_ROOT/active//", + "keywords": ["关键词1", "关键词2"], + "linkedSkill": "f2s-kb-fix", + "createdAt": "YYYY-MM-DD", + "assignee": "" + } +] +``` + +`folder` 落盘时须写成真实相对路径（例如 `.task/alice/active/fix_foo/` 或 legacy 的 `.task/active/fix_foo/`）。`assignee` 建议写入当前 `developerId`（legacy 可写 `"legacy"` 或省略）。 + +**写权约束**：`todo.json` 仅由主 agent 写，禁止子 agent 修改。 + +## 任务开始（代码变更前） + +0. 按上文解析并固定 **`TASK_ROOT`**（及 developerId / legacy）。 +1. 检查 `TASK_ROOT/todo.json` 是否存在活跃任务。 +2. 将用户输入与**该文件内**各条目 `keywords` 匹配（**禁止**读取其他 `TASK_ROOT`）： + - 命中一个 → 加载对应 `task.md`、`context.md`，**若存在** `user-todos.md` 则一并加载，展示剩余清单与未消用户代办 + - 命中多个 → 列出候选，让用户选择 + - 无命中 → 确认任务名称后创建新任务 +3. 创建新任务（无命中时）： + a. 确认任务名称（snake_case，简短描述变更内容） + b. 在 `TASK_ROOT/active//` 创建文件夹 + c. 将本次工作步骤写入 `task.md` + d. 将涉及文件路径和相关资料链接写入 `context.md` + e. **创建 `user-todos.md`**（固定文件名，与 `task.md` 同目录）：见下文「`user-todos.md` 格式与写盘义务」；尚无代办时可写入占位说明 + f. 在 `TASK_ROOT/todo.json` 新增条目（仅主 agent 写；`folder` 指向本任务目录） + +## 执行中 + +- 每完成一个步骤，**立即**用 `Edit` / `Write` 将 `task.md` 中对应 checkbox 由 `[ ]` 改为 `[x]`（与代码改动同等对待，**禁止**仅靠会话内口头宣称「已完成」代替磁盘更新） +- 禁止批量勾选或跳步 +- **用户代办须落盘**：凡须任务责任人（用户）在本机、数据库、配置平台或流程上完成的项（例如执行 DDL/DML、填密钥、点审批、发版、补数据），**同一会话内**追加写入 `user-todos.md`（`Edit` 追加小节或列表项），**禁止**仅在对话里交代而不写入该文件；可与对话摘要并存，以磁盘文件为交接真值 + +## 中断与会话结束（硬约束） + +- **长记忆以 `task.md` 的 checkbox 为真值**：下一会话通过「首个仍为 `[ ]` 的步骤」定位进度；未写盘则续作失真。 +- 本会话内每真实完成 `task.md` 所列一步：**当步**打钩，不得积压到归档前一次性勾选。 +- 若用户结束对话、工具流中断、或预计无法继续：在结束前至少打钩**已真实完成**的步骤，并在「## 备注」写明阻塞原因或「下一会话从步骤 N 继续」；**禁止**在未更新 `task.md` 的情况下直接结束（否则等同丢失进度信号）。 +- 中断前若本会话已识别出**用户代办**：**必须**写入或追加到 `user-todos.md`，避免下一会话丢失「交给用户的事」。 +- 若本会话为子任务创建过 **`git worktree`** 或等价隔离目录：结束前按 **`f2s-flow2spec-unified-entry`**「Git worktree 与子任务工作目录卫生」完成移除或写明残留路径与删除命令（必要时写入 `user-todos.md`）。 + +## 任务完成 + +**归档门禁（须先于移动目录自检）**： + +- 将目录移入 `completed/` **当且仅当** `task.md` 的「## 步骤」下，与本次交付相关的条目**全部为 `[x]`**（或用户明确取消的项已在「## 备注」说明，且对应列表项已改为 `[x]` / 已删除该项并注明取消）。 +- `task.md` 全部 `[x]` 后、移动目录前，**必须**已生成或更新 `acceptance.md`（见下文「acceptance.md 格式与写盘义务」）；缺失 `acceptance.md` 或仍为创建任务时的占位说明 → 视为门禁未过，禁止归档。 +- 若仍存在 `[ ]`：**禁止**移动 `active` → `completed/`、**禁止**从 `todo.json` 删除该条目；应先回到「执行中」补完或改清单后再归档。 + +完成上述门禁后： + +1. 将 `TASK_ROOT/active//` 整体移至 `TASK_ROOT/completed/-/` +2. 从 `TASK_ROOT/todo.json` 删除该条目 +3. 若 `todo.json` 变为空数组，删除该文件 + +## 新会话续作 + +新会话开始时，先解析 **`TASK_ROOT`**；若存在 `TASK_ROOT/todo.json`： + +1. **仅**读取该文件中的活跃任务（禁止合并其他 developer 的 todo） +2. 将用户首条消息与各条目 `keywords` 匹配 +3. 命中则展示剩余 checklist，**若存在 `user-todos.md` 则摘要其中仍为 `- [ ]` 的用户代办**；**若存在 `acceptance.md` 则提示其当前形态**（占位 / 已成稿；归档前必须成稿）；提示「检测到未完成任务，是否继续？」 +4. 用户确认后：**若 `linkedSkill` 非空，先加载对应技能规则文件（配置根 `skills//SKILL.md`）作为执行上下文**，再按 `task.md` 剩余步骤继续——技能的落盘约束、文风规则、自检清单全部生效，与首次调用一致 +5. 无命中则不打扰，正常响应 + +**孤儿 `active/`（`todo.json` 缺失或损坏）**：若**当前 `TASK_ROOT`** 下仍存在 `active//` 且其中 `task.md` 含未勾选步骤，应 `Read` 该 `task.md` 并提示用户是否续作；续作前宜按「任务开始」一节恢复或补写 `todo.json`（仅主 agent）。**禁止**扫描其他 `.task//active/` 当作孤儿续作。 + +## task.md 格式 + +```markdown +# <任务名> + +## 步骤 +- [ ] 步骤1 +- [ ] 步骤2 +- [x] 步骤3（已完成） + +## 备注 +<执行中的发现、决策等> +``` + +## context.md 格式 + +```markdown +# <任务名> 上下文 + +## 涉及文件 +- `src/<模块>/callback.js` +- `src/<模块>/retry.js` + +## 相关资料 +- `.Knowledge/req-docs/<能力>-spec.md` +- `.Knowledge/stock-docs/<能力>-arch.md` + +## 用户代办清单 +- 见同目录 `user-todos.md`（须用户执行的项统一写在该文件，勿仅在对话中罗列） + +## 验收 +- 见同目录 `acceptance.md`（task.md 全部 `[x]` 后、归档前生成） +``` + +## user-todos.md 格式与写盘义务 + +**路径**：`TASK_ROOT/active//user-todos.md`（归档后位于 `TASK_ROOT/completed/-/user-todos.md`）。**固定文件名** `user-todos.md`，便于 Hook 与脚本引用。 + +**用途**：汇总 **Agent 无法代劳**、必须由用户（或持权人在平台）完成的项，例如： + +- 在指定环境执行 SQL / 迁移脚本（可引用 `req-docs` 或仓库内 `.sql` 路径） +- 配置中心 / 环境变量 / 密钥 / 白名单 +- 发布、审批、工单、外部系统开关 + +**写盘义务**： + +1. **创建任务时**（`f2s-task`「任务开始」步骤 3.e）：创建该文件；可含简短说明 + 空列表。 +2. **执行中**：每出现一类新的用户代办，**当次**追加（推荐按日期分二级标题 `## YYYY-MM-DD`，下列 `- [ ]` 可勾选项或步骤编号）。 +3. **与 `task.md` 分工**：`task.md` 管 Agent 侧步骤 checkbox；`user-todos.md` 管用户侧待办；**勿**把「仅用户可执行」的长操作说明只写在 `task.md` 步骤正文代替本文件。 +4. **续作**：加载任务时 `Read` 本文件，向用户展示仍未勾选的 `- [ ]` 项（若有）。 + +**示例结构**： + +```markdown +# 用户代办清单 + +> Agent 追加；用户完成后可将对应 `- [ ]` 改为 `- [x]` 或删除该行。 + +## 2026-05-09 + +- [ ] 在目标环境执行：`.Knowledge/req-docs/xxx.sql`（先备份） +- [ ] 在配置中心打开功能开关 `feature.foo.enabled` + +## 2026-05-10 + +- [ ] 生产发版后回写实际版本号到本文档备注 +``` + +## acceptance.md 格式与写盘义务 + +**路径**：`TASK_ROOT/active//acceptance.md`（归档后位于 `TASK_ROOT/completed/-/acceptance.md`）。**固定文件名** `acceptance.md`，与 `task.md` / `user-todos.md` 同目录。 + +**用途**：Agent 在 `task.md` 全部 `[x]` 后、归档前，依据本次实际交付沉淀的**验收清单**：用户照单逐项核对就能确认「这次任务真的做完了」。与 `user-todos.md` **职责分离**： + +| 文件 | 谁在做 | 内容焦点 | +| --- | --- | --- | +| `task.md` | Agent | 实现步骤的进度 checkbox | +| `user-todos.md` | 用户 | **代办**：Agent 做不了、必须用户在外部（库 / 平台 / 审批）执行的事 | +| `acceptance.md` | 用户 | **验收**：本轮 Agent 已交付项，用户核对是否真的可用 | + +**生效范围**：凡使用 `.task/` 的任务均生成（自动模式 `changeTracking.feat` / `fix` / `implement` 命中、以及显式模式 `f2s-req-plan`）；不区分技能。 + +**写盘义务**： + +1. **创建任务时**（`f2s-task`「任务开始」步骤 3.e 之后）：**可同时创建** `acceptance.md` 并写占位说明（如「task.md 全部 `[x]` 后由 Agent 在此填入验收清单」）；尚未实现时**不得**预先写入验收点，避免与最终交付脱节。 +2. **执行中**：原则上**不写**；若交付边界发生重大变化，可在「## 备注」一行记录，最终成稿时再统一整理。 +3. **task.md 全部 `[x]` 后、归档前**（**必写**）：Agent 基于本次实际改动整理为正式验收清单；占位说明须被替换为成稿。**这是归档门禁**（见「任务完成」）。 +4. **续作**：加载任务时 `Read` 本文件，向用户展示当前形态（占位 / 已成稿）。 + +**内容形态**：可勾选 `- [ ]` 列表 + 验收方式。每项形如： + +```markdown +- [ ] <验收点：交付了什么>（验收方式：<查看哪份文件 / 跑哪条命令 / 看哪个页面>） +``` + +按交付域分二级标题分组（如 `## 代码`、`## 规则与知识库`、`## 任务清单本体`）。**勿**重复列 `task.md` 的执行步骤；**勿**把 `user-todos.md` 中「用户代办」搬入此处。 + +**示例结构**： + +```markdown +# 验收清单 + +> Agent 整理；用户核对后可将对应 `- [ ]` 改为 `- [x]`。 + +## 代码 + +- [ ] `src/<模块>/<文件>.ts`：<改动点>（验收方式：阅读该文件 / 跑 `npm test -- <文件>`） + +## 规则与知识库 + +- [ ] `.Knowledge/topics/.md`：<新增/修订说明>（验收方式：打开该文件确认章节齐全） +- [ ] `.Knowledge/manifest-routing.json`：<是否变更与原因>（验收方式：阅读对应字段） + +## 任务清单本体 + +- [ ] `TASK_ROOT/completed/-/` 目录齐全：`task.md` / `context.md` / `user-todos.md` / `acceptance.md` +- [ ] `TASK_ROOT/todo.json` 已删除对应条目（或文件已删除，若数组变空） +``` + +## 推荐 Hook 配置（Claude Code） + +在项目 `.claude/settings.json` 中添加，每次文件变更前将活跃任务注入上下文（示例为 **legacy** 单根；多人请改为当前 `TASK_ROOT/todo.json`，或在命令内按 `flow2spec.config.json` + git 解析路径）： + +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Edit|Write", + "hooks": [{ + "type": "command", + "command": "node -e \"try{const f='.task/todo.json',fs=require('fs');if(fs.existsSync(f)){const t=JSON.parse(fs.readFileSync(f,'utf8'));if(t.length)console.log('[task] 活跃任务: '+t.map(x=>x.name).join(', '))}}catch(e){}\" 2>/dev/null || true" + }] + }] + } +} +``` + +## 禁止项 + +- 禁止子 agent 写入 `todo.json` +- 禁止在所有步骤完成前将任务移至 `completed/` +- 禁止批量勾选 checkbox（必须逐步勾选） +- 禁止在 `changeTracking.feat` / `changeTracking.fix` / `changeTracking.implement` 均为 `false` 或字段不存在时创建任务目录（`f2s-req-plan` 不受此约束） +- 禁止在已使用任务清单的流程中，将「须用户执行的代办」**仅**写在对话或仅写在 `task.md` 而**不**追加到 `user-todos.md`（无代办时文件可保持占位说明） +- 禁止在 `acceptance.md` 仍为占位说明、或缺失该文件时归档；禁止把 `user-todos.md`（用户代办）与 `acceptance.md`（用户验收）合并写入同一文件 +- 禁止在任务实现完成前预先写入具体验收点（仅可写占位说明），避免与实际交付脱节 +- **禁止**为匹配/续作遍历其他 developer 的 `.task//` 或合并多人 `todo.json` +- **禁止**在未解析 `TASK_ROOT` 的情况下默认写入仓库根 `.task/active/`（除非当前解析结果即为 legacy `.task`） diff --git a/.dsh/topics/f2s-topic-authoring.md b/.dsh/topics/f2s-topic-authoring.md new file mode 100644 index 0000000..8aab8f6 --- /dev/null +++ b/.dsh/topics/f2s-topic-authoring.md @@ -0,0 +1,123 @@ +# Flow2Spec 主题创作准则（Topic Authoring） + +本条为 **创作侧** 单一事实源；凡 `f2s-*` 技能在新增或修改 `.Knowledge/topics/.md`、调整 `manifest-routing.topicMetadata` / `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**必须先 Read 本条全文**，再按对应 SKILL 的步骤继续。与 `f2s-flow2spec-unified-entry`（消费侧）**并存**；硬冲突时以统一入口为准。 + +## 适用范围 + +满足下列任一即「触达本条」： + +- 新增或重写 `.Knowledge/topics/.md`； +- 修改既有 topic 的标题 / 适用场景 / 关键流程边界； +- 新增、删除或调整 `manifest-routing.topicMetadata`； +- 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边； +- 在 `taskToTopicRules[].topics` 中新增引用某个 topic id； +- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。 + +## 1. topic 命名 + +- **id**：`kebab-case`，与 `manifest-routing.topicPaths` 的 key 一致。 +- **文件名**：`.Knowledge/topics/.md`；若该 topic 与同名 `f2s-*` 技能 / 规则强绑定（如 `f2s-task` / `f2s-req-plan`），文件名可加 `f2s-` 前缀以示同源。 +- **不要**：版本后缀（`-v2` / `-new`）、个人花名、与 `index.md` 行级标题冲突的同义词。 + +## 2. topic 定位与正文骨架 + +**topic 的定位**：可执行路由摘要 + 关键边界。topic 可以包含必要的边界说明、关键流程步骤、禁止项、配置摘要——Agent 读完即可执行或判断是否需要继续下钻；**不应承载**完整实现细节、长文背景或可在 stock-doc 里查的原始内容。stock-doc 承载完整背景与长文细节，topic 指向它。 + +**长文背景引用的目录边界（硬约束）**：topic 中「详细背景 / 相关资料 / 长文来源 / 参考文档」等**指向长文源**的引用槽位，**只允许**指向 `.Knowledge/stock-docs/*_终稿.md` 或已被归档为长文事实的 `stock-docs/*`；**禁止**把这类槽位挂到 `.Knowledge/req-docs/*`（含澄清 / 技术方案 / SQL / PRD 等）——`req-docs` 是本次交付的**临时输入**，用完会随任务归档或迁移，作为 topic 的长文事实源是悬空引用。若同步 / 新建 topic 时相应 `stock-docs/*_终稿.md` 尚未生成，**必须先触发 `f2s-doc-final` 沉淀终稿**（或与用户确认由手写补齐），再让 topic 指向终稿；不得跳过终稿直接把 topic 挂在 `req-docs` 上。**允许**：topic 正文可**短引**方案里的一句结论或一个字段名作为佐证（如「见 `.Knowledge/req-docs/xxx_技术方案.md`」的偶发点引），但**长文背景槽位**（"详细背景 / 相关资料"整节）仍须指向 stock-doc。 + +每个 topic 至少包含： + +1. **标题与一句话意图**（一行写清"该 topic 解决什么"）； +2. **适用场景 / 触发词**（与对应 `matchers/.json` `includeAny` 语义一致）； +3. **核心规则 / 流程**（可执行知识；步骤须可由 Agent 复现）； +4. **依赖声明**（若 `topicDependencies` 中存在依赖项，正文须显式写一句「执行前须先读依赖主题 ``」，参考 `topics/f2s-req-plan.md` 首段写法）； +5. **边界与禁止项**（避免膨胀到隔壁 topic）； +6. **长文背景 / 详细资料引用**（如需承载业务背景）：只列 `.Knowledge/stock-docs/*_终稿.md` 的可点击 Markdown 链接（1–3 条即可）；**禁止**直接列 `.Knowledge/req-docs/*` 作为长文背景来源；无对应终稿时**先生成终稿**再回填此小节。 + +## 3. topicMetadata 判定准则 + +`topicMetadata` 是治理元数据，只影响盘点、审计和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性。执行强制性以 `AGENTS.md`、rules、skills 与 topic 正文明确要求为准。 + +字段： + +- `primary`：主分类，单值，取 `feature` / `module` / `config` / `policy`。 +- `tags`：可选，数组，取值范围同 `primary`，不得与 `primary` 重复。用于描述 topic 同时包含的次要性质，仅作审计/阅读预期，不参与路由或执行。 +- `confidence`：取 `manual` / `inferred`。 + +判定： + +1. `topicMetadata` key 必须存在于 `topicPaths`；仅给已存在或本次确认创建的 topicId 写入。 +2. `primary` 取 topic 最核心的性质：读 topic 正文，判断其主要内容属于哪个类型，写入 `primary`。 +3. `config`：配置项、开关、默认值、初始化参数；仅当这些内容构成 topic 的主要语义时才可作为 `primary`。 +4. `policy`：流程、规则、约束、门禁、禁止项、agent 编排、技能步骤；仅当这些内容构成 topic 的主要语义时才可作为 `primary`。。 +5. `feature`：已落地业务 / 产品能力。 +6. `module`：公共能力、公共包、模块边界与工程结构 +7. topic 同时覆盖多个性质时，最主要性质写 `primary`，其余明确成立的性质写 `tags`（可选数组，元素取值同 `primary`，不得与 `primary` 重复）。 +8. `manual` 仅用于用户或维护者明确确认分类值；有明确证据但未人工确认分类值时写 `inferred`。证据不足时**不写 metadata**，但须在摘要中列出推断方向与依据（如「建议 policy，正文含多处强制约束」），供用户确认后手动补写 `manual`。**禁止仅凭 topicId 名称推断分类，必须 Read topic 正文后再判断。** **`inferred` 不需要用户事先同意即可直接落盘**：证据足够时按本条直接写入；只有当用户/维护者主动指定分类、或证据矛盾需要决断时，才升级为 `manual`。把 `inferred` 当作"待用户同意"是常见误读，等同于把"有依据的自动归类"硬变成"必须人工确认"，与本条第 7 项允许 `inferred` 落盘的语义冲突。 + +禁止：为了分类创建、重命名、拆分 topic；在 topic markdown 正文或 `index.md` 中重复写分类块。 + +## 4. topicDependencies 判定准则 + +设当前主题为 A、候选依赖为 B。**四问命中任一即声明 `A → B`**： + +1. **前置规则强引用**：A 的执行步骤**显式提到** B 的术语 / 产物 / 落盘约束（例：`f2s-req-plan` 要求「按 `f2s-task` 维护 `.task/`」）。 +2. **缺 B 必出错**：仅读 A 不读 B 能否产出对的结果？答否——典型为 A 写"怎么做"、B 写"在哪做 / 用哪份输入"。 +3. **共享落盘目标**：A、B 写同一组文件且 B 定义写盘格式（如 `.task/`、`.Knowledge/topics/`）。 +4. **fallback 跳转 B**：A 自身覆盖不全，按现有约定回落 B 兜底。 + +**反向排除**（避免依赖膨胀）： + +- 仅术语相邻（都谈"知识库"）→ 不写依赖，靠 `index.md` 语义边界即可。 +- 跨主题信息互查（A 想"了解一下" B）→ 不写依赖，靠 `taskToTopicRules` 次高候选 + `expand` 补召回。 +- **概述 → 详情导航**：大功能主 topic 与其子模块 topic 之间是"关联/导航"关系，不是强前置依赖——子模块 topic 通过各自的 matcher 独立命中，不写 `A → B`；主 topic 正文里写子模块 stock-doc 的可点击链接作为导航入口。 +- **传递依赖不重复声明**：若 `A→B`、`B→C` 已成立，禁止再写 `A→C`（读 B 时会自然带上 C）。 + +**DAG 与最小化**：`topicDependencies` 必须是 DAG，禁止环；保持最小边集。 + +**判定时机**：终稿与新 / 改 topic 落盘后，扫正文中**反引号引用的其他 topic id 与规则文件名**，逐个套四问；命中即写入 `manifest-routing.topicDependencies`，**并在新 topic 正文显式写依赖声明**（见骨架第 4 条）。 + +## 5. 大功能拆分策略 + +当一个业务功能体量较大时，推荐「主 topic + 子 topic」结构，而非单个大 topic。 + +**何时拆分（软约束，满足任一评估是否需拆）**： + +- 对应 stock-doc 超过 **300–500 行**：建议评估拆分，不强制阻断； +- matcher `includeAny` 超过 **12 个**：主题过宽信号； +- topic 正文包含超过 **3 个不相干职责域**的二级标题； +- `f2s-kb-upgrade` 审计时发现同一 topic 被多种不相干任务类型反复命中。 + +**拆分方式**： + +- **主 topic**（`primary: feature`）：写业务闭环、入口边界、子模块索引，正文里用可点击 stock-doc 链接指向各细节文档；不写子模块的实现细节。 +- **子模块 topic**：按实际语义各自写 `feature` / `module` / `config` / `policy`，不预设类型；各自拥有独立 matcher，通过细分触发词独立命中。 +- **stock-doc**：允许长文；超过阈值时建议拆成多份 focused stock-doc（如 `<功能名>-业务规则_终稿.md`、`<功能名>-数据模型_终稿.md`），每份对应一个子 topic。 + +**不要做的事**： + +- 不用 `topicDependencies` 表达"概述 → 详情"导航关系（见第 4 节反向排除）； +- 不为拆分而强行制造子 topic，若子模块本身不会被独立路由命中，不必建 topic。 + +## 6. rule 是否需新建对应 topic + +判据：**该 rule 是否会作为用户任务路由命中**。 + +- **会**（用户问 / 输入会触发该规则的执行）→ 须在 `.Knowledge/topics/` 建对应路由摘要，并在 `taskToTopicRules` 配置入口。例：`f2s-task`（变更追踪用户场景命中）、`f2s-implement-tech-design`（"按方案实现"用户场景命中）。 +- **不会**（仅被其他规则 / SKILL 内部引用，用户不会直接发起）→ **不建** topic。例：`f2s-knowledge-preflight`、`f2s-karpathy-guidelines`、`f2s-config-check`、本条 `f2s-topic-authoring`。 + +误区：「重要的规则就该有 topic」——重要不等于"用户路由命中"；让消费方 SKILL 在正文里直接 `Read rules/.*` 全文即可，无需走 manifest 路由。 + +## 7. 写盘权属（指针） + +`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/topics/*.md` 的写权约束**以 `f2s-flow2spec-unified-entry` 与各 SKILL 内「写权硬约束」为准**，本条不复述；遇分歧以统一入口与对应 SKILL 为准。 + +## 禁止项 + +- 在未读本条的情况下新增 / 修改 topic 或 `topicDependencies`。 +- 为补分类单独创建、重命名或拆分 topic。 +- 在 topic 正文或 `index.md` 中写 `## 概念分类` 等 metadata 副本。 +- 把"重要的规则"硬塞进 `taskToTopicRules`（参见第 4 条）。 +- 用 `topicDependencies` 表达"信息相关"（应通过 `index.md` 语义边界 + matcher 关键词补召回，而非依赖边）。 +- 在 `topicDependencies` 中写传递冗余边或形成环。 +- **在 topic 的「长文背景 / 详细资料 / 相关资料 / 长文来源 / 参考文档」等指向长文源的整节引用槽位里，列出 `.Knowledge/req-docs/*`**（含澄清 / 技术方案 / SQL / PRD）。此类槽位只允许指向 `.Knowledge/stock-docs/*_终稿.md`；无终稿时须先生成再回填。短句/佐证式的偶发点引不受此约束。 \ No newline at end of file