f2s-doc-final

name	f2s-doc-final
description	将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-kb-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版

执行口径：初稿/终稿统一写入 .Knowledge/stock-docs/；模板优先读取 .Knowledge/template/终稿模版.md。

编排（主 / 子 agent）

• subAgent / switchAgentVerification 两字段语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md（与上同源，flow2spec init 镜像）。本节不复述。
• 默认不拆子：MD / PDF → 终稿模版的连贯性最好，由主会话一气呵成完成理解、套模版与定稿。
• 可选拆子（仅当 subAgent=true 且大体量 / 多文件，阈值：PDF > 50 页 或 > ~5MB 文本）：子 agent 做「套模版、排版与结构搬运」草稿；主 agent 对照终稿模版、识别缺口并向用户追问、与用户对齐并定稿 / 验收；子 agent 不得单独宣称终稿已合规。
• 不为「格式转换可独立」默认拆子：终稿合规依赖模版语义 + 业务表述，主侧验收成本通常仍在。
• 校验：落盘侧 agent 自验，本 SKILL 不绑定交叉校验。

将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context）

用户会在本技能后附带至少一个参数：第一个参数为本地 PDF 文件路径或 Markdown 文件路径（必填）；第二个参数（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 f2s-kb-build 技能消费的终稿风格 Markdown 文档。

终稿模版仅作提示：若存在 .Knowledge/template/终稿模版.md，可读取作为结构参考；不强制套用。

内嵌模板结构（当项目内无 .Knowledge/template/终稿模版.md 时使用）

规范要求：

• 一级标题：方案名（如 # xxx 技术方案设计）。
• 二级标题至少包含：## 核心概念、## 业务规则、## 关键流程；其余可按需增删（如 状态与流转、接口、配置/表设计/错误码、实现位置与对接方式）。
• 核心概念：用表格列出术语、实体、关键 ID（列：概念、说明）。
• 状态与流转：若有状态机，用列表写状态及流转；若无可简述或省略。
• 业务规则：列表写约束、校验、配置项。
• 关键流程：按「用户侧或系统侧」主流程，列表写流程名、步骤简述、入口接口/方法、结果。
• 可选章节：接口、配置/表设计/错误码、实现位置与对接方式，按需保留并填写。

---

流程一：用户传入的是 Markdown（.md）

1. 读取用户传入的 .md 文件内容。
2. 参考格式（不强制）：若存在 .Knowledge/template/终稿模版.md，可读取作为结构提示；否则可参考下方内嵌模板结构。
3. 分析与转换：

• 理解原文主题与结构，提炼「方案名」「核心概念」「业务规则」「关键流程」及与原文相关的其他章节（如状态与流转、接口、配置/表设计/错误码、实现位置等）。
• 将内容重组为结构清晰的终稿风格 Markdown：一级标题为方案名；建议至少包含 核心概念、业务规则、关键流程 三个二级标题，其余按原文有无与需要增删；表格/列表格式可参考模版，不必完全一致。
• 若原文缺少某节，可标「（待补充）」或根据原文推断补全；若原文结构已清晰，可保留原文章节命名。

4. 输出：

• 默认写入 .Knowledge/stock-docs/<方案名>_终稿.md（最终产物带 _终稿 标识）。
• 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。

5. 回复：告知用户已生成 .Knowledge/stock-docs/<方案名>_终稿.md，并提示可按 f2s-kb-build 继续同步 .Knowledge/topics、.Knowledge/index.md（必要时 manifest）。

---

流程二：用户传入的是 PDF（.pdf）

分两步完成：先 PDF → 初稿 MD，用户确认后再 初稿 MD → 模板格式 MD。

步骤 A：首次执行（传入 PDF 路径）

1. 尝试读取 PDF：按用户传入路径读取 PDF（可为绝对路径，或相对项目根；如 .Knowledge/stock-docs/xxx.pdf）。

• 若当前环境可解析 PDF 文本：提取正文，转为 Markdown 初稿（保留标题层级、列表、段落，表格若可识别则保留）。
• 若无法直接读取 PDF（如仅能拿到二进制）：回复用户可将 PDF 内容转存为 .Knowledge/stock-docs/xxx.md 后再执行。

2. 生成初稿：

• 将提取出的内容保存为 .Knowledge/stock-docs/<方案名>_初稿.md（方案名可从 PDF 文件名或首标题推断）。
• 在回复中展示初稿的全文或主要结构，并明确说明：
  • 「初稿已保存为 .Knowledge/stock-docs/<方案名>_初稿.md，请检查并修改。」
  • 「确认无误后，请执行：f2s-doc-final .Knowledge/stock-docs/<方案名>_初稿.md。」

3. 本轮不进行模板格式转换，仅完成 PDF → 初稿 MD。

步骤 B：用户确认后再次执行（传入初稿 .md 路径）

当用户再次执行本技能并传入初稿的 .md 路径（如 .Knowledge/stock-docs/技术方案设计_初稿.md）时：

• 按 「流程一：用户传入的是 Markdown」 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。
• 输出建议：生成 .Knowledge/stock-docs/<方案名>_终稿.md。
• 回复：告知已生成规范版，并提示可按 f2s-kb-build 继续同步 .Knowledge/topics 与索引。

---

路径与输出约定

• 所有路径均相对于项目根；初稿/终稿统一放在 .Knowledge/stock-docs/。
• 输入：第一个参数为文件路径（必填），如 .Knowledge/stock-docs/方案.pdf 或 .Knowledge/stock-docs/方案_初稿.md；第二个参数可选。
• 输出：
  • PDF 首次：.Knowledge/stock-docs/<方案名>_初稿.md
  • MD 或初稿 MD：.Knowledge/stock-docs/<方案名>_终稿.md
• 若 .Knowledge/stock-docs/ 目录不存在，先创建再写入。

---

约束与注意

• 转换时不要照抄原文，要按模板提炼、归纳、补全，使核心概念、业务规则、关键流程清晰可查。
• 建议（不强制）保留 核心概念、业务规则、关键流程 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
• 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 f2s-kb-build 同步知识路由主题与索引。