f2s-doc-arch

name	f2s-doc-arch
description	根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿

执行口径：本技能产物默认写入 .Knowledge/stock-docs/，后续由知识库技能链（如 f2s-doc-final、f2s-kb-build）同步到 .Knowledge/topics/index/manifest。

编排（主 / 子 agent）

• subAgent / switchAgentVerification 两字段语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md（与上同源，flow2spec init 镜像）。本节不复述。
• 当 subAgent=true 时，从以下两种子策略择一：
  • B 模式（默认，单轮并行）：主先产出「inventory（入口 + 核心模块名，主手写）」+「扫描契约（可读路径 / 禁扫目录 / 统一产出字段）」→ 子 agent 并行只读扫表 → 主一轮合并去重 → 写 stock-docs 初稿 → 用户确认与验收在主 agent 内完成。
  • C 模式（多轮纠偏）：切换判据为以下任一 —— 多 workspace / monorepo、目录极深或源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合 / 矛盾严重。
• 子交付硬约束：子 agent 不得自行裁剪目录范围，必须按主手写 inventory 执行；子交付按「子交付 YAML schema」（字段：source / scope / cross_refs / pending），禁止散文式回传。
• 写权硬约束：.Knowledge/index.md / manifest-routing.json 恒由主 agent 落盘，子 agent 不得触碰。
• 落盘侧自验；本 SKILL 不绑定交叉校验。

生成项目架构说明（初稿）

本技能用于帮助用户生成项目架构的文档说明，产出形态类似初稿：无固定格式规范，以描述清楚为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。

与 f2s-kb-add 的分工：本技能只负责「架构说明类初稿」这一环，默认不在同一技能内写终稿、不直接执行 f2s-kb-build。若用户在工作中要把已做好的能力依据多份相关文件路径一次解析进知识库（初稿→终稿→topics/index/manifest），应使用 f2s-kb-add，勿用本技能冒充该流程。

---

入参（均可选）

参数	说明
第一个参数	可选。可为以下之一：一段纯文字说明（直接写在命令后）、本地文档路径（如 .Knowledge/stock-docs/xxx.md、.Knowledge/req-docs/README.md、README.md）。不传则进入「无输入」流程。
第二个参数	可选。输出文件路径；若不传，默认写入 .Knowledge/stock-docs/架构说明_初稿.md（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。

注意：不传任何说明或文档时，将使用 AI 扫描项目代码与目录 生成架构说明初稿，不保证质量。执行时必须先提示用户：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才继续。

---

执行流程

1. 若用户提供了说明或文档

1. 读取与理解
   • 若第一参数是文档路径：在配置根的父目录下按路径读取该文件内容（支持 .md、.txt 等文本格式）。
   • 若第一参数是纯文字说明：直接以用户输入为「用户说明」。
2. 结合项目补充
   • 根据用户说明中的代码路径、模块名、入口等线索，结合配置根的父目录下的实际目录结构、关键文件（如 package.json、入口文件、配置文件）进行归纳与补全。
   • 若用户说明较宽泛（如只说了「一个后台系统」），主动引导用户补充：主要代码路径、模块/包划分、入口与启动方式、与外部系统的边界等，便于生成更贴合的架构说明。
3. 生成初稿
   • 若启用拆子（B 模式），子 agent 必须按主手写 inventory 执行扫描，交付遵循子交付 YAML schema。
   • 产出一份项目架构说明：可包含但不限于：项目定位、技术栈、目录/模块划分、关键路径与入口、配置与部署要点、与文档产物阶段的对应说明（若适用）。
   • 无固定格式：采用清晰的标题与段落即可，不强制套用《终稿模版》。
4. 输出
   • 默认写入 .Knowledge/stock-docs/架构说明_初稿.md；若用户传入第二参数则写入该路径。
   • 若目录不存在则先创建。

2. 若用户未提供任何说明或文档

1. 提醒并确认
   • 明确说明：「未收到任何参数。 不传递说明或文档时，将使用 AI 扫描项目代码与目录生成架构说明初稿，不保证质量，且易遗漏重点、难以区分主次。建议先提供一段简要说明或已有文档（如 README、设计 doc）再执行本技能。」
   • 必须询问用户：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」
   • 仅当用户明确确认（如回复「确认」「是」「直接扫描」等）后，才继续步骤 2；若用户未确认或表示取消，则不再执行扫描与生成。
2. 扫描与生成
   • 基于配置根的父目录：列出主要目录与代表性文件（可结合 package.json、常见入口与配置文件名），归纳出「目录结构、疑似模块、入口与配置」等。
   • 生成一份架构说明初稿，并在文中注明「本初稿由扫描项目结构生成，建议结合业务说明与代码细节进一步补充」。
3. 输出
   • 同上，默认 .Knowledge/stock-docs/架构说明_初稿.md，或用户指定的第二参数。

---

引导与迭代

• 用户说明若范围较大（如「整个中台」），可提示：建议补充主要代码路径、子模块/包名、对外入口、依赖关系等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。

大功能拆分建议

扫描或理解完源码/说明后，若识别出以下任一信号，须在初稿末尾输出「拆分建议」段落，供用户参考（不阻断生成）：

• 源码总量超过 ~5000 行，或涉及文件超过 20 个；
• 能明显识别出 3 个以上不相干职责域（如接口层 / 核心规则 / 数据模型 / 外部依赖各自独立）；
• 用户说明本身已提到「多个子模块」或「多个功能」。

拆分建议格式（写在初稿末尾，独立节）：

## 拆分建议

当前功能体量较大，建议拆成多份 focused stock-doc，各自对应一个独立 topic：

| 建议文档 | 主要内容 | 建议 topic primary |
|---|---|---|
| <功能名>-概述_初稿.md | 入口边界、子模块关系、快速索引 | feature |
| <功能名>-业务规则_初稿.md | 核心流程、门禁、状态机 | policy |
| <功能名>-数据模型_初稿.md | 表结构、枚举、模型约定 | module |
| <功能名>-外部依赖_初稿.md | SOA/QMQ/Redis/风控封装 | config |

拆分后各子 topic 通过各自 matcher 独立命中，主 topic 正文写导航链接；
不通过 topicDependencies 串联"概述 → 详情"（见 f2s-topic-authoring 第 5 节）。

用户可选择：A) 按拆分建议分别执行 f2s-doc-arch（推荐），或 B) 继续用当前单份初稿进入后续流程。

完成后的下一步（硬约束）

本技能只产出初稿；结束时须按下列顺序引导，禁止让用户跳过终稿直接 f2s-kb-build：

1. 告知初稿路径，建议用户先审阅、补充内容。
2. 下一步必须为 f2s-doc-final：以初稿路径为入参，产出 .Knowledge/stock-docs/<方案名>_终稿.md（《终稿模版》规范格式）。
3. 仅在终稿落盘后再引导 f2s-kb-build，且入参须为终稿路径（含 _终稿 或由 f2s-doc-final 刚生成）。
4. 禁止在完成回复中单独写「请执行 f2s-kb-build」且入参指向 *_初稿.md；禁止将 f2s-kb-build 与 f2s-doc-final 并列成「二选一」。
5. 唯一例外：用户明确要求跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 f2s-kb-build。

完成回复模板（须同时包含 f2s-doc-final 与 f2s-kb-build，且 ctx-build 在终稿之后）：

已生成架构说明初稿：<初稿路径>。请先审阅修改；下一步请执行 f2s-doc-final <初稿路径> 转为终稿，再执行 f2s-kb-build <终稿路径> 同步知识路由主题与索引。

---

路径与输出约定

• 所有路径均相对于配置根的父目录。
• 默认输出：.Knowledge/stock-docs/架构说明_初稿.md；项目名取自 package.json 的 name（去掉 scope 与非法字符）或当前目录名。
• 若用户传入第二参数为输出路径，则优先使用该路径；若目录不存在则先创建。

---

约束与注意

• 不强制格式：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
• 无参数时必须确认：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
• 完成后按上文「完成回复模板」总结：初稿路径 + 必须先 f2s-doc-final 再 f2s-kb-build；不得仅推荐 build。