@leeoohoo/ui-apps-devkit 0.1.1 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@
 - 生成 UI Apps 插件工程（脚手架）
 - 在本地沙箱里运行/调试 `module` 应用（Host API mock）
 - 校验 `plugin.json` 与路径边界
-- 打包/安装到本机 ChatOS（`~/.deepseek_cli/chatos/ui_apps/plugins`）
+- 打包/安装到本机 ChatOS（用户插件目录：`<stateDir>/ui_apps/plugins`；`stateDir = <stateRoot>/<hostApp>`）
 
 ## 安装
 
@@ -28,11 +28,13 @@ npm install
 npm run dev
 ```
 
-## 沙箱能力
-
-- 模拟 `module mount()` 与 `host.*` API
-- 右上角 Theme 切换（light/dark/system），用于测试 `host.theme.onChange` 与样式响应
-- Inspect 面板展示 `host.context` 与 `--ds-*` tokens
+## 沙箱能力
+
+- 模拟 `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`）
+- `AI Config` 可设置 `Workdir` 覆盖（默认 `dataDir`，支持 `$dataDir/$pluginDir/$projectRoot`）
 
 ## 模板
 
@@ -45,15 +47,22 @@ 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
-```
-
-## 生成项目结构（约定）
+完成开发后：
+
+```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/` 目录：
 
@@ -71,6 +80,6 @@ my-first-uiapp/
 
 - `chatos-uiapp init <dir>`：生成工程
 - `chatos-uiapp dev`：启动本地运行沙箱（支持文件变更自动重载）
-- `chatos-uiapp validate`：校验 manifest 与路径边界
+- `chatos-uiapp validate`：校验 manifest 与路径边界（遇到 symlink 会给出警告）
 - `chatos-uiapp pack`：打包 `.zip`（用于 ChatOS 导入）
 - `chatos-uiapp install`：复制到本机 ChatOS 用户插件目录

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
   "license": "MIT",
-  "type": "module",
-  "scripts": {
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2"
+  },
+  "scripts": {
     "test": "node --test"
   },
   "bin": {

package/src/commands/init.js

@@ -2,15 +2,16 @@ import path from 'path';
 import readline from 'readline';
 
 import { ensureDir, isDirectory, isFile, rmForce, writeText } from '../lib/fs.js';
-import {
-  copyTemplate,
-  listTemplates,
-  readTemplateMeta,
-  maybeReplaceTokensInFile,
-  writeScaffoldConfig,
-  writeScaffoldManifest,
-  writeScaffoldPackageJson,
-} from '../lib/template.js';
+import {
+  copyTemplate,
+  listTemplates,
+  readTemplateMeta,
+  maybeReplaceTokensInFile,
+  writeScaffoldConfig,
+  writeScaffoldManifest,
+  writeScaffoldPackageJson,
+} from '../lib/template.js';
+import { COMPAT_STATE_ROOT_DIRNAME, STATE_ROOT_DIRNAME } from '../lib/state-constants.js';
 
 function canPrompt() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -126,10 +127,10 @@ export async function cmdInit({ positionals, flags }) {
   maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-prompt.en.md'), replacements);
 
   // Ensure a helpful note exists even if template is edited later.
-  writeText(
-    path.join(destDir, '.gitignore'),
-    `node_modules/\n.DS_Store\n.chatos/\n*.log\n\n# build outputs (if you add bundling later)\ndist/\n`
-  );
+  writeText(
+    path.join(destDir, '.gitignore'),
+    `node_modules/\n.DS_Store\n${STATE_ROOT_DIRNAME}/\n${COMPAT_STATE_ROOT_DIRNAME}/\n*.log\n\n# build outputs (if you add bundling later)\ndist/\n`
+  );
 
   // eslint-disable-next-line no-console
   console.log(`Created: ${destDir}

package/src/commands/install.js

@@ -1,14 +1,15 @@
-import os from 'os';
-import path from 'path';
-
-import { copyDir, ensureDir, isDirectory, rmForce, sanitizeDirComponent } from '../lib/fs.js';
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
-
-function defaultStateDir(hostApp) {
-  const app = typeof hostApp === 'string' && hostApp.trim() ? hostApp.trim() : 'chatos';
-  return path.join(os.homedir(), '.deepseek_cli', app);
-}
+import os from 'os';
+import path from 'path';
+
+import { copyDir, ensureDir, isDirectory, rmForce, sanitizeDirComponent } from '../lib/fs.js';
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
+import { STATE_ROOT_DIRNAME } from '../lib/state-constants.js';
+
+function defaultStateDir(hostApp) {
+  const app = typeof hostApp === 'string' && hostApp.trim() ? hostApp.trim() : 'chatos';
+  return path.join(os.homedir(), STATE_ROOT_DIRNAME, app);
+}
 
 function copyPluginDir(srcDir, destDir) {
   ensureDir(path.dirname(destDir));

package/src/commands/validate.js

@@ -10,22 +10,63 @@ function assert(cond, message) {
   if (!cond) throw new Error(message);
 }
 
-function statSizeSafe(filePath) {
-  try {
-    return fs.statSync(filePath).size;
-  } catch {
-    return 0;
-  }
-}
-
-export async function cmdValidate({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-
-  const { manifestPath, manifest } = loadPluginManifest(pluginDir);
-
-  const manifestSize = statSizeSafe(manifestPath);
-  assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
+function statSizeSafe(filePath) {
+  try {
+    return fs.statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+function collectSymlinks(rootDir) {
+  const root = typeof rootDir === 'string' ? rootDir.trim() : '';
+  if (!root) return [];
+  const out = [];
+  const walk = (dir) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.forEach((entry) => {
+      if (!entry || !entry.name) return;
+      const fullPath = path.join(dir, entry.name);
+      let stat;
+      try {
+        stat = fs.lstatSync(fullPath);
+      } catch {
+        return;
+      }
+      if (stat.isSymbolicLink()) {
+        out.push(fullPath);
+        return;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      }
+    });
+  };
+  walk(root);
+  return out;
+}
+
+export async function cmdValidate({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+
+  const { manifestPath, manifest } = loadPluginManifest(pluginDir);
+  const warnings = [];
+  const warn = (message) => warnings.push(message);
+
+  const symlinks = collectSymlinks(pluginDir);
+  if (symlinks.length > 0) {
+    const rel = symlinks.map((entry) => path.relative(pluginDir, entry) || entry);
+    warn(`Symlink detected inside plugin dir (may bypass path boundaries): ${rel.join(', ')}`);
+  }
+
+  const manifestSize = statSizeSafe(manifestPath);
+  assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
 
   assert(Number(manifest?.manifestVersion || 1) === 1, 'manifestVersion must be 1');
   assert(typeof manifest?.id === 'string' && manifest.id.trim(), 'plugin.id is required');
@@ -106,8 +147,15 @@ export async function cmdValidate({ flags }) {
       const size = statSizeSafe(abs);
       assert(size <= 128 * 1024, `mcpPrompt too large (>128KiB): ${rel}`);
     }
-  }
-
-  // eslint-disable-next-line no-console
-  console.log(`OK: ${path.relative(process.cwd(), pluginDir)} (apps=${apps.length})`);
-}
+  }
+
+  if (warnings.length > 0) {
+    warnings.forEach((message) => {
+      // eslint-disable-next-line no-console
+      console.warn(`WARN: ${message}`);
+    });
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`OK: ${path.relative(process.cwd(), pluginDir)} (apps=${apps.length})`);
+}

package/src/lib/state-constants.js

@@ -0,0 +1,2 @@
+export const STATE_ROOT_DIRNAME = '.deepseek_cli';
+export const COMPAT_STATE_ROOT_DIRNAME = '.chatos';