<div align="center">

<img src="docs/assets/banner.svg" alt="MakeAWish — 许愿式编程" width="100%">

<br>

**不会写代码？没关系。说出你想要的 App，剩下的交给神灯。**

[![MCP](https://img.shields.io/badge/MCP-genie-7c5cff?style=flat-square)](#-架构)
[![Agents](https://img.shields.io/badge/适配-11%2B%20个%20Agent-e9c46a?style=flat-square)](#-支持的-agent)
[![Zero deps](https://img.shields.io/badge/依赖-0-5ee6a8?style=flat-square)](#-安装)
[![Stack](https://img.shields.io/badge/技术栈-8%20平台%20×%202%20区域-ff6b6b?style=flat-square)](docs/STACK_MATRIX.md)
[![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE)

[30 秒看懂](#-30-秒看懂) · [流程](#-一个愿望是怎么变成-app-的) · [架构](#-架构) · [安装](#-安装) · [支持的 Agent](#-支持的-agent) · [分流表](docs/STACK_MATRIX.md)

</div>

---

## ✨ 30 秒看懂

```text
你：/wish 做一个出海的 AI 记账 iPhone App，拍小票自动识别，要能订阅付费

🪔 神灯已亮。
🔮 解梦  → iOS 原生 · 海外 · AI + 支付 + 账号 · 复杂度 M
🧭 分流  → SwiftUI + Supabase + Edge Function 调 Claude + RevenueCat + XCUITest
📜 铸约  → 5 条用户故事、4 张表（含 RLS）、3 个函数、端到端链路全部写清
🎨 造梦  → 「温暖治愈」主题，亮/暗双色，5 个页面原型已截图走查
⚒️ 施法  → 编码 → xcodebuild 构建通过
🧪 试炼  → 单元测试 18/18 · UI 测试 6/6 · 截图 12 张
🌟 兑现  → 兑现度 96/100 🌟🌟🌟 神灯满愿 · 交付报告与愿望证书已生成
```

<sub>↑ 示意流程。真实运行时每一步都会落盘产物，你随时可以打开看。</sub>

| 以前做一个 App | 现在 |
|---|---|
| 学框架、选技术栈、查文档、纠结用哪个云 | 🔮 神灯按 **8 平台 × 2 区域 × 12 能力** 的分流表自动决定 |
| 需求写不清，写到一半推倒重来 | 📜 先铸一份端到端技术契约，你点头了才开工 |
| 界面丑、配色乱 | 🎨 先出设计令牌和可点原型，截图走查过再写代码 |
| 「我电脑上能跑啊」 | 🧪 构建 + 单元测试 + **真机/浏览器 UI 测试**，带截图证据 |
| 不知道做完没有 | 🌟 兑现度打分 + 交付报告 + 一张愿望兑现证书 |

---

## 🪄 一个愿望是怎么变成 App 的

<p align="center"><img src="docs/assets/pipeline.svg" alt="MakeAWish 流水线：解梦、铸约、造梦、施法、试炼、兑现" width="100%"></p>

整个过程**只打扰你两次**：不确定国内还是海外时问一次，技术契约写好后确认一次。中途要装软件、要你的云账号或要花钱时，也会先问你。

| 阶段 | 神灯在干嘛 | 你能看到的产物 |
|---|---|---|
| 🔮 解梦 | 判断形态、面向国内还是海外、需要哪些能力 | 分流结果 |
| 📜 铸约 | 把「我想要」翻译成「怎么做」：用户故事、数据表、接口、AI 调用链路、每个按钮点下去之后发生的每一步 | `.wish/SPEC.md` |
| 🎨 造梦 | 根据愿望的情绪定配色和字体，画出关键页面的可点原型 | `.wish/design/` |
| ⚒️ 施法 | 检查并补齐工具，生成项目，逐条实现，编译到零错误 | 你的项目代码 |
| 🧪 试炼 | 单元测试 + UI 测试（自动点按钮、截图），不过就修 | `.wish/evidence/` 截图 |
| 🌟 兑现 | 打分、写交付报告、颁发证书 | `DELIVERY.md` + `certificate.html` |

---

## 🧭 技术栈分流：神灯怎么替你做选择

<p align="center"><img src="docs/assets/routing.svg" alt="技术栈分流：平台 × 区域 × 能力" width="100%"></p>

几个真实的分流例子（来自自带的回归测试）：

| 愿望 | 分流结果 |
|---|---|
| 做一个微信小程序，给社区团购用 | `miniprogram.cn` → 原生小程序 + TDesign + CloudBase |
| 我要一个海外的 SaaS 后台，团队协作看板 | `web-app.global` → Next.js + shadcn/ui + Supabase Realtime + Playwright |
| 给我的咖啡店做个官网，国内用户 | `web-site.cn` → Astro + CloudBase 静态托管 |
| iOS 和安卓都要的健身打卡 app，出海 | `cross-mobile.global` → Expo + NativeWind + Supabase + Maestro |

完整分流表见 **[docs/STACK_MATRIX.md](docs/STACK_MATRIX.md)**（平台层 × 区域层 × 功能模块 × AI 调用铁律）。

---

## 🏛 架构

<p align="center"><img src="docs/assets/architecture.svg" alt="MakeAWish 架构：Agent、Skill、genie MCP、法器与数据" width="100%"></p>

一句话：**Skill 负责「想」和「做」，MCP 负责「算」和「记」**。

- **Skill（大脑）**：告诉 AI 每个阶段该做什么、做到什么程度才算完。AI 读规程、写代码、跑命令、调用其他工具。
- **genie MCP（神灯）**：所有需要「稳定、可复现」的东西都在这里——分流规则、技术栈组合、契约骨架、设计令牌、流水线状态、测试记录、兑现度计算、报告生成。零依赖，Node.js 直接跑。
- **规程也装进了 MCP**：不支持 Skill 的 agent 通过 `wish_guide` 工具读同一份规程，所以只要能接 MCP 就能许愿。
- **状态落盘**：一切记录在你项目的 `.wish/` 里，关掉电脑明天接着许。

<details>
<summary><b>📂 目录结构</b></summary>

```
makeawish/
├── install.mjs              一键接入各家 agent
├── mcp/
│   ├── server.mjs           🪔 genie MCP（11 个工具 + /wish 提示词）
│   └── lib/                 triage 分流 · route 组栈 · spec 契约 · design 令牌
│                            deliver 报告证书 · workspace 状态机
├── matrix/stacks.json       📚 技术栈分流表（唯一数据源）
├── skills/makeawish/        🧠 总控 skill + references/01-06 阶段规程
├── commands/                /wish · /wish-status · /wish-matrix（Claude Code、Gemini）
├── agents/wish-qa.md        🧪 试炼官子 agent：独立跑 UI 测试
├── .claude-plugin/          Claude Code 插件 & 插件市场清单
├── gemini-extension.json    Gemini CLI 扩展
├── qwen-extension.json      Qwen Code 扩展
├── GEMINI.md · QWEN.md      扩展上下文
└── scripts/                 smoke.mjs 冒烟测试 · render-matrix.mjs · draw-diagrams.mjs
```
</details>

<details>
<summary><b>🧰 genie MCP 的 11 个工具</b></summary>

| 工具 | 作用 |
|---|---|
| `wish_guide` | 📖 读操作手册（总览 / 各阶段规程） |
| `wish_triage` | 🔮 解梦：分流平台 × 区域 × 能力，建立 `.wish/` |
| `wish_route_stack` | 🧭 组装完整技术栈，可按用户纠正重算 |
| `wish_stack_matrix` | 📚 查看整张分流表 |
| `wish_forge_spec` | 📜 生成技术契约骨架 |
| `wish_design_system` | 🎨 生成设计令牌（CSS / SwiftUI / Compose） |
| `wish_toolchain_check` | 🧰 检查 CLI，给出安装命令与推荐 MCP |
| `wish_checkpoint` | 🚩 推进流水线阶段 |
| `wish_record_test` | 🧪 记录构建 / 单元 / UI 测试结果与截图 |
| `wish_status` | 📍 查看进度与兑现度预估 |
| `wish_deliver` | 🌟 生成交付报告与愿望证书 |

另外提供 MCP 提示词 `wish`，在支持 MCP prompts 的客户端里就是一个 `/wish` 命令。
</details>

---

## 📦 安装

需要 [Node.js](https://nodejs.org) ≥ 20。没有别的依赖。

**第 1 步**：下载

点本页右上角绿色的 **Code → Download ZIP**，解压后把文件夹改名为 `makeawish`，放到你的用户目录下（也就是 `~/makeawish`）。会用 git 的话，直接把本仓库 clone 到同一位置。

**第 2 步**：一键接入你电脑上所有的 AI 编程助手

```bash
node ~/makeawish/install.mjs all
```

**第 3 步**：重启 agent，然后说

```text
我想做一个……
```

想只装某一个，把 `all` 换成名字就行，比如 `node ~/makeawish/install.mjs cursor`。加 `--project <你的项目目录>` 会同时写入项目规则，让 agent 更主动地触发许愿；加 `--dry-run` 只看不装。

---

## 🤝 支持的 Agent

| Agent | 接入方式 | 安装命令 | 状态 |
|---|---|---|---|
| **Claude Code** | 原生插件（Skill + MCP + 命令 + 子 Agent） | `install.mjs claude` | ✅ 已验证 |
| **OpenAI Codex CLI** | MCP + Skill | `install.mjs codex` | ✅ 已验证 |
| **Gemini CLI** | 原生扩展（MCP + 上下文 + `/wish`） | `install.mjs gemini` | ✅ 已验证 |
| **Cursor** | MCP + Rules | `install.mjs cursor` | 🧪 配置写入已验证 |
| **Windsurf** | MCP + Rules | `install.mjs windsurf` | 🧪 社区适配 |
| **OpenCode** | MCP + AGENTS.md | `install.mjs opencode` | 🧪 社区适配 |
| **Qwen Code**（通义） | 原生扩展 | `install.mjs qwen` | 🧪 社区适配 |
| **CodeBuddy**（腾讯） | MCP + Skill | `install.mjs codebuddy` | 🧪 社区适配 |
| **Kimi CLI**（月之暗面） | MCP | `install.mjs kimi` | 🧪 社区适配 |
| **Trae**（字节） | MCP + Rules | `install.mjs trae` | 🧪 引导手动粘贴 |
| **Cline / Roo Code** | MCP + Rules | `install.mjs cline` | 🧪 引导手动粘贴 |
| **其他支持 MCP 的** | 通用 | `install.mjs print` | 打印配置自行粘贴 |

> ✅ 已验证：在真实 CLI 中完成安装并确认 genie MCP 连接成功。🧪 社区适配：按各家公开的配置格式实现，欢迎提 Issue 反馈。

**Claude Code 用户**也可以把下载好的文件夹当作插件市场添加：

```bash
claude plugin marketplace add ~/makeawish
```

```bash
claude plugin install makeawish@makeawish
```

---

## 🌟 兑现度与愿望证书

神灯不会自己说「做完了」。交付时按下面的规则打分：

| 项 | 权重 |
|---|---|
| 测试通过率 | 40% |
| 流水线阶段完成度 | 25% |
| 带界面的应用有通过的 UI 测试 | 20% |
| 构建成功 | 15% |

**≥95** 🌟🌟🌟 神灯满愿 · **≥80** 🌟🌟 愿望成真 · **≥60** 🌟 初步显灵 · 其余 💨 法力不足

没有构建记录、或者带界面却没做 UI 测试的应用，**不算兑现**。最后会生成 `DELIVERY.md` 交付报告，和一张带 UI 截图的 `certificate.html` 愿望兑现证书。

---

## ❓ 常见问题

<details>
<summary><b>我完全不会编程，能用吗？</b></summary>

能。你只需要会描述你想要什么。神灯会在需要你做决定的时候用选择题问你（比如「主要给国内用户还是海外用户？」），其他的它自己搞定。不过最后上架应用商店、绑定域名这类需要你本人账号的事，还是得你自己点。
</details>

<details>
<summary><b>国内和海外有什么区别？</b></summary>

面向海外用户默认用 **Supabase**（数据库、登录、存储一站式）+ Claude 模型 + Stripe / 应用内购买；面向国内用户默认用**腾讯云 CloudBase** + 混元 / DeepSeek 等国内模型 + 微信 / 支付宝，并提醒你备案和隐私合规。
</details>

<details>
<summary><b>会不会乱装东西、乱花钱？</b></summary>

不会。装软件、用你的云账号、任何可能产生费用的操作，都会先列出来问你。密钥也不会让你贴在聊天里，而是让你自己写进本地配置文件。
</details>

<details>
<summary><b>能做多复杂的东西？</b></summary>

一次许愿聚焦一个 MVP（通常 3–5 个核心功能）。做完后交付报告里会附上「下一个愿望」建议，继续许就行。复杂度高的愿望，Claude Code 下会拆成多个模块并行施法。
</details>

<details>
<summary><b>我用的 agent 不在列表里？</b></summary>

只要它支持 MCP，就运行 `node install.mjs print`，把输出的配置和规则粘贴进去即可。规程本身也通过 MCP 提供，不依赖 Skill 功能。
</details>

---

## 🛠 开发

```bash
npm test
```

冒烟测试会启动 genie MCP，走完整条许愿流水线，并对分流引擎跑回归用例。修改 `matrix/stacks.json` 后运行 `npm run matrix` 重新生成分流表文档；README 里的图由 `npm run diagrams` 生成（`scripts/draw-diagrams.mjs`）。

## 📄 License

MIT