@monkey-mini-app/dsh-mini-app 0.1.0 → 0.1.4

package/skills/monkey-mini-app/references/theme.md

@@ -0,0 +1,197 @@
+<!-- GENERATED by scripts/gen/skill/theme.mjs — do not hand-edit.
+     Source: packages/ui/src/styles/globals.css + packages/panel/src/themes.ts THEME_VAR_KEYS.
+     Refresh with `pnpm gen:skill`. -->
+
+# Theme tokens
+
+Every mini-app renders inside the host theme, so ** colours come from tokens, never from literals**. Hardcoded hex does not follow the palette the user picked and is the fastest way to make a generated app look wrong in dark mode.
+
+## Reach for a Tailwind class first
+
+The tokens below are exposed as Tailwind semantic utilities, which is what you should write:
+
+```tsx
+<div className="bg-card text-card-foreground border-border ring-ring">
+  <span className="text-muted-foreground">…</span>
+  <button className="bg-primary text-primary-foreground">…</button>
+</div>
+```
+
+Use the raw `var(--token)` only where a utility cannot reach: `style={{ … }}`, SVG `fill`/`stroke`, gradients, `color-mix()`, or a value you hand to a chart component.
+
+## Tokens
+
+
+### Surface
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--background` | `bg-background` | `oklch(1 0 0)` | `oklch(0.145 0 0)` |
+| `--card` | `bg-card` | `oklch(1 0 0)` | `oklch(0.205 0 0)` |
+| `--input` | `border-input` | `oklch(0.922 0 0)` | `oklch(1 0 0 / 15%)` |
+| `--popover` | `bg-popover` | `oklch(1 0 0)` | `oklch(0.205 0 0)` |
+| `--sidebar` | `bg-sidebar` | `oklch(0.985 0 0)` | `oklch(0.205 0 0)` |
+| `--sidebar-accent` | `bg-sidebar-accent · text-sidebar-accent` | `oklch(0.97 0 0)` | `oklch(0.269 0 0)` |
+| `--sidebar-border` | `bg-sidebar-border · text-sidebar-border` | `oklch(0.922 0 0)` | `oklch(1 0 0 / 10%)` |
+| `--sidebar-foreground` | `text-sidebar-foreground` | `oklch(0.145 0 0)` | `oklch(0.985 0 0)` |
+| `--sidebar-primary` | `bg-sidebar-primary · text-sidebar-primary` | `oklch(0.205 0 0)` | `oklch(0.488 0.243 264.376)` |
+| `--sidebar-ring` | `bg-sidebar-ring · text-sidebar-ring` | `oklch(0.708 0 0)` | `oklch(0.556 0 0)` |
+
+### Text
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--accent-foreground` | `text-accent-foreground` | `oklch(0.205 0 0)` | `oklch(0.985 0 0)` |
+| `--card-foreground` | `text-card-foreground` | `oklch(0.145 0 0)` | `oklch(0.985 0 0)` |
+| `--foreground` | `text-foreground` | `oklch(0.145 0 0)` | `oklch(0.985 0 0)` |
+| `--muted-foreground` | `text-muted-foreground` | `oklch(0.556 0 0)` | `oklch(0.708 0 0)` |
+| `--popover-foreground` | `text-popover-foreground` | `oklch(0.145 0 0)` | `oklch(0.985 0 0)` |
+| `--primary-foreground` | `text-primary-foreground` | `oklch(0.985 0 0)` | `oklch(0.205 0 0)` |
+| `--secondary-foreground` | `text-secondary-foreground` | `oklch(0.205 0 0)` | `oklch(0.985 0 0)` |
+| `--sidebar-accent-foreground` | `text-sidebar-accent-foreground` | `oklch(0.205 0 0)` | `oklch(0.985 0 0)` |
+| `--sidebar-primary-foreground` | `text-sidebar-primary-foreground` | `oklch(0.985 0 0)` | `oklch(0.985 0 0)` |
+
+### Brand & status
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--accent` | `bg-accent · text-accent` | `oklch(0.97 0 0)` | `oklch(0.269 0 0)` |
+| `--destructive` | `bg-destructive · text-destructive` | `oklch(0.577 0.245 27.325)` | `oklch(0.704 0.191 22.216)` |
+| `--muted` | `bg-muted · text-muted` | `oklch(0.97 0 0)` | `oklch(0.269 0 0)` |
+| `--primary` | `bg-primary · text-primary` | `oklch(0.205 0 0)` | `oklch(0.922 0 0)` |
+| `--secondary` | `bg-secondary · text-secondary` | `oklch(0.97 0 0)` | `oklch(0.269 0 0)` |
+
+### Lines & focus
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--border` | `border-border` | `oklch(0.922 0 0)` | `oklch(1 0 0 / 10%)` |
+| `--ring` | `ring-ring` | `oklch(0.708 0 0)` | `oklch(0.556 0 0)` |
+
+### Chart
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--chart-1` | `bg-chart-1 · text-chart-1` | `oklch(0.87 0 0)` | `oklch(0.87 0 0)` |
+| `--chart-2` | `bg-chart-2 · text-chart-2` | `oklch(0.556 0 0)` | `oklch(0.556 0 0)` |
+| `--chart-3` | `bg-chart-3 · text-chart-3` | `oklch(0.439 0 0)` | `oklch(0.439 0 0)` |
+| `--chart-4` | `bg-chart-4 · text-chart-4` | `oklch(0.371 0 0)` | `oklch(0.371 0 0)` |
+| `--chart-5` | `bg-chart-5 · text-chart-5` | `oklch(0.269 0 0)` | `oklch(0.269 0 0)` |
+
+### Radius, font & shadow
+
+| Token | Tailwind | Light | Dark |
+|---|---|---|---|
+| `--radius` | `—` | `0.625rem` | `inherits` |
+
+## Notes
+
+- Light and dark are **the same token names**; only the values change. Never branch on the mode yourself — `<html class="dark">` is set by the host.
+- The host also ships named palettes (`data-palette` + `data-theme`). They override the tokens above, which is exactly why literal colours must not appear in a mini-app.
+- Illustrations (`Illu*`) already map their accent to `--primary` and their greys to `--muted` / `--card`; do not restyle them.
+- Radius comes from `--radius` (`--radius-sm` … `--radius-4xl` are derived), so prefer `rounded-lg` / `rounded-xl` over a fixed `px`.
+
+32 tokens read from `packages/ui/src/styles/globals.css`.
+
+## Custom host theme file
+
+Only write this when the user **asks** for a named / branded palette. Default: pick a builtin in the panel theme pop and put **no hex** in the mini-app.
+
+A custom theme is a **host-global** CSS file (every app can select it). mini_app_edit cannot write it — it lives outside the app dir. Use the host file tools.
+
+```
+<dirname(runtimeRoot)>/themes/theme-<id>.css
+```
+
+runtimeRoot comes from mini_app_list. id is [a-z0-9-]+. Create the directory if needed. Header comment name: is the label in the picker.
+
+This file uses **short keys** (--bg), **not** the mini-app tokens above (--background). Copying the table into the file is silently ignored. Both light and dark :root[data-mode] blocks are required; missing bg / fg / primary in either mode means the file is skipped.
+
+Pairing rules (light/dark as one family, not an invert) -> [styling.md](styling.md). Worked example: docs/assets/themes/theme-crimson.css (do not paste its hex here). Reopen the panel theme pop after writing — it re-reads /api/palettes.
+
+| File variable | Required (both modes) |
+|---|---|
+| `--bg` | yes |
+| `--fg` | yes |
+| `--surface` | no (filled from defaults) |
+| `--surface-fg` | no (filled from defaults) |
+| `--border` | no (filled from defaults) |
+| `--muted` | no (filled from defaults) |
+| `--muted-fg` | no (filled from defaults) |
+| `--primary` | yes |
+| `--primary-fg` | no (filled from defaults) |
+| `--secondary` | no (filled from defaults) |
+| `--secondary-fg` | no (filled from defaults) |
+| `--accent` | no (filled from defaults) |
+| `--accent-fg` | no (filled from defaults) |
+| `--destructive` | no (filled from defaults) |
+| `--destructive-fg` | no (filled from defaults) |
+| `--ring` | no (filled from defaults) |
+| `--input` | no (filled from defaults) |
+| `--radius` | no (filled from defaults) |
+| `--shadow` | no (filled from defaults) |
+
+Skeleton (fill values; do not ship this empty file):
+
+```css
+/* name: Display name */
+:root[data-mode="light"] {
+  --bg: ;
+  --fg: ;
+  --surface: ;
+  --surface-fg: ;
+  --border: ;
+  --muted: ;
+  --muted-fg: ;
+  --primary: ;
+  --primary-fg: ;
+  --secondary: ;
+  --secondary-fg: ;
+  --accent: ;
+  --accent-fg: ;
+  --destructive: ;
+  --destructive-fg: ;
+  --ring: ;
+  --input: ;
+  --radius: ;
+  --shadow: ;
+}
+:root[data-mode="dark"] {
+  --bg: ;
+  --fg: ;
+  --surface: ;
+  --surface-fg: ;
+  --border: ;
+  --muted: ;
+  --muted-fg: ;
+  --primary: ;
+  --primary-fg: ;
+  --secondary: ;
+  --secondary-fg: ;
+  --accent: ;
+  --accent-fg: ;
+  --destructive: ;
+  --destructive-fg: ;
+  --ring: ;
+  --input: ;
+  --radius: ;
+  --shadow: ;
+}
+```
+
+## App-local palette (theme.css)
+
+A mini-app may ship its own palette: `theme.css` **in the app directory** (unlike the host-global file above, `mini_app_edit` / `mini_app_write` can write it).
+
+**Only when the style depends on the hue** — a look the app carries (a neon signage surface, a glass island whose sky is part of the layout). A plain CRUD / table / settings app must NOT ship one: it should follow whatever palette the user picked. The manifest has no theme block; the file's presence is the whole decision.
+
+Same contract as the host-global file: short keys, both `:root[data-mode]` blocks, a `/* name: … */` header. ui.tsx still never contains a colour literal.
+
+Behaviour in the panel:
+
+- With the file present the app uses it by default; the theme pop lists it under the current app, tagged **`本应用`**.
+- The user can pick a host palette (or **`跟随全局`**) for that app; that is stored per app and does not delete the file.
+- Light / dark still follows the host — the file carries both densities.
+- **First paint:** the host bakes the file's tokens into the app runner HTML when the request uses the local palette (`palette=__local__` or a bare `/app/:id` open). The panel's `mma-set-env` can still override later; without the bake, the first frame is the kit default near-white.
+
+Reuse the skeleton from *Custom host theme file* above verbatim — same keys, same two blocks — and write it to `<appDir>/theme.css`.

package/skills/monkey-mini-app/references/tools.md

@@ -1,21 +1,21 @@
-# ctx.tool 能调什么
+# `ctx.tool` — what can be called
 
-**不要把本文件当固定目录。** 工具集随 dsh profile / 插件 / MCP 变化。
+**Do not treat this file as a catalogue.** The tool set changes with the dsh profile, plugins and MCP servers.
 
-生成或改 `main.api.ts` **并且确实要用 `ctx.tool`** 时才：
+Only when you are writing or changing a `main.api.ts` **that really uses `ctx.tool`**:
 
-1. 调聊天工具 `mini_app_list_ctx_tools`（无参）
-2. 人类调试才 `curl -s http://127.0.0.1:17880/api/ctx-tools`
+1. Call the chat tool `mini_app_list_ctx_tools` (no arguments)
+2. For human debugging only: `curl -s http://127.0.0.1:17880/api/ctx-tools`
 
-返回 `{ count, tools: [{ name, description, schema }] }`。  
-`name` 就是 `ctx.tool(name, args)` 的第一参；`schema` 是参数形状（可能叫 parameters / inputSchema）。
+Result: `{ count, tools: [{ name, description, schema }] }`.
+`name` is the first argument of `ctx.tool(name, args)`; `schema` describes the parameters (may be called parameters / inputSchema).
 
-`args` 必须是普通 JSON 对象（`{}` 可以）。禁止 `{ input: "..." }`、`Date`、function、`AbortSignal`。无参工具传 `{}`。
+`args` must be a plain JSON object (`{}` is fine). Never `{ input: "..." }`, `Date`, functions or `AbortSignal`. Pass `{}` for tools that take nothing.
 
-## 写 app 时的优先级
+## Priority when writing an app
 
 1. `ctx.storage` / `ctx.http` / `ctx.bash` / `ctx.llm` / `ctx.system.metrics`
-2. 只有明确要复用 dsh 已有工具（读工作区文件等）才 `ctx.tool`
-3. MCP 用 `ctx.mcp("server__tool", args)`，不要 `{ input }`
+2. `ctx.tool` only when you clearly want to reuse an existing host tool (reading workspace files, etc.)
+3. MCP via `ctx.mcp("server__tool", args)` — never wrapped in `{ input }`
 
-`ctx.listTools()` 在后端同样返回这份快照。
+`ctx.listTools()` in the backend returns the same snapshot.

package/skills/monkey-mini-app/references/troubleshoot.md

@@ -1,12 +1,165 @@
-# 排错
-
-| 现象 | 先查 |
-|------|------|
-| `/api/apps` 404 | dsh 插件没起来或 port 不是 17880 |
-| `already been declared defineDashboard` | 旧 loader；当前应只从 require dashboard 来 |
-| 对象字面量/正则被编坏 | 旧 `compileAppSource` 乱剥 `: type` |
-| `llm unavailable` + 其实聊天能用 | 应走 `ctx.llm.stream`；或 POST `/api/llm-config` |
-| bash `policy.mode` undefined | 用本地 `bash -c` 路径，不要依赖坏的 sandbox policy |
-| UI 空白 / CDN | esm.sh 被拦 |
-| iframe 一条缝 | 不是 app 的问题，是 host iframe 高度 |
-| MCP 没反应 | args 不要包 `{ input }` |
+# Troubleshooting
+
+Match the **literal message** you got. `mini_app_reload` prefixes each `errors[]` entry with the failing layer; `mini_app_call` surfaces backend runtime messages; `mini_app_errors` surfaces **UI** runtime messages (the ones no compile step can see).
+
+## The UI is blank / wrong and the build was green
+
+That is expected: a bundle can compile and still throw at render. The loop is
+
+```
+mini_app_reload → mini_app_open → mini_app_errors → mini_app_view_eval
+```
+
+`mini_app_errors` returns `kind` + `message` + `componentStack`. `componentStack` names the component that threw, which a raw browser stack does not.
+
+| `kind` | Meaning | Typical cause |
+|---|---|---|
+| `render` | Thrown while React was rendering — caught by the app's error boundary | undefined name, bad props, a hook called conditionally |
+| `module` | The compiled bundle never evaluated | bad import, SDK missing, entry mismatch |
+| `uncaught` | Threw outside render | an event handler, a timer callback |
+| `async` | A promise rejected with no handler | `call()` without a `catch`, un-awaited fetch |
+
+If the ring is empty you probably never opened it — the hint says so. An app that renders **but looks wrong** is a `mini_app_view_eval` question, not an error question.
+
+### `mini_app_view_eval` did not answer
+
+| `view` | Meaning | Next step |
+|---|---|---|
+| `not-open` | no browser is attached, or nothing is showing this app | `mini_app_open`, then retry |
+| `runner-not-booted` | the iframe exists but its script never ran | `mini_app_errors` (a `module` error), then `mini_app_open` |
+| `pending` | your query is **still running** in a healthy view | raise `timeoutMs` (default 1500, max 8000) or return before awaiting. Nothing is broken and the user must not be told to reload — the host proved that by getting an answer to a trivial probe |
+| `stuck` | the script ran, then stopped answering, and even the trivial probe went unanswered — the thread really is blocked | a `while (true)` in your own `code` does this, and it wedges the panel page too: tell the user to reload the tab |
+| `live` + `ok: false` | the view is fine, **your query** failed | `error.line` / `error.source` point into your JS |
+
+More → [eval.md](eval.md).
+
+## "Did my change actually take effect?"
+
+`mini_app_reload` answers this in its own result, so you never have to infer it from a
+screenshot. **CSS is part of the contract, not an afterthought:** a successful reload always
+drops the in-memory build of the API module, the UI bundle **and** the app's Tailwind CSS
+(`appCss: "dropped"`), then tells every attached panel to re-fetch. There is no "CSS somehow
+stayed" path — if `caches.appCss` is not `"dropped"`, something else is wrong.
+
+```json
+{ "ok": true, "caches": { "uiBundle": "dropped", "appCss": "dropped", "autogen": "removed", "views": "reload sent to 1 attached panel" } }
+```
+
+- `views: "no panel attached — nothing was showing this app"` → the browser never re-fetched,
+  because there was nothing to re-fetch. Call `mini_app_open`.
+- `views: "not sent (compile failed)"` → fix the compile; the memos still went, so the next
+  attempt cannot inherit the old bytes.
+- **`cleanCaches` defaults to `true` on the tool** — on-disk build output (`.autogen/`, cached
+  bundles) is purged and rebuilt, so a stale Tailwind artifact cannot survive a normal reload.
+  Pass `cleanCaches: false` only when you deliberately want to keep those files (faster, but
+  you are trusting the disk cache). The underlying `AppsManager.reload` API still defaults to
+  `false` when called without opts; only the tool flips the default.
+
+To prove the frame is a *new document*, compare `performance.timeOrigin` across the reload —
+the refreshed URL carries a cache-buster, so a real reload always changes it:
+
+```
+mini_app_view_eval({ appId, code: "return performance.timeOrigin" })   →  reload  →  ask again
+```
+
+Unchanged means it never reloaded. Then assert your *content* too: query a string only the new
+code can print, rather than looking at the panel.
+
+## `LLM_JSON_INVALID` / `LLM_RETRY_EXHAUSTED`
+
+`ctx.llm(prompt, { schema })` retried and still got nothing parseable. The message lists every
+attempt (`err.attempts`: `kind` `json` | `transport`, `error`, `bytes`, `head`) — read it before
+changing anything, the shape of the bad answer *is* the diagnosis:
+
+| The attempts say | Meaning | Fix |
+|---|---|---|
+| `transport`, 0 bytes every time | the model never answered | provider/config, not your prompt |
+| `json` with `head` = prose ("Here is the JSON:") | the schema instruction lost to the chatty system prompt | shorten `system`, put constraints in `schema` |
+| `json` with `head` = truncated object, `bytes` suspiciously round | hit the output ceiling | pass a bigger `maxTokens`, or ask for fewer items |
+| `json` with `head` = reasoning text | the budget died before the answer | bigger `maxTokens`; a reasoning model needs headroom |
+
+Never wrap `ctx.llm` in a hand-rolled salvage parser: the retries and the evidence are already the
+same thing, one layer down.
+
+## `mini_app_reload` → `errors[i]` prefix
+
+| Message | Root cause | Next step |
+|---|---|---|
+| `appId must be reverse-DNS (e.g. com.example.todo)` | Bad appId shape | Use `com.<you>.<thing>`; no Chinese, spaces or underscores |
+| `app not registered; call mini_app_register({ appId, files })` | Nothing on disk for that id | `mini_app_register` first — do not `edit` |
+| `app not found: <id>` | Same, or a typo in the id | Check `mini_app_list` |
+| `manifest: manifest missing <key>` | Missing `id` / `name` / `version` / `entry` | All four are required; `entry` is usually `"ui.tsx"` |
+| `manifest: manifest is not valid JSON` | JSON syntax (trailing comma, comment) | `manifest.json` allows **no** comments or trailing commas |
+| `manifest: manifest id is not a valid AppId` | `manifest.id` differs from appId or is malformed | They must be equal |
+| `missing main.api.ts` | No backend entry | Create `main.api.ts` (a single `list` method is fine) |
+| `main.api: …` | Backend compile failed / relative import unresolved | Read the tail; see "backend messages" below |
+| `main.api: "x()" is called but never defined or imported` | Typo or missing import in the backend | Fix the name; reload re-checks |
+| `ui: …` | UI bundle failed | Read the tail; see "UI messages" below |
+| `ui: JSX component <X /> is not defined or imported` | Used a component you never imported | Add it to the `@monkey-mini-app/ui` import |
+| `ui: hook "useX" is called but not imported` | Hook used without `import { useX } from "react"` | Import it — hooks are never globals |
+| `shared: …` | Undefined name in `shared/**` | Fix in `shared/` — both sides import from there |
+| `ui compiler not wired` | The host has no UI compiler attached | Host install problem, not an app problem ("Host-side" section) |
+| `commit: …` | Compiled fine, the auto-commit failed | Changes are on disk; commit explicitly with `mini_app_history_commit` |
+
+### `committed.status` after a reload
+
+| `status` | Meaning | Do |
+|---|---|---|
+| `committed` | A new commit was made | — |
+| `clean` | Nothing changed since your last `mini_app_edit` (it auto-commits) | Nothing — this is normal |
+| `skipped` | Compile failed, so nothing was committed | Fix `errors[]` first |
+| `failed` | Commit itself errored (`reason`) | `mini_app_history_commit`, or check the git dir |
+
+## Runtime / smoke-test messages
+
+| Message | Root cause | Fix |
+|---|---|---|
+| `Method not found: <m>` | `call("<m>")` is not a key of `api` | Align with `defineApp({ api })` keys (case-sensitive) |
+| `main.api must export defineApp({ name, description, api })` | Missing `export default defineApp({...})` | Add the default export |
+| `defineApp requires name and description` | One of them is missing | Provide both |
+| `defineApp.api must be an object` | `api` written as a function or array | `api: { async list(ctx) {…} }` |
+| `backend cannot import '<spec>'. Install it first: mini_app_install(...)` | The app needs that library but it is not in its own `node_modules` | Run `mini_app_install({ appId, packages: [{ name: "<spec>" }] })`, then `mini_app_reload`. Do **not** move the import into `ui.tsx` |
+| `backend cannot import '<spec>' (no package.json)` | Same, and nothing has ever been installed for this app | `mini_app_install` creates the manifest — never hand-write `package.json` |
+| `backend cannot import '<spec>': it resolves outside this app's node_modules` | The app is reaching the plugin's/repo's dependency tree | Reinstall the package into the app; a host dependency is not an app dependency |
+| `Cannot find package '<x>'`-style npm failure from `mini_app_install` | Typo, no network, or the name is not on the registry | Fix the name/version; report the npm stderr to the user rather than inventing a substitute |
+| `backend cannot import '<spec>': ui/** is UI-only` | Backend reached into the UI tree | Move the shared logic to `shared/**` |
+| `backend import escapes app dir: <spec>` | Backend imported `../` past the app root | Keep every import inside the app dir |
+| `unsafe relative path: <rel>` | Path contained `..` or was absolute | `mini_app_*` `path` values are app-relative |
+| `register requires manifest.json` | `files` had no manifest | Add it |
+| `cancelled` | The user pressed stop and `ctx.signal` fired | Expected behaviour; long jobs must wire it (see ctx.md) |
+
+## UI compile messages
+
+| Message | Root cause | Fix |
+|---|---|---|
+| `UI cannot import main.api.ts; use useApp() from @monkey-mini-app/ui` | UI imported the backend | Go through `call(method, args)` |
+| `UI cannot import api/**: "<spec>"` | UI reached into the backend tree | Move the shared logic to `shared/**` |
+| `UI import escapes the app dir: "<spec>"` | `../` pointed at a sibling app or outside | Keep every import inside the app dir |
+| `missing ui entry (ui.tsx / App.tsx)` | `manifest.entry` points at a file that isn't there | Match `entry` to the real file |
+| `Failed to resolve import "<pkg>"` | Imported an npm package the app directory does not have | UI: `react` / `@monkey-mini-app/ui` / in-app relative paths. React, lucide and recharts already ship inside the SDK |
+
+## It compiles but looks wrong
+
+| Symptom | Check first | Note |
+|---|---|---|
+| A class did nothing | Whether the class name is a **complete literal** | Tailwind scans source text: `` `bg-${x}-500` `` generates **no CSS and no error**. Full names only → [styling.md](styling.md) |
+| Colours wrong in dark mode | Any hardcoded hex | Use tokens → [theme.md](theme.md); the user's palette rewrites token values |
+| Custom theme file does not appear | Wrote `--background` or only one mode | File keys are `--bg` / `--fg` / `--primary` in **both** light and dark → [theme.md](theme.md) *Custom host theme file*; reopen the theme pop |
+| A node rendered to nothing | Its box and its classes, from the view | `mini_app_view_eval({ appId, code: 'return mma.$$("#root *").filter(n => !n.getBoundingClientRect().width).map(mma.selector)' })` — usually a class that never compiled, or a condition that never matched |
+| A token looks unset | The **computed** value, not the class name | `const cs = getComputedStyle(mma.$(".x")); return { color: cs.color, bg: cs.backgroundColor };` → [styling.md](styling.md) |
+| Panel still shows the old app after a fix | It should have refreshed on its own (`app:reload`) | If the browser was not attached to `/api/events`, use the panel's reload button |
+| The iframe is a thin strip | **Not an app problem** | Host iframe height; refresh or reopen the panel |
+| Blank page, no console error | Whether `#root.boot` gets cleared | That is load art only; it must be gone before mount |
+| Editor missing / code not highlighted | `CodeEditor` `CodeBlock` `DiffViewer` | They fetch CodeMirror / shiki from `esm.sh` on demand; on a blocked network they degrade. **Do not** `pnpm add` them and do not `import @codemirror/*` / `shiki` |
+| Rich text editor looks plain | `RichTextEditor` | It is a local contentEditable editor — no CDN, no dependency |
+| `ctx.http` times out | `http: timeout` / `http: only http/https` / `http: response too large` | Pass `timeout`; http/https only; page or sample large payloads |
+| `ctx.llm` says no model service / stream empty | Model not configured | A human configures it in settings or `POST /api/llm-config`; app code stays `await ctx.llm(...)` |
+| `ctx.tool` reports no tool service | This profile has no tools | Use `storage` / `http` / `bash`; check first with `mini_app_list_ctx_tools` |
+| MCP does nothing | Args wrapped as `{ input }` | Pass the business object directly |
+
+## Host side (human debugging — not the app's fault)
+
+| Symptom | Handling |
+|---|---|
+| `:17880/api/apps` returns 404 | Plugin not started, or the port is not 17880 — see [test.md](test.md) |
+| `@monkey-mini-app/... dist not found` | Host install is missing build output; a maintainer runs `node scripts/build/ui.mjs && node scripts/build/sdk.mjs` |

package/skills/monkey-mini-app/templates/README.md

@@ -1,24 +1,36 @@
-# Mini-app 模板指引
+# Mini-app templates
 
-每个模板是不同的**参考场景**：一个「布局原型」× 一条「能力轴」，告诉你**什么时候抄它、它主要教什么**。先看这张表定位，再决定细读哪个模板（避免把 7 个都读一遍）。
+Each template is a **product facade**: one interaction loop × one default Look. Use the table to find the closest starting point — real apps routinely take pieces from several.
 
-| 模板 | 一句话 | 什么时候抄它 | 主要教你 |
+Looks (style recipes, not apps) live in [`../references/looks/`](../references/looks/index.md). Open them only when the user names a style.
+
+| Template | Loop | Copy it when | What it teaches |
 |---|---|---|---|
-| [minimal](./minimal/) | 最简可运行的骨架 | 刚起步 / 连通检查 / 只要个能跑的壳 | `defineDashboard` + `useDashboardApi().call` 一次往返 + `AppShell`/`PageHeader` 骨架 |
-| [todo](./todo/) | 本地 CRUD + 筛选 + 派生统计 | 记本地数据、要增删改查+状态过滤 | `ctx.storage` + 一屏固定内滚 + `FilterBar` + `storage.table()` 多表 |
-| [insights](./insights/) | 联网数据 → 模型摘要（长任务） | 外部数据+智能提炼、会慢 | `ctx.http` + `ctx.llm({schema})` + **采样/进度/`ctx.signal` 取消**（`scan`/`scanStatus` 轮询） |
-| [monitor](./monitor/) | 本机指标实时看板 | 监控/大盘/图表/KPI | `ctx.system.metrics()` + `ctx.bash`(只做 host 没有的 ps/df) + 轮询隐藏即停 |
-| [review](./review/) | 代码/文本对比 + 用例表格 | 审阅/diff/用例、要编辑回写 | `DiffViewer`(original/modified) + `CodeEditor` + `DataGrid` 列筛/排序 + 写回 |
-| [agentrun](./agentrun/) | 让模型干多步活并展示过程 | 需要 `ctx.agent`（**唯一**示范）+ 取消/进度 | `ctx.agent` + `onEvent`→storage→UI 轮询 + 模块级 `AbortController` 取消 |
-| [jira](./jira/) | 复杂业务仿真（多视图+状态机+AI 辅助） | 工单/Jira/项目管理类、多视图、要 AI | `Kanban`+`DataGrid` 双视图 + 详情 `Sheet` 编辑 + 状态色板 + `ctx.llm` 生成用户可确认草稿 |
-
-## 怎么用
-
-1. **只读你需要的模板**，不要全读。按「一句话 / 什么时候抄它」定位。
-2. 模板内带 `// ⭐ 关键：...` 的注释是**教学点** —— 扫注释就能抓到要点（如 `ctx.agent`、`storage.table`、`ctx.signal` 取消、`DiffViewer` 的 original/modified、`StatusBadge` 认小写状态）。
-3. **通用约定**（每个都遵守，不分模板）：
-   - UI 只 `import`：`react` / `@monkey-mini-app/ui` / `@monkeyagent/host` / `./lib`。禁止其它 npm（app 目录无 node_modules）。
-   - 图标：`import { Icon } from "@monkey-mini-app/ui"` → `<Icon.HelpCircle />`（常用子集见 [../references/icons.md](../references/icons.md)）。空状态插图：`import { IlluServerStatus } from "@monkey-mini-app/ui"`。
-   - 唯一访问后端的入口：`useDashboardApi().call(method, args)`，method 必须是 `defineDashboard({ api })` 的键。
-   - 布局 `AppShell`（可选 `sidebar`/`header`）+ `PageHeader`（`title`/`description`/`actions`）。
-   - 列表/看板/表格数据用 `key` 字段做增删改定位。
+| [minimal](./minimal/) | one `call` | Starting out / connectivity | `defineApp` + `useApp().call` + `AppShell` skeleton. No Look. |
+| [today](./today/) | open → see my screen → one record | Personal home, "what first" | `ctx.storage` + `storage.table()` + `ListDetail` + glass-island |
+| [board](./board/) | items move in 2D status | Pipelines, "who is blocked" | `Kanban` + `DataGrid` + `Sheet` + `ctx.llm` confirm. aurora-bento |
+| [radar](./radar/) | I trigger → wait → read (cancel) | Fetch sources, write a brief, long job | `ctx.push`/`on` names in `shared/events.ts`; long job in `api/`; brief in `ui/`. editorial |
+| [sheets](./sheets/) | file in, grid work | `.xlsx` / column stats / compare | **`mini_app_install`** (`exceljs`) + lodash aggregates + `DataGrid`. desk-split |
+| [runner](./runner/) | the UI *is* the run | Multi-step model work | `ctx.agent` + `streamTo` + SSE. terminal |
+| [chores](./chores/) | named buttons, no model | One button on this machine | `ctx.bash` → stdout in `Terminal`. Not a prompt. |
+| [watch](./watch/) | numbers move by themselves | Live status, stop when hidden | `ctx.system.metrics()` + polling that stops when hidden. tape. **Reveal** |
+
+## Templates that need a library
+
+`sheets/` ships **no** `package.json`. After `mini_app_register`, install first, then reload:
+
+```
+mini_app_install({ appId: "com.example.sheets", packages: [{ name: "exceljs" }] })
+mini_app_reload({ appId: "com.example.sheets" })
+```
+
+## How to use them
+
+1. **Start from the closest loop** (the table). Open others when the app spans loops.
+2. **Lift the pattern, not the file.** Comments marked `// ⭐` are the teaching points.
+3. Looks are optional. Kit components first; Tailwind for the distinctive grammar. No hex.
+4. **Three facades ship a `theme.css`** (`today`, `runner`, `chores`) because their look is
+   hue-dependent — the panel shows it as a palette tagged `本应用` and the user can switch away.
+   The other facades follow the host palette on purpose. Do not add one to a plain CRUD app
+   ([../references/theme.md](../references/theme.md) → *App-local palette*).
+5. Visible copy in these samples is Chinese. Instructions and comments are English.

package/skills/monkey-mini-app/templates/{jira → board}/main.api.ts

@@ -1,9 +1,9 @@
-import { defineDashboard } from "@monkeyagent/dashboard";
+import { defineApp } from "@monkey-mini-app/api";
 
-// ⭐ 关键：列表/看板数据项的"key"字段很重要 —— 拖拽/更新都用它定位（还记得 idKey="key" 的坑）。
-//         Jira 仿真：改状态/负责人/优先级、加评论、AI 记工时。
+// ⭐ key: the "key" field of list/kanban items matters — drag & update both locate by it (remember the idKey="key" pitfall).
+//         Jira simulation: change status/assignee/priority, add comments, AI worklog.
 export type Issue = {
-  key: string;                       // 例如 "BUG-104"
+  key: string;                       // e.g. "BUG-104"
   type: "Story" | "Task" | "Bug" | "Epic";
   summary: string;
   status: "To Do" | "In Progress" | "Done" | "Blocked";
@@ -36,15 +36,15 @@ function touch(i: Issue): Issue {
   return { ...i, updatedAt: Date.now() };
 }
 
-export default defineDashboard({
-  name: "Jira 看板",
-  description: "看板/表格双视图 · 状态与评论编辑 · AI 记工时",
+export default defineApp({
+  name: "阶段看板",
+  description: "看板/表格双视图 · 状态与评论 · AI 记一笔",
   api: {
     async list(ctx) {
       const issues = await load(ctx);
       return { issues };
     },
-    // ⭐ 关键：乐观更新 + 持久化 —— 拖拽/改字段先改内存再落库；UI 拿 key 定位
+    // ⭐ key: optimistic update + persistence — drag/field edits change memory first, then save; the UI locates items by key
     async update(ctx, args?: { key?: string; patch?: Partial<Issue> }) {
       const key = args?.key;
       if (!key) throw new Error("缺少 key");
@@ -74,14 +74,14 @@ export default defineDashboard({
       await save(ctx, next);
       return next.find((i) => i.key === key);
     },
-    // 状态汇总：按 status 计数（简约色板用）
+    // status summary: counts per status (for the compact palette)
     async summary(ctx) {
       const issues = await load(ctx);
       const byStatus: Record<string, number> = {};
       for (const i of issues) byStatus[i.status] = (byStatus[i.status] || 0) + 1;
       return { byStatus, total: issues.length };
     },
-    // ⭐ 关键：AI 记工时 —— 用 ctx.llm(schema) 把 issue 的近期变动生成一条 worklog 草稿，用户确认后再存
+    // ⭐ key: AI worklog — ctx.llm(schema) turns the issue's recent activity into a worklog draft; saved only after the user confirms
     async worklogDraft(ctx, args?: { key?: string }) {
       const key = args?.key;
       const issues = await load(ctx);
@@ -95,7 +95,7 @@ export default defineDashboard({
       const parsed = JSON.parse(raw) as { note?: string };
       return { note: String(parsed.note ?? "").trim() || issue.summary };
     },
-    // 确认后存成一条评论（worklog 前缀）
+    // after confirmation, saved as a comment (with the worklog prefix)
     async logWork(ctx, args?: { key?: string; note?: string; minutes?: number }) {
       const key = args?.key;
       const minutes = Number(args?.minutes ?? 0) || 0;

package/skills/monkey-mini-app/templates/board/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "com.example.board",
+  "name": "阶段看板",
+  "description": "多条东西按阶段往前推 · 看板/表格 · AI 记一笔",
+  "version": "0.1.0",
+  "entry": "ui.tsx",
+  "acronym": "KB"
+}

package/skills/monkey-mini-app/templates/board/theme.css

@@ -0,0 +1,46 @@
+/* name: 极光便当 */
+/* Look-owned palette: the ground is an aurora, so the hue IS the identity. Light is the
+   indigo-violet field (A1), dark the graphite aurora-green (A2) — the lab picked the best
+   side of each; a palette file has two blocks, so that is legal and reads intentional. */
+:root[data-mode="light"] {
+  --bg: #c9cdf1;
+  --fg: #20213a;
+  --surface: #ffffff;
+  --surface-fg: #20213a;
+  --border: #c2c6e8;
+  --muted: #dfe2f5;
+  --muted-fg: #565a7e;
+  --primary: #6d5ae0;
+  --primary-fg: #ffffff;
+  --secondary: #e2e4f6;
+  --secondary-fg: #20213a;
+  --accent: #e9e3fb;
+  --accent-fg: #20213a;
+  --destructive: #c0392b;
+  --destructive-fg: #ffffff;
+  --ring: #6d5ae0;
+  --input: #c2c6e8;
+  --radius: 16px;
+  --shadow: rgba(35, 30, 90, 0.35);
+}
+:root[data-mode="dark"] {
+  --bg: #0e1512;
+  --fg: #dff2e8;
+  --surface: #141d19;
+  --surface-fg: #dff2e8;
+  --border: #1e2c25;
+  --muted: #101f19;
+  --muted-fg: #6f9784;
+  --primary: #3ee39a;
+  --primary-fg: #06140d;
+  --secondary: #16241d;
+  --secondary-fg: #dff2e8;
+  --accent: #13281f;
+  --accent-fg: #dff2e8;
+  --destructive: #ff6b5e;
+  --destructive-fg: #14060a;
+  --ring: #3ee39a;
+  --input: #1e2c25;
+  --radius: 16px;
+  --shadow: rgba(0, 0, 0, 0.55);
+}