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；若用户传入第二参数则写入该路径。
   • 若目录不存在则先创建。