@leeoohoo/ui-apps-devkit 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
   "license": "MIT",
   "type": "module",

package/src/commands/install.js

@@ -1,11 +1,29 @@
+import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import crypto from 'crypto';
 
 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 createActionId(prefix) {
+  const base = typeof prefix === 'string' && prefix.trim() ? prefix.trim() : 'action';
+  const short = crypto.randomUUID().split('-')[0];
+  return `${base}-${Date.now().toString(36)}-${short}`;
+}
+
+function logWith(filePath, entry) {
+  if (!filePath) return;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`, 'utf8');
+  } catch {
+    // ignore logging failures
+  }
+}
+
 function defaultStateDir(hostApp) {
   const app = typeof hostApp === 'string' && hostApp.trim() ? hostApp.trim() : 'chatos';
   return path.join(os.homedir(), STATE_ROOT_DIRNAME, app);
@@ -28,29 +46,59 @@ function copyPluginDir(srcDir, destDir) {
 
 export async function cmdInstall({ flags }) {
   const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const { pluginId, name, version } = loadPluginManifest(pluginDir);
-
+  const actionId = createActionId('devkit_install');
   const hostApp = String(flags['host-app'] || flags.hostApp || 'chatos').trim() || 'chatos';
   const stateDir = String(flags['state-dir'] || flags.stateDir || defaultStateDir(hostApp)).trim();
-  if (!stateDir) throw new Error('stateDir is required');
+  const logFile = String(flags['log-file'] || flags.logFile || path.join(stateDir, 'devkit-install-log.jsonl')).trim();
+  const log = (level, message, meta, err) => {
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      message,
+      actionId,
+      pid: process.pid,
+      meta: meta && typeof meta === 'object' ? meta : meta === undefined ? undefined : { value: meta },
+      error: err?.message || (err ? String(err) : undefined),
+    };
+    logWith(logFile, entry);
+  };
+
+  try {
+    if (!stateDir) throw new Error('stateDir is required');
+    log('info', 'devkit.install.start', { hostApp, stateDir, logFile });
+    const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+    const { pluginId, name, version } = loadPluginManifest(pluginDir);
+
+    const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
+    ensureDir(pluginsRoot);
 
-  const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
-  ensureDir(pluginsRoot);
+    const dirName = sanitizeDirComponent(pluginId);
+    if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
 
-  const dirName = sanitizeDirComponent(pluginId);
-  if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
+    const destDir = path.join(pluginsRoot, dirName);
+    const replaced = isDirectory(destDir);
+    copyPluginDir(pluginDir, destDir);
 
-  const destDir = path.join(pluginsRoot, dirName);
-  const replaced = isDirectory(destDir);
-  copyPluginDir(pluginDir, destDir);
+    log('info', 'devkit.install.complete', {
+      pluginId,
+      name,
+      version,
+      pluginDir,
+      destDir,
+      replaced,
+    });
 
-  // eslint-disable-next-line no-console
-  console.log(
-    `Installed: ${pluginId} (${name}@${version})\n` +
-      `  -> ${destDir}\n` +
-      `  replaced: ${replaced}\n\n` +
-      `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
-  );
+    // eslint-disable-next-line no-console
+    console.log(
+      `Installed: ${pluginId} (${name}@${version})\n` +
+        `  -> ${destDir}\n` +
+        `  replaced: ${replaced}\n` +
+        `  log: ${logFile}\n\n` +
+        `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
+    );
+  } catch (err) {
+    log('error', 'devkit.install.failed', {}, err);
+    throw err;
+  }
 }
 

package/src/commands/validate.js

@@ -18,11 +18,52 @@ function statSizeSafe(filePath) {
   }
 }
 
+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`);
@@ -108,6 +149,13 @@ export async function cmdValidate({ flags }) {
     }
   }
 
+  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/sandbox/server.js

@@ -628,6 +628,16 @@ function htmlPage() {
       }
       #container { flex: 1 1 auto; min-height:0; overflow:hidden; }
       #containerInner { height:100%; overflow:auto; }
+      body[data-surface='compact'] #headerSlot {
+        width: 50vw;
+        align-self: flex-end;
+        border-left: 1px solid var(--ds-panel-border);
+      }
+      body[data-surface='compact'] #container {
+        width: 50vw;
+        align-self: flex-end;
+        border-left: 1px solid var(--ds-panel-border);
+      }
       .muted { opacity: 0.7; font-size: 12px; }
       .bar { display:flex; gap:10px; align-items:center; justify-content:space-between; }
       .btn {
@@ -658,10 +668,12 @@ function htmlPage() {
         border-radius:14px;
         overflow:hidden;
         box-shadow: 0 18px 60px rgba(0,0,0,0.18);
+        z-index: 1305;
+        pointer-events: auto;
       }
       #promptsPanelHeader { padding: 10px 12px; display:flex; align-items:center; justify-content:space-between; border-bottom: 1px solid var(--ds-panel-border); }
       #promptsPanelBody { padding: 10px 12px; overflow:auto; display:flex; flex-direction:column; gap:10px; }
-      #promptsFab { position: fixed; right: 16px; bottom: 16px; width: 44px; height: 44px; border-radius: 999px; display:flex; align-items:center; justify-content:center; }
+      #promptsFab { position: fixed; right: 16px; bottom: 16px; width: 44px; height: 44px; border-radius: 999px; display:flex; align-items:center; justify-content:center; z-index: 1305; pointer-events: auto; }
       .card { border: 1px solid var(--ds-panel-border); border-radius: 12px; padding: 10px; background: var(--ds-panel-bg); }
       .row { display:flex; gap:10px; }
       .toolbar-group { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
@@ -739,16 +751,6 @@ function htmlPage() {
         box-shadow: 0 14px 40px rgba(0,0,0,0.16);
         z-index: 12;
       }
-      #mcpPanel[data-mode='half'] {
-        right: 0;
-        top: 72px;
-        width: 50vw;
-        height: calc(100vh - 84px);
-        max-height: none;
-        border-right: none;
-        border-top-right-radius: 0;
-        border-bottom-right-radius: 0;
-      }
       #mcpPanelHeader {
         padding: 10px 12px;
         display:flex;
@@ -805,7 +807,7 @@ function htmlPage() {
             <div id="sandboxContext" class="muted"></div>
             <button id="btnLlmConfig" class="btn" type="button">AI Config</button>
             <button id="btnMcpTest" class="btn" type="button">MCP Test</button>
-            <button id="btnMcpHalf" class="btn" type="button">Half Test</button>
+            <button id="btnHalfApp" class="btn" type="button">半屏</button>
             <button id="btnInspectorToggle" class="btn" type="button">Inspect</button>
             <button id="btnReload" class="btn" type="button">Reload</button>
           </div>
@@ -867,8 +869,8 @@ function htmlPage() {
         <div class="card">
           <div class="section-title">Paths</div>
           <pre id="mcpPaths" class="mono"></pre>
-          <label for="mcpWorkdir">Workdir Override (optional)</label>
-          <input id="mcpWorkdir" type="text" placeholder="留空则使用默认 workdir" />
+          <label for="mcpWorkdir">ProjectRoot Override (optional)</label>
+          <input id="mcpWorkdir" type="text" placeholder="留空则使用默认 projectRoot" />
         </div>
         <div class="card">
           <div class="section-title">Model</div>
@@ -961,7 +963,7 @@ const llmModelId = $('#llmModelId');
 const llmStatus = $('#llmStatus');
 const llmKeyStatus = $('#llmKeyStatus');
 const btnMcpTest = $('#btnMcpTest');
-const btnMcpHalf = $('#btnMcpHalf');
+const btnHalfApp = $('#btnHalfApp');
 const mcpPanel = $('#mcpPanel');
 const btnMcpClose = $('#btnMcpClose');
 const btnMcpClear = $('#btnMcpClear');
@@ -1033,6 +1035,34 @@ const updateContextStatus = () => {
   sandboxContext.textContent = __SANDBOX__.pluginId + ':' + __SANDBOX__.appId;
 };
 
+const entryCompactUrl = __SANDBOX__.entryCompactUrl || '';
+const hasCompactEntry = Boolean(entryCompactUrl);
+let currentSurface = 'full';
+
+const updateSurfaceState = (surface) => {
+  currentSurface = surface === 'compact' ? 'compact' : 'full';
+  document.body.dataset.surface = currentSurface;
+  if (btnHalfApp) {
+    if (!hasCompactEntry) {
+      btnHalfApp.disabled = true;
+      btnHalfApp.title = 'plugin.json 未配置 entry.compact.path';
+      delete btnHalfApp.dataset.active;
+    } else {
+      btnHalfApp.disabled = false;
+      btnHalfApp.title = '';
+      btnHalfApp.dataset.active = currentSurface === 'compact' ? '1' : '0';
+    }
+  }
+  if (host?.ui) host.ui.surface = currentSurface;
+};
+
+const toggleCompactSurface = () => {
+  if (!hasCompactEntry) return;
+  updateSurfaceState(currentSurface === 'compact' ? 'full' : 'compact');
+  loadAndMount().catch(renderError);
+  updateInspectorIfOpen();
+};
+
 const isInspectorOpen = () => sandboxInspector && sandboxInspector.style.display === 'flex';
 const isLlmPanelOpen = () => llmPanel && llmPanel.style.display === 'flex';
 const isMcpPanelOpen = () => mcpPanel && mcpPanel.style.display === 'flex';
@@ -1118,9 +1148,15 @@ const appendMcpOutput = (label, payload) => {
   mcpOutput.scrollTop = mcpOutput.scrollHeight;
 };
 
+const resolveMcpPaths = () => {
+  const projectRootOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
+  if (!projectRootOverride) return sandboxPaths;
+  return { ...sandboxPaths, projectRoot: projectRootOverride };
+};
+
 const refreshMcpPaths = () => {
   if (!mcpPaths) return;
-  mcpPaths.textContent = formatJson(sandboxPaths);
+  mcpPaths.textContent = formatJson(resolveMcpPaths());
 };
 
 const refreshMcpConfigHint = async () => {
@@ -1140,13 +1176,8 @@ const refreshMcpConfigHint = async () => {
   }
 };
 
-const setMcpPanelOpen = (open, mode) => {
+const setMcpPanelOpen = (open) => {
   if (!mcpPanel) return;
-  if (mode) {
-    mcpPanel.dataset.mode = mode;
-  } else {
-    delete mcpPanel.dataset.mode;
-  }
   mcpPanel.style.display = open ? 'flex' : 'none';
   mcpPanel.setAttribute('aria-hidden', open ? 'false' : 'true');
   if (open) {
@@ -1155,16 +1186,6 @@ const setMcpPanelOpen = (open, mode) => {
   }
 };
 
-const toggleMcpPanel = (mode) => {
-  if (!mcpPanel) return;
-  const currentMode = mcpPanel.dataset.mode || 'panel';
-  if (isMcpPanelOpen() && currentMode === mode) {
-    setMcpPanelOpen(false);
-    return;
-  }
-  setMcpPanelOpen(true, mode);
-};
-
 const runMcpTest = async () => {
   const sendBtn = btnMcpSend;
   try {
@@ -1180,9 +1201,11 @@ const runMcpTest = async () => {
       systemPrompt: mcpSystem ? String(mcpSystem.value || '').trim() : '',
       disableTools: Boolean(mcpDisableTools?.checked),
     };
-    const workdirOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
-    if (workdirOverride) {
-      payload.callMeta = { workdir: workdirOverride };
+    const projectRootOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
+    if (projectRootOverride) {
+      payload.callMeta = {
+        chatos: { uiApp: { projectRoot: projectRootOverride } },
+      };
     }
     setMcpStatus('Sending...');
     appendMcpOutput('request', payload);
@@ -1226,7 +1249,13 @@ const collectTokens = () => {
 const readHostContext = () => {
   if (!inspectorEnabled) return null;
   if (typeof host?.context?.get === 'function') return host.context.get();
-  return { pluginId: __SANDBOX__.pluginId, appId: __SANDBOX__.appId, theme: currentTheme, bridge: { enabled: true } };
+  return {
+    pluginId: __SANDBOX__.pluginId,
+    appId: __SANDBOX__.appId,
+    theme: currentTheme,
+    surface: currentSurface,
+    bridge: { enabled: true },
+  };
 };
 
 const readThemeInfo = () => ({
@@ -1305,9 +1334,10 @@ if (btnLlmClose) btnLlmClose.addEventListener('click', () => setLlmPanelOpen(fal
 if (btnLlmRefresh) btnLlmRefresh.addEventListener('click', () => refreshLlmConfig());
 if (btnLlmSave) btnLlmSave.addEventListener('click', () => saveLlmConfig());
 if (btnLlmClear) btnLlmClear.addEventListener('click', () => saveLlmConfig({ clearKey: true }));
-if (btnMcpTest) btnMcpTest.addEventListener('click', () => toggleMcpPanel('panel'));
-if (btnMcpHalf) btnMcpHalf.addEventListener('click', () => toggleMcpPanel('half'));
+if (btnMcpTest) btnMcpTest.addEventListener('click', () => setMcpPanelOpen(!isMcpPanelOpen()));
+if (btnHalfApp) btnHalfApp.addEventListener('click', () => toggleCompactSurface());
 if (btnMcpClose) btnMcpClose.addEventListener('click', () => setMcpPanelOpen(false));
+if (mcpWorkdir) mcpWorkdir.addEventListener('input', () => refreshMcpPaths());
 if (btnMcpClear)
   btnMcpClear.addEventListener('click', () => {
     if (mcpOutput) mcpOutput.textContent = '';
@@ -1499,7 +1529,15 @@ const getTheme = () => currentTheme || resolveTheme();
 
 const host = {
   bridge: { enabled: true },
-  context: { get: () => ({ pluginId: __SANDBOX__.pluginId, appId: __SANDBOX__.appId, theme: getTheme(), bridge: { enabled: true } }) },
+  context: {
+    get: () => ({
+      pluginId: __SANDBOX__.pluginId,
+      appId: __SANDBOX__.appId,
+      theme: getTheme(),
+      surface: currentSurface,
+      bridge: { enabled: true },
+    }),
+  },
   theme: {
     get: getTheme,
     onChange: (listener) => {
@@ -1552,7 +1590,7 @@ const host = {
     close: () => (setPanelOpen(false), { ok: true }),
     toggle: () => (setPanelOpen(panel.style.display !== 'flex'), { ok: true }),
   },
-  ui: { navigate: (menu) => ({ ok: true, menu }) },
+  ui: { navigate: (menu) => ({ ok: true, menu }), surface: 'full' },
   chat: (() => {
     const clone = (v) => JSON.parse(JSON.stringify(v));
 
@@ -1807,6 +1845,8 @@ const host = {
   })(),
 };
 
+updateSurfaceState('full');
+
 inspectorEnabled = true;
 updateInspector();
 
@@ -1816,7 +1856,7 @@ async function loadAndMount() {
   if (typeof dispose === 'function') { try { await dispose(); } catch {} dispose = null; }
   container.textContent = '';
 
-  const entryUrl = __SANDBOX__.entryUrl;
+  const entryUrl = currentSurface === 'compact' && entryCompactUrl ? entryCompactUrl : __SANDBOX__.entryUrl;
   const mod = await import(entryUrl + (entryUrl.includes('?') ? '&' : '?') + 't=' + Date.now());
   const mount = mod?.mount || mod?.default?.mount || (typeof mod?.default === 'function' ? mod.default : null);
   if (typeof mount !== 'function') throw new Error('module entry must export mount()');
@@ -1879,7 +1919,13 @@ export async function startSandboxServer({ pluginDir, port = 4399, appId = '' })
   const entryAbs = resolveInsideDir(pluginDir, entryRel);
   if (!isFile(entryAbs)) throw new Error(`module entry not found: ${entryRel}`);
 
+  const entryCompactRel = String(app?.entry?.compact?.path || '').trim();
   const entryUrl = `/plugin/${encodeURIComponent(entryRel).replaceAll('%2F', '/')}`;
+  const entryCompactAbs = entryCompactRel ? resolveInsideDir(pluginDir, entryCompactRel) : '';
+  const entryCompactUrl =
+    entryCompactAbs && isFile(entryCompactAbs)
+      ? `/plugin/${encodeURIComponent(entryCompactRel).replaceAll('%2F', '/')}`
+      : '';
 
   let backendInstance = null;
   let backendFactory = null;
@@ -2193,6 +2239,7 @@ export async function startSandboxServer({ pluginDir, port = 4399, appId = '' })
           .replaceAll('__SANDBOX__.pluginId', JSON.stringify(ctxBase.pluginId))
           .replaceAll('__SANDBOX__.appId', JSON.stringify(effectiveAppId))
           .replaceAll('__SANDBOX__.entryUrl', JSON.stringify(entryUrl))
+          .replaceAll('__SANDBOX__.entryCompactUrl', JSON.stringify(entryCompactUrl))
           .replaceAll('__SANDBOX__.registryApp', JSON.stringify({ plugin: { id: ctxBase.pluginId }, id: effectiveAppId, entry: { type: 'module', url: entryUrl } }))
           .replaceAll('__SANDBOX__.tokenNames', JSON.stringify(tokenNames))
           .replaceAll('__SANDBOX__.paths', JSON.stringify(sandboxPaths));

package/templates/basic/README.md

@@ -34,6 +34,7 @@ npm run dev
 
 - `plugin/plugin.json`：`apps[i].entry.type` 必须是 `module`，且 `path` 在插件目录内。
 - `plugin/plugin.json`：可选 `apps[i].entry.compact.path`，用于 compact UI。
+- 安全：插件目录内尽量避免 symlink（`npm run validate` 会提示），以免路径边界与打包行为不一致。
 - `mount()`：返回卸载函数并清理事件/订阅；滚动放在应用内部，固定内容用 `slots.header`。
 - 主题：用 `host.theme.*` 与 `--ds-*` tokens；避免硬编码颜色。
 - 宿主能力：先判断 `host.bridge.enabled`，非宿主环境要可降级运行。
@@ -49,6 +50,7 @@ npm run dev
 2) **后端调用 LLM**：在 `plugin/backend/index.mjs` 里通过 `ctx.llm.complete()` 调用模型；前端用 `host.backend.invoke('llmComplete', { input })` 触发。
 
 说明：本地沙箱默认是 mock；可通过右上角 `AI Config` 配置 `API Key / Base URL / Model ID` 后启用真实模型调用，并用于测试应用 MCP（需配置 `ai.mcp`）。
+补充：沙箱默认把 `_meta.workdir` 设为 `dataDir`；如需模拟其它工作目录，可在 `AI Config` 里设置 `Workdir` 覆盖（支持 `$dataDir/$pluginDir/$projectRoot`）。
 
 ## 安装到本机 ChatOS
 

package/templates/basic/docs/CHATOS_UI_APPS_AI_CONTRIBUTIONS.md

@@ -85,6 +85,8 @@
 
 同时，宿主默认注入 `_meta.workdir`（默认等于 `dataDir`；如需指定其它目录，可在 `ai.mcp.callMeta.workdir` 覆盖）。
 
+> DevKit sandbox：右上角 `AI Config` 支持设置 `Workdir` 覆盖；留空即使用 `dataDir`（也支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 示例（`plugin.json`）：
 
 ```json

package/templates/notepad/README.md

@@ -9,6 +9,11 @@ npm install
 npm run dev
 ```
 
+## 本地沙箱 AI Config（可选）
+
+- 右上角 `AI Config` 可配置 `API Key / Base URL / Model ID`，用于测试真实模型调用（以及 MCP 调用）。
+- 沙箱默认把 `_meta.workdir` 设为 `dataDir`；如需模拟其它工作目录，可在 `AI Config` 里设置 `Workdir` 覆盖（支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 ## 目录说明
 
 - `plugin/plugin.json`：插件清单（应用列表、入口、后端、AI 贡献）
@@ -29,6 +34,7 @@ npm run dev
 
 - `plugin/plugin.json`：`apps[i].entry.type` 必须是 `module`，且 `path` 在插件目录内。
 - `plugin/plugin.json`：可选 `apps[i].entry.compact.path`，用于 compact UI。
+- 安全：插件目录内尽量避免 symlink（`npm run validate` 会提示），以免路径边界与打包行为不一致。
 - `mount()`：返回卸载函数并清理事件/订阅；滚动放在应用内部，固定内容用 `slots.header`。
 - 主题：用 `host.theme.*` 与 `--ds-*` tokens；避免硬编码颜色。
 - 宿主能力：先判断 `host.bridge.enabled`，非宿主环境要可降级运行。

package/templates/notepad/docs/CHATOS_UI_APPS_AI_CONTRIBUTIONS.md

@@ -85,6 +85,8 @@
 
 同时，宿主默认注入 `_meta.workdir`（默认等于 `dataDir`；如需指定其它目录，可在 `ai.mcp.callMeta.workdir` 覆盖）。
 
+> DevKit sandbox：右上角 `AI Config` 支持设置 `Workdir` 覆盖；留空即使用 `dataDir`（也支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 示例（`plugin.json`）：
 
 ```json