/panel-app-creator

name: panel-app-creator
description: Create or update the Panel UI component of a complete schema v2 NextClaw Mini App or an explicitly loose local Panel. Use after nextclaw-app-creator selects Panel-only or Panel + Service, or for right-side UI, Service Actions, Agent-powered panels, React/Vite panels, and App bridge capability questions.
description_zh: 创建或修改完整 schema v2 NextClaw Mini App 的 Panel UI 组件，或用户明确要求的 loose 本地 Panel。适用于 nextclaw-app-creator 判断为纯 Panel 或 Panel + Service 后，以及右侧 UI、Service Actions、Agent Panel、React/Vite Panel 与 App bridge 能力问题。

NextClaw Panel App Creator

当用户需要实现右侧面板 UI 时使用这个专项 skill。若用户表达的是“做一个 NextClaw 小应用”而不是明确只做 UI，先读取 `nextclaw-app-creator` 判断是否还需要 Service App。

如果 Panel App 要调用 `window.nextclaw.serviceActions.*`、`window.nextclaw.agent.*` 或 `window.nextclaw.client`，必须先读取 `references/panel-app-bridge-api.md`，并按该 reference 的运行时合同写代码。

本 skill 只拥有 Panel App UI、`panel-app.json`、bridge 调用和窄侧栏体验。它不拥有 `service-app.json`、`actions.*.risk`、MCP server、Service App command 或依赖安装规则。只要需要创建或修改 Service App 文件，必须立即读取 `service-app-creator`，不能凭 Panel App 文档猜后端 manifest 字段。

前端工程形态判断

先主动判断是否需要工程化 `React + Vite + TypeScript + Tailwind CSS + pnpm`，不要只在用户点名技术栈时才读取专项 skill。工程化推荐栈是一整套，缺一不可；如果不使用这整套，必须是轻量目录式静态面板、用户明确指定其它技术栈，或有清楚的环境约束理由。

• 适合工程化方案：AI 应用、对话/Agent Run、需要 App Client 类型、多个视图/组件、列表筛选排序、图表、复杂表单、异步加载状态、错误/空状态较多，或后续会持续维护的 Panel App。遇到这些信号，先读取 `panel-app-react-vite-creator`，并使用完整 `React + Vite + TypeScript + Tailwind CSS + pnpm` 栈。
• 适合轻量目录式：极小工具、一次性页面、纯展示/简单表单、少量内存状态、无明显组件拆分和构建收益的应用。不要为了“像工程”而引入 npm 工程。
• 用户明确要求 Vite、React、Tailwind、现代前端技术栈、工程化源码、可构建 Panel App，或希望用 pnpm 开发再交付静态产物时，必须读取 `panel-app-react-vite-creator`。

本 skill 仍负责最终 `panel-app.json`、bridge、Client SDK、Service Actions、窄侧栏体验和 `nextclaw app check` 验收规则；`panel-app-react-vite-creator` 只负责源码工程、Vite/Tailwind 配置、构建和静态 `.panel` 产物交付。

能力发现

当用户询问 Panel App 能做什么、能否接入 AI、能否读取会话/历史/Agent Run、能否上传资产或订阅事件时，必须说明 `window.nextclaw.client` 这类 App Client 能力，但不要把 Service Actions 迁移成 App Client 主路径。Service Actions 当前推荐继续使用旧 bridge，因为旧 bridge 拥有 Panel App 所需的授权确认和自动 retry 体验。

默认说明这些能力边界：

• Panel UI：不需要宿主授权的静态界面、本地状态、表单、列表、图表。
• `window.nextclaw.client`：声明 `"client": true` 并整体授权后同步可用，是 App Client projection，适合 sessions、agents、agentRuns、assets、events 等标准客户端能力。`client.serviceActions.*` 当前存在，但不要作为 Panel App Service Actions 推荐路径。
• Service App：本地文件、外部 API、本地命令等后端动作；Panel App 当前推荐通过旧 bridge `window.nextclaw.serviceActions.*` 调用，以保留授权确认、grant 和自动 retry。

`window.nextclaw.serviceActions.*` 是当前 Panel App 调用 Service Actions 的推荐入口，不要因为 App Client 里存在 `client.serviceActions.*` 就默认替代。`window.nextclaw.agent.*` 暂时保留为旧 Agent bridge；只有实际不想开启整体 client 授权、维护旧应用，或需要旧 Agent bridge 独有便利能力时才提它。

输出位置与包边界

先沿用 `nextclaw-app-creator` 已经确定的边界，不要把完整 Mini App 拆成散落 workspace 组件：

• 完整、可安装、可发布或长期维护的 schema v2 Mini App：写入包根 `panels/<panel-id>.panel/`，并由根 `manifest.json.components` 以 `{ "kind": "panel", "path": "panels/<panel-id>.panel" }` 引用。
• 用户明确只要临时、本机、不可发布的 loose Panel：写入 NextClaw workspace 的 `panels/<panel-id>.panel/`。默认 workspace 是 `~/.nextclaw/workspace`；能读取配置时以 `agents.defaults.workspace` 为准。
• `<panel-id>` 必须使用 kebab-case，目录以 `.panel` 结尾，例如 `todo-board.panel/`。

如果 Panel 属于 Portable 或 native-process Service 包，Panel 仍只是静态 UI 组件；不要把 Guest 源码、MCP server 或根权限字段塞进 `.panel` 目录。

文件形态

• 新建或重写 Panel App 时只使用目录式 Panel App；完整包和 loose Panel 使用同一种组件格式。
• 目录式 Panel App 必须包含 `panel-app.json` 和入口 HTML；不要求服务器部署，不创建 npm 项目，不运行构建工具。
• 需要后端能力时，必须由 `service-app-creator` 选择 Portable WASI 或 native-process，并先完成对应 Service 验证；Panel bridge 不按 runtime 分叉。
• Panel App 运行在 sandbox iframe 中，不能依赖 `localStorage`、`sessionStorage`、cookie 或 IndexedDB。轻量状态默认只放内存；需要保存时提供导出/导入 JSON，或配套 Service App / App Client 能力。
• `panel-app.json` 是标题、描述、图标、入口、Agent capabilities 和 Service actions 的唯一 manifest 事实源；不要把 NextClaw manifest 字段写到 HTML meta。

Sandbox 运行环境约束

Panel App 不是普通同源网页。宿主为了隔离应用，iframe sandbox 不包含 `allow-same-origin`，文档 origin 是 opaque / `null`。写代码时必须默认遵守：

• 不访问 `window.localStorage`、`window.sessionStorage`、`document.cookie`、IndexedDB，也不要使用会在初始化时自动触碰这些 API 的持久化库或状态插件。
• 不假设当前页面和宿主同源；不要读取父窗口 DOM、cookie、token 或宿主内部全局变量。
• 不直接持久化 bridge token、runtime token、session token 或授权状态。
• 同源 `/api/...` 请求只能用于宿主允许的 Panel App 运行时链路；优先使用 `window.nextclaw.client`、`window.nextclaw.serviceActions.*` 或 `window.nextclaw.agent.*`。
• 临时 UI 状态用普通 JS/React state；需要跨重新打开保存时，优先设计为 Service App action、App Client 标准能力，或显式导出/导入 JSON。

如果用户报告 `Failed to read the 'localStorage' property from 'Window': The document is sandboxed and lacks the 'allow-same-origin' flag`，根因通常是 Panel App 或其依赖在 sandbox 环境中访问了 Web Storage。修复方向是删除该持久化访问，而不是给 iframe 增加 `allow-same-origin`。

如果用户报告具体运行时报错，例如 `Illegal invocation`、sandbox storage、opaque origin、CORS 或 App Client 注入异常，先读取 `references/panel-app-runtime-troubleshooting.md`，按错误签名定位，不要把所有低频排障细节写进主流程。

目录式静态应用

适合需要后续扩展、持续维护、资源拆分或更清晰代码组织的静态应用：

<package-root-or-workspace>/panels/markdown-manager.panel/
  panel-app.json
  index.html
  app.js
  styles.css
  assets/icon.svg

`panel-app.json` 示例：

{
  "title": "Markdown 管理器",
  "description": "浏览、编辑和整理本地 Markdown 文件",
  "icon": "assets/icon.svg",
  "entry": "index.html",
  "capabilities": ["agent:generateObject"],
  "actions": ["workspace-files.list", "workspace-files.read"]
}

目录式规则：

• `id` 可以省略，系统会使用目录名作为身份；如果显式填写 `id`，必须等于目录名去掉 `.panel` 后的值，例如 `markdown-manager.panel` 对应 `markdown-manager`。
• `entry` 必须是目录内的 HTML 文件，通常是 `index.html`。
• 只有确实需要完整 NextClaw Client SDK 时才写 `"client": true`；不需要 client 的 Panel App 不要声明。
• `icon` 可以是 emoji、data URL、http/https/绝对路径，也可以是目录内相对资源路径，例如 `assets/icon.svg`。
• 相对 CSS、JS、图片路径可以直接写 `styles.css`、`app.js`、`assets/icon.svg`；NextClaw 会通过资源接口托管它们。
• 轻量目录式 Panel 不创建 `package.json`、`node_modules`、Vite 配置或后台 dev server。工程化源码按 `panel-app-react-vite-creator` 管理，最终 `.panel` 目录仍只放静态构建产物和 manifest。
• 创建或修改 Panel App 后不需要重启 NextClaw 宿主、server 或桌面应用。loose Panel 刷新“面板应用”列表或重新打开；包内 Panel 通过当前 `app dev/install` 生命周期重新加载。也可以使用面板右上角刷新内容。

启动器元信息

每个 Panel App 默认都要在 `pa