更新记录

1.1.3（2026-01-28）下载此版本

修复某些情况下无法识别cli的问题

1.1.2（2026-01-27）下载此版本

优化ui样式，界面更简洁

1.1.1（2026-01-24）下载此版本

更新版本号

平台兼容性

HbuilderX/cli最低兼容版本
5.0.0

HBuilderX插件通用注意事项

HBuilderX-2.7.12以下版本安装插件市场内的插件后，卸载时需手动卸载，详细教程参考：如何手动卸载插件

Chat for Claude Code (HBuilderX)

一个为 HBuilderX 开发的 AI 代码助手插件，提供与 Claude Code 和 QOder 等 AI 模型交互的图形化聊天界面。

English | 中文

中文版本

项目简介

Chat for Claude Code (HBuilderX) 是一个强大的 HBuilderX 插件，它为开发者提供了一个美观、直观的 AI 代码助手聊天界面。该插件支持多种 AI 提供商（Claude Code CLI、QOder 等），让开发者可以在 HBuilderX 编辑器中直接与 AI 助手对话，获得代码建议、问题解答和编程帮助。

核心特性

🤖 多提供商支持

Claude Code CLI: 通过 Anthropic 的 Claude Code CLI 提供强大的代码理解和生成能力
QOder: 支持 QOder AI 助手（基于 Qwen 系列模型）
灵活的提供商架构，易于扩展新的 AI 服务

💬 完整的对话管理

会话持久化：自动保存所有对话历史
多会话支持：可以创建和管理多个独立的聊天会话
会话恢复：支持从之前的会话中恢复对话
历史记录查看：浏览和搜索历史对话

🎨 现代化用户界面

基于 Vue 3 构建的响应式 UI
使用 Vuex 进行状态管理
Markdown 渲染支持（服务端预渲染）
代码语法高亮（highlight.js）
流式响应实时显示（带防抖优化）
轻量级构建（~124KB 单文件 HTML）

🔧 强大的功能

文件引用: 通过 @ 符号快速引用项目文件
图片支持:
- 支持拖拽、粘贴（Ctrl+V/Cmd+V）和文件选择
- 图片预览和移除功能
- 点击图片全屏查看
- 自动 Base64 编码和压缩
工具调用可视化: 实时显示 AI 使用的工具（读取文件、搜索、编辑等）
Token 统计: 实时显示 Token 使用量和预估成本
草稿保存: 自动保存未发送的消息
Git 备份: 自动创建代码变更的 Git 快照

⚙️ 高度可配置

模型选择（Sonnet、Opus 等）
权限管理（自动批准、手动批准、YOLO 模式）
自定义 API 配置
环境变量管理

系统要求

HBuilderX: 3.0.0 或更高版本
Node.js: 16.0 或更高版本
操作系统: macOS, Windows, Linux

🚀 Git Checkpoint & Review 功能

自动创建检查点

每次发送消息给 AI 前，系统会自动创建 Git 检查点，保存当前工作区状态：

你: "帮我优化这个函数"
系统: ✓ 检查点已创建 (sha: a1b2c3d)
AI: 开始分析和修改代码...

查看代码变更（Review）

AI 完成修改后，可以在 HBuilderX 中打开 Review 模式，对比检查点与当前代码的差异：

🔍 并排显示旧版本和新版本
📝 高亮显示所有变更
🎯 精确定位每一处修改

恢复检查点

如果 AI 的修改不满意，可以一键恢复到任意检查点：

⏮️ 选择要恢复的检查点
🔄 一键撤销所有更改
💡 重新开始对话

📚 查看完整使用指南

📦 安装方法

方法 1: 从 HBuilderX 插件市场安装（推荐）

打开 HBuilderX
进入 工具 -> 插件管理
搜索 "AI Code Chat" 或 "Claude Code Chat"
点击安装

方法 2: 手动安装

克隆或下载此仓库

git clone https://github.com/yourusername/claude-code-chat.git
cd claude-code-chat/hbuilderx-ai-chat

安装依赖


# 安装插件侧依赖（marked 和 highlight.js）
npm install

构建 Vue UI（如果需要修改 UI）

cd vue-ui npm install npm run build cd ..


3. 将整个 `hbuilderx-ai-chat` 文件夹复制到 HBuilderX 插件目录：
   - **macOS**: `~/Library/Application Support/HBuilder X/plugins/`
   - **Windows**: `%APPDATA%\HBuilder X\plugins\`
   - **Linux**: `~/.config/HBuilder X/plugins/`

4. 重启 HBuilderX

### 快速开始

#### 1. 配置 AI 提供商

##### 使用 Claude Code CLI

1. 安装 Claude Code CLI（如果尚未安装）:
```bash
npm install -g @anthropic-ai/claude-code

配置 API 密钥:

export ANTHROPIC_API_KEY="your-api-key-here"

在插件设置中选择 "Claude Code" 作为提供商

使用 QOder

确保已安装 QOder CLI 或 API 服务
在插件设置中选择 "QOder" 作为提供商
配置 QOder API 端点和密钥

2. 打开聊天界面

方式 1: 点击 HBuilderX 侧边栏的 "AI Code Chat" 图标
方式 2: 使用命令面板，搜索 "Open AI Code Chat"
方式 3: 使用快捷键（可在设置中配置）

3. 开始对话

在输入框中输入您的问题或请求，例如：

"帮我解释这段代码的功能"
"如何在 JavaScript 中实现防抖函数？"
"重构这个函数以提高性能"
粘贴图片并询问相关问题

项目架构

文件目录结构

hbuilderx-ai-chat/
├── extension.js              # 插件入口文件（AiChatProvider 核心类）
├── package.json             # 插件配置和依赖
├── markdown-renderer.js     # Markdown 服务端渲染模块
├── default-ui.js            # 备用 UI 模板
├── providers/               # AI 提供商实现
│   ├── BaseProvider.js      # 提供商基类（统一接口、抽象方法）
│   ├── ClaudeCodeProvider.js # Claude Code CLI 提供商
│   ├── QoderProvider.js     # QOder 提供商
│   ├── ProviderFactory.js   # 提供商工厂（动态创建）
│   └── index.js            # 提供商导出
├── managers/                # 管理器模块
│   ├── ChatManager.js       # 聊天会话管理（生命周期、状态、Provider 切换）
│   └── GitBackupManager.js  # Git 备份管理（检查点、恢复、Review）
├── utils/                   # 工具函数
│   └── FileSelectionHelper.js # 文件选择辅助工具
├── mcp-servers/             # MCP 服务器
│   └── hbuilderx-mcp-server.js # HBuilderX 专用 MCP 服务器
├── vue-ui/                  # Vue 3 前端界面
│   ├── src/
│   │   ├── App.vue         # 主应用组件
│   │   ├── main.js         # Vue 应用入口
│   │   ├── components/     # UI 组件
│   │   │   ├── ChatHeader.vue        # 聊天头部（标题、统计）
│   │   │   ├── MessageList.vue       # 消息列表容器
│   │   │   ├── MessageItem.vue       # 单条消息组件（支持图片）
│   │   │   ├── MessageInput.vue      # 输入框（支持图片粘贴）
│   │   │   ├── ProviderSelection.vue # 提供商选择界面
│   │   │   ├── PermissionModal.vue   # 权限请求模态框
│   │   │   ├── ToolUseCard.vue       # 工具调用卡片
│   │   │   ├── ToolResultCard.vue    # 工具结果卡片
│   │   │   └── ErrorResultCard.vue   # 错误结果卡片
│   │   └── store/          # Vuex 状态管理
│   │       └── index.js    # 全局状态（消息、设置、权限）
│   ├── index.html          # HTML 模板（带 highlight.js CSS）
│   ├── vite.config.js      # Vite 构建配置（ES5 转译、压缩）
│   ├── .babelrc            # Babel ES5 转译配置
│   └── package.json        # 前端依赖
└── docs/                    # 文档
    ├── CHECKPOINT_QUICKSTART.md  # Git Checkpoint 快速开始
    ├── CHECKPOINT_EXAMPLE.md     # 使用示例
    ├── GIT_CHECKPOINT_REVIEW.md  # 完整功能说明
    └── CLAUDE_JSON_RESULTS_DOCS.md  # Claude CLI JSON 输出格式文档

架构设计模式

插件采用 分层架构 + Provider 模式 + 事件驱动 的混合架构：

┌──────────────────────────────────────────────────┐
│          HBuilderX IDE (宿主环境)                │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│         extension.js (插件入口层)                │
│  - AiChatProvider (核心协调器)                  │
│  - WebView 生命周期管理                         │
│  - 命令注册与事件分发                           │
└──────────┬───────────────────────┬───────────────┘
           │                       │
┌──────────▼────────┐   ┌──────────▼────────────┐
│  ChatManager      │   │  GitBackupManager     │
│  (聊天管理层)     │   │  (版本控制层)         │
└──────────┬────────┘   └───────────────────────┘
           │
┌──────────▼──────────────────────────────────────┐
│         Provider 抽象层                         │
│  ┌─────────────┐  ┌─────────────┐             │
│  │BaseProvider │  │ProviderFactory│            │
│  └──────┬──────┘  └─────────────┘             │
│         │                                       │
│  ┌──────▼──────────┐   ┌───────────────────┐  │
│  │ClaudeCodeProvider│   │  QoderProvider    │  │
│  │ (Anthropic CLI) │   │  (QOder AI CLI)   │  │
│  └─────────────────┘   └───────────────────┘  │
└───────────────────────────────────────────────┘
           │
┌──────────▼──────────────────────────────────────┐
│        Vue 3 UI Layer (WebView)                 │
│  ┌──────────────────────────────────────────┐  │
│  │   Vuex Store (状态管理)                  │  │
│  ├──────────────────────────────────────────┤  │
│  │   Vue Components:                        │  │
│  │   - ChatHeader                           │  │
│  │   - MessageList / MessageItem           │  │
│  │   - MessageInput                         │  │
│  │   - ProviderSelection                    │  │
│  │   - PermissionModal                      │  │
│  │   - ToolUseCard / ToolResultCard        │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

核心设计模式详解

1. Provider 模式 (providers/)

BaseProvider (抽象基类)
├── 定义统一接口: getName(), getVersion(), sendMessage()
├── 子进程管理: spawn(), cleanup()
├── 事件发射: EventEmitter
└── 配置管理: _mergeConfig()

具体实现:
├── ClaudeCodeProvider (Claude Code CLI)
│   └── 处理 JSON 流式输出
├── QoderProvider (QOder CLI)
    └── 处理特定协议格式

优势: 易于扩展新的 AI 提供商，无需修改核心代码

2. Manager 模式 (managers/)

ChatManager
├── 管理 Provider 生命周期
├── 处理消息收发
├── 统计 Token 和成本
└── 会话状态管理

GitBackupManager
├── Git 快照创建
├── 代码变更恢复
├── Review 模式支持
└── 独立 Git 仓库管理

3. 事件驱动架构

Provider (EventEmitter)
    ↓ emit('data', jsonData)
ChatManager
    ↓ emit('message', transformedData)
AiChatProvider
    ↓ webview.postMessage(message)
Vue Components (onMounted)
    ↓ window.addEventListener('message')
Vuex Store (mutations)

数据流设计

消息发送流程

用户输入
  → Vue MessageInput
  → window.postMessage({type: 'sendMessage'})
  → extension.js: _onDidReceiveMessage()
  → ChatManager.sendMessage()
  → Provider.sendMessage()
  → 子进程 stdin.write()
  → AI CLI 处理

消息接收流程

AI CLI stdout
  → Provider._processLine() (JSON 解析)
  → emit('data', jsonData)
  → ChatManager._handleProviderData()
  → emit('message', transformedMessage)
  → extension.js._handleChatMessage()
  → webview.postMessage(message)
  → Vue App: window.addEventListener
  → Vuex mutations
  → Vue Components 渲染

Checkpoint 备份流程

用户发送消息
  → extension.js._sendMessage()
  → GitBackupManager.createCheckpoint()
  → 执行 git add -A && git commit
  → 返回 commitSha
  → 关联到当前消息
  → 存储在会话历史中

核心业务功能

会话管理 (extension.js:1274-1456)

核心功能:
├── 自动保存会话到 JSON 文件
├── 会话索引维护 (_conversationIndex)
├── 历史会话快速查找 (QuickPick)
├── 会话恢复 (跨项目支持)
├── 多会话管理 (每个项目独立)
└── 草稿自动保存 (_draftMessage)

存储结构:
.hbuilderx/
└── code-chat-conversations/
    ├── conversation-{timestamp}.json
    └── index.json (会话索引)

Git Checkpoint 系统 (GitBackupManager.js)

功能:
├── 自动快照创建 (每次发送消息前)
├── 独立 Git 仓库 (.hbuilderx/code-chat-backups/)
├── Review 模式 (对比代码变更)
├── 一键恢复到任意检查点
└── 检查点列表管理

技术实现:
- 使用 --git-dir 和 --work-tree 分离 Git 仓库
- 支持 HBuilderX 原生 diff 对比
- 自动忽略敏感文件 (.env, node_modules)

权限管理系统 (extension.js:656-769)

模式:
├── bypassPermissions: 自动批准所有操作
├── requireApproval: 每次都询问用户
├── alwaysAllow: 记住特定工具/命令的批准
└── YOLO: 完全信任模式

实现机制:
- 文件系统 IPC (.request / .response 文件)
- 模态对话框 UI (PermissionModal.vue)
- 持久化存储用户偏好

图片处理流程 (extension.js:1020-1098)

支持方式:
├── 拖拽上传 (drag & drop)
├── 粘贴上传 (Ctrl+V / Cmd+V)
└── 文件选择器

处理流程:
图片文件
  → 复制到 .hbuilderx/claude-code-chat-images/
  → Base64 编码
  → 存储在消息对象中
  → 发送给 AI (支持视觉模型)
  → WebView 预览与展示

性能优化技术

1. 流式响应防抖 (extension.js:525-620)

防抖机制:
- 200ms 防抖延迟
- 批量更新消息内容
- 减少 UI 重绘次数
- 提升大文本响应性能

2. 服务端 Markdown 预渲染 (markdown-renderer.js)

优势:
- 减轻 WebView 渲染压力
- 统一渲染效果
- 支持代码高亮 (highlight.js)
- 减少打包体积 (~880KB)

流程:
原始 Markdown
  → marked.parse()
  → 自定义 renderer (代码块、链接、图片)
  → 注入 highlight.js CSS
  → 返回完整 HTML

3. 历史消息分页加载 (store/index.js:102-189)

性能优化:
- 首次仅加载最近 10 条消息
- 滚动触发增量加载 (每次 5 条)
- 避免一次性渲染大量 DOM
- 提升长会话加载速度

4. 单文件 HTML 构建 (vite.config.js)

优势:
- ~124KB 单文件大小
- 无外部依赖
- 快速加载
- 兼容 HBuilderX WebView 限制

实现:
- vite-plugin-singlefile (CSS/JS 内联)
- Terser 压缩
- Legacy 模式支持 ES5

数据持久化

会话存储格式

{
  "sessionId": "uuid-v4",
  "startTime": "2025-11-10T10:00:00.000Z",
  "endTime": "2025-11-10T11:30:00.000Z",
  "projectName": "my-project",
  "projectPath": "/path/to/project",
  "providerName": "Claude Code",
  "chatTitle": "实现用户登录功能",
  "messages": [
    {
      "messageType": "userInput",
      "data": "帮我实现用户登录",
      "images": null,
      "checkpointSha": "a1b2c3d4",
      "messageId": "msg-123"
    },
    {
      "messageType": "assistantMessage",
      "data": "## 登录功能实现\n\n...",
      "messageId": "msg-124"
    },
    {
      "messageType": "toolUse",
      "data": {
        "toolName": "Read",
        "parameters": {"file_path": "src/auth.js"}
      }
    }
  ],
  "totalCost": 0.0234,
  "totalTokensInput": 1200,
  "totalTokensOutput": 800,
  "messageCount": 15
}

状态持久化位置

.hbuilderx/
├── code-chat-conversations/    # 会话历史
│   ├── conversation-*.json
│   └── index.json
├── code-chat-backups/          # Git 快照
│   └── .git/
├── claude-code-chat-images/    # 上传的图片
└── code-chat-project-sessions.json  # 项目会话映射

核心技术特点

1. 服务端 Markdown 渲染

为了大幅减少前端打包体积（从 1.1MB 降至 ~124KB），我们将 Markdown 解析和代码高亮移到了插件侧处理：

markdown-renderer.js:

const hljs = require('highlight.js');
const marked = require('marked'); // v4.3.0 (CommonJS 兼容)

// 在插件侧预渲染 Markdown
function renderMarkdown(markdown) {
    return marked.parse(markdown);
}

extension.js:

_preprocessMarkdown(message) {
    if (message.type === 'assistantMessage' && message.data) {
        return {
            ...message,
            data: renderMarkdown(message.data),
            isPrerendered: true
        };
    }
    return message;
}

优势:

减少 WebView 计算负担（~880KB highlight.js CSS + ~130KB 库文件）
提高消息渲染性能
更好的浏览器兼容性（ES5 转译）

2. 图片处理流程

完整的图片处理流程包括粘贴、预览、发送、显示和查看：

MessageInput.vue - 图片粘贴和上传：

const handlePaste = async (e) => {
    const items = e.clipboardData?.items
    for (let i = 0; i < items.length; i++) {
        const item = items[i]
        if (item.type.indexOf('image') !== -1) {
            const blob = item.getAsFile()
            const dataUri = await blobToDataUri(blob)
            selectedImages.value.push({
                name: `pasted-image-${Date.now()}.png`,
                dataUri: dataUri,
                base64: dataUri.split(',')[1],
                mimeType: blob.type,
                size: blob.size
            })
        }
    }
}

MessageItem.vue - 图片显示和查看：

<div class="message-images">
  <img
    v-for="(image, index) in message.images"
    :key="index"
    :src="image.dataUri"
    class="message-image"
    @click="openImageModal(image)"
  />
</div>

3. Provider 架构设计

插件采用可扩展的 Provider 架构：

BaseProvider.js - 抽象基类：

class BaseProvider extends EventEmitter {
    // 必须实现的抽象方法
    getName()           // 获取 Provider 名称
    getVersion()        // 获取版本
    getDefaultConfig()  // 获取默认配置

    // 核心方法
    async initialize()          // 初始化
    async startSession(message) // 启动会话
    async sendMessage(message)  // 发送消息
    async stopSession()         // 停止会话
    dispose()                   // 清理资源
}

实现示例 - ClaudeCodeProvider.js：

class ClaudeCodeProvider extends BaseProvider {
    getName() { return 'Claude Code'; }

    async startSession(userMessage) {
        this.currentProcess = cp.spawn('claude', [
            '--output-format', 'stream-json',
            '--model', this.config.model
        ]);

        this.currentProcess.stdout.on('data', (data) => {
            this._parseJsonStream(data);
        });

        this.currentProcess.stdin.write(userMessage + '\n');
    }
}

4. ChatManager 会话管理

职责分离:

ChatManager: 管理 Provider 生命周期、消息存储、统计信息
Provider: 只负责与 AI CLI 的通信

class ChatManager extends EventEmitter {
    async initialize() {
        await this.switchProvider(this.providerType);
    }

    async sendMessage(message) {
        this.isProcessing = true;
        await this.currentProvider.sendMessage(message);
    }

    async switchProvider(type) {
        if (this.currentProvider) {
            this.currentProvider.dispose();
        }
        this.currentProvider = ProviderFactory.createProvider(type);
        await this.currentProvider.initialize();
    }
}

5. Vue 3 前端架构

使用 Vue 3 Composition API 和 Vuex 4：

store/index.js - 状态管理：

export default createStore({
    state: {
        messages: [],           // 消息列表
        processing: false,      // 处理中状态
        permissionRequest: null,// 权限请求
        // ...更多状态
    },
    mutations: {
        ADD_MESSAGE(state, { content, type, images }) {
            state.messages.push({
                id: Date.now(),
                content,
                type,
                images: images || null
            })
        }
    },
    actions: {
        addMessage({ commit }, payload) {
            commit('ADD_MESSAGE', payload)
        }
    }
})

组件通信:

<!-- App.vue -->
<script>
import { useStore } from 'vuex'

export default {
  setup() {
    const store = useStore()

    window.hbuilderx.onDidReceiveMessage((msg) => {
      handleMessage(msg)
    })

    const handleMessage = (message) => {
      switch (message.type) {
        case 'userInput':
          store.dispatch('addMessage', {
            content: message.data,
            type: 'user',
            images: message.images || null
          })
          break
      }
    }
  }
}
</script>

6. 流式响应防抖优化

为避免 AI 快速响应时的 UI 卡顿，实现了防抖机制：

// extension.js
_scheduleUpdate(update) {
    clearTimeout(this._updateDebounceTimer);
    this._pendingUpdate = update;
    this._updateDebounceTimer = setTimeout(() => {
        this._flushPendingUpdate();
    }, this._debounceDelay); // 150ms
}

_flushPendingUpdate() {
    if (this._pendingUpdate) {
        this._postMessage(this._pendingUpdate);
        this._pendingUpdate = null;
    }
}

开发指南

环境搭建

克隆仓库

git clone https://github.com/yourusername/claude-code-chat.git
cd claude-code-chat/hbuilderx-ai-chat

安装插件侧依赖

npm install
# 安装 marked@4.3.0 (CommonJS 兼容) 和 highlight.js

安装 Vue UI 依赖（仅开发时需要）
```
cd vue-ui
npm install
```

开发 Vue 前端

启动开发服务器
```
cd vue-ui
npm run dev
```

修改组件后构建

npm run build
# 输出到 vue-ui/dist/index.html (~124KB)

构建配置说明

vite.config.js - 核心配置：

export default defineConfig({
  plugins: [
    vue(),
    legacy({
      targets: ['ie >= 11'],  // ES5 转译（兼容旧版 WebView）
      renderLegacyChunks: true,
      polyfills: true
    }),
    viteSingleFile()  // 单文件输出
  ],
  build: {
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,      // 移除 console.log
        drop_debugger: true,
        pure_funcs: ['console.log']
      }
    }
  }
})

.babelrc - Babel 配置：

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "ie": "11"
        },
        "useBuiltIns": "usage",
        "corejs": 3
      }
    ]
  ]
}

调试插件

将项目文件夹链接到 HBuilderX 插件目录：


# macOS/Linux
ln -s $(pwd) ~/Library/Application\ Support/HBuilder\ X/plugins/claude-code-chat

Windows (管理员权限)

mklink /D "%APPDATA%\HBuilder X\plugins\claude-code-chat" "C:\path\to\hbuilderx-ai-chat"


2. 在 HBuilderX 中打开 `帮助` -> `查看运行日志` 查看插件输出

3. 修改代码后重启 HBuilderX 加载更新

#### 添加新的 AI 提供商

1. 在 `providers/` 目录创建新的提供商类：

```javascript
// providers/MyAIProvider.js
const BaseProvider = require('./BaseProvider');

class MyAIProvider extends BaseProvider {
    getName() {
        return 'MyAI';
    }

    getVersion() {
        return '1.0.0';
    }

    getDefaultConfig() {
        return {
            apiKey: '',
            apiEndpoint: 'https://api.myai.com',
            model: 'default'
        };
    }

    async initialize() {
        console.log('[MyAIProvider] Initializing...');
        this.initialized = true;
    }

    async startSession(userMessage) {
        // 实现会话启动逻辑
        // 1. 启动 CLI 进程或建立 HTTP 连接
        // 2. 监听输出流
        // 3. 发送用户消息
    }

    async sendMessage(message) {
        // 实现消息发送逻辑
    }

    async stopSession() {
        // 停止会话
        if (this.currentProcess) {
            this.currentProcess.kill();
        }
    }

    dispose() {
        this.stopSession();
    }
}

module.exports = MyAIProvider;

在 providers/ProviderFactory.js 中注册：

const MyAIProvider = require('./MyAIProvider');

class ProviderFactory {
    static createProvider(type, config) {
        switch(type) {
            case 'myai':
                return new MyAIProvider(config);
            case 'claude-code':
                return new ClaudeCodeProvider(config);
            // ...
            default:
                throw new Error(`Unknown provider type: ${type}`);
        }
    }
}

在 UI 中添加选项（vue-ui/src/components/ProviderSelection.vue）

配置选项

插件支持以下配置（通过 HBuilderX 设置界面或 .hbuilderx/settings.json）:

{
  "ai-code-chat": {
    "provider": "claude-code",           // AI 提供商: claude-code, qoder
    "model": "default",                  // 模型选择: opus, sonnet, default
    "permissionMode": "bypassPermissions", // 权限模式
    "apiKey": "",                        // API 密钥（可选）
    "apiEndpoint": "",                   // 自定义 API 端点（可选）
    "debounceDelay": 150,                // 流式响应防抖延迟（毫秒）
    "maxImageSize": 10485760             // 最大图片大小（字节，默认 10MB）
  }
}

常见问题

Q: 插件无法启动或显示空白？

检查 HBuilderX 版本是否 ≥ 3.0.0
查看运行日志是否有错误信息
确保插件文件夹位于正确的位置
检查是否安装了必要的依赖（npm install）
尝试重新安装插件

Q: 无法连接到 Claude Code CLI？

确认已安装 Claude Code CLI: claude --version
检查 API 密钥是否正确配置: echo $ANTHROPIC_API_KEY
验证网络连接是否正常
查看错误日志中的详细信息
尝试在终端手动运行 claude 命令

Q: 消息发送后无响应？

检查控制台是否有错误输出
确认 AI 提供商配置正确
验证 API 密钥和配额
尝试创建新会话
检查网络连接

Q: 如何查看 Token 使用量和成本？

A: 在聊天界面右上角可以看到实时的 Token 统计和预估成本（基于当前模型定价）。

Q: 图片无法显示？

确保图片小于 10MB
检查图片格式是否支持（PNG, JPG, GIF, WebP, BMP, SVG）
查看控制台是否有错误信息
尝试使用不同的粘贴方式（拖拽 vs 粘贴 vs 文件选择）

Q: Vue UI 构建失败？

确保 Node.js 版本 ≥ 16.0
删除 node_modules 和 package-lock.json，重新安装
检查是否有依赖冲突
使用 npm run build 查看详细错误信息

Q: 如何迁移到新版本？

备份现有会话数据（.claude/claude-code-chat-conversations/）
更新插件文件
运行 npm install 更新依赖
重新构建 Vue UI（如果需要）: cd vue-ui && npm run build
重启 HBuilderX

性能优化总结

打包体积优化: 从 1.1MB 降至 ~124KB（减少 89%）
- 服务端 Markdown 渲染（避免打包 marked 和 highlight.js）
- 单文件构建（vite-plugin-singlefile）
- Terser 压缩（移除 console.log、压缩代码）
渲染性能优化:
- 流式响应防抖（150ms）
- 虚拟滚动（长消息列表）
- 图片懒加载
内存优化:
- 消息限制（最多保留 1000 条）
- 图片压缩（自动转换 base64）
- 定期清理过期会话

贡献指南

欢迎贡献代码、报告问题或提出新功能建议！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

代码规范:

使用 ESLint（插件侧）
遵循 Vue 3 风格指南（UI 侧）
添加必要的注释和文档
编写单元测试（如果适用）

更新日志

v1.1.0 (2025-11-05) - 最新版本

新增: Vue 3 重构前端界面（替代原 default-ui.js）
新增: 服务端 Markdown 渲染（markdown-renderer.js）
新增: 图片粘贴、预览和全屏查看功能
新增: 完整的图片处理流程（拖拽、粘贴、文件选择）
优化: 打包体积从 1.1MB 降至 ~124KB（减少 89%）
优化: ES5 转译支持（兼容旧版 WebView）
修复: 图片显示路径问题
修复: 用户消息图片右对齐问题

v1.0.0 (2025-01-15)

初始版本发布
支持 Claude Code CLI 和 QOder
实现完整的聊天界面
添加会话管理功能
实现流式响应防抖优化
支持 Markdown 和代码高亮

近期更新

优化：助手消息回复过快时导致的 UI 卡顿问题（加上了防抖）
修复：QOder 消息助手存储历史会话消息格式不对的问题
修复：用户输入的消息被当前 Markdown 解析渲染的问题
清理：无用的代码和资源

技术栈

插件侧（Node.js）:

HBuilderX Extension API
marked v4.3.0 (Markdown 解析)
highlight.js v11.11.1 (代码高亮)
child_process (进程管理)
fs/path (文件系统)

前端侧（Vue 3）:

Vue 3.3.4 (Composition API)
Vuex 4.1.0 (状态管理)
Vite 7.0.0 (构建工具)
@vitejs/plugin-legacy (ES5 转译)
vite-plugin-singlefile (单文件构建)
core-js 3.46.0 (polyfills)

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

致谢

Anthropic Claude Code - 提供强大的 AI 代码助手能力
HBuilderX - 优秀的前端开发工具
QOder - 阿里云通义 AI 编码助手
Vue.js - 渐进式 JavaScript 框架
Vite - 下一代前端构建工具

联系方式

问题反馈: GitHub Issues
功能建议: GitHub Discussions
技术支持: 查看文档或在 Issues 中提问

English Version

Introduction

Chat for Claude Code (HBuilderX) is a powerful HBuilderX plugin that provides a beautiful, intuitive AI code assistant chat interface. The plugin supports multiple AI providers (Claude Code CLI, QOder, etc.), allowing developers to interact with AI assistants directly within the HBuilderX editor for code suggestions, problem-solving, and programming help.

Key Features

🤖 Multi-Provider Support

Claude Code CLI: Powerful code understanding and generation via Anthropic's Claude Code CLI
QOder: Support for QOder AI assistant (based on Qwen models)
Flexible provider architecture, easy to extend new AI services

💬 Complete Conversation Management

Session persistence: Automatically save all conversation history
Multi-session support: Create and manage multiple independent chat sessions
Session recovery: Resume from previous sessions
History viewing: Browse and search historical conversations

🎨 Modern User Interface

Built with Vue 3 for responsive UI
Vuex for state management
Markdown rendering (server-side pre-rendering)
Code syntax highlighting (highlight.js)
Real-time streaming responses (with debounce optimization)
Lightweight build (~124KB single-file HTML)

🔧 Powerful Features

File References: Quick file referencing with @ symbol
Image Support:
- Drag-drop, paste (Ctrl+V/Cmd+V), and file picker
- Image preview and removal
- Click to view full-screen
- Automatic Base64 encoding and compression
Tool Call Visualization: Real-time display of AI tool usage (file reading, searching, editing, etc.)
Token Statistics: Real-time token usage and cost estimation
Draft Saving: Auto-save unsent messages
Git Backup: Automatic Git snapshots of code changes

⚙️ Highly Configurable

Model selection (Sonnet, Opus, etc.)
Permission management (auto-approve, manual approve, YOLO mode)
Custom API configuration
Environment variable management

System Requirements

HBuilderX: 3.0.0 or higher
Node.js: 16.0 or higher
OS: macOS, Windows, Linux

Installation

Method 1: Install from HBuilderX Plugin Marketplace (Recommended)

Open HBuilderX
Go to Tools -> Plugin Management
Search for "AI Code Chat" or "Claude Code Chat"
Click Install

Method 2: Manual Installation

Clone or download this repository

git clone https://github.com/yourusername/claude-code-chat.git
cd claude-code-chat/hbuilderx-ai-chat

Install dependencies


# Install plugin-side dependencies (marked and highlight.js)
npm install

Build Vue UI (if you need to modify the UI)

cd vue-ui npm install npm run build cd ..


3. Copy the entire `hbuilderx-ai-chat` folder to HBuilderX plugins directory:
   - **macOS**: `~/Library/Application Support/HBuilder X/plugins/`
   - **Windows**: `%APPDATA%\HBuilder X\plugins\`
   - **Linux**: `~/.config/HBuilder X/plugins/`

4. Restart HBuilderX

### Quick Start

#### 1. Configure AI Provider

##### Using Claude Code CLI

1. Install Claude Code CLI (if not already installed):
```bash
npm install -g @anthropic-ai/claude-code

Configure API key:

export ANTHROPIC_API_KEY="your-api-key-here"

Select "Claude Code" as provider in plugin settings

Using QOder

Ensure QOder CLI or API service is installed
Select "QOder" as provider in plugin settings
Configure QOder API endpoint and credentials

2. Open Chat Interface

Method 1: Click the "AI Code Chat" icon in HBuilderX sidebar
Method 2: Use command palette and search "Open AI Code Chat"
Method 3: Use keyboard shortcut (configurable in settings)

3. Start Chatting

Enter your question or request in the input box, for example:

"Explain what this code does"
"How to implement a debounce function in JavaScript?"
"Refactor this function for better performance"
Paste an image and ask related questions

Project Architecture

See the Chinese version above for detailed architecture diagram.

Core Technical Features

1. Server-Side Markdown Rendering

To drastically reduce frontend bundle size (from 1.1MB to ~124KB), we moved Markdown parsing and code highlighting to the plugin side.

2. Image Processing Pipeline

Complete image processing workflow including paste, preview, send, display, and view.

3. Provider Architecture Design

Extensible provider architecture with abstract base class and factory pattern.

4. ChatManager Session Management

Separation of concerns: ChatManager handles lifecycle and storage, Providers handle AI communication.

5. Vue 3 Frontend Architecture

Uses Vue 3 Composition API and Vuex 4 for state management.

6. Streaming Response Debounce Optimization

Prevents UI stuttering during fast AI responses with 150ms debounce.

Development Guide

See the Chinese version above for detailed development instructions.

Configuration Options

{
  "ai-code-chat": {
    "provider": "claude-code",
    "model": "default",
    "permissionMode": "bypassPermissions",
    "apiKey": "",
    "apiEndpoint": "",
    "debounceDelay": 150,
    "maxImageSize": 10485760
  }
}

FAQ

See the Chinese version above for detailed FAQ.

Performance Optimization Summary

Bundle Size: Reduced from 1.1MB to ~124KB (89% reduction)
Rendering: Debounce, virtual scrolling, lazy loading
Memory: Message limits, image compression, session cleanup

Contributing

Contributions, issue reports, and feature suggestions are welcome!

Fork this repository
Create feature branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Open Pull Request

Changelog

v1.1.0 (2025-11-05) - Latest

New: Vue 3 frontend refactor
New: Server-side Markdown rendering
New: Image paste, preview, and full-screen view
Optimized: Bundle size reduced to ~124KB (89% reduction)
Optimized: ES5 transpilation for legacy WebView support
Fixed: Image display path issues
Fixed: User message image alignment

v1.0.0 (2025-01-15)

Initial release

Tech Stack

Plugin (Node.js):

HBuilderX Extension API
marked v4.3.0
highlight.js v11.11.1
child_process, fs/path

Frontend (Vue 3):

Vue 3.3.4, Vuex 4.1.0
Vite 7.0.0
@vitejs/plugin-legacy
vite-plugin-singlefile

License

MIT License. See LICENSE file.

Acknowledgments

Contact

Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions

Made with ❤️ by the Claude Code Chat Team

AI Chat AI

更新记录

1.1.3（2026-01-28） 下载此版本

1.1.2（2026-01-27） 下载此版本

1.1.1（2026-01-24） 下载此版本

平台兼容性

HBuilderX插件通用注意事项

Chat for Claude Code (HBuilderX)

中文版本

项目简介

核心特性

🤖 多提供商支持

💬 完整的对话管理

🎨 现代化用户界面

🔧 强大的功能

⚙️ 高度可配置

系统要求

🚀 Git Checkpoint & Review 功能

自动创建检查点

查看代码变更（Review）

恢复检查点

📦 安装方法

方法 1: 从 HBuilderX 插件市场安装（推荐）

方法 2: 手动安装

构建 Vue UI（如果需要修改 UI）

使用 QOder

2. 打开聊天界面

3. 开始对话

项目架构

文件目录结构

架构设计模式

核心设计模式详解

1. Provider 模式 (providers/)

2. Manager 模式 (managers/)

3. 事件驱动架构

数据流设计

消息发送流程

消息接收流程

Checkpoint 备份流程

核心业务功能

会话管理 (extension.js:1274-1456)

Git Checkpoint 系统 (GitBackupManager.js)

权限管理系统 (extension.js:656-769)

图片处理流程 (extension.js:1020-1098)

性能优化技术

1. 流式响应防抖 (extension.js:525-620)

2. 服务端 Markdown 预渲染 (markdown-renderer.js)

3. 历史消息分页加载 (store/index.js:102-189)

4. 单文件 HTML 构建 (vite.config.js)

数据持久化

会话存储格式

状态持久化位置

核心技术特点

1. 服务端 Markdown 渲染

2. 图片处理流程

3. Provider 架构设计

4. ChatManager 会话管理

5. Vue 3 前端架构

6. 流式响应防抖优化

开发指南

环境搭建

开发 Vue 前端

调试插件

Windows (管理员权限)

配置选项

常见问题

Q: 插件无法启动或显示空白？

Q: 无法连接到 Claude Code CLI？

Q: 消息发送后无响应？

Q: 如何查看 Token 使用量和成本？

Q: 图片无法显示？

Q: Vue UI 构建失败？

Q: 如何迁移到新版本？

性能优化总结

贡献指南

更新日志

v1.1.0 (2025-11-05) - 最新版本

v1.0.0 (2025-01-15)

近期更新

技术栈

1.1.3（2026-01-28）下载此版本

1.1.2（2026-01-27）下载此版本

1.1.1（2026-01-24）下载此版本