方法论与洞察

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 同构：参数前提不成立时不报错，照常执行出错误结果。

操作规则：

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

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

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

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

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

操作规则：

补写口播脚本默认纯文字输出，结构对齐已有章节的口播语气（口语化、短句、有收口句）；
事实性内容（命令、版本号、价格）先 WebSearch 核实再写，口播稿错了是播出事故；
写钉钉文档前先用 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 备份标注位置）。

关联文档

钉钉知识库交付_格式白名单与终版回填闭环_v1（同域上游：往钉钉交付长文档的格式白名单与回填闭环；本档是 dws 直连块级编辑的操作层补充）
自动化产出双重验收_机器验参数人眼验内容_v1（同根：命令返回 success ≠ 位置正确，必须独立校验）
UI自动化的固定坐标必须绑前提断言_v1（同构：参数前提不满足时不报错、静默执行出错误结果）
变通方案不等于故障点_v1（同项目提醒：钉钉链路结论要写明验证场景，不凭反推）
04_方法论与洞察索引

类型/协作工具链主题/钉钉文档