@agentunion/kite 1.5.0 → 1.6.1

package/docs/Evol/351/241/265/351/235/242/346/217/222/344/273/266/345/214/226-/345/244/226/351/203/250/346/250/241/345/235/227/346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -0,0 +1,468 @@
+# Evol 页面插件化 — 外部模块接入指南
+
+> 本文档面向 Kite 模块开发者，说明如何让你的模块在 Evol 控制台中拥有自己的页面入口。
+
+---
+
+## 一、总览
+
+你的模块只需要做两件事：
+
+1. **准备 UI 页面**（静态 HTML/JS/CSS）
+2. **发布一个事件**（`ui.page.register`）
+
+Evol 控制台会自动在侧边栏添加你的菜单项，用户点击后渲染你的页面。无需 import Evol 的任何代码。
+
+---
+
+## 二、接入方式选择
+
+| 方式 | 适用场景 | 你需要做什么 |
+|------|---------|-------------|
+| **iframe** | 你的模块已有 HTTP 服务 | 在现有服务上挂一个 UI 路由，注册时提供完整 URL |
+| **hosted** | 你的模块没有 HTTP 服务 | 把打包产物放在约定目录，Evol 代为 serve |
+
+---
+
+## 三、方式一：iframe 接入（模块自带 HTTP 服务）
+
+### 3.1 准备 UI 页面
+
+用任何技术栈开发，最终打包为静态文件，由你自己的 HTTP 服务 serve。
+
+**目录结构示例**：
+
+```
+extensions/services/model_service/
+├── entry.py
+├── server.py              ← 你的 FastAPI/Flask/Express 服务
+├── web/                   ← 前端源码（任意框架）
+│   ├── package.json
+│   ├── vite.config.ts
+│   └── src/
+│       └── App.vue        ← 或 App.tsx / index.html
+└── static/                ← 打包输出
+    ├── index.html
+    └── assets/
+```
+
+**Vite 打包配置**：
+
+```typescript
+// web/vite.config.ts
+export default {
+  build: {
+    outDir: '../static',
+  },
+}
+```
+
+**服务端挂载**（以 FastAPI 为例）：
+
+```python
+# server.py
+from starlette.staticfiles import StaticFiles
+from starlette.responses import FileResponse
+
+static_dir = Path(__file__).parent / "static"
+
+# 挂载静态资源
+app.mount("/ui/assets", StaticFiles(directory=str(static_dir / "assets")))
+
+# UI 入口
+@app.get("/ui")
+@app.get("/ui/{path:path}")
+async def serve_ui(path: str = ""):
+    return FileResponse(static_dir / "index.html")
+```
+
+### 3.2 发布注册事件
+
+在模块连接 Kernel 并发布 `module.ready` 之后，发布 `ui.page.register` 事件：
+
+```python
+import uuid
+
+async def register_ui_page(ws):
+    """注册 UI 页面到 Evol 控制台"""
+    await rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": "ui.page.register",
+        "data": {
+            "page_id": "model_service.dashboard",
+            "path": "/model-service",
+            "label": { "zh": "模型服务", "en": "Model Service" },
+            "icon": "Monitor",
+            "order": 100,
+            "type": "iframe",
+            "source": f"http://127.0.0.1:{my_port}/ui",
+            "requires_auth": True,
+        },
+    })
+```
+
+**`rpc_call` 参考实现**（如果你的模块还没有封装的话）：
+
+```python
+async def rpc_call(ws, method: str, params: dict) -> dict:
+    req_id = str(uuid.uuid4())
+    await ws.send(json.dumps({
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "method": method,
+        "params": params,
+    }))
+    # 等待响应（省略，参考 watchdog/entry.py 的 _rpc_call 实现）
+```
+
+### 3.3 完整时序
+
+```
+模块启动
+  ↓
+连接 Kernel WebSocket + 认证
+  ↓
+registry.register（注册 RPC 方法等）
+  ↓
+event.publish("module.ready")
+  ↓
+event.publish("ui.page.register")   ← 在 ready 之后
+  ↓
+Evol 收到 → 前端侧边栏出现菜单项
+  ↓
+用户点击 → iframe 加载你的 /ui 页面
+```
+
+---
+
+## 四、方式二：hosted 接入（Evol 代为托管）
+
+### 4.1 准备 UI 页面
+
+开发方式和 iframe 模式一样，但打包输出目录不同。
+
+**输出目录约定**（二选一）：
+
+```
+# 方式 A：放在模块源码目录下
+extensions/services/audit/
+├── entry.py
+└── ui/                      ← 打包产物放这里
+    ├── index.html
+    └── assets/
+
+# 方式 B：放在模块运行时数据目录下
+{KITE_INSTANCE_DIR}/audit/
+└── ui/
+    ├── index.html
+    └── assets/
+```
+
+**Vite 打包配置**（关键差异：必须配 `base`）：
+
+```typescript
+// web/vite.config.ts
+export default {
+  base: '/module-ui/audit/',    // 必须和模块名一致
+  build: {
+    outDir: '../ui',            // 输出到 ui/ 目录
+  },
+}
+```
+
+> `base` 配置至关重要。因为 Evol 会把你的静态文件挂载到 `/module-ui/{module_name}/` 路径下，所有资源引用（JS、CSS、图片）都需要基于这个前缀。
+
+### 4.2 发布注册事件
+
+```python
+await rpc_call(ws, "event.publish", {
+    "event_id": str(uuid.uuid4()),
+    "event": "ui.page.register",
+    "data": {
+        "page_id": "audit.logs",
+        "path": "/audit",
+        "label": { "zh": "审计日志", "en": "Audit Logs" },
+        "icon": "Document",
+        "order": 200,
+        "type": "hosted",          # 注意：不是 iframe
+        # source 不需要填，Evol 自动生成 /module-ui/audit/
+        "requires_auth": True,
+    },
+})
+```
+
+Evol 收到 `type == "hosted"` 的注册后，会自动查找模块的 `ui/` 目录并挂载静态文件服务。
+
+---
+
+## 五、注册事件数据字段说明
+
+### 5.1 `ui.page.register` 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page_id` | string | 是 | 页面唯一标识，建议格式 `{module_name}.{page_name}` |
+| `path` | string | 是 | 前端路由路径，如 `/model-service`，必须以 `/` 开头 |
+| `label` | `{zh, en}` | 是 | 显示名称，支持中英文 |
+| `icon` | string | 否 | Element Plus 图标名（如 `Monitor`、`Document`），默认 `Menu` |
+| `order` | number | 否 | 侧边栏排序，数字越小越靠前，默认 `100` |
+| `type` | string | 是 | `"iframe"` 或 `"hosted"` |
+| `source` | string | 条件必填 | `type == "iframe"` 时必填，完整的页面 URL |
+| `group` | string | 否 | 菜单分组名（预留，暂未实现） |
+| `badge` | string/number | 否 | 菜单角标内容 |
+| `requires_auth` | boolean | 否 | 是否需要登录，默认 `true` |
+
+### 5.2 `ui.page.deregister` 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page_id` | string | 是 | 要反注册的页面 ID |
+
+### 5.3 path 命名规范
+
+- 必须以 `/` 开头
+- 只允许小写字母、数字、连字符：`/[a-z0-9-]+`
+- 不允许嵌套路径（如 `/a/b/c`），一级路径即可
+- 不允许和 Evol 保留路径冲突：`/login`、`/account`、`/team`、`/credits`、`/ai-service`、`/commission`、`/api`、`/ws`、`/health`、`/status`、`/assets`、`/module-ui`
+
+---
+
+## 六、模块下线时的自动清理
+
+**你不需要手动反注册。** 当模块进程退出或 WebSocket 断开后，Evol 会自动：
+
+1. 收到 `module.offline` 事件
+2. 清理该模块注册的所有页面
+3. 通知前端移除菜单项
+
+但如果你想在运行时动态移除某个页面（比如功能禁用），可以主动发布 `ui.page.deregister`。
+
+---
+
+## 七、与 Evol 宿主通信（可选）
+
+如果你的 UI 页面需要和 Evol 控制台交互（获取用户信息、触发导航等），使用 `window.postMessage` 协议。
+
+### 7.1 接收宿主上下文
+
+Evol 会在 iframe 加载完成后向 iframe 发送上下文信息：
+
+```javascript
+// 在你的 UI 页面中监听
+window.addEventListener('message', (event) => {
+  // 安全校验：确保消息来自 Evol 宿主
+  if (event.data?.type === 'evol.context') {
+    const { user, theme, locale } = event.data.payload
+    // user: { phone, nickname, ... }
+    // theme: 'light' | 'dark'
+    // locale: 'zh' | 'en'
+  }
+})
+```
+
+### 7.2 请求宿主操作
+
+```javascript
+// 导航到其他页面
+window.parent.postMessage({
+  type: 'evol.navigate',
+  payload: { path: '/team' }
+}, '*')
+
+// 显示全局通知
+window.parent.postMessage({
+  type: 'evol.notify',
+  payload: {
+    title: '操作成功',
+    type: 'success',        // success | warning | error | info
+    message: '模型已部署'
+  }
+}, '*')
+
+// 更新角标
+window.parent.postMessage({
+  type: 'evol.badge',
+  payload: {
+    page_id: 'model_service.dashboard',
+    badge: 3               // 数字或字符串，null 清除
+  }
+}, '*')
+```
+
+### 7.3 通信协议汇总
+
+| 方向 | type | payload | 说明 |
+|------|------|---------|------|
+| Evol → iframe | `evol.context` | `{user, theme, locale}` | iframe 加载后自动推送 |
+| iframe → Evol | `evol.navigate` | `{path}` | 请求导航到指定路由 |
+| iframe → Evol | `evol.notify` | `{title, type, message}` | 显示 Element Plus 全局通知 |
+| iframe → Evol | `evol.badge` | `{page_id, badge}` | 更新侧边栏角标 |
+
+---
+
+## 八、UI 开发建议
+
+### 8.1 技术栈选择
+
+完全自由。以下是几种推荐方案：
+
+| 技术栈 | 适用场景 | 打包大小 |
+|--------|---------|---------|
+| **原生 HTML + CSS + JS** | 简单配置页面、状态面板 | 极小（几 KB） |
+| **Vue 3 + Element Plus** | 和 Evol 风格统一 | ~1.5 MB |
+| **React** | 团队偏好 React | ~200 KB |
+| **Svelte** | 追求极小体积 | ~30 KB |
+
+### 8.2 样式建议
+
+为了视觉一致性，建议模块 UI 页面：
+
+- 背景色使用 `#f5f7fa`（浅色）或 `#1a1a2e`（深色）
+- 主色调使用 `#409eff`（Element Plus 默认蓝）
+- 字体使用系统默认字体栈
+
+如果使用 Vue + Element Plus，可以和 Evol 保持完全一致的风格。
+
+### 8.3 响应式布局
+
+iframe 会占满 Evol 内容区的全部空间。你的页面应该：
+
+- 使用 `width: 100%; height: 100vh;` 或 `100%` 填满容器
+- 不要设置固定宽高
+- 考虑内容区大约在 `calc(100vw - 200px)` 宽度（减去侧边栏）
+
+---
+
+## 九、完整接入示例（Python 模块）
+
+以一个假设的 `audit` 模块为例，展示最小化接入流程：
+
+### 9.1 模块目录结构
+
+```
+extensions/services/audit/
+├── module.md              ← 模块声明
+├── entry.py               ← 模块入口
+└── ui/                    ← UI 静态文件（hosted 模式）
+    ├── index.html
+    └── style.css
+```
+
+### 9.2 最简 UI 页面（原生 HTML）
+
+```html
+<!-- ui/index.html -->
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>审计日志</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <h1>审计日志</h1>
+  <div id="log-list">加载中...</div>
+  <script>
+    // 接收 Evol 上下文
+    window.addEventListener('message', (e) => {
+      if (e.data?.type === 'evol.context') {
+        console.log('User:', e.data.payload.user)
+      }
+    })
+
+    // 加载数据（调用自己模块的 API 或通过 Kernel RPC）
+    fetch('/module-ui/audit/api/logs')
+      .then(r => r.json())
+      .then(data => {
+        document.getElementById('log-list').innerHTML =
+          data.map(log => `<div>${log.time} - ${log.action}</div>`).join('')
+      })
+  </script>
+</body>
+</html>
+```
+
+### 9.3 entry.py 中注册页面
+
+```python
+# 在 module.ready 之后
+async def _on_ready(ws):
+    # ... 其他 ready 逻辑 ...
+
+    # 注册 UI 页面
+    await _rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": "ui.page.register",
+        "data": {
+            "page_id": "audit.logs",
+            "path": "/audit",
+            "label": {"zh": "审计日志", "en": "Audit Logs"},
+            "icon": "Document",
+            "order": 200,
+            "type": "hosted",
+            "requires_auth": True,
+        },
+    })
+```
+
+完成。用户打开 Evol 控制台后，侧边栏会出现"审计日志"菜单项，点击后在内容区展示你的页面。
+
+---
+
+## 十、注册多个页面
+
+一个模块可以注册多个页面，每个页面独立的 `page_id` 和 `path`：
+
+```python
+pages = [
+    {
+        "page_id": "model_service.dashboard",
+        "path": "/model-service",
+        "label": {"zh": "模型服务", "en": "Model Service"},
+        "icon": "Monitor",
+        "order": 100,
+        "type": "iframe",
+        "source": f"http://127.0.0.1:{port}/ui/dashboard",
+    },
+    {
+        "page_id": "model_service.settings",
+        "path": "/model-settings",
+        "label": {"zh": "模型配置", "en": "Model Settings"},
+        "icon": "Setting",
+        "order": 101,
+        "type": "iframe",
+        "source": f"http://127.0.0.1:{port}/ui/settings",
+    },
+]
+
+for page in pages:
+    await _rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": "ui.page.register",
+        "data": {**page, "requires_auth": True},
+    })
+```
+
+---
+
+## 十一、常见问题
+
+**Q：模块重启后页面会消失吗？**
+
+A：模块下线时 Evol 会自动清理页面。模块重新 ready 后再次发布 `ui.page.register` 即可恢复。这是幂等操作。
+
+**Q：iframe 模式下，模块 UI 能调用 Kernel RPC 吗？**
+
+A：不能直接调用。模块 UI 应该通过自己模块的 HTTP API 来间接调用。或者通过 postMessage 请求 Evol 宿主代为调用（需要 Evol 侧实现对应的 handler）。
+
+**Q：hosted 模式下，模块 UI 的 API 请求发给谁？**
+
+A：hosted 模式只托管静态文件。如果模块 UI 需要 API，模块仍然需要自己的 HTTP 服务来提供 API 端点，UI 中的 fetch 请求直接指向模块的端口。或者完全依赖 Evol 的 RPC 转发接口 `POST /api/rpc/{method}`。
+
+**Q：我能注册一个带子路由的页面吗（如 `/audit/detail/:id`）？**
+
+A：当前设计只支持一级路由。子路由由你的 iframe 内部自行处理（hash 路由或 iframe 内的 Vue Router）。
+
+**Q：页面注册失败了怎么排查？**
+
+A：查看 Evol 模块日志 `{KITE_INSTANCE_DIR}/evol/log/latest.log`，搜索 `ui.page` 关键字。