Skip to main content

insert_content

insert_content 工具可以在现有文件中插入新的内容行，而不会修改原有内容。它非常适合在特定位置插入代码块、配置项或日志行。

参数​

该工具接受以下参数：

  • path（必需）：要插入内容的文件的相对路径（相对于工作区根目录）。
  • line（必需）：要在其之前插入内容的 1 基线号。使用 0 可将内容追加到文件末尾。
  • content（必需）：要插入的文本内容。

功能说明​

该工具会读取目标文件，根据 line 参数确定插入点，并在该位置插入提供的 content。如果 line 为 0，则内容会被添加到文件末尾。更改会以 diff 视图的形式展示，需用户批准后才会保存。

适用场景​

  • 在文件开头添加新的 import 语句。
  • 在现有代码中插入新的函数或方法。
  • 向配置文件添加配置块。
  • 追加日志条目或数据记录。
  • 在不更改现有行的情况下添加任何多行文本块。

主要特性​

  • 精准插入：可在指定行号精确插入内容，或追加到文件末尾。
  • 保留原有内容：不会修改或删除原有文件行。
  • 交互式审批：以 diff 视图展示拟议插入内容，需用户明确批准。
  • 支持用户编辑：允许用户在 diff 视图中直接编辑拟议内容后再批准。
  • 行号处理：正确解析 line 参数（1 基或 0 追加）。
  • 上下文追踪：记录文件编辑操作以便上下文管理。
  • 错误处理：检查参数缺失、行号无效和文件访问问题。

局限性​

  • 仅支持插入：无法替换或删除现有内容。如需修改请使用 apply_diff 或 search_and_replace。
  • 需文件已存在：path 指定的目标文件必须已存在。
  • 需审批流程：强制 diff 视图审批会增加一步交互流程。

工作原理​

当调用 insert_content 工具时，流程如下：

  1. 参数校验：检查 path、line 和 content 是否提供，且 line 为非负整数。
  2. 文件读取：读取由 path 指定的目标文件内容。
  3. 插入点计算：将 1 基的 line 参数转换为内部处理用的 0 基索引（追加时为 -1）。
  4. 内容插入：使用内部工具（insertGroups）将原文件行与新 content 在计算出的索引处合并。
  5. diff 视图交互：
    • 在 diff 视图中打开文件（cline.diffViewProvider.open）。
    • 用拟议内容更新 diff 视图（cline.diffViewProvider.update）。
  6. 用户审批：通过 askApproval 呈现更改，若被拒绝则回滚。
  7. 保存更改：如获批准，使用 cline.diffViewProvider.saveChanges 保存更改。
  8. 文件上下文追踪：通过 cline.getFileContextTracker().trackFileContext 追踪编辑。
  9. 处理用户编辑：如用户在 diff 视图中编辑了内容，会报告最终合并内容。
  10. 结果报告：报告成功（包括用户编辑）或失败。

使用示例​

在文件开头插入 import 语句（line: 1）：

<insert_content>
<path>src/utils.ts</path>
<line>1</line>
<content>
// 在文件开头添加 import
import { sum } from './math';
import { parse } from 'date-fns';
</content>
</insert_content>

在文件末尾追加内容（line: 0）：

<insert_content>
<path>config/routes.yaml</path>
<line>0</line>
<content>
- path: /new-feature
  component: NewFeatureComponent
  auth_required: true
</content>
</insert_content>

在第 50 行前插入函数：

<insert_content>
<path>src/services/api.js</path>
<line>50</line>
<content>
async function fetchUserData(userId) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error('Failed to fetch user data');
  }
  return response.json();
}
</content>
</insert_content>