@bdky/chat-pilot-kit-vue3 1.0.4

package/README.md

@@ -0,0 +1,248 @@
+# @bdky/chat-pilot-kit-vue3
+
+[![npm version](https://img.shields.io/npm/v/@bdky/chat-pilot-kit-vue3.svg)](https://www.npmjs.com/package/@bdky/chat-pilot-kit-vue3)
+[![license](https://img.shields.io/npm/l/@bdky/chat-pilot-kit-vue3.svg)](./LICENSE)
+
+`@bdky/chat-pilot-kit` 的 Vue3 适配层，提供 Provider、Composables 和 VueNodeViewRenderer，Markdown 渲染使用 [markstream-vue](https://github.com/markstream/markstream-vue)，NodeView 样式采用 GitHub 风格设计。
+
+## 特性
+
+- **Provider/Inject 模式** — `provideChatPilotKit` / `injectChatPilotKit`，与 Vue3 依赖注入无缝集成
+- **4 个 Composables** — `useChatPilotKit`、`useChatPilotKitEvents`、`useConversations`、`useNodeInteraction`
+- **VueNodeViewRenderer** — 将 Vue SFC 注册为 NodeView，与 React 版 API 对称
+- **8 个默认 NodeView 组件** — Text、Markdown（流式）、ThinkingBlock、ToolCall、Image、File、Audio、Video
+- **GitHub 风格样式** — 基于 GitHub Primer 色板，支持亮色/暗色模式
+
+## 安装
+
+```bash
+npm install @bdky/chat-pilot-kit-vue3
+# or
+yarn add @bdky/chat-pilot-kit-vue3
+```
+
+引入样式：
+
+```typescript
+import '@bdky/chat-pilot-kit-vue3/styles.css';
+```
+
+## 快速开始
+
+### 1. 创建 controller 并注入
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import {createChatPilotKit, provideChatPilotKit} from '@bdky/chat-pilot-kit-vue3';
+import {MyAgentService} from './services/MyAgentService';
+import ChatApp from './components/ChatApp.vue';
+
+const controller = createChatPilotKit({
+    agentService: new MyAgentService(),
+});
+
+provideChatPilotKit(controller);
+</script>
+
+<template>
+    <ChatApp />
+</template>
+```
+
+### 2. 在子组件中使用 Composables
+
+```vue
+<!-- ChatApp.vue -->
+<script setup lang="ts">
+import {
+    useChatPilotKit,
+    useConversations,
+    useChatPilotKitEvents,
+    getDefaultVueExtensions,
+} from '@bdky/chat-pilot-kit-vue3';
+import NodeRenderer from '@bdky/chat-pilot-kit-vue3';
+
+const {controller} = useChatPilotKit();
+const conversations = useConversations();
+
+useChatPilotKitEvents({
+    onConversationAdd: (conv) => {
+        console.log('新会话', conv.id);
+    },
+    onNodeAdd: (node) => {
+        console.log('新节点', node.id);
+    },
+});
+
+const extensions = getDefaultVueExtensions();
+
+const sendMessage = async () => {
+    await controller.conversationService.sendMessage({
+        content: 'Hello',
+        role: 'user',
+    });
+};
+</script>
+
+<template>
+    <div class="chat-container">
+        <div
+            v-for="conv in conversations"
+            :key="conv.id"
+            class="conversation"
+        >
+            <div
+                v-for="node in conv.nodes"
+                :key="node.id"
+            >
+                <NodeRenderer
+                    :node="node"
+                    :extensions="extensions"
+                />
+            </div>
+        </div>
+        <button @click="sendMessage">发送</button>
+    </div>
+</template>
+```
+
+### 3. 自定义 NodeView
+
+```typescript
+import {VueNodeViewRenderer, MessageExtension} from '@bdky/chat-pilot-kit-vue3';
+import MyCustomView from './MyCustomView.vue';
+
+const MyExtension = MessageExtension.extend({
+    name: 'my-node',
+    addNodeView() {
+        return VueNodeViewRenderer(MyCustomView);
+    },
+});
+```
+
+`MyCustomView.vue` 接收的 props 类型为 `NodeViewProps`：
+
+```vue
+<script setup lang="ts">
+import type {NodeViewProps} from '@bdky/chat-pilot-kit-vue3';
+
+const props = defineProps<NodeViewProps>();
+</script>
+```
+
+## API 文档
+
+### Provider
+
+| 函数 | 说明 |
+|------|------|
+| `provideChatPilotKit(controller)` | 在父组件中注入 controller |
+| `injectChatPilotKit()` | 在子组件中获取注入的 context，未注入时抛错 |
+| `ChatPilotKitProviderKey` | InjectionKey Symbol |
+
+### Composables
+
+#### `useChatPilotKit()`
+
+返回 `{ controller }`，controller 为 `createChatPilotKit()` 创建的实例。
+
+#### `useChatPilotKitEvents(props)`
+
+监听 emitter 事件，组件卸载时自动清理。
+
+| 回调 | 触发时机 |
+|------|----------|
+| `onConversationAdd` | 新会话创建 |
+| `onConversationChange` | 会话状态变更 |
+| `onNodeAdd` | 新节点添加 |
+| `onNodeUpdate` | 节点内容更新 |
+| `onNodeInteraction` | 节点交互事件 |
+| `onHistoryImport` | 历史记录导入 |
+| `onClear` | 会话清空 |
+| `onError` | 错误事件 |
+| `onStart` | 开始生成 |
+| `onStop` | 停止生成 |
+| `onComplete` | 生成完成 |
+
+#### `useConversations()`
+
+返回 `ShallowRef<IConversationItem[]>`，响应式跟踪所有会话及其节点。
+
+#### `useNodeInteraction(props)`
+
+```typescript
+const {sendCommand} = useNodeInteraction({
+    filter: (payload) => payload.nodeId === targetId,
+    onInteraction: (payload) => { /* ... */ },
+});
+
+// 向节点发送命令
+sendCommand(nodeId, 'copy', {});
+```
+
+### NodeView
+
+| 导出 | 说明 |
+|------|------|
+| `VueNodeViewRenderer(Component)` | 将 Vue SFC 包装为 NodeView factory |
+| `extractVueComponent(factory)` | 从 factory 中提取 Vue 组件 |
+| `NodeRenderer` | 核心渲染组件，自动选择 Vue/DOM 渲染路径 |
+| `DomNodeRenderer` | 非 Vue NodeView 的 DOM 挂载组件 |
+
+### 默认扩展
+
+```typescript
+import {getDefaultVueExtensions} from '@bdky/chat-pilot-kit-vue3';
+
+// 获取全部 8 个默认扩展
+const extensions = getDefaultVueExtensions();
+```
+
+也可单独引用：
+
+```typescript
+import {
+    VueTextExtension,
+    VueMarkdownExtension,
+    VueThinkingBlockExtension,
+    VueToolCallExtension,
+    VueImageExtension,
+    VueFileExtension,
+    VueAudioExtension,
+    VueVideoExtension,
+} from '@bdky/chat-pilot-kit-vue3';
+```
+
+## 样式定制
+
+通过 CSS 变量覆盖 GitHub Primer 色板：
+
+```css
+:root {
+    --cpk-node-accent: #your-brand-color;
+    --cpk-node-surface: #your-surface-color;
+    --cpk-node-border: #your-border-color;
+}
+```
+
+支持 `[data-theme="dark"]` 属性切换暗色模式：
+
+```javascript
+document.documentElement.setAttribute('data-theme', 'dark');
+```
+
+## 与 React 版对比
+
+| 特性 | React 版 (`chat-pilot-kit-react`) | Vue3 版 (`chat-pilot-kit-vue3`) |
+|------|----------------------------------|--------------------------------|
+| Provider | `<ChatPilotKitProvider>` 组件 | `provideChatPilotKit()` 函数 |
+| 获取 context | `useChatPilotKit()` hook | `useChatPilotKit()` composable |
+| 事件监听 | `useChatPilotKitEvents()` hook | `useChatPilotKitEvents()` composable |
+| 会话列表 | `useConversations()` hook | `useConversations()` composable |
+| NodeView 注册 | `ReactNodeViewRenderer` | `VueNodeViewRenderer` |
+| Markdown 渲染 | streamdown | markstream-vue |
+
+## License
+
+MIT