前言你是不是遇到过这样的情况——让AI“读取项目根目录的配置文件”结果它翻来翻去就是找不到或者让AI“参考另一个仓库的代码来写东西”它却告诉你“没有权限访问那个目录”上篇我们学会了用插件给OpenCode加新功能但插件要真正干活离不开对文件系统的操作。文件系统是OpenCode的“手脚”——没有它AI再聪明也动不了你项目里的一行代码。建议先点个关注收藏这个专栏这篇我们来彻底搞懂OpenCode是怎么读写文件、管理目录、控制访问权限的。上篇回顾上篇我们掌握了插件开发的核心技能——用config钩子注册斜杠命令、用tool钩子让AI调用自定义函数、用event钩子订阅系统事件、用tool.execute.before拦截工具调用。但插件的能力再强最终都要落到“读写文件”这个基本动作上。这一篇就是解决“怎么让AI安全、高效地操作你项目里的文件”这个问题。环境与前置说明本篇依赖上篇的产出成果OpenCode已安装并可用熟悉插件开发的基本流程了解opencode.json配置文件的用法不需要安装任何新依赖。所有文件操作功能都是OpenCode内置的。文章目录前言上篇回顾环境与前置说明核心内容第一步理解工作区目录Working Directory的概念第二步用client.file读取文件第三步列出目录内容第四步理解文件操作权限体系第五步用external_directory访问工作区外的文件第六步用add-dir插件动态添加工作目录第七步文件变更的Diff与追踪异常处理与常见坑报错1AI读取文件时报“Permission denied”报错2AI修改文件时一直弹确认框报错3/add-dir命令不存在本章产出总结作者互动与资源引导下篇预告核心内容第一步理解工作区目录Working Directory的概念目标搞清楚OpenCode的“工作区”到底是什么以及它跟普通文件夹有什么区别。你可能会问工作区不就是我启动OpenCode的那个文件夹吗这有什么好理解的对但也不全对。OpenCode启动时所在的目录确实是它的“工作区根目录”。但工作区这个概念比单纯一个文件夹要复杂——它包含三个维度维度说明directory你启动OpenCode时所在的目录当前工作目录worktreeGit工作树的根目录如果有Git仓库的话project项目的逻辑分组可以包含多个目录这三个维度共同定义了一个“工作单元”。OpenCode的会话是绑定到特定目录的每个项目维护自己的会话列表。注意了如果你在项目的子目录启动OpenCodedirectory是那个子目录而worktree是Git仓库的根目录。这意味着AI默认只能访问directory下面的文件但可以感知整个worktree的结构。在插件中你可以通过ctx.directory和ctx.worktree获取这两个值importtype{Plugin}fromopencode-ai/pluginexportconstWorkspacePlugin:Pluginasync(ctx){// 打印当前工作目录和Git工作树根目录console.log( 当前工作目录:,ctx.directory)console.log( Git工作树根目录:,ctx.worktree)return{}}运行验证在任意Git项目中创建这个插件在.opencode/plugins/目录下保存为workspace.ts重启OpenCode。观察终端输出——ctx.directory应该是你启动OpenCode的目录ctx.worktree应该是Git仓库的根目录。第二步用client.file读取文件目标学会在插件中通过SDK Client读取项目文件。上篇我们简单提过SDK Client但没深入讲文件操作。client.file是操作文件系统的核心入口。在.opencode/plugins/file-reader.ts中写入importtype{Plugin}fromopencode-ai/pluginexportconstFileReaderPlugin:Pluginasync(ctx){const{client,directory}ctxreturn{// 注册一个工具让AI能调用它来读取文件统计信息tool:{file_stats:tool({description:获取指定文件的统计信息行数、大小、修改时间,args:{// 文件路径参数相对于项目根目录filePath:tool.schema.string().describe(要统计的文件路径相对于项目根目录)},asyncexecute(args){// 使用client.file.read读取文件内容// 注意read返回的是文件内容不是文件元数据constresultawaitclient.file.read({path:{file:args.filePath}})// 从ctx中获取工作目录构造完整路径来获取文件信息constfullPath${directory}/${args.filePath}constfileInfoawaitBun.file(fullPath).stat()// 统计行数按换行符分割constlinesresult.data.split(\n).lengthreturn{fileName:args.filePath,lineCount:lines,fileSize:fileInfo.size,modifiedAt:fileInfo.mtime}}})}}}逐行解释一下client.file.read读取文件内容path.file指定文件路径Bun.file(fullPath).stat()获取文件的元数据大小、修改时间等工具的参数用tool.schema.string()定义底层是Zod schema运行验证保存插件重启OpenCode。在TUI中让AI“统计package.json的文件信息”AI应该会调用file_stats工具返回行数、大小和修改时间。第三步列出目录内容目标学会用client.file.list列出目录下的所有文件和子目录。client.file.list可以列出指定目录的内容// 在插件中列出目录内容constfilesawaitctx.client.file.list({query:{path:ctx.directory}// path指定要列出的目录})// files.data是一个数组每个元素包含文件/目录信息for(constfoffiles.data){console.log(f.name,f.isDirectory?:)}你可以把目录列表能力封装成一个工具让AI随时查看项目结构importtype{Plugin}fromopencode-ai/pluginexportconstDirListPlugin:Pluginasync(ctx){const{client,directory}ctxreturn{tool:{list_project:tool({description:列出项目根目录下的所有文件和文件夹,args:{},asyncexecute(){constresultawaitclient.file.list({query:{path:directory}})// 格式化成易读的列表constitemsresult.data.map(f{consticonf.isDirectory?:return${icon}${f.name}}).join(\n)return项目目录内容\n${items}}})}}}运行验证加载插件后在TUI中让AI“列出项目根目录的内容”AI会调用list_project工具返回目录列表。第四步理解文件操作权限体系目标搞清楚OpenCode的权限模型知道怎么控制AI能读哪些文件、能改哪些文件。OpenCode有一套精细的权限体系每个工具read、edit、write、glob、grep等都可以单独配置权限。权限的默认规则是这样的工具默认行为read允许AI可以读取工作区内的任何文件edit/write/patch需要确认AI每次修改文件都需要你批准glob/grep允许AI可以搜索文件bash需要确认AI执行命令需要你批准注意了read默认是允许的这意味着AI可以看到你项目里的所有代码。如果你有敏感文件比如.env、secrets.json需要用配置文件明确禁止读取。在opencode.json中配置权限{$schema:https://opencode.ai/config.json,permission:{// 禁止读取.env文件read:{**/.env:deny,**/.env.*:deny},// 禁止修改配置文件edit:{opencode.json:deny,.opencode/**:deny},// bash命令需要每次都确认bash:ask}}权限配置支持模式匹配glob pattern。**表示任意层级的子目录*表示任意文件名。运行验证在opencode.json中添加禁止读取.env的规则然后重启OpenCode。在TUI中让AI“读取.env文件的内容”——AI应该会收到权限错误无法读取。第五步用external_directory访问工作区外的文件目标学会配置OpenCode让它能读取和修改工作区目录之外的文件。默认情况下OpenCode只能访问当前工作区目录内的文件。如果你想让AI读取另一个项目的代码或者访问~/Documents里的文档就需要配置external_directory。在opencode.json中添加{$schema:https://opencode.ai/config.json,permission:{// 允许访问 ~/projects/ 下的所有子目录external_directory:{~/projects/**:allow}}}这个配置的意思是允许工具访问~/projects/目录下的所有文件。一旦某个目录被加入external_directory它就会继承工作区的默认权限规则。如果你想允许读取但禁止修改某个外部目录{$schema:https://opencode.ai/config.json,permission:{external_directory:{~/projects/legacy/**:allow},// 在外部目录中禁止编辑但允许读取edit:{~/projects/legacy/**:deny}}}这样AI可以读取~/projects/legacy/里的代码作为参考但不会误修改它们。运行验证配置external_directory指向另一个项目目录重启OpenCode。在TUI中让AI“读取~/projects/另一个项目/package.json的内容”——AI应该能成功读取。第六步用add-dir插件动态添加工作目录目标学会在运行时动态添加额外的工作目录无需修改配置文件。前面我们说了配置external_directory需要改opencode.json然后重启。但有时候你只是想临时让AI看一眼别的目录——每次都改配置太麻烦了。社区有一个opencode-add-dir插件可以解决这个问题# 安装add-dir插件opencode plugin opencode-add-dir-gf安装后在TUI中可以这样用/add-dir ~/projects/another-project这个命令会动态地把~/projects/another-project加入当前会话的允许目录列表AI立刻就能访问那个目录的文件。这里有个坑/add-dir添加的目录只在当前会话中有效。关闭会话后需要重新添加。运行验证安装插件后在TUI中输入/add-dir ~/Downloads然后让AI“列出~/Downloads目录下的文件”——AI应该能成功列出。第七步文件变更的Diff与追踪目标学会查看AI对文件做了哪些修改以及怎么追踪文件的变更历史。OpenCode会追踪所有文件操作你可以通过client.session.diff查看当前会话的文件变更// 在插件中获取当前会话的文件变更constdiffawaitctx.client.session.diff({path:{id:sessionId}})// diff包含了所有被修改、新增、删除的文件for(constchangeofdiff.data.changes){console.log(${change.path}:${change.type})// change.type 可能是 add、modify、delete}在TUI中你也可以用/diff命令快速查看当前会话的所有文件变更。这个命令会显示一个清晰的列表告诉你AI改了哪些文件、新增了哪些文件、删除了哪些文件。运行验证让AI修改一个文件比如在某个文件里加一行注释然后在TUI中输入/diff——你应该能看到那个文件出现在变更列表中并且能看到具体的改动内容。异常处理与常见坑报错1AI读取文件时报“Permission denied”Error: Permission denied: /path/to/file原因AI尝试读取工作区外的文件但external_directory没有配置允许该路径。解决方案在opencode.json中添加external_directory配置{permission:{external_directory:{/path/to/target/**:allow}}}或者安装opencode-add-dir插件在TUI中用/add-dir动态添加完全退出并重启OpenCode修改配置文件后必须重启报错2AI修改文件时一直弹确认框每次AI要修改文件都弹出Allow tool edit?的确认提示原因edit工具的默认行为是ask需要用户确认。解决方案如果信任AI的修改可以在opencode.json中把edit改为allow{permission:{edit:allow}}但强烈不推荐这样做——让AI自动修改文件而不经确认风险太高更好的做法在Build模式下工作每次修改前AI会展示变更内容你确认后再执行报错3/add-dir命令不存在输入/add-dir后显示command not found原因opencode-add-dir插件没有安装。解决方案安装插件opencode plugin opencode-add-dir-gf确认插件已加载opencode plugin list如果列表中没有opencode-add-dir检查opencode.json中是否包含{plugins:[opencode-add-dir]}完全退出并重启OpenCode本章产出总结完成本篇后你获得了以下能力/产出序号产出物/能力说明1理解工作区概念知道directory、worktree、project的区别2文件读取能用client.file.read读取任何项目文件3目录列表能用client.file.list列出目录内容4权限配置能用opencode.json精细控制AI的文件访问权限5跨目录访问能用external_directory让AI访问工作区外的文件6动态添加目录能用/add-dir在运行时临时添加工作目录7文件变更追踪能用/diff查看AI对文件做的所有修改文件系统是OpenCode的“双手”——学会了操作它你就知道AI是怎么读写你的代码、怎么理解你的项目结构的。从此你不会再被“文件找不到”、“权限不够”这些问题困扰了。作者互动与资源引导你在使用过程中有没有遇到过文件权限方面的困惑或者你有什么好用的文件操作技巧想跟大家分享欢迎在评论区留言我看到就会回复。如果觉得这个专栏对你有帮助关注我后续每一篇更新你都不会错过关注后私信我发送暗号“爱学Python”我会把Python全栈学习路线图和本专栏的源码包发给你我们还有一个技术交流群群里的小伙伴们每天都在讨论OpenCode的各种用法。想进群的朋友在评论区扣个“1”我拉你进来。下篇预告下一篇是[[基础篇09] 实现OpenCode基础错误处理与重试逻辑]我们会深入OpenCode的错误处理机制——AI调用失败怎么办API超时怎么重试怎么让插件在面对错误时更健壮如果本篇对你有帮助点赞、收藏、关注走一波咱们下篇见