| name | dingtalk-doc-delivery |
| description | 钉钉知识库文档交付工作流。把仓库里的 Markdown 教程/文档按钉钉格式白名单（修饰只用加粗+代码块，禁引用块和表格）与四段式教程体例（成品展示→所用工具→操作方法→总结与小技巧）收敛成交付母版，走手动导入或 API 推送进钉钉，上级审核过审后下载终版 verbatim 回填 git 仓库并 diff 沉淀规则。当用户说"并入钉钉母文档"、"做钉钉附件版"、"按钉钉规范排版"、"按教程格式重排"、"钉钉审核完了回填"、"下载了钉钉终版"时触发。 |
DingTalk Doc Delivery · 钉钉知识库文档交付工作流
角色定位
把「仓库 Markdown 文档 → 钉钉知识库母文档 → 上级审核 → 终版回填仓库」这条链路固化为可重复流程。核心是两件事：
- 交付前：按格式白名单主动收敛，不把返工留给审核人；
- 过审后：平台审核版是唯一真身，当天下载 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：交付前对母版搜 ^>、^\|，命中即改写；标题按上面两种定位核对。
教程文档的四段式体例（独立成页时的标准骨架）
公司现行教程通行结构，按顺序写，不要打乱：
- 一、成品展示 —— 先放成片视频 / 成品图，再用一两句说"本教程展示如何……"。读者先看到结果，才有动力往下读；
- 二、所用工具 —— 每个工具一个子节：一句话定位 + 官网地址 + 适用场景。生成图片和视频用到的工具必须全部列出，包括用户不用自己装的幕后引擎（注明"由 X 自动调用，你不用安装"），让读者知道成品里每样东西是谁做的；
- 三、操作方法 —— 分步骤，每步配对话截图；要照抄的话术 / 提示词一律放代码块（方便整段复制，也是白名单允许的两种修饰之一）；
- 四、总结 —— 适用场景与边界（什么项目适合用、什么情况会翻车）+ 小技巧清单 + 准备清单。小技巧从项目复盘的"没有一次做对的"里提炼，一条一句加粗开头；
- 五、附件 —— 把教程用到的可分发资产（skill 包、模板、脚本）打成一个 zip 挂文末，正文写清里面有什么、怎么用（一句话安装指令）、以及包里没有、需要读者自己注册的在线账号。zip 放
docs/attachments/，随仓库提交，导入后手动上传为钉钉附件。
交付流程
阶段 1 · 出交付母版
- 从定稿正文出发（不要从旧变体改），按白名单收敛格式；
- 配图按交付方式选（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 直接导入到目标位置"，不要走"先导入中转文档、再复制进母文档"；
- 视频与 zip 附件不能随 md 导入，各留一行 🔴 占位，导入后手动上传为钉钉附件；文首视频占位里顺带说明"配图自动带入，只有这两样要手动传"，交付人一眼知道还剩几步；
- 母版命名
xxx_附件版.md，git 归档后再交付。
阶段 2 · 导入钉钉
- 首选（当前可用）：手动导入 / 粘贴进母文档对应节，人工补图补附件；
- 待启用：API 推送脚本
ai-editing-course/scripts/dingtalk_push.py（凭证走 .dingtalk.env，不入库），卡企业应用权限审批；审批下来后先用测试文档试跑再上正式母文档。
阶段 3 · 审核与回填（闭环关键步）
- 上级在钉钉上直接改稿并过审——平台版从此是唯一真身；
- 过审当天从钉钉导出/下载 md；
- 与仓库最新版 diff，分类沉淀：
- 格式类修改 → 更新本 skill 的白名单；
- 内容类修改 → 写进项目复盘；
- 终版 verbatim 回填仓库为
xxx_附件版_钉钉终版.md——不做任何"顺手优化"，哪怕发现终版自身违反白名单（如残留引用块），也只标记待办向审核人确认，不擅改过审稿；
- 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（飞书侧发布链路）
