Code Stitcher：把LLM输出安全缝进本地代码库

在实际的 LLM 应用开发中，生成代码只是第一步，真正决定效率的是如何把模型输出的代码安全、准确地落回本地代码库。Code Stitcher 这个名字抓住了这个过程的本质：它不是一个代码生成器，而是一个“缝合器”，负责把 LLM 输出中散落的代码片段、diff 补丁和新增文件，按照正确的路径和策略应用到项目里。这篇文章会用一整个可运行的示例，拆解这类工具的核心流程、解析策略、安全机制和排查路径。

如果你的日常工作里经常把 ChatGPT、Claude 或其他模型生成的多文件改动手动复制进编辑器，或者你在开发 LLM Agent、编码助手这类工具，那么理解 Code Stitcher 的设计思路会非常有用。本文围绕“LLM 输出如何变成本地文件变更”这条主线展开，先解释为什么要单独做一层“应用层”，再通过一个最小实现跑通完整流程，最后给出参数选型、常见坑和生产级建议。

1. 先理解为什么 LLM 输出不能直接写到本地代码库

1.1 复制粘贴模式的问题：看起来能用，实际不可控

很多人用 LLM 改代码是这样的：让模型修改某个文件，模型输出一段 Markdown，里面夹着几个代码块，然后手动把代码块复制到对应文件里。这种做法在小改动时没问题，但一旦涉及多个文件、多次迭代、团队协作，问题就会暴露。

首先是完整性问题。LLM 输出通常不是完整的文件内容，而是“修改后的函数”“新增的配置块”这类片段。复制粘贴时很容易漏掉上下文，或者把模型生成的示例代码误当作真实改动。

其次是定位问题。模型输出的代码块可能带有路径注释，例如src/utils/format.ts，也可能只是纯代码。靠人眼定位文件本身就是一个容易出错的环节，尤其是文件结构复杂、同名文件多的时候。

第三是异常污染。模型输出里通常混有解释性文字、前后对照、甚至错误的理解。手动应用时，这些噪音可能被一并带入代码库。

Code Stitcher 这类工具解决的就是这个“输出到落地”的断层。它把 LLM 的响应看作一种需要解析和校验的输入格式，而不是可以直接信任的文本。

1.2 Code Stitcher 解决的核心问题

Code Stitcher 本质上是一个 CLI 工具或库，接收 LLM 文本输出，解析出结构化的变更内容，再通过预设策略应用到本地代码库。

它的核心职责可以拆成四部分：

1. 解析：从纯文本中提取出代码片段、diff、文件路径和操作类型。
2. 定位：根据路径、锚点、上下文等线索，确定代码要写入哪个文件、哪个位置。
3. 应用：执行插入、替换、追加或新增文件操作。
4. 安全：在执行前提供 dry-run 预览、备份、确认和回滚机制。

它不是把 LLM 输出当作“最终答案”，而是当作“待验证的变更提案”。这个定位上的差异，决定了它的安全设计和应用策略。

1.3 和 diff、patch、MCP、Agent 的关系

熟悉传统开发流程的人会问：为什么不直接用diff和patch？

传统模式是：我们把已知的改动整理成 patch，再用git apply应用。这套流程可靠，但要求 LLM 输出严格合法的 unified diff。实际场景中，模型经常输出不完整、夹带 Markdown 说明、甚至忘记写diff --git头。Code Stitcher 的思路是“容错解析”，它在传统 patch 工具之上增加了一层对模型输出的兼容处理。

在 LLM Agent 体系里，Code Stitcher 可以理解为“工具调用层”的一部分。Agent 决定改什么，Stitcher 负责怎么安全落地。类似的能力也可以通过与 MCP（Model Context Protocol）搭配的本地文件工具实现，但两者侧重不同：MCP 提供的是协议化工具调用，Code Stitcher 提供的是针对代码库文本变更的专门解析和应用策略。

理解这一层关系后，再看下面的最小实现，思路会清晰很多。

2. 一个 stitch 工作流要经过哪些阶段

2.1 从模型响应到文件变更的完整链路

一次完整的 stitch 流程可以分成六个阶段：

1. 输入：把 LLM 的文本响应传给 Code Stitcher。
2. 提取：从响应中识别代码块、diff 块和标注了路径的说明。
3. 解析：把代码块转成结构化的变更对象，包含文件路径、类型（新增/修改/删除）、内容或补丁。
4. 预览：在真正写文件之前，生成一份变更清单，显示会动哪些文件、怎么动。
5. 应用：根据用户确认，执行实际文件写入。
6. 验证：检查文件结构、语法或运行相关测试。

很多自动化工具会把第 4 步直接跳过，这是非常危险的做法。模型输出的代码即使是合法的，也可能不是你想要的。dry-run 的价值不是形式，而是给用户一个纠错窗口。

2.2 核心概念：变更对象、应用策略、锚点

为了统一处理不同类型的输出，可以把每个变更抽象成一个对象：

{ "file": "src/utils/format.ts", "operation": "replace", "content": "export function formatDate(date: Date): string { ... }", "anchor": "function formatDate", "mode": "anchor" }

字段说明：

• file表示目标文件路径。
• operation表示操作类型，可以是insert、replace、append、create、delete。
• content是要写入的内容。
• anchor是定位用的锚点文本，例如函数名、唯一字符串。
• mode决定如何定位，常见值有anchor、line、regex、replaceAll。

应用策略指“如何把这段内容放进去”。全量替换简单粗暴，但风险高；锚点定位更精准，但依赖锚点唯一性。实际工具通常会组合使用。

2.3 安全边界：为什么必须先 dry-run 再写文件

LLM 输出天然存在不确定性。即使模型给出的代码逻辑正确，应用到错误位置也会造成破坏。因此，所有 Code Stitcher 类工具都应该遵守一条原则：默认不直接修改文件，先展示变更计划，经过确认后才执行。

具体安全措施包括：

• 写文件前自动创建备份文件。
• 使用 git 工作区时，先检查是否有未提交改动，避免覆盖。
• 提供--dry-run参数，只输出计划不执行。
• 记录操作日志，方便回滚。

注意：不要只验证工具能正常启动，要验证“改动应用到错误文件时是否能被识别”。这是安全机制是否有效的关键场景。

3. 用一个最小实现跑通 Code Stitcher 核心流程

3.1 环境准备与项目结构

为了讲清楚原理，这里用一个 TypeScript 版本的最小实现来演示。实际项目可以选择任意语言，核心逻辑是通用的。

环境要求：

项目结构如下：

code-stitcher-demo/ ├── src/ │ ├── cli.ts # 命令行入口 │ ├── parser.ts # 解析 LLM 输出，提取代码块和路径 │ ├── locator.ts # 定位目标文件 │ ├── applier.ts # 应用变更 │ └── types.ts # 公共类型定义 ├── package.json └── tsconfig.json

3.2 定义公共类型

先定义整个流程中流转的数据结构：

// src/types.ts export type OperationType = "create" | "replace" | "insert" | "append" | "delete"; export interface CodeChange { file: string; operation: OperationType; content?: string; anchor?: string; mode: "anchor" | "replaceAll" | "end" | "start" | "line"; line?: number; } export interface PlanResult { changes: CodeChange[]; warnings: string[]; }

CodeChange是解析器、定位器、应用器之间传递的统一对象。mode字段决定了应用器如何解释anchor和content。

3.3 解析器：从 LLM 输出中提取代码块

模型输出常见的格式如下：

下面修改 `src/utils/format.ts`，把日期格式化函数改为支持时区参数： ```typescript export function formatDate(date: Date, timeZone?: string): string { const formatter = new Intl.DateTimeFormat("zh-CN", { timeZone: timeZone ?? "Asia/Shanghai" }); return formatter.format(date); } ```

解析器需要做的事是：

1. 识别包含路径的说明行。
2. 提取紧跟其后的代码块。
3. 根据说明词（修改、新增、在文件末尾追加）推断操作类型。

// src/parser.ts import { CodeChange } from "./types"; const PATH_PATTERN = /`([^`]+\.(ts|js|tsx|jsx|py|java|go|json|yaml|yml|xml|css|html|md|sql))`/; const OPERATION_HINTS: Array<{ regex: RegExp; operation: CodeChange["operation"] }> = [ { regex: /新增|创建|新建|create/i, operation: "create" }, { regex: /删除|delete/i, operation: "delete" }, { regex: /末尾|追加|append/i, operation: "append" }, { regex: /修改|替换|更新|replace/i, operation: "replace" }, ]; export function parseLLMOutput(rawOutput: string): CodeChange[] { const lines = rawOutput.split("\n"); const changes: CodeChange[] = []; for (let i = 0; i < lines.length; i++) { const line = lines[i]; const pathMatch = line.match(PATH_PATTERN); if (!pathMatch) { continue; } const filePath = pathMatch[1]; const codeBlocks: Array<{ lang: string; code: string }> = []; let j = i + 1; while (j < lines.length) { const blockStart = lines[j].match(/^```(\w*)/); if (blockStart) { const lang = blockStart[1]; const codeLines: string[] = []; j++; while (j < lines.length && !lines[j].startsWith("```")) { codeLines.push(lines[j]); j++; } codeBlocks.push({ lang, code: codeLines.join("\n") }); } // 如果遇到下一个路径说明，说明当前文件的代码块收集结束 if (j < lines.length && PATH_PATTERN.test(lines[j]) && codeBlocks.length > 0) { break; } j++; } const operationHint = OPERATION_HINTS.find((hint) => hint.regex.test(line)); const operation = operationHint?.operation ?? (fileExists(filePath) ? "replace" : "create"); for (const block of codeBlocks) { changes.push({ file: filePath, operation, content: block.code, mode: operation === "create" ? "start" : "replaceAll", }); } } return changes; } function fileExists(path: string): boolean { // 实际实现用 fs.existsSync return false; }

这段代码演示了最简单的解析规则：路径出现在反引号里，代码块跟在路径说明后面，说明里出现了“新增/修改/追加”等关键词就映射到对应操作。

实际生产级解析器要复杂得多，需要处理：

• 模型输出的 diff 格式。
• 多个代码块指向同一文件。
• 路径出现在代码块内部注释里。
• 模型没有给路径，只能靠上下文推断。

3.4 定位器：把逻辑路径映射到物理文件

模型给出的路径不一定是实际路径，可能是相对项目根目录的，也可能是简写的模块名。定位器负责做一次归一化：

// src/locator.ts import { globSync } from "fast-glob"; import path from "node:path"; export function resolveFilePath(candidate: string, projectRoot: string): string | null { const clean = candidate.replace(/^\.\//, ""); const fullPath = path.resolve(projectRoot, clean); if (existsSync(fullPath)) { return fullPath; } // 使用 basename 做模糊匹配 const basename = path.basename(clean); const matches = globSync(`**/${basename}`, { cwd: projectRoot, ignore: ["node_modules/**"] }); if (matches.length === 1) { return path.resolve(projectRoot, matches[0]); } if (matches.length > 1) { // 返回 null 并收集警告，让用户选择 return null; } return null; }

模糊匹配只适合在同名文件唯一时使用。如果项目里有多个index.ts，靠 basename 匹配会产生歧义，此时应该返回明确错误，而不是随机选一个。

3.5 应用器：按模式写入内容

应用器是最后一个环节。它根据mode决定写入方式：

// src/applier.ts import fs from "node:fs"; import path from "node:path"; import { CodeChange } from "./types"; export function applyChange(change: CodeChange, projectRoot: string): void { const fullPath = path.resolve(projectRoot, change.file); if (change.operation === "create") { fs.mkdirSync(path.dirname(fullPath), { recursive: true }); fs.writeFileSync(fullPath, change.content ?? "", "utf-8"); return; } if (!fs.existsSync(fullPath)) { throw new Error(`目标文件不存在: ${change.file}`); } const original = fs.readFileSync(fullPath, "utf-8"); switch (change.mode) { case "replaceAll": fs.writeFileSync(fullPath, change.content ?? "", "utf-8"); break; case "end": fs.appendFileSync(fullPath, `\n${change.content}\n`, "utf-8"); break; case "start": fs.writeFileSync(fullPath, `${change.content}\n${original}`, "utf-8"); break; } }

这个实现把replaceAll当作“全量替换”。但真实场景里，LLM 输出的往往只是某个函数的新版本，而不是整个文件。如果直接全量替换，文件里其他内容会全部丢失。所以更合理的做法是，基于锚点做局部替换：

// 局部替换示例：找到 anchor 所在位置，替换到下一个匹配结构 function replaceAroundAnchor(original: string, anchor: string, newContent: string): string { const anchorIndex = original.indexOf(anchor); if (anchorIndex === -1) { throw new Error(`未找到锚点: ${anchor}`); } const before = original.slice(0, anchorIndex); const after = original.slice(anchorIndex); // 实际实现需要根据括号层级或空行判断替换范围 return `${before}${newContent}\n${after}`; }

这里最大的难点是“替换范围”的判断。锚点只是起点，终点在哪并不明确。常见做法是：从锚点开始向下扫描，遇到连续两个空行、或函数结束符}、或注释标记时截断。扫描规则写不好，就可能把后面的代码一并吞掉。

3.6 命令行入口与 dry-run 流程

CLI 入口把所有环节串起来：

// src/cli.ts import { parseLLMOutput } from "./parser"; import { applyChange } from "./applier"; import { resolveFilePath } from "./locator"; interface CliOptions { input: string; projectRoot: string; dryRun: boolean; } export function runStitch(options: CliOptions): void { const fs = require("node:fs"); const rawOutput = fs.readFileSync(options.input, "utf-8"); const changes = parseLLMOutput(rawOutput); console.log(`解析到 ${changes.length} 个变更：\n`); for (const change of changes) { const resolved = resolveFilePath(change.file, options.projectRoot); if (!resolved) { console.warn(`[警告] 无法定位文件: ${change.file}`); continue; } console.log(`[${change.operation}] ${resolved}`); if (options.dryRun) { continue; } applyChange({ ...change, file: resolved }, options.projectRoot); } if (options.dryRun) { console.log("\n当前是 dry-run 模式，未修改任何文件。"); } }

执行方式：

# 解析模型输出文件，只预览 node dist/cli.js --input llm-output.md --project-root . --dry-run # 确认后实际应用 node dist/cli.js --input llm-output.md --project-root .

dry-run 输出应该清楚显示每个文件将执行什么操作，让用户有机会在真正写入前发现路径错误或操作类型错误。

注意：示例中的解析器只覆盖了最简单场景。实际使用时，如果模型输出的格式不同，解析结果可能为空或产生错误变更。先把 dry-run 输出检查清楚，再应用文件。

4. 解析策略和应用策略的细节设计

4.1 模型输出的格式兼容问题

不同模型输出的代码风格差异很大。有的模型偏好输出完整文件，有的偏好输出 diff，还有的会在路径前加“文件：”或“File:` 前缀。Code Stitcher 的价值恰恰在于兼容这些差异。

常见的三种输出形态：

三种形态可以混合出现。解析器可以先判断文本中是否包含diff --git或@@，如果包含则按 diff 解析；否则按路径锚点解析。

4.2 diff 形式的解析与容错

unified diff 是工程上最可靠的形式，因为它天然包含了上下文。用diff这样的库解析后，可以得到结构化 hunk。

但模型输出的 diff 经常缺少diff --git头，只保留---、+++和@@部分。此时需要自己补全文件名信息，或根据上下文推断。容错处理可以这样做：

1. 尝试按标准 unified diff 解析。
2. 如果失败，去掉diff --git行再试。
3. 如果还是没有@@行，说明模型输出不完整，应终止而不是猜测。

diff 应用也有冲突概念。如果目标文件已经被修改过，原上下文可能失效。此时git apply会报错，Code Stitcher 也应该给出冲突提示，而不是强行写入。

4.3 锚点匹配的几种模式

锚点定位是“局部替换”的关键。锚点可以是：

• 函数名：export function formatDate
• 唯一字符串：const DEFAULT_TIMEOUT = 5000
• 正则表达式：/\/\/ @ts-ignore/
• 行号：不推荐，因为模型输出时不知道最新行号

锚点选择有一个重要原则：必须唯一。可以用一个简单检查：在文件内容里统计锚点出现次数，如果大于 1，应该要求用户确认。

function isAnchorUnique(content: string, anchor: string): boolean { const count = content.split(anchor).length - 1; return count === 1; }

如果锚点不唯一，工具应该返回歧义错误，推荐用户换用更长的上下文锚点，例如函数名加前后一行注释。

4.4 替换范围的判定方法

锚点定位之后，如何确定替换的结束位置？

一个比较稳妥的方法是“括号配对”：从第一个{开始计数，遇到{加一，遇到}减一，减到 0 时结束。这种方法适合函数、类、条件块，但对没有括号的配置文件和纯文本不适用。

另一个方法是“结构边界扫描”：从锚点向下扫描，遇到以下情况之一就结束：

• 连续两个空行。
• 下一个顶层}或end。
• 注释块结束标记。
• 下一个函数声明或导出声明。

实际实现通常把两者结合：优先做括号配对，配对失败时退回空行边界。这里不给出唯一的正确方案，因为不同语言和文件类型需要不同规则。关键是工具必须把“匹配到的范围”清晰地展示给用户，而不是默默吞掉内容。

5. 参数设计和风险控制

5.1 常见参数速查

一个 Code Stitcher 类工具通常具备以下参数：

--max-warnings是一个容易被忽视的参数。当解析器发现多个文件无法定位或锚点不唯一时，与其逐个交互，不如设置一个阈值，超过直接终止，避免误操作。

5.2 学习环境与生产环境的差异

学习环境里，工具直接改本地文件没有太大风险，因为代码库可以随时重置。生产环境里，Code Stitcher 的使用方式完全不同：

生产环境的推荐做法不是让工具直接改工作区，而是让工具生成一份“变更提案”，例如一个包含所有CodeChange对象的 JSON 文件，然后由另一个审批流程决定是否应用。

{ "proposalId": "20250217-001", "createdAt": "2025-02-17T10:30:00Z", "changes": [ { "file": "src/utils/format.ts", "operation": "replace", "mode": "anchor", "anchor": "export function formatDate", "contentPreview": "export function formatDate(date: Date, timeZone?: string): string { ... }" } ] }

这样的提案文件可以用 git diff 对比，也可以导入 CI 流水线做语法检查和测试，通过后再自动应用。

6. 常见问题和排查路径

6.1 解析结果为空

现象：输入了完整的 LLM 输出，但工具提示“解析到 0 个变更”。

可能原因：

1. 模型输出里没有使用反引号包裹路径。
2. 路径语言和解析器正则不匹配，例如路径是.vue或.tsx但正则只支持.ts。
3. 模型输出的是 diff，但解析器只实现了路径锚点解析。
4. 输入文件编码不是 UTF-8。

检查方式：

• 直接用文本编辑器查看输入文件，确认路径格式。
• 在解析器入口打印原始文本前 200 个字符。
• 把路径正则单独跑一遍，看看是否能匹配到目标路径。

解决方案：扩大路径正则的匹配范围，增加 diff 解析分支，统一输入编码。

6.2 路径匹配到错误文件

现象：模糊匹配时，项目里有多个同名index.ts，工具定位到了错误的那个。

原因：basename 匹配没有做唯一性校验。

检查方式：在定位器返回结果前，打印匹配到的所有候选路径。

解决方案：候选多于 1 个时直接报错，提示用户补充更多路径信息。不猜，不选第一个。

6.3 锚点匹配到多个位置

现象：使用函数名做锚点，但同名函数在文件和测试文件里都存在。

检查方式：统计锚点在目标内容中出现的次数。

解决方案：先用精确匹配，匹配不到再尝试正则；出现次数大于 1 时，要求用户补充上下文锚点，例如：

export function formatDate(date: Date): string { // 原有注释 }

把整个函数签名连同注释行作为锚点，唯一性会大幅提高。

6.4 替换后文件内容被吞

现象：应用完变更后，目标文件的尾部代码消失了。

原因：替换范围判定太激进，从锚点一直截到了文件末尾。

检查方式：对比 dry-run 输出的影响范围与预期。如果工具支持，查看应用前备份文件。

解决方案：把替换范围判定策略切换为brace，并加一个保护逻辑：当扫描到文件末尾仍未闭合时，丢弃这次变更并报错，而不是写入截断内容。

6.5 未提交改动被覆盖

现象：用户本地有未提交改动，应用变更后这些改动消失。

原因：工具直接写文件，没有检查 git 状态。

检查方式：应用前运行git status --porcelain检查目标文件是否已被修改。

解决方案：如果目标文件有未提交改动，默认中止并提示用户先提交或 stash。这样可以避免灾难性覆盖。

下表汇总了常见问题和对应排查顺序：

7. 最佳实践与扩展方向

7.1 应用前必须做的检查清单

每次把 LLM 输出应用到代码库之前，建议按这个清单逐项确认：

• [ ] dry-run 输出的变更数量是否合理。
• [ ] 每个目标路径是否能唯一确定。
• [ ] 每个锚点是否只在一个地方出现。
• [ ] 替换范围是否会覆盖到不相关代码。
• [ ] 目标文件当前没有未提交的关键改动。
• [ ] 本次变更是否真的需要“全量替换”，而不是局部修改。
• [ ] 是否已经生成了备份文件。
• [ ] 变更涉及的文件是否都属于当前项目，而不是依赖包或生成目录。

这个清单不是走过场。绝大多数 Code Stitcher 类工具造成事故，都是因为跳过了其中某一项。

7.2 与 LLM Agent、RAG 和 CI/CD 结合

Code Stitcher 不只是一个独立的 CLI 工具，它更适合嵌入到更大的 LLM 应用链路里。

在 LLM Agent 场景中，Agent 负责推理、拟定修改方案，Stitcher 负责把方案变成真实文件变更。两者结合时，Stitcher 应该向 Agent 暴露两种能力：

1. 预览接口：返回变更计划，让 Agent 决定是否执行。
2. 应用接口：执行变更并返回文件内容或 git diff，供 Agent 确认。

在 RAG 场景里，Stitcher 写回的代码可以作为新的上下文来源。比如把刚应用的代码片段向量化，加入会话记忆，避免后续对话时模型忘记刚才改了什么。

在 CI/CD 场景中，可以把 dry-run 输出作为 PR 描述的一部分，把提案 JSON 作为可审查的工件。这样既保留了自动化效率，也保留了人工审查的可控性。

7.3 不要用 Code Stitcher 做的事

明确工具的边界，比扩展它的功能更重要。

• 不要让它直接修改node_modules、vendor、dist等生成目录，除非显式指定。
• 不要让它自动执行新增代码里的命令，工具只负责写文件，不负责运行不可信代码。
• 不要在高风险变更中关闭 dry-run。全量替换一个复杂文件时，即使模型输出看起来正确，也应该先看影响范围。
• 不要在未确认备份策略的情况下，让工具自动覆盖多个文件。

7.4 与 LLM 精度问题的关联

在热词里频繁出现的 fp16、fp32、bf16 精度问题，表面上和 Code Stitcher 无关，但实际应用的体验里关系不小。模型输出代码时，如果用的是低精度推理，可能出现变量名拼写错误、参数名漂移、符号不匹配等问题。Code Stitcher 的锚点匹配经常会因为这种微小差异而失败。

所以一个实用的建议是：当锚点匹配频繁失败时，除了检查解析规则，还可以检查推理精度配置。在开发调试阶段使用 fp32 或 bf16 减少符号漂移，在批量生成时再切换到 fp16 提效。工具层面则应该把“锚点差异过大的警告”单独列出，方便定位是模型问题还是解析问题。

7.5 下一步可以尝试的方向

如果你对这个主题感兴趣，可以按以下路径继续深入：

1. 完善 diff 解析：使用成熟的 diff 库，支持标准git apply同样格式的补丁应用。
2. 增加语言感知：针对 TypeScript、Python、Go 等语言实现括号配对、字符串字面量跳过和注释识别。
3. 接入编辑器插件：把解析、预览、应用能力封装成 VSCode 插件或 JetBrains 插件。
4. 增加测试覆盖：构建一组包含正常输出、缺路径、锚点重复、diff 损坏的测试样本，验证解析器的容错能力。
5. 设计回滚机制：在应用前自动生成.stitch-backup目录，记录原文件，支持一键还原。

Code Stitcher 这类工具的价值，不在于把 LLM 输出“无脑应用”，而在于为模型输出和真实代码库之间建立了一条可控、可查、可回滚的通道。理解了解析、定位、应用和验证这一整条链路，无论自己实现还是使用现成工具，都能更快找到问题所在。文中那个最小示例只覆盖了最简单场景，落地到真实项目时，建议优先补齐 diff 解析、锚点唯一性校验和替换范围保护这三块能力。