docs: add docs/adapters/medo-integration.md
This commit is contained in:
molecule-ai[bot]
GitHub
parent
58ba097395
commit
891f36fe09
173
content/docs/adapters/medo-integration.md
Normal file
173
content/docs/adapters/medo-integration.md
Normal file
@ -0,0 +1,173 @@
|
||||
# MeDo Integration Design — Molecule AI Hackathon (May 20 2026)
|
||||
|
||||
**Status:** Design — implementation pending operator sign-off on open questions (§5).
|
||||
**Scope:** How the molecule-dev team builds MeDo apps for the "Build with MeDo" hackathon.
|
||||
**Key constraint:** MeDo App Builder is an OpenClaw skill on ClawHub (`seiriosPlus/miaoda-app-builder`),
|
||||
not a REST API. All interactions go through natural-language messages to an OpenClaw workspace.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architecture Overview
|
||||
|
||||
```
|
||||
CEO / Canvas
|
||||
│ A2A task
|
||||
▼
|
||||
PM (claude-code)
|
||||
│ delegate_task_async → workspace: medo-builder
|
||||
▼
|
||||
MeDo Builder workspace [runtime: openclaw, skill: miaoda-app-builder]
|
||||
│ OpenClaw CLI → skill → api.miaoda.cn
|
||||
▼
|
||||
MeDo platform (app created / published → URL returned)
|
||||
│ result relayed via A2A event_queue
|
||||
▼
|
||||
PM → CEO
|
||||
```
|
||||
|
||||
The MeDo Builder workspace is a **dedicated OpenClaw-runtime workspace** inside the
|
||||
molecule-dev org with the Miaoda App Builder skill pre-installed. PM delegates natural-language
|
||||
app-build requests to it via `delegate_task_async` and polls for the result (5–8 min latency).
|
||||
|
||||
---
|
||||
|
||||
## 2. Installing the Miaoda App Builder Skill
|
||||
|
||||
### 2.1 API Key
|
||||
|
||||
The skill requires `MIAODA_API_KEY` (not `MEDO_API_KEY`).
|
||||
|
||||
> ⚠️ **Credential name mismatch**: the global platform secret is currently named `MEDO_API_KEY`.
|
||||
> The skill's frontmatter declares `primaryEnv: MIAODA_API_KEY`. The MeDo Builder workspace must
|
||||
> set `MIAODA_API_KEY` — either rename the global secret or add a workspace-level alias.
|
||||
> See open question §5-A.
|
||||
|
||||
Obtain the key from: **MeDo website → Settings → API Keys**. Keys do not expire, but generating
|
||||
a new one immediately invalidates the previous one.
|
||||
|
||||
### 2.2 Installation Query
|
||||
|
||||
OpenClaw installs skills by sending a natural-language install message to the agent.
|
||||
No CLI command is documented on ClawHub — send this message to the OpenClaw workspace on first boot:
|
||||
|
||||
```
|
||||
Install the Miaoda App Builder skill from ClawHub: seiriosPlus/miaoda-app-builder
|
||||
```
|
||||
|
||||
OpenClaw auto-downloads the skill, installs Python runtime deps (`requests`), and makes the skill
|
||||
available for subsequent messages.
|
||||
|
||||
### 2.3 Workspace Config Sketch (`org-templates/medo-builder/workspace.yaml`)
|
||||
|
||||
```yaml
|
||||
name: MeDo Builder
|
||||
role: Builds and publishes MeDo applications via the Miaoda App Builder OpenClaw skill
|
||||
runtime: openclaw
|
||||
tier: 2
|
||||
required_env:
|
||||
- MIAODA_API_KEY # TODO: resolve name vs platform secret MEDO_API_KEY (§5-A)
|
||||
- OPENROUTER_API_KEY # OpenClaw needs an LLM provider
|
||||
initial_prompt: |
|
||||
You are a MeDo App Builder. On startup:
|
||||
1. Install the Miaoda App Builder skill:
|
||||
"Install the Miaoda App Builder skill from ClawHub: seiriosPlus/miaoda-app-builder"
|
||||
2. Confirm installation succeeded.
|
||||
3. Wait for build tasks from PM via A2A.
|
||||
When you receive a build task, use natural language to instruct the skill:
|
||||
"Create a [description] app and publish it when done."
|
||||
App generation takes 5–8 minutes — poll the skill or wait for confirmation before reporting done.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. A2A Delegation Pattern (5–8 Min Latency)
|
||||
|
||||
App generation is asynchronous and slow. PM **must** use `delegate_task_async` + `check_task_status`
|
||||
rather than `delegate_task` (which has a shorter timeout and will return before the app is ready).
|
||||
|
||||
### 3.1 PM Delegation Flow
|
||||
|
||||
```python
|
||||
# Step 1: fire and forget
|
||||
task = await delegate_task_async(
|
||||
workspace_id="medo-builder-workspace-id",
|
||||
task="Build a restaurant reservation tool with online booking, menu display, "
|
||||
"and contact form. Publish when done and return the URL."
|
||||
)
|
||||
|
||||
# Step 2: poll every 60s (app takes 5–8 min)
|
||||
while True:
|
||||
status = await check_task_status(task_id=task["task_id"])
|
||||
if status["status"] in ("completed", "failed"):
|
||||
break
|
||||
await asyncio.sleep(60)
|
||||
|
||||
result_url = status.get("result") # MeDo app URL on success
|
||||
```
|
||||
|
||||
### 3.2 Invocation Patterns (verified from Baidu doc)
|
||||
|
||||
Natural-language messages the MeDo Builder workspace should accept from PM:
|
||||
|
||||
| Intent | Message to send to MeDo Builder workspace |
|
||||
|--------|-------------------------------------------|
|
||||
| List existing apps | `"Show me my apps"` |
|
||||
| Create + auto-publish | `"Create a [description] and publish it when done"` |
|
||||
| Create only | `"Create a [description]"` |
|
||||
| Modify existing | `"Add a search function to app [name/ID]"` |
|
||||
| Publish draft | `"Publish this app"` |
|
||||
| Status check | `"Is the app generation done yet?"` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Proposed Org Template — `org-templates/medo-builder/`
|
||||
|
||||
```
|
||||
org-templates/medo-builder/
|
||||
├── org.yaml ← minimal single-workspace org (not full team)
|
||||
├── medo-builder/
|
||||
│ ├── system-prompt.md ← MeDo Builder agent persona + delegation rules
|
||||
│ └── workspace.yaml ← runtime: openclaw, skill install, env
|
||||
```
|
||||
|
||||
**org.yaml sketch:**
|
||||
|
||||
```yaml
|
||||
name: MeDo Builder
|
||||
description: Single-workspace org for building MeDo apps (hackathon)
|
||||
defaults:
|
||||
runtime: openclaw
|
||||
tier: 2
|
||||
required_env: [MIAODA_API_KEY, OPENROUTER_API_KEY]
|
||||
|
||||
workspaces:
|
||||
- name: MeDo Builder
|
||||
role: Builds and publishes MeDo applications via Miaoda App Builder skill
|
||||
files_dir: medo-builder
|
||||
canvas: { x: 400, y: 300 }
|
||||
```
|
||||
|
||||
The medo-builder workspace is deployed **as a child of the molecule-dev PM** in the hackathon org,
|
||||
not as a standalone org. Full `org-templates/medo-builder/` implementation is Week 2 scope.
|
||||
|
||||
---
|
||||
|
||||
## 5. Open Questions (Operator Resolution Required)
|
||||
|
||||
| # | Question | Why it blocks |
|
||||
|---|----------|---------------|
|
||||
| 5-A | **Credential name**: platform secret is `MEDO_API_KEY`; skill expects `MIAODA_API_KEY`. Rename global secret or add workspace alias? | Workspace boot will fail with "MIAODA_API_KEY not set" |
|
||||
| 5-B | **Credit cost per app**: Baidu doc mentions a Credit System but content was not rendered. How many credits does create+generate+publish consume? Do we have enough for hackathon testing? | Budget planning |
|
||||
| 5-C | **Rate limits**: no rate-limit info in docs or ClawHub page. What's the max concurrent app generations per API key? | Parallelism planning |
|
||||
| 5-D | **Failure recovery**: what happens if the OpenClaw skill process crashes mid-generation (after Confirm & Generate, before Publish)? Is there a way to resume or check status by app ID? | Reliability design |
|
||||
| 5-E | **Submission format**: does the hackathon judge the published MeDo app URL, the Molecule AI org config, or both? | Determines whether we need a polished demo org or just a working app |
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Checklist (Weeks 1–3)
|
||||
|
||||
- [x] Week 1: This design doc (`docs/adapters/medo-integration.md`)
|
||||
- [ ] Week 1: Resolve §5-A (credential name) + obtain API key credits estimate
|
||||
- [ ] Week 2: `org-templates/medo-builder/` — full system-prompt + workspace.yaml
|
||||
- [ ] Week 2: Integration test — PM delegates one real app build end-to-end
|
||||
- [ ] Week 3: Polish demo org; rehearse submission flow; publish hackathon entry
|
||||
Loading…
Reference in New Issue
Block a user