f2s-req-tech

name	f2s-req-tech
description	根据澄清后的需求基于项目知识库/Skills/Rules 生成技术方案文档；触发：生成技术方案、技术方案、f2s-req-tech

执行口径：业务文档统一在 /.Knowledge/，本技能只产出 .Knowledge/req-docs 方案文档并参考 .Knowledge 内知识，不修改配置根 rules/skills。

编排（主 / 子 agent）

• 两字段（subAgent / switchAgentVerification）语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md（与上同源，flow2spec init 镜像）。本技能不复述。
• 拆子前提（硬约束）：当 subAgent=true 时，主 agent 必须先抽取一份「项目约定摘要」作为子 agent 的强制上下文，覆盖：对外契约规范、错误与返回约定、异步/集成规范、数据与存储约定、工程结构、模块边界，合计 < 80 行。若未做该前置，不拆子——验收返工成本 > 拆子收益，强行拆子得不偿失。
• 子职责：多源只读（.Knowledge/topics、stock-docs、澄清后的 req-docs、模版）+ 按 .Knowledge/template/技术方案模版.md 写 req-docs 方案初稿。
• 主职责：契约定稿、对照模版与澄清文档验收、处理交付单元/流程一致性。
• 校验：默认落盘侧自验；本技能不绑定交叉校验。

根据需求生成技术方案文档

用户在对话中提供已澄清的需求（或需求摘要、PRD 路径），并可选择附带需求条件（如范围限定、必须/禁止使用的技术、端侧限定、优先级等）。你需要基于业务知识文档（.Knowledge/）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的技术方案文档。

用途：本技能产出的技术方案供后续代码实现使用，开发按该文档实现功能。不限于后端，适用于后端、前端、全栈、移动端、脚本工具等任意场景。不用于生成 Rules/Skills。

结构范本：技术方案按 .Knowledge/template/技术方案模版.md 中的可选积木按需组装输出。不要硬套固定章节：只写本次实现真正需要的交付单元、数据结构、配置、依赖、流程或异常处理；每个交付单元小节内同时说明契约/输入输出与必要处理流程，避免再单独拆「接口及流程说明」「关联调用流程」「流程说明」等大章重复描述同一单元。

---

输入

• 第一参数（必填）：澄清后的需求描述，或需求/PRD 文档路径（如 .Knowledge/req-docs/xxx.md、.Knowledge/stock-docs/需求_终稿.md）。
• 后续参数或用户补充（可选）：需求条件与约束，例如：
  • 范围（只做某模块、某端）
  • 必须/禁止使用的技术栈、接口风格
  • 与现有某模块的边界
  • 性能、安全、合规要求

---

输出结构

生成文档时，先读取 .Knowledge/template/技术方案模版.md 作为结构参考，按需选用其中的章节积木；与需求无关的整节可省略，也可根据项目实际增加未列出的章节。

---

拆子前置（可选，仅当 subAgent=true）

主 agent 在拆子前，必须产出「项目约定摘要」作为子 agent 的强制输入，否则不拆子。摘要篇幅上限 < 80 行，必须包含以下 6 类条款（技术栈无关，按项目实际填具体值）：

1. 对外契约规范：接口 / 事件 / 消息 / 组件 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。
2. 错误与返回约定：错误码体系来源、前缀 / 分段规则、必选字段（如 code / message / data）、状态分层。
3. 异步 / 集成规范：消息队列 / 事件总线 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。
4. 数据与存储约定：库 / 表 / 字段 / 缓存 / 文件 / 搜索等命名规范、主键 / 索引 / 时间字段约定、分库分表策略（若有）。
5. 工程结构：模块分层（如 controller / service / dao / domain，或前端的 pages / components / hooks / store，或等价命名）与包路径 / 目录约定。
6. 模块边界：本方案涉及的既有模块与其他模块的调用 / 数据边界。

未完成该前置即拆子，视为违反硬约束；摘要完成后方可将子任务交付子 agent。

---

步骤

1. 读取需求：从用户提供的路径或正文获取需求内容；若有需求条件，一并纳入。
2. 加载项目上下文：主动读取并运用：
   • .Knowledge/topics/ 下与本次需求相关的主题规则/流程；
   • .Knowledge/stock-docs/ 下的背景文档与历史技术方案；
   • 结构对照 .Knowledge/template/技术方案模版.md。
3. 对齐项目约定：命名规范、目录结构、配置约定、消息队列、错误码、数据模型等与现有项目一致。
4. 撰写文档：按 .Knowledge/template/技术方案模版.md 按需选用章节积木书写；交付单元涉及行为逻辑时，在同一小节写清处理流程，避免交付物与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。
5. 输出位置：默认 .Knowledge/req-docs/<方案名>_技术方案.md；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。

---

约束

• 所有路径相对于项目根目录（与 .Knowledge 同级）。
• 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。
• 原则：交付单元小节按需包含契约（输入/输出）与处理流程，二者不拆章重复；结构以 .Knowledge/template/技术方案模版.md 为参考，按需取用，不硬套。