Panel App Creator

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 默认都要在 panel-app.json 写清启动器元信息，让用户在 Panel Apps 列表中能快速识别它：

{
  "title": "番茄便签",
  "description": "番茄钟、任务清单和专注记录",
  "icon": "🍅",
  "entry": "index.html"
}

图标规则：

• 最简单优先在 panel-app.json.icon 放一个语义明确的 emoji 或 1-2 个短字符。
• 如果用户要求正式图片图标，再使用目录内相对资源路径，例如 assets/icon.svg。
• 不要省略图标；没有用户指定时，按应用主题选择一个克制、可识别的 emoji。
• 可以在 panel-app.json.icon 中使用相对资源路径。

窄侧栏优先布局

Panel App 默认打开在 NextClaw 右侧栏里，初始宽度通常较窄；用户可以把右侧栏拉宽，但不能假设一开始就是桌面宽屏。

• 默认按 320px-480px 窄面板优先设计，再逐步增强到宽屏。
• 主流程、核心按钮、表单和列表在窄宽度下必须完整可用，不横向溢出。
• 使用单列布局作为基础；宽屏时再用 CSS media query 升级为双列、网格或并排详情。
• 工具栏和筛选项在窄屏下允许换行、折叠或变成分段按钮，不要做依赖大宽度的顶部横排。
• 卡片、表格、图表要适配窄容器：长文本换行，表格优先改成列表/详情卡，图表使用 width: 100% 和稳定高度。
• 不使用固定桌面宽度容器，例如 width: 960px；容器应使用 max-width: 100%、min-width: 0、box-sizing: border-box。
• 验收时至少想象两种宽度：窄侧栏和用户拉宽后的面板。窄侧栏可用性优先于宽屏装饰性。

Panel Card 体验合同

只有当你已经判断这个 Panel App 适合以内联卡片展示时，才使用本节；不要把普通右侧面板、编辑器、管理页、大表格或多页工作流硬做成卡片。

适合 Panel Card 的形态：

• 天气卡片、汇率卡、计时器、计算器、checklist、picker、短表单、小 preview、小 dashboard。
• 用户希望“直接试一下”“快速看一下”“在当前对话里操作”，且核心交互能在有限高度内完成。

不适合 Panel Card 的形态：

• 长文档阅读、富文本/代码/Markdown 编辑器、文件浏览器、设置页、复杂管理台、大表格、多页持续工作区。

如果决定做 Panel Card，必须按 card-first 设计：

• 首屏 220px-420px 高度内必须看见核心价值，不要让用户先滚动才知道卡片能做什么。
• 横向优先：默认让信息沿宽度展开，宽度大于高度；常见结构是左侧主结果/核心状态，右侧短列表、次要指标或一个主操作。容器太窄时再折成单列。
• 禁止横向滚动、固定桌面宽度、大片空白和过高 hero。
• 设计上不要依赖 document 级内部滚动；允许 dropdown、select、短列表等控件级局部滚动。内容超出时改成摘要 + 展开，而不是把整张卡片设计成滚动页面。宿主可能用 iframe 滚动兜底旧内容，但不要把它当成默认体验。
• 只保留一个主操作，最多 2-3 个辅助操作；复杂配置、详情和历史记录交给展开后的 side panel。
• 必须有 loading、empty、error 状态；错误要可读，不要只在 console 里报错。
• 视觉要像精美卡片：清晰层级、克制色彩、足够留白、稳定高度、数字/状态突出、按钮和输入控件可点击。
• inline 宿主会在 URL 上追加 nextclawDisplayMode=card 和 nextclawPlacement=inline；检测到这些参数时，优先渲染 card-first 布局，不要继续使用完整页面布局。
• 普通 inline Panel App 展示必须输出 nextclaw-inline fenced JSON block；不要调用 show_panel_app 做 inline 展示。show_panel_app 只用于 side panel 即时预览，可传 App id 自动打开其 primaryPanelId，也可传从 nextclaw app list --json 获得的 Panel component id；如果实现过程中发现卡片空间不足，改用 side panel，不要勉强塞进 inline。

Service Actions

本节只说明 Panel App 如何声明和调用已存在或由 service-app-creator 设计出的 Service Action；不要在这里发明 Service App action 的 risk、inputSchema、command 或 server 实现。当前 Panel App 调用 Service Actions 推荐使用 window.nextclaw.serviceActions.*；client.serviceActions.* 暂时不作为推荐路径，因为它缺少旧 bridge 的授权确认和自动 retry 体验。

Panel App 调用 Service App 前，必须在 panel-app.json 的 actions 数组声明允许使用的 action：

{
  "title": "Markdown 管理器",
  "entry": "index.html",
  "actions": ["workspace-files.list", "workspace-files.read"]
}

action id 必须来自对应 service-app.json.actions：<service-app-id>.<tool-name>。service-app-id 不包含点号，tool name 可以包含点号。 不要发明 permissions.allowlist、serviceActions 等额外字段；当前标准字段就是 actions。

运行时通过宿主注入的 SDK 调用：

// Service App 调用必须在 try/catch 中，错误要给出明确用户反馈
try {
  if (window.nextclaw?.serviceActions?.invoke) {
    // invoke() 返回 action 的业务结果 payload，不需要读取 response.result
    const note = await window.nextclaw.serviceActions.invoke("workspace-notes.readNote", {
      path: "notes/today.md"
    });
    renderNote(note.content ?? "");
  } else {
    showError("当前环境不支持 Service Actions");
  }
} catch (e) {
  console.error("Service Action 调用失败:", e);
  showError("Service Action 调用失败，请检查授权和服务状态。");
}

list() 返回 action 数组，invoke() 已由宿主 SDK 解包，返回值就是 Service App tool 的业务 payload。不要写 response.actions、response.result、response.files 这种不确定访问：

const actions = await window.nextclaw.serviceActions.list();
renderActions(actions);

如果 action 返回 { files: [...] }，应写：

const payload = await window.nextclaw.serviceActions.invoke("workspace-files.list", {});
const files = payload.files ?? [];

错误提示要区分原因：bridge 不存在才说 Service Actions 不可用；调用抛错才说 Service Action 调用失败；返回结构不符合预期要说返回格式未识别，不要统一误报为 Service App 不可用。

不要在 Panel App 里伪造 caller、保存 token 或直接请求 Service Gateway；首次调用授权由宿主处理。 不要为了发现 action 在 Panel App 启动时自行触发后端探测；Service Actions 列表由宿主读取静态 manifest，运行时 discovery 由服务应用面板中的显式操作完成。