@leeoohoo/ui-apps-devkit 0.1.0

package/templates/basic/plugin/apps/app/index.mjs

@@ -0,0 +1,263 @@
+export function mount({ container, host, slots }) {
+  if (!container) throw new Error('container is required');
+  if (!host || typeof host !== 'object') throw new Error('host is required');
+
+  const headerSlot =
+    slots?.header && typeof slots.header === 'object' && typeof slots.header.appendChild === 'function' ? slots.header : null;
+
+  const ctx = typeof host?.context?.get === 'function' ? host.context.get() : { pluginId: '', appId: '', theme: 'light' };
+  const bridgeEnabled = Boolean(ctx?.bridge?.enabled);
+
+  const root = document.createElement('div');
+  root.style.height = '100%';
+  root.style.boxSizing = 'border-box';
+  root.style.padding = '14px';
+  root.style.display = 'flex';
+  root.style.flexDirection = 'column';
+  root.style.gap = '12px';
+
+  const title = document.createElement('div');
+  title.textContent = '__PLUGIN_NAME__ · __APP_ID__';
+  title.style.fontWeight = '800';
+
+  const meta = document.createElement('div');
+  meta.style.fontSize = '12px';
+  meta.style.opacity = '0.75';
+  meta.textContent = `${ctx?.pluginId || ''}:${ctx?.appId || ''} · theme=${ctx?.theme || 'light'} · bridge=${bridgeEnabled ? 'enabled' : 'disabled'}`;
+
+  const header = document.createElement('div');
+  header.appendChild(title);
+  header.appendChild(meta);
+
+  const body = document.createElement('div');
+  body.style.display = 'grid';
+  body.style.gridTemplateColumns = '320px 1fr';
+  body.style.gap = '12px';
+  body.style.flex = '1';
+  body.style.minHeight = '0';
+
+  const actions = document.createElement('div');
+  actions.style.border = '1px solid rgba(0,0,0,0.12)';
+  actions.style.borderRadius = '14px';
+  actions.style.padding = '12px';
+  actions.style.display = 'grid';
+  actions.style.gap = '10px';
+
+  const input = document.createElement('textarea');
+  input.placeholder = '输入要发送给 ChatOS / 后端 LLM 的内容…';
+  input.style.width = '100%';
+  input.style.minHeight = '86px';
+  input.style.boxSizing = 'border-box';
+  input.style.borderRadius = '12px';
+  input.style.border = '1px solid rgba(0,0,0,0.14)';
+  input.style.background = 'rgba(0,0,0,0.04)';
+  input.style.padding = '10px 10px';
+  input.style.resize = 'vertical';
+  input.style.outline = 'none';
+
+  const log = document.createElement('pre');
+  log.style.border = '1px solid rgba(0,0,0,0.12)';
+  log.style.borderRadius = '14px';
+  log.style.padding = '12px';
+  log.style.margin = '0';
+  log.style.overflow = 'auto';
+  log.style.minHeight = '0';
+
+  const appendLog = (type, payload) => {
+    const ts = new Date().toISOString();
+    log.textContent += `[${ts}] ${type}${payload !== undefined ? ` ${JSON.stringify(payload, null, 2)}` : ''}\n`;
+    log.scrollTop = log.scrollHeight;
+  };
+
+  const mkBtn = (label) => {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.textContent = label;
+    btn.style.padding = '9px 10px';
+    btn.style.borderRadius = '12px';
+    btn.style.border = '1px solid rgba(0,0,0,0.14)';
+    btn.style.background = 'rgba(0,0,0,0.04)';
+    btn.style.cursor = 'pointer';
+    btn.style.fontWeight = '650';
+    return btn;
+  };
+
+  const run = async (label, fn) => {
+    try {
+      const res = await fn();
+      appendLog(label, res);
+      return res;
+    } catch (e) {
+      appendLog(`${label}.error`, { message: e?.message || String(e) });
+      return null;
+    }
+  };
+
+  const btnPing = mkBtn('backend.invoke("ping")');
+  btnPing.addEventListener('click', () => run('backend.invoke', () => host.backend.invoke('ping', { hello: 'world' })));
+
+  const btnLlmComplete = mkBtn('backend.invoke("llmComplete")');
+  btnLlmComplete.addEventListener('click', async () => {
+    const text = String(input.value || '').trim();
+    if (!text) return;
+    btnLlmComplete.disabled = true;
+    try {
+      const res = await run('backend.invoke.llmComplete', () => host.backend.invoke('llmComplete', { input: text }));
+      if (res?.content) {
+        log.textContent += `\n[sandbox llm]\n${String(res.content)}\n`;
+        log.scrollTop = log.scrollHeight;
+      }
+    } finally {
+      btnLlmComplete.disabled = false;
+    }
+  });
+
+  const btnPrompt = mkBtn('uiPrompts.request(kv)');
+  btnPrompt.addEventListener('click', async () => {
+    try {
+      const res = await host.uiPrompts.request({
+        prompt: {
+          kind: 'kv',
+          title: '需要你补充信息',
+          message: '填写后点 Submit',
+          fields: [
+            { key: 'name', label: '姓名', placeholder: '请输入', required: true },
+            { key: 'note', label: '备注', placeholder: '可选', multiline: true },
+          ],
+        },
+      });
+      appendLog('uiPrompts.request', res);
+      host.uiPrompts.open();
+    } catch (e) {
+      appendLog('uiPrompts.request.error', { message: e?.message || String(e) });
+    }
+  });
+
+  let activeSessionId = '';
+  let chatUnsub = null;
+
+  const ensureSession = async () => {
+    const agents = await run('chat.agents.list', () => host.chat.agents.list());
+    let agentId = agents?.agents?.[0]?.id || '';
+    if (!agentId) {
+      const ensured = await run('chat.agents.ensureDefault', () => host.chat.agents.ensureDefault());
+      agentId = ensured?.agent?.id || ensured?.agents?.[0]?.id || '';
+    }
+    if (!agentId) throw new Error('no agentId');
+
+    const res = await run('chat.sessions.ensureDefault', () => host.chat.sessions.ensureDefault({ agentId }));
+    activeSessionId = res?.session?.id || '';
+    if (activeSessionId) appendLog('activeSessionId', activeSessionId);
+    return activeSessionId;
+  };
+
+  const btnEnsureSession = mkBtn('chat.sessions.ensureDefault');
+  btnEnsureSession.addEventListener('click', () => ensureSession().catch((e) => appendLog('chat.ensureSession.error', { message: e?.message || String(e) })));
+
+  const btnSend = mkBtn('chat.send');
+  btnSend.addEventListener('click', async () => {
+    const text = String(input.value || '').trim();
+    if (!text) return;
+    btnSend.disabled = true;
+    try {
+      if (!activeSessionId) await ensureSession();
+      if (!activeSessionId) throw new Error('no sessionId');
+      await run('chat.send', () => host.chat.send({ sessionId: activeSessionId, text }));
+      input.value = '';
+    } finally {
+      btnSend.disabled = false;
+    }
+  });
+
+  const btnSub = mkBtn('chat.events.subscribe');
+  btnSub.addEventListener('click', async () => {
+    if (!activeSessionId) await ensureSession();
+    if (!activeSessionId) {
+      appendLog('chat.events.subscribe.error', { message: 'no sessionId' });
+      return;
+    }
+    if (chatUnsub) {
+      try {
+        chatUnsub();
+      } catch {
+        // ignore
+      }
+      chatUnsub = null;
+    }
+    try {
+      chatUnsub = host.chat.events.subscribe({ sessionId: activeSessionId }, (payload) => {
+        appendLog('chat.event', payload);
+        if (payload?.type === 'assistant_delta' && payload?.delta) {
+          log.textContent += payload.delta;
+          log.scrollTop = log.scrollHeight;
+        }
+      });
+      appendLog('chat.events.subscribe', { ok: true });
+    } catch (e) {
+      appendLog('chat.events.subscribe.error', { message: e?.message || String(e) });
+    }
+  });
+
+  const btnUnsub = mkBtn('chat.events.unsubscribe');
+  btnUnsub.addEventListener('click', () => {
+    if (chatUnsub) {
+      try {
+        chatUnsub();
+      } catch {
+        // ignore
+      }
+      chatUnsub = null;
+      appendLog('chat.events.unsubscribe', { ok: true });
+      return;
+    }
+    run('chat.events.unsubscribe', () => host.chat.events.unsubscribe());
+  });
+
+  actions.appendChild(btnPing);
+  actions.appendChild(btnLlmComplete);
+  actions.appendChild(btnPrompt);
+  actions.appendChild(input);
+  actions.appendChild(btnEnsureSession);
+  actions.appendChild(btnSend);
+  actions.appendChild(btnSub);
+  actions.appendChild(btnUnsub);
+
+  body.appendChild(actions);
+  body.appendChild(log);
+
+  root.appendChild(body);
+
+  if (headerSlot) {
+    try {
+      headerSlot.textContent = '';
+      headerSlot.appendChild(header);
+    } catch {
+      root.prepend(header);
+    }
+  } else {
+    root.prepend(header);
+  }
+
+  try {
+    container.textContent = '';
+  } catch {
+    // ignore
+  }
+  container.appendChild(root);
+
+  return () => {
+    if (chatUnsub) {
+      try {
+        chatUnsub();
+      } catch {
+        // ignore
+      }
+      chatUnsub = null;
+    }
+    try {
+      container.textContent = '';
+    } catch {
+      // ignore
+    }
+  };
+}

package/templates/basic/plugin/apps/app/mcp-prompt.en.md

@@ -0,0 +1,7 @@
+# __PLUGIN_NAME__ · MCP Prompt (EN)
+
+You are a tool assistant for a ChatOS UI App.
+
+- MCP Server: `__PLUGIN_ID__.__APP_ID__`
+- Prefer using its MCP tools when relevant.
+

package/templates/basic/plugin/apps/app/mcp-prompt.zh.md

@@ -0,0 +1,7 @@
+# __PLUGIN_NAME__ · MCP Prompt（中文）
+
+你是一个 ChatOS 应用的工具助手。
+
+- 对应 MCP Server：`__PLUGIN_ID__.__APP_ID__`
+- 当用户需要使用该应用能力时，优先调用该 MCP tools。
+

package/templates/basic/plugin/apps/app/mcp-server.mjs

@@ -0,0 +1,15 @@
+/**
+ * MCP Server 入口（可选）
+ *
+ * 注意：
+ * - ChatOS 导入插件包时会默认排除 `node_modules/`，因此这里不要依赖“随包携带的依赖”。
+ * - 若你需要使用 `@modelcontextprotocol/sdk`，请在 build 阶段做 bundle（把依赖打进单文件）。
+ *
+ * 你可以：
+ * 1) 用 bundler（esbuild/rollup）把 MCP Server 打包成单文件，并在 plugin.json 里把 `ai.mcp.entry` 指向打包产物；
+ * 2) 或者把依赖源码 vendoring 到插件目录内，使用相对路径 import。
+ */
+
+// TODO: 实现你自己的 MCP Server（stdio）。建议把日志写到 stderr，不要污染 stdout。
+console.error('[mcp] placeholder: implement your MCP server here');
+process.exit(1);

package/templates/basic/plugin/backend/index.mjs

@@ -0,0 +1,37 @@
+export async function createUiAppsBackend(ctx) {
+  const llmComplete = async (params, runtimeCtx) => {
+    const api = runtimeCtx?.llm || ctx?.llm || null;
+    if (!api || typeof api.complete !== 'function') {
+      throw new Error('Host LLM bridge is not available (ctx.llm.complete)');
+    }
+    const input = typeof params?.input === 'string' ? params.input : typeof params?.prompt === 'string' ? params.prompt : '';
+    const normalized = String(input || '').trim();
+    if (!normalized) {
+      throw new Error('input is required');
+    }
+    return await api.complete({
+      input: normalized,
+      modelId: typeof params?.modelId === 'string' ? params.modelId : undefined,
+      modelName: typeof params?.modelName === 'string' ? params.modelName : undefined,
+      systemPrompt: typeof params?.systemPrompt === 'string' ? params.systemPrompt : undefined,
+      disableTools: params?.disableTools,
+    });
+  };
+
+  return {
+    methods: {
+      async ping(params, runtimeCtx) {
+        return {
+          ok: true,
+          now: new Date().toISOString(),
+          pluginId: runtimeCtx?.pluginId || ctx?.pluginId || '',
+          params: params ?? null,
+        };
+      },
+
+      async llmComplete(params, runtimeCtx) {
+        return await llmComplete(params, runtimeCtx);
+      },
+    },
+  };
+}

package/templates/basic/template.json

@@ -0,0 +1,7 @@
+{
+  "description": "基础模板：无依赖 module + backend.invoke 示例 + uiPrompts 示例",
+  "defaults": {
+    "appId": "app",
+    "withBackend": true
+  }
+}

package/templates/notepad/README.md

@@ -0,0 +1,36 @@
+# __PLUGIN_NAME__（Notepad 示例模板）
+
+这是一个更接近“真实应用”的 **ChatOS UI Apps** 示例模板：Markdown 记事本（文件夹分类 + 标签检索 + 编辑/预览）。
+
+## 快速开始
+
+```bash
+npm install
+npm run dev
+```
+
+## 目录说明
+
+- `plugin/plugin.json`：插件清单（应用列表、入口、后端、AI 贡献）
+- `plugin/apps/__APP_ID__/`：前端 module（浏览器环境，导出 `mount({ container, host, slots })`）
+- `plugin/backend/`：插件后端（Node/Electron main，导出 `createUiAppsBackend(ctx)`）
+- `plugin/shared/`：共享存储实现（后端持久化所需）
+- `docs/`：协议文档快照（随工程分发）
+
+## 后端 API（示例）
+
+前端通过 `host.backend.invoke(method, params)` 调用后端方法，本模板提供 `notes.*` 一组方法用于管理笔记：
+
+- `notes.listFolders / notes.createFolder / notes.renameFolder / notes.deleteFolder`
+- `notes.listNotes / notes.createNote / notes.getNote / notes.updateNote / notes.deleteNote`
+- `notes.listTags / notes.searchNotes`
+
+## MCP（可选）
+
+模板内包含 `plugin/apps/__APP_ID__/mcp-server.mjs` 与 `mcp-prompt.*.md`，但默认 **未在** `plugin/plugin.json` 启用 `ai.mcp`（避免打包时遗漏依赖导致运行失败）。
+
+如需启用 MCP：
+
+1) 实现并 **bundle 成单文件**（建议 esbuild/rollup，把 `@modelcontextprotocol/sdk` 等依赖打进去）  
+2) 在 `plugin/plugin.json` 的 `apps[i].ai.mcp` 写入 `entry/command/args/...` 并指向 bundle 产物  
+

package/templates/notepad/chatos.config.json

@@ -0,0 +1,4 @@
+{
+  "pluginDir": "plugin",
+  "appId": "__APP_ID__"
+}

package/templates/notepad/docs/CHATOS_UI_APPS_AI_CONTRIBUTIONS.md

@@ -0,0 +1,181 @@
+# ChatOS UI Apps：AI 暴露（MCP / Prompts）协议
+
+本文件描述应用如何对 ChatOS 的 Chat Agent 暴露能力，包括：
+
+- 声明一个专属 MCP Server（让工具随应用交付、随插件安装）
+- 声明应用的默认 MCP Prompt（告诉模型如何使用这些工具/这个应用）
+- 聚合暴露“已有的”全局 MCP Servers / Prompts（面板型应用常用）
+- 内置应用的“开关 + 精细清单”两层机制（清单在 `aide` 维护）
+
+实现对照（以代码为准）：
+
+- schema：`deepseek_cli/electron/ui-apps/schemas.js`
+- 扫描与贡献解析：`deepseek_cli/electron/ui-apps/index.js`（`#resolveAi` / `getAiContribution()`；可选 `#syncAiContributes` 持久化到 Admin DB）
+- 内置默认清单：`aide/shared/defaults/ui-apps-expose/`
+
+## 1. 两种暴露方式（应用侧选择其一或组合）
+
+### 方式 A：应用自带 MCP Server + MCP Prompt
+
+用于：应用包含专属 tools（数据库查询、系统诊断、内部系统调用等）。
+
+在 `apps[i].ai` 里声明：
+
+- `ai.mcp`：宿主会创建/更新一个 MCP server（`serverName` 固定为 `${pluginId}.${appId}`）
+- `ai.mcpPrompt`：宿主会创建/更新对应 system prompt（prompt 名称固定派生）
+
+示例（节选）：
+
+```json
+{
+  "id": "db-client",
+  "name": "数据库客户端",
+  "entry": { "type": "module", "path": "db-client/index.mjs" },
+  "ai": {
+    "mcp": { "entry": "db-client/mcp-server.mjs", "command": "node", "allowMain": true, "allowSub": true },
+    "mcpPrompt": { "zh": "db-client/mcp-prompt.zh.md", "en": "db-client/mcp-prompt.en.md" }
+  }
+}
+```
+
+### 方式 B：聚合暴露“已有的” MCP servers / Prompts（面板型应用常用）
+
+用于：应用以“工作台/面板”形态聚合展示能力，不提供新的 MCP server，但需要按应用维度暴露已有 MCP servers / Prompts。
+
+在 `apps[i].ai` 里声明：
+
+- `ai.mcpServers: true | false | string[]`
+- `ai.prompts: true | false | string[]`
+
+注意：这是“可见/可选范围”的声明；最终是否启用、启用哪些，仍由 Agent 编辑页对该应用的多选结果决定。
+
+## 2. 命名规则（宿主自动派生）
+
+对每个 app：
+
+- MCP `serverName`：`${pluginId}.${appId}`
+- Prompt name：
+  - 中文：`mcp_<normalize(serverName)>`
+  - 英文：`mcp_<normalize(serverName)>__en`
+
+`normalize()`：
+
+- 转小写
+- 把非 `[a-z0-9_-]` 的字符替换为 `_`
+- 去掉首尾 `_`
+
+## 3. `ai.mcp` 的 url 生成规则（entry → cmd://）
+
+当 `ai.mcp.entry` 存在时，宿主会把它转换为：
+
+- `cmd://<command> <absEntryOrRelEntry> <args...>`
+- `command` 默认为 `node`
+
+当 `ai.mcp.url` 存在时，直接使用该 url（远程/HTTP/WS 等）。
+
+## 4. Agent UI 如何消费应用暴露（你需要知道的运行机制）
+
+### 4.1 体现在哪里（持久化 vs 运行时注入）
+
+当你把插件放进插件目录并在 UI「应用」页点击“刷新”后：
+
+1) 宿主扫描插件并解析 `plugin.json`
+2) 若发现 `apps[i].ai`：
+   - 宿主会在 UI Apps 注册表中暴露该应用的 `ai` 声明；
+   - **无论是否写入 Admin DB**，Chat Agent 运行时都可通过 `uiApps.getAiContribution()` 读取 `mcp.url` 与 `mcpPrompt` 文本，并按需“临时注入”到本次运行（见第 4.3 节）。
+   - （可选）若宿主启用 `syncAiContributes`，则会把 `ai.mcp` / `ai.mcpPrompt` **持久化同步**到 Admin DB（出现在 `MCP Servers` / `Prompts` 列表中，便于管理与复用）。
+3) 在 `Chat → Agents` 创建/编辑 agent 时：
+   - 先选择应用（按应用维度）
+   - 再为每个应用分别勾选 MCP/Prompt，并在多选框中选择要挂载的 servers/prompts
+
+### 4.2 保存结构（简化）
+
+```json
+{
+  "uiApps": [
+    {
+      "pluginId": "com.example.tools",
+      "appId": "db-client",
+      "mcp": true,
+      "prompt": true,
+      "mcpServerIds": ["<admin.mcpServers.id>", "..."],
+      "promptIds": ["<admin.prompts.id>", "..."]
+    }
+  ]
+}
+```
+
+### 4.3 运行时关键规则
+
+- 主流程（MAIN）默认只启用 `allowMain=true` 的 MCP server（安全/权限控制）
+- 如果希望 prompt 生效，请确保在应用下勾选 Prompt 并选择需要的 prompts（或提供 app 自己的 `ai.mcpPrompt`）
+
+## 5. 内置应用的“开关 + 精细清单”机制
+
+内置应用采用两层设计：
+
+1) 宿主侧（`deepseek_cli` 的 `plugin.json`）只保留粗粒度开关：
+
+```json
+{ "ai": { "mcpServers": true, "prompts": true } }
+```
+
+2) 精细清单由应用团队在 `aide` 侧维护：
+
+- 路径：`aide/shared/defaults/ui-apps-expose/<pluginId>__<appId>.yaml`（也支持 `.yml/.json`）
+
+示例：
+
+```yaml
+mcpServers:
+  - project_files
+  - task_manager
+
+prompts:
+  - default
+  - internal_main
+  - mcp_project_files
+  - mcp_task_manager
+```
+
+文件名规范：
+
+- `<pluginId>__<appId>.yaml`（全部小写；不合法字符替换为 `_`）
+
+重要：如果 `plugin.json` 未显式写 `ai.mcpServers/prompts`（或写成 `false`），宿主不会自动启用默认清单，避免“意外暴露”。
+
+## 6. 暴露范围的合并优先级（精确规则）
+
+对 `mcpServers` / `prompts` 分别适用相同规则（从高到低）：
+
+1) `plugin.json` inline 的 `ai.mcpServers/ai.prompts`
+2) `ai.config` 文件（插件目录内）的 `mcpServers/prompts`
+3) 内置默认清单（`aide/shared/defaults/ui-apps-expose`）
+
+规则要点：
+
+- inline 为 `false`：强制关闭（无视文件与默认清单）
+- inline 为 `string[]`：强制使用该列表
+- inline 为 `true`：优先用 `ai.config` 的值；若没有，再用默认清单；若仍没有，表示“全部”
+- inline 未设置：只允许 `ai.config` 生效（不会自动启用默认清单）
+
+## 7. MCP Server 最小骨架（Node.js / stdio）
+
+MCP server 进程通过 stdio 与宿主通信（不要输出到 stdout，日志写 stderr）：
+
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new McpServer({ name: 'my_server', version: '0.1.0' });
+
+// server.tool('tool_name', schema, handler) ...
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+提示：
+
+- tools 最终名字通常会变成 `mcp_<serverName>_<toolName>`（由宿主注册/派生）
+- `serverName` 为 MCP server 的 `name`（应用方式 A 下由宿主固定派生为 `${pluginId}.${appId}`）

package/templates/notepad/docs/CHATOS_UI_APPS_BACKEND_PROTOCOL.md

@@ -0,0 +1,74 @@
+# ChatOS UI Apps：插件后端协议（Electron main 进程）
+
+插件后端用于承载需要 Node 能力的逻辑（数据库/SSH/I/O/调用本地二进制等）。后端运行在 Electron main 进程，通过 IPC 由 `module` 前端调用。
+
+实现对照（以代码为准）：
+
+- `deepseek_cli/electron/ui-apps/index.js`（`uiApps:invoke` 与后端加载/缓存）
+
+## 1. 开启后端：`plugin.json`
+
+```json
+{
+  "backend": { "entry": "backend/index.mjs" }
+}
+```
+
+约束：
+
+- `backend.entry` 必须位于插件目录内；
+- 必须是文件；
+- 文件变更后会按 `mtime` 自动 reload（旧实例会尝试调用 `dispose()`）。
+
+## 2. 后端入口：`createUiAppsBackend(ctx)`
+
+后端入口模块必须导出：
+
+```js
+export async function createUiAppsBackend(ctx) {
+  return {
+    methods: {
+      async ping(params, ctx2) {
+        return { ok: true, echo: params, pluginId: ctx2.pluginId };
+      },
+    },
+    async dispose() {},
+  };
+}
+```
+
+硬约束：
+
+- 必须导出函数 `createUiAppsBackend`
+- `createUiAppsBackend()` 返回值必须包含 `{ methods }`
+
+方法调用约定：
+
+- 前端调用：`await host.backend.invoke('ping', params)`
+- 实际执行：`methods[method](params, ctx)`
+  - 第二个参数 `ctx` 会再次传入（即使你在 `createUiAppsBackend(ctx)` 的闭包里也已拿到一份）
+
+## 3. `ctx`（宿主注入的运行时上下文）
+
+`ctx` 字段（当前实现）：
+
+- `pluginId`：插件 ID
+- `pluginDir`：插件安装目录（只读引用；用于读取插件资源）
+- `dataDir`：`<stateDir>/ui_apps/data/<pluginId>`（插件可写数据目录；宿主会确保存在）
+- `stateDir`：`<home>/.deepseek_cli/<hostApp>`（ChatOS 的 `hostApp=chatos`）
+- `sessionRoot`：会话根
+- `projectRoot`：宿主工程根（开发态下有用）
+- `llm`：可选（共享模型调用接口）
+  - `ctx.llm.complete({ input, modelId?, modelName?, systemPrompt?, disableTools? })`
+  - 在 ChatOS 宿主实现中，`disableTools` 默认启用（除非显式传 `disableTools:false`）；返回形如 `{ ok:true, model, content }`
+
+规则：
+
+- 持久化只写 `dataDir`，并自行做版本化与迁移。
+- 返回值请保持可 JSON 序列化（避免传递函数/循环引用）。
+- 插件后端不保存或读取 API Keys；密钥由宿主注入到环境变量；模型调用通过 `ctx.llm.complete()`。
+
+## 4. 错误处理与返回结构
+
+- 后端方法抛错会被宿主捕获并返回 `{ ok:false, message }`；
+- 前端侧 `host.backend.invoke()` 会把 `ok:false` 转成异常抛出（便于应用用 `try/catch` 处理）。