dws 块级插入：—index 语义陷阱与倒序插入法

入档：2026-08-17 来源：DeepSeek Harness 教程钉钉文档口播脚本补写（alidocs adoc，dws doc block 链路） 验证状态：✅ 当场验证（顺序搞反 → 对调修复 → 倒序插入 5 段 → list 校验顺序正确）

事实记录（不可修改区）

• 任务：往钉钉在线文档（adoc）「本地端安装」标题下插入 7 段口播正文
• 第一段用 --ref-block <标题块ID> --where after 插入成功，正确落在标题后（index 22）
• 第二段改用 --index 22 --where after，预期”插到 22 之后成为 23”，实际插到了 22 的位置，把第一段挤到 23，两段顺序颠倒；命令返回的 "index": 22 本身就暴露了这一语义，当时没读出来
• 修复：没用 delete 重插，而是用 dws doc block update 把两个块的文本对调，零删除完成顺序修正
• 剩余 5 段改用”同一锚点 --ref-block + --where after + 倒序插入”（先插最后一段，再插倒数第二段……），每段都紧跟锚点，最终顺序自然正确
• 插完用 dws doc block list --start-index --end-index 拉该区段校验文本顺序，确认 7 段全对
• 另一条协作偏好（作者当场纠正）：口播脚本补写只交付纯口播文字，不要写「（花字：xxx）」「[录屏占位]」这类剪辑标注——剪辑标注由作者自己加，AI 加了反而是噪音，要整段重写

一、方法论沉淀

[—index 是”插入位置”，不是”参照位置”]

核心：dws doc block insert 的 --index N 语义是**“插入到索引 N 处”**（原 N 及之后整体后移），不是直觉上的”插到 N 之后”。--where before/after 只修饰 --ref-block，不修饰 --index。把两者混用（--index 22 --where after）不会报错，会静默插错位置——和 UI自动化的固定坐标必须绑前提断言_v1 同构：参数前提不成立时不报错，照常执行出错误结果。

操作规则：

1. 多段连续插入，锚定块 ID（--ref-block），不要锚索引——索引每次插入都会漂移，块 ID 是稳定引用；
2. 同一锚点连续插入多段时倒序插入（最后一段先插），每段都紧贴锚点，顺序自然正确；
3. 或者每插一段重新 block list 拿新块 ID 再插下一段（更慢但更直白）；
4. 插完必须 block list 校验最终顺序，返回的 success 只证明”插进去了”，不证明”插对了位置”（同 自动化产出双重验收_机器验参数人眼验内容_v1 的机器关/人眼关分层）。

[顺序错了先想对调，delete 是最后手段]

核心：两段顺序颠倒时，用 block update 互换两段文本即可修复，比”delete + 重插”少一步危险操作（doc block delete 不可恢复、且在 dws 危险操作清单里）。文本对调是幂等的、可预览的，适合一切”内容对、位置错”的修复。

[口播脚本协作：AI 只写文字层，标注层归作者]

核心：给视频口播脚本补写内容时，AI 的交付物是可直接念的正文。花字、录屏占位、aroll/broll 提示、放大/变暗等剪辑标注是作者的私有工作流语言，由作者在录制/剪辑阶段自己加。AI 代加标注的三个问题：① 格式和作者的标注习惯不一致（作者用红色 span 标注，格式各异）；② 标注依赖素材实际情况，AI 不知道录了什么；③ 作者要全文删一遍标注才能用。

操作规则：

1. 补写口播脚本默认纯文字输出，结构对齐已有章节的口播语气（口语化、短句、有收口句）；
2. 事实性内容（命令、版本号、价格）先 WebSearch 核实再写，口播稿错了是播出事故；
3. 写钉钉文档前先用 dws doc info 探节点类型（adoc/axls/able 路由不同产品），写的过程中每步用 block list 校验。

二、一句话结论

dws 块级插入锚块 ID 不锚索引、多段倒序插、插完 list 校验；顺序错了对调文本不重插；口播脚本只写纯文字，剪辑标注是作者的图层。

如何使用

• 下次用 dws 给钉钉文档插内容：直接按「ref-block 锚定 + 倒序插入 + list 校验」三步走，跳过 --index；
• 任何 CLI 的 index/位置类参数，先用一段无关内容探一次语义再批量执行（探针成本远低于返工）；
• 接”补写脚本/文案”类需求时，先问一句”标注层谁来加”，默认只写正文。

事实追加（2026-08-17 下午 · callout 批注框与配图上传）

• callout 批注框的正确打开方式：钉钉”批注框”（蓝底气泡）在块体系里是 container（subType: colorBlocks），不是 callout 类型——直接传 {"blockType":"callout"} 会报 Undefined block element。正解：先让作者手动做一个样式满意的框，用 block list --content-format jsonml 读出它的完整 JSONML（含 bgcolor:#E8F2FE、sticker:气泡、borderRadius:8、padding 11），以后照抄这份 JSONML 用 --content-format jsonml --element 插入/更新。模板（2026-08-17 定型，跳蛛教程 6 个名词批注全部用它）：

["container",{"subType":"colorBlocks","metadata":{"padding":{"top":11,"right":11,"bottom":11,"left":11},"borderRadius":8,"sticker":"气泡","bgcolor":"#E8F2FE","showstk":true}},["p",{},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"标题"]]],["p",{},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"正文"]]]]

• shell 转义坑：JSONML 里含中文引号和嵌套引号，直接写在 --element '...' 里会因转义错乱报 invalid character '\\'。稳定做法：JSONML 写入临时文件，--element "$(cat /tmp/x.json)" 传入。
• media insert 管道吞返回值：dws doc media insert ... | python -c ... 解析失败时（stdout 前有杂质），插入本身已成功——用管道消费返回值做判断会误判失败导致重复插入（2026-08-17 实例：同一张图插了两次，靠 block list 数量复核才发现）。教训：media insert 后一律用 block list/read 校验数量，不靠管道返回值。
• 配图排序：多张图插同一段后要按口播顺序排列时，用”锚点链”：图 A 插段落后 → list 拿 A 的块 ID → 图 B 以 A 为 ref-block 插入 → 依此类推。倒序法在媒体块上同样适用但锚点链更直观。
• 重写带内嵌标注的段落：block update --text 会把原段落里作者手加的红色剪辑标注（span color）抹成纯文本——重写前提醒作者标注层会丢，需重新加（或先读出 jsonml 备份标注位置）。

事实追加（2026-09-04 · block update 通道选择、fetch-uuid 直改与 uuid 易变陷阱）

场景：WorkBuddy 教程钉钉文档（1300+ 块）按回执决策修订 5 个正文块 + 全文残留校验。

• --element 传裸 JSONML 数组会服务端 500：block update --element '["p", {}, [...]]' 报 ClassCastException: Failed to set pojo McpBlockUpdateRequest property element value...(class java.util.ArrayList)——该参数要的是 dict 结构（如 {"blockType":"heading",...}），不是裸数组；空属性 {} 还会被 fix-jsonml 弄成 null 加剧报错。纯文本段落直接用 --content "文本" 快捷参数，本次 5 块全部一次成功；带复杂格式才走 dict 结构或照抄容器 JSONML（见上一节 callout 模板）。
• +fetch 的 uuid 就是 blockId，可全文档直改：+fetch --scope full --detail full 返回的 content.jsonml 是字符串（需二次 json.loads）；块属性里的 uuid（19 位，如 mtlb2dzffkezs5ny2nm）可直接当 --block-id 传给 block update。配合 Python 递归解析（leaf 判据：data-type=='leaf' 且第 3 元素为 str），可越过 block list 只返回前 50 块的限制，任意深度的块都能定位并原地改。
• uuid 易变陷阱（跨时间对比文档不能用 uuid）：块被编辑后 uuid 会重新生成——昨晚拉的全量与今天对比，uuid 对比得出「新增 38 块」的假象，改用 (name+size) 指纹（图片用文件名+字节大小，文本用内容哈希）才得到真实的「新增 10、消失 2」。uuid 只适合当次会话内的引用，跨版本对比一律用内容指纹。
• 写操作串行铁律（本次本地侧翻车）：同一文件的两处 Edit 并行执行，后者基于旧内容应用导致前者被覆盖——工具没报错但改动丢了。文件写操作（Edit/Write/块更新）一律串行，或合并为一次重写。
• Windows 回收站删除对中文路径基本不可用：send2trash 依赖 8.3 短文件名转换，路径含中文且系统未启用 8.3 名称时报 FileNotFoundError: \\?\E:/...；PowerShell 工具又拦截 Add-Type（COM Shell.Application 方案不通）。实际可用路径：用户明确拍板后 rm，或先把文件挪到纯英文路径再 send2trash。

事实追加（2026-09-04 · 大板块改写：先出待审稿，再一次性入库）

场景：WorkBuddy 教程《能力7-Skill》板块（22 块 / 2061 字）从「概念讲解」改为「手把手实操演示」。

• 诊断先行：全文导出整板块再判断。用 +fetch 全量 + Python 打印「标题块 → 下一同级标题块」之间的全部块（uuid + tag + 文本），一眼看出结构性问题：本板块前 4 段是理论、后 12 块是链接罗列、全篇没有一步操作路径——只靠读单块看不出「整块是干的」。
• 大板块改写不要直接写进文档。先出一份本地待审 md，固定三节结构：① 口播正文（纯净可直接念）；② 写入方案表（每段对应哪个现有 uuid、改写/新增/删除/保持）；③ 待定项（事实存疑、结构归属、补图清单）。作者一次确认覆盖全部块，避免「逐块改到一半被推翻」的返工——这比直接动文档省得多。
• 改写时顺手解决旧错误：动手前先把该板块已知的「不可复现 / 入口不符」条目列入待定项，在新稿里一次性处理（本次：删掉无法复现的「指令反向生成」弹窗说法、把「设置页导入」改为「技能页 → 添加技能 → 上传技能」）。
• 操作步骤要对齐真实界面菜单：实操稿的每一步必须能在界面上点出来，命名用界面原文（「查找技能 / 上传技能 / 创建技能」），不要用「照表单填」这类想当然的描述——口播稿描述错路径是播出事故。
• 补图跟在文稿之后：正文定了再列补图清单，并标出「需重渲」的图（本次 07-3 三条路示意图因正文改名而失效）——先出图后改文，图必返工。

关联文档

• 钉钉知识库交付_格式白名单与终版回填闭环_v1（同域上游：往钉钉交付长文档的格式白名单与回填闭环；本档是 dws 直连块级编辑的操作层补充）
• 2026-08-26_周报整合钉钉周会手册_三轮修复与诊断反转复盘_v1（同链路下游：周报场景实战——表格 element 通道、--where before 正序镜像、listId 共享判据与 --block-id 过滤失效实测）
• 自动化产出双重验收_机器验参数人眼验内容_v1（同根：命令返回 success ≠ 位置正确，必须独立校验）
• UI自动化的固定坐标必须绑前提断言_v1（同构：参数前提不满足时不报错、静默执行出错误结果）
• 变通方案不等于故障点_v1（同项目提醒：钉钉链路结论要写明验证场景，不凭反推）
• 04_方法论与洞察索引

事实追加（2026-09-04 · 同事并行编辑下的改稿：先拉快照、倒序插入、格式去留、全文审阅导出）

场景：WorkBuddy 教程《能力6-Skill》板块按 v2.1 稿写入 9 块；期间同事同步把「仓库推荐区」从散装链接重做成三张表格，并把整篇能力编号前移一位（删了原能力5-AI助理，导致 6→5、7→6、8→7、9→8、10→9）。

同事并行编辑 → 动笔必须重新拉快照

• 别人的改动会让你手里的 uuid 表失效。我按旧快照规划写入位置，同事同时插入了 95 个表格块（含表头/行/单元格），原「心法收尾」块 mtlbn2cj6gecwirii92 已被 mtmn3mvol3k0v8nnua 取代。写入前一定重新 +fetch 一次，用新快照定位锚点——用旧快照的位置规划去写，会插到错误位置且难以回滚。
• 结构被重做时，先适配再写，不要对抗。同事把推荐区做成表格后，我原稿第五步「逐个念仓库名」就废了，改为「下面这几张表给你归好类了……链接都直接列在表里」一句带过，正文负责讲操作、表格负责给清单，各司其职。
• 编号整体位移要全局查引用。能力编号前移后，全文搜「能力\d+」确认正文无残留旧编号引用（本次一处都没有，因为正文从不引用编号，只有标题有——但这属于运气，必须查）。

倒序插入仍然成立（同锚点插多块）

同锚点 X 用 --where after 插多块时，按「最终顺序的倒序」依次插入：想得 X → A → B，就先插 B（after X），再插 A（after X）——后插的会顶到最前面。本次「第六步」+「心法」两块即如此，结果 684 选择路径收尾 → 685 第六步 → 686 心法，顺序正确。

• 注意：block insert 返回体不含新块 uuid（只有 blockType/index/logId），要拿到新块 ID 必须事后 +fetch 再解析。

--content 会清掉 inline 格式——这既是坑也是工具

• 用 --content "文本" 更新段落，原块上的 highlight / color / bold 等 inline 属性全部消失。
• 反过来说：想去掉同事留下的讨论用高亮，用 --content 重写是最省事的办法（比构造 jsonml 摘除属性简单得多）。本次三段带黄色高亮 #F9DDB2 的块，其中两段被 --content 覆盖时高亮自动消失，剩下一段是之前用 jsonml 通道特意保留的，最后单独用 --content 重写才统一。
• 判据：要留格式 → --element '[...]' --content-format jsonml；要去格式 → --content。
• 前提：确认高亮是「讨论用」而非「正文强调」再动手。本次由作者确认「Skill 板块的高亮是同事讨论时候用的，与我们的写入无关，可以覆盖」后才执行。

全文内容层审阅：导出带 uuid 的行索引

审长文档（本例 4.5 万字 / 2484 块）不要靠 block list（只有前 50 块）或肉眼翻页面。可用流程：

1. dws doc +fetch --node <id> --scope full --detail full > doc.json
2. Python json.loads(data['content']['jsonml'])（注意是字符串，要二次解析）
3. 递归遍历，只收直属 leaf 文本（子块的文本不计入父块，否则父块文本会含全部子孙，重复且无法定位）
4. 输出 doc_index.tsv：每行 行号 \t uuid \t 类型 \t 文本
5. 正则扫疑似问题（的的、了了、存储中、，，、术语不一致、数字前后矛盾），命中后从 tsv 直接取 uuid

好处：审核报告里每条问题都能附块 ID，作者点头后可以直接批量执行，不用二次定位。 本次用这套流程扫出 A 类明确错误 27 处、B 类内容缺失 7 处（都是正文留了位置没填的网址）。

其他

• dws doc block list 没有 --ref-block / --where 参数（只有 start-index / end-index / block-id / block-type），报 unknown flag。想按锚点取附近块，只能 +fetch 全量后本地解析。
• bash heredoc 写 Python 会被吃掉反斜杠：heredoc 里 '\n'.join(...) 会变成 '/n'.join(...)，且引号嵌套易乱，直接 SyntaxError。含转义字符的脚本一律用文件写入工具落盘，不要用 cat << 'EOF'。
• 表格单元格是普通 <p> 块，若内容是不带链接属性的纯文本，可以直接 --content 改（本次订正表格内 skillhub.tencent.com → skillhub.cn）。改前先用脚本 dump 该块的原始 jsonml 确认没有 a / link 包裹，否则会把超链接打没。

六、+media-insert 批量插图：verify 假失败与重复插入（2026-09-04 补）

插图的完整命令

cd <图片所在目录>   # 必须！用 ./相对路径
dws doc +media-insert --node <DOC> --file ./xxx.png --ref-block <ID> --where after -y

陷阱 1：verify 失败 = exit 1 = 批量脚本中断

四步流程 resolve_upload -> upload_oss -> insert_block -> verify。verify 这一步经常失败： 媒体资源在有界回读窗口内仍无法读取: list_document_blocks 声明仍有下一页但当前页为空， 返回 partial_success、verified: false、retryable: false，进程退出码 1。

但实际已经插入成功（前三步 success）。 后果：bash 批量脚本里如果直接串行调用，第一张就把脚本”跑死”了（我第一次就只插成 2 张）。

对策：批量脚本每张命令后加 || true，或把退出码吞掉（子 shell 里跑完再 echo 退出码）。 不要用 && 串联，不要 set -e。

+media-list 不能作为校验依据（count 恒等于附件数，不含图片）。 唯一可信的校验是 +fetch 全量拉下来数 img 块。

陷阱 2：脚本被中断的那一批，“以为没插”的其实插了

本次：批 A 脚本执行到第 3 张时进程被 SIGTERM，日志显示”插入 07-13”后无结果。 我判断没成功，又单独重插了一次 —— 结果那一组变成 4 张（应 3 张）。 根因：SIGTERM 发生在 verify 阶段或之后，前三步早已写库。

对策：批量插入中途被打断后，必须先拉快照数一遍实际张数，再决定补哪张， 绝不能凭”日志没有成功输出”就重跑。

陷阱 3：如何判定哪张是重复项

钉钉块 uuid 形如 mt + base36 时间戳 + 随机串（如 mtmujds9w807gsgt0a）。 中间两个字符是时间戳，越大 = 创建越晚：jd(697) > ha(622) > en(527) > cz(467)。 配合倒序插入法可以还原真实插入顺序，再拿 src 尾 40 字符和执行日志里的 resourceUrl 比对， 就能精确定位”哪一张是重跑的那张”，删掉即可，不用猜。

陷阱 4：图片不是独立块，是嵌在空段落里

+media-insert 生成的结构是 p 段落内嵌 img 节点：

["p", {"uuid": "..."},
  ["span", {"data-type":"text"}, ["span", {"data-type":"leaf"}, ""]],
  ["img", {"uuid":"...", "src":"..."}, [...]],
  ["span", {"data-type":"text"}, ["span", {"data-type":"leaf"}, ""]]]

删图 = 删整个 p 段落（不是删 img 子节点），block delete --block-id <p 的 uuid>。 校验时也不能只统计”顶层块里的 img”，要递归找。

陷阱 5：JSONML 的 leaf 不是 leaf 标签

文本节点是 ["span", {"data-type":"leaf"}, "文字"] —— 标签是 span，靠属性区分。 按 x[0] == "leaf" 判断会全部落空（我第一次 dump 出来所有块文本都是空字符串， 一度以为同事把正文搬走了）。正确写法：

if x[0] == "span" and isinstance(x[1], dict) and x[1].get("data-type") == "leaf":
    text += x[2]

校验脚本套路

统计”锚点块之后紧跟的连续新图段落数”，与预期张数逐锚点比对：

EXPECT = {anchor_uuid: [图1说明, 图2说明], ...}
# 新插入的 img：uuid 以 mt 开头且长度 > 12（文档原有的图多是 6 位短 uuid）
# 每个锚点往下扫，遇到非新图段落就停

26 张一次性校验完成，当场抓出 1 处重复。

七、窗口截图边缘光晕（壁纸透色）的自动修复（2026-09-04 补）

症状

实机截图（非全屏，窗口贴不满桌面）四周有一圈橙红色杂边。 本次 26 张图里 13 张 1920×1080 实机截图全部中招； 3200×1800 的示意图和 1600×900 的图完全干净 —— 凡是自己画的图就不会有。

根因（三层，逐层量化）

界面本体本身就是暖白设计（R-G ≈ 15-19），所以”把橙色都改掉”会误伤界面， 只能把”超出本体水平的色相偏移”压回去。

解法：亮度-色相基线自适应校正

1. 自动检测四边光带宽度：从边缘往内扫，找第一个”连续 8 像素 R-G ≤ 22”的位置，+3px 余量后裁剪
2. 建基线：用图像内部区域（距边 > 100px）按亮度桶（r//16）统计 R-G / R-B 的中位数
3. 边缘带 64px 内校正：超出 基线 + 4 的部分压回；excess < 50 才动（保护 UI 高饱和橙色按钮）

效果：残留 4981 → 157 像素（散布在 12px 环带，肉眼不可见）， 顶部橙色”安装”按钮、彩色卡片图标零误伤。

为什么中间踩了两个坑

结论：界面颜色是设计出来的，不能靠绝对阈值判断”正不正常”，只能跟图像自己的统计比。

修复成果

13 张修复图输出到 截图_clean/，原图未动。

八、长文档内容层审核：数字与专名核对的三条铁律

场景：3 万字钉钉教程《WorkBuddy全案实战汇总》，先产出一份 A/B/C 分类审核报告（A 类明确错误 27 处），再分批执行修改。执行到「事实数字类」时踩出的坑。

铁律一：一致性 ≠ 正确性——「与全文统一」类建议必须先查外部信源

审核报告 #12 建议：某处写「混元 Hy3」，全文其余 12 处写「混元 3」，故「Hy3 → 混元 3」。

这个建议是反的。 查证后：

• 腾讯 2026-07-06 正式发布 Hy3（腾讯 Hy，原「腾讯混元」品牌）
• 官方英文稿原文：“In internal evaluations conducted within Tencent’s workplace environment, Hy3 delivered a task success rate exceeding 90% when used in WorkBuddy…”
• 文档那句正是「基于 WorkBuddy 办公场景内部测评，Hy3 整体表现质量更高速度更快」——照官方口径写的，内容正确
• 反倒是全文 12 处「混元 3（Hunyuan 3）」疑似旧称

教训：审核报告里凡出现「改成与 XX 统一」这种理由，它证明的只是「多数派」，不是「正确」。多数派可能集体过期。这类条目必须先查权威信源再定方向，否则会把对的内容改错——改错比不改的代价大得多。

判断顺序应为：① 外部信源查证 → ② 再看全文是否需同步 → ③ 改不动的标为待确认（例如模型名这类”要看客户端实际显示什么”的事项，AI 判不了，交给人）。

铁律二：数字类错误必须对齐”计数源”，不能只看句子本身

要点：数字错往往伴随「列举项漏项」或「别处另有说法」，只替换数字会留下新的不一致。改前先把整节上下文（前后 8 块）dump 出来看。

铁律三：审核报告的行号与块 ID 会过期，执行前必须重新定位

文档在上一步被改动过（插章节、删块、插图），报告的坐标就失效了：

• #13 报告给的 mtmenixo5ng2f6im3j 已不存在，实际块是 mtmenixop9v7vpuqnj
• #24 报告给的 mtl922crwkzgm81pmr 已失效，实际要改的是 mtl7sbjiumabjber7ts
• #25 报告写「5、怎么用」，文档实际是「3、怎么用」
• #5 报告写直角引号 「任务」，文档实际是弯引号 “任务”

做法：写脚本按 uuid 在最新快照里反查，命中不到就按关键词全文重找，不要直接拿报告的 ID 去调 update。

副产物：提示词原文块要不要改

教程里的 prompt 是”录制时念的原文”，改了会与录像不一致。判据：

• 缺字/错字照改（如「…向、左侧纵向坐标标尺」→「横向、左侧…」）——错别字不影响录像语义
• 内容自相矛盾不擅改（如同一段 prompt 先说「小清新风格」后说「暗黑主题」）——可能就是原样念出来的，要问作者；可在旁边加口播说明而非删改

执行通道（复用）

改文字一律走 --element '<jsonml>' --content-format jsonml，不要用 --content "文本"（后者会清掉 highlight/color/bold 等 inline 格式）。同块多处替换必须合成一次更新——分两次会因 uuid 在首次更新后变更而失效。

九、事实追加（2026-09-15 · 本档续篇已独立成篇）

同一篇《WorkBuddy全案实战汇总》的逐字稿补写（案例 7 / 案例 12 引言 + 两处过渡话术），本轮沉淀两条超出本篇标题范围的新律，已独立成篇，见 2026-09-15_钉钉逐字稿引言与过渡话术补写_占位符原地改写与mention保留_v1：

1. 正文里写着「过渡话术」的段落 = 作者预留的槽位，接到「补一段过渡话术」要先读区间——槽位往往已存在，原地改写而非新增；且槽位块带 @某人 mention，改写必须原样拼回（--content 会把 mention 一起清掉，只能走 JSONML 通道）。
2. 逐字稿案例引言有固定骨架（承上 → 传统做法对比 → 本节定位 + 步骤数预告 → 成品展示句 → 制作步骤），其中「一共 N 步」必须往下数正文实际步骤标题——与本篇「铁律二：数字对齐计数源」同失效模式，本次为跨场景二次验证。

本篇的倒序插入法在本轮第三次验证成立；JSONML 通道留格式 / --content 清格式的判据本轮再次适用（mention 属于要留的那一类）。