@double-codeing/flow2spec 3.1.2 → 3.1.3

package/README.en.md

@@ -62,7 +62,7 @@ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock key
 `/f2s-kb-feat` writes topics while writing features, `/f2s-kb-fix` corrects topics while fixing bugs, `/f2s-git-commit` checks topic coverage before committing. Changing code == updating knowledge. No separate "documentation maintenance."
 
 **④ Full pipeline from requirements to code**  
-`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-backend` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
+`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-tech` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
 
 **⑤ Task checklists track progress across sessions**  
 When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
@@ -124,7 +124,7 @@ In your Agent tool (Cursor / Claude Code):
 
 ```
 /f2s-req-clarify  one-line description or paste PRD    ← clarify requirements
-/f2s-req-backend                                       ← generate technical proposal
+/f2s-req-tech                                       ← generate technical proposal
 natural language: implement the proposal above         ← AI starts coding (task checklist auto-created when changeTracking is on)
 (debug and verify)
 /f2s-kb-feat  add xxx capability                       ← if something's missing
@@ -147,7 +147,7 @@ natural language: implement the proposal above         ← AI starts coding (tas
 | Command | Purpose |
 |---|---|
 | `/f2s-req-clarify` | Clarify requirements |
-| `/f2s-req-backend` | Generate technical proposal |
+| `/f2s-req-tech` | Generate technical proposal |
 | `/f2s-kb-feat` | Add a new capability |
 | `/f2s-kb-fix` | Fix a bug |
 | `/f2s-kb-sync` | Sync knowledge base |

package/README.md

@@ -60,7 +60,7 @@ AI: 开始改，预计 3 处文件。
 `/f2s-kb-feat` 写功能时同步写 topic，`/f2s-kb-fix` 修 bug 时更正 topic，`/f2s-git-commit` 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。
 
 **④ 需求到实现全链路：澄清 → 技术方案 → 代码**  
-`/f2s-req-clarify` 反问到无歧义，`/f2s-req-backend` 生成可直接实现的技术方案文档落到 `req-docs/`，AI 按方案实现，不靠口头约定。
+`/f2s-req-clarify` 反问到无歧义，`/f2s-req-tech` 生成可直接实现的技术方案文档落到 `req-docs/`，AI 按方案实现，不靠口头约定。
 
 **⑤ 任务清单跨会话追踪进度**  
 开启 `changeTracking` 配置后，`f2s-kb-feat` / `f2s-kb-fix` 等技能执行时自动创建带 checkbox 的 `task.md`，每步完成立即打钩落盘。新会话续作时自动加载剩余清单，不靠记忆、不靠口头，任务进度永远在磁盘上。用户侧的代办（执行 SQL、配环境变量、点审批）单独写入 `user-todos.md`，不混在 AI 步骤里。
@@ -122,7 +122,7 @@ npx @double-codeing/flow2spec@latest init
 
 ```
 /f2s-req-clarify  一句话需求或粘贴 PRD    ← 需求澄清
-/f2s-req-backend                          ← 生成技术方案
+/f2s-req-tech                          ← 生成技术方案
 自然语言：实现上面的技术方案              ← AI 开始实现（开启 changeTracking 时自动建任务清单）
 （调试验证）
 /f2s-kb-feat  新增 xxx 能力               ← 功能缺失时补能力
@@ -145,7 +145,7 @@ npx @double-codeing/flow2spec@latest init
 | 命令 | 用途 |
 |---|---|
 | `/f2s-req-clarify` | 需求澄清 |
-| `/f2s-req-backend` | 生成技术方案 |
+| `/f2s-req-tech` | 生成技术方案 |
 | `/f2s-kb-feat` | 新增小功能 |
 | `/f2s-kb-fix` | 改 BUG |
 | `/f2s-kb-sync` | 同步知识库 |

package/docs/.mermaid-cache.json

@@ -21,7 +21,7 @@
       "marker": "MERMAID_a24148e2b009"
     },
     {
-      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-kb-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-kb-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
+      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-kb-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-kb-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-tech\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
       "hash": "6335fa6eda40",
       "marker": "MERMAID_6335fa6eda40"
     },

package/docs/en/commands-reference.md

@@ -13,7 +13,7 @@
 | `/f2s-kb-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
 | `/f2s-doc-pdf` | Convert PDF technical proposal to Markdown, save to req-docs | Doc Curation |
 | `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |
-| `/f2s-req-backend` | Generate backend technical proposal from clarified requirements | Requirements |
+| `/f2s-req-tech` | Generate technical proposal from clarified requirements | Requirements |
 | `/f2s-req-plan` | Break a technical proposal into a task checklist and implement (always creates tasks, regardless of `changeTracking.*` config) | Requirements |
 | `/f2s-git-commit` | Commit code; checks knowledge base coverage by default, skips that check in "quick commit" mode | Commit |
 | `/f2s-kb-feat` | Add new capability + sync knowledge base | KB Maintenance |
@@ -176,17 +176,17 @@
 
 **Purpose**: Converts PDF technical proposals to Markdown format, saves to `req-docs/`, and can supplement the process description.
 
-**How It Works**: Extracts structured content from the PDF (API definitions, data models, sequence flows, etc.) into Markdown under `req-docs/` for editing and follow-up with `f2s-req-clarify` / `f2s-req-backend`. Unlike `f2s-doc-final`, `doc-pdf` writes to `req-docs/`; `doc-final` writes to `stock-docs/` for `ctx-build`. **Not recommended** as a shortcut for "PDF straight to coding" without clarification and a backend technical proposal.
+**How It Works**: Extracts structured content from the PDF (API definitions, data models, sequence flows, etc.) into Markdown under `req-docs/` for editing and follow-up with `f2s-req-clarify` / `f2s-req-tech`. Unlike `f2s-doc-final`, `doc-pdf` writes to `req-docs/`; `doc-final` writes to `stock-docs/` for `ctx-build`. **Not recommended** as a shortcut for "PDF straight to coding" without clarification and a technical proposal.
 
 **Use Cases**:
 - Cross-team deliverables are in PDF format and need conversion to editable Markdown
 - Historical PDF proposals need to live under `req-docs/`
-- Provide a readable draft before `f2s-req-clarify` / `f2s-req-backend`
+- Provide a readable draft before `f2s-req-clarify` / `f2s-req-tech`
 
 **Relationships**:
 - **Prerequisite**: PDF document
 - **Output**: `.Knowledge/req-docs/<Proposal>.md`
-- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-kb-build`
+- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-tech` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-kb-build`
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes the full workflow
@@ -206,7 +206,7 @@
 
 **Purpose**: Asks clarifying questions against PRDs/requirement documents, using multi-round Q&A to define requirement boundaries, non-goals, and key flows, until the requirements are clear enough for a technical proposal.
 
-**How It Works**: Uses a "structured questioning" strategy — decomposes the requirement document along six dimensions (roles, scenarios, flows, boundaries, exceptions, non-goals), checks each for vague wording, undefined concepts, or contradictions, and generates targeted questions for each gap. Dialogue continues until all dimensions are unambiguous, then outputs a clarification record as input for `f2s-req-backend`. It turns unstructured PRDs into structured, actionable requirement constraints.
+**How It Works**: Uses a "structured questioning" strategy — decomposes the requirement document along six dimensions (roles, scenarios, flows, boundaries, exceptions, non-goals), checks each for vague wording, undefined concepts, or contradictions, and generates targeted questions for each gap. Dialogue continues until all dimensions are unambiguous, then outputs a clarification record as input for `f2s-req-tech`. It turns unstructured PRDs into structured, actionable requirement constraints.
 
 **Use Cases**:
 - First step after receiving a PRD, ensuring correct understanding
@@ -215,18 +215,18 @@
 
 **Relationships**:
 - **Prerequisite**: None (can be triggered directly)
-- **Next Step**: `f2s-req-backend` (generates a technical proposal after clarification)
+- **Next Step**: `f2s-req-tech` (generates a technical proposal after clarification)
 - **Output**: Requirement clarification record (optionally saved to `.Knowledge/req-docs/`)
 
 **Sub-Agent Invocation**: None (clarification relies on continuous dialogue and immediate user feedback throughout; no sub-agent splitting)
 
 ---
 
-### `f2s-req-backend`
+### `f2s-req-tech`
 
-**Purpose**: Based on clarified requirements and the project knowledge base, generates a backend technical proposal document including API design, data models, flow descriptions, error codes, etc.
+**Purpose**: Based on clarified requirements and the project knowledge base, generates an implementation-ready technical proposal. The content is selected by scenario: APIs, pages/components, scripts/tools, data processing, configuration, events, or module changes.
 
-**How It Works**: Centered on "knowledge base constraints + template-driven" authoring — first pull a constraint summary for the current project from `topics/stock-docs` (architecture conventions, API style, data model norms, etc.), then fill the backend technical proposal template (APIs / models / flows / errors / config / migrations) chapter by chapter against the clarified requirements so the proposal matches the existing architecture. Output is persisted under `req-docs/` as the coding contract for `implement-tech-design`.
+**How It Works**: Centered on "knowledge base constraints + template-guided" authoring — first pull a constraint summary for the current project from `topics/stock-docs` (architecture conventions, contract style, data and module boundaries, etc.), then choose only the relevant blocks from the technical proposal template. Do not force API, database, error-code, or message-queue sections just to fit the template. Output is persisted under `req-docs/` as the coding contract for `implement-tech-design`.
 
 **Use Cases**:
 - After `f2s-req-clarify` completes, output a proposal based on clarification results
@@ -248,7 +248,7 @@
 | Sub-Agent | Read-only access to multiple sources (topics / stock-docs / clarified req-docs / templates), writes `req-docs` draft per template; must not expand the read scope on its own |
 
 **Cross-Verification (when `switchAgentVerification: true`)**:
-- API/model/flow documents persisted by sub-agents -> Main agent verifies cross-chapter consistency (API signatures align with data models, flows and error handling coverage)
+- Draft proposals persisted by sub-agents -> Main agent verifies consistency across deliverables, data structures, processing flows, error handling, and project conventions
 - Only effective when `subAgent: true` and sub-tasks are actually dispatched; otherwise all verification happens within the main agent
 
 ---
@@ -574,7 +574,7 @@ The following are not skill commands but rules activated by trigger words to gui
 - After a proposal change, code needs to be updated accordingly
 
 **Relationships**:
-- **Prerequisite**: `.Knowledge/req-docs/<Technical Proposal>.md` (via `f2s-req-backend` or manual placement)
+- **Prerequisite**: `.Knowledge/req-docs/<Technical Proposal>.md` (via `f2s-req-tech` or manual placement)
 - **Rule Location**:
   - Cursor: `.cursor/rules/f2s-implement-tech-design.mdc`
   - Claude: `.claude/rules/f2s-implement-tech-design.md`

package/docs/en/design-principles.md

@@ -63,6 +63,24 @@ graph LR
     note2["Rules evolve with tool upgrades"] -.-> R
 ```
 
+### 1.1 Rule Scope and Priority
+
+Flow2Spec rules intentionally overlap in a few places: the global entry defines the overall path, while focused rules enforce one specific stage. This redundancy reduces missed mandatory steps, but agents must resolve overlap by scope priority instead of treating similar wording as conflict.
+
+| Scenario | Priority Rule | Role |
+| --- | --- | --- |
+| First read / first tool call for ordinary questions | `f2s-knowledge-preflight` | Decides whether current-repo questions must first read `.Knowledge/manifest-routing.json`, and governs the gap gate / source fallback rhythm. |
+| Source fallback closing for ordinary Q&A | `f2s-kb-feedback-closing` | After answering from source code, all four cases must take an explicit stance: cases 1–3 emit a `f2s-kb-add` / `f2s-kb-sync` suggestion; case 4 emits an explicit "knowledge base already covers" marker. Silently skipping the entire closing step is forbidden. |
+| Global routing facts / progressive loading chain | `f2s-flow2spec-unified-entry` | Defines the source-of-truth relationship and read order for manifest, matcher, topic, stock-docs, and req-docs. |
+| Reading config before any `f2s-*` skill | `f2s-config-check` | Enforces `flow2spec.config.json` as the first step of every `f2s-*` skill. |
+| Implementing from a technical proposal | `f2s-implement-tech-design` | Full execution rule for implementation from a technical design. |
+| `stock-docs` / `req-docs` boundary | `f2s-stock-docs-vs-req-docs` | Defines the path responsibilities of persistent context vs requirement / technical proposal documents. |
+| Writing topics / metadata / dependencies | `f2s-topic-authoring` | Authoring-side rule for topic naming, granularity, classification, dependencies, and persistence. |
+| Task checklist maintenance | `f2s-task` | Governs `.task/` creation, continuation, and archival. |
+| General coding discipline | `f2s-karpathy-guidelines` | Supplemental coding discipline only; it must not override mandatory f2s workflows. |
+
+Core principle: **gate rules decide whether something must be read or whether an action is allowed; focused rules then define how to execute it**. If rules overlap, apply the scenario priority above.
+
 
 
 ### 2. Progressive Routing
@@ -104,7 +122,7 @@ graph LR
 
     OLD["Existing Code/Docs"] -->|f2s-kb-add| K
 
-    NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
+    NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-tech"]
     BE --> IMPL["Implement xxx technical design"] -->|auto-trigger implement-tech-design rule| K
 
     GIT["After Git Merge"] -->|f2s-kb-merge| K

package/docs/en/usage-guide.md

@@ -67,14 +67,14 @@ If **`changeTracking` is off** but you still need a `.task/` checklist temporari
 ### New Feature Development
 
 ```
-f2s-req-clarify (one-line requirement or doc) → f2s-req-backend → implement <technical design> (strictly follows implement-tech-design rule)
+f2s-req-clarify (one-line requirement or doc) → f2s-req-tech → implement <technical design> (strictly follows implement-tech-design rule)
 After implementation, new capability → f2s-kb-feat
 After implementation, bug fix → f2s-kb-fix
 After debugging → f2s-kb-sync
 Finally → f2s-git-commit
 ```
 
-When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
+When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-tech`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
 
 ### Document Ingestion
 

package/docs/en/usage-scenarios.md

@@ -29,11 +29,11 @@ The following examples revolve around the same e-commerce project, covering the
 
 **Agent**
 
-> Clarification complete. Run `/f2s-req-backend` to produce the technical design.
+> Clarification complete. Run `/f2s-req-tech` to produce the technical design.
 
 **You**
 
-> /f2s-req-backend
+> /f2s-req-tech
 
 **Agent**
 

package/docs//344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md

@@ -29,11 +29,11 @@
 
 **Agent**
 
-> 澄清完成。执行 `/f2s-req-backend` 输出技术方案。
+> 澄清完成。执行 `/f2s-req-tech` 输出技术方案。
 
 **你**
 
-> /f2s-req-backend
+> /f2s-req-tech
 
 **Agent**
 

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -71,14 +71,14 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 ### 新需求开发
 
 ```
-f2s-req-clarify 一句话需求或文档 → f2s-req-backend → 实现xx技术方案 （会严格按照implement-tech-design规则走）
+f2s-req-clarify 一句话需求或文档 → f2s-req-tech → 实现xx技术方案 （会严格按照implement-tech-design规则走）
 实现完成后需新增能力→ f2s-kb-feat
 实现完成后需修bug→ f2s-kb-fix
 调试完成后-> f2s-kb-sync
 最后->f2s-git-commit
 ```
 
-需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-backend` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
+需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-tech` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
 
 ### 文档沉淀
 

package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -13,7 +13,7 @@
 | `/f2s-kb-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
 | `/f2s-doc-pdf` | PDF 技术方案转 Markdown，保存到 req-docs | 文档沉淀 |
 | `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |
-| `/f2s-req-backend` | 基于澄清结果生成后端技术方案文档 | 需求与方案 |
+| `/f2s-req-tech` | 基于澄清结果生成技术方案文档 | 需求与方案 |
 | `/f2s-req-plan` | 按技术方案拆任务清单，支持并行实现 （不依赖 `changeTracking.*` 配置） | 需求与方案 |
 | `/f2s-git-commit` | 提交代码，默认检查知识库覆盖；说“快捷提交”时跳过覆盖检查 | 提交 |
 | `/f2s-kb-feat` | 新增能力，补全实现 + 同步知识库 | 知识库维护 |
@@ -204,19 +204,19 @@
 
 **作用**：将 PDF 技术方案转为 Markdown 格式，保存到 `req-docs/`，可补全流程说明。
 
-**工作原理**：将 PDF 中的接口定义、数据模型、时序流程等提取为 Markdown 并落盘 `req-docs/`，便于后续编辑或与 `f2s-req-clarify` / `f2s-req-backend` 衔接。与 `f2s-doc-final` 的区别：`doc-pdf` 输出到 `req-docs/`（实现侧文档目录），`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。**不推荐**把「PDF 转 MD」当作跳过澄清与后端技术方案的直驱编码路径。
+**工作原理**：将 PDF 中的接口定义、数据模型、时序流程等提取为 Markdown 并落盘 `req-docs/`，便于后续编辑或与 `f2s-req-clarify` / `f2s-req-tech` 衔接。与 `f2s-doc-final` 的区别：`doc-pdf` 输出到 `req-docs/`（实现侧文档目录），`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。**不推荐**把「PDF 转 MD」当作跳过澄清与技术方案的直驱编码路径。
 
 **使用场景**：
 
 - 跨团队交付物为 PDF，需转为可编辑的 Markdown
 - 历史 PDF 技术方案需纳入 `req-docs/` 管理
-- 为后续 `f2s-req-clarify` / `f2s-req-backend` 提供可读底稿
+- 为后续 `f2s-req-clarify` / `f2s-req-tech` 提供可读底稿
 
 **关联关系**：
 
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
-- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-kb-build`
+- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-tech` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-kb-build`
 
 **子 agent 调用**：
 
@@ -240,7 +240,7 @@
 
 **作用**：针对 PRD/需求文档进行反问澄清，通过多轮问答明确需求边界、非目标、关键流程，直至需求足够清晰可供技术方案编写。
 
-**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-backend` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。
+**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-tech` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。
 
 **使用场景**：
 
@@ -251,18 +251,18 @@
 **关联关系**：
 
 - **前置**：无（可直接触发）
-- **后续**：`f2s-req-backend`（澄清后生成技术方案）
+- **后续**：`f2s-req-tech`（澄清后生成技术方案）
 - **输出**：需求澄清记录（可选保存至 `.Knowledge/req-docs/`）
 
 **子 agent 调用**：无（澄清全程依赖连续对话与用户即时反馈，不拆子 agent）
 
 ---
 
-### `f2s-req-backend`
+### `f2s-req-tech`
 
-**作用**：基于已澄清的需求和项目知识库，生成后端技术方案文档，包含接口设计、数据模型、流程说明、错误码等。
+**作用**：基于已澄清的需求和项目知识库，生成可实现的技术方案文档；具体内容按需求选择，可能是 API、页面/组件、脚本工具、数据处理、配置、消息事件或模块改造等。
 
-**工作原理**：以「知识库约束 + 模版驱动」为核心——先从 `topics/stock-docs` 中抽取当前项目的架构约定、接口风格、数据模型规范等约束摘要，再将澄清后的需求对照后端技术方案模版（接口/模型/流程/异常/配置/迁移）逐章填写，确保方案与现有架构一致。输出落盘 `req-docs/`，即为 `implement-tech-design` 的编码依据。
+**工作原理**：以「知识库约束 + 模版参考」为核心——先从 `topics/stock-docs` 中抽取当前项目的架构约定、契约风格、数据与模块边界等约束摘要，再按技术方案模版的可选积木取舍章节；不为套模板强行生成接口、数据库、错误码或消息队列章节。输出落盘 `req-docs/`，即为 `implement-tech-design` 的编码依据。
 
 **使用场景**：
 
@@ -291,7 +291,7 @@
 
 **交叉验证（`switchAgentVerification: true` 时）**：
 
-- 子 agent 落盘的接口/模型/流程文档 → 主 agent 校验跨章节一致性（接口签名与数据模型对齐、流程与异常处理覆盖）
+- 子 agent 落盘的方案初稿 → 主 agent 校验交付单元、数据结构、处理流程、异常处理与项目约定是否一致
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
 ---
@@ -672,7 +672,7 @@
 
 **关联关系**：
 
-- **前置**：`.Knowledge/req-docs/<技术方案>.md`（通过 `f2s-req-backend` 或手动放置）
+- **前置**：`.Knowledge/req-docs/<技术方案>.md`（通过 `f2s-req-tech` 或手动放置）
 - **规则位置**：
   - Cursor：`.cursor/rules/f2s-implement-tech-design.mdc`
   - Claude：`.claude/rules/f2s-implement-tech-design.md`

package/docs//350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -105,6 +105,24 @@ graph LR
     note2["规则随工具升级"] -.-> R
 ```
 
+### 1.1 规则范围与优先级
+
+Flow2Spec 的 rules 存在少量**有意重叠**：全局入口负责总路线，专项规则负责某个环节的强约束。这样做是为了降低 Agent 漏读关键步骤的概率，但执行时必须按优先级理解，避免把相似描述当成冲突。
+
+| 场景 | 优先规则 | 说明 |
+| --- | --- | --- |
+| 普通提问首读 / 首工具调用 | `f2s-knowledge-preflight` | 决定当前仓库相关问题是否必须先读 `.Knowledge/manifest-routing.json`，并约束缺口闸门与源码下钻节奏。 |
+| 普通问答源码补答收口 | `f2s-kb-feedback-closing` | 源码补答后强制四 case 显式表态：case 1～3 输出 `f2s-kb-add` / `f2s-kb-sync` 补充建议，case 4 输出"知识库已覆盖"显式标记；禁止悄悄跳过整个收口流程。 |
+| 全局路由事实源 / 渐进式读取链路 | `f2s-flow2spec-unified-entry` | 定义 manifest、matcher、topic、stock-docs/req-docs 的读取顺序与事实源口径。 |
+| 执行任意 `f2s-*` 技能前读配置 | `f2s-config-check` | 专门约束技能首步必须读 `flow2spec.config.json`。 |
+| 按技术方案实现 | `f2s-implement-tech-design` | 命中技术方案实现时的完整执行条令。 |
+| `stock-docs` / `req-docs` 边界 | `f2s-stock-docs-vs-req-docs` | 详细约束存量上下文与需求/技术方案文档的路径职责。 |
+| 写 topic / metadata / dependencies | `f2s-topic-authoring` | 创作侧规则，约束主题命名、粒度、分类、依赖与落盘。 |
+| 任务清单维护 | `f2s-task` | 约束 `.task/` 的创建、续作、归档。 |
+| 通用编码习惯 | `f2s-karpathy-guidelines` | 只作为编码纪律补充；不得覆盖 f2s 强制流程。 |
+
+核心原则：**门禁规则先判断是否必须读 / 是否允许做，专项规则再决定具体怎么做**。若规则表述重叠，按上表的场景优先级执行。
+
 ### 2. 渐进式路由
 
 ```mermaid
@@ -142,7 +160,7 @@ graph LR
 
     OLD["存量代码/文档"] -->|f2s-kb-add| K
 
-    NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
+    NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-tech"]
     BE --> IMPL["实现xxx技术方案"] -->|自动触发implement-tech-design规则| K
 
     GIT["Git 合并后"] -->|f2s-kb-merge| K

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {
@@ -27,8 +27,10 @@
   },
   "scripts": {
     "test": "node cli.js --help",
+    "sync:agents": "node cli.js init cursor claude codex",
     "prepublishOnly": "node cli.js --help",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "tag:version": "node scripts/git-tag-version.js"
   },
   "keywords": [
     "flow2spec",
@@ -56,4 +58,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/templates/AGENTS.md

@@ -56,6 +56,7 @@
    - 禁止把 `fallbackTopic` 当作最终命中直接实施改动；`fallbackTopic` 仅作安全兜底与澄清前置上下文。
    - 禁止在不满足触发门槛时做跨 matcher 全量补检索。
 10. **检索与作答节奏**：在 KB 已形成可答结论时，控制 `grep`/读盘范围与轮次；优先按 topic 给出的目录做单点 `Read`。用户未要求「全仓 / 通读依赖」时，允许**先短答再按需下钻**。细则见 **`./.codex/topics/f2s-knowledge-preflight.md`** 中 **「检索体积与作答节奏」**。
+11. **普通问答源码补答收口**：普通问答下钻源码并据此补答时，先按 **`./.codex/topics/f2s-knowledge-preflight.md`** 完成首读与缺口闸门，再按 **`./.codex/topics/f2s-kb-feedback-closing.md`** 完成最终知识库补充建议收口；只提示，不自动执行 `f2s-kb-add` / `f2s-kb-sync`。
 
 ## 渐进式读取顺序
 
@@ -89,6 +90,7 @@
 同目录下另有：
 
 - **`./.codex/topics/f2s-knowledge-preflight.md`**：**普通提问**也须先 `Read` **`./.Knowledge/manifest-routing.json`** 再下钻代码；与统一入口并行时以本条「首工具调用」为准。
+- **`./.codex/topics/f2s-kb-feedback-closing.md`**：普通问答读取业务源码后的知识库补充建议收口；需要补充时只输出一条 `f2s-kb-add` / `f2s-kb-sync` 命令，不需要时静默。
 - **`./.codex/topics/f2s-config-check.md`**：内容与上文「先 Read **`./flow2spec.config.json`**」一致并含 **changeTracking** 细表；**仅**在需核对细表时按需打开，不必与上列三条并列必读。
 
 执行 Flow2Spec 相关任务时，先读本文件（**`./AGENTS.md`**）与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。

package/templates/knowledge/index.md

@@ -30,7 +30,7 @@
 | f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现；始终维护 `.task/` | 技能：`skills/f2s-req-plan/SKILL.md`；依赖 `f2s-task` |
 
 每主题保留 **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` 前置同源，按需打开）。
+其中 **`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`。
 
 ---
 

package/templates/knowledge/template//346/212/200/346/234/257/346/226/271/346/241/210/346/250/241/347/211/210.md

@@ -0,0 +1,90 @@
+> **主口径（统一知识库）**：技术方案模板与产物统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/req-docs/`。
+> 本模板唯一来源为 `templates/knowledge/template/技术方案模版.md`。
+
+# 技术方案模版
+
+> 供 **f2s-req-tech** 技能使用。主模板路径为 `.Knowledge/template/技术方案模版.md`；配置根不再写入 `template/` 副本。**章节为可选积木**：与需求无关的整节可省略，按需增加项目特有章节；章节顺序建议如下，可按实际调整。不要为了套模板强行生成接口、数据库、错误码或消息队列章节。
+
+---
+
+## 1. 文档标题
+
+- 一级标题：`# <活动/需求名> 技术方案`
+
+---
+
+## 2. 需求概述
+
+- 二级标题：`## 需求概述`
+- 用无序列表或短段落写清：背景、目标、范围、**明确不做什么**。
+
+---
+
+## 3. 重点问题概述
+
+- 二级标题：`## 重点问题概述`
+- 技术难点、并发/一致性/性能、与现有模块边界、风险与取舍（列表即可）。
+- **何时填**：存在需要决策的技术权衡时；无明显难点可省略。
+
+---
+
+## 4. 外部依赖与内部调用
+
+- 二级标题：`## 外部依赖与内部调用`
+- 简要列出：依赖的外部服务（HTTP/RPC/第三方 API/SDK 等）；内部会调用的模块或方法（不必展开到每个参数）。
+- **何时填**：存在跨模块、跨服务调用时；纯单模块内部改动可省略。
+
+---
+
+## 5. 配置
+
+- 二级标题：`## 配置`
+- 按配置来源分子节（如 `### 环境变量`、`### 配置文件`、`### 功能开关`），内嵌示例并注释字段含义。
+- **何时填**：需要新增或修改配置项时；无新配置可省略。
+
+---
+
+## 6. 消息队列/事件总线（如有）
+
+- 二级标题：`## 消息队列/事件总线`
+- 按场景分子节（如 `### xxx 流程`），说明生产/消费方、主题/队列名、触发时机、消费逻辑、幂等处理等。
+- **何时填**：涉及异步消息、事件驱动架构时；无消息队列可省略。
+
+---
+
+## 7. 交付单元
+
+- 二级标题按实际交付形态命名（如 `## API 契约`、`## 组件设计`、`## 页面/交互`、`## 脚本/工具`、`## 服务逻辑`、`## 数据处理`）。
+- **每个交付单元一个三级标题**：`### <交付单元名>`（可括注路径或类型）。
+- **同一小节内按需包含**（顺序建议）：
+  1. **业务说明**（可选）：前置条件、使用场景、注意事项。
+  2. **输入/触发**：参数签名、请求体、用户操作、事件、定时任务或脚本参数示例；说明可用列表或表格。
+  3. **输出/结果**：返回体、页面状态、组件 Props、落库结果、消息事件或文件产物说明。
+  4. **字段说明**（可选）：表格 `| 字段 | 类型 | 说明 |`。
+  5. **处理流程**（按需）：涉及业务逻辑、状态变更、跨模块调用或异常分支时必须写；纯结构说明或静态配置可省略。
+- **复用通用能力**的单元：写清输入/输出示例 + 「详见《xxx 技术方案》」即可，**处理流程**可简写为「同 xxx 逻辑」。
+- **禁止**：单独再开一章罗列所有交付单元流程；禁止在文末再整段重复每个单元的逐步流程（除非是全链路**一页级**串联，见下条）。
+
+---
+
+## 8. 调用/交互流程（可选、仅全景）
+
+- 二级标题：`## 调用流程` 或 `## 交互流程`
+- **仅**写用户/系统维度的**调用顺序**（如：进页先加载配置，再触发提交，再展示结果），**不**重复各单元内部步骤。若无多单元串联必要，可整节省略。
+
+---
+
+## 9. 错误码/异常处理
+
+- 二级标题：`## 错误码` 或 `## 异常处理`
+- 表格：`| 错误码/异常类型 | 说明 | 处理建议 |`（与项目约定保持一致）。
+- **何时填**：存在明确的错误码体系或需要统一异常处理策略时；无则省略。
+
+---
+
+## 10. 数据模型/表设计
+
+- 二级标题：`## 数据模型` 或 `## 表设计`
+- 数据库：每个表 `### 表中文名 表名`，内嵌字段说明+索引说明。
+- 前端/状态：用类型定义或 TypeScript interface 示例。
+- **何时填**：涉及新建或修改数据结构时；纯逻辑改动可省略。

package/templates/rules/f2s-flow2spec-unified-entry.mdc

@@ -79,6 +79,7 @@ alwaysApply: true
 - **「向用户说明」「明确承认无覆盖」必须是用户可见的自然语言**，不得仅在内部分析或工具链中隐含带过；细则与停步条件见 **`f2s-knowledge-preflight`**（缺口闸门、探索次数上限）。
 - **禁止**在命中 **1b / 2** 后，未做上述可见说明便进入「多文件 + 依赖目录」的链式探源；每出现一个新的「入口符号」就再 `Grep` 一轮，属于典型反模式。
 - **HTTP 状态、错误正文、重定向与否**等事实，**不得以训练数据或他库经验代答**；须以当前仓库内**本次已读到的实现**为准。
+- 普通问答下钻源码并据此补答时，先按 **`f2s-knowledge-preflight`** 完成首读与缺口闸门，再按 **`f2s-kb-feedback-closing`** 完成最终知识库补充建议收口；只提示，不自动落盘。
 
 ## 知识库落盘文风（全局，写 stock-docs / topics / index 时适用）
 

package/templates/rules/f2s-kb-feedback-closing.mdc

@@ -0,0 +1,59 @@
+---
+description: 普通问答读取源码后的知识库补充建议收口规则；只提示 f2s-kb-add/f2s-kb-sync，不自动落盘
+alwaysApply: true
+---
+
+# Flow2Spec 知识库反馈收口
+
+本条专管普通问答读取业务源码后的知识库补充建议。它不是用户任务路由 topic，也不替代 `f2s-kb-add` / `f2s-kb-sync`；只决定最终回答是否需要追加一条极简提示。
+
+## 适用范围
+
+仅当同时满足以下条件时执行：
+
+- 本轮是**普通问答 / 排查 / 解释**；
+- 本轮**未进入** `f2s-*` 技能、`implement-tech-design`、`f2s-git-commit` 或其他已有后续流程；
+- 本轮读取过业务源码，且最终答案引用了源码事实。
+
+若本轮已经在执行知识库技能，不重复提示。
+
+## 机械门禁
+
+- 读完首个业务源码文件后，视为本轮已触发 `sourceFallbackUsed=true`。
+- `sourceFallbackUsed=true` 且最终答案引用源码事实时，发出回答前必须执行本条四 case 自检。
+- **四 case 必须显式表态**：每轮收口必须从 case 1～4 中选一个**明确输出对应块**，不允许悄悄跳过整个收口流程。
+- topic 命中 + 读了源码 + 答案引用源码时，默认走 **case 2 / `f2s-kb-sync`**；只有确认 KB 相关 topic 已完整覆盖本轮答案核心事实、且本轮未引入 KB 之外的新事实时，才允许走 **case 4** 显式标记 KB 已覆盖。
+- 若下钻源码前已对用户写过「仍缺 X / KB 未覆盖 X / topic 未覆盖 X」等缺口说明，答后强制走 **case 2**，禁止走 case 4。
+
+## 四种收口
+
+1. **KB 未覆盖 + 源码找到答案**：在答案末尾追加：
+   ```md
+   > **知识库补充建议**
+   > `f2s-kb-add <模块路径>`
+   ```
+2. **KB 已覆盖但不够细 + 源码补齐答案**：在答案末尾追加：
+   ```md
+   > **知识库补充建议**
+   > `f2s-kb-sync <topicId>：<本轮新增细节摘要>`
+   ```
+3. **KB 与源码不一致**：以源码事实回答，并在答案末尾追加：
+   ```md
+   > **知识库补充建议**
+   > `f2s-kb-sync <topicId>：<本轮修正事实摘要>`
+   ```
+4. **KB 已完整覆盖，源码仅核验**：在答案末尾追加：
+   ```md
+   > **知识库已覆盖**：本轮答案核心事实已由 `<topicId>` 完整提供，源码读取仅作核验。
+   ```
+   判定条件：KB 相关 topic 已写明本问题核心答案、本轮未引入 KB 之外的新事实，且未在下钻源码前对用户写过缺口说明。
+
+## 输出格式
+
+- case 1～3：输出一个 Markdown 引用块，块内只放一条可执行命令。
+- case 4：输出一个 Markdown 引用块，标明"知识库已覆盖"+ 关联 topicId。
+- `f2s-kb-sync` 后必须附本轮可回写事实的一句话摘要，避免裸命令依赖会话记忆。
+- `f2s-kb-add <模块路径>` 的路径取本轮实际读取到的最小稳定目录；若路径不确定，先用正文向用户确认候选，不输出补充建议块。
+- 禁止省略本块；禁止输出已读 KB 路径列表、覆盖对照表、原因解释或多行背景。
+- 只提示，不自动执行 `f2s-kb-add` / `f2s-kb-sync`。
+

package/templates/rules/f2s-knowledge-preflight.mdc

@@ -34,7 +34,9 @@ alwaysApply: true
 - 用户给出 **绝对路径 + 明确指令**（例如「只把该行改为 x」）且与业务知识无关的纯机械编辑；
 - **同一会话内**已对当前工作区执行过 `Read(".Knowledge/manifest-routing.json")` 且用户未要求「重新路由/全量检查」的**直接续问**：可在回答首句写「manifest 已读本会话，沿用上次路由」，**不再重复 Read** manifest。
 
-## 知识缺口与下钻源码（防「grep 死循环」）
+## 回答收口检查（源码补答后）
+
+普通问答读取业务源码后的知识库补充建议，以 **`f2s-kb-feedback-closing`** 为单一规则源。本条只保留触发关系：读完首个业务源码文件后，视为本轮已触发 `sourceFallbackUsed=true`；若最终答案引用源码事实，发出回答前必须执行 `f2s-kb-feedback-closing` 的四 case 自检。若本轮已经进入 `f2s-*` 技能、`implement-tech-design`、`f2s-git-commit` 或其他已有后续流程，不重复提示。
 
 与 **`f2s-flow2spec-unified-entry`** 中 **「知识缺口与对策」** 一致；命中 **1b（命中但上下文不够）** 或 **2（库里没有对应文档）** 时，还须遵守：
 
@@ -67,4 +69,4 @@ alwaysApply: true
 
 ## 对 Agent 自检
 
-若你发现自己在回答当前仓库相关问题时尚未 `Read` manifest，**须立即停止补写**，先 `Read` manifest 与命中 topic，再更正或续答。
+若你发现自己在回答当前仓库相关问题时尚未 `Read` manifest，**须立即停止补写**，先 `Read` manifest 与命中 topic，再更正或续答。若本轮读取过业务源码并引用源码事实，发出回答前须继续执行 `f2s-kb-feedback-closing`。

package/templates/skills/f2s-req-clarify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: f2s-req-clarify
-description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出技术方案；触发：需求澄清、PRD 澄清
+description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-tech 出技术方案；触发：需求澄清、PRD 澄清
 ---
 
 ## 编排（主 / 子 agent）
@@ -17,4 +17,4 @@ description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出
 
 **行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。
 
-**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`。输出完文档后，再提示使用 `f2s-req-backend` 生成技术方案，供后续代码实现。
+**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`。输出完文档后，再提示使用 `f2s-req-tech` 生成技术方案，供后续代码实现。

package/templates/skills/{f2s-req-backend → f2s-req-tech}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: f2s-req-backend
-description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成后端技术文档；触发：生成后端技术文档、后端技术方案
+name: f2s-req-tech
+description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成技术方案文档；触发：生成技术方案、技术方案、f2s-req-tech
 ---
 > 执行口径：业务文档统一在 `/.Knowledge/`，本技能只产出 `.Knowledge/req-docs` 方案文档并参考 `.Knowledge` 内知识，不修改配置根 `rules/skills`。
 
@@ -8,17 +8,17 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 - 两字段（`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` 方案初稿。
-- **主职责**：契约定稿、对照模版与澄清文档验收、处理接口/流程一致性。
+- **子职责**：多源只读（`.Knowledge/topics`、`stock-docs`、澄清后的 `req-docs`、模版）+ 按 `.Knowledge/template/技术方案模版.md` 写 `req-docs` 方案初稿。
+- **主职责**：契约定稿、对照模版与澄清文档验收、处理交付单元/流程一致性。
 - **校验**：默认落盘侧自验；本技能不绑定交叉校验。
 
-# 根据需求生成后端技术文档
+# 根据需求生成技术方案文档
 
-用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、优先级等）。你需要基于业务知识文档（`.Knowledge/`）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的后端技术文档。
+用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、端侧限定、优先级等）。你需要基于业务知识文档（`.Knowledge/`）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的技术方案文档。
 
-**用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不用于生成 Rules/Skills。
+**用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。不用于生成 Rules/Skills。
 
-**结构范本**：技术方案按 `.Knowledge/template/后端技术模版.md` 的章节顺序与书写要求输出。**接口与处理流程写在同一处**：每个接口小节内同时给出契约（请求/返回）与**处理流程**（分步说明、分支与错误码引用），**不要**再单独拆「接口及流程说明」「关联接口调用流程」「流程说明」等大章重复描述同一接口。
+**结构范本**：技术方案按 `.Knowledge/template/技术方案模版.md` 中的**可选积木**按需组装输出。**不要硬套固定章节**：只写本次实现真正需要的交付单元、数据结构、配置、依赖、流程或异常处理；每个交付单元小节内同时说明契约/输入输出与必要处理流程，避免再单独拆「接口及流程说明」「关联调用流程」「流程说明」等大章重复描述同一单元。
 
 ---
 
@@ -27,7 +27,7 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 - **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 `.Knowledge/req-docs/xxx.md`、`.Knowledge/stock-docs/需求_终稿.md`）。
 - **后续参数或用户补充（可选）**：需求条件与约束，例如：
   - 范围（只做某模块、某端）
-  - 必须/禁止使用的中间件、接口风格
+  - 必须/禁止使用的技术栈、接口风格
   - 与现有某模块的边界
   - 性能、安全、合规要求
 
@@ -35,7 +35,7 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 ## 输出结构
 
-生成文档时，**按 `.Knowledge/template/后端技术模版.md` 中的章节顺序与书写要求**输出；与需求无关的整节可省略。执行本技能时请**先读取该模版**作为结构与表述参考。
+生成文档时，**先读取 `.Knowledge/template/技术方案模版.md`** 作为结构参考，按需选用其中的章节积木；与需求无关的整节可省略，也可根据项目实际增加未列出的章节。
 
 ---
 
@@ -43,11 +43,11 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 主 agent 在拆子前，必须产出「项目约定摘要」作为子 agent 的**强制输入**，否则**不拆子**。摘要篇幅上限 **< 80 行**，必须包含以下 6 类条款（技术栈无关，按项目实际填具体值）：
 
-1. **对外契约规范**：接口 / 事件 / 消息 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。
+1. **对外契约规范**：接口 / 事件 / 消息 / 组件 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。
 2. **错误与返回约定**：错误码体系来源、前缀 / 分段规则、必选字段（如 code / message / data）、状态分层。
-3. **异步 / 集成规范**：消息队列 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。
+3. **异步 / 集成规范**：消息队列 / 事件总线 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。
 4. **数据与存储约定**：库 / 表 / 字段 / 缓存 / 文件 / 搜索等命名规范、主键 / 索引 / 时间字段约定、分库分表策略（若有）。
-5. **工程结构**:  后端模块分层（如 controller / service / dao / domain，或等价命名）与包路径 / 目录约定。
+5. **工程结构**：模块分层（如 controller / service / dao / domain，或前端的 pages / components / hooks / store，或等价命名）与包路径 / 目录约定。
 6. **模块边界**：本方案涉及的既有模块与其他模块的调用 / 数据边界。
 
 未完成该前置即拆子，视为违反硬约束；摘要完成后方可将子任务交付子 agent。
@@ -58,11 +58,11 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 1. **读取需求**：从用户提供的路径或正文获取需求内容；若有需求条件，一并纳入。
 2. **加载项目上下文**：主动读取并运用：
-   - `.Knowledge/topics/` 下与接口、配置、MQ、数据相关的主题规则/流程；
+   - `.Knowledge/topics/` 下与本次需求相关的主题规则/流程；
    - `.Knowledge/stock-docs/` 下的背景文档与历史技术方案；
-   - **结构对照 `.Knowledge/template/后端技术模版.md`**。
-3. **对齐项目约定**：接口命名、目录结构、配置中心、QMQ、错误码、表命名等与现有项目一致。
-4. **撰写文档**：按 `.Knowledge/template/后端技术模版.md` 书写；**每个接口下写全处理流程**，避免接口与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。
+   - **结构对照 `.Knowledge/template/技术方案模版.md`**。
+3. **对齐项目约定**：命名规范、目录结构、配置约定、消息队列、错误码、数据模型等与现有项目一致。
+4. **撰写文档**：按 `.Knowledge/template/技术方案模版.md` 按需选用章节积木书写；交付单元涉及行为逻辑时，在同一小节写清处理流程，避免交付物与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。
 5. **输出位置**：默认 `.Knowledge/req-docs/<方案名>_技术方案.md`；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。
 
 ---
@@ -70,6 +70,5 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 ## 约束
 
 - 所有路径相对于项目根目录（与 `.Knowledge` 同级）。
-- 生成的是**后端技术文档**，不写前端 UI 细节（接口契约与入参出参除外）。
 - 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。
-- **原则**：接口小节 = 契约 + 处理流程，二者不拆章重复；结构以 `.Knowledge/template/后端技术模版.md` 为准。
+- **原则**：交付单元小节按需包含契约（输入/输出）与处理流程，二者不拆章重复；结构以 `.Knowledge/template/技术方案模版.md` 为参考，按需取用，不硬套。

package/templates/knowledge/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md

@@ -1,84 +0,0 @@
-> **主口径（统一知识库）**：技术方案模板与产物统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/req-docs/`。
-> 本模板唯一来源为 `templates/knowledge/template/后端技术模版.md`。
-
-# 后端技术方案模版
-
-> 供 **f2s-req-backend** 技能使用。主模板路径为 `.Knowledge/template/后端技术模版.md`；配置根不再写入 `template/` 副本。生成 Markdown 时一级、二级标题顺序固定如下，与需求无关的整节可省略。**接口与处理流程写在同一处**，不拆章重复。
-
----
-
-## 1. 文档标题
-
-- 一级标题：`# <活动/需求名> 后端技术方案`
-
----
-
-## 2. 需求概述
-
-- 二级标题：`## 需求概述`
-- 用无序列表或短段落写清：背景、目标、范围、**明确不做什么**。
-
----
-
-## 3. 重点问题概述
-
-- 二级标题：`## 重点问题概述`
-- 技术难点、库存/并发/一致性、与现有模块边界、风险与取舍（列表即可）。
-
----
-
-## 4. 外部对接和内部调用
-
-- 二级标题：`## 外部对接和内部调用`
-- 简要列出：依赖的外部 HTTP/RPC/消息队列等；本服务内部会调用的模块或方法（不必展开到每个参数）。
-
----
-
-## 5. 配置
-
-- 二级标题：`## 配置`
-- 按配置来源分子节，例如 `### xxx.json`，内嵌 JSON 示例（可用注释说明字段含义）。
-- 若有拼团等，可另起 `### groupon-setting 片段` 等。
-
----
-
-## 6. QMQ（如有）
-
-- 二级标题：`## QMQ`
-- 按场景分子节，如 `### xxx 流程`，用编号步骤说明生产/消费、落库字段等。
-
----
-
-## 7. 接口（接口 + 流程合一）
-
-- 二级标题：`## 接口`
-- **每个接口一个三级标题**：`### <接口中文名>`（可括号注明 serverless 名或路径）。
-- **同一小节内必须包含**（按需取舍，顺序建议）：
-  1. **业务说明**（可选）：一两句或列表，如前置条件、是否仅主态调用。
-  2. **请求体**：`json` 代码块；参数说明可用列表或表格。
-  3. **返回体**：`json` 代码块。
-  4. **data 字段说明**（可选）：表格 `| 字段 | 说明 |`。
-  5. **处理流程**（必选）：编号步骤 `1. 2. 3.`，含分支（**是/否** → 下一步或错误码）、DB/Redis/下游调用、与项目约定的 `responseData`/错误码。复杂接口流程可写多步，步骤粒度适中、便于实现对照。
-- **复用通用能力**的接口（如直接透传拼团）：写清请求体示例 +「详情见《拼团技术方案设计》」即可，**处理流程**可简写为「同公共拼团接口逻辑」。
-- **禁止**：单独再开一章「接口及流程说明」罗列所有接口流程；禁止在文末再整段重复每个接口的逐步流程（除非是全链路**一页级**串联，见下条）。
-
----
-
-## 8. 关联接口调用流程（可选、仅全景）
-
-- 二级标题：`## 关联接口调用流程`
-- **仅**写用户/页面维度的**调用顺序**（如：进页先调 A 再调 B），**不**重复各接口内部步骤（内部步骤已在「接口」各小节「处理流程」中写完）。若无多接口串联必要，可整节省略。
-
----
-
-## 9. 错误码
-
-- 二级标题：`## 错误码`
-- 表格：`| 错误码 | 说明 |`（或 resultCode 与项目枚举一致）。
-
----
-
-## 10. 表设计
-
-- 二级标题：`## 表设计`
-- 每个表：`### 表中文名 表名`，内嵌 `CREATE TABLE` 或字段说明+索引说明。