diff --git a/.Knowledge/index.md b/.Knowledge/index.md index 03de2d1..d2b9f43 100644 --- a/.Knowledge/index.md +++ b/.Knowledge/index.md @@ -50,7 +50,7 @@ ## 命中与执行（与统一入口一致） -- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中,详见 `topics/kb-routing-summary.md`)。 +- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中)。 - **依赖**：命中主主题前，按 `topicDependencies` 先读依赖主题。 - **兜底**：`fallbackTopic` 指向分诊主题（如 `fallback-triage`），仅低置信度上下文，**不得**当作最终命中直接改代码。 - **执行链**：`match → expand → verify → act`；`expand` 须含依赖展开，并保留次高候选做校验。 diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index ab16998..d9d66d3 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.6.2", + "version": "3.7.0", "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", "sourceOfTruth": ".Knowledge/manifest-routing.json", @@ -211,7 +211,7 @@ "summary": "初筛 summary 与 matcher 分片 4 字段(资格/否决门)语义" } ], - "projectRev": 2, + "projectRev": 3, "pkgRev": 3, "topicMetadata": { "implement-tech-design": { diff --git "a/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\346\212\200\346\234\257\346\226\271\346\241\210.md" "b/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\346\212\200\346\234\257\346\226\271\346\241\210.md" new file mode 100644 index 0000000..62db4f8 --- /dev/null +++ "b/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\346\212\200\346\234\257\346\226\271\346\241\210.md" @@ -0,0 +1,374 @@ +# 流程无二次确认与自动更新 技术方案 + +## 需求概述 + +- **背景**：Session `ff3c3636-0689-47f2-818a-87a18d73850d` 与 Issue #38 反映——从需求到实现主链上有多个"二次确认"阻塞点让 Agent 停下来等待，且 CLI/Core 兼容更新场景 Hook 只提示不代跑，需要用户手工介入。 +- **目标**：压缩主链人为确认点、简化 `f2s-kb-sync` 反馈文案、区分 Core-only / Template-update 两条更新路径让 Agent 在 Core-only 场景直接代跑。 +- **范围**：仅改本仓 `packages/core/templates/{zh-CN,en-US}/` 下的 4 个 skill / 1 个 rule / 1 个 hook + 1 个统一入口小节；本仓专属规则 `repo-dev-workflow-constraints.md` 不动。 +- **明确不做**： + - 不引入 `flow2spec.config.json` 新的开关字段（如 `skipTaskConfirm`），Q2 例外阈值直接写死在 skill/rule 里； + - 不改 `f2s-kb-sync` 是否入库门禁（仍保留 y/n），只改文案； + - 不让 hook 自己调 `npm install`（Q5a 选 A，走 Agent 代跑）； + - 不改 `f2s-kb-upgrade` skill 本体； + - 不主动跑 `flow2spec init` / `sync:agents`（分发交给用户）。 + +## 重点问题概述 + +### 问题 1：过渡型提示行与阻塞型确认行如何在 skill 里表述？ + +`f2s-req-clarify` 现行第 22 行已经写「澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`」，但实际执行常在提示行处停下等回复。**根因是提示行本身**含"是否 / 请 / 等"型措辞，Agent 会把它读成确认询问。 + +**方案**：在 skill 里明确把提示行改为**过渡口吻**（"→ 继续生成技术方案"），并在同一段落用**独立元指令**（"本行仅作过渡不等待任何回复，Agent 落盘后立即调用下一 skill"）把行为固化。同样的写法应用到 `f2s-req-plan` 展示 + 落盘的过渡行。 + +### 问题 2：Q2 例外触发门槛需要 Agent 能机器判定 + +如果例外规则含"关键决策缺失时才停"这类模糊语，Agent 会保守地把大多数情况都判为"关键决策缺失"从而变相恢复阻塞。**方案**：写死可枚举的触发信号： +- 方案文本中 `待定 / 待确认 / TBD / \?\?\?` 类未决标记 **≥ 3 处**； +- 方案关键契约字段（接口签名 / 表结构 / 状态机 / 错误码）**整节缺失**（不是"不够详尽"）； +- 用户明确说"先只列任务 / 别急着实现 / 让我先看看清单"等停步语。 + +三条命中任一才停下来一次性列出问题；其余情况一律"展示 + 落盘 + 进入下一步"同轮完成。 + +### 问题 3：`f2s-kb-sync` 反馈简化的边界 + +Issue #38 强调"用户需要仔细查看入库了什么 不入库什么"——核心信号是 **入 / 不入 / 是否继续** 三段。次要信号（拟改文件路径、topicMetadata 证据、终稿沉淀计划）需要保留但不能挤占视觉焦点。 + +**方案**：3 段主体（每段 1-5 行）+ `
` 折叠详情。是否入库门禁保持不变（用户仍需 y/n）。 + +### 问题 4：Agent 代跑 update 需要有可靠的 CLI 入口 + +用户机器上可能没有全局 `flow2spec` CLI。**方案**：Agent 代跑时按优先级尝试： +1. `flow2spec update --cli`（全局 CLI）； +2. 失败则 `npx @double-coding/flow2spec update --cli`（临时下载）； +3. 都失败则一行报告 + 命令原文交给用户，继续本轮任务不阻塞。 + +不引入 hook 层直接执行 npm install——保留在 Agent 层可控。 + +### 问题 5：Core-only 场景与 Template 场景的判定 + +`.claude/hooks/f2s-update-check.js` 已按 `coreUpdateAvailable` / `templateUpdateAvailable` 两个独立布尔分场景。**方案**：只改 `buildNotice()` 的 agent-instruction 措辞： +- 场景 A（`coreUpdateAvailable && !templateUpdateAvailable`）：措辞从"可执行"→"须直接代跑（无需二次确认），跑前告知用户一行'正在自动更新 CLI/Core，不涉及知识库主题变更'"； +- 场景 B（`templateUpdateAvailable`）：保持"提示用户 + 询问后代跑 + Template 变更走 f2s-kb-upgrade"口径。 + +## 外部依赖与内部调用 + +### 依赖 + +- `flow2spec` CLI（用户机器全局命令）——Q4 场景 A/B Agent 代跑时使用； +- npm registry（`https://registry.npmjs.org`）——`f2s-update-check.js` 已依赖，本次不改； +- `sync-core-templates.js`（`packages/core/package.json.scripts.prepack` 触发）——改完根 templates 后本地开发跑 `npm run sync:core-templates` 或依赖 prepack 自动同步。 + +### 内部调用 + +- `f2s-req-clarify` 落盘澄清文档后 → 同轮调用 `f2s-req-tech`（现行链路，本次只调整过渡行文案）； +- `f2s-req-plan` 步骤 2 → 同轮直接执行步骤 3 落盘 → 步骤 4 实现（拿掉步骤 2 与步骤 3 之间的用户确认阻塞）； +- `f2s-implement-tech-design` 步骤 2.5 → 步骤 4（跳过步骤 3 除非命中例外门槛）； +- `f2s-kb-sync` 步骤 2 → 用户 y → 步骤 2.5（如需） → 步骤 3 落盘（保持不变，只改步骤 2 大纲文案）； +- `f2s-update-check.js` Hook → 注入 `additionalContext` → Agent 按新措辞在本轮回复开头处理（Core-only 直接代跑，Template 询问后代跑）。 + +## 配置 + +### `flow2spec.config.json`（不新增字段） + +本次改造**不引入**新配置字段。Q2 例外阈值写死在 skill/rule 里；如后续需要用户可配再单独澄清。 + +### 相关现有字段（口径不变） + +- `updateCheck.enabled: true`：Hook 自检开关； +- `subAgent: true`：受影响 skill 内的拆子逻辑保持现行； +- `switchAgentVerification: true`：交叉校验口径不变； +- `intentRecognition: true`：本次改造后自动衔接逻辑仍走该开关。 + +## 交付单元 + +### 交付单元 1：`f2s-req-clarify` skill 文案调整 + +**输入 / 触发**：改动 `packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md` + `packages/core/templates/en-US/skills/f2s-req-clarify/SKILL.md`（en-US 版为同源翻译）。 + +**输出 / 结果**：澄清文档落盘后过渡行明确为不等待型；三个例外条款保持不变。 + +**改动细节**（以 zh-CN 版为准，en-US 同步翻译）： + +- 第 22 行段落改写： + - **原**：「澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`」+ 示例提示行「澄清文档已就绪：`<路径>`；正在按 `f2s-req-tech` 生成技术方案」 + - **新**： + ```markdown + **澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`（Agent 无需征询用户）**：以刚落盘的澄清文档路径为输入直接进入技术方案生成，落盘后 **Agent 在同一轮回复内**输出一行**过渡型提示**（示例："澄清文档已就绪：`<路径>` → 继续生成技术方案。"），然后**当轮立即**调用 `f2s-req-tech`。 + + **硬约束**：过渡行使用箭头"→"或"继续"等推进型措辞；**禁止**使用"是否 / 请确认 / 等您回复 / 可以吗"等等待型措辞；Agent 输出过渡行后**不得**在同一轮内停止工具调用等待用户输入。 + ``` + +- 三个例外条款（未决问题清单 / 用户停步语 / 显式指定后续动作）**保持不变**。 + +**处理流程**：本改动为文本改写，无逻辑变更。分发后新会话生效。 + +### 交付单元 2：`f2s-req-plan` skill 步骤 2 拿掉硬阻塞 + +**输入 / 触发**：改动 `packages/core/templates/{zh-CN,en-US}/skills/f2s-req-plan/SKILL.md`。 + +**改动细节**（zh-CN 版）： + +- 「编排（主 / 子 agent）」段中： + - **原**：`步骤 2（草稿确认）：必须主 agent；未确认前禁止创建 .task/ 或写业务代码。` + - **新**：`步骤 2（展示 + 落盘同轮）：必须主 agent；除歧义例外命中外不停下等待，落盘后进入步骤 4。` + +- 步骤 2 标题改写： + - **原**：`### 步骤 2：输出草稿并确认（必须主 agent）` + - **新**：`### 步骤 2：同轮展示 + 落盘（主 agent，不等待确认）` + - 正文改写为： + ```markdown + 主 agent 在**同一轮回复**内同时完成"向用户展示"与"落盘"两个动作，**不停下等待用户点确认**： + + 1. **展示**（回复中输出，供用户过目）：任务名（snake_case）、实现清单草稿（`## 步骤` 下 `- [ ]` 列表）、涉及文件列表、建议 `keywords`（2–5 个）； + 2. **落盘**（同轮当即执行）：按步骤 3 严格创建 `TASK_ROOT/active//` 全套文件 + 更新 `todo.json`； + 3. 展示与落盘**必须同轮**——用户看到步骤 2 摘要时任务已建，可用一句话说"改一下 / 换个名字"来触发调整。 + + **歧义例外（唯一停步条件）**：仅当以下**任一**命中，主 agent 应改为"输出草稿 + 一次性列出待答问题 + 停止"，等待用户回答后再进入步骤 3： + - 用户输入中含 `待定 / 待确认 / TBD / \?\?\?` 类明确未决标记 **≥ 3 处**； + - 用户输入未指明本次要改的模块/端/文件范围，且方案文档也不含范围章节； + - 用户明确说"先只列任务 / 别急着实现 / 让我先看看清单"等停步语。 + + 未命中例外时不得停下等待——即便用户输入较简略，也直接以合理默认草稿落盘，用户不满意再触发调整。 + ``` + +- 「## 约束」段中： + - **原**：`步骤 2 必须主 agent；未确认禁止落盘` + - **新**：`步骤 2 同轮完成展示与落盘；除歧义例外外不停等待` + +**处理流程**：同现行步骤 1（续作分诊）→ 步骤 2（展示 + 直接落盘）→ 步骤 3（按 `f2s-task` 写文件，逻辑不变）→ 步骤 4（实现）。 + +### 交付单元 3：`f2s-implement-tech-design` rule 步骤 3 条件化 + +**输入 / 触发**：改动 `packages/core/templates/{zh-CN,en-US}/rules/f2s-implement-tech-design.md`。 + +**改动细节**（zh-CN 版）： + +- 步骤 3 标题改写： + - **原**：`### 步骤 3：实现前提问（必做，不可跳过）` + - **新**：`### 步骤 3：实现前提问（条件触发）` + - 正文改写为： + ```markdown + **默认**：跳过本步，直接进入步骤 4 实现。 + + **触发条件（任一命中即停下来一次性列出问题）**： + - 方案文本中 `待定 / 待确认 / TBD / \?\?\?` 类明确未决标记 **≥ 3 处**； + - 方案关键契约字段**整节缺失**（不是"不够详尽"）——例如涉及接口但完全没有接口签名章节、涉及数据但完全没有数据模型章节、涉及状态机但完全没有状态列表； + - 用户明确说"先只列任务 / 别急着实现 / 让我先看看清单 / 先讨论方案"等停步语。 + + 命中时一次性列出 3–6 条最影响实现落笔的问题；未命中一律直接进入步骤 4，未定义细节按合理默认或占位实现并在待完成列表标注"需用户确认"。 + ``` + +- 「## 五、约束与小结」段中： + - **原**：`不得跳过步骤 2.5（任务列表）与步骤 3（实现前提问）直接编码` + - **新**：`不得跳过步骤 2.5（任务列表）；步骤 3 按条件触发（默认跳过，命中歧义门槛才停）` + +**处理流程**：步骤 2.5 输出任务列表 + 直接落 `task.md`（若 `changeTracking.implement=true`）→ 步骤 3 条件判定（默认跳过）→ 步骤 4 实现。 + +### 交付单元 4：`f2s-kb-sync` skill 步骤 2 大纲文案简化 + +**输入 / 触发**：改动 `packages/core/templates/{zh-CN,en-US}/skills/f2s-kb-sync/SKILL.md`。 + +**改动细节**（zh-CN 版）： + +- 步骤 2 正文改写（保留标题「### 步骤 2：输出《更新大纲》（必须）」）： + ```markdown + 大纲**采用 3 段主体 + 折叠详情**结构，让用户一眼看清"入哪 / 改什么 / 不入哪"，细节按需展开： + + ````markdown + ## 知识库同步大纲 + + ### 📥 入库 + - ``：<一句话说明改了什么>（→ `.Knowledge/topics/.md`） + - **新建** ``：<能力概述>（→ 新增 topic + matcher + 路由条目） + + ### 🚫 不入库 + - <能力/变更>：<一句话原因> + + ### 是否继续？(y/n) + +
+ 展开查看详情 + + **拟改文件**： + - `.Knowledge/topics/.md` + - `.Knowledge/index.md` + - `.Knowledge/manifest-routing.json` + - `.Knowledge/matchers/.json` + + **主题元数据**（如有）： + - ``：primary=``，tags=`[...]`，confidence=`` + + **终稿沉淀**（如需）： + - 待生成 `stock-docs/<能力名>_终稿.md`（来源：`req-docs/<方案>.md` + 代码） + + **信息来源**：<用户指定 / Agent 推断 / git diff / 目录扫描> + + **不改动范围**：<列出本次刻意跳过的项与原因> + +
+ ```` + + 主体 3 段每段控制在 **1–5 行**；详情用 `
` 折叠；用户仍需回复 `y/n` 才落盘（本改造只改文案不改门禁）。 + ``` + +- 「## 输出摘要格式（建议）」段：同步简化为 3 段风格（`已修改 / 未执行 / 详情折叠`），保留 `.last-sync.json` 时间戳写入段落不动。 + +- 保留：步骤 2.5 终稿沉淀（硬约束）、步骤 3 落盘、步骤 5 写入 `.last-sync.json`、`manifest-routing.json` 与 `.Knowledge/index.md` 主 agent 单点落盘。 + +**处理流程**：步骤 1（收集素材）→ 步骤 2（**新简化大纲**）→ 用户 y/n → 步骤 2.5（如需终稿）→ 步骤 3（写入，逻辑不变）→ 步骤 4-5（收尾摘要 + 时间戳）。 + +### 交付单元 5：`f2s-update-check.js` Hook agent-instruction 措辞调整 + +**输入 / 触发**：改动 `packages/core/templates/{zh-CN,en-US}/hooks/f2s-update-check.js` 的 `buildNotice()` 函数。 + +**改动细节**（zh-CN 版，两分支改写）： + +- **场景 A：`state.templateUpdateAvailable === false && state.coreUpdateAvailable === true`**（仅 Core 更新） + ```javascript + return [ + '[flow2spec/agent-instruction] 你必须在本轮回复开头执行以下动作，无需征询用户：', + '', + `1. 用一行告知用户："正在自动更新 CLI/Core（${versionSummary}），不涉及知识库主题变更"；`, + `2. 调用 Bash 执行 \`flow2spec update --cli\`（若失败则 fallback 到 \`npx @double-coding/flow2spec update --cli\`；仍失败则一行报告命令原文与错误摘要后继续本轮任务）；`, + `3. 成功后调用 \`flow2spec init <已初始化的 agents>\`（幂等）刷新配置根 Hook；`, + `4. 完成后删除 \`.Knowledge/update-check.json\`；`, + `5. 一行报告完成："CLI/Core 更新完成，Template Version 未变（v${state.manifestVersion}），继续本轮任务。"`, + '', + `📦 [flow2spec] 当前项目「${project}」仅有 Core 程序更新（${versionSummary}），模板版本未变化。Template Version 未变，不进入 f2s-kb-upgrade。`, + ].join('\n'); + ``` + +- **场景 B：`state.templateUpdateAvailable === true`**（Template 有更新，可能同时 Core 也变） + ```javascript + return [ + '[flow2spec/agent-instruction] 你必须在本轮回复开头转告用户以下更新提示：', + '', + `📦 [flow2spec] 当前项目「${project}」有模板更新（${versionSummary}）。`, + '', + '[flow2spec/agent-instruction] Template 变更影响知识库主题，须征询用户后再动。建议流程：', + '1. 询问用户是否代跑 `flow2spec update --cli` + `flow2spec init `；', + '2. 用户同意 → 代跑；init 后读 `.Knowledge/manifest-routing.json`：projectRev 与 pkgRev 相等则删除 `.Knowledge/update-check.json` 结束；不等则调用 f2s-kb-upgrade skill（可从其步骤 2c 起继续）；', + '3. 用户拒绝 → 保留缓存不动，继续本轮任务。', + ].join('\n'); + ``` + +en-US 版同源翻译。 + +**处理流程**：Hook 在 SessionStart 输出 JSON 到 stdout → Claude Code 解析 `hookSpecificOutput.additionalContext` 注入到本轮 Agent 上下文 → Agent 按新措辞在本轮回复开头执行动作。 + +### 交付单元 6：`f2s-flow2spec-unified-entry.md` 「知识库版本自检」小节措辞对齐 + +**输入 / 触发**：改动 `packages/core/templates/{zh-CN,en-US}/rules/f2s-flow2spec-unified-entry.md` 的「知识库版本自检」小节。 + +**改动细节**（zh-CN 版第 100 行段落改写）： + +- **原**：`coreUpdateAvailable=true 时可执行 flow2spec update --cli...若 templateUpdateAvailable=false，随后只执行一次幂等 flow2spec init...` +- **新**： + ```markdown + 2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日，不重复查 npm。 + - **`coreUpdateAvailable=true` 且 `templateUpdateAvailable=false`**（Core-only 更新）：Agent **必须**在本轮回复开头**主动代跑** `flow2spec update --cli`（失败 fallback `npx @double-coding/flow2spec update --cli`）+ 幂等 `flow2spec init <已初始化的 agents>`，跑前告知用户一行"正在自动更新 CLI/Core，不涉及知识库主题变更"，跑完删除 `.Knowledge/update-check.json`，**不进入** `f2s-kb-upgrade`，**无需征询用户**。 + - **`templateUpdateAvailable=true`**（Template 变更）：Agent **必须**在本轮回复开头转告用户提示 + **询问用户是否代跑**；用户同意后代跑 update + init，然后按 `projectRev` / `pkgRev` 判定是否继续 `f2s-kb-upgrade` 完整流程。 + - `.Knowledge/manifest-routing.json.version` 表示 Template Version，禁止与 Core Version 直接比较。 + ``` + +## 处理流程（整体串联） + +``` +Session A：Q1（澄清 → 技术方案自动衔接） + 用户提需求 + ↓ + f2s-req-clarify 反问对齐 → 落盘 <能力>_需求澄清.md + ↓ + Agent 输出过渡行"→ 继续生成技术方案"（不等待） + ↓ + 同轮调用 f2s-req-tech → 落盘 <能力>_技术方案.md + ↓ + 一行收口，停止 + +Session B：Q2（任何场景创建 task 不 2 次确认） + 路径 B1（f2s-req-plan）：用户说"任务规划" + ↓ 步骤 1 续作分诊 + ↓ 步骤 2 同轮展示 + 直接落 .task/active/（无等待） + ↓ 步骤 4 实现代码 + 路径 B2（f2s-implement-tech-design）：打开 req-docs/*.md + ↓ 步骤 2.5 输出任务列表 + 直接落 task.md + ↓ 步骤 3 条件判定（默认跳过）→ 步骤 4 实现 + +Session C：Q3（sync 反馈简化） + 用户触发 f2s-kb-sync + ↓ 步骤 1 收集素材 + ↓ 步骤 2 输出 3 段大纲（入库 / 不入库 / y/n） +
详情 + ↓ 用户 y → 步骤 3 落盘 + +Session D：Q4 + Q5（SessionStart 自动更新） + Hook 检测 → 注入 additionalContext + ↓ + 场景 A（Core-only）：Agent 一行告知 + 代跑 update + init + 删缓存 + 一行报告 + 场景 B（Template）：Agent 转告 + 询问 → 用户同意 → 代跑 + 走 f2s-kb-upgrade +``` + +## 数据模型 + +无新数据模型。涉及的现有文件： + +| 文件 | 类型 | 本次改动 | +| --- | --- | --- | +| `packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md` | Markdown | 改过渡行段 | +| `packages/core/templates/zh-CN/skills/f2s-req-plan/SKILL.md` | Markdown | 改步骤 2 与约束段 | +| `packages/core/templates/zh-CN/rules/f2s-implement-tech-design.md` | Markdown | 改步骤 3 与约束段 | +| `packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md` | Markdown | 改步骤 2 与摘要格式 | +| `packages/core/templates/zh-CN/hooks/f2s-update-check.js` | JavaScript | 改 `buildNotice()` 两分支 | +| `packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md` | Markdown | 改「知识库版本自检」小节 | +| `packages/core/templates/en-US/...` 同步 6 份 | 同源翻译 | 与 zh-CN 语义一致 | + +## 异常处理 + +| 场景 | 处理 | +| --- | --- | +| Q1 过渡后 `f2s-req-tech` 落盘失败 | Agent 一行告知失败原因 + 澄清文档已在原路径，停止本轮 | +| Q2 落盘时目录已存在冲突 | 按 `f2s-task` 续作分诊逻辑走；无法调和时**这是唯一硬阻塞点**——列冲突详情等用户决策 | +| Q4 场景 A `flow2spec update --cli` 失败 | Fallback `npx @double-coding/flow2spec update --cli`；仍失败一行报告命令原文与错误摘要，继续本轮任务不阻塞 | +| Q4 场景 A `flow2spec init` 失败 | 一行报告 + 保留缓存不删；用户下次会话仍会看到提示 | +| Q5b npm 返回缺 `templateVersion` 字段 | Hook 现行 fallback `metadata.templateVersion \|\| metadata.version` 保持不变；本次不改此逻辑 | +| Hook 层网络/权限异常 | 静默跳过（现行行为不变） | + +## 验证建议 + +### 分发验证 + +1. 改完根 `templates/{zh-CN,en-US}/`，跑： + ```bash + npm run sync:core-templates:check # 应无漂移 + npm run sync:core-templates # 若有漂移则同步 + ``` +2. 用户手工分发到本仓配置根： + ```bash + npm run sync:agents + # 或 node ./cli.js init codex claude cursor + ``` +3. 观察 `.claude/skills/{f2s-req-clarify,f2s-req-plan,f2s-kb-sync}/SKILL.md`、`.claude/rules/{f2s-implement-tech-design,f2s-flow2spec-unified-entry}.md`、`.claude/hooks/f2s-update-check.js` 是否更新到新版；三端（`.cursor/`、`.codex/`）同理。 + +### 功能烟测 + +- **Q1 场景**：新起会话 → 提一个需求 → 让 Agent 走 `f2s-req-clarify` → 观察澄清文档落盘后 Agent 是否**不停下等待**、同轮进入 `f2s-req-tech`； +- **Q2 场景 B1**：让 Agent 用一个短需求走 `f2s-req-plan` → 观察是否**跳过草稿确认**直接落 `TASK_ROOT/active/`； +- **Q2 场景 B2**：打开一个 `req-docs/*.md` → 让 Agent 按方案实现 → 观察步骤 3 是否被跳过（未命中歧义门槛时）； +- **Q3 场景**：让 Agent 触发 `f2s-kb-sync` → 观察大纲输出是否为 3 段主体 + `
` 折叠； +- **Q4 场景 A**：伪造 `.Knowledge/update-check.json`（`coreUpdateAvailable=true`, `templateUpdateAvailable=false`）→ 新起会话 → 观察 Agent 本轮回复开头是否直接代跑 update + init + 一行前置告知 + 一行完成报告； +- **Q4 场景 B**：伪造 `templateUpdateAvailable=true` 的缓存 → 观察 Agent 是否走"转告 + 询问代跑 + Template 变更后走 f2s-kb-upgrade"路径。 + +### 回归观察点 + +- `f2s-req-clarify` 三个例外条款（未决问题 / 用户停步语 / 显式指定后续动作）是否仍生效； +- `f2s-kb-sync` 未确认前禁止落盘的门禁是否仍生效； +- `f2s-task` 归档门禁（`task.md` 全 `[x]` 才归档）是否不受影响； +- `switchAgentVerification=true` 时的交叉校验是否不受影响。 + +## 相关资料 + +- `.Knowledge/req-docs/流程无二次确认与自动更新_需求澄清.md`（本方案的澄清文档） +- `.claude/rules/repo-dev-workflow-constraints.md`（本仓开发纪律，只改 templates 的硬约束） +- `packages/core/templates/zh-CN/hooks/f2s-update-check.js`（Hook 现行实现） +- `.claude/rules/f2s-flow2spec-unified-entry.md`（统一入口，知识库版本自检小节） +- GitHub Issue #38 +- Session `ff3c3636-0689-47f2-818a-87a18d73850d` diff --git "a/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\351\234\200\346\261\202\346\276\204\346\270\205.md" "b/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\351\234\200\346\261\202\346\276\204\346\270\205.md" new file mode 100644 index 0000000..b4f35fe --- /dev/null +++ "b/.Knowledge/req-docs/\346\265\201\347\250\213\346\227\240\344\272\214\346\254\241\347\241\256\350\256\244\344\270\216\350\207\252\345\212\250\346\233\264\346\226\260_\351\234\200\346\261\202\346\276\204\346\270\205.md" @@ -0,0 +1,264 @@ +--- +title: 流程无二次确认与自动更新 +type: 需求澄清 +issue: #38（sync skill 反馈文案简化） +createdAt: 2026-09-04 +--- + +# 需求澄清：流程无二次确认与自动更新 + +## 背景与目标 + +Flow2Spec 目前若干过程编排型技能存在多处「二次确认」阻塞点，让用户从需求到落地的路径出现不必要的中断；同时更新检查 Hook 仅提示、不代跑，导致 CLI/Core 兼容更新场景仍需用户手动介入。本次改造目标： + +- **压缩人为确认点**：需求澄清 → 技术方案 → 任务创建 → 实现，这条主链上除非用户输入含明显歧义/矛盾，全程不再中途等待确认； +- **简化 KB 同步反馈**：`f2s-kb-sync` 的入库大纲让用户一眼看清"入哪 / 改什么 / 不入哪"，细节可展开； +- **区分更新通道**：CLI/Core 兼容更新 → Agent 无二次确认直接代跑；只有主题版本变更 → 提示 `f2s-kb-upgrade`。 + +对应用户反馈来源：Session `ff3c3636-0689-47f2-818a-87a18d73850d` 与 GitHub Issue #38。 + +## 范围（包含 / 不包含） + +### 包含 + +1. **`f2s-req-clarify` skill**：澄清文档落盘后 → 自动衔接 `f2s-req-tech` 的过渡提示行改写为**过渡口吻且不等待**。 +2. **`f2s-req-plan` skill**：拿掉步骤 2「输出草稿并等用户确认」的硬阻塞，改为**展示+落盘+进入实现**同一动作序列不中断。 +3. **`f2s-implement-tech-design` rule**：拿掉步骤 3「实现前提问必做」的硬阻塞，改为"输入含明显歧义/矛盾才停"。 +4. **`f2s-kb-sync` skill**：步骤 2《更新大纲》从 8 大项压缩到 3 段核心信号（入库 / 不入库 / 是否继续），细节收进可展开的详情块。 +5. **`f2s-update-check` hook + 统一入口规则**：Agent 在只有 Core 更新的场景直接代跑 `flow2spec update --cli` + `flow2spec init `；Template 变更才提示 `f2s-kb-upgrade`。跑前用一行告诉用户"正在自动更新，不涉及知识库主题变更"，跑完报结果。 +6. **同步落盘位置**：所有 skill / rule 变更**只改 `packages/core/templates/{zh-CN,en-US}/`**（本仓开发纪律硬约束）；hook 已经在 core templates 里到位，配置根 `.claude/hooks/f2s-update-check.js` 已同步；本次 hook 若需要新增"允许自动代跑"的口径调整，同样改 templates。 + +### 不包含 + +1. **不改** `f2s-req-clarify` 的核心行为（继续反问直到澄清充分才落盘）；本次只改**落盘后衔接**那一行提示。 +2. **不改**任何 `f2s-kb-*` 写盘之前的**必要预演**（`kb plan`/`kb apply`/`kb build`/`kb check`），只改**给用户看的大纲文案**。 +3. **不改** `.task/` 目录结构、`todo.json` 写权、`f2s-task.md` 归档门禁等强约束——只拿掉 skill 内 "等用户点确认" 的**阻塞门**，落盘规范照旧。 +4. **不引入** hook 直接调 `npm install` 的能力（用户 Q5a 选 A，走 Agent 代跑，不走 hook 层直接执行）。 +5. **不改** `f2s-kb-upgrade` skill 自身；只调用它作为 Template 变更时的下游动作。 +6. **不动**本仓专属规则（`repo-dev-workflow-constraints.md` 等），它们不进 templates。 + +## 关键流程 + +### 流程 1：需求澄清 → 技术方案（Q1） + +``` +用户提出需求 + ↓ +Agent 进入 f2s-req-clarify，反问对齐 + ↓ +澄清充分 → 落盘 .Knowledge/req-docs/<能力名>_需求澄清.md + ↓ +Agent 输出过渡行：「→ 继续按 f2s-req-tech 生成技术方案」（不等待任何输入） + ↓ +同一轮 Agent 直接调用 f2s-req-tech，读取刚落盘的澄清文档作为输入 + ↓ +生成技术方案 → 落盘 .Knowledge/req-docs/<能力名>_技术方案.md + ↓ +输出收口行「技术方案已就绪：<路径>；如需拆任务/实现，可用 f2s-req-plan / implement-tech-design」→ 停止 +``` + +**过渡行样式**（示意，实际落 skill 时按此措辞）： +``` +澄清文档已就绪：`.Knowledge/req-docs/<能力名>_需求澄清.md` → 继续生成技术方案。 +``` +禁止使用「是否继续」「等您确认」等等待型措辞。 + +### 流程 2：创建任务不二次确认（Q2） + +**入口 A：`f2s-req-plan` skill**（用户显式说"任务规划 / 创建任务"） + +``` +用户输入需求 / 方案路径 / 变更描述 + ↓ +步骤 1 续作分诊 + 解析（同现行） + ↓ +【本次改造点】步骤 2 改为「同轮展示 + 直接落盘」，不再等待： + - 主 agent 在回复里同时输出：任务名、步骤清单、涉及文件、keywords + - Agent 展示完当轮立即 Write task.md / context.md / user-todos.md 占位 + todo.json 新增条目 + - 展示与落盘同轮完成，用户看到时任务已建 + ↓ +步骤 3 落盘完成（同现行的文件格式，走 f2s-task 硬约束） + ↓ +步骤 4 实现代码（同现行） +``` + +**入口 B：`f2s-implement-tech-design` rule**（打开 `.Knowledge/req-docs/*.md` 或"按方案实现"） + +``` +读方案 → 步骤 2.5 输出任务列表 + 直接落 .task/active//task.md（若 changeTracking.implement=true） + ↓ +【本次改造点】步骤 3「实现前提问必做」→ 改为「实现前提问（条件触发）」： + - 默认：直接进入步骤 4 实现 + - 例外：仅当方案存在 3 个及以上「明确未定义/矛盾/关键决策缺失」时才停下来一次性列出问题 + ↓ +步骤 4 按任务列表实现（同现行） +``` + +**Q2 例外触发门槛（写入 skill 与 rule）**： + +- 方案文本含"待定 / 待确认 / TBD / ??? / 待补充"等明确未决标记且**≥ 3 处**；或 +- 方案关键字段（接口契约、表结构、状态机、错误码）**完全缺失**（不是"未详尽"）；或 +- 用户明确说「先只列任务 / 别急着实现 / 让我先看看清单」等停步语。 + +命中任一才停下来一次性列问题，其余情况一律直接展示 + 落盘 + 进入下一步。 + +### 流程 3：`f2s-kb-sync` 反馈简化（Q3） + +**现行反馈（8 项）**：同步目标、能力清单、信息来源、拟改文件清单、主题同步计划（含 topicMetadata 证据）、终稿沉淀计划、不改动范围、等待确认。 + +**改造后反馈**（3 段主体 + 折叠详情）： + +```markdown +## 知识库同步大纲 + +### 📥 入库 +- ``：<一句话说明改了什么>（→ `.Knowledge/topics/.md`） +- **新建** ``：<能力概述>（→ 新增 `topics/.md` + `matchers/.json` + 路由条目） + +### 🚫 不入库 +- <能力/变更>：<一句话原因>（如"仅代码重构无新语义 / 属于 fix 已在其他 topic 覆盖"） + +### 是否继续？(y/n) + +
+展开查看详情（拟改文件 / 主题元数据 / 终稿沉淀计划） + +**拟改文件** +- `.Knowledge/topics/.md` +- `.Knowledge/index.md` +- `.Knowledge/manifest-routing.json` +- `.Knowledge/matchers/.json` + +**主题元数据**（如有） +- ``：primary=``，tags=`[...]`，confidence=`` + +**终稿沉淀**（如需） +- 待生成 `stock-docs/<能力名>_终稿.md`（来源：`req-docs/<方案>.md` + 代码 + 澄清文档） + +
+``` + +主体 3 段，每段 1–5 行；详情用 `
` 折叠，用户想看就展开。 + +**保留不变**： +- 用户仍需回复 `y/n` 才落盘（这是 `f2s-kb-sync` 的核心保护——避免误入库；Q3 只改文案不改门禁）； +- 步骤 2.5 终稿沉淀、步骤 3 落盘、步骤 5 `.last-sync.json` 时间戳等强约束照旧。 + +### 流程 4：自动更新（Q4 + Q5） + +`.claude/hooks/f2s-update-check.js`（已是新版）在 SessionStart 输出两类 `agent-instruction`： + +**场景 A：只有 Core 更新，Template 未变**（`coreUpdateAvailable=true` + `templateUpdateAvailable=false`） + +``` +Hook 注入 additionalContext： + 📦 [flow2spec] 当前项目「」仅有 Core 程序更新（Core vX.X.X -> vY.Y.Y），模板版本未变化。 + [agent-instruction] 直接代跑 `flow2spec update --cli` + 幂等 `flow2spec init `， + 跑完删除 .Knowledge/update-check.json，不进入 f2s-kb-upgrade，无需征询用户。 + 跑前用一行告知："正在自动更新 CLI/Core，不涉及知识库主题变更"。 + +Agent 本轮回复开头： + 1. 转告用户上述提示； + 2. 立即调用 Bash 执行 `flow2spec update --cli`； + 3. 成功后调用 `flow2spec init `（幂等）； + 4. 完成后删除 `.Knowledge/update-check.json`； + 5. 一行报告："CLI/Core 更新完成，Template Version 未变（v），继续本轮任务。" +``` + +**场景 B：Template 有更新**（`templateUpdateAvailable=true`） + +``` +Hook 注入 additionalContext： + 📦 [flow2spec] 当前项目「」有模板更新（Core vX -> vY，Template vA -> vB）。 + [agent-instruction] 提示用户执行 `flow2spec update --cli` + `flow2spec init `， + 然后按需触发 `f2s-kb-upgrade` skill（可从其步骤 2c 起继续）。 + +Agent 本轮回复开头： + 1. 转告用户此提示； + 2. 询问用户是否代跑 update + init（Template 变更影响 KB，须用户知情）； + 3. 用户同意 → 代跑；随后如 projectRev ≠ pkgRev，进入 f2s-kb-upgrade skill。 +``` + +**判定口径**： +- Core 更新 = `GENERATED_CORE_VERSION < npm latest .version` +- Template 更新 = `.Knowledge/manifest-routing.json.version < npm latest .templateVersion` +- 两者独立判定，只 Core 更新走 A，Template 有更新走 B（即使 Core 也同时变了）。 + +## 边界与异常 + +### 边界 + +1. **Q2 例外只在 skill 内声明，不新增配置字段**：本次不引入 `flow2spec.config.json` 新的开关（如 `skipTaskConfirm`），阈值写死在 skill/rule 里；若后续需要用户可配再另开澄清。 +2. **`f2s-kb-sync` 反馈仍需 y/n**：Q3 只改文案不改是否入库门禁；用户明说"简化文案"但也说"用户需要仔细查看入库了什么 不入库什么"→ 保留人工把关。 +3. **`f2s-req-clarify` 澄清不充分时仍会停**：现行 skill 的例外条款（未决问题影响方案结构、用户说"先只出澄清"）保留；本次只改"衔接过渡行"，不改反问深度。 +4. **自动更新的执行环境**：Agent 代跑 `flow2spec update --cli` 依赖用户机器上有 `flow2spec` 全局 CLI（或 `npx flow2spec`）；无 CLI 时 hook 已注入的提示会失效，Agent 需要退回"手动提示用户装 CLI"路径。 + +### 异常 + +1. **Q1 过渡后 `f2s-req-tech` 落盘失败**（磁盘只读 / 路径冲突）：不重试无限次；Agent 在回复末尾一行告知"技术方案落盘失败：<原因>，澄清文档仍在 `<路径>`"，然后停止。 +2. **Q2 直接落 `.task/` 时目录已存在**：按 `f2s-task` 续作分诊逻辑走（现行覆盖）；若冲突无法解决则**这是唯一硬阻塞点**——列出冲突详情等用户决策，不再"无 confirm 直接覆盖"。 +3. **Q4 场景 A 代跑 `flow2spec update --cli` 失败**（网络 / 权限）：Agent 一行报告失败原因，把命令原文和文档链接给用户，继续本轮任务不阻塞。 +4. **Q5b `templateVersion` 字段缺失**（老版本 npm 包）：hook 现行的 fallback 是 `metadata.templateVersion || metadata.version`，会误判为需升；本次不改此 fallback，但在 Q5b 判定精度不足时以"提示用户查 changelog"兜底。 + +## 关键概念定义 + +- **过渡型提示行**：Agent 在同一轮内输出的"→ 继续做 X"式说明，用户可读但**规则明确不等待任何输入**。区别于"是否继续 (y/n)" 阻塞型确认行。 +- **展示 + 落盘同轮**：Agent 在一次回复里既向用户展示"我要建的任务是什么"，又立即完成 `.task/` 目录写入；用户看到时任务已建，可选择接下来说"不对，改一下"来触发调整。 +- **例外触发门槛**：默认无阻塞，只在明确歧义/矛盾（Q2 触发条件、Q3 y/n、Q4 Template 变更）时才停下来，且门槛必须**可机器判定**（如"3 处以上 TBD 标记"）。 +- **Agent 代跑**：Agent 在同一轮回复内主动调用 Bash / Write / Edit 等工具完成操作，无需用户输入"go / y / 继续"。 +- **场景 A / 场景 B**：Q4 中依据 `coreUpdateAvailable` / `templateUpdateAvailable` 组合区分的两条更新路径。 + +## 验收标准 + +### skill / rule 文本层面 + +1. **`f2s-req-clarify` SKILL.md**： + - 「结束（澄清文档落盘 → 自动衔接技术方案）」段落中的示例提示行改为过渡口吻（"→ 继续生成技术方案"），并显式声明"该行仅作过渡不等待任何回复"； + - 三个例外条款（未决问题 / 用户停步语 / 显式指定后续动作）保留不变。 +2. **`f2s-req-plan` SKILL.md**： + - 步骤 2 标题从「输出草稿并确认（必须主 agent）」改为「同轮展示 + 落盘（主 agent）」； + - 删除"等待用户确认"和"未确认前禁止创建 `.task/`"的硬阻塞措辞； + - 新增例外条款：仅在用户输入明显歧义/矛盾时停下来一次； + - 「## 约束」章节删除"步骤 2 必须主 agent；未确认禁止落盘"，替换为"步骤 2 同轮完成展示与落盘；除歧义例外不停"。 +3. **`f2s-implement-tech-design.md` rule**： + - 步骤 3 标题从「实现前提问（必做，不可跳过）」改为「实现前提问（条件触发）」； + - 明确列出触发门槛（3 处以上未决标记 / 关键字段完全缺失 / 用户停步语）； + - 「## 五、约束与小结」删除"不得跳过步骤 3（实现前提问）直接编码"这一句。 +4. **`f2s-kb-sync` SKILL.md**： + - 步骤 2《更新大纲》骨架从 8 项改为 3 段主体 + `
` 折叠详情（示例见流程 3）； + - 保留"未确认前禁止落盘修改"这一条不动； + - 「## 输出摘要格式」的收尾摘要格式同步简化为 3 段风格。 +5. **`f2s-flow2spec-unified-entry.md` rule**（统一入口）： + - 「知识库版本自检」小节调整措辞：明确 Core 更新场景 Agent **可主动代跑** `flow2spec update --cli` + init，无需用户确认；Template 更新场景仍需征询用户后再动。 +6. **`hooks/f2s-update-check.js`**： + - `buildNotice()` 场景 A（仅 Core 更新）的 agent-instruction 措辞从"可执行"改为"须直接代跑（无需二次确认），跑前告知用户一行'正在自动更新 CLI/Core，不涉及知识库主题变更'"； + - 场景 B（Template 更新）保持"提示用户"的口径不变。 + +### 分发与验证 + +7. **落盘位置**：所有变更**只写 `packages/core/templates/zh-CN/` + `packages/core/templates/en-US/`**（双语同步）；由 `sync-core-templates.js` 保持 `packages/core/templates/` 副本；本仓专属规则（`repo-dev-workflow-constraints.md`）**不动**。 +8. **配置根不手改**：`.claude/skills/*` / `.claude/rules/*` / `.claude/hooks/*` / `.cursor/*` / `.codex/*` / 根 `AGENTS.md` 中由 templates 派生的文件本次**不直接编辑**；由 `flow2spec init` 分发。 +9. **用户分发**：改完 templates 后 Agent **不主动跑** `flow2spec init` / `sync:agents`；回复里提示用户"改完 templates，请执行 `npm run sync:agents` 或 `node ./cli.js init codex claude cursor` 分发"。 +10. **同步 core templates**：改完根 `templates/` 后需要跑 `npm run sync:core-templates`（或依赖 `prepack` 自动同步）；如未同步可先跑 `npm run sync:core-templates:check` 校验漂移。 +11. **烟测**： + - Q1 场景：新起会话让 Agent 走一次澄清 → 检查是否自动进入技术方案生成且过渡行为一行式不阻塞； + - Q2 场景：让 Agent 用一个短需求走 `f2s-req-plan`，检查是否**跳过草稿确认**直接落 `.task/active/`； + - Q3 场景：让 Agent 触发 `f2s-kb-sync`，观察大纲是否为 3 段主体 + 详情折叠； + - Q4 场景 A：伪造 `.Knowledge/update-check.json`（core 有更新、template 未变），观察 SessionStart 后 Agent 是否直接代跑 update + init； + - Q4 场景 B：伪造 template 有更新的缓存，观察 Agent 是否走"询问用户 + f2s-kb-upgrade"路径。 + +## 未决问题 + +无（Q1–Q5 均已明确，无关键项待答）。 + +## 相关资料 + +- `.claude/skills/f2s-req-clarify/SKILL.md`（现行澄清 skill） +- `.claude/skills/f2s-req-plan/SKILL.md`（现行任务规划 skill） +- `.claude/rules/f2s-implement-tech-design.md`（现行实现 rule） +- `.claude/skills/f2s-kb-sync/SKILL.md`（现行 KB 同步 skill） +- `.claude/hooks/f2s-update-check.js`（现行 update-check hook，新版已到位） +- `.claude/rules/f2s-flow2spec-unified-entry.md`（统一入口，知识库版本自检小节） +- `.claude/rules/repo-dev-workflow-constraints.md`（本仓开发纪律，规定只改 templates） +- GitHub Issue #38（sync skill 反馈复杂度） +- Session `ff3c3636-0689-47f2-818a-87a18d73850d`（Q1 场景来源） diff --git a/.claude/hooks/f2s-update-check.js b/.claude/hooks/f2s-update-check.js index 208c7b8..561dbbc 100644 --- a/.claude/hooks/f2s-update-check.js +++ b/.claude/hooks/f2s-update-check.js @@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; const PACKAGE_NAME = '@double-coding/flow2spec-core'; -const GENERATED_CORE_VERSION = '3.7.2'; -const GENERATED_TEMPLATE_VERSION = '3.6.2'; +const GENERATED_CORE_VERSION = '3.8.0'; +const GENERATED_TEMPLATE_VERSION = '3.7.0'; function readJson(file) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; } diff --git a/.codex/hooks/f2s-update-check.js b/.codex/hooks/f2s-update-check.js index 208c7b8..561dbbc 100644 --- a/.codex/hooks/f2s-update-check.js +++ b/.codex/hooks/f2s-update-check.js @@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; const PACKAGE_NAME = '@double-coding/flow2spec-core'; -const GENERATED_CORE_VERSION = '3.7.2'; -const GENERATED_TEMPLATE_VERSION = '3.6.2'; +const GENERATED_CORE_VERSION = '3.8.0'; +const GENERATED_TEMPLATE_VERSION = '3.7.0'; function readJson(file) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; } diff --git a/.cursor/hooks/f2s-update-check.js b/.cursor/hooks/f2s-update-check.js index 208c7b8..561dbbc 100644 --- a/.cursor/hooks/f2s-update-check.js +++ b/.cursor/hooks/f2s-update-check.js @@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json'); const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__'; const PACKAGE_NAME = '@double-coding/flow2spec-core'; -const GENERATED_CORE_VERSION = '3.7.2'; -const GENERATED_TEMPLATE_VERSION = '3.6.2'; +const GENERATED_CORE_VERSION = '3.8.0'; +const GENERATED_TEMPLATE_VERSION = '3.7.0'; function readJson(file) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; } diff --git a/packages/core/templates/en-US/hooks/f2s-update-check.js b/packages/core/templates/en-US/hooks/f2s-update-check.js index 1165600..36f1cfa 100644 --- a/packages/core/templates/en-US/hooks/f2s-update-check.js +++ b/packages/core/templates/en-US/hooks/f2s-update-check.js @@ -93,17 +93,24 @@ function buildNotice(state) { return [ '[flow2spec/agent-instruction] At the start of this response, relay this update notice to the user:', '', - `📦 [flow2spec] Project "${project}" has a template update (${versionSummary}).`, + `📦 [flow2spec] Project "${project}" has a template update (${versionSummary}). Template changes affect the knowledge-base topic layout and require user confirmation before proceeding.`, '', - '[flow2spec/agent-instruction] You may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep), then `flow2spec init `. After init, read `.Knowledge/manifest-routing.json`: if projectRev equals pkgRev, delete `.Knowledge/update-check.json`; otherwise continue with f2s-kb-upgrade from step 2c.', + '[flow2spec/agent-instruction] Recommended flow (do NOT skip user confirmation):', + '1. Ask the user whether to run `flow2spec update --cli` + `flow2spec init ` on their behalf (if the global CLI is missing, fallback to `npx @double-coding/flow2spec update --cli`).', + '2. On user consent: run them; after init, read `.Knowledge/manifest-routing.json` — if projectRev equals pkgRev, delete `.Knowledge/update-check.json` and stop; otherwise invoke the f2s-kb-upgrade skill (may resume from its step 2c).', + '3. On user decline: keep the cache untouched and continue the current task.', ].join('\n'); } return [ - '[flow2spec/agent-instruction] At the start of this response, relay this update notice to the user:', + '[flow2spec/agent-instruction] At the start of this response, execute the following actions **without asking the user** (Core-only updates do not affect knowledge-base topics):', '', - `📦 [flow2spec] Project "${project}" has a Core-only update (${versionSummary}); the template version is unchanged.`, + `1. Tell the user in one line: "Auto-updating CLI/Core (${versionSummary}); knowledge-base topics are unchanged.";`, + '2. Invoke Bash to run `flow2spec update --cli`; if it fails because the global CLI is missing, fallback to `npx @double-coding/flow2spec update --cli`; if that still fails, report the command and error summary in one line and continue the current task without blocking;', + '3. On success, invoke `flow2spec init ` (idempotent) to refresh the config-root Hook;', + '4. Delete `.Knowledge/update-check.json` afterwards;', + `5. Report completion in one line: "CLI/Core updated; Template Version unchanged (v${state.manifestVersion}); continuing the current task."`, '', - '[flow2spec/agent-instruction] You may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep), then one idempotent `flow2spec init ` to refresh the Hook. Do not enter f2s-kb-upgrade when Template Version is unchanged; delete `.Knowledge/update-check.json` afterwards.', + `📦 [flow2spec] Project "${project}" has a Core-only update (${versionSummary}); the template version is unchanged. Template Version is unchanged — **do NOT** enter f2s-kb-upgrade.`, ].join('\n'); } diff --git a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md index ab15647..434f43b 100644 --- a/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md @@ -98,7 +98,10 @@ Each initialized client uses its own startup/update mechanism when supported; th **Rule-layer fallback check** (backup for script cache): 1. Read `flow2spec.config.json` -> if `updateCheck.enabled` is not `true`, skip and show no notice. -2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is on the same local calendar day, do not query npm again. When `coreUpdateAvailable=true`, the agent may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep). If `templateUpdateAvailable=false`, run one idempotent `flow2spec init ` to refresh the Hook, delete the cache, and do not enter `f2s-kb-upgrade`. If `templateUpdateAvailable=true`, update first, run init, then use `projectRev` / `pkgRev` to choose the fast path or full flow. `.Knowledge/manifest-routing.json.version` is Template Version and must not be compared directly with Core Version. +2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is on the same local calendar day, do not query npm again. Handle two scenarios separately: + - **`coreUpdateAvailable=true` and `templateUpdateAvailable=false`** (Core-only update): the agent **must actively run** `flow2spec update --cli` (fallback to `npx @double-coding/flow2spec update --cli` if the global CLI is missing; if that still fails, report in one line and continue without blocking) + one idempotent `flow2spec init ` at the start of this turn to refresh the Hook. Before running, tell the user in one line "Auto-updating CLI/Core; knowledge-base topics are unchanged". Afterwards delete `.Knowledge/update-check.json`, **do NOT** enter `f2s-kb-upgrade`, and **do NOT ask the user for confirmation** (Core-only updates do not affect knowledge-base topics). + - **`templateUpdateAvailable=true`** (Template changed; Core may also have changed): the agent **must** relay the notice at the start of the turn **and ask the user whether to run** update + init. On consent, run `flow2spec update --cli` + init, then use `projectRev` / `pkgRev`: equal -> delete the cache and stop; unequal -> invoke the `f2s-kb-upgrade` skill (may resume from its step 2c). + - `.Knowledge/manifest-routing.json.version` is Template Version and must not be compared directly with Core Version. 3. If neither of the two steps above skipped the check: run the update-check script under the current agent configuration root (Claude: `node .claude/hooks/f2s-update-check.js`; Cursor: `node .cursor/hooks/f2s-update-check.js`; Codex: `node .codex/hooks/f2s-update-check.js`) and parse JSON from stdout: - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content and follow its separate Core-only or Template-update instructions. - If there is no output or parsing fails: stay silent. diff --git a/packages/core/templates/en-US/rules/f2s-implement-tech-design.md b/packages/core/templates/en-US/rules/f2s-implement-tech-design.md index 4c068ef..1373dd7 100644 --- a/packages/core/templates/en-US/rules/f2s-implement-tech-design.md +++ b/packages/core/templates/en-US/rules/f2s-implement-tech-design.md @@ -94,9 +94,19 @@ If `changeTracking.implement: true`, after outputting the task list, write this - Whenever work corresponding to an implementation task-list item is completed, use `Edit` **in the same session** to update the corresponding `[ ]` -> `[x]` in `.task/active//task.md`. Do not defer this to closing, and do not replace disk updates with verbal completion claims (see `f2s-task` "During execution" and "Interruption and session end"). - Whenever an item appears during execution that **must be done by the user** (database changes, environment configuration, etc.), append it **in the same session** to `.task/active//user-todos.md` (see `f2s-task` "user-todos.md"). -### Step 3: Ask Pre-Implementation Questions (Mandatory; Do Not Skip) +### Step 3: Ask Pre-Implementation Questions (Conditional; Skipped by Default) -Before coding, list all unclear items at once and ask the user to confirm. Common questions: +**Default**: do not stop to ask; proceed directly to Step 4. Items not clearly defined in the design are implemented with reasonable defaults or placeholders and marked as "requires user confirmation" in the Step 5 pending list. + +**Trigger conditions** (any one match causes a single stop to list open questions and wait for the user before continuing): + +- The design text contains **≥ 3** explicit "undecided" markers such as `待定 / 待确认 / TBD / \?\?\?`; +- Key contract sections of the design are **entirely missing** (not merely "insufficiently detailed") — for example, the design references APIs but has no API-signature section at all, references data but has no data-model section at all, or references a state machine but has no state list at all; +- The user explicitly says a stop phrase such as "only list the tasks / don't rush the implementation / let me review the list first / discuss the plan first". + +When triggered, list 3–6 open questions that most affect where implementation lands (draw from the common items below), and ask the user to confirm all of them at once. When not triggered, **do NOT ask** — proceed directly to Step 4. + +**Common question items** (pick from these when a trigger condition is met): - **Scope and acceptance**: what must be delivered in this turn, and what is explicitly out of scope; - **Technical boundary**: which module/side to implement in (frontend, backend, script, data task, etc.); @@ -105,8 +115,6 @@ Before coding, list all unclear items at once and ask the user to confirm. Commo - **Flowchart gaps**: branch conditions, failure fallback, timeout and retry strategy; - **Release constraints**: whether routing, permissions, scheduling, and deployment steps are ready. -If the user does not answer an item, implement using a reasonable default or placeholder and mark it as "requires user confirmation" in the pending list. - ### Step 4: Implement According to the Task List Trim the order according to the design and the actual project. Recommended sequence: @@ -139,7 +147,7 @@ Requirements: reuse existing dependencies and wrappers; match project naming, di ## 5. Constraints and Summary - PDFs must be converted to MD before entering the implementation flow. -- Do not skip step 2.5 (task list) or step 3 (pre-implementation questions) and code directly. +- Do not skip step 2.5 (task list); step 3 is conditional (skipped by default, and only triggers a single stop when an ambiguity threshold is hit). - If `changeTracking.implement: true`: do not skip step 2.6 (write back `task.md` checkboxes as implementation progresses and append `user-todos.md`); archiving must satisfy the `f2s-task` archive gate. - The output must include a pending list and post-implementation reminder list. If `changeTracking.implement: true`, user-side items in those lists must be synced into `user-todos.md`. - Keep the content general. Do not assume a "backend only" scenario; trim implementation objects according to the design's actual scope. diff --git a/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md index 2e91a96..0af7e5c 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md @@ -50,22 +50,55 @@ This skill must not make manual command execution part of the user flow. After t ### Step 2: Output the "Update Outline" (Required) -The outline must include at least: - -1. Sync goal. -2. Capability list (user-specified / Agent-inferred / merged result). -3. Information sources. -4. Proposed file-change list (exact paths). -5. Topic sync plan: for each capability, state whether it updates an existing topic or creates a new topic, and list topicId, topic file, index row, and manifest/matcher changes. If `topicMetadata` is involved, list candidate `primary` / `tags` / `confidence` and evidence; if evidence is unclear, write "do not classify / do not write for now". -6. **Stock-doc consolidation plan (hard rule)**: For every topic being "created / updated", check whether its "Detailed background / Related materials / Long-form source / Reference documents" reference slot already has a corresponding `.Knowledge/stock-docs/*_终稿.md`: - - **Exists** → reference it directly; - - **Missing but the capability being synced is already implemented in code** → the outline **must list** "generate `stock-docs/_终稿.md`", noting the consolidation sources (the matching `req-docs/*_技术方案.md` + implemented code + clarification doc). Before step 3, this SKILL first triggers `f2s-doc-final` to consolidate (or waits for user confirmation to hand-write), **then** points the topic to the stock-doc; - - **Capability is still at the req-docs stage without code** → the topic's "Long-form background" section writes a placeholder "to be generated by `f2s-doc-final` after the code lands". **Do not** list `req-docs/*` in this slot. - - Basis: see `rules/f2s-topic-authoring.*` "Directory boundary for long-form background references (hard rule)". -7. Out-of-scope items. -8. Prompt to wait for user confirmation. - -> Before confirmation, writing any changes is forbidden. +The outline uses a **3-block main body + collapsible details** structure so the user can grasp "what's in / what's changed / what's out" at a glance and expand details on demand. Goal: **high signal density with visual focus on decision points** (Issue #38). + +**Output skeleton** (the Agent fills in the actual content per this structure): + +````markdown +## KB Sync Outline + +### 📥 In +- ``: (→ `.Knowledge/topics/.md`) +- **New** ``: (→ new topic + matcher + routing entry) + +### 🚫 Out +- : (e.g., "pure refactor, no new semantics / already covered by another topic / duplicate") + +### Continue? (y/n) + +
+Expand details + +**Proposed file changes**: +- `.Knowledge/topics/.md` +- `.Knowledge/index.md` +- `.Knowledge/manifest-routing.json` +- `.Knowledge/matchers/.json` + +**Topic metadata** (if any): +- ``: primary=``, tags=`[...]`, confidence=`` + +**Stock-doc consolidation** (if needed): +- To generate `stock-docs/_终稿.md` (sources: `req-docs/.md` + implemented code + clarification doc) + Basis: see `rules/f2s-topic-authoring.*` "Directory boundary for long-form background references (hard rule)". + +**Information sources**: + +**Out of scope**: + +
+```` + +**Writing rules**: + +- 3-block main body: 📥 In / 🚫 Out / Continue? (y/n); keep each block within **1–5 lines**; scannable at a glance. +- Details are folded via `
` and include: proposed file changes, topic metadata, stock-doc consolidation plan, information sources, out-of-scope items. The fold is a **verifiability** safeguard — it must not be omitted, but it must not occupy the main visual focus either. +- **The write gate is unchanged**: the user must still reply `y/n` before disk writes (this reform only changes wording, not the gate). Before confirmation, disk writes are forbidden. +- **Stock-doc consolidation (hard rule)**: When creating or updating a topic, if the "Long-form background / Related materials" reference slot lacks a corresponding `.Knowledge/stock-docs/*_终稿.md`: + - Code has landed → list "generate `stock-docs/_终稿.md`" in the details block; Step 2.5 triggers `f2s-doc-final` to consolidate; + - Code not yet landed → the topic's "Long-form background" section writes a placeholder "to be generated by `f2s-doc-final` after the code lands"; **do not** list `req-docs/*` in this slot. + +> Before confirmation (y), disk writes are forbidden. ### Step 2.5: Consolidate Stock-Docs (If Step 2 Listed Any) @@ -115,22 +148,29 @@ After this skill successfully writes to disk (Step 3 actually modified files), t ## Output Summary Format (Recommended) -```markdown -## Knowledge-Base Sync Result +Uses the same **3-block main body + collapsible details** structure as Step 2 outline: -### Confirmed Capability Scope -- -- +```markdown +## KB Sync Result -### Modified Files -- .Knowledge/topics/.md: -- .Knowledge/index.md: -- .Knowledge/manifest-routing.json: -- .Knowledge/matchers/.json: -- .Knowledge/stock-docs/.md: +### ✅ Modified +- `.Knowledge/topics/.md`: +- `.Knowledge/index.md`: -### Skipped Items +### ⏭️ Skipped - : + +
+Expand details + +**Other modified paths**: +- `.Knowledge/manifest-routing.json`: +- `.Knowledge/matchers/.json`: +- `.Knowledge/stock-docs/.md`: + +**Capability scope**: + +
``` ## Complex Scenario Example diff --git a/packages/core/templates/en-US/skills/f2s-req-clarify/SKILL.md b/packages/core/templates/en-US/skills/f2s-req-clarify/SKILL.md index 62d886f..19c4655 100644 --- a/packages/core/templates/en-US/skills/f2s-req-clarify/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-req-clarify/SKILL.md @@ -19,7 +19,12 @@ description: Clarify a PRD or requirement through follow-up questions until it i **Completion (write clarification doc → auto-chain to technical design)**: When the information is clear enough, output a Markdown "requirement clarification document" that can be written directly to disk. The document must include at least: background and goals, scope (included / excluded), key flows, boundaries and exceptions, key concept definitions, acceptance criteria, and open questions if any. Save it under `.Knowledge/req-docs/` (recommended name: `_需求澄清.md`). -**After the clarification document is written to disk, this skill auto-chains to `f2s-req-tech` within the same turn**: feed the just-written clarification path directly into technical-design generation without waiting for another user trigger. Before chaining, emit a one-line notice "Clarification document ready: ``; proceeding to generate the technical design via `f2s-req-tech`", then continue. +**After the clarification document is written to disk, this skill auto-chains to `f2s-req-tech` within the same turn (Agent does NOT ask the user for confirmation)**: feed the just-written clarification path directly into technical-design generation. After the write, **the Agent emits within the same turn** one line of **transitional notice** (example: "Clarification document ready: `` → continuing to generate the technical design."), then **immediately in the same turn** invokes `f2s-req-tech`. + +**Transitional-line hard constraints**: +- Use forward-arrow "→" or "continuing" style **push-forward wording**; +- **Do NOT** use waiting or interrogative wording such as "shall I / please confirm / awaiting your reply / okay? / proceeding to generate ..." (the last one reads as a status stall); +- After emitting the transitional line, the Agent **must NOT** stop tool calls in the same turn to wait for user input; it must immediately fire the `f2s-req-tech` invocation. **Exceptions — stay at clarification, do NOT auto-chain to technical design** (any one triggers a stop): - The clarification document's "open questions" section still has items that materially shape the design structure (e.g., core contracts for tables / APIs / state machines are undefined) — in that case, list the remaining questions, wait for answers, then write and chain; diff --git a/packages/core/templates/en-US/skills/f2s-req-plan/SKILL.md b/packages/core/templates/en-US/skills/f2s-req-plan/SKILL.md index f9eb769..1939f3a 100644 --- a/packages/core/templates/en-US/skills/f2s-req-plan/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-req-plan/SKILL.md @@ -24,7 +24,7 @@ Start from a requirement or technical design and cover the full "plan -> impleme - `subAgent` / `switchAgentVerification` use the unified entry as the only source of truth: **Cursor/Claude** -> `rules/f2s-flow2spec-unified-entry.*`; **Codex** -> `.codex/topics/f2s-flow2spec-unified-entry.md`. - **Step 1 (continuation triage + parsing)**: the main agent must perform `f2s-task` "Task Start" 1-2. Document parsing may be split to a sub agent (read-only). -- **Step 2 (draft confirmation)**: must be handled by the main agent. Before confirmation, do not create `.task/` and do not write business code. +- **Step 2 (show + write in the same turn)**: must be handled by the main agent; **does NOT wait for user confirmation by default**. Show the draft and write files within the same turn. The agent stops only when the "ambiguity exceptions" listed in Step 2 body are hit. - **Step 3 (write task files)**: follow `f2s-task` "Task Start" 3.a-3.f. `todo.json` is **main-agent only**. Drafts of `task.md` / `context.md` / `user-todos.md` may be created by a sub agent; additions to `user-todos.md` during execution are merged by the main agent. - **Step 4 (implementation)**: sub agents may write only business code. **Sub agents must not** write `todo.json` or modify `task.md` checkboxes. The main agent checks off items after merging. - **Step 5 (archive)**: main agent only. Execute only after the archive gates in `f2s-task` "Task Completion" are satisfied. @@ -65,21 +65,29 @@ When `subAgent=true`, read-only parsing may be split to sub agents: Sub agents return only a "parsing summary"; when `subAgent=false`, the main agent does this work. -> **Step 2**. -### Step 2: Output Draft and Confirm (Main Agent Required) +### Step 2: Show + Write in the Same Turn (Main Agent, No Waiting) -The main agent outputs: +The main agent performs "show to user" and "write files" **within the same reply turn**, **without stopping to wait for a confirmation**: -1. **Task name** (`snake_case`) -2. **Implementation checklist draft** (each step may be a checkbox and will be written into `task.md` under `## Steps`) -3. **Touched file list** (will be written into `context.md`) -4. **Suggested `keywords`** (2-5 terms for continuation matching in `todo.json`) -5. **Wait for user confirmation** +1. **Show** (output in the reply for the user to review): + - Task name (`snake_case`) + - Implementation checklist draft (each step as `- [ ]`, to be written into `task.md` under `## Steps`) + - Touched file list (to be written into `context.md`) + - Suggested `keywords` (2-5 terms for continuation matching in `todo.json`) +2. **Write** (execute in the same turn, immediately after showing): strictly create the full `TASK_ROOT/active//` set of files and update `todo.json` per Step 3 below. +3. Show and write **must happen in the same turn** — when the user reads the Step 2 summary, the task already exists on disk. The user can adjust it by saying "rename / add a step / drop step 3". -> Before confirmation, it is forbidden to create `.task/`, write `todo.json`, or write business code. +**Ambiguity exception (the ONLY stop condition)**: only when **any** of the following is true, the main agent switches to "output draft + list open questions once + stop" and waits for user answers before proceeding to Step 3: + +- The user input or design document contains **≥ 3** explicit "undecided" markers such as `待定 / 待确认 / TBD / \?\?\?`; +- The user input does not specify which module / end / files this task should touch, and the design document also lacks a scope section; +- The user explicitly says a stop phrase such as "only list the tasks / don't rush the implementation / let me review the list first / discuss the plan first". + +When none of the exceptions fires, **do NOT stop and wait** — even if the user input is brief, write files with a reasonable default draft and let the user trigger adjustments after seeing the result. ### Step 3: Write Task Files (`f2s-task` "Task Start" 3.a-3.f) -After the user confirms, **strictly follow `f2s-task`** (the format is defined by that rule body; do not omit files): +Execute in the **same turn** right after Step 2 shows the draft (no user confirmation required), **strictly following `f2s-task`** (the format is defined by that rule body; do not omit files): | Sub-step | Action | Write authority | | --- | --- | --- | @@ -137,7 +145,7 @@ After passing: - **Step 0**: must first `Read` `flow2spec.config.json` + the **full `f2s-task` text** (three-client paths above). - **`.task/`**: always obey `f2s-task`; this SKILL must not conflict with it. - Does not depend on `changeTracking`, but **always** creates and maintains a task list (unless continuing an existing active task). -- Step 2 must be handled by the main agent; before confirmation, no disk writes. +- Step 2 must be handled by the main agent; **does not wait for user confirmation by default** — show and write happen in the same turn; the agent stops only when an ambiguity exception is hit. - `todo.json` is main-agent only; sub agents must not write it. - No batch checkbox updates; do not skip `user-todos.md`. diff --git a/packages/core/templates/zh-CN/hooks/f2s-update-check.js b/packages/core/templates/zh-CN/hooks/f2s-update-check.js index bb8e36c..432f3fc 100644 --- a/packages/core/templates/zh-CN/hooks/f2s-update-check.js +++ b/packages/core/templates/zh-CN/hooks/f2s-update-check.js @@ -93,17 +93,24 @@ function buildNotice(state) { return [ '[flow2spec/agent-instruction] 你必须在本轮回复开头转告用户以下更新提示：', '', - `📦 [flow2spec] 当前项目「${project}」有模板更新（${versionSummary}）。`, + `📦 [flow2spec] 当前项目「${project}」有模板更新（${versionSummary}）。Template 变更会影响知识库主题结构，须征询用户后再动。`, '', - '[flow2spec/agent-instruction] 可先执行 `flow2spec update --cli`（CLI 与配套 Core 联动更新），再执行 `flow2spec init <已初始化的 agents>`。init 后读取 `.Knowledge/manifest-routing.json`：projectRev 与 pkgRev 相等则更新完成并删除 `.Knowledge/update-check.json`；不等时再执行 f2s-kb-upgrade（可从步骤 2c 继续）。', + '[flow2spec/agent-instruction] 建议流程（不得跳过用户询问）：', + '1. 询问用户是否代跑 `flow2spec update --cli` + `flow2spec init <已初始化的 agents>`（若全局 CLI 缺失，fallback `npx @double-coding/flow2spec update --cli`）；', + '2. 用户同意 → 代跑；init 后读 `.Knowledge/manifest-routing.json`：projectRev 与 pkgRev 相等则删除 `.Knowledge/update-check.json` 结束；不等则调用 f2s-kb-upgrade skill（可从其步骤 2c 起继续）；', + '3. 用户拒绝 → 保留缓存不动，继续本轮任务。', ].join('\n'); } return [ - '[flow2spec/agent-instruction] 你必须在本轮回复开头转告用户以下更新提示：', + '[flow2spec/agent-instruction] 你必须在本轮回复开头执行以下动作，**无需征询用户**（Core-only 更新不影响知识库主题）：', '', - `📦 [flow2spec] 当前项目「${project}」仅有 Core 程序更新（${versionSummary}），模板版本未变化。`, + `1. 用一行告知用户："正在自动更新 CLI/Core（${versionSummary}），不涉及知识库主题变更"；`, + '2. 调用 Bash 执行 `flow2spec update --cli`；若因全局 CLI 缺失失败，fallback 到 `npx @double-coding/flow2spec update --cli`；仍失败则一行报告命令原文与错误摘要后继续本轮任务，不阻塞；', + '3. 成功后调用 `flow2spec init <已初始化的 agents>`（幂等）刷新配置根 Hook；', + '4. 完成后删除 `.Knowledge/update-check.json`；', + `5. 一行报告完成："CLI/Core 更新完成，Template Version 未变（v${state.manifestVersion}），继续本轮任务。"`, '', - '[flow2spec/agent-instruction] 可执行 `flow2spec update --cli`（CLI 与配套 Core 联动更新），随后执行一次幂等 `flow2spec init <已初始化的 agents>` 刷新 Hook。Template Version 未变化，不进入 f2s-kb-upgrade；完成后删除 `.Knowledge/update-check.json`。', + `📦 [flow2spec] 当前项目「${project}」仅有 Core 程序更新（${versionSummary}），模板版本未变化。Template Version 未变，**不**进入 f2s-kb-upgrade。`, ].join('\n'); } diff --git a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md index f3feeca..9dd1a7f 100644 --- a/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md +++ b/packages/core/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md @@ -98,7 +98,10 @@ alwaysApply: true **规则层双保险**（与脚本缓存互为备份）： 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。 -2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日，不重复查 npm；`coreUpdateAvailable=true` 时可执行 `flow2spec update --cli`（CLI 与配套 Core 联动更新）。若 `templateUpdateAvailable=false`，随后只执行一次幂等 `flow2spec init <已初始化的 agents>` 刷新 Hook，删除缓存，不进入 `f2s-kb-upgrade`；若 `templateUpdateAvailable=true`，更新后执行 init，再以 `projectRev` / `pkgRev` 判定快速路径或完整流程。`.Knowledge/manifest-routing.json.version` 表示 Template Version，禁止与 Core Version 直接比较。 +2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日，不重复查 npm。按两种场景分别处理： + - **`coreUpdateAvailable=true` 且 `templateUpdateAvailable=false`**（Core-only 更新）：Agent **必须**在本轮回复开头**主动代跑** `flow2spec update --cli`（若全局 CLI 缺失，fallback `npx @double-coding/flow2spec update --cli`；仍失败则一行报告，不阻塞）+ 幂等 `flow2spec init <已初始化的 agents>` 刷新 Hook，跑前告知用户一行"正在自动更新 CLI/Core，不涉及知识库主题变更"，跑完删除 `.Knowledge/update-check.json`，**不进入** `f2s-kb-upgrade`，**无需征询用户**（Core-only 不影响知识库主题）。 + - **`templateUpdateAvailable=true`**（Template 变更，可能同时 Core 也变）：Agent **必须**在本轮回复开头转告用户提示，**并询问用户是否代跑**；用户同意后代跑 `flow2spec update --cli` + init，然后按 `projectRev` / `pkgRev` 判定：相等则删除缓存结束；不等则进入 `f2s-kb-upgrade` skill（可从其步骤 2c 起继续）。 + - `.Knowledge/manifest-routing.json.version` 表示 Template Version，禁止与 Core Version 直接比较。 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`：**告知用户**该内容，并按其中 agent-instruction 分别处理 Core-only 与 Template 更新。 - 无输出或解析失败：静默，不提示。 diff --git a/packages/core/templates/zh-CN/rules/f2s-implement-tech-design.md b/packages/core/templates/zh-CN/rules/f2s-implement-tech-design.md index ea6a7f0..28bff1a 100644 --- a/packages/core/templates/zh-CN/rules/f2s-implement-tech-design.md +++ b/packages/core/templates/zh-CN/rules/f2s-implement-tech-design.md @@ -94,9 +94,19 @@ alwaysApply: false - 每完成实现任务列表中一项对应工作，**同一会话内**用 `Edit` 更新 `.task/active//task.md` 中对应 `[ ]`→`[x]`，禁止积压到收尾、禁止口头完成代替写盘（见 `f2s-task`「执行中」「中断与会话结束」）。 - 执行过程中每出现**须用户执行**的项（改库、配环境等），**同会话内**追加到 `.task/active//user-todos.md`（见 `f2s-task`「user-todos.md」）。 -### 步骤 3：实现前提问（必做，不可跳过） +### 步骤 3：实现前提问（条件触发，默认跳过） -进入编码前，必须一次性列出未明确项并请用户确认。常见问题： +**默认**：不停下提问，直接进入步骤 4 实现。方案文档未明确的细节按合理默认或占位实现，并在步骤 5 待完成列表中标注"需用户确认"。 + +**触发条件**（任一命中即停下来一次性列出问题，等用户回答后再继续）： + +- 方案文本中 `待定 / 待确认 / TBD / \?\?\?` 类明确未决标记 **≥ 3 处**； +- 方案关键契约字段**整节缺失**（不是"不够详尽"）——例如涉及接口但完全没有接口签名章节、涉及数据但完全没有数据模型章节、涉及状态机但完全没有状态列表； +- 用户明确说"先只列任务 / 别急着实现 / 让我先看看清单 / 先讨论方案"等停步语。 + +命中时一次性列出 3–6 条最影响实现落笔的问题（可参考下列常见项），一并请用户确认；未命中一律**不问**、直接进入步骤 4。 + +**常见问题项**（命中触发条件时可从中挑选）： - **范围与验收**：本次必须交付什么，哪些明确不做； - **技术边界**：实现在哪个模块/端（前端、后端、脚本、数据任务等）； @@ -105,8 +115,6 @@ alwaysApply: false - **流程图缺口**：分支条件、失败回退、超时与重试策略； - **发布约束**：路由、权限、调度、部署步骤是否已具备。 -若用户未回复某项：按合理默认或占位实现，并在待完成列表中标注“需用户确认”。 - ### 步骤 4：按任务列表实现 按方案与项目实际裁剪顺序，建议： @@ -139,7 +147,7 @@ alwaysApply: false ## 五、约束与小结 - PDF 必须先转 MD，再进入实现流程； -- 不得跳过步骤 2.5（任务列表）与步骤 3（实现前提问）直接编码； +- 不得跳过步骤 2.5（任务列表）；步骤 3 按条件触发（默认跳过，命中歧义门槛才停下提问）； - 若 `changeTracking.implement: true`：不得跳过步骤 2.6（随实现进度写回 `task.md` checkbox，并追加 `user-todos.md`）；归档须满足 `f2s-task` 归档门禁； - 输出中必须包含待完成列表与实现后提醒清单；若 `changeTracking.implement: true`，其中用户侧项须同步写入 `user-todos.md`； - 内容保持通用，不预设“仅后端”场景，按方案实际范围裁剪实现对象。 diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md index 922569a..2394166 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-sync/SKILL.md @@ -50,22 +50,55 @@ description: 可显式给出能力或零输入推断；先输出知识库更新 ### 步骤 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. 等待用户确认提示 - -> 未确认前禁止落盘修改。 +大纲**采用 3 段主体 + 折叠详情**结构，让用户一眼看清"入哪 / 改什么 / 不入哪"，细节按需展开。目标是**信号密度高、视觉焦点在决策点**（Issue #38）。 + +**输出骨架**（Agent 按此结构填充实际内容）： + +````markdown +## 知识库同步大纲 + +### 📥 入库 +- ``：<一句话说明改了什么>（→ `.Knowledge/topics/.md`） +- **新建** ``：<能力概述>（→ 新增 topic + matcher + 路由条目） + +### 🚫 不入库 +- <能力/变更>：<一句话原因>（如"仅代码重构无新语义 / 属于 fix 已在其他 topic 覆盖 / 与既有 topic 重复"） + +### 是否继续？(y/n) + +
+展开查看详情 + +**拟改文件**： +- `.Knowledge/topics/.md` +- `.Knowledge/index.md` +- `.Knowledge/manifest-routing.json` +- `.Knowledge/matchers/.json` + +**主题元数据**（如有）： +- ``：primary=``，tags=`[...]`，confidence=`` + +**终稿沉淀**（如需）： +- 待生成 `stock-docs/<能力名>_终稿.md`（来源：`req-docs/<方案>.md` + 已实现代码 + 澄清文档） + 依据见 `rules/f2s-topic-authoring.*`「长文背景引用的目录边界（硬约束）」。 + +**信息来源**：<用户指定 / Agent 推断 / git diff / 目录扫描> + +**不改动范围**：<列出本次刻意跳过的项与原因> + +
+```` + +**书写规则**： + +- 主体 3 段：📥 入库 / 🚫 不入库 / 是否继续？(y/n)；每段控制在 **1–5 行**；一眼可扫。 +- 详情用 `
` 折叠，包含：拟改文件、主题元数据、终稿沉淀计划、信息来源、不改动范围；折叠段是**可核查性**保障，不能省略但不占主视觉。 +- **入库门禁不变**：用户仍需回复 `y/n` 才落盘（本改造只改文案不改门禁）；未确认前禁止落盘修改。 +- **终稿沉淀（硬约束）**：新建 / 更新 topic 时，若「长文背景 / 详细资料」引用槽位缺对应 `.Knowledge/stock-docs/*_终稿.md`： + - 代码已落地 → 详情段列"待生成 `stock-docs/<能力名>_终稿.md`"，由步骤 2.5 触发 `f2s-doc-final` 沉淀； + - 代码尚未落地 → topic 「长文背景」小节暂写占位说明「待代码落地后由 `f2s-doc-final` 生成 stock-doc 终稿」，**禁止**在此槽位直接列 `req-docs/*`。 + +> 未确认（y）前禁止落盘修改。 ### 步骤 2.5：终稿沉淀（若步骤 2 列出待生成终稿） @@ -115,22 +148,29 @@ description: 可显式给出能力或零输入推断；先输出知识库更新 ## 输出摘要格式（建议） +**采用 3 段主体 + 折叠详情**，与步骤 2 大纲同构： + ```markdown ## 知识库同步结果 -### 已确认能力范围 -- <能力1> -- <能力2> +### ✅ 已修改 +- `.Knowledge/topics/.md`：<修改说明> +- `.Knowledge/index.md`：<修改说明> -### 已修改文件 -- .Knowledge/topics/.md：<修改说明> -- .Knowledge/index.md：<修改说明> -- .Knowledge/manifest-routing.json：<修改说明或“未改动”> -- .Knowledge/matchers/.json：<修改说明或“未改动”> -- .Knowledge/stock-docs/.md：<修改说明或“未改动”> - -### 未执行项 +### ⏭️ 未执行 - <项>：<原因> + +
+展开查看详情 + +**其他改动路径**： +- `.Knowledge/manifest-routing.json`：<修改说明或"未改动"> +- `.Knowledge/matchers/.json`：<修改说明或"未改动"> +- `.Knowledge/stock-docs/.md`：<修改说明或"未改动"> + +**能力范围**：<用户确认的能力清单> + +
``` ## 复杂场景示例 diff --git a/packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md index 9a23245..61e1ac4 100644 --- a/packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-req-clarify/SKILL.md @@ -19,7 +19,12 @@ description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-tech 出技 **结束（澄清文档落盘 → 自动衔接技术方案）**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`（推荐命名 `<能力名>_需求澄清.md`）。 -**澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`**：以刚落盘的澄清文档路径为输入直接进入技术方案生成，无需等用户再次触发；进入前给用户一行提示「澄清文档已就绪：`<路径>`；正在按 `f2s-req-tech` 生成技术方案」，然后继续。 +**澄清文档落盘后本技能同轮自动衔接 `f2s-req-tech`（Agent 无需征询用户）**：以刚落盘的澄清文档路径为输入直接进入技术方案生成。落盘后 **Agent 在同一轮回复内**输出一行**过渡型提示**（示例："澄清文档已就绪：`<路径>` → 继续生成技术方案。"），然后**当轮立即**调用 `f2s-req-tech`。 + +**过渡行硬约束**： +- 使用箭头"→"或"继续"等**推进型措辞**； +- **禁止**使用"是否 / 请确认 / 等您回复 / 可以吗 / 正在按 X 生成"等等待型或询问型措辞； +- Agent 输出过渡行后**不得**在同一轮内停止工具调用等待用户输入，必须紧接着发起 `f2s-req-tech` 的执行动作。 **例外——停在澄清、不自动衔接技术方案**（任一命中即停）： - 澄清文档「未决问题」小节仍有影响方案结构的关键项未回答（如库/表/接口/状态机主契约缺定义），此时输出一段说明列出待答项，等用户回答后再落盘并衔接； diff --git a/packages/core/templates/zh-CN/skills/f2s-req-plan/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-req-plan/SKILL.md index 0232fd5..91f4e43 100644 --- a/packages/core/templates/zh-CN/skills/f2s-req-plan/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-req-plan/SKILL.md @@ -24,7 +24,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 - `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/` 或写业务代码。 +- **步骤 2（同轮展示 + 落盘）**：必须主 agent；**默认不等待用户确认**，展示与落盘同一轮完成；仅命中「歧义例外」时才停下一次列问题（见步骤 2 正文）。 - **步骤 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`「任务完成」归档门禁后执行。 @@ -65,21 +65,29 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 子 agent 只交「解析摘要」；`subAgent=false` 时主 agent 完成。→ **步骤 2**。 -### 步骤 2：输出草稿并确认（必须主 agent） +### 步骤 2：同轮展示 + 落盘（主 agent，不等待确认） -主 agent 输出： +主 agent 在**同一轮回复**内同时完成"向用户展示"与"落盘"两个动作，**不停下等待用户点确认**： -1. **任务名称**（snake_case） -2. **实现清单草稿**（每步可 checkbox，将写入 `task.md` 的「## 步骤」） -3. **涉及文件列表**（将写入 `context.md`） -4. **建议 `keywords`**（2–5 个，供 `todo.json` 续作匹配） -5. **等待用户确认** +1. **展示**（在回复里输出，供用户过目）： + - 任务名称（snake_case） + - 实现清单草稿（每步 `- [ ]`，将写入 `task.md` 的「## 步骤」） + - 涉及文件列表（将写入 `context.md`） + - 建议 `keywords`（2–5 个，供 `todo.json` 续作匹配） +2. **落盘**（同轮当即执行，紧接展示动作）：按下面步骤 3 严格创建 `TASK_ROOT/active//` 全套文件 + 写 `todo.json`。 +3. 展示与落盘**必须同轮完成**——用户看到步骤 2 摘要时任务已建，可用一句话说"改一下 / 换个名字 / 加一步"来触发调整。 -> **未确认前**禁止：创建 `.task/`、写 `todo.json`、写业务代码。 +**歧义例外（唯一停步条件）**：仅当以下**任一**命中时，主 agent 改为"输出草稿 + 一次性列出待答问题 + 停止"，等用户回答后再进入步骤 3： + +- 用户输入或方案文档中含 `待定 / 待确认 / TBD / \?\?\?` 类明确未决标记 **≥ 3 处**； +- 用户输入未指明本次要改的模块 / 端 / 文件范围，且方案文档也不含范围章节； +- 用户明确说"先只列任务 / 别急着实现 / 让我先看看清单 / 先讨论方案"等停步语。 + +未命中例外时**不得**停下等待——即便用户输入较简略，也直接以合理默认草稿落盘，用户不满意再触发调整。 ### 步骤 3：落盘任务清单（`f2s-task`「任务开始」3.a–3.f） -用户确认后，**严格按 `f2s-task` 执行**（格式以该规则正文为准，不得省略文件）： +在步骤 2 展示后**同轮**执行（无需等待用户确认），**严格按 `f2s-task` 执行**（格式以该规则正文为准，不得省略文件）： | 子步 | 动作 | 写权 | | --- | --- | --- | @@ -137,7 +145,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 - **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** - **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 - 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） -- 步骤 2 必须主 agent；未确认禁止落盘 +- 步骤 2 主 agent 同轮完成展示与落盘；**默认不等待用户确认**，仅歧义例外命中才停 - `todo.json` 仅主 agent；子 agent 禁止写入 - 禁止批量勾选；禁止跳过 `user-todos.md`