Weapp Agent

让 AI 写完的小程序代码，更容易被验证和交付。

文档 · English · 贡献指南

面向 weapp-vite 原生与 Wevu 微信项目的交付能力层。通过 MCP 和 CLI 为 Codex 等宿主提供工程诊断、确定性验收与截图日志，不需要第二个模型或 API Key。保留独立 AI CLI 模式。

当前状态

源码预览版。仓库提供可运行实现和可打包 CLI。实际验收记录见 VALIDATION.md，模拟测试与真实模型、DevTools 验证分别记录。

安装预览包

从 npm 安装预览版：

npm install --global @weapp-agent/cli@preview
weapp-agent --version

从源码开始

需要 Node.js 24.15+、pnpm。

corepack enable
pnpm install
pnpm build
node apps/cli/dist/index.mjs --help
pnpm --filter @weapp-agent/cli pack --pack-destination ../../artifacts

将生成的 .tgz 安装到全局，或直接通过 node 调用构建入口。

使用已有 AI 宿主时，先阅读无模型接入指南。以下命令用于独立 agent 模式：

weapp-agent init --provider openai --model YOUR_MODEL
# 在终端环境中设置 OPENAI_API_KEY
weapp-agent doctor
weapp-agent --trust run "为首页增加一个计数器，执行构建与测试"
weapp-agent

新建项目：

weapp-agent init my-miniapp --create --template wevu --model YOUR_MODEL
cd my-miniapp
pnpm install
weapp-agent --trust

在现有 AI 工具中验收

以下新入口需要包含本次改动的构建包，尚未发布到 npm：

weapp-agent init
weapp-agent doctor --json
# 审阅项目脚本、配置与场景后
weapp-agent --trust accept --json
weapp-agent -C /absolute/path/to/project mcp
weapp-agent skill .agents/skills/weapp-acceptance

在配置的 acceptance.scenarios 中列出场景 JSON 文件。默认要求 build 和 devtools 都通过；缺少场景返回未验证。MCP 提供 inspect/start/status/cancel/report 五类操作，宿主负责代码修改和修复。新报告为 version 2，绑定源码摘要，支持取消和中断识别，报告不会自动重放交互。旧 verify 输出继续兼容。

接入、场景格式与排错 · 计数器场景 · 实施状态与发布门槛 · 对照评测

工作方式

• 模型独立： OpenAI Responses、Anthropic Messages、OpenAI-compatible；支持参考截图。
• 修改可检查： 流式进度、代码差异、文件哈希冲突检测，保留用户现有改动。
• 验证有边界： 类型检查、构建、测试、DevTools 分别报告，缺失检查标记未验证。
• 会话可恢复： 本地 JSONL 日志，不自动重放中断的副作用操作。
• 权限可理解： 可信项目内编辑和已配置检查自动执行；任意 Shell、未知 MCP、上传发布需确认。
• 自动化接口： run --json 输出版本化事件；verify --json 输出检查报告。

weapp-agent run "参考截图实现首页" --image reference.png
weapp-agent sessions
weapp-agent resume SESSION_ID "继续修复失败的检查"
weapp-agent verify --json

--trust 表示你已审阅该项目脚本与配置。工具权限控制不是 OS 沙箱。任务内容和所需源码、截图会发往配置的模型服务，会话保存在本机。不要在提示词或配置中放置密钥。

开发

pnpm validate
pnpm exec repo doctor
pnpm exec repo check
pnpm docs:dev

工程由 repoctl 创建，文档由 Nimbus 创建。核心、模型适配、小程序工具和终端界面相互分离。设计参考与固定源码版本见 架构文档。

License

MIT。第三方项目的商标与许可证归各自维护者所有。