kd-chatbot-ui-vue2 0.1.1 → 0.1.2

package/README.md

@@ -1,515 +1,554 @@
-# kd-chatbot-ui-vue2
-
-Vue **2.7** 智能体会话组件库（由 Vue3 包 `kd-chatbot-ui` 迁移）。
-
-请求鉴权由宿主传入 `request`，组件库不写死 token / 拦截器。
-
-| 模式 | 组件 | 适用场景 |
-|------|------|----------|
-| **适配（推荐同协议）** | `AgentChatAdaptPanel` | 流程与 interpret 相近：组件内调接口；地址、入参字段由宿主配置 |
-| **受控（完全自定义）** | `AgentChatPanel` | 路径/入参/出参都可能不同：宿主自己调接口，props 传 `sessions` |
-
----
-
-## 0. 与 Vue3 版差异（必读）
-
-| 项 | Vue3（`kd-chatbot-ui`） | Vue2（本包） |
-|----|-------------------------|--------------|
-| Vue | `^3.5` | `^2.7` |
-| UI | Element Plus | Element UI `^2.15` |
-| 状态 | Pinia `^3` | Pinia `^2.1` |
-| 气泡 / 输入框 | `vue-element-plus-x` | 包内 `ChatBubble` / `ChatSender` |
-| 历史栏双向绑定 | `v-model:history-open` | `:history-open.sync` |
-| 插件安装 | `app.use(plugin)` | `Vue.use(plugin)` |
-| 本地存储 key | `kdChatbotUi_v3` | `kdChatbotUi_vue2_v1`（与 Vue3 隔离） |
-
-**接口契约相同**：`request` / `endpoints` / `requestParams` / `reloadKey` / `responseFields` / `theme` 等与 Vue3 版一致。
-
----
-
-## 1. `AgentChatAdaptPanel`（优先阅读）
-
-组件内部完成：拉会话列表、创建会话、发问、轮询进度、取消、写 store。
-
-宿主只需要传：**请求函数**、**接口地址**、**传参映射**、**隔离维度**。
-
-### 1.1 最小用法
-
-```vue
-<template>
-  <div class="agent-chat-page">
-    <AgentChatAdaptPanel
-      :request="request"
-      :theme="theme"
-      :endpoints="endpoints"
-      :request-params="requestParams"
-      :reload-key="reloadKey"
-      :tips="agentTips"
-      :show-open-in-browser="false"
-    />
-  </div>
-</template>
-
-<script>
-import {
-  AgentChatAdaptPanel
-} from "kd-chatbot-ui-vue2";
-import "kd-chatbot-ui-vue2/style.css";
-import request from "@/utils/request";
-
-export default {
-  name: "AgentChatPage",
-  components: { AgentChatAdaptPanel },
-  data() {
-    return {
-      request,
-      theme: "light",
-      /** 快捷提示（多项）：value 文案 / content 发送内容 / type 提问类型 */
-      agentTips: [
-        {
-          id: "default_analysis",
-          value: "整体分析",
-          content: "请对动力学计算结果进行整体分析",
-          type: "default_analysis"
-        }
-      ],
-      endpoints: {
-        createSession: "/ds-dynamics-alg-service/interpret/sessions",
-        listSessions: "/ds-dynamics-alg-service/interpret/sessions",
-        history: "/ds-dynamics-alg-service/interpret/history/:sessionId",
-        ask: "/ds-dynamics-alg-service/interpret/chat/ask",
-        cancel: "/ds-dynamics-alg-service/interpret/chat/cancel",
-        progress: "/ds-dynamics-alg-service/interpret/chat/progress"
-      }
-    };
-  },
-  computed: {
-    wellboreId() {
-      return String(this.$store?.state?.well?.wellboreId || "");
-    },
-    mainId() {
-      return String(this.$store?.state?.well?.mainId || "");
-    },
-    tripId() {
-      return String(this.$store?.state?.well?.tripId || "");
-    },
-    reloadKey() {
-      return `${this.wellboreId}|${this.mainId}|${this.tripId}`;
-    },
-    /**
-     * 各接口真实传参。
-     * - 主应用字段：在闭包里直接取（wellboreId 等）
-     * - 包内字段：用参数 runtime（sessionId / taskId / content / type / since）
-     */
-    requestParams() {
-      const self = this;
-      return {
-        createSession: () => ({
-          body: {
-            wellbore_id: self.wellboreId,
-            main_id: self.mainId,
-            trip_id: self.tripId
-          }
-        }),
-        listSessions: () => ({
-          query: {
-            wellbore_id: self.wellboreId,
-            main_id: self.mainId,
-            trip_id: self.tripId
-          }
-        }),
-        history: runtime => ({
-          path: { sessionId: runtime.sessionId }
-        }),
-        ask: runtime => ({
-          body: {
-            wellbore_id: self.wellboreId,
-            main_id: self.mainId,
-            trip_id: self.tripId,
-            session_id: runtime.sessionId,
-            type: runtime.type,
-            content: runtime.content
-          }
-        }),
-        cancel: runtime => ({
-          body: { task_id: runtime.taskId }
-        }),
-        progress: runtime => ({
-          query: {
-            task_id: runtime.taskId,
-            since: runtime.since
-          }
-        })
-      };
-    }
-  }
-};
-</script>
-```
-
-> 不必再传 `:context`。主应用字段写在 `requestParams` 闭包里即可。  
-> `endpoints` 已是完整路径（以 `/` 开头）时，不必再传 `base-url`。  
-> 宿主需已安装并注册 **Pinia**、**Element UI**。
-
-### 1.2 Props
-
-| 模板属性 | 类型 | 说明 |
-|----------|------|------|
-| `request` | `AgentChatRequestFn` | 宿主请求函数（带 token）。不传则用 `fetch`（无鉴权） |
-| `base-url` | `string` | 可选统一前缀。`endpoints` 已给完整路径时可省略。模板写 `base-url`（不要写成 `baseURL`） |
-| `endpoints` | `AgentChatEndpoints` | 各接口路径。以 `/` 开头视为站点绝对路径，不再拼 `base-url` |
-| `request-params` | `AgentChatRequestParams` | **各接口传参映射**（主应用字段 + 包内 runtime） |
-| `reload-key` | `string \| number` | 井/趟等维度变化时重拉会话。建议传 `` `${wellboreId}|${mainId}|${tripId}` `` |
-| `response-fields` | `AgentChatResponseFields` | 响应字段名。默认 `session_id` / `task_id` / `code === "OK"` |
-| `theme` | `"light" \| "dark" \| "gray" \| "white"` | 面板主题；`white` 按 `light` 处理 |
-| `tips` | `AgentChatTip[]` | 底部快捷提示（**多项**）。每项：`value` 文案、`content` 发送内容、`type` 提问类型。不传则用默认「整体分析」。样式已 `flex-wrap`，多了会换行 |
-| `show-open-in-browser` | `boolean` | 是否显示「浏览器打开」，默认 `true` |
-| `poll-interval-ms` | `number` | 进度轮询间隔，默认 `500` |
-| `context` | `AgentChatContext` | **已不推荐**。仅兼容旧写法；新接入请用 `request-params` |
-| `required-context` | `string[]` | 仅在仍使用 `context` 时做必填校验 |
-
-### 1.3 Events
-
-| 事件 | 说明 |
-|------|------|
-| `open-browser` | 点击「浏览器打开」。其它交互（发送/切会话/取消）由面板内部处理；新开页由宿主自行 `window.open` |
-
-### 1.3.1 `tips` 快捷提示（多项、字段均可动态）
-
-```js
-agentTips: [
-  {
-    id: "default_analysis",
-    value: "整体分析",                         // 按钮文案
-    content: "请对动力学计算结果进行整体分析", // 发送内容
-    type: "default_analysis"                   // ask.type
-  }
-  // 继续追加即可
-]
-```
-
-模板：`:tips="agentTips"`。也可 `import { DEFAULT_AGENT_CHAT_TIPS } from "kd-chatbot-ui-vue2"` 再改。
-
-### 1.4 两套字段从哪里来
-
-| 来源 | 例子 | 怎么写进请求 |
-|------|------|----------------|
-| **主应用** | `wellboreId`、`mainId`、`tripId` | 在 `requestParams` **闭包里直接取** |
-| **包内 runtime** | `sessionId`、`taskId`、`content`、`type`、`since` | mapper 的参数 `runtime` |
-
-`runtime` 由包在发请求前组装，宿主**不用**自己存 `sessionId`：
-
-1. 调创建会话 / 拉列表后，包从响应里读出 `session_id`（字段名可由 `response-fields` 改）
-2. 写入包内 store：`sessions[].id` + `activeId`
-3. 用户发送时取出当前会话 id，连同 `content`、`type` 放进 `runtime`
-4. 调用你写的 mapper，例如 `session_id: runtime.sessionId`
-
-`taskId` 同理：来自 ask / history 响应，用于 cancel、progress。
-
-### 1.5 `requestParams` 返回结构
-
-```ts
-type AgentChatParamMapper = (
-  runtime: AgentChatCallRuntime
-) => {
-  path?: Record<string, unknown>;  // 替换 URL 里的 :name / {name}
-  query?: Record<string, unknown>; // GET 查询参数
-  body?: Record<string, unknown>;  // POST body
-};
-```
-
-| 接口 key | 常用写法 |
-|----------|----------|
-| `createSession` | `body`：主应用隔离字段 |
-| `listSessions` | `query`：主应用隔离字段 |
-| `history` | `path: { sessionId: runtime.sessionId }` 填 `:sessionId` |
-| `ask` | `body`：主应用字段 + `runtime.sessionId/type/content` |
-| `cancel` | `body: { task_id: runtime.taskId }` |
-| `progress` | `query: { task_id, since }` |
-
-只写需要改的接口；未写的接口仍走包内默认 interpret 字段。
-
-### 1.6 换项目时怎么改
-
-**只换字段名：**
-
-```js
-ask: runtime => ({
-  body: {
-    wellId: this.wellId,            // 你们自己的主应用字段
-    chatId: runtime.sessionId,      // 包内 sessionId → 你们的 chatId
-    msg: runtime.content
-  }
-})
-```
-
-**路径占位也不同：**
-
-```js
-// endpoints
-history: "/xxx/history/:conversationId"
-
-// requestParams
-history: runtime => ({
-  path: { conversationId: runtime.sessionId }
-})
-```
-
-**响应字段不同：**
-
-```vue
-<AgentChatAdaptPanel
-  :response-fields="{ sessionId: 'id', taskId: 'taskId', okValue: 0 }"
-  ...
-/>
-```
-
-包读出后仍放入 `runtime.sessionId` / `runtime.taskId`，后续映射不变。
-
-### 1.7 `endpoints` 路径规则
-
-- `http(s)://...`：原样使用
-- 以 `/` 开头的覆盖路径：站点绝对路径，**不拼** `base-url`
-- 其它相对路径：拼在 `base-url` 后面
-- `history` 支持 `:sessionId` 或 `{sessionId}`（或你在 `path` 里声明的其它占位名）
-
-### 1.8 约定接口（相对默认）
-
-未覆盖 `endpoints` 时，相对 `base-url`：
-
-- `POST /sessions` — 创建会话
-- `GET /sessions` — 会话列表
-- `GET /history/:sessionId` — 历史
-- `POST /chat/ask` — 提问（返回 `task_id`）
-- `POST /chat/cancel` — 取消
-- `GET /chat/progress` — 轮询进度
-
-默认成功码：`code === "OK"`。
-
----
-
-## 2. `AgentChatPanel`（受控模式）
-
-宿主自己调接口，用 props 传入展示数据；用户操作通过事件抛回宿主。
-
-### 2.1 Props / Events
-
-| Props | 说明 |
-|-------|------|
-| `sessions` | `AgentSession[]` |
-| `active-id` | 当前会话 id |
-| `history-open` | 历史侧栏；用 **`:history-open.sync`**（不要用 `v-model:history-open`） |
-| `is-replying` | 是否回复中 |
-| `tips` / `theme` / `show-open-in-browser` | 同适配面板 |
-
-| Events | 说明 |
-|--------|------|
-| `send` | `(payload: { text, type?, tip? })` |
-| `select-session` | `(sessionId)` |
-| `create-session` | 新建 |
-| `cancel-reply` | 停止生成 |
-| `clear-session` | 清空当前会话 |
-| `update:historyOpen` | 切换历史栏（配合 `.sync`） |
-| `open-browser` | 浏览器打开 |
-
-### 2.2 示例
-
-```vue
-<template>
-  <AgentChatPanel
-    :sessions="sessions"
-    :active-id="activeId"
-    :history-open.sync="historyOpen"
-    :is-replying="isReplying"
-    @send="onSend"
-    @select-session="onSelect"
-    @create-session="onCreate"
-    @cancel-reply="onCancel"
-    @clear-session="onClear"
-  />
-</template>
-
-<script>
-import { AgentChatPanel } from "kd-chatbot-ui-vue2";
-import "kd-chatbot-ui-vue2/style.css";
-
-export default {
-  components: { AgentChatPanel },
-  data() {
-    return {
-      sessions: [],
-      activeId: "",
-      historyOpen: false,
-      isReplying: false
-    };
-  },
-  methods: {
-    async onSend({ text, type }) {
-      this.isReplying = true;
-      // 调你们自己的接口，写入 sessions
-      this.isReplying = false;
-    },
-    onSelect(id) {
-      this.activeId = id;
-    },
-    onCreate() {},
-    onCancel() {},
-    onClear() {}
-  }
-};
-</script>
-```
-
-会话消息结构：
-
-```ts
-interface AgentSession {
-  id: string;
-  title: string;
-  content: AgentMessage[];
-  pinned?: boolean;
-  badge?: number;
-  updatedAt?: number;
-  snippet?: string;
-}
-
-interface AgentMessage {
-  type: "ask" | "answer";
-  placement: "start" | "end";
-  content: string;
-  segments?: { type: "reasoning" | "answer"; content: string }[];
-}
-```
-
-流式回复：持续更新当前会话最后一条 `answer.segments`，再通过 `:sessions` 传入即可。
-
----
-
-## 3. 安装与依赖
-
-### 3.1 安装
-
-```bash
-npm i kd-chatbot-ui-vue2
-# 或 yarn / pnpm
-```
-
-本地联调（file 依赖示例）：
-
-```json
-"kd-chatbot-ui-vue2": "file:../agent-chat-components-vue2"
-```
-
-修改组件库后需在组件库目录执行 `npm run build`，宿主侧必要时重新安装该依赖。
-
-### 3.2 Peer 依赖
-
-| 包 | 版本参考 |
-|----|----------|
-| `vue` | `^2.7` |
-| `vue-template-compiler` | 与 `vue` 同版本 |
-| `pinia` | `^2.1`（需配合 Vue 2.7） |
-| `element-ui` | `^2.15` |
-| `echarts` | `^5.5` |
-| `marked` | `^15` / `^16` / `^18` |
-| `dompurify` | `^3` |
-
-宿主入口示例：
-
-```js
-import Vue from "vue";
-import ElementUI from "element-ui";
-import "element-ui/lib/theme-chalk/index.css";
-import { createPinia, PiniaVuePlugin } from "pinia";
-import KdChatbotUi from "kd-chatbot-ui-vue2";
-import "kd-chatbot-ui-vue2/style.css";
-
-Vue.use(ElementUI);
-Vue.use(PiniaVuePlugin);
-Vue.use(KdChatbotUi); // 可选：全局注册 KdChatPanel / KdChatAdaptPanel / KdChatView
-
-const pinia = createPinia();
-
-new Vue({
-  pinia,
-  render: h => h(App)
-}).$mount("#app");
-```
-
-也可不 `Vue.use(KdChatbotUi)`，在页面里按需：
-
-```js
-import { AgentChatAdaptPanel } from "kd-chatbot-ui-vue2";
-```
-
-### 3.3 样式
-
-```js
-import "kd-chatbot-ui-vue2/style.css";
-```
-
----
-
-## 4. 导出一览
-
-```ts
-import {
-  AgentChatAdaptPanel,
-  AgentChatPanel,
-  AgentChatView,
-  useAgentChat,
-  useAgentChatStore,
-  createAgentChatClient,
-  buildInterpretContext,
-  INTERPRET_POLL_INTERVAL_MS
-} from "kd-chatbot-ui-vue2";
-
-import type {
-  AgentChatEndpoints,
-  AgentChatRequestParams,
-  AgentChatRequestFn,
-  AgentChatCallRuntime,
-  AgentChatResponseFields,
-  AgentChatContext,
-  AgentSession,
-  AgentMessage,
-  AgentChatTip,
-  AgentChatSendPayload,
-  AgentChatTheme
-} from "kd-chatbot-ui-vue2";
-```
-
-默认导出为 Vue 插件：`Vue.use(KdChatbotUi)`。
-
----
-
-## 5. 打包与发布
-
-```bash
-cd agent-chat-components-vue2
-npm install
-npm run build   # 输出 dist/kd-chatbot-ui.js、kd-chatbot-ui.css、类型声明
-```
-
-发布：
-
-```bash
-npm publish     # prepublishOnly 会先 build
-```
-
----
-
-## 6. 怎么选模式
-
-- 后端仍是「会话 + ask + progress 轮询」这一套，只是路径/字段名不同 → **`AgentChatAdaptPanel`** + `endpoints` + `requestParams`
-- 协议完全不同，或宿主已有完整编排 → **`AgentChatPanel`**，自己管接口与 `sessions`
-
-Vue3 项目请用姊妹包 `kd-chatbot-ui`，不要混用本包。
-
----
-
-## 7. 版本
-
-- 包名：`kd-chatbot-ui-vue2`
-- 版本：见 `package.json` 的 `version`
-- License：MIT
+# kd-chatbot-ui-vue2
+
+Vue **2.7** 智能体会话组件库。与姊妹包 [`kd-chatbot-ui`](../kd-chatbot-ui)（Vue 3）接口契约对齐；请求鉴权由宿主传入 `request`，组件库不写死 token / baseURL。
+
+本包位于 Monorepo：`agent-chat-components/packages/kd-chatbot-ui-vue2`。
+
+| 模式 | 组件 | 适用场景 |
+|------|------|----------|
+| **适配（推荐）** | `AgentChatAdaptPanel` | 流程与 interpret 相近：组件内调接口；路径与入参由宿主配置 |
+| **受控** | `AgentChatPanel` | 协议完全自定义：宿主自己调接口，用 props 传入 `sessions` |
+
+---
+
+## 目录
+
+1. [与 Vue3 版差异](#0-与-vue3-版差异必读)
+2. [安装与依赖](#1-安装与依赖)
+3. [AgentChatAdaptPanel](#2-agentchatadaptpanel推荐)
+4. [AgentChatPanel](#3-agentchatpanel受控模式)
+5. [导出一览](#4-导出一览)
+6. [开发与发布](#5-开发与发布)
+7. [怎么选模式](#6-怎么选模式)
+
+---
+
+## 0. 与 Vue3 版差异（必读）
+
+| 项 | Vue3（`kd-chatbot-ui`） | Vue2（本包） |
+|----|-------------------------|--------------|
+| 包名 | `kd-chatbot-ui` | `kd-chatbot-ui-vue2` |
+| Vue | `^3.5` | `^2.7`（不支持 2.6 及更早） |
+| UI | Element Plus | Element UI `^2.15` |
+| 状态 | Pinia `^3` | Pinia `^2.1` |
+| 气泡 / 输入框 | `vue-element-plus-x` | 包内 `ChatBubble` / `ChatSender` |
+| 历史栏双向绑定 | `v-model:history-open` | `:history-open.sync` |
+| 插件安装 | `app.use(plugin)` | `Vue.use(plugin)` |
+| 本地存储 key | `kdChatbotUi_v3` | `kdChatbotUi_vue2_v1`（与 Vue3 隔离） |
+
+**接口契约相同**：`request` / `endpoints` / `requestParams` / `reloadKey` / `responseFields` / `theme` / `tips` 等与 Vue3 版一致。  
+**不要**在同一个 Vue 应用里同时安装两套包。
+
+---
+
+## 1. 安装与依赖
+
+### 1.1 安装
+
+```bash
+npm i kd-chatbot-ui-vue2
+# 或 yarn / pnpm
+```
+
+本地联调（指向 Monorepo 内本包）：
+
+```json
+{
+  "dependencies": {
+    "kd-chatbot-ui-vue2": "link:../agent-chat-components/packages/kd-chatbot-ui-vue2"
+  }
+}
+```
+
+修改源码后，在 Monorepo 根目录执行：
+
+```bash
+pnpm build:vue2
+```
+
+宿主侧如未热更新到最新 `dist`，可再执行一次 `pnpm install` / 重启开发服务。
+
+### 1.2 Peer 依赖
+
+| 包 | 版本 |
+|----|------|
+| `vue` | `^2.7` |
+| `vue-template-compiler` | 与 `vue` **同版本** |
+| `pinia` | `^2.1`（配合 Vue 2.7） |
+| `element-ui` | `^2.15` |
+| `echarts` | `^5.5` |
+| `marked` | `^15` / `^16` / `^18` |
+| `dompurify` | `^3` |
+
+### 1.3 宿主入口
+
+```js
+import Vue from "vue";
+import ElementUI from "element-ui";
+import "element-ui/lib/theme-chalk/index.css";
+import { createPinia, PiniaVuePlugin } from "pinia";
+import KdChatbotUi from "kd-chatbot-ui-vue2";
+import "kd-chatbot-ui-vue2/style.css";
+
+Vue.use(ElementUI);
+Vue.use(PiniaVuePlugin);
+Vue.use(KdChatbotUi); // 可选：全局注册 KdChatPanel / KdChatAdaptPanel / KdChatView
+
+const pinia = createPinia();
+
+new Vue({
+  pinia,
+  render: h => h(App)
+}).$mount("#app");
+```
+
+也可不 `Vue.use`，在页面内按需引入：
+
+```js
+import { AgentChatAdaptPanel } from "kd-chatbot-ui-vue2";
+import "kd-chatbot-ui-vue2/style.css";
+```
+
+---
+
+## 2. `AgentChatAdaptPanel`（推荐）
+
+组件内部完成：拉会话列表、创建会话、发问、轮询进度、取消、写 store。  
+宿主只需传：**请求函数**、**接口地址**、**传参映射**、**隔离维度**。
+
+### 2.1 最小用法
+
+```vue
+<template>
+  <div class="agent-chat-page">
+    <AgentChatAdaptPanel
+      :request="request"
+      :theme="theme"
+      :endpoints="endpoints"
+      :request-params="requestParams"
+      :reload-key="reloadKey"
+      :tips="agentTips"
+      :show-open-in-browser="false"
+    />
+  </div>
+</template>
+
+<script>
+import { AgentChatAdaptPanel } from "kd-chatbot-ui-vue2";
+import "kd-chatbot-ui-vue2/style.css";
+import request from "@/utils/request";
+
+export default {
+  name: "AgentChatPage",
+  components: { AgentChatAdaptPanel },
+  data() {
+    return {
+      request,
+      theme: "light",
+      /** 快捷提示（多项）：value 文案 / content 发送内容 / type 提问类型 */
+      agentTips: [
+        {
+          id: "default_analysis",
+          value: "整体分析",
+          content: "请对动力学计算结果进行整体分析",
+          type: "default_analysis"
+        }
+      ],
+      endpoints: {
+        createSession: "/ds-dynamics-alg-service/interpret/sessions",
+        listSessions: "/ds-dynamics-alg-service/interpret/sessions",
+        history: "/ds-dynamics-alg-service/interpret/history/:sessionId",
+        ask: "/ds-dynamics-alg-service/interpret/chat/ask",
+        cancel: "/ds-dynamics-alg-service/interpret/chat/cancel",
+        progress: "/ds-dynamics-alg-service/interpret/chat/progress"
+      }
+    };
+  },
+  computed: {
+    wellboreId() {
+      return String(this.$store?.state?.well?.wellboreId || "");
+    },
+    mainId() {
+      return String(this.$store?.state?.well?.mainId || "");
+    },
+    tripId() {
+      return String(this.$store?.state?.well?.tripId || "");
+    },
+    reloadKey() {
+      return `${this.wellboreId}|${this.mainId}|${this.tripId}`;
+    },
+    /**
+     * 各接口真实传参。
+     * - 主应用字段：在闭包里直接取（wellboreId 等）
+     * - 包内字段：用参数 runtime（sessionId / taskId / content / type / since）
+     */
+    requestParams() {
+      const self = this;
+      return {
+        createSession: () => ({
+          body: {
+            wellbore_id: self.wellboreId,
+            main_id: self.mainId,
+            trip_id: self.tripId
+          }
+        }),
+        listSessions: () => ({
+          query: {
+            wellbore_id: self.wellboreId,
+            main_id: self.mainId,
+            trip_id: self.tripId
+          }
+        }),
+        history: runtime => ({
+          path: { sessionId: runtime.sessionId }
+        }),
+        ask: runtime => ({
+          body: {
+            wellbore_id: self.wellboreId,
+            main_id: self.mainId,
+            trip_id: self.tripId,
+            session_id: runtime.sessionId,
+            type: runtime.type,
+            content: runtime.content
+          }
+        }),
+        cancel: runtime => ({
+          body: { task_id: runtime.taskId }
+        }),
+        progress: runtime => ({
+          query: {
+            task_id: runtime.taskId,
+            since: runtime.since
+          }
+        })
+      };
+    }
+  }
+};
+</script>
+```
+
+说明：
+
+- 不必再传 `:context`；主应用字段写在 `requestParams` 闭包里即可。
+- `endpoints` 已是完整路径（以 `/` 开头）时，不必再传 `base-url`。
+- 宿主需已安装并注册 **Pinia**、**Element UI**。
+
+### 2.2 Props
+
+| 模板属性 | 类型 | 说明 |
+|----------|------|------|
+| `request` | `AgentChatRequestFn` | 宿主请求函数（带 token）。不传则用 `fetch`（无鉴权） |
+| `base-url` | `string` | 可选统一前缀。`endpoints` 已给完整路径时可省略。模板写 `base-url`（不要写成 `baseURL`） |
+| `endpoints` | `AgentChatEndpoints` | 各接口路径。以 `/` 开头视为站点绝对路径，不再拼 `base-url` |
+| `request-params` | `AgentChatRequestParams` | 各接口传参映射（主应用字段 + 包内 runtime） |
+| `reload-key` | `string \| number` | 井/趟等维度变化时重拉会话。建议 `` `${wellboreId}|${mainId}|${tripId}` `` |
+| `response-fields` | `AgentChatResponseFields` | 响应字段名。默认 `session_id` / `task_id` / `code === "OK"` |
+| `theme` | `"light" \| "dark" \| "gray" \| "white"` | 面板主题；`white` 按 `light` 处理 |
+| `tips` | `AgentChatTip[]` | 底部快捷提示（多项）。每项：`value` 文案、`content` 发送内容、`type` 提问类型。不传则用默认「整体分析」 |
+| `show-open-in-browser` | `boolean` | 是否显示「浏览器打开」，默认 `true` |
+| `poll-interval-ms` | `number` | 进度轮询间隔，默认 `500` |
+| `context` | `AgentChatContext` | **已不推荐**。仅兼容旧写法；新接入请用 `request-params` |
+| `required-context` | `string[]` | 仅在仍使用 `context` 时做必填校验 |
+
+### 2.3 Events
+
+| 事件 | 说明 |
+|------|------|
+| `open-browser` | 点击「浏览器打开」。发送 / 切会话 / 取消由面板内部处理；新开页由宿主自行 `window.open` |
+
+### 2.4 `tips` 快捷提示
+
+```js
+agentTips: [
+  {
+    id: "default_analysis",
+    value: "整体分析",                         // 按钮文案
+    content: "请对动力学计算结果进行整体分析", // 发送内容
+    type: "default_analysis"                   // ask.type
+  }
+  // 继续追加即可
+]
+```
+
+也可：
+
+```js
+import { DEFAULT_AGENT_CHAT_TIPS } from "kd-chatbot-ui-vue2";
+```
+
+### 2.5 两套字段从哪里来
+
+| 来源 | 例子 | 怎么写进请求 |
+|------|------|----------------|
+| **主应用** | `wellboreId`、`mainId`、`tripId` | 在 `requestParams` **闭包里直接取** |
+| **包内 runtime** | `sessionId`、`taskId`、`content`、`type`、`since` | mapper 的参数 `runtime` |
+
+`runtime` 由包在发请求前组装，宿主**不用**自己存 `sessionId`：
+
+1. 创建会话 / 拉列表后，包从响应读出 `session_id`（字段名可由 `response-fields` 改）
+2. 写入包内 store：`sessions[].id` + `activeId`
+3. 用户发送时取出当前会话 id，连同 `content`、`type` 放进 `runtime`
+4. 调用你写的 mapper，例如 `session_id: runtime.sessionId`
+
+`taskId` 同理：来自 ask / history 响应，用于 cancel、progress。
+
+### 2.6 `requestParams` 返回结构
+
+```ts
+type AgentChatParamMapper = (
+  runtime: AgentChatCallRuntime
+) => {
+  path?: Record<string, unknown>;  // 替换 URL 里的 :name / {name}
+  query?: Record<string, unknown>; // GET 查询参数
+  body?: Record<string, unknown>;  // POST body
+};
+```
+
+| 接口 key | 常用写法 |
+|----------|----------|
+| `createSession` | `body`：主应用隔离字段 |
+| `listSessions` | `query`：主应用隔离字段 |
+| `history` | `path: { sessionId: runtime.sessionId }` 填 `:sessionId` |
+| `ask` | `body`：主应用字段 + `runtime.sessionId/type/content` |
+| `cancel` | `body: { task_id: runtime.taskId }` |
+| `progress` | `query: { task_id, since }` |
+
+只写需要改的接口；未写的接口仍走包内默认 interpret 字段。
+
+### 2.7 换项目时怎么改
+
+**只换字段名：**
+
+```js
+ask: runtime => ({
+  body: {
+    wellId: this.wellId,       // 你们自己的主应用字段
+    chatId: runtime.sessionId, // 包内 sessionId → 你们的 chatId
+    msg: runtime.content
+  }
+})
+```
+
+**路径占位也不同：**
+
+```js
+// endpoints
+history: "/xxx/history/:conversationId"
+
+// requestParams
+history: runtime => ({
+  path: { conversationId: runtime.sessionId }
+})
+```
+
+**响应字段不同：**
+
+```vue
+<AgentChatAdaptPanel
+  :response-fields="{ sessionId: 'id', taskId: 'taskId', okValue: 0 }"
+  ...
+/>
+```
+
+包读出后仍放入 `runtime.sessionId` / `runtime.taskId`，后续映射不变。
+
+### 2.8 `endpoints` 路径规则
+
+- `http(s)://...`：原样使用
+- 以 `/` 开头：站点绝对路径，**不拼** `base-url`
+- 其它相对路径：拼在 `base-url` 后面
+- `history` 支持 `:sessionId` 或 `{sessionId}`（或你在 `path` 里声明的其它占位名）
+
+### 2.9 约定接口（未覆盖 `endpoints` 时）
+
+相对 `base-url`：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `POST` | `/sessions` | 创建会话 |
+| `GET` | `/sessions` | 会话列表 |
+| `GET` | `/history/:sessionId` | 历史 |
+| `POST` | `/chat/ask` | 提问（返回 `task_id`） |
+| `POST` | `/chat/cancel` | 取消 |
+| `GET` | `/chat/progress` | 轮询进度 |
+
+默认成功码：`code === "OK"`。
+
+---
+
+## 3. `AgentChatPanel`（受控模式）
+
+宿主自己调接口，用 props 传入展示数据；用户操作通过事件抛回宿主。
+
+### 3.1 Props / Events
+
+| Props | 说明 |
+|-------|------|
+| `sessions` | `AgentSession[]` |
+| `active-id` | 当前会话 id |
+| `history-open` | 历史侧栏；用 **`:history-open.sync`**（不要用 `v-model:history-open`） |
+| `is-replying` | 是否回复中 |
+| `tips` / `theme` / `show-open-in-browser` | 同适配面板 |
+
+| Events | 说明 |
+|--------|------|
+| `send` | `(payload: { text, type?, tip? })` |
+| `select-session` | `(sessionId)` |
+| `create-session` | 新建 |
+| `cancel-reply` | 停止生成 |
+| `clear-session` | 清空当前会话 |
+| `update:historyOpen` | 切换历史栏（配合 `.sync`） |
+| `open-browser` | 浏览器打开 |
+
+### 3.2 示例
+
+```vue
+<template>
+  <AgentChatPanel
+    :sessions="sessions"
+    :active-id="activeId"
+    :history-open.sync="historyOpen"
+    :is-replying="isReplying"
+    @send="onSend"
+    @select-session="onSelect"
+    @create-session="onCreate"
+    @cancel-reply="onCancel"
+    @clear-session="onClear"
+  />
+</template>
+
+<script>
+import { AgentChatPanel } from "kd-chatbot-ui-vue2";
+import "kd-chatbot-ui-vue2/style.css";
+
+export default {
+  components: { AgentChatPanel },
+  data() {
+    return {
+      sessions: [],
+      activeId: "",
+      historyOpen: false,
+      isReplying: false
+    };
+  },
+  methods: {
+    async onSend({ text, type }) {
+      this.isReplying = true;
+      // 调你们自己的接口，写入 sessions
+      this.isReplying = false;
+    },
+    onSelect(id) {
+      this.activeId = id;
+    },
+    onCreate() {},
+    onCancel() {},
+    onClear() {}
+  }
+};
+</script>
+```
+
+### 3.3 会话消息结构
+
+```ts
+interface AgentSession {
+  id: string;
+  title: string;
+  content: AgentMessage[];
+  pinned?: boolean;
+  badge?: number;
+  updatedAt?: number;
+  snippet?: string;
+}
+
+interface AgentMessage {
+  type: "ask" | "answer";
+  placement: "start" | "end";
+  content: string;
+  segments?: { type: "reasoning" | "answer"; content: string }[];
+}
+```
+
+流式回复：持续更新当前会话最后一条 `answer.segments`，再通过 `:sessions` 传入即可。
+
+---
+
+## 4. 导出一览
+
+```ts
+import {
+  AgentChatAdaptPanel,
+  AgentChatPanel,
+  AgentChatView,
+  useAgentChat,
+  useAgentChatStore,
+  createAgentChatClient,
+  buildInterpretContext,
+  INTERPRET_POLL_INTERVAL_MS,
+  DEFAULT_AGENT_CHAT_TIPS
+} from "kd-chatbot-ui-vue2";
+
+import type {
+  AgentChatEndpoints,
+  AgentChatRequestParams,
+  AgentChatRequestFn,
+  AgentChatCallRuntime,
+  AgentChatResponseFields,
+  AgentChatContext,
+  AgentSession,
+  AgentMessage,
+  AgentChatTip,
+  AgentChatSendPayload,
+  AgentChatTheme
+} from "kd-chatbot-ui-vue2";
+```
+
+默认导出为 Vue 插件：`Vue.use(KdChatbotUi)`。
+
+---
+
+## 5. 开发与发布
+
+本包在 Monorepo 内维护：
+
+```text
+agent-chat-components/
+  packages/
+    kd-chatbot-ui/         # Vue3
+    kd-chatbot-ui-vue2/    # 本包
+```
+
+```bash
+# 在 agent-chat-components 根目录
+pnpm install
+pnpm build:vue2          # 只构建本包
+pnpm build               # Vue2 + Vue3 都构建
+pnpm dev:vue2            # watch 构建
+```
+
+构建产物：`dist/kd-chatbot-ui.js`、`dist/kd-chatbot-ui.css`、类型声明。
+
+发布（在本包目录或按你们的发包流程）：
+
+```bash
+pnpm --filter kd-chatbot-ui-vue2 publish
+# prepublishOnly 会先执行 build
+```
+
+---
+
+## 6. 怎么选模式
+
+- 后端仍是「会话 + ask + progress 轮询」，只是路径/字段名不同 → **`AgentChatAdaptPanel`** + `endpoints` + `requestParams`
+- 协议完全不同，或宿主已有完整编排 → **`AgentChatPanel`**，自己管接口与 `sessions`
+
+Vue 3 项目请用姊妹包 [`kd-chatbot-ui`](../kd-chatbot-ui)，不要混用本包。
+
+---
+
+## 版本
+
+- 包名：`kd-chatbot-ui-vue2`
+- 版本：见本目录 `package.json` 的 `version`
+- License：MIT