single-source-docs-pipeline 装配层

skill-single-source-docs-pipeline · skill · A6o-交付发布 · Layer 0

① 作用

单一真相源文档交付流水线。当任务需同时交付 MD(真相源)+ HTML(可读版)+ 公开部署,且多产物必须保持一致时使用。触发关键词:MD/HTML 双轨、单一真相源、派生脚本、对账脚本、文档一致性、GitHub Pages 发布、自包含 HTML、链接可达性。

② 提供能力

暂无

③ 依赖(上游)

无内部依赖(或为叶子/外部)

④ 被依赖(下游)

无下游依赖

⑤ 为什么存在(why)

历史引入动机

源自 09-07 offshore_reflect_v3、09-11 stage6 内容排版发布、08-25 GitHub Pages 上传与 changelog 系统等实战,经合并批 batch_20260911 与 0911 架构能力实战提炼。

当前需求驱动

需求驱动:同一内容需交付 MD(真相源)+ HTML(可读版)+ 公开部署且多产物必须数据一致,杜绝「MD 改了 HTML 忘改」与「归档复制后相对路径 404」类漂移。

⑥ 怎么用(how)

触发方式

需同时交付 MD + HTML(或再加 PDF/站点)且两者必须数据一致、曾出现多产物漂移、需将文档发布为 GitHub Pages 静态站点时加载;不适用一次性交互页面或不发布不归档的单机内容。

工作流/用法

①选单一真相源(MD/数据 JSON 为唯一权威,HTML 一律脚本派生,禁双写);②派生脚本(build_report.py / gen-changelog.py,占位符 replace 避开 format 的 CSS 大括号冲突);③对账脚本(跨文档核对目录数/组数/模型名/路径/网关,不一致即报错退出);④可机检门控(逐句标记词布尔校验 + 链接可达性 + div 开闭平衡 + UTF-8 无替换字符);⑤可移植化(归档 HTML 内联 CSS 自包含或校正导航前缀);⑥发布(GitHub Actions Pages,push 被拦用 gh api PUT contents + workflow_dispatch,LFS 用 media.githubusercontent.com 直链);⑦发布前回盘复验(Pages 200 + 关键入口 200 实测)。

协作关系

与 kb-construction(内容交付型门控)、github-bulk-upload(push 被 deny 时 Contents/Git Data API)、resumable-content-pipeline(多产物交付)协作;单一真相源原则对齐 mech-coding-discipline;依赖 config-main。