DevFlow/docs/ai-file-ops-manual.md

AI 文件操作工具能力手册

最后更新：2026-06-15 | 基于全量测试验证

---

工具总览

工具	用途	可靠性
read_file	读取文件内容（全文/分页）	✅ 高
write_file	创建/覆盖写入文件（纯文本）	✅ 高
list_directory	列出目录内容（含递归/深度控制）	✅ 高
run_command	执行 shell 命令	⚠️ 可执行，但 stdout 不可用

---

read_file

读取文件内容，支持分页。

参数

参数	类型	必填	说明
path	string	✅	文件路径，支持 / 和 \
offset	number	❌	起始行（0 基索引），默认 0
limit	number	❌	读取行数，默认全部

行为规则

• offset 是 0 基索引：offset=0 → 第 1 行，offset=10 → 第 11 行
• offset 超出总行数 → 返回空内容，不报错
• limit 超出剩余行数 → 返回到末尾，不报错
• 空文件 → 返回 { content: "", lines: 0, size: 0 }
• 不存在的文件 → 报错 os error 2
• 二进制文件 → 返回 { binary: true, content: null, error: "文件非 UTF-8 文本" }
• 路径越界（项目目录外）→ 被拦截

返回结构

{
  "content": "文件文本内容",
  "lines": 30,      // 总行数（始终是全量值，非当前页行数）
  "size": 145,      // 总字节数（始终是全量值）
  "path": "..."
}

⚠️ lines 和 size 始终返回全量值，不受 offset/limit 影响。

---

write_file

创建或覆盖写入文件，纯文本模式。

参数

参数	类型	必填	说明
path	string	✅	文件路径
content	string	✅	文本内容（UTF-8）

行为规则

• 自动创建多级父目录：路径中不存在的目录会自动创建
• 覆盖已有文件：直接覆盖，无确认机制（⚠️ 注意安全）
• 返回 old_size（覆盖前大小，新建时为 null）和 bytes_written（写入大小）
• 支持 emoji、引号、反斜杠、中文等特殊字符
• 路径分隔符 / 和 \ 均可
• 中文路径/文件名含空格 → 正常工作
• 空内容（content=""）→ 创建 0 字节文件
• 无法写入二进制数据（NULL 字节等会被当文本处理）
• 路径越界（项目目录外）→ 被拦截

局部修改的正确做法

write_file 是全量覆盖，局部修改需三步：

1. read_file 获取完整内容
2. AI 在内存中替换目标行/文本
3. write_file 写回完整内容

---

list_directory

列出目录内容，支持递归和深度控制。

参数

参数	类型	必填	说明
path	string	✅	目录路径
recursive	boolean	❌	是否递归，默认 false
max_depth	number	❌	递归最大深度（配合 recursive）
skip_noise_dirs	boolean	❌	跳过 node_modules/.git 等，默认 false

返回结构

{
  "entries": [
    { "name": "src", "type": "directory", "size": 0, "depth": 0 },
    { "name": "main.ts", "type": "file", "size": 466, "depth": 0 }
  ],
  "truncated": false
}

行为规则

• type 取值："directory" | "file"
• depth：0 = 根层级，1 = 一级子目录，以此类推
• 不存在的目录 → 报错 os error 3
• truncated: false 表示结果完整未截断

---

run_command

执行 shell 命令。

参数

参数	类型	必填	说明
command	string	✅	shell 命令（非交互式）
working_dir	string	❌	工作目录
timeout_secs	number	❌	超时秒数，默认 60

⚠️ 已知问题

stdout 始终返回空字符串（已确认是普遍问题）：

• echo、Write-Output 等输出无法被捕获
• 命令本身能正常执行（cp/mv/rm/重定向写文件均验证通过）
• stderr 大部分场景也为空

可靠使用的场景

场景	可靠性	示例
删除文件 rm	✅	rm -f path/to/file
复制文件 cp	✅	cp src.txt dst.txt
移动/重命名 mv	✅	mv old.txt new.txt
创建目录 mkdir	✅	mkdir -p deep/nested/dir
写入文件（重定向）	✅	echo content > file.txt
二进制写入 printf	✅	printf '\x89PNG' > file.png
超时控制	✅	timeout_secs=3 正确中断
工作目录切换	✅	working_dir 生效，相对路径可用
获取命令输出	❌	stdout/stderr 不可用

---

快速参考：常见操作怎么做

我想要...	工具调用
读文件全文	read_file(path)
读第 10~15 行	read_file(path, offset=9, limit=6)
创建新文件	write_file(path, content)
修改文件中某几行	read_file → AI 替换 → write_file
追加内容到文件末尾	read_file → 拼接 → write_file
删除文件	run_command("rm -f path")
重命名文件	run_command("mv old new")
列出项目结构	list_directory(path, recursive=true, max_depth=3)
搜索文件内容	分页 read_file 逐段扫描（无原生搜索）
搜索文件名	list_directory 递归 + AI 过滤（无原生 glob）
写入二进制文件	run_command("printf '\x89...' > file")
获取文件大小/行数	read_file（必须读内容，无轻量元信息工具）

---

待实现能力（已建任务）

能力	任务 ID	优先级
文件内容搜索 search_in_file	F-FILE-01	P1
文件局部更新 patch_file	F-FILE-02	P1
文件元信息 file_info	F-FILE-03	P1
run_command stdout 修复	F-FILE-07	P1
追加写入 append_file	F-FILE-04	P2
文件名搜索 search_files	F-FILE-05	P2
Base64 二进制写入	F-FILE-06	P2
文件差异对比 diff_file	F-FILE-08	P3