miaoda-app-builder

Readme

# miaoda-app-builder

[中文文档](README.zh-CN.md)

An agent skill for [DeepSeek Harness](https://www.miaoda.cn) that lets an AI agent drive the **Baidu Miaoda (秒哒)** platform — a chat-driven full-stack application builder — through natural-language instructions.

Miaoda turns a natural-language description into a production-ready product: frontend UI, backend services, database schema, integrations, and deployable hosting. Typical outputs include websites, web apps, dashboards, SaaS products, admin panels, internal tools, browser/mini games, Weixin mini programs, native iOS/Android apps, research reports, PPTs, and data analysis documents.

## Repository Layout

```
.
├── SKILL.md               # Skill manifest + full usage guide for the agent
├── _meta.json              # Skill registry metadata (slug, version, publish time)
└── scripts/
    └── miaoda_api.py        # Stateless CLI wrapping the Miaoda HTTP API
```

- **`SKILL.md`** — the source of truth. Defines when the skill should trigger, the application lifecycle (create → PRD refine → generate → publish), all CLI commands with parameters and examples, LGUI node-scoped editing, and error-handling guidance.
- **`scripts/miaoda_api.py`** — the only supported way to talk to the Miaoda platform. All operations go through this script; direct API calls are disallowed by the skill contract.
- **`_meta.json`** — package identity used by the skill registry (`ownerId`, `slug`, `version`, `publishedAt`).

## Requirements

- Python 3
- `requests` package (`pip install requests`)
- A Miaoda API key, exposed as the `MIAODA_API_KEY` environment variable

```bash
export MIAODA_API_KEY="sk_xxxxx"
```

When running inside qianfan-desk without an explicit key, the CLI can fall back to a session-bound Miaoda proxy (`DUMATE_SESSION_ID` + desktop gateway). Outside that environment, set `MIAODA_API_KEY` explicitly.

## Quick Start

```bash
# 1. Create a new app (PRD refinement stage)
python scripts/miaoda_api.py chat --text "创建一个待办事项管理应用"

# 2. Once the trajectory exposes a "Generate App" button, generate it
python scripts/miaoda_api.py generate-app --app-id <app_id> --context-id <context_id> --watch

# 3. Publish to production
python scripts/miaoda_api.py publish --app-id <app_id> --wait
```

To modify an already-generated app, keep using `chat` with the same `appId`/`conversationId` — do **not** call `generate-app` again.

## Available Commands

| Command | Purpose |
|---|---|
| `list-apps` | List applications for the authenticated user |
| `app-detail` | Get app details; auto-injects `conversationId` and `appFocus` (publish readiness) |
| `get-context-id` | Recover a lost `conversationId` from an app's trajectory |
| `conversation-history` | Human-readable summary of past chat turns |
| `chat` | Create a new app, refine its PRD, or modify an existing generated app (supports LGUI `--node-json` for node-scoped edits) |
| `trajectory` / `fetch-trajectory` | Poll or fetch conversation/generation progress events |
| `generate-app` | Trigger app generation (once, only after PRD is ready) |
| `publish` / `publish-status` | Deploy to production and poll release status |
| `download-source` | Download the full generated app source ZIP |
| `list-task-files` | List files in the Agent workspace task directory |
| `download-task-file` | Download one Agent workspace task file (report, image, doc, etc.) |

Full parameter lists, JSON response shapes, the lifecycle state machine, and troubleshooting (`IAM AccessKey validation failed`, `NotOpenSSLWarning`, `秒点不足`) are documented in [`SKILL.md`](SKILL.md).

## Lifecycle Rules (summary)

- **New app:** `chat` → PRD refinement → `generate-app` (once) → `publish`
- **Modify existing app:** `chat` → `chat` → ... (no re-generation)
- **General task** (report / PPT / analysis, no app): `chat` alone; response has `needGenerateApp: false`
- Always pass `--app-id` and `--context-id` **together** when continuing an existing app — passing `--app-id` alone silently creates a new app (the CLI now errors on this instead).
- Treat a successful `publish` (`SUCCESS`) as terminal; do not re-publish just because downstream UI/events look incomplete.