UDF VSCode 插件 — 插件协议与实现说明
概述
- 名称: UDF
- 描述: 一组增强编辑器体验的工具集合（书签、关键词管理、DBF 编辑、SQL 辅助、自动化检查等）。
- 版本: 由
package.json 管理（当前版本示例: 0.0.4）。
目标读者: 插件维护者、二次开发者、希望集成或扩展此插件的团队。
目录结构（高层）
extension.js: 插件主入口，负责激活、注册命令、视图与事件绑定。bookmark.js, keyword.js, utils.js: 与书签/关键词/工具相关的独立脚本（根目录下）。module/: 按功能划分的模块目录（如 autoqc/, bookmark/, keyword/, sqldebugger/ 等），每个模块封装具体功能与 API。
插件协议（实现约定）
（以下为本仓库采用的约定，扩展模块时请遵守）
入口与激活: 插件的激活由 extension.js 控制，package.json 的 activationEvents 决定什么时候激活（例如 onLanguage:javascript、onStartupFinished 等）。所有模块应假设在被激活后由 extension.js 调用初始化入口。
模块约定: 每个功能模块放在 module/<name>/ 下，应导出一个或多个用于初始化/注册的函数，例如 activate(context) 或明确的初始化 API。extension.js 负责调用这些初始化函数并将 context（ExtensionContext）传入。
命令注册: 所有对外命令需在 package.json 的 contributes.commands 中声明（包含 command 与 title），并在 extension.js 中通过 vscode.commands.registerCommand 实际绑定实现。新增命令步骤：
- 在
package.json 增加命令条目；
- 在相应模块中实现命令处理函数（建议导出）；
- 在
extension.js 中 import 并 registerCommand。
视图（TreeView）与上下文菜单: 插件在 contributes.views / viewsContainers 中声明自定义视图（例如 bookmarkThemeView, keywordTreeView）。对应的 Tree 数据提供者（TreeDataProvider）应由模块实现并在 extension.js 中注册。上下文菜单项在 contributes.menus 中声明，使用 when 条件控制显示。
配置项: 插件在 package.json 的 contributes.configuration 中声明所有可配置项。实现中通过 vscode.workspace.getConfiguration('UDF') 读取。
数据与缓存: 模块内若需本地缓存（如 module/*/cache/*.json），请统一使用相对路径或 ExtensionContext.globalStoragePath 进行持久化，避免硬编码绝对路径。
网络/API 调用: 插件使用 axios 与后端交互（例如 module/autoqc/apis/*），所有对外请求应支持超时与错误处理，并不直接在激活阶段阻塞主线程。
数据库与敏感信息: package.json 中含有 SQL 连接配置项（示例: UDF.SQL.*）。不要在仓库中明文提交真实凭据；对需要加密/掩码的配置应在文档中说明风险并建议使用系统密码管理或 VSCode SecretStorage。
模块清单与职责（示例）
- autoqc/: 与自动化 QC、DevOps 集成相关的检查、登录、包版本管理等逻辑。
- bookmark/: 书签主题与书签管理（TreeView、装饰器、跳转功能）。
- keyword/: 关键词管理、关键字树、搜索与高亮。
- cmdhandler/: 命令分发、项目打开等工具函数。
- cpp/, delphi/: 与语言相关的构建/调试/跟踪工具集成。
- dbfeditor/: DBF 文件编辑、对比与保存。
- sqldebugger/: 与 SQL 调试、事务监控相关的工具。
（具体实现请查看对应目录下的 index.js / *.js 文件以获取函数签名与导出）
APIs 与数据流
- 内部 API: 模块之间通过导出函数进行交互，不推荐使用全局可变状态；若确实需要共享状态，请把它封装在
context.globalState 或 context.workspaceState。
- 事件与消息: 若需要模块间发布/订阅事件，可使用
vscode.EventEmitter 或在 extension.js 中建立一个轻量的事件总线（export 出 emitter）。
Contributes（配置 / 命令 / 菜单）快速参考
- 命令: 在
package.json.contributes.commands 中声明。
- 快捷键: 在
package.json.contributes.keybindings 中声明（示例中包含 ctrl+q, ctrl+oem_3, ctrl+enter）。
- 视图: 在
contributes.viewsContainers 与 contributes.views 中声明并在 extension.js 中注册 TreeDataProvider。
配置项（重点示例）
- 关键路径:
UDF.keyword.configPath, UDF.bookmarkTheme.configPath — 指向本地 JSON 文件用于初始化数据。
- SQL 配置:
UDF.SQL.server_name, UDF.SQL.database, UDF.SQL.user, UDF.SQL.password — 用于连接 MSSQL（插件依赖 mssql）。
- AUTOQC 配置:
UDF.AUTOQC.* 系列为自动化 QC 接口与路径设置。
命令与快捷使用
- 常用命令:
UDF.execJump（跳转）、keywordTreeView.addFromSelection（将选中文本添加为关键词）、bookmarkThemeView.addBookmarkHere（在行号上下文添加书签）等。
- 建议操作: 使用命令面板（Ctrl+Shift+P）输入命令名或在侧边栏的 UDF 视图中使用视图操作按钮。
开发与调试
npm run dev
npm run build
# 或
npm run publish
- 安装依赖: 使用
npm install（项目已在 package.json 中声明了依赖）。
- 调试断点: 在
extension.js 中设置断点，使用 VSCode 的「运行扩展」调试配置。
如何新增功能/命令（示例流程）
- 在
package.json 的 contributes.commands 添加命令声明。
- 在对应模块中实现命令处理函数并导出。
- 在
extension.js 中引入模块并用 context.subscriptions.push(vscode.commands.registerCommand(...)) 注册。
- 如需视图或 TreeDataProvider，在
package.json 中声明视图并在 extension.js 注册 provider。
打包与发布注意事项
- 版本号: 更新
package.json.version 或使用 updateVersion.js 自动化脚本。
- 私有/发布: 当前
package.json 中 private: true（示例），发布到 Marketplace 前请确认并设置正确的 publisher、repository 与 license。
- vsce: 项目使用
vsce 进行打包（见 devDependencies）。
贡献指南
- 代码风格: 保持现有风格（CommonJS 模块、简洁函数）。
- Pull Request: 提供变更说明、涉及的命令/配置变更、测试步骤。
- 敏感信息: 不要提交明文密码或凭据到仓库，使用占位符或 CI Secret。
常见问题（FAQ）
- Q: 如何改变关键词配置路径？
- A: 修改设置
UDF.keyword.configPath 指向新的 JSON 文件路径并重启 VSCode 或重新加载窗口。
- Q: 插件如何在 C++ 文件中高亮 SQL？
- A: 开启
UDF.SQL.HighlightInCpp，插件会在 C++ 解析中尝试增强 SQL 关键字显示。
参考
package.json（插件清单、命令与配置）- 查看模块实现目录以获取更细粒度的 API 说明：
module/*
如果你希望我把 README 扩展为英文版、添加 API 列表（函数签名）或为每个模块生成单独文档，我可以继续生成对应文档文件。
| |
