dingtalk-doc-delivery · diff
git:20260722.4dd7f60 to git:20260722.145780f
5 added, 4 removed. Audit A to A.
---
name: dingtalk-doc-delivery
description: 钉钉知识库文档交付工作流。把仓库里的 Markdown 教程/文档按钉钉格式白名单（修饰只用加粗+代码块，禁引用块和表格）与四段式教程体例（成品展示→所用工具→操作方法→总结与小技巧）收敛成交付母版，走手动导入或 API 推送进钉钉，上级审核过审后下载终版 verbatim 回填 git 仓库并 diff 沉淀规则。当用户说"并入钉钉母文档"、"做钉钉附件版"、"按钉钉规范排版"、"按教程格式重排"、"钉钉审核完了回填"、"下载了钉钉终版"时触发。
---
# DingTalk Doc Delivery · 钉钉知识库文档交付工作流
## 角色定位
把「仓库 Markdown 文档 → 钉钉知识库母文档 → 上级审核 → 终版回填仓库」这条链路固化为可重复流程。核心是两件事：
1. **交付前**：按格式白名单主动收敛，不把返工留给审核人；
2. **过审后**：平台审核版是唯一真身，当天下载 verbatim 回填 git，仓库不漂移。
来源实战：《实战6-自动化口播剪辑》附件版并入钉钉母文档「自动化口播剪辑」节，一轮过审（2026-07-17）。方法论母档：知识库 [[钉钉知识库交付_格式白名单与终版回填闭环_v1]]。
---
## 触发判断
- "把这篇并入钉钉母文档 / 知识库"、"做一份钉钉附件版"
- "按钉钉规范排版 / 检查格式"
- "钉钉上审核通过了，回填一下"、"我下载了终版 md"
- 新的富文本平台（语雀 / Notion / 飞书知识库）交付时，可套用同一闭环，白名单另行提炼
---
## 格式白名单（硬规则，2026-07-17 上级审核确立）
**修饰文本只允许两种**：
| 允许 | 用法 |
|---|---|
| **加粗** | 小标题并入正文的首句锚点、关键动作、要复述的话术短语 |
| 代码块 / 行内代码 | 需要整段复制的 prompt、命令、文件名 |
**禁止**（审核中被实际删改过的项）：
- ❌ **引用块 `>`** —— 示例话术一律写成正文段落，不包引用
- ❌ **表格** —— 信息改走图卡片（推荐）或正文列点
- ❌ **多级小标题 `##`/`###`** —— 并入正文，改为段首加粗短句（如 "**Step 1 · 把素材丢给 Codex。**"）
- ❌ 分隔线、脚注等其余花哨语法
**结构层面可用**：正文段落、有序 / 无序列表、图片、链接。
**标题按文档定位分两种**（2026-07-22 修正，原「一律禁小标题」过严）：
- **作为母文档的一个子节并入**：不带自己的标题层级，小标题并入正文首句加粗（实战6 附件版即此形态，上级审核实际改法）；
- **独立成页的教程文档**：按公司现行教程体例分节，用 `## 一、二、三、四` + `### 1. 2. 3.`（依据：同知识库《鲸海拾贝-导演调度蓝图生视频教程》通行体例）。
**审稿自查一遍 grep**：交付前对母版搜 `^>`、`^\|`，命中即改写；标题按上面两种定位核对。
---
## 教程文档的四段式体例（独立成页时的标准骨架）
公司现行教程通行结构，按顺序写，**不要打乱**：
1. **一、成品展示** —— 先放成片视频 / 成品图，再用一两句说"本教程展示如何……"。读者先看到结果，才有动力往下读；
2. **二、所用工具** —— 每个工具一个子节：一句话定位 + 官网地址 + 适用场景。**生成图片和视频用到的工具必须全部列出**，包括用户不用自己装的幕后引擎（注明"由 X 自动调用，你不用安装"），让读者知道成品里每样东西是谁做的；
3. **三、操作方法** —— 分步骤，每步配对话截图；**要照抄的话术 / 提示词一律放代码块**（方便整段复制，也是白名单允许的两种修饰之一）；
4. **四、总结** —— 适用场景与边界（什么项目适合用、什么情况会翻车）+ 小技巧清单 + 准备清单。小技巧从项目复盘的"没有一次做对的"里提炼，一条一句加粗开头。
## 交付流程
### 阶段 1 · 出交付母版
1. 从定稿正文出发（不要从旧变体改），按白名单收敛格式；
- 2. 配图按交付方式选（2026-07-20 实测更新）：
- - **复制粘贴交付（当前默认）**：钉钉粘贴带不了图片和视频 → 一律用**占位标注版**，图/视频位置写 `🔴【此处插入图N xxx ｜ 源文件：docs/images/xxx/图N_xxx.png】`（带仓库内源文件路径，方便粘贴后按图索骥手动补素材）；
- - **文件导入交付**：公网直链（GitHub raw）导入时自动抓图实测可行，但仅限"导入 md 文件"场景，复制粘贴场景无效；
- 3. 视频不能内嵌，正文放钉钉附件链接占位；
+ 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. 视频不能随 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`（飞书侧发布链路）