dingtalk-doc-delivery

name	dingtalk-doc-delivery
description	钉钉知识库文档交付工作流。把仓库里的 Markdown 教程/文档按钉钉格式白名单（修饰只用加粗+代码块，禁引用块和表格）与四段式教程体例（成品展示→所用工具→操作方法→总结与小技巧）收敛成交付母版，走手动导入或 API 推送进钉钉，上级审核过审后下载终版 verbatim 回填 git 仓库并 diff 沉淀规则。当用户说"并入钉钉母文档"、"做钉钉附件版"、"按钉钉规范排版"、"按教程格式重排"、"钉钉审核完了回填"、"下载了钉钉终版"时触发。

DingTalk Doc Delivery · 钉钉知识库文档交付工作流

角色定位

把「仓库 Markdown 文档 → 钉钉知识库母文档 → 上级审核 → 终版回填仓库」这条链路固化为可重复流程。核心是两件事：

1. 交付前：按格式白名单主动收敛，不把返工留给审核人；
2. 过审后：平台审核版是唯一真身，当天下载 verbatim 回填 git，仓库不漂移。

来源实战：《实战6-自动化口播剪辑》两轮交付全部走通——第一轮附件版并入母文档「自动化口播剪辑」节并过审回填（2026-07-17），第二轮按五段式教程体例重做、配图走公网直链直接导入并挂工具包附件（2026-07-22）。方法论母档：知识库 [[钉钉知识库交付_格式白名单与终版回填闭环_v1]]，归因教训 [[变通方案不等于故障点_v1]]。

---

触发判断

• "把这篇并入钉钉母文档 / 知识库"、"做一份钉钉附件版"
• "按钉钉规范排版 / 检查格式"
• "钉钉上审核通过了，回填一下"、"我下载了终版 md"
• 新的富文本平台（语雀 / Notion / 飞书知识库）交付时，可套用同一闭环，白名单另行提炼

---

格式白名单（硬规则，2026-07-17 上级审核确立）

修饰文本只允许两种：

允许	用法
加粗	小标题并入正文的首句锚点、关键动作、要复述的话术短语
代码块 / 行内代码	需要整段复制的 prompt、命令、文件名

禁止（审核中被实际删改过的项）：

• ❌ 引用块 > —— 示例话术一律写成正文段落，不包引用
• ❌ 表格 —— 信息改走图卡片（推荐）或正文列点
• ❌ 多级小标题 ##/### —— 并入正文，改为段首加粗短句（如 "Step 1 · 把素材丢给 Codex。"）
• ❌ 分隔线、脚注等其余花哨语法

结构层面可用：正文段落、有序 / 无序列表、图片、链接。

标题按文档定位分两种（2026-07-22 修正，原「一律禁小标题」过严）：

• 作为母文档的一个子节并入：不带自己的标题层级，小标题并入正文首句加粗（实战6 附件版即此形态，上级审核实际改法）；
• 独立成页的教程文档：按公司现行教程体例分节，用 ## 一、二、三、四 + ### 1. 2. 3.（依据：同知识库《鲸海拾贝-导演调度蓝图生视频教程》通行体例）。

审稿自查一遍 grep：交付前对母版搜 ^>、^\|，命中即改写；标题按上面两种定位核对。

---

教程文档的四段式体例（独立成页时的标准骨架）

公司现行教程通行结构，按顺序写，不要打乱：

1. 一、成品展示 —— 先放成片视频 / 成品图，再用一两句说"本教程展示如何……"。读者先看到结果，才有动力往下读；
2. 二、所用工具 —— 每个工具一个子节：一句话定位 + 官网地址 + 适用场景。生成图片和视频用到的工具必须全部列出，包括用户不用自己装的幕后引擎（注明"由 X 自动调用，你不用安装"），让读者知道成品里每样东西是谁做的；
3. 三、操作方法 —— 分步骤，每步配对话截图；要照抄的话术 / 提示词一律放代码块（方便整段复制，也是白名单允许的两种修饰之一）；
4. 四、总结 —— 适用场景与边界（什么项目适合用、什么情况会翻车）+ 小技巧清单 + 准备清单。小技巧从项目复盘的"没有一次做对的"里提炼，一条一句加粗开头；
5. 五、附件 —— 把教程用到的可分发资产（skill 包、模板、脚本）打成一个 zip 挂文末，正文写清里面有什么、怎么用（一句话安装指令）、以及包里没有、需要读者自己注册的在线账号。zip 放 docs/attachments/，随仓库提交，导入后手动上传为钉钉附件。

交付流程

阶段 1 · 出交付母版

1. 从定稿正文出发（不要从旧变体改），按白名单收敛格式；
2. 配图按交付方式选（2026-07-22 作者澄清后更正）：
   • 导入 md 文件（首选，图片能带进去）：正文用 GitHub raw 公网直链，钉钉导入时自动抓图，14 张图零手工补图实测走通。链接按 https://raw.githubusercontent.com/<owner>/<repo>/main/<path> 拼，中文路径段必须 EscapeDataString 百分号编码；交付前对每条链接 curl -I 确认 200（图必须已 commit+push 到 main，仓库须公开）；
   • 占位标注版：只在无法用公网直链时才退回（私有仓库 / 图未入库），写 🔴【此处插入图N xxx ｜ 源文件：docs/images/xxx/图N_xxx.png】；
   • ⚠️ 丢图发生在「钉钉文档 → 复制粘贴到另一个钉钉文档」这一步，不是导入这一步。所以链路要设计成"md 直接导入到目标位置"，不要走"先导入中转文档、再复制进母文档"；
3. 视频与 zip 附件不能随 md 导入，各留一行 🔴 占位，导入后手动上传为钉钉附件；文首视频占位里顺带说明"配图自动带入，只有这两样要手动传"，交付人一眼知道还剩几步；
4. 母版命名 xxx_附件版.md，git 归档后再交付。

阶段 2 · 导入钉钉

• 首选（当前可用）：手动导入 / 粘贴进母文档对应节，人工补图补附件；
• 待启用：API 推送脚本 ai-editing-course/scripts/dingtalk_push.py（凭证走 .dingtalk.env，不入库），卡企业应用权限审批；审批下来后先用测试文档试跑再上正式母文档。

阶段 3 · 审核与回填（闭环关键步）

1. 上级在钉钉上直接改稿并过审——平台版从此是唯一真身；
2. 过审当天从钉钉导出/下载 md；
3. 与仓库最新版 diff，分类沉淀：
   • 格式类修改 → 更新本 skill 的白名单；
   • 内容类修改 → 写进项目复盘；
4. 终版 verbatim 回填仓库为 xxx_附件版_钉钉终版.md——不做任何"顺手优化"，哪怕发现终版自身违反白名单（如残留引用块），也只标记待办向审核人确认，不擅改过审稿；
5. commit 信息注明"钉钉终版回填"。

---

禁止行为

• ❌ 全量 Markdown 语法直接交付，等审核人删格式
• ❌ 过审后不回填，仓库继续基于旧变体迭代（版本漂移）
• ❌ 回填时"顺手修正"过审稿的措辞或格式
• ❌ 白名单确立后仍维护多个交付变体（试探期产物只留历史，不再更新）
• ❌ API 权限未验证就直推正式母文档

---

关联资产

• 方法论母档：知识库 04_方法论与洞察/06_协作运营与发布/钉钉知识库交付_格式白名单与终版回填闭环_v1.md
• 同项目上游：完结项目反推学员教程_大纲先行两级审核_v1（大纲/正文两级审核）
• 实战样例：ai-editing-course/docs/实战6_自动化口播剪辑_附件版_钉钉终版.md（过审终版）与同目录 4 个试探期变体
• 推送脚本：ai-editing-course/scripts/dingtalk_push.py
• 同族 skill：feishu-doc-publish（飞书侧发布链路）