方法论与洞察

钉钉知识库交付：格式白名单 + 终版回填闭环

入档：2026-07-17 来源：《实战6-自动化口播剪辑》附件版并入钉钉知识库母文档「自动化口播剪辑」节的交付全程（教程本体见 完结项目反推学员教程_大纲先行两级审核_v1） 验证状态：✅✅ 闭环三验证（2026-07-17 实战6 首验 → 2026-07-20 白名单沿用 → 2026-07-20 四篇 Codex 教程回填完成，闭环走通）

事实记录（不可修改区）

• 目标：教程正文定稿后并入公司钉钉知识库母文档，上级在钉钉上做终审
• API 路线搁置：钉钉推送脚本骨架已就绪（ai-editing-course/scripts/dingtalk_push.py，凭证走 .dingtalk.env 不入库），卡在企业应用权限审批，本次改走手动导入
• 手动导入前做了 4 个变体试探导入通道（单日 4 连发提交）：
  1. 附件版（小标题并入正文为纯一级文本）
  2. 公网图链版（14 处配图改 GitHub raw 直链，赌钉钉导入自动抓图）
  3. 纯文字版（去除全部 Markdown 符号，图/视频位置 🔴 文字占位，供直接粘贴）
  4. 占位标注版（保留 Markdown，仅图/视频换 🔴 占位，供知识库导入后中转）
• 母文档在钉钉上人工修正后过审。终审版 vs 仓库占位标注版的实际 diff：
  • 删除结尾「准备清单」表格（信息由图14卡片承担，正文不再重复）
  • Step 1 / Step 5 的示例话术从引用块改为正文段落
  • 开场白重写为口播式完整段落（原「先看成片。」三字开头）；成片视频改为钉钉附件链接
  • 新增加粗三处：「AI 乐队」「帮我安装这几个 skill」「你说一段话，Codex 给一个结果」
  • 残留一处引用块未删（Step 4 反馈公式 > 截图 + 圈出来 + 说想要什么）——回填时按「不擅改过审稿」标待办上报，作者确认为漏网，当天修正线上版并同步本地，白名单零例外成立
• 审核后定下的格式规则（作者原话）：修饰文本只能使用加粗和代码块；引用块和表格全部去掉
• 2026-07-22 作者澄清了当初做 4 个变体的真实原因：导入钉钉这一步本身没问题（含图片），出问题的是「从钉钉文档复制到另一个钉钉文档」这一步会丢图。此后交付一律走「md 带 GitHub raw 公网直链 → 直接导入目标位置」，14 张图零手工补图；纯文字版与占位标注版降级为无公网直链时的兜底
• 终版 md 从钉钉下载后 verbatim 回填 ai-editing-course/docs/实战6_自动化口播剪辑_附件版_钉钉终版.md
• 2026-07-22 第二轮交付（同一篇教程按公司通行教程体例重做，docs/实战6_自动化口播剪辑_钉钉版_四段式_v2.md）：
  • 体例参照同知识库《鲸海拾贝-导演调度蓝图生视频教程》，重排为五节：一、成品展示 → 二、所用工具 → 三、操作方法 → 四、总结与小技巧 → 五、附件
  • 「所用工具」按作者要求补全生成图片与视频的幕后工具：faster-whisper（词级字幕）、Pillow（26 张卡片/4 组图表/进度条）、FFmpeg（合成渲染质检），均从仓库真实脚本核对得出，标注”Codex 自动调用、读者不用装”
  • 14 张配图改 GitHub raw 公网直链并逐条 curl -I 验证 200，随导入自动抓图，零手工补图
  • 「五、附件」把 4 个 skill + 安装说明打成 docs/attachments/实战6_剪辑工具包.zip（19.9 KB）随仓库分发；打包前比对 .agents / .claude / 学员包三处副本逐文件哈希一致
  • 全文仅剩视频与 zip 两处需手动上传，均以 🔴 标注
  • 归因更正详见 变通方案不等于故障点_v1

事实追加（2026-07-20 · 三篇 Codex 教程附件版交付）

• 交付对象：《120min Codex小白系列教程》三个子章节（人生模拟器 / 台风实时预测 / 桌面小程序）附件版，仓库 codex-tutorial
• 交付通道从「导入 md 文件」变为复制粘贴正文进母文档；作者实测：钉钉粘贴无法携带图片与视频，公网直链（GitHub raw）在粘贴场景同样失效
• 三篇共 46 处配图从 raw 直链全部改回 🔴 占位标注（占位内写仓库源文件路径），视频维持附件占位；作者一键复制文字后手动补素材（人生模拟器篇已上传完毕）
• 引言按组长「AI剪辑」板块范文重写，两轮迭代的写作规律另档 范文参考骨架律_v1

事实追加（2026-07-20 · 四篇终版回填完成）

• 作者提供母文档完整终版（含四个子章节：台风实时预测 / 人生模拟器 / 桌面小程序 / AI编程理论科普），按标题定位逐篇 verbatim 提取为 codex-tutorial/docs/*_附件版_钉钉终版.md
• diff 核对（先用正则剥离图片链接、🔴 占位、标题、空白行后再比对，避免图片实体化/列表渲染差异污染判断）：其中两篇（人生模拟器、桌面小程序）与仓库稿件逐句一致，唯一差异是平台把 - 列表渲染成 * 加空行、1.加成1. 双空格——纯格式噪音，不代表真实修改
• 另两篇有真实文字改动，均已回填进仓库底稿（_教程正文_定稿.md/_教程正文_v0.1.md 与 _附件版.md 同步，而非只留在终版文件里）：
  • 台风实时预测：删去开场句「挂在 B站上、上线后还拿到了官方推流」（简化开场，非事实证伪）；「你在实战 2 已经会了」改「你在自动化剪辑案例已经会了」——内部草稿的章节编号不能进最终交付，因为草稿编号（实战2）与母文档最终编号不保证一致，只有实际章节标题是稳定引用
  • AI编程理论科普：「点开软件动手」改「点开Codex动手」（更具体）；结尾统一改成「一句话总结」；「这套课」在部分位置改「这套教程」——用词一致性由平台终审收口，仓库草稿反过来要跟平台学
• 白名单持续零例外：四篇终版逐一 grep 引用块（^>）与表格（^|）标记，计数均为 0

事实追加（2026-07-23 · LastStand 教程钉钉版交付，跨项目复用）

• 交付对象：个人项目 LastStand《从 0 到发布》教程（12 张配图），公开仓库 last-stand
• 首次导入钉钉后 12 张图全部「加载失败」，根因是正文写的是仓库相对路径 ../assets/...——相对路径在任何通道都失效，这是与”导入 vs 粘贴”通道差异无关的前置错误，先修这个再谈通道
• 按本档配图策略产出两版一起交，交付方按现场通道二选一：
  • raw 直链版：链接按 raw.githubusercontent.com/<owner>/<repo>/main/<path> 拼，中文路径段 percent-encode（上传itch → %E4%B8%8A%E4%BC%A0itch），交付前逐条 curl 确认 200（12 条全绿才交稿）——对应「导入 md 文件」通道
  • 🔴 占位标注版：每图替换为 🔴【图N · 说明 ｜ 源文件：路径】——对应「复制粘贴进母文档」通道（本档 2026-07-20 已记：粘贴场景公网直链同样失效）
• 本次新增做法：占位版文末附**「图片上传对照表」**（编号 → 说明 → 源文件路径的完整清单），解决十几张图手动上传时对不上号的问题
• 定位修正：占位版不再只是”无法用直链时才退回的兜底”，而是与直链版并列的通道适配版本，两版一起交付、一起入库
• 附带约束：raw 直链依赖仓库保持公开且图片留在 main，仓库转私有会让已交付文档的图集体失效——这类文档要么锁定占位版，要么在转私有时同步替换

一、方法论沉淀

[富文本平台交付：格式白名单先行，不等审核删改]

核心：往钉钉这类富文本知识库交付 Markdown，语法要按平台白名单主动收敛，而不是全量语法交上去等审核人手动删。本次白名单：修饰只用加粗 + 代码块；结构层面正文段落和有序列表可用；禁引用块、禁表格、禁多级小标题（并入正文加粗）。表格的信息改走图卡片或正文列点。

来源：终审 diff 的两处关键删改（表格删除、引用块转正文）都是格式层修改，与内容无关——这些返工本可以在交付前收敛掉。

操作规则：

1. 首次给一个新平台交付，交付后拿审核版 diff 一遍，把格式层删改提炼成该平台白名单；
2. 白名单一旦确立，后续交付按白名单写母版，变体试探（直链版/纯文字版/占位版）收敛为单一母版；
3. 白名单存进 skill / 规范文档，不靠记忆。

[终版回填闭环：平台审核版是唯一真身]

核心：文档在平台上被人工修改并过审后，平台版成为 source of truth，必须立即下载回填 git 仓库（verbatim，不做任何「顺手优化」）；否则仓库版从此漂移，下次迭代会基于过时底稿返工。

来源：本次终审在钉钉编辑器里完成（开场白重写、加粗调整均发生在平台侧），仓库里 4 个变体没有一个等于过审版；不回填则真身只存在于钉钉。

操作规则：

1. 平台过审 → 当天下载 md → 与仓库最新变体 diff → verbatim 回填为「钉钉终版」文件；
2. diff 出的格式类修改沉淀进白名单，内容类修改沉淀进复盘；
3. 回填时发现审核版自身违反已定规则（如本次残留引用块），不擅自改过审稿，标记待办向审核人确认；
4. 内容类修改要反向同步回仓库底稿（正文定稿/大纲展开稿），不能只留在「钉钉终版」文件里——否则下次基于底稿改版又会长出同样的问题。2026-07-20 实例：草稿里用内部编号引用其他章节（「实战 2」），终审改成实际章节标题（「自动化剪辑案例」），因为草稿编号和母文档最终编号不保证一致；这条修正回填进了正文定稿而不只是终版文件。

[导入通道不明时用变体分治，通道定了就收敛]

核心：不确定平台导入行为（会不会自动抓图、认不认 Markdown）时，一文多变体各赌一条通道是合理试探；但通道和白名单确认后，变体只保留历史价值，母版收敛为一个，避免多副本漂移。

来源：单日 4 个变体提交是试探期产物；终版落地后它们全部被「钉钉终版」取代。

[配图策略跟着交付通道走，通道变了先实测再选版]

核心（2026-07-22 作者澄清后更正）：钉钉有三条通道，能不能带图各不相同——导入 md 文件：公网直链自动抓图，可带；钉钉文档 → 另一个钉钉文档复制粘贴：丢图；本地文本粘贴：丢图。所以正解不是”退回占位版”，而是把链路设计成 md 直接导入到目标位置，不要经过中转文档；占位标注版只在无公网直链可用（私有仓库 / 图未入库）时才启用。

来源：2026-07-17 导入通道实测直链可行；2026-07-20 一度按”复制粘贴丢图”把占位版定为默认；2026-07-22 作者澄清真正丢图的是”钉钉→钉钉复制”这一步，导入本身没问题，遂改回直链并实测 14 张图零手工补图。归因错位的教训另立 变通方案不等于故障点_v1。

操作规则：

1. 每次交付先确认通道，并按”是否经过中转文档”判断能否带图；
2. 首选：md 带 GitHub raw 公网直链，直接导入目标位置；链接中文路径段百分号编码，交付前逐条 curl -I 确认 200（图须已 push 到 main、仓库公开）；
3. 无直链可用时才退回占位标注版，占位写 🔴【此处插入图N xxx ｜ 源文件：docs/images/xxx/图N_xxx.png】；
4. 视频与 zip 附件任何通道都带不进去，留 🔴 占位、导入后手动上传；
5. 通道结论当天写回 skill dingtalk-doc-delivery，不靠记忆。

[教程文档的四段式体例：先给结果，再给工具，最后给能带走的资产]

核心：公司现行教程通行结构是一、成品展示 → 二、所用工具 → 三、操作方法 → 四、总结与小技巧 → 五、附件。三个易漏点：① 成品放在第一屏（读者先看到结果才有动力读下去）；② 「所用工具」要把生成图片和视频的幕后工具也列全（读者不用装的也列，注明”由 X 自动调用”），否则读者不知道成品里每样东西是谁做的；③ 文末挂一个 zip，把 skill / 模板 / 脚本这些能带走的资产打包，并写清包里没有、需要自己注册的在线账号。

来源：2026-07-22 作者指定按《鲸海拾贝-导演调度蓝图生视频教程》体例重做实战6；「补幕后工具」与「加附件压缩包」两条都是作者点名追加的，说明它们是体例里读者最在意的部分。

操作规则：

1. 幕后工具从仓库真实脚本核对（本次 faster-whisper / Pillow / FFmpeg 三样均取自 transcribe.py、render_codex_tutorial.py），不凭印象写；
2. 小技巧一节从项目复盘的”没有一次做对的”提炼，一条一句、加粗开头；
3. 附件 zip 放 docs/attachments/ 随仓库提交；多处存在同名资产时先逐文件哈希比对再打包，避免打进旧版本；
4. 标题层级按文档定位：作为母文档子节并入时并入正文加粗，独立成页教程用「一、二、三」分节。

二、一句话结论

富文本平台交付 = 格式白名单 + 通道适配 + 终版回填：按白名单收敛格式、按通道决定图片走直链还是占位、按体例排成品-工具-步骤-总结-附件；过审后平台版是唯一真身，当天下载回填，仓库才不漂移。

如何使用

• 下次往钉钉母文档交付：直接按 skill 07_skill存档/dingtalk-doc-delivery 的白名单写母版，跳过变体试探；
• 遇到新的富文本平台（语雀/Notion/飞书知识库等）：套用「交付→diff 审核版→提炼白名单→回填」同一套闭环。

关联文档

• 完结项目反推学员教程_大纲先行两级审核_v1（同项目上游：大纲与正文的两级审核；本档是其下游交付段）
• 变通方案不等于故障点_v1（本档催生的原子律：从 4 个格式变体反推”粘贴丢图”是错误归因，真故障点在钉钉文档间复制）
• 范文参考骨架律_v1（同批交付的正文行文层规律：参考范文提炼骨架不抄句式）
• 2026-07-16_Codex保姆级教学_代码化口播剪辑完整复盘（教程素材母体）
• 复盘事实先行原则（回填闭环同根：先冻结事实，仓库版=事实）
• 配套 skill：dingtalk-doc-delivery/SKILL.md
• 飞书侧同类链路：飞书应用文档授用户编辑权_唯open_id可靠_v1 · skill 07_skill存档/feishu-doc-publish
• 04_方法论与洞察索引