Markdown 文档更新技能说明

本文档总结了处理 Markdown 文件更新任务时的通用方法，尤其适用于“扩写文档”“润色说明”“更新首页介绍”等场景。

适用场景

当任务满足以下任意一种情况时，可以使用这套方法：

• 需要修改已有 Markdown 文档内容。
• 需要在不改变主题的前提下扩写描述。
• 需要同时更新多个说明性文件，比如 README.md、index.md、AGENT.md 等。
• 需要避免覆盖用户已经确认的最终版本。

核心原则

先确认基线，再修改内容

不要假设文件内容和用户提供的片段完全一致。真正修改前，应先确认当前文件的真实内容，尤其是在文件可能已被手动修改的情况下。

先小改，后大改

优先使用精确替换完成局部更新。这样影响范围更小，也更容易控制变更。

如果精确替换失败，再升级为补丁更新或整体覆盖，不要一开始就使用破坏性更强的方式。

最近修改的文件必须重读

如果系统提示某个文件是最近修改后的最终版本，继续编辑前必须重新读取。后续所有修改都必须基于这个新版本继续进行。

标准处理步骤

第一步：先读文件

在准备修改 README.md 或其他 Markdown 文件前，先读取目标文件，确认：

• 当前内容是否和预期一致。
• 是否存在额外空行、格式差异或用户刚刚做过的修改。
• 文件是否已经是最新最终版本。

第二步：尝试精确替换

当只需要替换一小段文本时，优先使用精确搜索替换。这样可以：

• 控制改动范围。
• 减少误修改其他内容的风险。
• 保持文件其余部分完全不变。

第三步：替换失败时先判断原因

如果出现无法命中的情况，不要立即重复提交相同替换。应优先判断以下可能性：

• 搜索文本与真实文本不完全一致。
• 存在不可见字符或换行差异。
• 文件内容已经在别处被修改。
• 上下文已经过期。

第四步：必要时改用补丁更新

当文件较短，且精确替换反复失败时，改用补丁更新通常更高效。补丁方式适合：

• 整体替换一小段文件内容。
• 在已知原始行内容的前提下稳定更新。
• 避免为不可见字符反复调试搜索文本。

第五步：多文件任务要拆开处理

如果同时更新多个文件，不要假设它们都能一次成功。正确做法是：

• 确认哪些文件已经成功。
• 只继续处理失败的文件。
• 避免重复改动已经确认完成的文件。

常见问题与处理建议

问题：明明看起来一样，为什么匹配失败

原因通常不是内容语义不同，而是文本字节层面不完全相同，例如换行、空格或隐藏字符不同。

建议先重新读取文件，再决定是否继续精确替换。

问题：文件已经被用户改过，还能继续用旧内容改吗

不能。只要提示文件是最近修改后的最终版本，就必须重读。否则容易覆盖用户已确认的内容。

问题：什么时候该从替换切换到补丁

当同一个文件多次精确替换失败，并且文件体量不大时，就应该尽快切换到补丁方式，而不是继续消耗在文本匹配上。

推荐实践

• 修改前先读取。
• 修改失败先确认基线。
• 多文件任务逐个确认状态。
• 用户已确认的文件不要重复改。
• 精确替换不稳定时尽快切换补丁。

总结

Markdown 文档编辑看似简单，但真正容易出错的地方往往不是写内容，而是“基于什么版本改”。只要把“先确认基线、再执行修改、失败后切换策略”这套流程固定下来，处理大多数文档更新任务都会稳定很多。