@leeoohoo/ui-apps-devkit 0.1.0

package/templates/basic/docs/CHATOS_UI_APPS_PLUGIN_MANIFEST.md

@@ -0,0 +1,227 @@
+# ChatOS UI Apps：`plugin.json` 清单规范（协议）
+
+本文件定义 UI Apps 插件清单 `plugin.json` 的字段与约束，目标是让第三方/内置应用都能按统一契约被 ChatOS 扫描、加载与运行。
+
+实现对照（以代码为准）：
+
+- schema：`deepseek_cli/electron/ui-apps/schemas.js`
+- 扫描/校验：`deepseek_cli/electron/ui-apps/index.js`
+- 导入/安装：`deepseek_cli/electron/ui-apps/plugin-installer.js`
+
+另见：
+
+- [`CHATOS_UI_APPS_HOST_API.md`](./CHATOS_UI_APPS_HOST_API.md)（`module` 应用与宿主交互）
+- [`CHATOS_UI_APPS_BACKEND_PROTOCOL.md`](./CHATOS_UI_APPS_BACKEND_PROTOCOL.md)（插件后端）
+- [`CHATOS_UI_APPS_AI_CONTRIBUTIONS.md`](./CHATOS_UI_APPS_AI_CONTRIBUTIONS.md)（MCP/Prompt 暴露）
+
+## 1. 文件与安装位置
+
+- 每个插件一个目录，目录根部必须包含 `plugin.json`。
+- 插件目录可放在：
+  - `deepseek_cli/ui_apps/plugins`（内置/开发）
+  - `~/.deepseek_cli/chatos/ui_apps/plugins`（用户插件目录）
+- 也可通过桌面端 UI：`应用` → `导入应用包`（目录或 `.zip`）安装到用户插件目录。
+
+## 2. 顶层 schema（`uiAppsPluginSchema`）
+
+`plugin.json`（Top-level）字段：
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---:|---:|---|---|
+| `manifestVersion` | `number` | 否 | `1` | 目前仅支持 `1` |
+| `id` | `string` | 是 | - | 插件 ID（使用反向域名；稳定且全局唯一） |
+| `name` | `string` | 是 | - | 插件显示名称 |
+| `version` | `string` | 否 | `"0.0.0"` | 版本号（展示用途） |
+| `description` | `string` | 否 | `""` | 插件描述 |
+| `backend` | `object` | 否 | - | 插件后端（Electron main 进程） |
+| `apps` | `array` | 否 | `[]` | 插件内的应用列表 |
+
+`backend`：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|---:|---|
+| `backend.entry` | `string` | 是 | 后端入口模块路径（相对插件目录；必须在插件目录内且是文件） |
+
+## 3. apps schema（`uiAppSchema`）
+
+`apps[i]` 字段：
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---:|---:|---|---|
+| `id` | `string` | 是 | - | 应用 ID（同一插件内唯一） |
+| `name` | `string` | 是 | - | 应用显示名称 |
+| `description` | `string` | 否 | `""` | 描述 |
+| `icon` | `string` | 否 | `""` | 图标（当前实现以字符串透传为主） |
+| `entry` | `object` | 是 | - | 入口（仅支持 `module`） |
+| `ai` | `object|string` | 否 | - | AI 声明（MCP/Prompt/暴露列表等；详见下文） |
+
+### 3.1 `apps[i].entry`（仅支持 `module`）
+
+```json
+{ "type": "module", "path": "my-app/index.mjs" }
+```
+
+硬约束：
+
+- `entry.type` 必须为 `"module"`（ChatOS 不支持 `iframe/url`）。
+- `entry.path` 必须在插件目录内（宿主做路径边界校验），且必须是文件。
+
+## 4. `apps[i].ai` schema（`uiAppAiSchema`）
+
+`ai` 可以写成两种形式：
+
+1) **对象**（inline）：
+
+```json
+{
+  "ai": {
+    "mcpServers": true,
+    "prompts": true
+  }
+}
+```
+
+2) **字符串路径**（等价于 `{ "config": "<path>" }`）：
+
+```json
+{ "ai": "my-app/ai.yaml" }
+```
+
+对象形式还支持额外带一个 `config` 字段，用于从文件读取并与 inline 合并：
+
+```json
+{
+  "ai": {
+    "config": "my-app/ai.yaml",
+    "mcpServers": true,
+    "prompts": true
+  }
+}
+```
+
+所有 `ai` 的 path（`ai.config`、`ai.mcp.entry`、`ai.mcpPrompt.*.path`）都必须在插件目录内，且文件大小受限（默认最大 `128 KiB`）。
+
+### 4.1 `ai` 字段一览（`uiAppAiConfigSchema`）
+
+| 字段 | 类型 | 说明 |
+|---|---:|---|
+| `ai.mcp` | `object` | 声明并同步一个 MCP Server（`serverName` 固定派生为 `${pluginId}.${appId}`） |
+| `ai.mcpPrompt` | `string|object` | 声明并同步一个 system prompt（名称固定派生） |
+| `ai.mcpServers` | `true|false|string[]` | 暴露给 Agent 的 MCP servers 范围（聚合“已有的”资源） |
+| `ai.prompts` | `true|false|string[]` | 暴露给 Agent 的 prompts 范围（聚合“已有的”资源） |
+| `ai.agent` | `object` | 可选：应用提供的 Agent 模板（当前实现主要做透传/保留字段） |
+
+## 5. `ai.mcp`：MCP Server 声明
+
+`ai.mcp` 字段（当前 schema）：
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---:|---:|---|---|
+| `url` | `string` | 二选一 | - | 远程 MCP Server 地址（`http(s)://` / `ws(s)://` 等） |
+| `entry` | `string` | 二选一 | - | 本地脚本入口（相对插件目录）；宿主会转换为 `cmd://...` |
+| `command` | `string` | 否 | `"node"` | 拉起本地 `entry` 时使用的命令 |
+| `args` | `string[]` | 否 | `[]` | 拉起时追加参数 |
+| `description` | `string` | 否 | `""` | 描述 |
+| `tags` | `string[]` | 否 | `[]` | 标签（宿主还会自动附加 `uiapp*` 标签） |
+| `enabled` | `boolean` | 否 | - | 是否启用（未填则宿主同步时默认 `true`） |
+| `allowMain` | `boolean` | 否 | - | 是否允许主流程使用（未填则宿主同步时默认 `true`） |
+| `allowSub` | `boolean` | 否 | - | 是否允许子代理使用（未填则宿主同步时默认 `true`） |
+| `auth` | `object` | 否 | - | 认证信息（token/basic/headers） |
+
+强约束：
+
+- 必须提供 `url` 或 `entry` 其中之一（只写 `command` 不算有效配置）。
+
+`auth` 结构（均为可选，且支持 partial）：
+
+```json
+{
+  "auth": {
+    "token": "…",
+    "basic": { "username": "u", "password": "p" },
+    "headers": { "X-Foo": "bar" }
+  }
+}
+```
+
+当使用 `entry` 时，宿主会把它转换为可运行的 `cmd://`：
+
+- `command` 默认为 `node`
+- `args` 会追加到命令行末尾
+- 宿主会把空格/引号等做安全引用，以避免路径包含空格时解析失败
+
+## 6. `ai.mcpPrompt`：应用默认 Prompt 声明
+
+`ai.mcpPrompt` 支持两种写法：
+
+1) **字符串**：等价于中文 prompt 从该路径读取：
+
+```json
+{ "mcpPrompt": "my-app/mcp-prompt.zh.md" }
+```
+
+2) **对象**：可分别提供 `zh`/`en`，并支持 path 或 inline content：
+
+```json
+{
+  "mcpPrompt": {
+    "title": "My App · MCP Prompt",
+    "zh": "my-app/mcp-prompt.zh.md",
+    "en": { "path": "my-app/mcp-prompt.en.md" }
+  }
+}
+```
+
+`zh/en` 的“source”结构为：
+
+```json
+{ "path": "relative.md", "content": "inline markdown…" }
+```
+
+约束：
+
+- `mcpPrompt` 必须至少提供 `zh` 或 `en` 其一；
+- 若提供 `path`，必须在插件目录内且是文件；
+- 内容大小受限（默认最大 `128 KiB`）。
+
+## 7. `ai.mcpServers` / `ai.prompts`：聚合暴露范围
+
+- `true`：开启暴露（“具体暴露哪些”由 `ai.config` / 内置默认清单决定；否则表示全部）
+- `false`：禁用暴露
+- `string[]`：精确列出允许暴露的 `serverName` / `prompt name`
+
+注意：这里定义的是“在 Agent UI 中可选/可见的范围”，最终是否启用、启用哪些仍由 Agent 编辑页勾选决定。
+
+## 8. 最小示例
+
+### 8.1 最小可运行插件（仅 module）
+
+```json
+{
+  "manifestVersion": 1,
+  "id": "com.example.tools",
+  "name": "Example Tools",
+  "version": "0.1.0",
+  "apps": [
+    {
+      "id": "hello",
+      "name": "Hello App（Module）",
+      "entry": { "type": "module", "path": "hello/index.mjs" }
+    }
+  ]
+}
+```
+
+### 8.2 带后端 + MCP/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" }
+  }
+}
+```

package/templates/basic/docs/CHATOS_UI_PROMPTS_PROTOCOL.md

@@ -0,0 +1,392 @@
+# ChatOS UI Prompts（笑脸交互待办）协议
+
+UI Prompts 是 ChatOS 的全局交互队列：任意组件（AI / MCP / UI Apps）都通过向队列写入 `request` 记录来发起一次“需要用户输入/确认”的交互；用户在 UI（右下角笑脸面板）完成填写后，系统写入对应的 `response` 记录来结束该交互。
+
+本协议定义：
+
+- 存储格式：`ui-prompts.jsonl`（JSON Lines 追加日志）
+- 交互生命周期：`request` → `response`
+- UI 渲染支持的 `prompt.kind` 与字段（`kv` / `choice` / `task_confirm` / `file_change_confirm`）
+- UI Apps 的 Host API 调用方式（`host.uiPrompts.*`）
+
+实现对照（以代码为准）：
+
+- UI 渲染：`deepseek_cli/apps/ui/src/features/session/floating-island/FloatingIslandPrompt.jsx`
+- 笑脸面板：`deepseek_cli/apps/ui/src/components/UiPromptsSmileHub.jsx`
+- Host IPC：`deepseek_cli/electron/main.js`（`uiPrompts:*`）
+- 写入/读取日志：`aide/electron/session-api.js`（`requestUiPrompt` / `respondUiPrompt` / `readUiPromptsPayload`）
+- MCP `ui_prompter`：`aide/mcp_servers/ui-prompt-server.js`
+
+---
+
+## 1. 存储：`ui-prompts.jsonl`
+
+### 1.1 文件位置
+
+UI Prompts 以 JSONL 形式追加写入到：
+
+- `stateDir/ui-prompts.jsonl`
+
+其中 `stateDir` 为 ChatOS 的状态目录（宿主按 `hostApp` 做隔离；ChatOS 的 `hostApp=chatos`）。
+
+### 1.2 JSONL 记录类型
+
+每一行是一个 JSON 对象（以下简称 entry）。当前 UI Prompts 只消费：
+
+- `entry.type === "ui_prompt"`
+
+并按 `entry.action` 区分：
+
+- `entry.action === "request"`：发起交互
+- `entry.action === "response"`：结束交互
+
+### 1.3 Pending 判定（队列语义）
+
+UI 端的“待处理”集合由日志推导：
+
+- 对同一个 `requestId`，存在 `request` 但不存在 `response` 时，该交互处于 pending 状态；
+- 当出现 `response` 后，该交互从 pending 中移除；
+- 日志是追加写入，系统不删除旧行。
+
+---
+
+## 2. Host API（UI Apps 对接入口）
+
+UI Apps 的 `module` 应用通过 Host API 与 UI Prompts 交互：
+
+- `host.uiPrompts.read(): Promise<{ path: string, entries: any[] }>`
+- `host.uiPrompts.onUpdate((payload) => void): () => void`
+- `host.uiPrompts.request(payload): Promise<{ ok: true, requestId: string }>`
+- `host.uiPrompts.respond(payload): Promise<{ ok: true }>`
+- `host.uiPrompts.open()/close()/toggle()`
+
+`host.uiPrompts.request()` 在 `prompt.source` 为空时，会自动写入 `${pluginId}:${appId}`。
+
+### 2.1 `host.uiPrompts.request(payload)`
+
+`payload` 字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|---:|---|
+| `requestId` | `string` | 否 | 为空时宿主生成 |
+| `runId` | `string` | 否 | 透传到 entry，用于 UI 标识来源 run |
+| `prompt` | `object` | 是 | 交互定义（见第 4-8 节） |
+
+返回：
+
+- `{ ok: true, requestId }`（`requestId` 为最终使用的 ID）
+
+### 2.2 `host.uiPrompts.respond(payload)`
+
+`payload` 字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|---:|---|
+| `requestId` | `string` | 是 | 对应 `request` 的 `requestId` |
+| `runId` | `string` | 否 | 透传到 entry |
+| `response` | `object` | 是 | 必须包含 `response.status` |
+
+返回：
+
+- `{ ok: true }`
+
+---
+
+## 3. Entry 协议（写入 `ui-prompts.jsonl` 的数据结构）
+
+### 3.1 Request Entry
+
+```json
+{
+  "ts": "2026-01-11T00:00:00.000Z",
+  "type": "ui_prompt",
+  "action": "request",
+  "requestId": "uuid-or-app-generated-id",
+  "runId": "optional-run-id",
+  "prompt": { "...": "see below" }
+}
+```
+
+字段：
+
+- `ts`：ISO 时间字符串
+- `type`：固定为 `"ui_prompt"`
+- `action`：固定为 `"request"`
+- `requestId`：字符串；同一次交互的唯一 ID
+- `runId`：可选字符串；用于在 UI 中标识来源 run（显示为 Tag）
+- `prompt`：对象；由 `prompt.kind` 决定结构（见第 4 节）
+
+### 3.2 Response Entry
+
+```json
+{
+  "ts": "2026-01-11T00:00:10.000Z",
+  "type": "ui_prompt",
+  "action": "response",
+  "requestId": "uuid-or-app-generated-id",
+  "runId": "optional-run-id",
+  "response": { "...": "see below" }
+}
+```
+
+字段：
+
+- `ts`：ISO 时间字符串
+- `type`：固定为 `"ui_prompt"`
+- `action`：固定为 `"response"`
+- `requestId`：必须与对应 `request` 一致
+- `runId`：可选；用于标识来源 run
+- `response`：对象；必须包含 `response.status`
+
+---
+
+## 4. Prompt 协议（`prompt.kind`）
+
+### 4.1 通用字段（所有 kind 均可出现）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|---:|---|
+| `kind` | `string` | 是 | 取值：`kv` / `choice` / `task_confirm` / `file_change_confirm` |
+| `title` | `string` | 否 | UI 标题 |
+| `message` | `string` | 否 | UI 描述/说明 |
+| `source` | `string` | 否 | 来源标识（UI 显示 Tag） |
+| `allowCancel` | `boolean` | 否 | `false` 时 UI 不提供取消入口；其余情况允许取消 |
+
+---
+
+## 5. `kind="kv"`：键值表单（多字段输入）
+
+### 5.1 请求结构
+
+```json
+{
+  "kind": "kv",
+  "title": "需要你补充信息",
+  "message": "请填写表单后继续。",
+  "source": "com.example.plugin:my-app",
+  "allowCancel": true,
+  "fields": [
+    {
+      "key": "name",
+      "label": "姓名",
+      "description": "用于报告署名",
+      "placeholder": "请输入",
+      "default": "",
+      "required": true,
+      "multiline": false,
+      "secret": false
+    }
+  ]
+}
+```
+
+字段约束：
+
+- `fields`：数组，长度 `1..50`
+- `fields[].key`：字符串，非空且在 `fields` 内唯一
+- `fields[].label/description/placeholder/default`：可选字符串
+- `fields[].required/multiline/secret`：可选布尔
+
+UI 渲染规则：
+
+- `multiline=true` → 多行输入框（TextArea）
+- `secret=true` → 密码输入框（Password）
+- 否则 → 单行输入框（Input）
+
+### 5.2 响应结构
+
+```json
+{ "status": "ok", "values": { "name": "Alice" } }
+```
+
+- `status="ok"` 时，`values` 必须为对象，value 类型为 `string`
+- `status!="ok"` 时，`values` 字段不参与消费
+
+---
+
+## 6. `kind="choice"`：单选 / 多选
+
+### 6.1 请求结构（单选）
+
+```json
+{
+  "kind": "choice",
+  "title": "需要你做出选择",
+  "message": "请选择一项。",
+  "source": "com.example.plugin:my-app",
+  "allowCancel": true,
+  "multiple": false,
+  "options": [
+    { "value": "alpha", "label": "Alpha", "description": "选项说明" },
+    { "value": "beta", "label": "Beta", "description": "" }
+  ],
+  "default": "alpha",
+  "minSelections": 0,
+  "maxSelections": 2
+}
+```
+
+### 6.2 请求结构（多选）
+
+```json
+{
+  "kind": "choice",
+  "title": "需要你做出选择（多选）",
+  "message": "请选择 1-2 项。",
+  "allowCancel": true,
+  "multiple": true,
+  "options": [
+    { "value": "a", "label": "A" },
+    { "value": "b", "label": "B" },
+    { "value": "c", "label": "C" }
+  ],
+  "default": ["a"],
+  "minSelections": 1,
+  "maxSelections": 2
+}
+```
+
+字段约束：
+
+- `options`：数组，长度 `1..60`
+- `options[].value`：字符串，非空且在 `options` 内唯一
+- `options[].label/description`：可选字符串
+- `multiple`：布尔，缺省为 `false`
+- `default`：
+  - `multiple=false` → `string`
+  - `multiple=true` → `string[]`
+  - 默认值必须来自 `options[].value`
+- `minSelections/maxSelections`：
+  - `multiple=true` 时生效
+  - `minSelections`：整数，范围 `0..options.length`
+  - `maxSelections`：整数，范围 `1..options.length`
+  - `minSelections <= maxSelections`
+
+### 6.3 响应结构
+
+单选：
+
+```json
+{ "status": "ok", "selection": "alpha" }
+```
+
+多选：
+
+```json
+{ "status": "ok", "selection": ["a", "b"] }
+```
+
+`status!="ok"` 时，`selection` 字段不参与消费。
+
+---
+
+## 7. `kind="task_confirm"`：任务创建确认（复杂表单）
+
+该类型用于“任务列表的创建/编辑/排序确认”。UI 会渲染一组可编辑任务卡片，并在提交时返回任务数组。
+
+### 7.1 请求结构
+
+```json
+{
+  "kind": "task_confirm",
+  "title": "任务创建确认",
+  "message": "请确认任务列表。",
+  "allowCancel": true,
+  "source": "main",
+  "tasks": [
+    {
+      "draftId": "uuid",
+      "title": "写文档",
+      "details": "补齐 UI Prompts 协议",
+      "priority": "high",
+      "status": "todo",
+      "tags": ["docs", "ui-prompts"]
+    }
+  ],
+  "defaultRemark": ""
+}
+```
+
+字段：
+
+- `tasks`：可选数组（缺省为 `[]`）
+- `tasks[].draftId`：字符串；为空时系统会生成
+- `tasks[].title/details`：字符串
+- `tasks[].priority`：`high | medium | low`（缺省为 `medium`）
+- `tasks[].status`：`todo | doing | blocked | done`（缺省为 `todo`）
+- `tasks[].tags`：`string[]`
+- `defaultRemark`：可选字符串；用于初始化备注输入框
+
+### 7.2 响应结构
+
+```json
+{
+  "status": "ok",
+  "tasks": [
+    {
+      "draftId": "uuid",
+      "title": "写文档",
+      "details": "补齐 UI Prompts 协议",
+      "priority": "high",
+      "status": "todo",
+      "tags": ["docs", "ui-prompts"]
+    }
+  ],
+  "remark": "按这个列表创建即可"
+}
+```
+
+`status="ok"` 时，`tasks` 为数组；`remark` 为可选字符串。  
+`status!="ok"` 时，`tasks` 字段不参与消费；`remark` 可出现。
+
+---
+
+## 8. `kind="file_change_confirm"`：文件变更确认（复杂表单）
+
+该类型用于“文件变更/命令执行前确认”。UI 会渲染 diff/命令与路径信息，并在提交时返回 `remark`。
+
+### 8.1 请求结构
+
+```json
+{
+  "kind": "file_change_confirm",
+  "title": "文件变更确认",
+  "message": "即将写入文件。",
+  "allowCancel": true,
+  "source": "filesystem/write_file",
+  "path": "src/app.js",
+  "command": "node scripts/generate.js",
+  "cwd": "C:\\\\project\\\\aide",
+  "diff": "--- a/src/app.js\\n+++ b/src/app.js\\n@@ ...",
+  "defaultRemark": ""
+}
+```
+
+字段：
+
+- `path/command/cwd/diff/defaultRemark`：可选字符串
+
+### 8.2 响应结构
+
+```json
+{ "status": "ok", "remark": "继续执行" }
+```
+
+`remark` 为可选字符串；`status="ok"` 表示确认继续，其它 `status` 表示取消/中止。
+
+---
+
+## 9. 复杂交互的构建方式
+
+UI Prompts 的基本单位是一条 `request` 记录。复杂交互由多条 `request/response` 串联构成：
+
+1) 应用写入第 1 条 `request`（得到 `requestId`）  
+2) 应用监听 `host.uiPrompts.onUpdate`，在 entries 中定位同 `requestId` 的 `response`  
+3) 应用基于该 `response` 决定下一步，再写入下一条 `request`
+
+在该模型下：
+
+- “多字段表单”使用 `kind="kv"` 的 `fields[]` 承载
+- “多选/单选”使用 `kind="choice"` 的 `multiple/options` 承载
+- “任务列表确认”使用 `kind="task_confirm"` 承载
+- “diff/命令确认”使用 `kind="file_change_confirm"` 承载