Lzh on GitHub

insert_content

该工具的作用是在现有文件中添加新的内容行，而不会修改原始内容。它非常适合在特定位置插入代码块、配置条目或日志行。

该工具的作用是在现有文件中添加新的内容行，而不会修改原始内容。它非常适合在特定位置插入代码块、配置条目或日志行。

参数

该工具接受以下参数：

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

功能与使用时机

insert_content 工具会读取目标文件，根据 line 参数识别指定的插入点，然后将提供的内容插入到该位置。如果 line 为 0，内容将添加到文件末尾。在保存更改之前，会以差异视图的形式呈现更改，以供用户批准。

该工具在以下情况中使用：

  • 在文件开头添加新的导入语句。
  • 将新函数或方法插入到现有代码中。
  • 向设置文件中添加配置块。
  • 附加日志条目或数据记录。
  • 添加任何多行文本块，而不更改现有行。

主要功能

  • 精准插入：将内容精确地添加到指定的行号，或附加到文件末尾。
  • 保留现有内容：不会修改或删除原始文件行。
  • 交互式批准：在差异视图中显示提议的插入内容，需要用户的明确批准。
  • 支持用户编辑：允许在最终批准前，直接在差异视图中编辑提议的内容。
  • 行号处理：正确解析 line 参数（基于 1 的行号或用于附加的 0）。
  • 上下文跟踪：记录文件编辑操作以进行上下文管理。
  • 错误处理：检查是否缺少参数、行号是否无效以及文件访问问题。

局限性

  • 仅插入：无法替换或删除现有内容。
  • 需要现有文件：path 指定的目标文件必须存在。
  • 审查开销：强制性的差异视图批准会增加一个交互步骤。

工作原理

当调用 insert_content 工具时，它会遵循以下流程：

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

用法示例

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

<insert_content>
  <path>src/utils.ts</path>
  <line>1</line>
  <content>
    // Add imports at start of file
    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>