write-file

name	write-file
description	创建或覆盖文件：工作区作用域写入，需计划确认。当需要新建文件或完整重写文件内容时触发此技能。
tools	write_file
metadata	{"category":"tools","tree_id":"fs/write_file","tree_group":"fs","min_tier":"task_write","approval_type":"plan_confirm","emoji":"✍️","enabled_when":"always","file_access":"scoped_write","scope_check":"workspace","security_level":"sandboxed","policy_groups":["group:fs"],"profiles":["coding","full"],"wizard_group":"fs","sort_order":3,"exclude_from":["task_delete"],"intent_keywords":{"zh":["写","编写","创建","新建","修改","改一","改个","改成","修","添加","新增","生成","重构","派生"],"en":["write","create","add","modify","fix","generate","refactor","update"]},"intent_priority":10,"related_tools":["read_file","apply_patch"],"scene_hint":"单文件写入用write_file，多文件批量修改用apply_patch","summary":"Create or overwrite files","title":"Write File","verb":"Write","detail_keys":"path","tool_description":"创建或覆盖写入文件内容，工作区作用域限制。","tool_input_schema":{"type":"object","properties":{"path":{"type":"string","description":"Path to the file"},"content":{"type":"string","description":"Content to write"}},"required":["path","content"]}}

Write File — 文件写入

参数

参数	必填	说明
path	是	目标文件路径（工作区作用域内）
content	是	完整文件内容

使用指南

• 创建新文件或完整覆盖现有文件
• 作用域限定于工作区 — 无法写入工作区边界之外
• 执行前需要计划确认（plan_confirm）
• 部分编辑优先使用 apply_patch（结构化 diff 格式）
• 在新位置创建文件前，应先与用户确认写入路径
• 排除于 task_delete 意图 — 删除操作不会触发此工具

适用场景

• 创建全新文件（代码、配置、文档）
• 完整重写现有文件内容
• 批量生成模板文件

不适用场景

• 局部修改 → 使用 apply_patch
• 单行变更 → 使用 bash 配合 sed/echo
• 删除文件 → 使用 bash 的 rm 命令

---

常见用法模式

创建新文件

write_file path="src/utils/helpers.ts" content="export function isEmpty(v: unknown): boolean {\n  return v == null || v === '';\n}\n"

创建全新文件最典型的用法。content 为文件完整内容，包含末尾换行符。

覆盖现有文件

# 先读取确认当前内容
read_file path="config/app.yaml"
# 再写入新内容
write_file path="config/app.yaml" content="..."

必须先 read_file 确认当前内容后再写入，避免意外覆盖用户未预期的变更。这是核心安全规则。

批量生成模板

# 生成多个结构相似的文件
write_file path="src/models/user.ts" content="..."
write_file path="src/models/order.ts" content="..."
write_file path="src/models/product.ts" content="..."

适用于脚手架生成、项目初始化等场景。每个文件独立调用。

追加内容（间接方式）

write_file 本身是全量覆盖操作，不支持追加。如需追加：

• 少量追加：read_file 读取 → 拼接新内容 → write_file 写回
• 单行追加：bash + echo "new line" >> file.txt（更高效）
• 结构化追加：apply_patch 在文件末尾插入新段落

安全规则

写前必读

在覆盖现有文件之前，必须先用 read_file 读取当前内容。原因：

1. 确认文件当前状态，避免覆盖用户并行修改
2. 理解完整上下文，确保不遗漏非目标区域的内容
3. 如果只需局部修改，识别后改用 apply_patch 更安全

路径确认

• 首次在新位置创建文件前，应先询问用户确认路径
• 不要假设目录结构已存在；必要时先用 bash + mkdir -p 创建目录
• 工作区外路径会被拒绝 — write_file 作用域限定于工作区

备份考量

• write_file 覆盖后无内置回滚机制
• 对关键文件，可先用 bash + cp file file.bak 创建备份
• 在 git 仓库中，可依赖 git diff / git checkout 恢复

内容完整性

• content 参数必须包含文件的完整内容，不是增量 diff
• 遗漏原有内容等同于删除该内容 — 这是最常见的错误来源
• 写入前在心理上核对：新内容 = 旧内容中需要保留的部分 + 变更部分

审批模型详解

write_file 的审批类型为 plan_confirm，意味着：

阶段	行为
意图分析	仅在 task_write 及以上意图层级触发；task_delete 意图被排除
计划确认	执行前向用户展示写入计划（目标路径 + 内容摘要）等待确认
执行	确认后写入文件，返回成功/失败状态

与 bash 的 exec_escalation 审批不同，plan_confirm 侧重于内容审查而非权限提升。

错误处理指南

错误场景	表现	处理方式
路径超出工作区	写入被拒绝	确认路径在工作区范围内；系统文件写入需走 bash + 提权
目录不存在	写入失败	先用 bash + mkdir -p 创建父目录
权限不足	写入失败	检查目录写入权限；考虑是否需要 bash 提权操作
磁盘空间不足	写入失败	用 bash + df -h 检查可用空间
计划被用户拒绝	操作取消	根据用户反馈调整方案，重新提交

跨工具决策指南

需求	推荐工具	原因
创建全新文件	write_file	最直接，有计划确认保护
完整重写文件	write_file	语义清晰，替换全部内容
修改文件中几行	apply_patch	结构化 diff，只改目标行，不碰其余内容
追加一行到文件末尾	bash + echo >> file	不需要读取全文，高效且无审批
修改配置中的单个值	bash + sed -i	针对简单替换更高效
写入工作区外路径	bash + tee/echo >	write_file 不支持工作区外写入
写入需要 root 权限的文件	bash + sudo tee	需要 exec_escalation 审批
同时创建目录和文件	bash + mkdir -p && cat >	write_file 不自动创建父目录
基于模板批量生成	write_file 循环调用	每个文件有独立确认，更安全

典型组合工作流

1. 安全覆盖：read_file 确认内容 → write_file 写入新版本
2. 精准编辑：read_file 定位 → apply_patch 局部修改（优先于 write_file）
3. 脚手架生成：bash + mkdir -p 创建结构 → 多次 write_file 填充内容
4. 配置迁移：read_file 读取旧配置 → 转换格式 → write_file 写入新配置