write_to_file

write_to_file 工具用于新建文件，或通过交互式确认流程完全替换已有文件的内容。该工具会提供差异视图，支持用户在变更生效前对内容进行审核。

参数说明

本工具接收以下参数，均为必填项：

path（路径）：待写入文件的路径，基于当前工作目录的相对路径
content（内容）：待写入文件的完整内容
line_count（行数）：文件的总行数，包含空行在内

核心功能

该工具将指定内容写入目标文件：若文件不存在则完成新建，若文件已存在则对原有内容进行全量覆盖。所有内容变更均需通过差异视图界面获得用户的显式确认，用户可在变更生效前审核甚至编辑拟变更的内容。

适用场景

VJSP 需从零新建文件时
VJSP 需对已有文件进行全量重写时
为新项目批量创建多份文件时
生成配置文件、技术文档或源代码时
需在变更生效前对内容进行审核确认时

核心特性

交互式确认：以差异视图展示拟变更内容，变更生效前需用户显式确认
支持用户编辑：允许用户在最终确认前，对拟提交的内容进行编辑修改
安全防护机制：可检测代码遗漏问题、验证文件路径合法性、防止内容被截断
编辑器集成：打开差异视图时，自动滚动至第一处内容差异位置
内容预处理：兼容不同AI模型的输出结果，自动清理冗余内容标识
访问控制：执行变更前，校验.vjspignore配置的文件访问限制规则
父目录自动创建：依托系统依赖能力，自动创建文件所需的上级目录
全量替换：单次操作即可生成完成内容转换后的目标文件

局限性

不适用于已有文件的局部修改：相较于apply_diff工具，对已有文件进行修改时效率更低、耗时更长
大文件处理性能衰减：处理大文件时，操作执行效率会显著下降
全量覆盖机制：会替换文件的全部原有内容，无法保留指定的原始内容
强依赖行数参数：需传入准确的文件行数，才能实现内容截断风险的检测
审核流程带来额外开销：相较于直接编辑，交互式确认流程会增加额外的操作步骤
仅支持交互式执行：无法在要求非交互式运行的自动化工作流中使用

执行流程

调用write_to_file工具后，将按以下步骤执行操作：

参数校验:对必填参数的完整性及操作权限进行校验
- 检查path、content、line_count参数是否全部传入
- 校验目标文件是否允许访问（未被.vjspignore配置限制）
- 确保文件路径处于工作区的合法边界内
- 统计参数缺失的连续错误次数
- 针对不同的校验失败场景，展示专属的错误提示信息
内容预处理
- 移除 AI 模型可能添加的代码块标识符
- 处理转义的 HTML 实体字符（主要针对非 Claude 系列模型的输出）
- 若内容中意外包含行号，自动进行剥离处理
- 针对不同AI服务商的模型，执行专属的内容预处理逻辑
差异视图生成
- 在编辑器中打开差异视图，展示拟执行的内容变更
- 增加300毫秒延迟，保障界面的响应性
- 自动滚动至第一处内容差异的位置
- 对变更内容进行高亮标注，提升审核效率
用户确认流程
- 阻塞执行流程，等待用户的显式确认指令
- 支持用户在差异视图中直接编辑拟提交的内容
- 捕获用户的所有编辑操作，作为最终写入内容的组成部分
- 提供变更拒绝选项，支持用户放弃本次操作
- 检测并融合用户的修改内容，生成最终的待写入内容
安全校验
- 对比传入的line_count参数与实际内容行数，检测内容截断风险
- 若检测到内容可能不完整，即时展示告警信息
- 重新校验文件路径的合法性及操作的访问权限
- 通过isOutsideWorkspace标识，专门校验文件是否超出工作区边界
文件写入
- 将用户确认后的内容（含用户编辑的部分）写入目标文件
- 输出操作成功的确认提示
- 操作执行成功后，重置参数缺失的连续错误计数器

实际应用示例

新建项目时，VJSP 批量生成各类项目文件，且在提交变更前让用户逐份审核确认
配置文件初始化时，VJSP 在差异视图中展示拟生成的配置内容，供用户确认
技术文档生成时，VJSP 新建 Markdown 格式的文档文件，且支持用户在差异视图中完成最终的内容调整
原型开发阶段，VJSP 在差异视图中展示完整的源代码文件，用户可在保存前进行精细化调优

用法示例

新建JSON配置文件

<write_to_file>
<path>config/settings.json</path>
<content>
{
  "apiEndpoint": "https://api.example.com",
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d",
    "fontFamily": "Arial, sans-serif"
  },
  "features": {
    "darkMode": true,
    "notifications": true,
    "analytics": false
  },
  "version": "1.0.0"
}
</content>
<line_count>14</line_count>
</write_to_file>

新建简易HTML文件

<write_to_file>
<path>src/index.html</path>
<content>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Application</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <div id="app"></div>
  <script src="app.js"></script>
</body>
</html>
</content>
<line_count>13</line_count>
</write_to_file>

新建JavaScript模块文件

<write_to_file>
<path>src/utils/helpers.js</path>
<content>
/**
 * 应用程序通用工具函数库
 */

export function formatDate(date) {
  return new Date(date).toLocaleDateString();
}

export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

export function debounce(func, delay) {
  let timeout;
  return function(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), delay);
  };
}
</content>
<line_count>18</line_count>
</write_to_file>

write_to_file ​

参数说明 ​

核心功能 ​

适用场景 ​

核心特性 ​

局限性 ​

执行流程 ​

实际应用示例 ​

用法示例 ​