@core-pilot/sdk 0.0.0-beta.1 → 0.0.0-beta.3

package/README.md

@@ -1,5 +1,185 @@
-# Vue 3 + TypeScript + Vite
+# @core-pilot/sdk
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+`@core-pilot/sdk` 是一个轻量级、框架无关的 JavaScript SDK，旨在帮助开发者快速将 AI 智能助手（Agent）能力集成到现有的 Web 应用中。
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+它提供了开箱即用的 UI 组件、标准化的通信协议抽象（Provider）、以及完善的事件交互机制（HITL），支持与后端 AI 引擎（如 CoreAgent、Dify 等）进行无缝对接。
+
+## 核心功能
+
+- **⚡️ 快速集成**：通过简单的配置即可挂载完整的 AI 对话界面。
+- **🔌 多协议支持**：内置 CoreAgent 协议支持，架构设计支持扩展 Dify 等其他 Provider。
+- **🔄 事件驱动**：提供 `subscribeEvent` 和 `triggerEvent` 接口，实现宿主应用与 Agent 之间的双向通信（Code Bridge）。
+- **🔐 鉴权管理**：支持 Client/Server 模式的 Token 管理。
+- **🎨 样式隔离**：自带样式（需引入 CSS），支持自定义挂载点。
+
+## 安装
+
+```bash
+# npm
+npm install @core-pilot/sdk
+
+# pnpm
+pnpm add @core-pilot/sdk
+
+# yarn
+yarn add @core-pilot/sdk
+```
+
+## 快速开始
+
+```typescript
+import { createCorePilot } from '@core-pilot/sdk';
+import '@core-pilot/sdk/dist/index.css'; // 引入样式
+
+// 1. 初始化 SDK 实例
+const pilot = createCorePilot({
+  // 基础配置
+  appId: 'your-app-id',
+  baseUrl: 'https://your-agent-api.com',
+  provider: 'coreagent', // 目前支持 'coreagent' | 'dify'
+  
+  // 鉴权配置
+  auth: {
+    mode: 'client', // 'client' | 'server'
+    token: 'your-api-secret-key',
+  },
+
+  // 挂载配置
+  mount: {
+    selector: '#agent-container', // 宿主应用中的 DOM 节点 ID
+  },
+  
+  // 调试模式
+  debug: true,
+});
+
+// 2. 挂载 UI
+pilot.mount();
+```
+
+## 功能指南 (按能力)
+
+### 1. 基础挂载与生命周期管理
+
+SDK 提供了完整的生命周期管理方法，允许你在单页应用 (SPA) 中灵活控制 Agent 的显示与销毁。
+
+```typescript
+// 挂载 UI 到指定节点
+pilot.mount();
+
+// 卸载 UI (清除 DOM 内容，但保留实例配置)
+pilot.unmount();
+
+// 重新加载 (可传入新配置，常用于切换租户或更新 Token)
+pilot.reload({
+  auth: {
+    mode: 'client',
+    token: 'new-token'
+  }
+});
+
+// 彻底销毁实例 (清除日志、订阅等)
+pilot.destroy();
+```
+
+### 2. 双向通信 (Code Bridge / HITL)
+
+这是 SDK 的核心能力之一。通过事件机制，Agent 可以控制宿主应用（例如：Agent 请求打开某个文件），宿主应用也可以向 Agent 发送隐式指令。
+
+#### 监听 Agent 事件 (Agent -> App)
+
+当 Agent 需要执行本地操作（如打开 IDE 文件、跳转页面）时，会下发自定义事件。
+
+> 另外的，针对action的类型，这里做如下的规范约定：
+>所有的操作action分为以下三种情况，及其对应的命名定义
+> 1. 通过sdk 与后端进行交互部分：**core_业务场景**
+> 2. 当前卡片组件纯前端交互（上一步，下一步）：**inner_业务场景** 
+> 3. 透传到sdk外部，供用户调用事件：**cust_业务场景**
+
+```typescript
+// 订阅事件
+pilot.subscribeEvent((event) => {
+  console.log('收到 Agent 事件:', event);
+  
+  // 示例：处理打开文件请求
+  if (event.type === 'open_file') {
+    const { filePath, line } = event.payload;
+    myEditor.open(filePath, line);
+  }
+});
+```
+
+#### 触发 Agent 行为 (App -> Agent)
+
+宿主应用可以主动触发 Agent 的某些行为，或者获取 Agent 的内部数据。目前支持的事件类型如下：
+
+| 事件类型 | 说明 |
+|------|------|
+| get_suggestion_questions | 获取推荐问题 |
+| get_conversation_list | 获取会话列表 |
+| get_message_history | 获取消息历史 |
+| submit_core_action | 提交核心业务场景 |
+| new_message | 打开新对话触发，用于重置消息历史 |
+| submit_message | 提交通过对话框输入的消息 |
+
+
+```typescript
+// 触发 SDK 内部行为
+pilot.triggerEvent({
+  action: 'get_suggestion_questions', // 示例：获取推荐问题
+  payload: {
+    // ... 具体的请求参数
+  }
+}).then(res => {
+  console.log('Result:', res);
+});
+```
+
+### 3. 鉴权配置 (Authentication)
+
+支持两种模式：
+
+- **Client Mode**: 直接在前端传入 API Key（仅用于开发或内网环境）。
+- **Server Mode**: 通过后端代理转发，前端不暴露 Key（推荐生产环境）。
+
+```typescript
+// Client Mode
+const pilot = createCorePilot({
+  // ...
+  auth: {
+    mode: 'client',
+    token: 'sk-xxxxxxxx',
+  }
+});
+
+// Server Mode (通常配合自定义的 AuthManager 或 Proxy Url)
+// 目前 SDK 内部会根据 mode 处理请求头的组装
+```
+
+### 4. 调试与日志
+
+开启 `debug` 模式后，SDK 会在控制台输出详细的运行日志，方便排查连接、鉴权和事件流问题。
+
+```typescript
+const pilot = createCorePilot({
+  // ...
+  debug: true, // 开启调试日志
+  eventTracker: {
+    url: 'https://monitor.example.com/log', // 可选：上报日志到服务器
+  }
+});
+```
+
+## API 参考
+
+### `CorePilotOptions`
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `appId` | string | 是 | Agent 应用 ID |
+| `baseUrl` | string | 否 | API 服务基础地址 |
+| `provider` | `'coreagent' \| 'dify'` | 是 | 协议提供商 |
+| `auth` | `AuthOptions` | 是 | 鉴权配置 `{ mode, token }` |
+| `mount` | `MountOptions` | 是 | 挂载配置 `{ selector, container? }` |
+| `debug` | boolean | 否 | 是否开启调试模式 |
+| `hitl` | boolean | 否 | 是否启用 Human-in-the-Loop 功能 |