# 应用构建 Skill

应用构建 Skill 让本地 AI 在你的电脑上编写和调试茄总多文件应用，再通过已经授权的 MCP 安装到你的个人空间。它不要求你取得茄总项目源码，也不会自动把应用发布到公开市场。

## 使用前提

- AI 助手能够读取本地 Skill 文件、执行 Node.js 命令并查看图片。
- 电脑安装 Node.js 22 或更新版本；第一次预览可能需要准备浏览器运行时。
- 需要安装到个人空间时，AI 助手还需要连接茄总 MCP，并由你完成授权。

下载入口：[应用构建 Skill](/skill)。正式发布版本会同时提供版本号、文件大小和 SHA-256 校验值。

## 推荐请求

```text
使用 $life-os-app-builder，帮我做一个记录家庭支出的应用。
先在本地预览和测试，不要安装到桌面；等我确认后再安装。
```

AI 会先阅读设计原则和工作流，再创建 `app.json`、`index.js` 以及必要的 `pages/`、`lib/` 文件。应用必须通过 `platform.*` 访问数据，不能直接 `fetch`、使用外部模块或访问本地文件。

## 本地预览

预览使用 Skill 自带的 runtime/container 和合成数据，不读取你的正式记录：

```sh
node scripts/preview.mjs --app ./my-app \
  --fixtures ./fixtures/demo.json \
  --steps ./steps/smoke.json \
  --out ./artifacts/preview
```

调试步骤使用语义操作：`click`、`fill`、`select`、`expect_text` 和 `wait`。报告会记录源码 hash、runtime hash、宽屏和窄屏结果、运行时错误、被阻断请求以及步骤状态。预览服务结束后会关闭浏览器和本地端口。

本地 AI 应先运行：

```sh
node scripts/doctor.mjs
node scripts/check-package.mjs --app ./my-app
```

## 安装到桌面

只有你明确要求安装时，AI 才调用 MCP。一般流程是：

1. `validate_app` 检查文件包。
2. 必要时使用 `list_app_tables` 和 `prepare_app_table` 创建空逻辑表。
3. 新应用使用 `create_app`；已有应用先使用 `read_app_source` 读取最新版本，再使用 `update_app`。
4. 每项写入使用稳定 `idempotency_key`；响应不确定时先查询操作和应用版本，不能重复创建。
5. 安装后核对应用 ID、源码 revision、数据绑定和操作结果。

安装到个人桌面不等于发布市场。Skill 不会复制预览数据，不会上传 MCP token，也不会替你操作公开市场。

## 常见问题

- **没有本地命令权限**：当前助手不能运行这个 Skill，需要使用支持本地文件和脚本的客户端。
- **预览失败**：先查看报告中的 runtime 错误和具体步骤，修复后重新预览，不要跳过错误。
- **MCP 未连接**：仍然可以本地编写和预览；只有安装到桌面才需要连接。
- **安装结果不明确**：不要重试相同参数，先读取操作状态和当前应用 revision。
- **想公开分享**：这是独立的市场发布操作，需要你另外明确要求。