批量Markdown文档到OKF Bundle转换模式

批量Markdown文档到OKF Bundle转换模式#

触发条件#

当出现以下任一或多个场景时，应采用本模式：

  1. 散乱Wiki文档结构化：源目录中存在大量无统一组织的Markdown文档，需要按主题归并为结构化知识包。

  2. 元数据缺失或不统一：文档缺少frontmatter，或frontmatter字段各异、格式不一致，需要统一补全为OKF v0.2规范。

  3. 知识库导航建立：需要将已有文档纳入知识库体系，建立index导航、Bundle分组和跨文档链接。

  4. 文档迁移与格式升级：从其他Wiki系统或文档平台导出Markdown，需要转换为OKF Bundle标准格式。

  5. 跨Bundle引用修复：文档重组后文件路径发生变化，原有相对链接需要系统性修复。

  6. 大规模文档治理：文档数量超过20个，手工逐个处理效率低下且容易遗漏，需要分批处理与自动化验证。

  7. 内容审计与保真：需要在格式转换过程中确保正文内容不丢失、代码块完整、图片链接有效。

  8. 团队知识资产沉淀：将个人笔记或项目文档整理为团队可复用、可审计、有成熟度标记的知识资产。

核心步骤#

本模式采用 R→I→E→V→C 五阶段工作流，每阶段有明确产出物和质量门，前一阶段未通过不得进入下一阶段。

R阶段：事实采集#

目标：对源目录进行全量、零推测的事实扫描，建立完整文件清单。

操作步骤：

  1. 全量扫描源目录，递归列出所有文件（包括.md、.html、图片及其他附件）。

  2. 对每个Markdown文件记录以下事实：

    • 文件相对路径与绝对路径

    • 文件大小（字节数或行数）

    • 现有frontmatter的完整内容（若无则标注为空）

    • H1标题（若存在）

    • 文件类型初判（教程/概念/参考/模式/报告/示例/未知）

    • 入站链接与出站链接数量

  3. 统计文件总数、各类型文件数量、总大小、目录最大深度。

  4. 分析目录结构，记录现有的子目录划分方式（按主题、按日期、按来源等）。

  5. 将以上事实写入 facts.md，每条事实编号为 F-xxx。

质量门：

  • 禁止在事实记录中使用推断性词语，包括"用于"、"目的是"、"应该是"、"可能是"等。

  • 只记录"文件里有什么"，不记录"文件大概讲什么"。

  • 文件数量必须与文件系统实际数量一致，不得遗漏。

I阶段：架构洞察#

目标：基于事实清单设计Bundle映射方案，解决所有开放性问题。

操作步骤：

  1. Bundle映射：按主题或来源将文件划分为若干Bundle，每个Bundle对应一个独立的知识领域。映射关系需记录每个文件的源路径与目标Bundle。

  2. 类型分配：为每个Markdown文件分配OKF文档类型：

    • Tutorial：分步教学类文档

    • Concept：概念解释与原理阐述

    • Reference：API参考、配置项说明、数据表格

    • Pattern：可复用模式、最佳实践、反模式

    • Report：复盘报告、分析报告、调研报告

    • Example：示例代码、完整案例

  3. 解决Open Questions：

    • 散文件归属：不属于任何主题的独立文件，归入misc Bundle或按类型新建Bundle。

    • HTML文件处理：HTML文件保持原位不转换，在Bundle映射中标注为"保持原位"。

    • 无overview的Bundle：若Bundle缺少概述文档，标注为"需新建overview"或"暂以index.md充当"。

    • 重名文件处理：不同目录下的同名文件，需在目标路径中保留子目录前缀以避免冲突。

    • README.md定位：明确README.md是作为导航入口（转为index.md）还是作为Reference文档保留。

  4. 产出 bundle-mapping.md，包含：

    • Bundle清单与每个Bundle的描述

    • 文件级映射表（源路径 → 目标Bundle/目标路径/类型）

    • Open Questions清单与决议

    • 待新建文件清单（如overview.md）

质量门：

  • 所有源文件必须在映射表中有明确归属，不得遗漏。

  • 每个Bundle至少包含2个文件，避免单文件Bundle（overview除外）。

  • Open Questions全部有明确决议，不得遗留"待定"项。

E阶段：批量生成#

目标：按映射方案执行目录重组、frontmatter补全和链接转换，分批生成OKF Bundle。

分批策略：

  1. 试点批次：选取3个具有代表性的文件（覆盖不同类型和不同Bundle）进行转换，验证所有规则。

  2. 常规批次：试点通过后，每批处理3至5个文件或1个Bundle，每批完成后立即验证。

  3. 复杂Bundle单独处理：包含超过10个文件或存在大量跨Bundle引用的Bundle，单独作为一批处理。

  4. 对于相互独立的Bundle，可使用子代理并行处理，但每个子代理必须遵循统一的指令模板和验收标准。

目录重组规则：

<bundle-name>/
  index.md              # Bundle导航（无frontmatter）
  concepts/             # 教程、概念、报告、模式类文档
  references/           # 参考资料类文档
  examples/             # 示例代码与案例
  log.md                # Bundle变更日志

Frontmatter补全规则：

  1. 所有文档必须包含以下必填字段：type、description、generated、verified、status、stale_after。

  2. generated和verified必须使用嵌套YAML格式，禁止使用inline花括号：

    generated:
  by: "process:docs-to-okf-conversion"
  at: "2026-08-22T00:00:00Z"
verified:
  by: "process:seven-concepts-v"
  at: "2026-08-22T00:00:00Z"

  3. status取值为stable、draft、deprecated之一。

  4. stale_after设置为生成日期加一年。

  5. 已有frontmatter的文件，保留原有字段，仅补全缺失字段，不得覆盖已有值。

链接转换规则：

  1. 同一Bundle内的裸文件名链接（如[文本](other-file.md)）转换为绝对路径（如[文本](/concepts/other-file.md)或[文本](/references/other-file.md)）。

  2. 跨Bundle链接根据文件实际位置调整路径，以/开头指向Bundle根目录。

  3. 文件移动后，所有引用该文件的链接必须同步更新相对路径层级（../的数量）。

  4. 锚点链接（#section）保持不变，但需确认目标文件中对应锚点存在。

index.md规则：

  1. 根目录index.md仅包含okf_version字段，不添加其他frontmatter。

  2. 子目录index.md（如concepts/index.md）不包含任何frontmatter，直接从H1标题开始。

  3. index.md的正文为该目录下文件的导航表格，包含文件名、类型、简要说明。

log.md规则：

  1. 每个Bundle一个log.md，记录该Bundle的变更历史。

  2. 使用## YYYY-MM-DD作为日期标题，按时间倒序排列（最新在最上方）。

  3. 每条变更记录包含：变更类型（新增/修改/迁移/删除）、涉及文件、变更说明。

V阶段：独立验证#

目标：对生成的OKF Bundle进行独立、全面的验证，确保格式合规、内容保真、链接有效。

验证维度：

  1. Frontmatter验证：

    • type字段值为合法枚举值（Tutorial/Concept/Reference/Pattern/Report/Example）。

    • generated和verified为嵌套YAML格式，非inline花括号。

    • 所有必填字段存在且非空。

    • status值合法，stale_after格式为YYYY-MM-DD且在未来。

    • YAML分隔符（---）成对出现，无语法错误。

  2. 链接验证：

    • 所有以/开头的绝对路径链接，目标文件存在。

    • 所有相对路径链接（含../），目标文件存在。

    • 锚点链接目标在目标文件中存在对应标题。

    • 无悬空链接（指向已删除或已移动但未更新的文件）。

  3. 内容保真验证：

    • 代码块围栏（```）成对出现，数量平衡。

    • 每个文件正文非空（frontmatter之后有实质内容）。

    • 抽样10%的文件进行人工复核，确认转换过程中未丢失正文段落、列表、表格等元素。

    • 标题层级合理（H1唯一，H2/H3递进，不跳级）。

  4. 图片链接验证：

    • 所有图片引用路径（相对或绝对）指向存在的图片文件。

    • 图片文件随Bundle一同迁移，未遗留在源目录。

    • 外部图片URL保持原样，不做本地下载。

  5. 结构完整性验证：

    • 每个Bundle包含index.md和log.md。

    • 子目录concepts/、references/、examples/中文件类型与目录名一致。

    • 根index.md的okf_version字段值正确。

质量门：所有验证项必须100%通过，不允许"已知问题但暂不修复"的豁免。发现问题后返回E阶段修复，修复后重新执行V阶段全量验证（非仅验证修复项）。

C阶段：模式沉淀#

目标：将本次转换过程中的经验萃取为可复用模式，更新组织级知识资产。

操作步骤：

  1. 顺利点记录：列出本次转换中验证有效的策略、工具和流程（见下方"顺利点"章节）。

  2. 问题点记录：列出本次转换中遇到的所有问题、根因分析和解决方案。

  3. 反模式萃取：从问题点中提炼至少7个反模式，每个反模式包含：错误做法、后果、正确做法（见下方"反模式"章节）。

  4. Skill文档更新：若本项目已有文档转换相关Skill，将新发现的规则和检查项补充到Skill文档中。

  5. 验证清单固化：将V阶段的验证维度固化为标准检查清单，供后续同类任务直接使用。

  6. 模式文档归档：将本模式文档存入模式库，标注成熟度和验证次数。

反模式#

以下反模式均来自实际转换过程中的真实教训，每个反模式后附正确做法。

  1. Inline YAML花括号格式

    • 错误做法：generated: {by: "process:...", at: "2026-08-22T00:00:00Z"}

    • 后果：YAML解析器可能无法正确识别嵌套结构，导致下游工具读取字段失败。

    • 正确做法：使用缩进嵌套格式，generated:换行后缩进两字节书写by:和at:。

  2. 根index.md过度frontmatter

    • 错误做法：在根目录index.md中添加title、description、tags等完整frontmatter。

    • 后果：OKF规范要求根index仅声明版本号，多余字段可能导致Bundle校验失败。

    • 正确做法：根index.md仅包含okf_version字段，其余信息在Bundle overview中表达。

  3. 子目录index.md带frontmatter

    • 错误做法：在concepts/index.md等子目录索引页添加frontmatter。

    • 后果：子目录index是纯导航页，frontmatter会被误识别为一个独立文档条目。

    • 正确做法：子目录index.md不包含任何frontmatter，直接从H1标题开始书写导航内容。

  4. 忽略HTML等非md文件

    • 错误做法：扫描和迁移时只处理.md文件，忽略同目录下的.html、图片、附件等。

    • 后果：非md文件遗留在源目录，迁移后的Bundle出现图片断链和附件缺失。

    • 正确做法：R阶段全量扫描所有文件类型，HTML等非Markdown文件保持原位但需记录在映射表中，图片和附件随Bundle迁移。

  5. 跨Bundle链接路径深度错误

    • 错误做法：文件从a/移动到bundle/concepts/后，链接中的../层级未相应调整。

    • 后果：链接指向不存在的路径，产生断链。

    • 正确做法：文件移动后，根据新路径重新计算相对路径层级，或将链接统一改为以/开头的绝对路径。

  6. 散文件遗漏

    • 错误做法：I阶段建立Bundle映射时，忽略源目录根层级的零散文件或隐藏目录中的文件。

    • 后果：部分文件未被迁移，转换完成后源目录仍有残留，知识资产不完整。

    • 正确做法：I阶段必须建立完整文件映射，逐文件核对R阶段清单，确保每个文件在映射表中有归属。

  7. 正则替换丢失字段

    • 错误做法：在PowerShell中使用-replace进行批量文本替换时，替换字符串中的$1被解析为字面量而非正则捕获组引用。

    • 后果：替换后文本出现字面量$1，原有捕获内容丢失，导致frontmatter或正文损坏。

    • 正确做法：在PowerShell中使用${1}明确捕获组边界，或使用-replace的脚本块替代形式，替换后立即抽样验证结果。

  8. README.md与index.md冲突

    • 错误做法：将README.md直接保留同时新建index.md，两个文件内容重复且导航入口不明确。

    • 后果：读者不知道以哪个文件为入口，维护时容易出现内容不一致。

    • 正确做法：I阶段明确README.md的定位。若作为导航入口则重命名为index.md并去除frontmatter；若作为参考文档则移入references/目录；若内容已过时则删除。

  9. 一次性批量转换过多Bundle

    • 错误做法：同时启动所有Bundle的转换，不做试点验证，不做分批检查。

    • 后果：规则错误被放大到所有文件，返工成本极高；问题定位困难，无法判断哪个批次引入了错误。

    • 正确做法：严格执行分批策略，先试点3个文件验证规则，再每批3至5个文件推进，复杂Bundle单独处理，每批完成后立即验证。

顺利点#

以下策略和做法在实际转换中被证明有效，应在后续同类任务中保留：

  1. 试点批次验证转换规则：先转换3个不同类型的文件，确认frontmatter模板、链接规则和目录结构无误后再全面推广，避免了规则错误的规模化传播。

  2. 分批策略有效控制风险：每批3至5个文件，配合即时验证，使问题能够在最小范围内被发现和修复，显著降低了返工成本。

  3. 自动化验证脚本快速发现问题：V阶段使用脚本批量检查frontmatter格式、链接有效性和代码块平衡，在数分钟内完成了人工需要数小时的检查工作。

  4. 子代理并行处理独立Bundle：对于无跨Bundle依赖的独立Bundle，分派子代理并行处理，在保证质量一致的前提下缩短了整体处理时间。每个子代理使用统一的指令模板和验收标准，避免了产出物风格不一致的问题。

迁移验证#

本节说明另一个人（或另一个团队）如何按照本模式独立完成一次类似的Markdown到OKF Bundle转换任务，以验证模式的可迁移性。

  1. 读取OKF规范：在开始之前，完整阅读OKF v0.2规范文档，理解Bundle结构、frontmatter字段要求、文档类型定义和index/log文件约定。若规范有更新，以最新版本为准并记录差异。

  2. 按R→I→E→V→C执行：严格遵循五个阶段的顺序，不跳阶段、不合并阶段。R阶段只记录事实不做设计；I阶段完成所有架构决策后才进入E阶段；E阶段分批生成；V阶段独立验证；C阶段沉淀经验。每个阶段的产出物必须经过质量门检查后方可进入下一阶段。

  3. 使用验证清单逐项检查：V阶段参照本模式"V阶段：独立验证"中的五个维度（Frontmatter、链接、内容保真、图片链接、结构完整性），逐项检查并记录结果。建议将检查项制作为检查表，每项标注通过或不通过，不通过项需返回E阶段修复。

  4. 参考反模式避免常见错误：在E阶段开始前通读"反模式"章节，将9个反模式作为事前检查项。特别是Inline YAML格式、index.md frontmatter规则、PowerShell正则替换陷阱这三项高频错误，应在每批生成后优先排查。

  5. 独立完成的判定标准：转换者无需依赖原转换者的口头指导，仅凭本模式文档和OKF规范即可完成全部工作，且所有验证项100%通过。若发现本模式文档中存在未覆盖的情况，应记录并反馈到C阶段，用于模式的持续改进。

适用范围与边界#

适用于：

  • 已有一定数量Markdown文档（10个文件以上）需要结构化重组为OKF Bundle的场景。

  • 文档内容基本成熟，主要工作是格式转换、元数据补全和目录重组，而非内容重写。

  • 源文档使用标准Markdown语法，frontmatter为YAML格式。

  • 需要建立知识库导航和跨文档链接体系的团队知识资产治理项目。

不适用于：

  • 从零创建Wiki（本模式假设源文档已存在，从零创建应使用OKF Wiki创建方法论）。

  • 非Markdown格式的批量转换（如Word、Confluence、HTML专有的转换需要额外的预处理步骤）。

  • 需要对文档内容进行实质性重写、翻译或大规模修订的场景（内容创作与格式转换是不同性质的工作，应分开处理）。

  • 文档数量少于5个的小型任务（五阶段工作流的流程开销可能超过收益，可使用轻量单文件变体）。