Harmony

License: MIT Node.js

对 AI 说"帮我发个版本"，然后喝口水，完事了。

小程序开发者的 AI 副驾驶 —— 能理解你的项目、帮你一键发版、诊断编译错误的 MCP Server。

不需要云开发，不需要密钥，不需要白名单。装上就能用。

---

🚀 v0.4.0 重大更新：深度智能 + 协议升级

�️ 合规预检 — 发版前自动扫描隐私 API 调用（15 条规则），检查 permission 声明、__usePrivacyCheck__ 配置，推断所需类目，标注个人主体限制。再也不怕审核被拒。

🎯 MCP Prompts — 4 个快捷指令，输入 / 即可触发完整工作流：

• /harmony-check — 环境预检
• /harmony-audit — 代码质量审计
• /harmony-shrink — 包体积优化
• /harmony-publish — 合规预检 → 编译诊断 → 一键发版

✅ Elicitation 确认 — 发版前弹出确认框（项目名/版本号/描述），防止误操作。Client 不支持时自动降级。

📊 视觉报告 — 包体积报告含进度条（█████░░░ 1.7MB / 2MB），审计报告含仪表盘卡片 + 规则命中分布。

🔧 源码路径映射 — 编译报错路径自动映射回源码（Taro→.tsx / uni-app→.vue / mpx→.mpx）。

💡 suggestedPatch 预计算 — 常见错误直接给 AI 可执行的修复补丁，AI 不用再推理。

� 归因引擎极致化 — 组件树级联归因 + 分包预加载配置生成 + 分包后体积模拟。

🆕 新工具 — wechat_audit（代码质量审计）、wechat_init_project（新建项目）、wechat_compliance_check（合规预检）。

---

⚡ 快速开始

在你的 AI 工具（Kiro / Claude Desktop / Cursor 等）的 MCP 配置中添加：

{
  "mcpServers": {
    "harmony-mcp": {
      "command": "npx",
      "args": ["-y", "@yujiamei/harmony-mcp"]
    }
  }
}

前置条件

1. Node.js >= 18
2. 微信开发者工具已安装（下载）
3. 开发者工具「设置 → 安全 → 服务端口」已开启

💡 微信开发者工具安装在默认路径时会自动检测，无需额外配置。

---

✨ 能做什么

一键发版

你：帮我发个版本，描述是修复了购物车 bug
AI：📖 读取项目信息... ✅
    🔨 构建 npm... ✅
    🚀 上传代码 v1.2.4... ✅
    🎉 发版完成！去微信后台提交审核吧

一句话搞定原来 3-4 步的手动操作：版本递增 → npm 构建 → 上传代码。

包体积分析

你：包体积快超了，帮我看看
AI：📊 主包 1.8MB / 2MB（警告！）
    📁 images/ 占 42%（建议压缩）
    📁 vendor/ 占 28%（建议分包）
    💡 优化建议：1. 图片转 WebP  2. lodash 换 lodash-es  3. 大页面移入分包

编译诊断 → 自动修复

你：编译报错了帮我修
AI：❌ pages/cart/cart.js:42 - Cannot find module 'utils/pay'
    🔍 类型：模块缺失 | 指令：READ_FILE_AND_PATCH
    🔧 正在读取文件并修复...
    ✅ 重新编译通过！0 错误
    ⚠️ 检测到 2 个运行时隐患：
       - RT001: onPageScroll 中 setData 未节流（第 15 行）
       - RT004: 调用 wx.getLocation 但未声明权限

AI 自动读取报错文件、修复代码、重新编译验证，直到零报错。编译通过后还会扫描运行时隐患。

跨框架支持

你：分析一下 D:\projects\my-uniapp 的包体积
AI：🔍 检测到 uni-app 项目，已自动定位到编译产物: dist/build/mp-weixin
    📊 主包 1.6MB / 2MB
    ⚠️ 当前处于编译产物目录，改代码请去源码目录修改！
    🎯 体积归因：pages/detail 移到分包可省 430KB（含独占组件 video-player）

---

📋 全部工具（20 个）

工具	功能	说一句话就能触发
wechat_diagnose	编译诊断 + 自动修复 + 运行时隐患扫描	"编译报错了帮我修"
wechat_publish	一键发版 + Elicitation 确认	"帮我发个版本"
wechat_compliance_check	合规预检（隐私API + 权限 + 类目）	"发版前检查合规"
wechat_audit	代码质量审计（11规则 + A/B/C/D评分）	"帮我检查代码质量"
wechat_package_size	包体积分析 + 进度条报告	"包超了吗"
wechat_subpackage_suggest	智能分包 + 归因 + 预加载 + 体积模拟	"主包超了怎么办"
wechat_init_project	新建项目（blank/tabbar/subpackage）	"帮我新建一个小程序"
wechat_ready_check	全链路预检（CLI/登录/端口/项目）	"环境正常吗"
wechat_project_info	读取项目配置（支持 uni-app/Taro/mpx）	"帮我看看这个项目"
wechat_page_list	列出所有页面	"有哪些页面"
wechat_config_validate	配置文件校验	"配置有没有问题"
wechat_dependency_check	依赖健康检查	"依赖有问题吗"
wechat_preview	预览小程序	"预览一下"
wechat_upload	上传代码	"上传 1.2.0 版本"
wechat_build_npm	构建 npm	"构建一下 npm"
wechat_cli_login	登录开发者工具	"帮我登录"
wechat_open_project	打开项目	"打开项目"
wechat_close_project	关闭项目	"关闭项目"
wechat_reset_fileutils	重置文件监听	"重置文件缓存"
wechat_self_test	环境自检	"检查一下环境"

---

� 快捷指令（MCP Prompts）

在支持 MCP Prompts 的客户端（Cursor / Claude 等）中输入 / 即可看到：

指令	功能
/harmony-check	🚀 一键环境预检，就绪后推荐下一步
/harmony-audit	🛡️ 全量代码审计 + 视觉评分报告
/harmony-shrink	📦 包体积分析 → 超限自动给分包方案
/harmony-publish	🎉 合规预检 → 编译诊断 → 确认发版

---

�🆚 与其他方案的区别

	harmony-mcp	cloudbase-mcp	miniprogram-ci
需要云开发	❌	✅ 必须	❌
需要密钥/白名单	❌	✅	✅
AI 可直接调用	✅	✅	❌
能理解项目结构	✅	❌	❌
一键发版	✅	❌	❌
编译报错自动修复	✅	❌	❌
智能分包建议	✅	❌	❌
合规预检	✅	❌	❌
代码质量审计	✅	❌	❌
MCP Prompts	✅	❌	❌
零配置使用	✅	❌	❌

harmony-mcp 面向不用云开发的 70% 普通小程序开发者。赛道内唯一能做到 AI 编译闭环的产品。

---

❓ 常见问题

提示"找不到微信开发者工具"

确认开发者工具已安装。如果安装在非默认路径，在项目根目录创建 harmony-mcp.json：

{
  "cliPath": "D:\\你的路径\\cli.bat"
}

提示"需要重新登录"

微信开发者工具登录态过期了。对 AI 说"帮我登录"，扫码即可。

支持 Mac 吗？

支持。自动检测 macOS 常见安装路径（/Applications/wechatwebdevtools.app 等）。

支持 uni-app / Taro / mpx 吗？

支持。传入源码目录会自动识别框架类型并定位到编译产物（如 dist/build/mp-weixin）。如果产物不存在，会提示你先执行编译命令。

中文路径有问题吗？

没有。已在 D:\ZhuoMian\中文\ 这类中文路径下充分验证，CLI 调用全部用双引号包裹。

能力边界

• ✅ 编译层问题（语法错误、模块缺失、配置错误）— 全自动修复
• ✅ 运行时隐患（setData 性能、异步错误、权限缺失）— 静态扫描检测
• ⚠️ 运行时逻辑 bug（白屏、接口时序、业务逻辑）— 超出当前能力，需人工调试

---

⚖️ 免责声明

本项目非微信官方产品，与腾讯公司无任何关联。

harmony-mcp 通过调用微信开发者工具官方公开的 CLI 命令行接口实现功能，不涉及逆向工程、协议破解或非公开接口调用。使用本工具前，请确保你已阅读并同意《微信小程序平台服务条款》。

"微信"及"小程序"为腾讯公司的注册商标，本项目中的使用仅用于描述兼容性，不构成任何官方背书。

本软件按"原样"提供，不附带任何明示或暗示的担保。 作者不对因使用本软件导致的任何直接或间接损失承担责任，包括但不限于：代码上传错误、版本覆盖、项目数据丢失、微信账号异常等。使用者应自行承担使用风险，并在操作前做好备份。详见 LICENSE。

---

License

MIT © 朱