Skill: seiriosplus/miaoda-app-builder (version 1.0.12)

--- name: miaoda-app-builder description: >- Create, modify, generate, and deploy websites, web apps, dashboards, SaaS products, internal tools, interactive web pages, Weixin mini program , games on the Baidu Miaoda (秒哒) platform using natural-language instructions. metadata: openclaw: requires: bins: - python3 env: - MIAODA_API_KEY primaryEnv: MIAODA_API_KEY disable-model-invocation: false --- # Miaoda (秒哒) App Builder Miaoda (秒哒) is a **chat-driven full-stack application builder**. Official website: https://www.miaoda.cn Users describe what they want in natural language and Miaoda generates a **production-ready web product**, including: - frontend UI - backend services - database schema - integrations - deployable hosting Typical outputs include: - websites - web applications - dashboards - SaaS products - admin panels - internal tools - landing pages - interactive web pages - browser games and mini games - research reports - data analysis documents - PPT / presentations - general content documents This skill enables AI agents to interact with the **Miaoda(秒哒) platform** to create, iterate, generate, and deploy applications. All platform operations must be executed through the packaged CLI script: ```bash python scripts/miaoda_api.py <command> [options] ``` Do **not** call platform APIs directly. Always use the CLI commands provided by this skill. --- # When to Use This Skill Use this skill whenever the user wants to: * create a **website** * create a **webpage** * build a **web application** * build a **dashboard** * create a **SaaS product** * build an **admin panel** * build an **internal tool** * create a **landing page** * build an **interactive web page** * create a **browser game** * create a **mini game** * generate an **MVP web product** * modify an existing **Miaoda project** * publish or deploy a **Miaoda application** * generate a **research report** * create a **PPT or presentation** * produce a **data analysis document** * create any **general content output** (not a deployed app) Do **not** use this skill for unrelated programming tasks. --- # Routing Keywords Trigger this skill if the request includes concepts such as: * build a website * create a webpage * build a web app * create a SaaS * build a dashboard * create an admin panel * build an internal tool * create a landing page * build a browser game * create a mini game * generate a web product * make a snake game webpage * build a todo web app * create a blog site --- # Example Requests Examples that should route to this skill: * "Create a todo list web app" * "Build a personal blog website" * "Make a dashboard for sales analytics" * "Create a SaaS landing page" * "Build an admin panel" * "Write a snake game webpage" * "Create a browser game" * "Build a mini web game" * "Modify my Miaoda project" * "Publish this Miaoda app" --- # Stateless Execution Model The CLI script is **stateless**. It does not store workflow state between calls. Application workflow state is maintained by the Miaoda platform and must be inferred from: * `appId` * `conversationId` * application detail * conversation trajectory events Agents must pass the appropriate identifiers when continuing conversations or modifying applications. --- # Application Lifecycle Rules Miaoda applications follow a strict lifecycle. Agents must follow these rules. --- ## Initial Creation For a new application: 1. Start with a `chat` request describing the product. 2. The application enters the **PRD refinement stage**. 3. Continue chatting to refine the specification. 4. When the trajectory contains a **Generate App** button (`type":"button"` and `event":{"name":"generateApp"}` in `result.artifact.parts[].data.actions[]`), trigger application generation using `generate-app`. Generation is required **only once** during the initial creation. --- ## Multi-Round Modification After an application has already been generated: * **Do not call `generate-app` again.** * Continue using `chat` with the same `appId` and `conversationId`. Normal chat messages modify the existing application. --- ## Publishing Publishing is allowed **after the application has been generated at least once**. Rules: * Publishing does **not require another generation step** * Publishing may happen anytime after the first generation * Publishing must be followed by **status polling** (or use `--wait` flag) Typical deployment flow: ``` publish → publish-status polling ``` Or use the `--wait` flag to auto-poll: ``` publish --wait ``` Stop polling when the status becomes: * `SUCCESS` * `FAILED` --- ## General Task (No Generation Required) For general tasks such as research reports, PPT, or analysis documents, the platform processes the request entirely in the chat stage. Rules: * There is **no PRD refinement stage** * There is **no `generate-app` step** * There is **no `publish` step** * The task is complete when `chat` returns `{"needGenerateApp": false, "appType": "TASK"}` Do **not** call `generate-app` for general tasks. --- # Application URLs Miaoda provides two types of URLs during the lifecycle. --- ## Project Preview (Editor / Development) After the application is created, the project can be accessed at: ``` https://www.miaoda.cn/projects/<app_id> ``` This URL can be shared with the user for: * viewing the project * editing the application * previewing the generated result The preview URL becomes available once an `appId` is created. --- ## Production Deployment URL After publishing succeeds, the application is accessible at: ``` https://<app_id>.appmiaoda.com ``` This is the **public production URL** of the deployed application. Only return this URL after publishing completes successfully. --- # Standard Workflow ## Create New Application ``` chat → PRD refinement → generate-app --watch → publish --wait ``` --- ## Modify Existing Generated Application ``` chat → chat → chat ``` (no additional generation step required) --- ## Deploy Application ``` publish → publish-status polling ``` Or: ``` publish --wait ``` --- ## General Task (Direct Completion) ``` chat → state:completed (needGenerateApp: false) ``` No generate-app or publish step required. --- # Available Commands All commands are executed via the CLI script. **Important**: Always set the `MIAODA_API_KEY` environment variable before running commands. ```bash export MIAODA_API_KEY="your_api_key_here" ``` --- ## list-apps List all applications belonging to the authenticated user. **Usage:** ```bash python scripts/miaoda_api.py list-apps [--brief] ``` **Optional Parameters:** - `--brief`: Output only key fields: `appId`, `name`, `type`, `appFocus`, `host`, `updatedAt`. Recommended for agents to reduce token usage. - `--name NAME`: Filter by app name (substring) - `--page PAGE`: Page number (default: 1) - `--size SIZE`: Page size (default: 12) **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" # Brief mode (recommended for agents) python scripts/miaoda_api.py list-apps --brief # Full mode python scripts/miaoda_api.py list-apps ``` **Returns:** JSON array of applications with `appId`, `name`, `type`, etc. --- ## app-detail Get detailed information about a specific application. **Automatically injects `conversationId`** into the response by default — no need to call `get-context-id` separately. **Usage:** ```bash python scripts/miaoda_api.py app-detail --app-id <app_id> [--no-context] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--no-context`: Skip auto-fetching `conversationId` from trajectory (faster, but response will not contain `conversationId`) **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py app-detail --app-id app-abc123xyz ``` **Returns:** JSON object with application details, configuration, and status. `data.conversationId` is automatically populated. **appFocus — Publish Readiness Guide:** After calling `app-detail`, check `data.appFocus` to determine whether publishing is allowed: | `appFocus` | Meaning | Can Publish? | |------------|---------|--------------| | `NOT_GENERATE` | Not yet generated | No — call `generate-app` first | | `WAITING` | Queued for generation | No — wait for generation to complete | | `UNDER_CREATING` | Generation in progress | No — wait for generation to complete | | `CREATE_FAILED` | Generation failed | No — retry `generate-app` | | `DESIGNING` | Generated, ready to edit/deploy | **Yes** | | `RELEASED` | Already published | **Yes** (re-publish allowed) | | `RELEASE_FAILED` | Last publish failed | **Yes** (retry allowed) | | `UNDER_RELEASE` | Publish currently in progress | Wait — do not call publish again | **Rule:** Only proceed with `publish` when `appFocus` is `DESIGNING`, `RELEASED`, or `RELEASE_FAILED`. --- ## get-context-id Recover the `conversationId` for an existing app by reading its trajectory. Useful when the `conversationId` has been lost after a session reset. **Usage:** ```bash python scripts/miaoda_api.py get-context-id --app-id <app_id> ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--fetch-timeout SECONDS`: Request timeout in seconds (default: 10) **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py get-context-id --app-id app-abc123xyz ``` **Returns:** `{"appId": "app-abc123xyz", "conversationId": "conv-def456uvw"}` **Use Cases:** - Need to modify a previously created app in a new session but `conversationId` is lost - Use the returned `conversationId` with `chat --app-id --context-id` to resume modification --- ## conversation-history Show a human/agent-readable summary of past interactions for an app. More convenient than `trajectory` or `fetch-trajectory` for quickly understanding what happened in previous sessions. **Usage:** ```bash python scripts/miaoda_api.py conversation-history --app-id <app_id> [options] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--full`: Show full content instead of truncated summaries (default: truncate at 200 chars) - `--limit N`: Only show the last N conversation turns - `--fetch-timeout SECONDS`: Request timeout in seconds (default: 10) **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" # View conversation history summary python scripts/miaoda_api.py conversation-history --app-id app-abc123xyz # Only show the last 3 turns python scripts/miaoda_api.py conversation-history --app-id app-abc123xyz --limit 3 # Show full content without truncation python scripts/miaoda_api.py conversation-history --app-id app-abc123xyz --full ``` **Returns:** JSON Lines, one entry per meaningful turn: ```json {"eventId": 5, "role": "user", "type": "message", "content": "创建一个待办事项应用..."} {"eventId": 865, "role": "agent", "type": "file", "content": "[file: 需求文档.md]"} {"eventId": 880, "role": "user", "type": "message", "content": "生成应用"} ``` **Use Cases:** - Quickly understand what happened in previous sessions before resuming work - Determine which phase the app is in (PRD refinement / generated / modified) - Check for unfinished modifications or cancelled tasks --- ## chat Start or continue a conversation to create or modify an application. **Usage:** ```bash python scripts/miaoda_api.py chat --text "description" [options] ``` **Required Parameters:** - `--text TEXT`: The message/instruction to send **Optional Parameters:** - `--context-id CONTEXT_ID`: Conversation ID of an existing app. - `--app-id APP_ID`: Application ID of an existing app. - `--query-mode QUERY_MODE`: Query mode (default: deep_mode) - `--input-field-type INPUT_FIELD_TYPE`: Input field type (default: web) - `--poll-interval SECONDS`: Seconds between trajectory polls (default: 2.0) - `--fetch-timeout SECONDS`: Per-request timeout for each trajectory fetch (default: 10) - `--no-stream`: Return raw chat POST response without trajectory polling - `--prompt-generate`: After polling, interactively ask whether to submit app generation if text was returned > **⚠️ IMPORTANT — `--app-id` and `--context-id` must always be used together.** > > | Intent | `--app-id` | `--context-id` | > |--------|-----------|----------------| > | Create a brand-new app | omit | omit | > | Continue / modify an existing app | required | required (conversationId) | > > Passing `--app-id` **without** `--context-id` will **NOT** modify the existing app. > The platform will silently create a **new** app every time. The CLI will now raise an error in this case to prevent accidental app proliferation. **Examples:** **1. Create a new application:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py chat --text "创建一个待办事项管理应用" ``` Response includes `appId` and `contextId` for subsequent calls. **2. Continue conversation (refine PRD):** ```bash python scripts/miaoda_api.py chat \ --text "添加优先级标记功能" \ --app-id app-abc123xyz \ --context-id conv-def456uvw ``` **3. Modify existing generated app:** ```bash python scripts/miaoda_api.py chat \ --text "把按钮颜色改成蓝色" \ --app-id app-abc123xyz \ --context-id conv-def456uvw ``` **Important Notes:** - Extract `appId` and `contextId` from the response and save them - Use these IDs for all subsequent operations on the same app - The first `chat` creates the app and starts PRD refinement - After generation, `chat` directly modifies the app (no `generate-app` needed) --- ## trajectory Poll trajectory events until the task reaches a terminal state. **Usage:** ```bash python scripts/miaoda_api.py trajectory --app-id <app_id> [options] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--last-event-id EVENT_ID`: Start eventId; -1 = all events from beginning (default: -1) - `--poll-interval SECONDS`: Seconds between polls (default: 2.0) - `--fetch-timeout SECONDS`: Per-request timeout in seconds (default: 10) - `--sse`: Use legacy SSE streaming instead of polling **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py trajectory --app-id app-abc123xyz ``` **Use Cases:** - Monitor conversation / generation progress - Detect when PRD refinement is complete (look for Generate App button in `result.artifact.parts[].data.actions[]`) - Verify generation has completed --- ## fetch-trajectory Fetch one batch of trajectory events (single request, no polling loop). **Usage:** ```bash python scripts/miaoda_api.py fetch-trajectory --app-id <app_id> [options] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--last-event-id EVENT_ID`: Fetch events after this eventId; -1 = all (default: -1) - `--fetch-timeout SECONDS`: Request timeout in seconds (default: 10) **Example:** ```bash # First call — get all events (note maxEventId from stderr) python scripts/miaoda_api.py fetch-trajectory --app-id app-abc123xyz # Subsequent calls — incremental fetch python scripts/miaoda_api.py fetch-trajectory --app-id app-abc123xyz --last-event-id 345 ``` Events are printed to stdout as JSON lines; `{"maxEventId": N, "isTerminal": bool}` is printed to stderr. **Generate App readiness:** Inspect `result.artifact.parts[].data.actions[]` for an action with `"type":"button"` and `"event":{"name":"generateApp"}`. Example: ```json {"type":"button","label":"Generate App","value":"Generate App","event":{"name":"generateApp"}} ``` When this button appears, PRD is ready and `generate-app` may be called. --- ## generate-app Submit app-generation confirmation and return immediately with `appId`/`conversationId`. **Usage:** ```bash python scripts/miaoda_api.py generate-app --app-id <app_id> --context-id <context_id> [options] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID **Optional Parameters:** - `--context-id CONTEXT_ID`: Conversation ID (default: "") - `--query-mode QUERY_MODE`: Query mode (default: deep_mode) - `--watch`: Block and poll trajectory until generation completes **(recommended)** (default: return immediately) - `--poll-interval SECONDS`: Seconds between polls when `--watch` is set (default: 2.0) - `--fetch-timeout SECONDS`: Per-request timeout in seconds when `--watch` is set (default: 10) **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" # Recommended: submit and block until generation finishes python scripts/miaoda_api.py generate-app \ --app-id app-abc123xyz \ --context-id conv-def456uvw \ --watch # Alternative: submit and return immediately — check status later with fetch-trajectory python scripts/miaoda_api.py generate-app \ --app-id app-abc123xyz \ --context-id conv-def456uvw ``` **Important:** - Only call this **once** during initial creation - Call **only** when trajectory contains a Generate App button in `result.artifact.parts[].data.actions[]`: an action with `"type":"button"` and `"event":{"name":"generateApp"}` (label may vary by locale; use event name for the check). This indicates PRD is ready. - Do **not** call again for modifications after the first generation - After this command, use `chat` to modify the generated app > * **Never** call this command when `chat` returns `"needGenerateApp": false`. > General tasks (reports, PPT, analysis) complete in the `chat` step and > do not have a generation stage. --- ## publish Trigger deployment to production. **Usage:** ```bash python scripts/miaoda_api.py publish --app-id <app_id> [options] ``` **Required Parameters:** - `--app-id APP_ID`: Application ID to publish **Optional Parameters:** - `--env ENV`: Target environment (default: PRODUCE) - `--wait`: Auto-poll publish status until SUCCESS or FAILED **Examples:** **1. Publish and manually check status:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py publish --app-id app-abc123xyz ``` Returns `releaseId` immediately. Then poll with `publish-status`. **2. Publish and auto-wait for completion (recommended):** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py publish --app-id app-abc123xyz --wait ``` This polls automatically and exits when deployment succeeds or fails. **Important:** - Application must be generated at least once before publishing - After successful publish, the app is live at: `https://<app_id>.appmiaoda.com` --- ## publish-status Check the status of a deployment. **Usage:** ```bash python scripts/miaoda_api.py publish-status --release-id <release_id> ``` **Required Parameters:** - `--release-id RELEASE_ID`: Release ID from `publish` command **Example:** ```bash export MIAODA_API_KEY="sk_xxxxx" python scripts/miaoda_api.py publish-status --release-id app_release_record-xyz789abc ``` **Returns:** JSON with status: `PROCESSING`, `RUNNING`, `SUCCESS`, or `FAILED` **Usage Pattern:** ```bash # Get release ID from publish RELEASE_ID=$(python scripts/miaoda_api.py publish --app-id app-abc123xyz | jq -r '.releaseId') # Poll status while true; do STATUS=$(python scripts/miaoda_api.py publish-status --release-id $RELEASE_ID | jq -r '.status') echo "Status: $STATUS" if [[ "$STATUS" == "SUCCESS" || "$STATUS" == "FAILED" ]]; then break fi sleep 5 done ``` **Tip:** Use `publish --wait` to avoid manual polling. --- # Complete Workflow Examples ## Example 1: Create and Deploy a New App ```bash export MIAODA_API_KEY="sk_xxxxx" cd ~/.openclaw/skills/miaoda-app-builder # Step 1: Create app via chat (returns appId + conversationId on first line) FIRST=$(python scripts/miaoda_api.py chat --text "创建一个简单的计数器应用" | head -1) APP_ID=$(echo $FIRST | jq -r '.appId') CONTEXT_ID=$(echo $FIRST | jq -r '.conversationId') # Step 2: Generate and wait for completion (recommended: --watch auto-polls until done) python scripts/miaoda_api.py generate-app \ --app-id $APP_ID \ --context-id $CONTEXT_ID \ --watch # Step 3: Publish (with auto-wait) python scripts/miaoda_api.py publish --app-id $APP_ID --wait # Done! App is live at: echo "https://$APP_ID.appmiaoda.com" ``` --- ## Example 2: Modify an Existing App > **IMPORTANT — Always update `CONTEXT_ID` from each `chat` response.** > > Each `chat` call prints a JSON header line `{"appId": "...", "conversationId": "..."}`. > The platform may return an updated `conversationId` in this response. > **Always capture it and use it for the next `chat` call**, or the next round will create a brand-new app. ```bash export MIAODA_API_KEY="sk_xxxxx" cd ~/.openclaw/skills/miaoda-app-builder APP_ID="app-abc123xyz" # Step 1: Get app detail — conversationId is auto-injected DETAIL=$(python scripts/miaoda_api.py app-detail --app-id $APP_ID) CONTEXT_ID=$(echo $DETAIL | jq -r '.data.conversationId') # Abort early if conversationId is missing (app may have no history yet) if [ -z "$CONTEXT_ID" ] || [ "$CONTEXT_ID" = "null" ]; then echo "Error: could not retrieve conversationId. Try: get-context-id --app-id $APP_ID" exit 1 fi # Step 2 (optional): Review conversation history to understand previous work python scripts/miaoda_api.py conversation-history --app-id $APP_ID # Step 3a: First modification — capture the UPDATED conversationId from the response header CHAT_RESULT=$(python scripts/miaoda_api.py chat \ --text "把背景颜色改成深色模式" \ --app-id $APP_ID \ --context-id $CONTEXT_ID | head -1) CONTEXT_ID=$(echo $CHAT_RESULT | jq -r '.conversationId') # ← UPDATE for next round # Step 3b: Second modification — uses the updated CONTEXT_ID CHAT_RESULT=$(python scripts/miaoda_api.py chat \ --text "添加暗黑模式切换按钮" \ --app-id $APP_ID \ --context-id $CONTEXT_ID | head -1) CONTEXT_ID=$(echo $CHAT_RESULT | jq -r '.conversationId') # ← UPDATE again # Step 4: Re-publish python scripts/miaoda_api.py publish --app-id $APP_ID --wait ``` --- # Command Semantics ## chat Used to: * create a new application * refine PRD specifications * modify an existing generated application For a new application, `chat` creates the project and begins the PRD stage. For an existing application, `chat` performs iterative modifications. --- ## trajectory Streams conversation progress and system events. Use this to determine: * whether PRD generation is ongoing * whether the app is ready for generation (see generate-app condition below) * whether generation has completed --- ## generate-app Triggers application generation. Call **only** when trajectory contains a Generate App button in `result.artifact.parts[].data.actions[]`: an action with `"type":"button"` and `"event":{"name":"generateApp"}`. This indicates PRD is ready. Do **not** rely on text alone—the button structure is the authoritative signal. Call **once** during initial creation. Do not call again for modifications. --- ## publish Triggers application deployment. Use `--wait` flag to auto-poll status (recommended). --- ## publish-status Polls deployment progress until the release completes. Not needed if using `publish --wait`. --- # Error Handling ## IAM AccessKey Validation Failed **Symptom:** ``` IAM access key validation failed. ``` **Cause:** The configured `MIAODA_API_KEY` is invalid or missing. **Resolution:** 1. Go to the Miaoda(秒哒) official website: https://www.miaoda.cn 2. In the left navigation panel, apply for an available access key. 3. Set the key as the environment variable: ```bash export MIAODA_API_KEY="sk_xxxxx" ``` 4. Or create a `.env` file in the skill directory: ```bash echo "MIAODA_API_KEY=sk_xxxxx" > ~/.openclaw/skills/miaoda-app-builder/.env ``` --- ## NotOpenSSLWarning **Symptom:** ``` NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 2.8.3' ``` **Cause:** macOS uses LibreSSL by default, but urllib3 v2 recommends OpenSSL. **Impact:** This is a **warning only**. API calls still work correctly. **Resolution (optional):** If you want to suppress the warning: ```bash pip3 install 'urllib3<2' ``` Or ignore it - it doesn't affect functionality. --- ## 秒点不足 (Insufficient Credits) **Symptom:** ``` [秒点不足] 您的秒点余额不足，无法继续操作。 请前往秒哒官网充值：https://www.miaoda.cn ``` Or within an error message: ``` 秒点不足，您可明日再来，或邀请新人立即获得秒点奖励。 ``` **Cause:** Your Miaoda account does not have enough 秒点 (Credits) to perform this operation (e.g., generating or publishing an app). **Resolution:** Visit the official Miaoda website to recharge your credits: **https://www.miaoda.cn** Log in → navigate to the recharge page → complete payment. Credits are credited immediately. --- # Error Handling Guidance Agents should handle the following situations: * generation requested before the platform indicates readiness * publish requested before generation has completed * missing `appId` or `conversationId` (use `get-context-id` to recover a lost `conversationId`) * interrupted trajectory stream * failed deployment status * incorrect or missing parameter values If workflow state is unclear, inspect the trajectory or application detail before taking the next action. **Pro Tips:** - Always check command `--help` when unsure about parameters - Use `--wait` flag with `publish` to simplify deployment - Save `appId` and `contextId` from first `chat` response - Only call `generate-app` once during initial creation - After generation, use `chat` directly for modifications **Application Sharing Rule (IMPORTANT)** - You must share your application **only using the production deployment URL** (after it has been published). Do not share the editor (development) URL. Production deployment URL format: ``` https://<app_id>.appmiaoda.com ``` - If the application has **not been published**, you must publish it before sharing with others. Example publish command: ``` python scripts/miaoda_api.py publish --app-id <app_id> --wait ``` - The project editor URL (`https://www.miaoda.cn/projects/<app_id>`) is **visible only to yourself**. Other users cannot access your editor environment. Never use the editor URL for sharing with others. Editor URL is for: - your own development - preview - internal editing only Editor URL must NOT be used for: - external/public sharing - distribution to others or end users


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)