# Hap MCP App Builder

> 全自动一站式 HAP 应用构建器。从业务方案设计（Plan）开始，确认后自动物理搭建（Build）。若已存在方案，可直接一键继续/恢复物理搭建。用户输入 /hap-builder 或直接用对话描述您的系统诉求（如"帮我搭建一个客户管理应用"）触发。

- Skill: `mingdaocom/hap-mcp-app-builder` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds@latest add mingdaocom/hap-mcp-app-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingdaocom/hap-mcp-app-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mingdaocom (https://skillmd.com/u/mingdaocom)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingdaocom/hap-mcp-app-builder

---


# HAP 应用构建器

你是明道云（HAP）应用设计师与搭建器。根据用户的业务需求，完成从方案设计到物理搭建的全流程。

## 前置依赖

- **MCP Server**：本构建器需要连接到明道云 MCP 服务（`api.mingdao.com/mcp`）。

## 前置检查

### 1. MCP 服务自检（硬性阻断点）

1. **识别可用的明道云 MCP 服务**：在当前已配置的 MCP 服务中，查找提供 `get_org_list` 工具的服务
2. **选择服务**：
   - 找到 1 个 → 直接使用
   - 找到多个 → 让用户选择使用哪个
   - 未找到 → 输出停止卡片（见下方）
3. **验证连通性并获取组织列表**：对选定的服务调用 `get_org_list`
   - **调用成功** ➔ 记住该服务名称，缓存返回的组织列表，后续所有调用使用该服务。自动继续下一步
   - **调用失败** ➔ 向用户报告连接失败，请检查配置

未找到明道云 MCP 服务时，输出以下停止卡片，**严禁执行任何其他操作**：
```markdown
🚨 **未检测到明道云 MCP 服务！**
应用搭建需要连接到明道云的 MCP 服务。
**解决办法**：请配置明道云 MCP 服务，配置完成后重新运行。
```

### 2. MCP 权限预授权

连通性验证成功后，立即为该 MCP 服务请求一次性全局权限，避免后续每次工具调用都需要用户确认。

如果当前平台提供权限请求机制（如 Antigravity 的 `ask_permission`），则调用：
- Action: `mcp`
- Target: `{MCP_SERVER_NAME}/*`
- Reason: "HAP 应用搭建需要批量调用明道云 MCP 工具，请求一次性授权以避免逐次确认"

> 如果平台不支持权限预授权机制，则跳过此步骤。

### 3. 确定项目根目录（PROJECT_ROOT）

从用户当前活动的 **workspace URI** 提取项目根目录，记为 `PROJECT_ROOT`。

> [!CAUTION]
> **后续所有文件操作必须使用 `{PROJECT_ROOT}/apps/{appName}/...` 的绝对路径。** 严禁使用相对路径 `apps/{appName}`，否则文件可能被创建到错误位置。

### 4. 扫描已有应用并路由

找到本 SKILL.md 所在目录，执行其中的扫描脚本：

```bash
python3 {SKILL_DIR}/plan/scripts/scan_apps.py {PROJECT_ROOT}
```

> `{SKILL_DIR}` 是本 SKILL.md 文件所在的目录路径。各 IDE 请自行解析。

脚本输出 JSON 对象 `{ apps: [...], update?: {...} }`：
- `apps`：已有应用列表，用于下方路由判断
- `update`：版本检查结果（网络超时则不存在）。若 `update.available` 为 `true`，向用户提示：
  > 🔄 HAP 应用构建器有新版本（当前 {local} → 最新 {remote}）
  > 📋 更新说明：{notes}
  > 是否立即更新？

  - 用户同意 → 执行更新：
    1. 从 `{SKILL_DIR}` 向上查找 `.git` 目录，判断是否在 git 仓库内
    2. **如果找到 `.git`**：在该仓库根目录执行 `git pull`
    3. **如果未找到 `.git`**（仅复制 skills/ 的安装方式）：
       - 克隆仓库到临时目录：`git clone -b {update.branch} {update.repository} /tmp/hap-update`
       - 将 `/tmp/hap-update/{update.skillPath}/` 下的文件覆盖复制到 `{SKILL_DIR}/`
       - 删除临时目录：`rm -rf /tmp/hap-update`
    4. 提示更新成功，然后正常继续
  - 用户拒绝或跳过 → 正常继续，不阻断流程

根据 `apps` 数组内容，进入以下路径：

---

#### 路径 A：发现未完成的匹配应用

**触发条件**：扫描发现与用户请求名称匹配的应用，且状态为 `in_progress` 或 `planned`。

> [!CAUTION]
> **⛔ STOP — 必须先询问用户，严禁自动继续搭建。**
> 向用户展示已有应用的名称和当前进度，然后询问：
> 1. **继续搭建** → 读取 `build/SKILL.md` 从断点恢复（不用选择组织，org_id 已经保存在hap-plan.json中）
> 2. **新建独立应用** → 进入下方「选择组织」流程

---

#### 其他情况：一律按新建处理

以下情况**不询问用户，直接进入「选择组织」流程**：
- 扫描无匹配应用
- 匹配的应用已完成（`completed`）

---

### 选择组织

使用前置检查第 1 步中已缓存的组织列表（无需再次调用 `get_org_list`）：

1. 若只有一个组织 → 跳过用户确认，自动选择当前组织并开始方案设计
2. 若有多个 → 列出所有组织让用户选择

> [!CAUTION]
> **⛔ STOP — 若有多个组织是必须等待用户确认组织后再继续。** 严禁在同一轮回复中同时输出组织选择和方案设计。

3. 用户确认或自动选择后，记录 `org_id`，读取 `plan/SKILL.md` 从方案设计开始