@leeoohoo/ui-apps-devkit 0.1.0

package/templates/basic/README.md

@@ -0,0 +1,58 @@
+# __PLUGIN_NAME__
+
+这是一个 **ChatOS UI Apps 插件工程**（UI Apps Plugins）。
+
+## 你应该在哪写什么
+
+- `plugin/plugin.json`：插件清单（应用列表、入口、后端、AI 贡献）
+- `plugin/apps/__APP_ID__/index.mjs`：**module 入口**（导出 `mount({ container, host, slots })`）
+- `plugin/backend/index.mjs`：**插件后端**（导出 `createUiAppsBackend(ctx)`，通过 `host.backend.invoke()` 调用）
+- `plugin/apps/__APP_ID__/mcp-server.mjs`：应用自带 MCP Server（可选）
+- `plugin/apps/__APP_ID__/mcp-prompt.zh.md` / `.en.md`：MCP Prompt（可选）
+
+## 开发与预览（本地沙箱）
+
+```bash
+npm install
+npm run dev
+```
+
+沙箱会：
+
+- 用 HTTP 运行你的 `module` 入口（模拟 ChatOS 的 `mount()` 调用）
+- 提供 `host.*` 的 mock（含 `host.backend.invoke()`、`host.uiPrompts.*`、`host.chat.*`）
+
+## 复用 ChatOS 的 AI 调用（推荐）
+
+本模板演示两种“复用宿主模型/密钥/工具链”的方式：
+
+1) **前端直连 Chat 域**：用 `host.chat.*` 创建 agent/session、`host.chat.send()` 发送消息、`host.chat.events.subscribe()` 订阅流式事件。
+2) **后端调用 LLM**：在 `plugin/backend/index.mjs` 里通过 `ctx.llm.complete()` 调用模型；前端用 `host.backend.invoke('llmComplete', { input })` 触发。
+
+说明：本地沙箱只提供 mock（不会真实调用模型）；要验证真实 AI 行为请安装到 ChatOS 后运行。
+
+## 安装到本机 ChatOS
+
+```bash
+npm run validate
+npm run install:chatos
+```
+
+或打包成 zip（用于 ChatOS UI：应用 → 导入应用包）：
+
+```bash
+npm run pack
+```
+
+## 协议文档
+
+`docs/` 目录包含当前版本的协议快照（建议团队内统一对齐）。
+
+## 启用 MCP（可选）
+
+本模板默认只启用 `ai.mcpPrompt`（不启用 `ai.mcp`），避免第三方插件在未打包依赖时运行失败。
+
+如果你要启用 MCP：
+
+1) 实现并打包 `plugin/apps/__APP_ID__/mcp-server.mjs`（建议 bundle 成单文件）  
+2) 在 `plugin/plugin.json` 的 `apps[i].ai.mcp` 写入 `entry/command/args/...`  

package/templates/basic/chatos.config.json

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

package/templates/basic/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/basic/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` 处理）。

package/templates/basic/docs/CHATOS_UI_APPS_HOST_API.md

@@ -0,0 +1,123 @@
+# ChatOS UI Apps：`module` 入口与 Host API（协议）
+
+本文件定义 UI Apps 的 `module` 入口规范，以及宿主注入的 `host` 对象（应用与 ChatOS 交互的稳定契约）。
+
+实现对照（以代码为准）：
+
+- `deepseek_cli/apps/ui/src/features/apps/AppsPluginView.jsx`
+
+## 1. module 入口规范
+
+`plugin.json` 中的入口示例：
+
+```json
+{ "type": "module", "path": "my-app/index.mjs" }
+```
+
+入口模块需导出 `mount`（以下三种写法宿主都接受）：
+
+- `export function mount(...) { ... }`
+- `export default { mount(...) { ... } }`
+- `export default function mount(...) { ... }`
+
+`mount` 签名：
+
+```js
+export function mount({ container, host, slots }) {
+  return () => {}; // or return { dispose() {} }
+}
+```
+
+- `container`：应用正文容器（body）
+- `slots.header`：可选固定 Header 容器（不随 body 滚动）
+- 返回值：
+  - `() => void|Promise<void>`：卸载回调；或
+  - `{ dispose(): void|Promise<void> }`
+
+布局规范：
+
+- 不要使用 `window/body` 作为滚动容器；把滚动放到应用内部。
+- 将 Tabs/二级导航/操作按钮等放到 `slots.header`，可滚动内容放到 `container`。
+
+## 2. Host Bridge 可用性
+
+宿主仅在“file-based entry + preload bridge 可用”的情况下提供 `host` 能力；否则会抛错：
+
+- 若你在非 ChatOS 宿主环境下单独打开页面（或 preload 未加载），`host.bridge.enabled` 可能为 `false`。
+- 生产场景（桌面端应用内）一般为 `true`。
+
+## 3. `host` API 约定
+
+### 3.1 上下文与主题
+
+- `host.bridge.enabled: boolean`
+- `host.context.get(): { pluginId, appId, theme, bridge: { enabled } }`
+- `host.theme.get(): string`（当前实现读取 `document.documentElement.dataset.theme`）
+- `host.theme.onChange(listener): () => void`
+
+### 3.2 Admin（全局配置读取）
+
+- `host.admin.state(): Promise<any>`：读取全局 Admin 状态快照
+- `host.admin.onUpdate(listener): () => void`：订阅 Admin 更新事件
+- `host.admin.models.list(): Promise<any>`：列出 Models
+- `host.admin.secrets.list(): Promise<any>`：列出 Secrets（脱敏；不会返回明文 key）
+
+说明：
+
+- UI Apps **不得**在自己的配置里保存/管理 API Keys；应完全复用宿主全局配置。
+
+### 3.3 Registry（插件注册表）
+
+- `host.registry.list(): Promise<any>`：等价于 `uiApps:list`（包含 apps 列表、插件目录、加载错误等）
+
+### 3.4 Backend（插件后端调用）
+
+- `host.backend.invoke(method: string, params?: any): Promise<any>`
+  - `method`：后端 `methods` 的 key
+  - 返回值：后端方法返回的 `result`（宿主会把 `{ ok, result }` 解包）
+
+后端协议详见：[CHATOS_UI_APPS_BACKEND_PROTOCOL.md](./CHATOS_UI_APPS_BACKEND_PROTOCOL.md)。
+
+### 3.5 UI Prompts（右下角笑脸：交互待办）
+
+用于把“需要用户确认/输入”的交互投递到全局队列，用户无需进入对应应用即可处理。
+
+- `host.uiPrompts.read(): Promise<any>`：读取当前队列/最新状态
+- `host.uiPrompts.onUpdate(listener): () => void`：订阅队列变化
+- `host.uiPrompts.request({ prompt, runId?, requestId?, ... }): Promise<any>`：投递待办（`prompt.source` 为空时宿主写入 `${pluginId}:${appId}`）
+- `host.uiPrompts.respond({ requestId, runId?, response }): Promise<any>`：写入用户响应
+- `host.uiPrompts.open(): { ok: true }`：打开笑脸面板
+- `host.uiPrompts.close(): { ok: true }`
+- `host.uiPrompts.toggle(): { ok: true }`
+
+`prompt` / `response` 的字段协议见：[CHATOS_UI_PROMPTS_PROTOCOL.md](./CHATOS_UI_PROMPTS_PROTOCOL.md)。
+
+### 3.6 导航
+
+- `host.ui.navigate(menu: string): { ok: true }`
+  - 用于跨应用/跨页面跳转（由宿主统一处理路由）
+
+### 3.7 Chat（Agents / Sessions / Messages / Send / Events）
+
+`host.chat` 提供对聊天域的直接操作能力（节选）：
+
+- `host.chat.agents.list()`
+- `host.chat.agents.ensureDefault()`
+- `host.chat.agents.create(payload)`
+- `host.chat.agents.update(id, patch)`
+- `host.chat.agents.delete(id)`
+- `host.chat.agents.createForApp({ name?, description?, modelId?, promptIds?, subagentIds?, skills?, mcpServerIds? })`
+  - 创建一个“绑定当前应用”的 Agent，并自动写入 `uiApps: [{ pluginId, appId, mcp:true, prompt:true }]`
+- `host.chat.sessions.list()`
+- `host.chat.sessions.ensureDefault(payload?)`
+- `host.chat.sessions.create(payload)`
+- `host.chat.messages.list(payload)`
+- `host.chat.send(payload)`
+- `host.chat.abort(payload)`
+- `host.chat.events.subscribe({ sessionId?, types? }, listener): () => void`
+- `host.chat.events.unsubscribe(): { ok: true }`
+
+事件订阅说明：
+
+- `subscribe` 支持用 `sessionId` 与 `types` 做过滤；
+- 当最后一个 listener 解绑后，宿主会自动取消底层订阅。

package/templates/basic/docs/CHATOS_UI_APPS_OVERVIEW.md

@@ -0,0 +1,110 @@
+# ChatOS UI Apps（嵌入应用）概览
+
+本文把散落在仓库各处的“ChatOS 嵌入应用（UI Apps 插件）框架/协议”说明提取到仓库根目录，并补齐了若干关键约束（路径边界、打包导入、schema 字段等）。
+
+配套文档（按从概览 → 细节的阅读顺序）：
+
+- [`CHATOS_UI_APPS_PLUGIN_MANIFEST.md`](./CHATOS_UI_APPS_PLUGIN_MANIFEST.md)：`plugin.json` / `apps[i].ai` 的清单与字段规范（含完整字段、示例与约束）。
+- [`CHATOS_UI_APPS_HOST_API.md`](./CHATOS_UI_APPS_HOST_API.md)：`module` 应用入口与 `host.*` 交互协议（前端侧）。
+- [`CHATOS_UI_PROMPTS_PROTOCOL.md`](./CHATOS_UI_PROMPTS_PROTOCOL.md)：右下角笑脸「交互待办（UI Prompts）」协议（表单/单选/多选/复杂确认）。
+- [`CHATOS_UI_APPS_BACKEND_PROTOCOL.md`](./CHATOS_UI_APPS_BACKEND_PROTOCOL.md)：插件后端（Electron main 进程）协议与 `ctx` 运行时上下文。
+- [`CHATOS_UI_APPS_AI_CONTRIBUTIONS.md`](./CHATOS_UI_APPS_AI_CONTRIBUTIONS.md)：应用如何对 Chat Agent 暴露 MCP/Prompt（含命名规则、合并规则、内置清单机制）。
+
+## 术语与角色
+
+- **ChatOS（宿主）**：桌面端 Electron 应用（本仓库的 `deepseek_cli`）。
+- **AIDE（引擎）**：模型调用/工具/MCP/子代理等核心能力（本仓库的 `aide`）。
+- **UI Apps（嵌入应用/小应用）**：以插件形式注入到桌面端「应用」中心的应用。
+- **MCP**：Model Context Protocol；通过 MCP Server 暴露 tools，最终工具名通常为 `mcp_<serverName>_<toolName>`。
+- **Prompt**：system prompt 模板；可被 Agent 勾选并注入运行时 system prompt。
+
+## 目录与状态（sessionRoot / stateDir）
+
+- `sessionRoot`：会话根目录
+  - 默认：用户主目录（Home）
+  - 可通过环境变量覆盖：`MODEL_CLI_SESSION_ROOT=/path/to/root`
+  - 桌面端/CLI 会把“上次使用的 sessionRoot”记录到 `<home>/.deepseek_cli/last-session-root.txt`（未设置 env 时会优先读取）
+- `stateDir`：`<home>/.deepseek_cli/<hostApp>`（ChatOS 的 `hostApp=chatos`）
+
+全局配置（由宿主维护；应用侧只读/复用）：
+
+- `stateDir/chatos.db.sqlite`：Admin DB（Models / Secrets / MCP Servers / Prompts / Settings…）
+- 文件镜像（从 Admin DB 同步出来，便于运行时读取）：
+  - `stateDir/auth/models.yaml`
+  - `stateDir/auth/mcp.config.json`
+  - `stateDir/auth/system-prompt.yaml`
+  - `stateDir/auth/*prompt*.yaml`
+
+原则：
+
+- **Secrets（API Keys）只存 DB**，不会明文同步到 yaml。
+- 运行前宿主会把 Secrets 写入 `process.env`（受 `override` 控制），Provider 通过 `apiKeyEnv` 取值。
+
+## UI Apps 插件目录（宿主扫描）
+
+宿主会扫描两个目录（并在 UI「应用」页展示实际路径）：
+
+- **内置/开发目录**：`deepseek_cli/ui_apps/plugins`
+- **用户插件目录**：`<stateDir>/ui_apps/plugins`（即 `~/.deepseek_cli/chatos/ui_apps/plugins`）
+
+同名 `plugin.id` 的覆盖规则：
+
+- 用户目录的插件会覆盖内置目录的同 `plugin.id` 插件（便于开发调试/热替换）。
+
+插件数据目录（供插件后端存放自己的持久化数据）：
+
+- `dataDir`：`<stateDir>/ui_apps/data/<pluginId>`
+- 插件后端的持久化数据写入目录为 `dataDir`；插件安装目录用于读取插件资源。
+
+## 插件包导入（目录或 .zip）
+
+桌面端 UI 支持：`应用` → `导入应用包` → 选择插件目录或 `.zip`。
+
+包结构要求：
+
+- `plugin.json` 在包根目录；或
+- 包根目录下一层目录中包含一个或多个插件目录（每个目录内有 `plugin.json`）。
+
+导入时的复制规则（重要）：
+
+- 会拷贝到用户插件目录 `~/.deepseek_cli/chatos/ui_apps/plugins/<sanitized(plugin.id)>/`；
+- 默认会排除：`node_modules/`、`.git/`、`.DS_Store`、`*.map`；
+- 因此若插件需要依赖，请在构建时做 bundle（不要指望随包携带 `node_modules` 生效）。
+
+## 安全边界与硬约束（协议的一部分）
+
+为避免插件越权读取宿主文件系统，宿主对“路径型字段”做了强约束：
+
+- `apps[i].entry.path` 必须位于插件目录内，且必须是文件（`module` 入口）。
+- `backend.entry` 必须位于插件目录内，且必须是文件。
+- `apps[i].ai.config`、`ai.mcp.entry`、`ai.mcpPrompt.*.path` 等所有 path 都必须位于插件目录内。
+
+尺寸限制（默认值，防止误导入超大文件）：
+
+- `plugin.json` 最大 `256 KiB`
+- `mcpPrompt` 内容最大 `128 KiB`（读取 path 或 inline content 都受限）
+
+## 最短接入路径（TL;DR）
+
+1) 从模板复制：`deepseek_cli/ui_apps/template/basic-plugin` → 放进任一插件目录  
+2) 修改 `plugin.json`：只支持 `apps[i].entry.type="module"`  
+3) 桌面端打开「应用」页 → 点“刷新” → 进入你的应用  
+4) （可选）需要 Node 能力：加 `backend.entry`，前端用 `host.backend.invoke()`  
+5) （可选）需要给 Agent 暴露工具/说明：配置 `apps[i].ai`（见 [`CHATOS_UI_APPS_AI_CONTRIBUTIONS.md`](./CHATOS_UI_APPS_AI_CONTRIBUTIONS.md)）
+
+提示：`ai.mcp` / `ai.mcpPrompt` 是否持久化写入 Admin DB，取决于宿主是否启用 `syncAiContributes`；即使不持久化，Agent 运行时也可以按 `apps[i].ai` 声明进行“临时注入”。
+
+## 实现位置（便于对照代码）
+
+- schema（`plugin.json` / `apps[i].ai`）：`deepseek_cli/electron/ui-apps/schemas.js`
+- 插件扫描/入口校验/AI 同步：`deepseek_cli/electron/ui-apps/index.js`
+- 应用包导入（目录/zip）：`deepseek_cli/electron/ui-apps/plugin-installer.js`
+- module 运行时 Host API 注入：`deepseek_cli/apps/ui/src/features/apps/AppsPluginView.jsx`
+
+## 原始文档来源（本次提取/整合）
+
+- `deepseek_cli/doc/app-dev-handbook.md`
+- `deepseek_cli/doc/app-integration.md`
+- `deepseek_cli/doc/ui-apps-plugins.md`
+- `deepseek_cli/doc/ui-apps-dev-guide.md`
+- `aide/shared/defaults/ui-apps-expose/README.md`