@leeoohoo/ui-apps-devkit 0.1.1 → 0.1.3

package/README.md

@@ -1,76 +1,84 @@
-# ChatOS UI Apps DevKit
-
-一个可通过 npm 安装的 DevKit，用来：
-
-- 生成 UI Apps 插件工程（脚手架）
-- 在本地沙箱里运行/调试 `module` 应用（Host API mock）
-- 校验 `plugin.json` 与路径边界
-- 打包/安装到本机 ChatOS（`~/.deepseek_cli/chatos/ui_apps/plugins`）
-
-## 安装
-
-```bash
-npm i -g @leeoohoo/ui-apps-devkit
-```
-
-或直接用 npx：
-
-```bash
-npx @leeoohoo/ui-apps-devkit chatos-uiapp --help
-```
-
-## 快速开始
-
-```bash
-chatos-uiapp init my-first-uiapp
-cd my-first-uiapp
-npm install
-npm run dev
-```
-
-## 沙箱能力
-
-- 模拟 `module mount()` 与 `host.*` API
-- 右上角 Theme 切换（light/dark/system），用于测试 `host.theme.onChange` 与样式响应
-- Inspect 面板展示 `host.context` 与 `--ds-*` tokens
-
-## 模板
-
-```bash
-chatos-uiapp init --list-templates
-chatos-uiapp init my-app --template basic
-chatos-uiapp init my-app --template notepad
-```
-
-- `basic`：最小可运行骨架（含 `host.chat.*` / `ctx.llm.complete()` 示例）
-- `notepad`：完整示例应用（文件夹/标签/搜索/后端持久化）
-
-完成开发后：
-
-```bash
-npm run validate
-npm run pack
-npm run install:chatos
-```
-
-## 生成项目结构（约定）
-
-生成的工程里，**可安装产物**固定在 `plugin/` 目录：
-
-```
-my-first-uiapp/
-  docs/                # 协议文档（随工程分发）
-  chatos.config.json   # DevKit 配置（pluginDir/appId）
-  plugin/              # 直接导入/安装到 ChatOS 的插件目录
-    plugin.json
-    backend/           # (可选) Electron main 进程后端
-    apps/<appId>/      # module 前端 + AI 贡献（MCP/Prompt）
-```
-
-## CLI
-
-- `chatos-uiapp init <dir>`：生成工程
-- `chatos-uiapp dev`：启动本地运行沙箱（支持文件变更自动重载）
-- `chatos-uiapp validate`：校验 manifest 与路径边界
-- `chatos-uiapp pack`：打包 `.zip`（用于 ChatOS 导入）
-- `chatos-uiapp install`：复制到本机 ChatOS 用户插件目录
+# ChatOS UI Apps DevKit
+
+一个可通过 npm 安装的 DevKit，用来：
+
+- 生成 UI Apps 插件工程（脚手架）
+- 在本地沙箱里运行/调试 `module` 应用（Host API mock）
+- 校验 `plugin.json` 与路径边界
+- 打包/安装到本机 ChatOS（用户插件目录：`<stateDir>/ui_apps/plugins`；`stateDir = <stateRoot>/<hostApp>`）
+
+## 安装
+
+```bash
+npm i -g @leeoohoo/ui-apps-devkit
+```
+
+或直接用 npx：
+
+```bash
+npx @leeoohoo/ui-apps-devkit chatos-uiapp --help
+```
+
+## 快速开始
+
+```bash
+chatos-uiapp init my-first-uiapp
+cd my-first-uiapp
+npm install
+npm run dev
+```
+
+## 沙箱能力
+
+- 模拟 `module mount()` 与 `host.*` API
+- 右上角 Theme 切换（light/dark/system），用于测试 `host.theme.onChange` 与样式响应
+- Inspect 面板展示 `host.context` 与 `--ds-*` tokens
+- 右上角 `AI Config` 可配置 `API Key / Base URL / Model ID`，用于在沙箱内调用真实模型并测试应用 MCP（需配置 `ai.mcp`）
+
+## 模板
+
+```bash
+chatos-uiapp init --list-templates
+chatos-uiapp init my-app --template basic
+chatos-uiapp init my-app --template notepad
+```
+
+- `basic`：最小可运行骨架（含 `host.chat.*` / `ctx.llm.complete()` 示例）
+- `notepad`：完整示例应用（文件夹/标签/搜索/后端持久化）
+
+完成开发后：
+
+```bash
+npm run validate
+npm run pack
+npm run install:chatos
+```
+
+## MCP 依赖（必读）
+
+- ChatOS 导入插件时会排除 `node_modules/`，MCP server 运行时无法读取随包依赖。
+- MCP server 只要引入第三方依赖（如 `@modelcontextprotocol/sdk`、`zod`），就必须在 build 阶段 **bundle 成单文件**，并在 `plugin.json` 的 `ai.mcp.entry` 指向 bundle 产物。
+- 如果 MCP 启动报错 `Cannot find package '@modelcontextprotocol/sdk'`，说明依赖未被 bundle 或 vendoring 到插件目录。
+- 或者完全使用 Node 内置模块，或把依赖源码 vendoring 到插件目录内。
+
+## 生成项目结构（约定）
+
+生成的工程里，**可安装产物**固定在 `plugin/` 目录：
+
+```
+my-first-uiapp/
+  docs/                # 协议文档（随工程分发）
+  chatos.config.json   # DevKit 配置（pluginDir/appId）
+  plugin/              # 直接导入/安装到 ChatOS 的插件目录
+    plugin.json
+    backend/           # (可选) Electron main 进程后端
+    apps/<appId>/      # module 前端 + AI 贡献（MCP/Prompt）
+```
+
+## CLI
+
+- `chatos-uiapp init <dir>`：生成工程
+- `chatos-uiapp dev`：启动本地运行沙箱（支持文件变更自动重载）
+- `chatos-uiapp validate`：校验 manifest 与路径边界
+- `chatos-uiapp pack`：打包 `.zip`（用于 ChatOS 导入）
+- `chatos-uiapp install`：复制到本机 ChatOS 用户插件目录

package/bin/chatos-uiapp.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { runCli } from '../src/cli.js';
-
-await runCli(process.argv);
-
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2));

package/package.json

@@ -1,25 +1,28 @@
-{
-  "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.1",
-  "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
-  "license": "MIT",
-  "type": "module",
-  "scripts": {
-    "test": "node --test"
-  },
-  "bin": {
-    "chatos-uiapp": "bin/chatos-uiapp.js"
-  },
-  "files": [
-    "bin/**",
-    "src/**",
-    "templates/**",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@leeoohoo/ui-apps-devkit",
+  "version": "0.1.3",
+  "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "chatos-uiapp": "bin/chatos-uiapp.js"
+  },
+  "files": [
+    "bin/**",
+    "src/**",
+    "templates/**",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -1,53 +1,53 @@
-import { cmdInit } from './commands/init.js';
-import { cmdValidate } from './commands/validate.js';
-import { cmdPack } from './commands/pack.js';
-import { cmdInstall } from './commands/install.js';
-import { cmdDev } from './commands/dev.js';
-
-import { parseArgs } from './lib/args.js';
-
-function printHelp() {
-  // Keep it short; detailed docs live in README and generated project.
-  // eslint-disable-next-line no-console
-  console.log(`chatos-uiapp
-
-Usage:
-  chatos-uiapp init <dir> [--template <name>] [--force] [--plugin-id <id>] [--name <name>] [--app-id <appId>] [--version <semver>]
-  chatos-uiapp init --list-templates
-  chatos-uiapp dev [--port 4399] [--app <appId>] [--plugin-dir <path>]
-  chatos-uiapp validate [--plugin-dir <path>]
-  chatos-uiapp pack [--out <zipPath>] [--plugin-dir <path>]
-  chatos-uiapp install [--host-app chatos] [--state-dir <path>] [--plugin-dir <path>]
-
-Examples:
-  chatos-uiapp init my-app
-  chatos-uiapp init my-app --template notepad
-  chatos-uiapp init --list-templates
-  chatos-uiapp dev --port 4399
-  chatos-uiapp install --host-app chatos
-`);
-}
-
-export async function runCli(argv) {
-  const { positionals, flags } = parseArgs(argv);
-  const cmd = String(positionals[0] || '').trim();
-
-  if (!cmd || cmd === 'help' || cmd === '--help' || flags.help) {
-    printHelp();
-    return;
-  }
-
-  try {
-    if (cmd === 'init') return await cmdInit({ positionals: positionals.slice(1), flags });
-    if (cmd === 'dev') return await cmdDev({ positionals: positionals.slice(1), flags });
-    if (cmd === 'validate') return await cmdValidate({ positionals: positionals.slice(1), flags });
-    if (cmd === 'pack') return await cmdPack({ positionals: positionals.slice(1), flags });
-    if (cmd === 'install') return await cmdInstall({ positionals: positionals.slice(1), flags });
-
-    throw new Error(`Unknown command: ${cmd}`);
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error(`[chatos-uiapp] ${err?.message || String(err)}`);
-    process.exitCode = 1;
-  }
-}
+import { cmdInit } from './commands/init.js';
+import { cmdValidate } from './commands/validate.js';
+import { cmdPack } from './commands/pack.js';
+import { cmdInstall } from './commands/install.js';
+import { cmdDev } from './commands/dev.js';
+
+import { parseArgs } from './lib/args.js';
+
+function printHelp() {
+  // Keep it short; detailed docs live in README and generated project.
+  // eslint-disable-next-line no-console
+  console.log(`chatos-uiapp
+
+Usage:
+  chatos-uiapp init <dir> [--template <name>] [--force] [--plugin-id <id>] [--name <name>] [--app-id <appId>] [--version <semver>]
+  chatos-uiapp init --list-templates
+  chatos-uiapp dev [--port 4399] [--app <appId>] [--plugin-dir <path>]
+  chatos-uiapp validate [--plugin-dir <path>]
+  chatos-uiapp pack [--out <zipPath>] [--plugin-dir <path>]
+  chatos-uiapp install [--host-app chatos] [--state-dir <path>] [--plugin-dir <path>]
+
+Examples:
+  chatos-uiapp init my-app
+  chatos-uiapp init my-app --template notepad
+  chatos-uiapp init --list-templates
+  chatos-uiapp dev --port 4399
+  chatos-uiapp install --host-app chatos
+`);
+}
+
+export async function runCli(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const cmd = String(positionals[0] || '').trim();
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || flags.help) {
+    printHelp();
+    return;
+  }
+
+  try {
+    if (cmd === 'init') return await cmdInit({ positionals: positionals.slice(1), flags });
+    if (cmd === 'dev') return await cmdDev({ positionals: positionals.slice(1), flags });
+    if (cmd === 'validate') return await cmdValidate({ positionals: positionals.slice(1), flags });
+    if (cmd === 'pack') return await cmdPack({ positionals: positionals.slice(1), flags });
+    if (cmd === 'install') return await cmdInstall({ positionals: positionals.slice(1), flags });
+
+    throw new Error(`Unknown command: ${cmd}`);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(`[chatos-uiapp] ${err?.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/dev.js

@@ -1,14 +1,14 @@
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir } from '../lib/plugin.js';
-import { startSandboxServer } from '../sandbox/server.js';
-
-export async function cmdDev({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const portRaw = String(flags.port || flags.p || '').trim();
-  const port = portRaw ? Number(portRaw) : 4399;
-  const appId = String(flags.app || flags['app-id'] || flags.appId || config?.appId || '').trim();
-
-  await startSandboxServer({ pluginDir, port, appId });
-}
-
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir } from '../lib/plugin.js';
+import { startSandboxServer } from '../sandbox/server.js';
+
+export async function cmdDev({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+  const portRaw = String(flags.port || flags.p || '').trim();
+  const port = portRaw ? Number(portRaw) : 4399;
+  const appId = String(flags.app || flags['app-id'] || flags.appId || config?.appId || '').trim();
+
+  await startSandboxServer({ pluginDir, port, appId });
+}
+