# 调试指南

# 一、使用开发者工具

下载安装微信开发者工具（Nightly Electron Build 最新版本)

在「编译模式」入口切换到「小程序 AI 编译」，调试基础库切到 3.16.1

如果进入项目窗口发现看不到 “小程序 AI 编译”，可尝试通过重新登录 / 重新打开项目窗口的方式重试。

若流程跑不通，尝试将调试基础库切到其他版本，再切回 3.16.1（触发重新下载资源）

在该编译模式下，支持：

对单个 SKILL 调试，可切换 SKILL
对单个原子接口调试，可切换原子接口，可手动填入参数
对单个原子组件调试，可手动填入参数，可调整组件宽度以适配最小/最大高度
完整的对话交互流程，可单步调试，直观地看到原子接口的入参与出参

开发者工具执行异常反馈：帮助 -> 上传工具日志，并提供微信号和复现的时间点

# 二、真机预览与调试

微信客户端支持真机预览体验，需要将微信更新至 8.0.74 及以上（目前仅 iOS 支持），并确保基础库版本是 3.16.1 及以上。

预览调试：扫描开发者工具预览的二维码，打开开发版小程序后，在右上角胶囊可以看到「小程序 AI 开发模式」入口，进去即可体验并测试流程，支持胶囊右上角菜单「打开调试」开启 vConsole 进行调试。

真机预览调试，非开发者工具上的「真机调试」远程调试功能，该功能暂不支持。

通过以下方法确认基础库版本号：

打开小程序右上角菜单 -> 打开调试 -> 展开 vConsole -> 切至 WeChat 页

问题反馈：在开发者社区「小程序 AI 能力」主页发贴反馈问题，为提升问题排查效率，需提供微信号、复现的时间点，并截个屏及上传客户端日志，日志上传入口：微信“我” -> 设置 -> 帮助与反馈 -> 右上角小扳手-> 上传日志 -> 上传最近一小时日志（或在复现时间点附近最小时间范围的日志）

# 三、开发辅助

# 3.1 生成辅助

为了帮助开发者接入，我们将提供一套自动生成与循环验证的系统，核心思路是：基于小程序源码，利用 LLM 自动生成原子接口和原子组件，并通过运行环境验证形成闭环，不断迭代直至达到质量标准。

建议一次只生成一小部分业务逻辑对应的原子服务，校验没问题后，再生成其他部分的逻辑。

# 3.1.1 安装「生成 Skills」（wxa-skills-generate）

可便捷的基于原有业务代码生成原子接口与原子组件, 可以自由地选择顺手的 Coding Agent（如 CodeBuddy、Claude Code）进行生成，只需要输入「帮我分析这个项目，接入微信小程序 AI 开发模式」就可以激活「生成 skills」进入生成流程，按照模型的提示，提供信息便可生成对应的原子接口与原子组件。

强烈建议生成后用下方「校验 Skills」进行校验，便于发现 Coding Agent 生成的代码的异常问题

# 3.1.2 安装「校验 Skills」 (wxa-skills-validate)

可基于开发者工具的渲染与执行能力，验证上轮命令中生成的代码，模型会依据真实的运行结果闭环迭代生成原子组件与原子接口（运行过程中开发者工具可能会有对应的授权弹窗，需手动进行授权，未授权可能会导致原子接口执行失败），任务完成后会输出 DELIVERY.md 阐述。

在使用「校验 Skills」前，必须在微信开发者工具上进行设置：手动打开工具 -> 设置 -> 安全设置，将服务端口开启。

# 3.2 评测辅助

在基础接入与生成辅助能力之外，开发者实际开发时常会遇到表现不符合预期的问题，且调试成本较高。为此，我们提供「评测 Skills」，帮助开发者自动生成评测报告与优化建议，降低排查难度，提升调优效率。

在使用「评测 Skills」前，必须在微信开发者工具上进行设置：手动打开工具 -> 设置 -> 安全设置，将服务端口开启。

# 安装「评测 Skills」（wxa-skills-eval）

填写用于评测的模型配置后，告知开发者工具路径以及小程序项目目录，可便捷的基于已生成完的原子接口、原子组件，模拟用户对话进行效果评测，自动分析存在的问题，提供优化建议。任务完成后会输出评测报告，eval_report.html 展示评测信息。

详细指引，可参考评测指南