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

package/skills/monkey-mini-app/references/contracts/timeline.md

@@ -0,0 +1,24 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# Timeline
+
+`import { Timeline, TimelineItem } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/products/timeline.tsx` · products
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `items` | `TimelineItem[]` | ✓ |  |
+
+## Types
+
+### `TimelineItem`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `description` | `string \| undefined` |  |  |
+| `id` | `string` | ✓ |  |
+| `time` | `string \| undefined` |  |  |
+| `title` | `string` | ✓ |  |

package/skills/monkey-mini-app/references/contracts/timezone-select.md

@@ -0,0 +1,27 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# TimezoneSelect
+
+`import { TimezoneSelect, ZoneInfo } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/composites/timezone-select.tsx` · composites
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `className` | `string \| undefined` |  |  |
+| `onChange` | `((zone: string) => void) \| undefined` |  |  |
+| `value` | `string \| undefined` |  |  |
+
+## Types
+
+### `ZoneInfo`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `city` | `string` | ✓ |  |
+| `id` | `string` | ✓ |  |
+| `offset` | `string` | ✓ |  |
+| `region` | `string` | ✓ |  |
+| `search` | `string` | ✓ |  |

package/skills/monkey-mini-app/references/contracts/transfer.md

@@ -0,0 +1,24 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# Transfer
+
+`import { Transfer, TransferItem } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/composites/transfer.tsx` · composites
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `items` | `TransferItem[]` | ✓ |  |
+| `onChange` | `((value: string[]) => void) \| undefined` |  |  |
+| `value` | `string[] \| undefined` |  |  |
+
+## Types
+
+### `TransferItem`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `id` | `string` | ✓ |  |
+| `label` | `string` | ✓ |  |

package/skills/monkey-mini-app/references/contracts/tree-view.md

@@ -0,0 +1,23 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# TreeView
+
+`import { TreeView, TreeNode } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/products/tree-view.tsx` · products
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `nodes` | `TreeNode[]` | ✓ |  |
+
+## Types
+
+### `TreeNode`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `children` | `TreeNode[] \| undefined` |  |  |
+| `id` | `string` | ✓ |  |
+| `label` | `string` | ✓ |  |

package/skills/monkey-mini-app/references/contracts/trend-card.md

@@ -0,0 +1,26 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# TrendCard
+
+`import { TrendCard, TrendPoint } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/blocks/trend-card.tsx` · blocks
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `data` | `TrendPoint[]` | ✓ |  |
+| `delta` | `string \| undefined` |  |  |
+| `title` | `string` | ✓ |  |
+| `trend` | `"up" \| "down" \| "flat" \| undefined` |  |  |
+| `value` | `ReactNode` | ✓ |  |
+
+## Types
+
+### `TrendPoint`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `label` | `string` | ✓ |  |
+| `value` | `number` | ✓ |  |

package/skills/monkey-mini-app/references/contracts/user-picker.md

@@ -0,0 +1,24 @@
+<!-- generated by scripts/generate-skill.mjs — do not edit -->
+
+# UserPicker
+
+`import { UserPicker, UserOption } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/composites/user-picker.tsx` · composites
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `onChange` | `((id: string) => void) \| undefined` |  |  |
+| `users` | `UserOption[]` | ✓ |  |
+| `value` | `string \| undefined` |  |  |
+
+## Types
+
+### `UserOption`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `id` | `string` | ✓ |  |
+| `name` | `string` | ✓ |  |

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

@@ -0,0 +1,137 @@
+# RunContext `ctx`
+
+每个 `api.*` / `onMount` / `onUnmount` 都拿到同一个 `ctx`。
+
+## 总是可用
+
+| API | 返回 | 说明 |
+|-----|------|------|
+| `ctx.appId` | string | 当前小程序 reverse-DNS id |
+| `ctx.appDir` | string | 当前小程序绝对目录（`runtime/apps/<appId>`） |
+| `ctx.storage.get(key)` | value 或 `null` | `storage/main.storage.json` |
+| `ctx.storage.set(key, value)` | | JSON 可序列化 |
+| `ctx.storage.delete` / `clear` | | |
+| `ctx.storage.table(name)` | 同样 API | `{name}.storage.json`，name=`[A-Za-z0-9_-]` |
+| `ctx.state` | object | 内存，与 defineDashboard.state 同一引用 |
+| `ctx.config` | `{ theme, palette, chatLanguage, hostPort, llm }` | 只含本 Host 配置（设置页 / 顶栏配色可改），**不是** dsh 设置 dump。`theme`=`light`/`dark`；`palette`=`default`/`ocean`/`violet`/`slate`（默认/海蓝/青紫/石墨） |
+| `ctx.credentials` | `Record<string,string>` | 声明过的密钥 |
+| `ctx.log(...args)` | | console |
+| `ctx.signal` | AbortSignal 或 undefined | 当前调用的取消信号（chat 点「停止」时 abort）。长任务在批次/循环间 `if (ctx.signal?.aborted) throw new Error("cancelled")`，`sleep` 也传它 |
+| `ctx.push(method, params)` | | 常为 no-op |
+| `ctx.system.metrics()` | os 快照 | |
+
+## Host 能力
+
+| API | 签名 | 返回 | Fallback | 失败 |
+|-----|------|------|----------|------|
+| `http(url)` / `http(url, opts)` | opts：`method?` `headers?` `query?` `body?` `timeout?`（默认 8s）。自动组合 `ctx.signal`（停止即中断） | `{ ok, status, headers, text, json }`。`json` 仅当 Content-Type 含 json 且能 parse，否则 `null`。HTTP 4xx/5xx **不 throw**，看 `ok`/`status`。只允许 http/https | Node `fetch` | `http: timeout` / `http: only http/https` / `http: response too large` / `http: …` |
+| `bash(command)` | string | `{ stdout, stderr, exitCode }` | 本地 `bash -c` 120s/8MB → dsh `shell.run`。给本机命令用，**不要** `curl` | `bash unavailable` |
+| `tool(name, args)` | args **普通对象**，禁止 `{input}` | **string** | dsh tools | `tool: ctx.tools not available` |
+| `mcp(name, args?)` | 不要 `mcp_` 前缀 | string | `tool(name)` 再 `tool("mcp__"+name)`。dsh 登记名是 `mcp__<server>__<tool>`，例如 `ctx.mcp("everything__echo", { message: "hi" })` | 第一次错误 |
+| `llm(prompt, opts?)` | 见下方 **ModelCallOptions** | **string** | dsh `llm.stream` | `llm: no dsh model service` / `llm stream empty` |
+| `agent(goal, opts?)` | **ModelCallOptions** + `onEvent?`（见下） | **string** | dsh one-shot agent（与聊天 session 隔离）；可用工具循环。不要用多次 `ctx.llm` 假装 agent | `agent: … unbound` / `empty result` / `cancelled` |
+
+```ts
+const r = await ctx.http("https://example.com/api", {
+  method: "GET",
+  headers: { accept: "application/json" },
+  query: { q: "hi" },
+  timeout: 8000,
+});
+if (!r.ok) throw new Error("HTTP " + r.status);
+const data = r.json ?? JSON.parse(r.text);
+```
+
+POST：`ctx.http(url, { method: "POST", body: { a: 1 } })`（对象会 JSON 编码）。RSS/HTML 用 `r.text`。
+
+### ModelCallOptions（`llm` / `agent` 共用最小集合）
+
+```ts
+type ModelCallOptions = {
+  provider?: string;   // 默认跟 dsh 当前模型；可不传
+  model?: string;
+  system?: string;
+  schema?: object;     // JSON Schema；要对象时用，再 JSON.parse 返回值
+  maxTokens?: number;
+  signal?: AbortSignal; // api 调用里通常已有 ctx.signal，可省略
+};
+
+// llm
+await ctx.llm(prompt, opts?: ModelCallOptions): Promise<string>
+
+// agent = ModelCallOptions + onEvent + maxIterations + cwd
+await ctx.agent(goal, opts?: ModelCallOptions & {
+  /** Soft turn cap: host cancels after this many completed turns. */
+  maxIterations?: number;
+  onEvent?: (ev: AgentEvent) => void;
+  /**
+   * Working dir mode (default "process").
+   * app = 当前小程序目录；process = dsh 启动目录；temp = 临时目录；custom = 配 cwd 绝对路径。
+   * 只传 cwd 路径 ⇒ 视为 custom。cwd + 非 custom 的 cwdType ⇒ 报错。
+   */
+  cwdType?: "app" | "process" | "temp" | "custom";
+  cwd?: string; // 绝对路径；custom 必填，或单独传
+}): Promise<string>
+```
+
+路由：`opts.provider/model` → dsh 当前 `agent-default-model` → `deepseek-official` / `deepseek-v4-flash`。不必改 `host.json`。
+
+### `opts.schema`（llm + agent）
+
+软约束「只回 JSON」+ 剥 markdown；**返回仍是 string**，`JSON.parse`。例子 → [llm-json.md](llm-json.md)。提示宜短，约束交给 schema。
+
+### `opts.onEvent`（仅 agent）— 过程事件完整形状
+
+返回值仍是最终 string；`onEvent` 只观测过程。UI 用 storage 轮询即可：
+
+```ts
+type AgentEvent =
+  | { type: "status"; status: "running" | "idle" }
+  | { type: "text-delta"; text: string }
+  | { type: "tool"; phase: "start" | "end"; name: string; args?: unknown; result?: unknown }
+  | { type: "turn"; phase: "start"; turn: number }
+  | { type: "turn"; phase: "end"; turn: number; reason?: { kind: string; error?: unknown; reason?: unknown } }
+  // reason.kind 常见：completed | blocked | error | aborted | max-tokens
+  | { type: "error"; message: string }
+  | { type: "done"; text: string };
+
+const trace = [];
+const text = await ctx.agent("根据材料给出洞察", {
+  schema: { type: "object", properties: { summary: { type: "string" } }, required: ["summary"] },
+  onEvent: (ev) => {
+    trace.push(ev);
+    void ctx.storage.set("agentTrace", trace);
+  },
+});
+const insight = JSON.parse(text);
+```
+
+`ctx.agent` 与用户聊天 session 隔离（ephemeral，跑完 dispose）。
+
+
+## 列出当前 tool
+
+**仅当 main.api.ts 会调用 `ctx.tool` 时**才调聊天工具 `mini_app_list_ctx_tools`。纯 storage / http / bash / llm 的 app 不要调。
+
+后端也可用 `ctx.listTools()`。不要假设 read/write/bash 一定存在或参数名固定。
+
+## 长耗时任务：必须采样 + 响应取消
+
+多源抓取 × LLM 分析这类任务，**不要全量跑**：
+
+- **采样走通流程**：10 个 RSS 取 2 个有代表性的源（如主站 + 高热度站）；批次只跑 1 批（如最热的 16~24 条）验证全链路；其余用启发式兜底。告诉用户「先跑样例，全量可后续加」。
+- **批次上限**：LLM 分析批次数硬上限（如 `MAX_BATCHES = 2`），避免单次调用跑 10 分钟。
+- **必须响应取消**：循环/批次/sleep 处检查 `ctx.signal`：
+  ```ts
+  async function sleep(ms: number, signal?: AbortSignal) {
+    return new Promise((resolve) => {
+      if (signal?.aborted) return resolve();
+      const t = setTimeout(resolve, ms);
+      signal?.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+    });
+  }
+  // 批次间
+  if (ctx.signal?.aborted) throw new Error("cancelled");
+  await sleep(400, ctx.signal);
+  ```
+- **异步进度**：长任务提供 `scanStatus`/`progress` 类方法（写入 storage），UI 轮询；`scan` 本身 fire-and-forget 立即返回「已启动」。

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

@@ -0,0 +1,10 @@
+# 版控
+
+每 app 一份轻量历史（类git）。
+
+- `mini_app_history_commit` 全量保留，不要靠清快照 ≈ git commit
+- list commits 是树 ≈ git log
+- revert ≈ 从某 commit **分叉**，旁支还在
+- 单分支，不要做 merge
+
+生成或改完 app 后都 commit 一次，方便 AI 误操作后找回。

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

@@ -0,0 +1,83 @@
+# Icons
+
+`import { Icon } from "@monkey-mini-app/ui"` — 一个 `Icon` 命名空间（来自 lucide）。`Icon.<Name>` 接受**任意 lucide React 组件名**（大驼峰）。下面是**常用推荐子集**，按用途分组、一句话告诉你什么时候用；没列到的按 lucide 命名规则也能用（如 `Icon.IconName`）。
+
+```tsx
+import { Icon } from "@monkey-mini-app/ui";
+<Icon.Search size={16} strokeWidth={2} />
+```
+
+## 操作
+| 名字 | 何时用 |
+|---|---|
+| `Plus` / `Minus` | 添加 / 减少 |
+| `X` | 关闭、清除 |
+| `Check` / `CheckCircle2` | 完成、成功 |
+| `Trash2` | 删除 |
+| `Pencil` / `PenLine` | 编辑、重命名 |
+| `Copy` / `Clipboard` | 复制 |
+| `Download` / `Upload` | 下载 / 上传 |
+| `RefreshCw` | 刷新、重新拉取 |
+| `Send` | 提交、发送 |
+| `ExternalLink` | 打开新窗口 |
+| `Link` | 复制链接 |
+
+## 导航
+| 名字 | 何时用 |
+|---|---|
+| `ChevronRight` / `ChevronLeft` | 进入/展开 或 返回 |
+| `ChevronDown` / `ChevronUp` | 折叠/展开 |
+| `ChevronsUpDown` | 可排序 |
+| `ArrowUpRight` | 外链、跑分增长 |
+| `ArrowLeftRight` / `ArrowUpDown` | 切换、传输 |
+| `MoreHorizontal` | 更多菜单 |
+
+## 状态
+| 名字 | 何时用 |
+|---|---|
+| `Bell` / `BellOff` | 通知 / 免打扰 |
+| `Eye` / `EyeOff` | 显示 / 隐藏敏感值 |
+| `Info` | 信息提示 |
+| `AlertCircle` / `TriangleAlert` | 警告 |
+| `Loader2` / `LoaderCircle` | 加载中（配 animate） |
+| `HelpCircle` | 帮助 |
+| `BadgeCheck` | 已验证、通过 |
+| `Star` / `Heart` | 收藏 / 喜欢 |
+
+## 内容 & 输入
+| 名字 | 何时用 |
+|---|---|
+| `Search` | 搜索框 |
+| `Filter` | 筛选 |
+| `SlidersHorizontal` | 高级筛选、设置参数 |
+| `CalendarDays` | 日期 |
+| `Clock` / `History` | 时间 / 历史 |
+| `Tag` | 标签、分类 |
+| `File` / `FileText` | 文件 / 文档 |
+| `Folder` / `FolderOpen` | 目录 |
+| `Image` | 图片 |
+| `List` / `ListOrdered` | 列表 / 有序列表 |
+| `Hash` | 编号、话题 |
+| `Code2` / `Terminal` | 代码 / 命令行 |
+
+## 系统 & 监控
+| 名字 | 何时用 |
+|---|---|
+| `Activity` / `Zap` | 实时活动、性能 |
+| `Gauge` / `BarChart3` | 指标、大盘 |
+| `Server` / `Database` | 服务、数据存储 |
+| `HardDrive` / `Cpu` / `MemoryStick` | 磁盘 / CPU / 内存 |
+| `Cloud` / `Network` / `Globe` / `Wifi` | 网络、云、外部服务 |
+| `TrendingUp` / `TrendingDown` | 涨 / 跌 |
+| `GitBranch` / `GitMerge` / `GitPullRequest` | git 分支、合并、PR |
+| `Rocket` | 发布、上线 |
+
+## 媒体 / 用户 / 设置
+| 名字 | 何时用 |
+|---|---|
+| `Play` / `Pause` | 播放 / 暂停 |
+| `Music2` / `Video` / `Mic` / `Camera` | 音视频 |
+| `Settings` / `Settings2` | 设置 |
+| `Mail` / `MessageSquare` | 邮箱 / 评论 |
+| `Lock` / `Unlock` / `KeyRound` | 权限、密钥 |
+| `Home` | 首页 |

package/skills/monkey-mini-app/references/llm-json.md

@@ -0,0 +1,69 @@
+# 结构化 JSON（`ctx.llm` / `ctx.agent` + `opts.schema`）
+
+需要对象/数组时走这条，不要自己试各种「请只输出 JSON」。
+
+## 契约（llm 与 agent 对齐）
+
+| | 说明 |
+|--|------|
+| 入口 | `ctx.llm(prompt, { schema })` **或** `ctx.agent(goal, { schema })` |
+| 返回 | **始终是 string**；给了 `schema` 时宿主会要求模型只回 JSON，并尽量剥掉 markdown/前言 |
+| App 侧 | `JSON.parse(raw)`；失败就 throw，不要当业务文案展示 |
+| 不是什么 | **不是**默认每次结构化；**不是** provider 原生 JSON mode / schema 校验重试（二期可加强） |
+
+`schema` 用普通 JSON Schema 对象（至少 `type` + `properties` / `items`）。提示宜短：任务说清楚 + 把约束交给 `schema`，不必再堆「不要解释」。
+
+## `ctx.llm` 例子
+
+完整 RSS + `./lib` + schema 见 `templates/insights/`。
+
+```ts
+const SCHEMA = {
+  type: "object",
+  properties: {
+    headline: { type: "string" },
+    bullets: { type: "array", items: { type: "string" } },
+  },
+  required: ["headline", "bullets"],
+};
+
+const raw = await ctx.llm("写一条中文 headline，以及恰好 3 条中文 bullets。不要前言。", {
+  schema: SCHEMA,
+});
+const digest = JSON.parse(raw);
+```
+
+## `ctx.agent` 例子
+
+适合「多步工具/推理后再收成结构化结果」。仍返回 string。若还要过程时间线，同一调用加 `onEvent`（形状见 [ctx.md](ctx.md)）。
+
+```ts
+const INSIGHT_SCHEMA = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    risks: { type: "array", items: { type: "string" } },
+    nextStep: { type: "string" },
+  },
+  required: ["summary", "risks", "nextStep"],
+};
+
+const raw = await ctx.agent(
+  "根据下面材料给出对独立开发者的洞察：风险列表 + 下一步建议。\n" + materials,
+  { schema: INSIGHT_SCHEMA },
+);
+const insight = JSON.parse(raw);
+await ctx.storage.set("insight", insight);
+return insight;
+```
+
+与 llm 一样：`schema` 可选；自然语言最终句不必传 `schema`。
+
+## 宿主实际做了什么（实现提示）
+
+1. `withJsonInstruction`：把 schema 写进约束（llm → stream 的 `system`；agent → one-shot followup 文本）  
+2. 模型生成  
+3. `coerceSchemaJson`：去掉 \`\`\`json 围栏 / 前言，尽量抽出 `{…}` / `[…]`  
+4. App `JSON.parse`
+
+校验失败时 **不会**自动重试；该 throw 就 throw，让 UI 显示错误。

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

@@ -0,0 +1,30 @@
+# Loader
+
+Host 在服务端即时编译：**后端**用 sucrase 编译 `main.api.ts` / `lib/*.ts`；**前端 UI** 用 esbuild-wasm 把 `ui.tsx` 连同用到的组件打包成单个 ESM bundle（tree-shake，按 app 裁剪组件库）。
+
+## 后端（main.api.ts / lib/*.ts）
+
+- `import { defineDashboard } from "@monkeyagent/dashboard"`
+- `import { foo } from "./lib/foo"`（也可 `./components/...`）
+- TypeScript 随意（sucrase：参数类型、`{ title: string }`、`catch (e: any)` 都可以）
+- `export default defineDashboard(...)`
+- `lib/` 里 `export function` / `export const` / `export async function`
+
+## 前端（ui.tsx）
+
+- `import { Button, DataGrid, ... } from "@monkey-mini-app/ui"` —— 组件库（已内置图标/图表/编辑器依赖，不要额外 import npm 包）
+- `import { useDashboardApi } from "@monkeyagent/host"` —— host 注入的 hook，只返回 `{ call }`
+- `import { useState } from "react"` —— React 19（host 注入）
+- `import { foo } from "./lib/foo"` —— 相对 app 内文件，随 bundle 一起打包
+- 布局用 Tailwind classes（`flex flex-col gap-3` 等）
+
+## 禁止（编译即报错，不要绕）
+
+- npm 包：`recharts`、`lucide-react`、`rss-parser`、`openai`、`node-fetch`…（组件库已内置）
+- Node 内置：`fs`、`http`、`path`…
+- 逃出 app 目录的 `../` 出界（前端 `./lib` 同理）
+- UI `import main.api.ts`（要数据走 `call`）
+
+抓网页用 `ctx.http("https://…", { timeout: 8000 })`，看 `r.ok` / `r.text` / `r.json`；解析写在 `./lib`。本机命令才 `ctx.bash`。
+
+改 `ui.tsx` / `main.api.ts` / `lib/*.ts` 会按 mtime 重新编译。RSS + lib 完整例子见 `templates/insights/`。

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

@@ -0,0 +1,30 @@
+# Host 冒烟调试（人类用）
+
+这是 **Host `:17880` 调试**，不是小程序里的 `ctx.http`。
+
+冒烟请用聊天工具 **`mini_app_call({ appId, method, args })`**，不要 bash/curl。
+
+Base: `http://127.0.0.1:17880`（插件 apply 时已 listen，打开小程序面板会预热）。仅在人类调试时用 curl。
+
+| 方法 | 路径 | Body | 结果 |
+|------|------|------|------|
+| GET | `/api/apps` | | `{ apps: [{ id, name, version }] }` |
+| GET | `/api/ctx-tools` | | `{ count, tools: [{ name, description, schema }] }` |
+| POST | `/api/call` | `{ appId, method, args }` | `{ ok: true, value }` 或 `{ ok: false, error }` |
+| GET | `/app/:id` | | runner HTML |
+| GET | `/api/app/:id/ui/entry.js` | | per-app UI bundle（编译缓存） |
+| GET | `/ui.css` | | @monkey-mini-app/ui 全局样式 |
+| DELETE | `/api/app/:id` | | `{ ok, appId }` |
+| GET/POST | `/api/host-config` | POST `{ hostPort, theme, palette, … }` | Host 设置 |
+| GET/POST | `/api/llm-config` | POST `{ provider, model }` | 写入 `runtime/llm.json` |
+
+```bash
+curl -s http://127.0.0.1:17880/api/apps
+curl -s http://127.0.0.1:17880/api/call \
+  -H 'content-type: application/json' \
+  -d '{"appId":"com.example.todo","method":"list","args":{"filter":"all"}}'
+```
+
+CORS 已开。改 `main.api.ts` 后直接再 curl，不必开浏览器。
+
+小程序后端抓外网 API：用 `ctx.http`，见 [ctx.md](ctx.md)。

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

@@ -0,0 +1,21 @@
+# ctx.tool 能调什么
+
+**不要把本文件当固定目录。** 工具集随 dsh profile / 插件 / MCP 变化。
+
+生成或改 `main.api.ts` **并且确实要用 `ctx.tool`** 时才：
+
+1. 调聊天工具 `mini_app_list_ctx_tools`（无参）
+2. 人类调试才 `curl -s http://127.0.0.1:17880/api/ctx-tools`
+
+返回 `{ count, tools: [{ name, description, schema }] }`。  
+`name` 就是 `ctx.tool(name, args)` 的第一参；`schema` 是参数形状（可能叫 parameters / inputSchema）。
+
+`args` 必须是普通 JSON 对象（`{}` 可以）。禁止 `{ input: "..." }`、`Date`、function、`AbortSignal`。无参工具传 `{}`。
+
+## 写 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 }`
+
+`ctx.listTools()` 在后端同样返回这份快照。

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

@@ -0,0 +1,12 @@
+# 排错
+
+| 现象 | 先查 |
+|------|------|
+| `/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 }` |

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

@@ -0,0 +1,24 @@
+# Mini-app 模板指引
+
+每个模板是不同的**参考场景**：一个「布局原型」× 一条「能力轴」，告诉你**什么时候抄它、它主要教什么**。先看这张表定位，再决定细读哪个模板（避免把 7 个都读一遍）。
+
+| 模板 | 一句话 | 什么时候抄它 | 主要教你 |
+|---|---|---|---|
+| [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` 字段做增删改定位。

package/skills/monkey-mini-app/templates/agentrun/main.api.ts

@@ -0,0 +1,78 @@
+import { defineDashboard } from "@monkeyagent/dashboard";
+
+// ⭐ 关键：ctx.agent 是「让模型干一个多步活」的入口，返回最终 string。
+//         过程事件经 onEvent 观测（status/tool/turn/text-delta/done），写进 storage 让 UI 轮询。
+//         取消：用模块级 AbortController（app 模块只加载一次，var 可存）；页面隐藏/停止时不空跑。
+type Step = { phase: string; name?: string; turn?: number; text?: string; at: number };
+
+let currentAbort: AbortController | null = null;
+
+function pushStep(ctx, step: Step) {
+  void ctx.storage.set("step", step);
+}
+async function addStep(ctx, step: Step) {
+  const run = (await ctx.storage.get("run")) || { goal: "", status: "idle", steps: [], result: "", startedAt: 0 };
+  run.steps = [...(run.steps || []), step];
+  await ctx.storage.set("run", run);
+}
+
+export default defineDashboard({
+  name: "任务执行器",
+  description: "让模型干一个多步活，实时展示过程，可取消",
+  api: {
+    async runStatus(ctx) {
+      return (await ctx.storage.get("run")) || { goal: "", status: "idle", steps: [], result: "", startedAt: 0 };
+    },
+
+    // 启动：立即返回，后台跑 agent；progress 靠 storage + UI 轮询
+    async start(ctx, args?: { goal?: string }) {
+      const goal = String(args?.goal ?? "").trim();
+      if (!goal) throw new Error("请输入目标");
+      currentAbort?.abort();
+      const ac = new AbortController();
+      currentAbort = ac;
+      const run = { goal, status: "running", steps: [], result: "", startedAt: Date.now() };
+      await ctx.storage.set("run", run);
+      await ctx.storage.set("step", { phase: "status", text: "running", at: Date.now() });
+
+      void ctx.agent(goal, {
+        signal: ac.signal,
+        maxIterations: 12,
+        onEvent: (ev) => {
+          // ⭐ 关键：onEvent 只是观测过程，返回值仍是最终 string。这里把每个事件落 storage。
+          if (ev.type === "tool") void addStep(ctx, { phase: "tool", name: ev.name, at: Date.now() });
+          else if (ev.type === "turn") void addStep(ctx, { phase: "turn", turn: ev.turn, at: Date.now() });
+          else if (ev.type === "text-delta") setText(ctx, ev.text);
+          else if (ev.type === "done") void addStep(ctx, { phase: "done", at: Date.now() });
+          else if (ev.type === "error") void addStep(ctx, { phase: "error", text: ev.message, at: Date.now() });
+        },
+      })
+        .then(async (text) => {
+          const cur = (await ctx.storage.get("run")) || run;
+          await ctx.storage.set("run", { ...cur, status: "done", result: text.slice(-4000), steps: cur.steps || [] });
+          if (currentAbort === ac) currentAbort = null;
+        })
+        .catch(async (cause) => {
+          const msg = String((cause as Error)?.message || cause);
+          const cur = (await ctx.storage.get("run")) || run;
+          await ctx.storage.set("run", { ...cur, status: "error", result: msg, steps: cur.steps || [] });
+          if (currentAbort === ac) currentAbort = null;
+        });
+      return { ok: true, started: true };
+    },
+
+    async cancel(ctx) {
+      currentAbort?.abort();
+      currentAbort = null;
+      const cur = (await ctx.storage.get("run")) || { goal: "", status: "idle", steps: [], result: "", startedAt: 0 };
+      await ctx.storage.set("run", { ...cur, status: "cancelled" });
+      return { ok: true };
+    },
+  },
+});
+
+async function setText(ctx, delta: string) {
+  const cur = (await ctx.storage.get("run")) || { goal: "", status: "running", steps: [], result: "", startedAt: Date.now() };
+  cur.result = (cur.result || "") + delta;
+  await ctx.storage.set("run", { ...cur, steps: cur.steps || [] });
+}