lockai

一个面向「板端开发」的 VS Code 插件，把 SSH/SFTP 远程设备文件管理、编辑器内远程文件编辑、保存即同步、板端运行脚本等能力整合进 VS Code，让本地—板端协作开发像在同一台机器上一样顺畅。

功能概览

• 板端文件树：在活动栏的 Lockai 视图中以树形浏览板端 SFTP 目录，支持展开/折叠、跳转路径、刷新。
• 编辑器内直接编辑远程文件：通过虚拟文件系统 lockai-sftp:// 把板端文件像本地文件一样在 VS Code 编辑器中打开、编辑、保存（保存即写回板端）。
• 完整的文件操作：上传/下载、新建文件/文件夹、重命名、删除、复制路径，支持多选。
• 拖拽上传：从 Windows 资源管理器 / macOS Finder 直接把文件或文件夹拖到「板端文件」视图即可上传。
• 集成 SSH 终端：在 VS Code 集成终端中打开板端交互式 Shell，键盘输入实时转发到远程。
• 保存即同步：本地保存文件时按配置的本地→板端路径映射自动上传，支持排除规则和静默模式。
• 在板端运行：针对 .py / .sh 文件，在编辑器运行按钮下拉中提供「在板端运行」入口，自动上传并复用同一终端执行。

项目结构

j:\my\lockai
├── src/
│   ├── extension.ts                     # 插件入口：命令注册、事件监听、自动同步逻辑
│   └── ssh/
│       ├── sshManager.ts                # SSH/SFTP 连接管理器（单例），状态/配置/路径工具
│       ├── sftpExplorerProvider.ts      # 板端文件树视图（TreeDataProvider）
│       ├── sftpFileSystemProvider.ts    # lockai-sftp:// 虚拟文件系统，支持编辑器内编辑
│       ├── sftpTreeDragAndDropController.ts  # 外部文件拖拽上传控制器
│       └── sshTerminalProvider.ts       # VS Code 终端 ↔ ssh2 Shell/exec 桥接（Pseudoterminal）
├── package.json                         # 命令、菜单、配置项、视图声明
├── tsconfig.json
└── README.md

核心模块说明

SshManager（src/ssh/sshManager.ts）

• 单例模式管理 SSH Client 与 SFTPWrapper。
• 维护连接状态 disconnected | connecting | connected | error，通过 onDidChangeStatus 与 onDidChangeSftp 事件向外通知。
• 读取 lockai.ssh.* 配置（host/port/username/password/remotePath/keepaliveInterval/readyTimeout）。
• 提供远程路径工具函数：normalizeRemotePath / joinRemotePath / parentRemotePath / basenameRemote。

SftpExplorerProvider（src/ssh/sftpExplorerProvider.ts）

• 实现 TreeDataProvider<SftpNode>，驱动 lockai.sftpExplorer 视图。
• SftpNode 带 contextValue（root / folder / file / disconnected），用于在 package.json 的 view/item/context 中按节点类型条件显示菜单。
• 断开连接时返回 disconnected 占位节点，避免 VS Code 因空数组显示 viewsWelcome 而阻塞右键菜单交互。
• 实现刷新、跳转路径、打开远程文件、上传/下载/删除/重命名/新建等操作，并支持外部 Webview 媒体预览。

SftpFileSystemProvider（src/ssh/sftpFileSystemProvider.ts）

• 注册 lockai-sftp:// 虚拟文件系统，URI 形如 lockai-sftp:///home/user/file.txt。
• 实现 FileSystemProvider 的 stat / readDirectory / readFile / writeFile / rename / delete / createDirectory 等方法，把对远程文件的操作全部代理到 SFTP。
• 使远程文件能像本地文件一样在编辑器中打开、编辑、保存，保存时自动写回板端并触发树视图刷新。

SftpTreeDragAndDropController（src/ssh/sftpTreeDragAndDropController.ts）

• 接收 files MIME 类型（即外部文件资源管理器拖入）。
• 拖到文件夹 → 上传到该文件夹；拖到文件 → 上传到其所在目录；拖到空白 → 上传到当前目录。
• 未连接时弹出连接提示，桌面端优先使用 uri，web 端把字节写入临时文件后再上传。

SshTerminalProvider（src/ssh/sshTerminalProvider.ts）

• 实现 Pseudoterminal，把 VS Code 集成终端桥接到 ssh2 通道。
• 默认走交互式 Shell 模式（设备终端），可缓存初始命令在 Shell 就绪后送入。
• 提供 sendText / isAlive 等接口，支持「在板端运行」复用同一终端。
• 终端尺寸（cols/rows）随 VS Code 终端 resize 同步到远程 PTY。

extension.ts（src/extension.ts）

• activate 中注册全部命令、视图、文件系统、状态栏、保存事件监听。
• 自动同步核心逻辑：autoSyncFile 在 onDidSaveTextDocument 触发，按 lockai.autoSync.mappings 解析本地→板端路径，匹配排除规则后用 sftp.fastPut 上传，并刷新树视图。
• 「在板端运行」：解析目标 URI（板端文件直接用，本地文件通过映射或回退到 /tmp/<文件名>），必要时先 ensureRemoteDir + 上传，再复用 boardRunTerminalRef 终端发送命令。

命令清单

配置项

lockai.ssh.*（连接参数）

lockai.autoSync.*（保存即同步）

lockai.run.*（在板端运行）

快捷键

使用流程

1. 在 VS Code 设置中填写 lockai.ssh.host / port / username / password，或执行 Lockai SSH: 配置连接参数 命令交互式填写。
2. 点击活动栏 Lockai 图标，在「板端文件」视图中点连接按钮（或执行 Lockai SSH: 连接板端）。
3. 连接成功后即可在树中浏览、右键操作远程文件，或双击在编辑器中直接编辑保存。
4. （可选）在 lockai.autoSync.mappings 中配置本地→板端路径映射，开启保存即同步。
5. （可选）打开 .py / .sh 文件，点编辑器右上角运行按钮下拉中的「在板端运行」，自动上传并执行。

环境与依赖

• VS Code 最低版本：^1.100.0（@types/vscode 锁定 1.100.0）
• 运行时依赖：ssh2 ^1.17.0
• 开发依赖：TypeScript ^6.0.3、ESLint ^10.5.0、@vscode/test-cli / @vscode/test-electron

编译与调试

npm install         # 安装依赖
npm run compile     # tsc -p ./ 编译到 out/
npm run watch       # 增量编译，便于调试
npm run lint        # eslint src
npm test            # vscode-test 运行单测

按 F5 在「扩展开发宿主」中调试本插件（见 .vscode/launch.json）。