Code Agent 的模糊编辑工具如何返回匹配类型、置信度和实际命中文本？

Code Agent 的模糊编辑工具不能只返回“成功”或“失败”。当工具允许旧文本与当前文件存在差异时，调用者必须知道它采用了哪种匹配策略、相似程度是多少，以及最终命中的原始文本是什么。match_type、confidence 和 matched_text 分别回答“怎样找到”“像到什么程度”“到底改了哪里”，三者共同构成一次模糊写入的可审计证据。

为什么模糊编辑需要更丰富的结果

精确替换的契约相对简单：旧字符串唯一存在就替换，否则拒绝。模糊工具为了容忍模型输出中的空白差异、过期上下文和轻微文本漂移，会搜索相似候选。容错提高了首次应用率，也引入新的不确定性：工具可能找到一个足够相似、却不是模型原本指向的代码块。

如果结果只有 status=applied，Agent 无法判断这次写入是百分之百精确命中，还是刚刚超过阈值的近似猜测。后续策略也无法分级：高风险修改与普通格式漂移会被同样处理。结构化匹配信息让 Agent 能在低置信度时重新读取，在精确命中时直接进入测试。

HarnessKit 的四级匹配链

HarnessKit 按固定顺序尝试四类策略。第一层是 exact，在文件中寻找完全相同的旧文本；唯一命中时类型为 exact，置信度为 1.0。第二层是 whitespace，删除双方全部空白后比较，再把命中位置映射回原文件；成功时类型为 whitespace，实现给出 0.95 的固定置信度。

第三层是 fuzzy。工具围绕旧文本长度构造不同大小的滑动窗口，使用标准库 SequenceMatcher 计算字符相似度，只保留超过可配置阈值的最佳候选。默认阈值为 0.8。第四层是 line_fuzzy，它按旧文本行数扫描连续行块，对每一行计算原始文本和展开制表符后的相似度，再取平均值。

策略具有优先级：只要较严格的一层得到唯一结果，就不会继续用更宽松的方法。这一点应体现在返回类型中，否则使用者无法区分一次看似相同的成功究竟经历了怎样的容错。

match_type 告诉调用者什么

match_type 是匹配路径的离散标签。在 HarnessKit 中可能是 exact、whitespace、fuzzy 或 line_fuzzy。它不是装饰字段，而是风险分类依据。exact 说明请求文本与磁盘文本一致；whitespace 表示非空白字符一致，但排版不同；fuzzy 与 line_fuzzy 则说明内容本身存在差异。

Agent 可以按类型决定复核强度。例如 exact 仍需查看 diff 和测试，但通常不必重新定位；whitespace 要检查缩进和格式是否被正确保留；fuzzy 应立即读取命中片段及其上下文；line_fuzzy 还应确认整段行边界没有吞掉相邻代码。

工具演进时，类型值需要保持稳定并写入接口文档。若新增语法树、锚点或符号匹配，应新增明确类型，而不是继续笼统返回 fuzzy，否则遥测和策略规则会失去意义。

confidence 不是正确概率

confidence 表示匹配算法内部的相似度或预设等级，不是“修改在语义上正确”的概率。HarnessKit 的 exact 固定为 1.0，whitespace 固定为 0.95，字符模糊匹配使用 SequenceMatcher 比率，逐行匹配使用各行相似度平均值。这些数值来源不同，不能直接当成经过校准的统一概率。

即便置信度为 1.0，也只说明文本完全一致，不能证明选中的函数符合用户意图。反过来，0.85 的候选可能正是格式化器修改后的目标。阈值控制的是工具愿意接受多大文本差异，业务风险仍应由 Agent 根据文件、改动类型和测试能力判断。

生产系统应按匹配类型分别统计置信度分布、误命中率和后续测试失败率，再建立策略。不要凭一个通用数字就自动批准所有修改。安全相关配置、迁移脚本和权限代码可以要求 exact；文档或生成文件可以接受更宽松的阈值。

matched_text 为什么不可缺少

matched_text 返回文件里真正被选中的文本。模糊匹配时，它往往不同于请求中的 old_text。没有这个字段，调用者只知道算法声称找到了候选，却无法展示或复核实际目标。

Agent 可以将 old_text、matched_text 和 new_text 做三方比较：先确认哪些部分属于环境漂移，再确认新内容是否应该应用到这些差异之上。日志系统也可以保存匹配文本的哈希和有限预览，既支持审计，又避免把整个敏感文件写入日志。

返回实际文本还帮助解释格式适配。HarnessKit 会根据命中文本的缩进、换行和差异尝试调整替换内容。只有看到 matched_text，开发者才能判断适配基于什么输入，并在结果异常时复现问题。

多候选不能用置信度强行打破

匹配算法可能找到多个同分且互不重叠的候选。HarnessKit 对每一级策略都先检查候选数量：唯一才返回，多个则抛出歧义错误。它不会仅因分数很高就随意选择文件中第一处。

这是模糊编辑的重要边界。两个完全相同的测试函数都能得到 1.0，但数值无法表达用户想改哪一个。恢复方式应是扩大旧文本上下文、增加稳定锚点，或让 Agent读取候选位置后重新发出精确请求。

结果对象怎样设计

一个实用结果至少包含状态、文件、匹配类型、置信度、实际命中文本和错误信息。HarnessKit 的结果模型还预留验证状态和 diff。成功时返回三项匹配证据；没有候选时返回 no_match；多候选时返回 ambiguous；语法验证失败则使用单独状态。

字段应使用稳定的 JSON 类型。置信度保持 0 到 1 的数值，不要格式化成字符串；未产生匹配时可以省略匹配字段或设为空；状态码与进程退出码应一致。CI 集成便可把状态、置信度和匹配类型输出给后续步骤。

Agent 如何消费这些字段

• exact：展示 diff，运行目标测试；对普通修改可继续流程。
• whitespace：核对缩进与行尾，必要时运行格式化器。
• fuzzy：读取 matched_text 前后上下文，确认语义对象后再接受。
• line_fuzzy：重点检查块边界、缺失行和新增行的落点。
• ambiguous：停止写入，搜索候选并扩展 old_text，不自动选第一处。
• no_match：重新读取文件，判断上下文漂移、错误路径或任务已完成。

日志与隐私如何平衡

完整 matched_text 对调试有价值，却可能包含密钥、个人数据或专有代码。交互结果可以短暂提供给当前 Agent，长期遥测则应限制长度、过滤敏感模式，或只保存内容哈希、行号、字符范围和匹配类型。

置信度和类型适合做聚合指标，例如每种策略的调用占比、模糊命中后的回滚率和测试失败率。不要只统计“应用成功率”，否则工具越激进，表面成功率反而越高。

还需要哪些验证

匹配证据只能说明定位过程，最终仍要检查生成 diff、语法和测试。HarnessKit 支持 dry-run，让调用者在不写盘时查看计划；还提供语法验证和原子模式，用于失败时回滚一组编辑。这些能力与匹配字段互补：前者控制状态变化，后者解释定位依据。

测试应覆盖每种 match_type、阈值边界、多个同分候选、Unicode、不同换行、制表符与空格，以及 matched_text 是否严格等于实际替换区间。还应验证序列化输出不会丢失换行或把数值变成字符串。

结论

模糊编辑的价值是容忍 Code Agent 的轻微文本误差，但容错不能变成不可见的猜测。match_type 说明算法路径，confidence 描述该路径下的相似程度，matched_text 暴露真实写入目标；缺少任何一项，调用者都难以建立可靠的复核策略。

最稳妥的接口不是追求每次都“成功应用”，而是让每次应用都能解释，让歧义明确失败，让低置信度触发更严格验证。这样模糊匹配才能从方便的字符串技巧，升级为可用于自动化编码流程的受控编辑能力。