前言¶

在 DSH 里改原生微信小程序时，常见做法是打开微信开发者工具，或在浏览器里单独起一个预览服务。工具链和对话界面往往分开：模型很难在同一侧栏里直接看到页面、切换路由或对照 WXML。若还要把 DOM 点选映射回源码，通常得再叠一层自定义调试脚本。

dsh-wx-preview（维护者 zhxnix，社区目录分类为联网工具）是一个可移植的 DSH 插件：读取你指定的项目目录，在本机启动浏览器兼容的预览运行时，并把预览页放进 DSH 右侧栏。它不绑定固定业务仓库、端口或用户目录；目标项目源码只读，缓存写入独立的 DSH_WX_PREVIEW_HOME（默认 ~/.dsh-wx-preview）。

这是什么¶

一句话：dsh-wx-preview 用于发现、预编译、打开和调试原生微信小程序项目。它解析 project.config.json 与 app.json，预编译页面、分包、组件及 WXML/WXSS/JS/JSON，并在 DSH 中提供可交互的本地预览与一组 DSH 工具。

预览身份、storage、登录状态以及 wx.getSetting / wx.authorize 的结果均为本地 Fixture；插件不会调用真实微信登录、读取微信账号、写入 CloudBase 或修改项目源码。当前 npm 包版本为 0.1.1（见仓库 package.json），许可证为 MIT。

核心功能¶

下面介绍插件在资料中明确列出的能力。

项目识别与预编译¶

• 识别任意原生小程序项目，以及 project.config.json 里 miniprogramRoot 指向的源码目录。
• 预编译页面、分包、组件、WXML/WXSS/JS/JSON 和常用 wx.* API。
• 明确拒绝 UniApp、Taro 等非原生项目。

DSH 右栏预览¶

• 在 DSH 右栏启动可交互本地预览，支持页面切换、返回、刷新和热更新。
• 没有注释插件时，仍可使用独立 iframe 基础预览，并可手工输入 HTTP(S) 预览地址。

DSH 工具¶

插件向 DSH 注册以下工具（模型在会话中可通过自然语言触发，例如「发现 / 打开某路径」）：

• wxpreview_discover
• wxpreview_precompile
• wxpreview_open
• wxpreview_status
• wxpreview_logs
• wxpreview_update_identity
• wxpreview_stop

wxpreview_open 返回的 url / openInDshSidebar 为本机回环地址；预览按调用该工具的 DSH 会话保存面板映射，右栏请求 /dsh-wx-preview/config?sessionId=... 时只返回当前会话的预览，避免多会话串项目。

与注释插件协作¶

若已安装 dsh-sidebar-annotations，本插件会使用共享 BrowserPanel，面板类型为 dsh-wx-preview，网页点选注释、连续多条注释、上下文批注、控制台和 DevTools 可复用同一套体验。建议先加载注释插件，再加载本插件；本插件会监听共享面板的热更新事件，二者可独立升级。

预览 DOM 会标注源码位置，供注释插件映射回 WXML：

data-dsh-source-file="/absolute/path/to/pages/index/index.wxml"
data-dsh-source-line="12"
data-dsh-source-kind="wxml"

这是模板元素的实际起始行，不是对 JS 业务逻辑的推断。第三方注释/调试插件只需依赖上述三个属性，无需了解本插件内部编译结构。

命令行（脱离 DSH）¶

插件提供 CLI dsh-wx-preview，与 DSH 共用同一预览引擎，但不加载 DSH 工具或右栏 UI：

npm install
npx dsh-wx-preview discover ./my-mini-program
npx dsh-wx-preview precompile ./my-mini-program --force
npx dsh-wx-preview serve ./my-mini-program --route pages/index/index

serve 会启动本机服务并持续运行，按 Ctrl-C 停止。

安装与启用¶

市场收录申请中；当前可从 GitHub Release 安装预构建包。条目计划提交到 awesome-dsh-plugin。DSH 社区插件目录见 SkillHub 条目页（与 DeepSeek / 幻方无官方从属关系，属社区生态「一切皆插件」的独立站点）。

非 managed profile（DSH CLI）¶

将 web 换成你实际使用的非 managed profile：

dsh plugin --profile web add \
  https://github.com/zhxnix/dsh-wx-preview/releases/latest/download/dsh-wx-preview.tgz

安装后重启 DSH，并新建一个 session。

DSH Desktop（managed desktop profile）¶

Desktop 请使用仓库提供的 checkout 安装器（README 要求从 checkout 安装，而非仅 tgz）：

git clone https://github.com/zhxnix/dsh-wx-preview.git
cd dsh-wx-preview
npm install
node scripts/install.mjs --profile desktop

卸载：

node scripts/install.mjs --uninstall --profile desktop

若不使用安装器，可在 DSH profile 的 cordis.patch.yml 中手工加入（路径按实际 checkout 位置调整）：

- insert:
    - id: dsh-wx-preview
      name: './plugins/dsh-wx-preview/lib/index.js'

运行环境：package.json 要求 Node ^20.19.0 || >=22.12.0。

典型用法¶

在 DSH 会话中¶

在会话里直接说明项目路径，例如：

发现 /Users/me/projects/example-mini
打开 /Users/me/projects/example-mini

模型会调用工具，参数形态如下：

wxpreview_discover({ projectPath })
wxpreview_precompile({ projectPath, force? })
wxpreview_open({ projectPath, route?, port?, force? })
wxpreview_status({ projectPath?, sessionId? })
wxpreview_logs({ projectPath?, sessionId?, limit? })
wxpreview_update_identity({ projectPath, ...fixturePatch })
wxpreview_stop({ projectPath?, sessionId?, all? })

仓库最小示例¶

仓库 examples/native-mini-miniprogram 为不依赖业务项目的原生小程序夹具：

npx dsh-wx-preview discover examples/native-mini-miniprogram
npx dsh-wx-preview precompile examples/native-mini-miniprogram
npx dsh-wx-preview serve examples/native-mini-miniprogram

项目要求与能力边界¶

1. 项目根目录需包含 project.config.json 或 app.json；若存在 project.config.json，插件按 miniprogramRoot 定位源码，源码根必须有 app.json，且 app.json 至少声明一个 pages 页面。
2. 原生页面、组件和分包可使用 .js、.ts、.json、.wxml、.wxss、.wxs。
3. WXS、微信插件、Worker、地图、蓝牙、支付、Canvas、真实授权、CloudBase 和完整设备能力会在兼容性报告或运行时日志中提示；终验仍需要微信开发者工具或真机。

适用场景与注意¶

适合谁： 在 DSH 里做原生微信小程序相关开发或排查、希望模型能调用统一工具完成发现/预编译/打开预览，并在右栏（可选配合注释插件）对照 WXML 的开发者。

运行权限： 插件以当前 DSH 进程权限运行，会读取你传入的项目路径并在 DSH_WX_PREVIEW_HOME 写入缓存。安装前请自行查看 GitHub 源码 与 MIT 许可证（LICENSE）；通用预览引擎改编自本地 DSH 环境中的 wxpreview 包，来源说明见 NOTICE。

结尾¶

dsh-wx-preview 把原生小程序的发现、预编译和本地预览收进 DSH 工具与右栏，并在 DOM 上暴露 WXML 源码映射，便于与注释类插件联动。目录与详情：SkillHub；源码与 README：github.com/zhxnix/dsh-wx-preview。