dsh-vba-bridge

让 DSH 会话里的 AI 直接读写 Excel VBA 工程：列模块、读源码、改代码、导出 .frm/.frx、列过程，并在保存后重新打开校验。核心走 Excel 自己的 COM/VBIDE，所以改完的宏由 Excel 编译、保存和验收，而不是硬拆 vbaProject.bin。

Windows · 桌面 Excel · DSH Host 插件 · MIT

GitHub: https://github.com/alexltr/dsh-vba-bridge

VBA Bridge 讲解图

工具

工具	作用
`vba_doctor`	安装后先跑：检查 Python、pywin32、Excel COM、`AccessVBOM`、离线解析器、临时目录，可选一个工作簿
`vba_inspect`	工程名、保护状态、全部组件（模块/工作表/ThisWorkbook/窗体）与引用
`vba_read_module`	读取单个模块源码，含 UserForm 代码区
`vba_write_module`	替换/追加/新建模块，原地保存，复开校验，生成 `.bak`
`vba_export_modules`	导出全部组件：源码（`.bas/.cls/.frm`）或原生 `.frm` + `.frx`，写 `_manifest.json`
`vba_list_procedures`	列出 `Sub`/`Function`/`Property` 的参数、起止行号，含窗体事件处理

相对路径按 DSH 会话工作目录 解析；绝对路径原样使用。

安装

发布到 npm 后：

dsh plugin add dsh-vba-bridge

当前开发目录（本地链接安装）：

plugin_manager action=install_bundle target=F:\MyProjects\dsh\vba_bridge

安装后先调用 vba_doctor，它会把“缺 Python / 缺 pywin32 / 没开 AccessVBOM / Excel 起不来”逐项列出来并给修复建议。

前置条件

Windows + 桌面版 Microsoft Excel（本机实测 16.0.20430.20182）。
Python 3.10+，并安装 pywin32： pip install pywin32。默认使用 PATH 里的 python，可用配置 pythonPath 或环境变量 DSH_VBA_PYTHON 指定。
Excel 信任中心开启 “信任对 VBA 工程对象模型的访问”： HKCU\Software\Microsoft\Office\16.0\Excel\Security\AccessVBOM = 1。这是允许本机程序读写 VBA 的全局开关，属于安全决策，不要在不可信的机器上随意打开。
目标文件是 .xlsm / .xlsb / .xls / .xlam；.xlsx 没有 VBA 容器，会被拒绝。

用法

直接用自然语言即可：

“看一下 D:\book.xlsm 里有哪些 VBA 模块”
“把 模块1 的源码读出来”
“把这段代码写进 模块1，先备份”
“把 MyVBALibrary.xlam 的全部模块导出到 F:\dump”
“列出 FRM_PictureViewer 里有哪些事件处理过程”

手动参数示例：

{"file": "D:\\book.xlsm"}
{"file": "D:\\book.xlsm", "module": "模块1"}
{"file": "D:\\book.xlsm", "module": "模块1", "code": "Sub Hello()\r\n    MsgBox \"hi\"\r\nEnd Sub\r\n", "mode": "replace"}
{"file": "D:\\book.xlsm", "outDir": "D:\\dump", "mode": "component", "overwrite": true}
{"file": "D:\\book.xlsm", "module": "FRM_PictureViewer"}

写入语义

mode=replace：重写模块代码区；隐藏的 VB_* 属性由 Excel 保留，文档模块可安全重写。
mode=append：读出旧代码 → 拼接 → 整体重写（不依赖 AddFromString 的插入位置）。
create=true：模块不存在时新建标准模块。
每次写入先复制 原名.YYYYmmdd-HHMMSS.bak.xlsm，保存后在同一 Excel 实例里重新打开并比对源码 SHA-256，返回 verified: true/false。

窗体（UserForm）

窗体的代码就是它的 CodeModule：UserForm_Activate、btnCancel_Click、 imgBigPicture_MouseUp 等事件处理都能读写，和普通模块一致。
只改代码区，不改控件布局、属性页或 .frx 设计数据。
mode=component 导出 .frm + .frx，.frm 头部保留 VERSION 5.00 / Begin ...， .frx 的 OleObjectBlob 完整，可用于备份/迁移。
mode=code 的 .frm 只有代码，不能直接重新导入。

导出

mode=code：UTF-8 源码，适合 grep、diff、喂给模型分析。
mode=component：调用 VBComponent.Export，窗体会多出 .frx。
输出目录写 _manifest.json（类型、行数、字节数、SHA-256、跳过/失败）。
overwrite 默认 false，已存在的文件跳过并报告。

配置

安装行 id 是 vba-bridge，默认配置在 cordis.patch.yml：

键	默认	说明
`pythonPath`	空 → `python`（其次 `DSH_VBA_PYTHON`）	带 `pywin32` 的 Python
`bridgePath`	空 → 包内 `bridge/vba_bridge.py`	自定义桥接脚本
`timeoutMs`	`240000`	单次工具调用超时
`allowWrite`	`true`	`false` 时 `vba_write_module` 直接拒绝
`maxOutputChars`	`200000`	工具输出截断上限

修改后重载插件（禁用/启用）或重启 Harness 生效；也可以在该 profile 的 patch 层按行 id vba-bridge 覆盖配置。当前版本尚未导出 Config schema，所以这些键通过 patch 配置而不是设置页表单修改。

安全边界

桥接期间 AutomationSecurity=3，读写源码不会顺带执行工作簿里的宏。
不提供“运行宏”工具；运行宏等于任意代码执行，需要时另行评估。
插件以宿主用户权限运行 Python，绕过 DSH 文件沙箱；只安装可信版本，只对可信工作簿使用。
写入默认生成 .bak 并复开校验；校验失败会返回 verified: false，不会静默成功。
密码保护的 VBA 工程无法编辑；任何改动都会使数字签名失效。
保存由 Excel 重写整个包，字节会变化（本机样本 39,195 → 37,537 字节）；生产使用请保留备份并做业务校验。

错误码

代码	含义	处理
`NOT_MACRO_ENABLED`	`.xlsx` 等无 VBA 容器	换 `.xlsm`/`.xlsb`/`.xls`
`FILE_NOT_FOUND`	路径不存在	检查路径/相对路径基准
`FILE_LOCKED`	被 Excel 占用或残留 `~$` 文件	关闭工作簿/清理锁文件
`VBA_TRUST_DISABLED`	未开 AccessVBOM	信任中心勾选
`PROJECT_PROTECTED`	VBA 工程有密码	在 VBE 中取消密码
`MODULE_NOT_FOUND`	模块名不匹配	按提示候选名重试
`EXCEL_UNAVAILABLE`	COM 无法启动 Excel	安装桌面 Excel、检查策略
`PYWIN32_MISSING`	当前 Python 无 pywin32	`pip install pywin32`
`OLETOOLS_MISSING`	离线解析器缺失	重装 bundle
`ENGINE_READONLY`	指定 `engine=ovba` 做写入/导出	改用 COM
`INVALID_OUTDIR`	`outDir` 指向文件	传目录路径

开发与测试

npm test          # Node 单元测试：工具注册、schema、相对路径、元数据
npm run test:py   # Python 单元测试：过程解析、文件名清洗

E2E 需要 Excel + AccessVBOM=1，见 docs/feasibility.md 与 test_local.mjs。桥接脚本可以直接跑：

python bridge\vba_bridge.py inspect fixtures\sample.xlsm
python bridge\vba_bridge.py read fixtures\sample.xlsm 模块1
python bridge\vba_bridge.py export fixtures\sample.xlsm work\export --mode component
python bridge\vba_bridge.py procedures fixtures\sample.xlsm 模块1

项目结构

vba_bridge/
├─ index.js                 # 六个工具与路径解析
├─ package.json             # bundle 清单与市场元数据
├─ cordis.patch.yml         # 插入 vba-bridge 行
├─ locale/{en,zh}.json      # 插件管理器显示名/描述
├─ icon.svg
├─ bridge/vba_bridge.py     # JSON 协议桥接：COM + 离线 OVBA
├─ vendor/                  # 精简 oletools 子集（离线只读）
├─ tests/                   # Node + Python 单元测试
├─ docs/feasibility.md      # 可行性论证
├─ docs/screenshot.png      # 讲解图
└─ CHANGELOG.md

限制

写入/导出依赖桌面 Excel；无 Excel 只能离线读，且离线模式的组件类型是近似值、行数包含隐藏的 Attribute 行。
窗体只支持代码，不支持设计器编辑。
当前不运行宏。
当前没有 Config schema / 设置页表单，也没有 allowedRoots 路径白名单；配置通过 profile patch 完成。
.xlsb / .xls 未单独实测（.xlsm / .xlam 已实测）。
单次调用通常 5–15 秒，取决于 Excel 启动、杀毒软件和是否复开校验。

License

MIT；第三方组件见 THIRD_PARTY_NOTICES.md。

dsh-vba-bridge

Install

Source

Tags

Creators

Readme

dsh-vba-bridge

工具

安装

前置条件

用法

写入语义

窗体（UserForm）

导出

配置

安全边界

错误码

开发与测试

项目结构

限制

License