前言¶
用 DSH 让 Agent 写微信小程序时，常见失败不是 wxml 写错，而是页面文件已经在磁盘上，却没有写进 app.json 的 pages。微信开发者工具只认注册过的路径，这类「孤儿页」在 IDE 里打不开，Agent 往往还要再跑一轮补救。
手工改 app.json 还有另一层麻烦：小程序工程允许 JSON 带注释，普通 JSON.parse / JSON.stringify 会抹掉注释和格式；分包、tabBar、miniprogramRoot 与项目根混用时，页面还容易登记到主包或落到错误目录。
下面介绍社区插件 dsh-miniprogram-helper（维护者 leo666-cloud，分类：客户端）。它在 DSH 里注册 11 个工具，把「建文件 + 注册 + 校验」做成可重复的原子操作，并可调用微信开发者工具 CLI 出预览二维码。
这是什么¶
dsh-miniprogram-helper 是一个 DSH（DeepSeek Harness）插件：让 Agent 能扫描、生成、注册、校验微信小程序页面与配置，并联动微信开发者工具 CLI。
- 目录页：https://www.skillhub.cn/plugins/leo666-cloud/dsh-miniprogram-helper
- 源码：https://github.com/leo666-cloud/dsh-miniprogram-helper
- 当前 package 版本：
0.2.0，许可证 MIT
DSH 生态主张「一切皆插件」；SkillHub 等社区目录由社区维护，与 DeepSeek / 幻方无官方从属关系。安装前请自行查看源码与许可证。插件在当前 dsh 进程权限下读写工程与调用 CLI，勿对不可信仓库直接 plugin add。
核心功能：11 个工具¶
| 工具 | 作用 |
|---|---|
mp_scan |
全面体检：页面清单、文件完整性、未注册的孤儿页、tabBar/分包/组件路径校验、包体积 |
mp_page_add |
新建页面（wxml/wxss/脚本/json）+ 自动写进 app.json + 写完立即自检 |
mp_page_remove |
注销页面（可连文件一起删），拦截删启动页 / tab 页 / 最后一个页 |
mp_entry_set |
改启动页，同步 entryPagePath |
mp_register |
只补注册已存在的页面，不建文件 |
mp_fix |
一键修复：把磁盘上有但未注册的页面补进 app.json |
mp_subpackage_add |
创建分包：校验 root、写 subPackages、搭首个页面（登记到分包，不是主包） |
mp_component_add |
创建自定义组件 + 自动注入目标页面的 usingComponents |
mp_tabbar |
用「页面:文字」列表配置底部 tab，自动补注册、校验图标与 2–5 条数量限制 |
mp_project_init |
生成可直接导入开发者工具的工程骨架（含 miniprogramRoot 结构） |
mp_devtools |
调微信开发者工具 CLI：detect / login / open / preview（出二维码 PNG）/ upload |
实现上值得单独记的几点（来自 README，影响 Agent 是否误改工程）：
- 项目根 vs 代码根：路径相对
project.config.json里miniprogramRoot指向的代码根解析；可传项目根或含app.json的代码根。 - 保格式改 JSON：内置 JSONC 解析与区间替换，改
pages等片段时尽量保留注释与缩进。 - 页面与组件区分：组件靠同名
.json的"component": true及可配置的componentDirs跳过，避免mp_fix把组件路径塞进pages。 - 分包页面登记位置：落在已声明分包 root 下的路径写入该分包
pages，不写进主包pages。 - 默认不覆盖：
mp_page_add/mp_component_add在目标文件已存在时默认跳过；覆盖需显式force/overwrite。 mp_devtools失败归因：区分权限、IDE 未初始化、未登录、服务端口未开、超时等，CLI 调用带超时（默认见配置项devtoolsTimeoutSec）。
安装与启用¶
前置环境¶
- Node.js
^22.19或>=24 - pnpm（
dsh plugin add内部会转发给 pnpm） - 本机已安装 DSH，终端可执行
dsh --help
若从源码构建插件（维护者流程）：
cd dsh-miniprogram-helper
pnpm install
pnpm run build
pnpm test
README 写明有 21 个端到端测试，在临时目录中真实执行工具链。
装进 profile¶
在插件仓库的父目录执行（相对路径锚定到当前工作目录）：
dsh plugin --profile web add ./dsh-miniprogram-helper
确认已进入配置树（不 boot，较快）：
dsh --profile web --dump-config | grep -A2 miniprogram
预期片段含 dsh-miniprogram-helper 与 id: miniprogram-helper。
然后重启 dsh web，并新开一个会话——客户端模块注册表在进程内缓存元数据，不重启不会加载新插件。
Desktop 版使用 desktop profile，由 App 独占管理；命令行 dsh --profile desktop 会被拒绝。桌面版请在 App 插件市场安装，或按 README 将插件链到 ~/.dsh/profiles/desktop/node_modules 并在 cordis.patch.yml 插入对应条目后重启 App。
可选配置¶
可在插件设置中配置默认工程路径等，减少每次让模型传路径：
| 配置 | 默认 | 说明 |
|---|---|---|
projectRoot |
空 | 默认项目路径，留空则每次由模型传入 |
useTypeScript |
false |
生成 .ts 而非 .js |
componentDirs |
components |
组件目录（逗号分隔多个），扫描时跳过 |
appId |
空 | mp_project_init 写入的 AppID，留空用 touristappid |
devtoolsCli |
空 | 开发者工具 CLI 路径，留空自动探测 |
devtoolsPort |
空 | IDE 服务端口；IDE 已用其它端口启动时需一致 |
devtoolsTimeoutSec |
90 |
CLI 超时秒数 |
previewDir |
空 | 预览二维码落盘目录，留空用系统临时目录 |
使用 mp_devtools 前需在微信开发者工具中打开「服务端口」，并完成登录；macOS CLI 常见路径为 /Applications/wechatwebdevtools.app/Contents/MacOS/cli，插件可自动探测。
典型用法¶
在 DSH 会话里用自然语言驱动即可，README 示例包括：
用 mp_scan 扫一下 ~/project/miniprogram，看看有什么问题
帮我加一个"我的订单"页面 pages/order/index，导航标题叫"我的订单"
把扫描出来的孤儿页面都注册进 app.json
加一个底部导航：首页 / 订单 / 我的
生成预览二维码，我扫码看看效果
维护者推荐的串联流程：
用 mp_scan 扫一遍项目，告诉我有什么问题
→ 帮我加一个订单页 pages/order/index
→ 加个底部导航：首页 / 订单 / 我的
→ 跑一次 mp_fix 确认没有漏注册的页面
→ 再 mp_scan 复核
→ 出预览二维码
适用场景与注意¶
适合谁：用 DSH Agent 迭代微信小程序、希望页面创建与 app.json 注册一致、并偶尔需要预览二维码的开发者。
注意：
- 传错目录会报找不到
app.json；若代码在miniprogram/子目录，应理解miniprogramRoot，或直接传代码根。 - 路径含空格时，
dsh plugin add转发绝对路径可能失败，README 建议将仓库放在无空格路径。 - 插件依赖
@deepseek-ai/dsh-tools的0.2.1-rc.2（README 提醒勿误装latest上的陈旧 dist-tag）。 - 仅当你信任源码与维护者时再安装；工具会读写你指定的工程目录并可能调用本机微信开发者工具。
结尾¶
dsh-miniprogram-helper 把小程序工程里「文件在、未注册」这类 Agent 高频失误，收敛到 mp_page_add、mp_fix、mp_scan 等可验证步骤，并兼顾 JSONC、miniprogramRoot 与分包登记等细节。需要进一步了解能力边界与报错速查，可直接阅读仓库 README。
- 插件目录：https://www.skillhub.cn/plugins/leo666-cloud/dsh-miniprogram-helper
- GitHub：https://github.com/leo666-cloud/dsh-miniprogram-helper
