VSCode 1.86+ 插件必须显式声明 capabilities 才能读写文件，未声明 "workspace" 等能力将静默失败；需按路径粒度获用户授权，WSL 下必须使用 vscode.workspace.fs 而非 Node.js fs。
插件无法读写文件？检查 package.json 的 capabilities 声明
VSCode 1.86+ 强制要求插件显式声明能力，否则即使调用 vscode.workspace.fs.readFile() 也会静默失败或抛出 OperationNotSupportedError。不声明 "workspace" | "globalState" | "userData" | "env" 等 capability，插件连自己安装目录都进不去。
常见错误现象：插件在调试时能读取本地测试文件，但发布后对用户工作区文件调用 readFile() 返回空或报错；vscode.env.appRoot 可读，但 vscode.Uri.file('C:\some\path') 拒绝访问。
-
package.json中必须包含"capabilities"字段，且至少声明所需最小集，例如："capabilities": { "virtualWorkspaces": false, "untrustedWorkspaces": { "supported": true }, "workspace": { "cat": true, "read": true, "write": true } } - 若仅需读取当前打开的文件，声明
"workspace": { "read": true }即可；若要写入用户项目目录，"write": true不可省略 - 声明
"workspace": true是旧写法，已弃用；未声明"workspace"对象时，默认为{ "read": false, "write": false }
调用 vscode.workspace.fs 前，必须确认用户已授权访问路径
即使 capability 声明完整，VSCode 仍会在首次访问非工作区路径（如 C: emp、/home/user/downloads）时弹出权限提示。这个提示不是一次性的——它按路径粒度控制，C: emp oo 和 C: empar 被视为两个不同授权域。
使用场景：插件需要导入用户桌面配置、扫描下载目录日志、或导出报告到任意位置。
- 不要直接传入硬编码路径给
vscode.workspace.fs.readFile()，先用vscode.window.showOpenDialog()让用户选择，返回的Uri[]自动获得该路径授权 - 若必须构造路径（如拼接
os.homedir()），需先调用vscode.workspace.fs.stat()并捕获FilePermissionDeniedError，再引导用户手动授权 - Windows 上访问
C:Program Files或C:Windows类路径永远失败，插件无权绕过系统 ACL，别尝试
剪贴板、终端、调试接口等敏感能力需运行时二次确认
声明 "env" 或 "terminal" capability 后，调用 vscode.env.clipboard.readText() 或 vscode.window.createTerminal() 仍会触发一次性弹窗确认。这是强制策略，无法跳过或预授权。
容易踩的坑：在插件激活（activate()）时立即读剪贴板，用户还没看到界面就弹窗，体验极差；或在后台任务中反复调用，每次弹窗导致流程中断。
- 剪贴板操作务必放在用户显式触发的动作里（如点击命令、右键菜单），避免自动执行
- 创建终端前，先检查
vscode.terminal.activeTerminal是否存在，避免无意义弹窗 - 调试接口（
vscode.debug）需额外声明"debuggers"capability，且仅限已启用对应调试器扩展的环境生效
WSL 场景下跨系统路径权限失效？优先用 vscode.workspace.fs 替代 Node.js fs
在 WSL 连接模式下，插件若直接使用 Node.js 的 fs.promises.readFile() 读取 /mnt/c/Users/xxx/project/file.txt，大概率遇到 EACCES 或空内容——因为该调用走的是 WSL 内核路径解析，而 VSCode 主进程运行在 Windows 层，两者权限上下文隔离。
正确做法是统一通过 VSCode 提供的文件系统 API，它内部做了跨平台路径归一化和权限代理。
- 绝对不要在插件中
require('fs')操作/mnt/下的路径；所有文件 I/O 必须走vscode.workspace.fs.*() - 若需兼容纯 Node.js 工具逻辑（如调用外部 CLI），应将路径转为 Windows 格式（
C:\Users\xxx\project\file.txt）再传入，并确保该路径已在 capability 中声明可访问 - WSL 中修改
/etc/wsl.conf启用metadata选项，仅影响 Linux 层 chmod 行为，对 VSCode 插件无直接作用
