文章目录直接写路径为什么会错位写作顺序和成图顺序不同步后期改一张图要动整篇占位规划怎么写进 Markdown约定可解析的注释块边写边插张数跟着结构走解析与替换的最小实现改图与排错时盯住这几条只改编排意图不动已合并路径在合并前空占位与假外链要提前拦和目录、标题注释的边界写技术博文时插图最容易出两类问题一是写到一半就先填 后面改章节顺序图还钉在旧位置二是出图工具换了文件名正文里一串路径要手工搜改漏一处就成死链。把「画面要求」和「最终文件名」拆开用占位写进正文再统一出图、按顺序替换这两类坑能一起压住。直接写路径为什么会错位写作顺序和成图顺序不同步正文是按论证推出来的图是按渲染队列出来的。你在第二节写了 第三节又插了一段第二节变成第四节文件名还叫fig-02读者会以为「第二张图对应第二节」实际已经对不上。更糟的是预览器和发布器对相对路径、空行规则不一致有的要求图片行上下各空一行有的会把紧贴代码块的图吞掉。后期改一张图要动整篇路径写死之后换图等于改契约做法正文改动量典型风险直接写 每换一张改一处路径漏改、路径拼错先写占位再统一替换只改占位里的画面描述文件名由流水线生成文末集中贴图再手工挪整篇重排位置和叙述脱节占位的价值不在「多一种注释语法」而在把意图这张图要表达什么、插在哪一段旁边和产物名figure-01.png解耦。占位规划怎么写进 Markdown约定可解析的注释块用 HTML 注释承载结构化字段预览时不渲染脚本又能用正则整段抠出来。字段至少要有类型、简短 alt、出图用的画面描述类型建议收敛成固定词表例如主题图片、流程图、时序图、框架图、技术介绍图、辅助理解图、重点说明图。解析时把未知类型落到「辅助理解图」并按类型给默认宽高主题图常用 1280×720流程图可略宽。写作阶段不要写 也别虚构文件名文件名留给合并步骤按序号生成。边写边插张数跟着结构走规划原则可以写死几条避免凑图默认 2 张结构清晰时 23 张只有某一小节确实需要画面再加最多 5 张。占位紧贴它服务的段落讲流程就放在流程说明附近讲对照就放在表格前后。prompt写画面约束不写文件路径alt 用短中文合并后直接进 。写作完成后脚本按出现顺序解析占位生成任务列表出图阶段只读占位、不改正文合并阶段再把注释块换成真正的图片行并保证该行前后各空一行减少平台解析差异。解析与替换的最小实现下面这段示意「按出现顺序收集占位 → 按同样顺序替换」核心是顺序对齐不是复杂 AIimportrefromdataclassesimportdataclass FIGURE_BLOCK_REre.compile(r!--\\s*figure\\b([\\s\\S]*?)--,re.I)KEY_REre.compile(r^(type|alt|prompt)\\s*:\\s*(.*)$,re.I)dataclassclassFigureSpec:raw:strkind:stralt:strprompt:strdefparse_fields(body:str)-dict[str,str]:fields,current,buf{},,[]forlineinbody.splitlines():mKEY_RE.match(line.strip())ifm:ifcurrent:fields[current]\\n.join(buf).strip()current,bufm.group(1).lower(),[m.group(2)]elifcurrent:buf.append(line)ifcurrent:fields[current]\\n.join(buf).strip()returnfieldsdefparse_placeholders(text:str)-list[FigureSpec]:out[]forminFIGURE_BLOCK_RE.finditer(textor):fparse_fields(m.group(1))out.append(FigureSpec(rawm.group(0),kind(f.get(type)or辅助理解图).strip(),alt(f.get(alt)or配图).strip(),prompt(f.get(prompt)or).strip(),))returnoutdefreplace_one(body:str,raw:str,alt:str,filename:str)-str:mdfreturnbody.replace(raw,f\\n\\n{md}\\n\\n,1)出图时把kind prompt 文章标题拼成完整画面要求产物命名为figure-01.png、figure-02.png…合并时zip(占位列表, 文件列表)一对一替换。数量对不上就失败返回比默默少贴一张图更安全。改图与排错时盯住这几条只改编排意图不动已合并路径在合并前合并前改图改占位里的prompt/type删掉旧 PNG 再跑出图步骤即可正文位置不变。合并后若必须换图优先覆盖同名文件避免改 Markdown只有增删张数时才回头改占位并重跑解析。空占位与假外链要提前拦正文一个占位都没有可以按标题补一张「主题图片」但应打警告——说明作者没做画面规划。禁止模型在写作阶段写example.com、picsum之类假图链校验阶段直接删掉只保留合法占位。同一占位字符串必须唯一替换用「首次出现」重复 raw 会导致第二张图替换失败。和目录、标题注释的边界文首目录由平台脚本插入正文里不要再写目录标记。发布标题单独放在 不要再做同名一级标题避免目录里出现两个一样的入口。配图占位是第三种「机器可读注释」给人看的是段落给流水线看的是type/alt/prompt。把插图从「写到哪填到哪的文件名」改成「写到哪就钉在哪的意图描述」错位和难替换会一起变少。你下次开新篇时先定 23 个占位落点再写论证成图只是后一步的渲染。