Qwen Code 文件系统工具全解析：从 list_directory 到 edit 的源码级使用指南

Qwen Code 文件系统工具全解析从 list_directory 到 edit 的源码级使用指南【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeQwen Code 是运行在终端中的开源 AI 编程代理其与本地文件系统交互的能力全部由一组内置工具承载。本文以 docs/developers/tools/file-system.md 为骨架结合packages/core/src/tools/下的真实实现系统讲解list_directory、read_file、notebook_edit、write_file、glob、grep_search、edit七个工具的调用参数、输出格式、权限确认机制与平台差异帮助你理解模型读写代码时的底层行为并为二次开发或自定义工具提供参考。安全边界一切操作都限定在 rootDirectory 之内所有文件系统工具都运行在一个rootDirectory通常是启动 CLI 时的当前工作目录之内出于安全考虑工具要求传入绝对路径或相对于该 root 目录进行解析。从源码看路径解析与校验集中在 packages/core/src/utils/paths.ts 的resolveAndValidatePath、isSubpath等函数中edit工具在失败条件里明确包含“file_path不是绝对路径或位于 root 目录之外”。权限层面各工具并不相同list_directory对工作区、用户 skills 目录、用户扩展目录和 memory 目录内的路径返回allow其余路径返回ask见 ls.ts 的getDefaultPermission实现read_file、glob、grep_search通常无需确认写操作类工具write_file、edit、notebook_edit默认需要用户批准并在写入前展示 diff在自动批准模式或规则放行时除外。1.list_directoryListFiles目录内容列举list_directory列出指定目录下的文件和子目录名称可按 glob 模式忽略部分条目。Tool namelist_directoryDisplay nameListFilesFilels.ts参数pathstring必填要列出的目录绝对路径ignorestring[]可选要从结果中排除的 glob 模式列表例如[*.log, .git]respect_git_ignoreboolean可选是否遵循.gitignore规则默认true。行为细节与源码对照返回每个条目的名称并标记其是否为目录目录优先、再按字母序排序——对应 ls.ts 中的entries.sort逻辑单次最多展示MAX_ENTRY_COUNT 100条同时受truncateToolOutputLines配置约束见 ls.ts超出部分截断空目录返回Directory ... is empty.而非报错除ignore参数外还会通过文件发现服务过滤被.gitignore/.qwenignore忽略的文件filterFilesWithReportls.ts。输出llmContent示例Directory listing for /path/to/your/folder: [DIR] subfolder1 file1.txt file2.png确认否工作区路径内工作区外的路径请求需要用户确认。注意该工具是opt-in的默认关闭因为glob在多数情况下已覆盖目录列举需求。需在设置中将tools.listDirectory.enabled设为true或通过--core-tools/tools.core的coreTools白名单显式加入list_directory。2.read_fileReadFile读取文件与多模态内容read_file读取并返回指定文件的内容支持文本文件与当前模型支持模态的媒体文件图片、PDF、音频、视频。Tool nameread_fileDisplay nameReadFileFileread-file.ts参数file_pathstring必填要读取文件的绝对路径offsetnumber可选文本文件从第几行开始读0 起设置时必须同时设置limitlimitnumber可选最多读取的行数不设置时读取默认上限约 2000 行或整个文件pagesstring可选PDF 的 1 起页或闭区间页范围如3或20-25单次请求最多 20 页。行为细节文本文件返回内容配合offset/limit只返回对应行切片并注明是否因行数或行长限制被截断截断提示形如[File content truncated: showing lines 1-100 of 500 total lines...]媒体文件若模型支持该模态返回 base64 编码的inlineData对象{ inlineData: { mimeType: image/png, data: base64encodedstring } }若不支持返回带替代方案建议的错误信息PDF 的文本提取与视觉回退对纯文本主模型先尝试文本提取提取失败、或显式请求或实际的单页超出 12K token 文本预算时配置的视觉桥vision bridge会渲染并转写从请求首页开始的至多四页源码中PDF_TEXT_RESULT_MAX_TOKENS 12_000、PDF_MAX_PAGES_PER_READ 20定义于 pdf.ts。转写结果会被标记为“不可信的机器生成内容”并在 TUI、ACP、结构化输出与导出中标识所用视觉模型与端点其他二进制文件识别后跳过返回类似Cannot display content of binary file: /path/to/data.bin的信息。确认否。Jupyter notebook 的读取对.ipynb文件read_file会解析 notebook JSON返回结构化的、模型可读的视图包含 notebook 语言、有序单元格、cell ID、源码与摘要输出而非原始 JSON。offset/limit对.ipynb不生效若渲染输出过大导致内部截断后续notebook_edit会拒绝单元格级编辑要求先精简输出或拆分 notebook。3.notebook_editNotebookEdit安全地按单元格编辑 .ipynb修改 notebook 单元格时应使用notebook_edit而非edit或write_file。Tool namenotebook_editDisplay nameNotebookEditFilenotebook-edit.ts参数notebook_pathstring必填.ipynb文件绝对路径cell_idstring可选read_file显示的单元格 IDreplace和delete必填insert时新单元格插入到该单元格之后省略则插入到开头new_sourcestring可选replace/insert的新单元格源码delete不需要cell_typecode或markdown可选插入单元格的类型或替换时的目标类型edit_modereplace、insert或delete可选编辑操作默认replace源码中const mode params.edit_mode ?? replace见 notebook-edit.ts。行为细节要求本会话中先用read_file读取过该 notebook通过read_file渲染出的 ID 定位单元格包括真实 notebook cell ID 与显示的cell-N回退 ID遇到歧义 ID 时拒绝猜测code 单元格源码变化时清除过期输出并重置execution_count尽量保留 notebook 的 JSON 格式、行尾、编码与 BOM结构性编辑导致回退 ID 可能移位后会使先前的读取状态失效下次编辑前需重新read_file。确认是。写入前展示 notebook JSON diff 并请求用户批准除非当前权限模式或规则自动批准编辑类工具。示例替换一个 code 单元格notebook_edit( notebook_path/path/to/analysis.ipynb, cell_idload-data, new_sourceresult 41 1\nprint(result) )在既有单元格后插入 markdown 单元格notebook_edit( notebook_path/path/to/analysis.ipynb, edit_modeinsert, cell_idsummary, cell_typemarkdown, new_source## Findings\n\nThe cleaned data is ready for modeling. )删除单元格notebook_edit( notebook_path/path/to/analysis.ipynb, edit_modedelete, cell_idold-experiment )4.write_fileWriteFile写文件与覆盖write_file将内容写入指定文件文件存在则覆盖不存在则创建同时创建必要的父目录。Tool namewrite_fileDisplay nameWriteFileFilewrite-file.ts参数file_pathstring必填要写入文件的绝对路径contentstring必填要写入的内容。行为细节不写原始 Jupyter notebook JSON.ipynb的单元格编辑请使用notebook_edit父目录不存在时自动创建写入时会保留既有文件的编码与 BOM见下文“文件编码与平台行为”。输出示例Successfully overwrote file: /path/to/your/file.txt或Successfully created and wrote to new file: /path/to/new/file.txt。确认是。写入前展示变更 diff 并请求批准。5.globGlob按模式查找文件glob根据 glob 模式查找文件如src/**/*.ts、*.md返回按修改时间排序最新在前的绝对路径。Tool nameglobDisplay nameGlobFileglob.ts参数patternstring必填要匹配的 glob 模式如*.py、src/**/*.jspathstring可选搜索目录缺省为当前工作目录。行为细节与源码对照基于glob包实现globStreamglob.ts默认遵循.gitignore、.qwenignore及配置的自定义 Qwen ignore 文件单次最多返回MAX_FILE_COUNT 100个文件glob.ts防止上下文溢出排序采用“近期修改优先”策略最近修改阈值内的文件按最新在前排列旧文件按字母序排在后面sortFileEntriesglob.ts。输出示例Found 5 file(s) matching *.ts within /path/to/search/dir, sorted by modification time (newest first): --- /path/to/file1.ts /path/to/subdir/file2.ts --- [95 files truncated] ...确认否。6.grep_searchGrep正则搜索文件内容grep_search在指定目录的文件内容中搜索正则表达式模式可用 glob 过滤文件返回命中的行及其文件路径与行号。Tool namegrep_searchDisplay nameGrepFilegrep.ts回退实现为 ripGrep.ts参数patternstring必填要搜索的正则表达式如function\\smyFunction、log.*Errorpathstring可选搜索的文件或目录缺省为当前工作目录globstring可选按 glob 过滤文件如*.js、src/**/*.{ts,tsx}limitinteger可选只输出前 N 个匹配行必须是正整数不设置则输出全部匹配。行为细节优先使用 ripgrep 快速搜索不可用时回退到 JavaScript 实现默认大小写不敏感遵循.gitignore、.qwenignore及自定义 ignore 文件限制输出量防止上下文溢出。输出示例Found 3 matches for pattern myFunction in path . (filter: *.ts): --- src/utils.ts:15:export function myFunction() { src/utils.ts:22: myFunction.call(); src/index.ts:5:import { myFunction } from ./utils; --- [0 lines truncated] ...示例grep_search(patternfunction\\smyFunction, pathsrc) grep_search(patternfunction, pathsrc, limit50) grep_search(patternfunction, glob*.js, limit10)确认否。7.editEdit精准文本替换与多阶段自校正edit替换文件中的文本。默认要求old_string唯一匹配一处有意修改所有出现位置时设置replace_all为true。该工具为精准、定向修改设计要求old_string附带足够上下文且空格与缩进必须精确匹配。Tool nameeditDisplay nameEditFileedit.ts参数file_pathstring必填要修改文件的绝对路径old_stringstring必填要替换的确切字面文本。关键必须唯一标识目标位置应包含足够上下文、精确匹配空白与缩进若old_string为空则尝试用new_string在file_path创建新文件new_stringstring必填替换后的确切字面文本replace_allboolean可选是否替换所有出现位置默认false。行为细节不编辑原始 Jupyter notebook JSON.ipynb请用notebook_editold_string为空且文件不存在时创建新文件old_string非空时读取文件并尝试找到唯一出现位置除非replace_all为 true多阶段编辑校正Enhanced Reliability当初始old_string未找到或匹配多处时工具可调用 Qwen 模型迭代精化old_string必要时含new_string通过自校正识别模型真正想修改的片段使编辑在上下文略有偏差时依然稳健。失败条件尽管有校正机制file_path不是绝对路径或位于 root 目录之外old_string非空但文件不存在old_string为空但文件已存在校正后old_string仍未在文件中找到old_string匹配多处、replace_all为 false且自校正无法解析为唯一无歧义的匹配。输出成功Successfully modified file: /path/to/file.txt (1 replacements).或Created new file: /path/to/new_file.txt with provided content.失败带原因的错误信息如Failed to edit, 0 occurrences found...、Failed to edit because the text matches multiple locations...。确认是。写入前展示变更 diff 并请求批准。文件编码与平台特定行为编码检测与保留读取文件时Qwen Code 按多步策略检测编码UTF-8—— 首先尝试现代工具链大多输出 UTF-8chardet—— 对非 UTF-8 内容做统计检测系统编码—— 回退到操作系统代码页Windowschcp/ UnixLANG。write_file和edit都会保留既有文件的原始编码与 BOM例如文件以带 UTF-8 BOM 的 GBK 读取写回时保持同样方式。defaultFileEncoding配置项在 config.ts 中定义FileEncodingTypeutf-8-bom取值在 fileSystemService.ts 中声明并有对应的单元测试覆盖write-file.test.ts、edit.test.ts。新文件默认编码配置defaultFileEncoding设置只影响新建文件不作用于既有文件的编辑取值行为未设置UTF-8 无 BOM并自动做平台特定调整见下utf-8UTF-8 无 BOM不做自动调整utf-8-bom所有新文件带 UTF-8 BOM在.qwen/settings.json或~/.qwen/settings.json中配置{ general: { defaultFileEncoding: utf-8-bom } }Windows批处理文件强制 CRLF在 Windows 上.bat和.cmd文件自动使用 CRLF\r\n行尾。因为cmd.exe以 CRLF 作为行分隔符——仅 LF 的行尾会破坏多行if/else、goto标签和for循环。此行为与编码设置无关且仅作用于 Windows。WindowsPowerShell 脚本的 UTF-8 BOM在 Windows 且系统代码页非 UTF-8如 GBK/cp936、Big5/cp950、Shift_JIS/cp932时新建的.ps1文件自动写入 UTF-8 BOM。原因是 Windows 10/11 内置的 Windows PowerShell 5.1 会按系统 ANSI 代码页读取无 BOM 脚本缺少 BOM 会导致非 ASCII 字符被错误解析。自动 BOM 仅在以下条件同时满足时生效平台是 Windows系统代码页非 UTF-8不是 65001文件是新建的.ps1既有文件保留原编码用户没有显式在设置中配置defaultFileEncoding。PowerShell 7pwsh默认使用 UTF-8 并能透明处理 BOM因此该 BOM 在 pwsh 下无害。若显式将defaultFileEncoding设为utf-8自动 BOM 会被禁用——这是为拒绝 BOM 的仓库或工具链提供的刻意逃生通道。平台行为汇总文件类型平台自动行为.bat、.cmdWindowsCRLF 行尾.ps1Windows非 UTF-8 代码页新文件带 UTF-8 BOM其他全部所有平台UTF-8 无 BOM默认总结工具矩阵与使用建议工具文件名用途默认需确认备注list_directoryls.ts列目录工作区内否opt-in默认关闭read_fileread-file.ts读文件/媒体/PDF否PDF 支持页范围与视觉桥回退notebook_editnotebook-edit.ts编辑 .ipynb 单元格是需先read_filewrite_filewrite-file.ts写/覆盖文件是保留编码与 BOMglobglob.ts按模式找文件否最多 100 个结果grep_searchgrep.ts正则搜内容否ripgrep 驱动editedit.ts精准文本替换是多阶段自校正这组文件系统工具构成了 Qwen Code 理解与操作本地项目上下文的基础读侧由read_file/glob/grep_search提供“看得懂”写侧由write_file/edit/notebook_edit提供“改得准”list_directory补充目录遍历能力而编码检测与平台差异处理则保证了跨 Windows / Unix 环境下读写行为的一致与安全。若需进一步了解工具如何被调度与权限管理可继续阅读 docs/developers/tools/introduction.md 及 docs/developers/tools/sandbox.md。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考