更新记录

2.0.0（2026-06-17） 下载此版本

第一个版本

平台兼容性

HBuilderX插件通用注意事项

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

智清AI助手 (zhiqing-ai-helper)

HBuilderX AI Agent 编码助手 — 多模型对话、图形化聊天面板、代码补全与自主代码编辑

版本： 2.0.0
平台： HBuilderX 插件
许可证： MIT

目录

• 简介
• 功能特性
• 快速开始
  • 安装
  • 配置 AI 模型
  • 基本使用
• 支持的 AI 模型
• 架构设计
  • 目录结构
  • 核心模块
  • 数据流
• Agent 工具系统
  • 文件操作工具
  • 代码编辑工具
  • 搜索工具
  • 终端命令工具
  • Web 抓取工具
• 工作模式
  • Plan 模式（分析模式）
  • Build 模式（构建模式）
• 深度控制
• 代码补全
• 安全机制
  • 命令安全
  • API Key 加密
  • 文件备份与回滚
• 会话管理
• 配置选项
• 日志系统
• 上下文管理
• UI 界面
  • 聊天面板
  • 快捷键
• 开发者指南
  • 项目结构详解
  • 添加新的 LLM Provider
  • 添加新工具
• 依赖说明
• 常见问题
• 更新日志

简介

智清AI助手 是一款专为 HBuilderX 打造的 AI Agent 编码助手插件。它不仅提供传统的 AI 对话和代码补全功能，更内置了一个完整的 自主 Agent 系统，能够理解用户的编码意图，自主读取文件、搜索代码、编辑文件和执行终端命令，真正实现"AI 代你编码"。

核心理念

• Agent 自主循环：AI 根据任务自主规划、执行工具、检查结果，最多可循环 20 轮
• 多模型支持：同时支持 DeepSeek、OpenAI、通义千问、SiliconFlow 和本地 Ollama
• 安全优先：三级命令安全检查、文件自动备份、API Key 加密存储
• 上下文感知：自动收集编辑器上下文、项目结构、光标位置，精准理解代码场景

功能特性

快速开始

安装

1. 将 zhiqing-ai-helper 文件夹放入 HBuilderX 的 plugins 目录
2. 重启 HBuilderX
3. 状态栏将显示 "智清AI" 图标

配置 AI 模型

首次使用时，需要配置至少一个 AI 模型：

1. 方式一：点击聊天面板左下角的模型选择器，选择模型后配置 API Key
2. 方式二：在 HBuilderX 设置中配置（插件会自动创建配置文件）

配置文件位置：

%APPDATA%/HBuilderX/plugins/zhiqing/pref.json

快速配置示例

DeepSeek：

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek V3",
      "provider": "deepseek",
      "apiKey": "your-api-key-here",
      "baseUrl": "https://api.deepseek.com/v1"
    }
  ],
  "activeModel": "deepseek-chat"
}

Ollama（本地模型，无需 API Key）：

{
  "models": [
    {
      "id": "deepseek-r1:8b",
      "name": "DeepSeek R1 8B",
      "provider": "ollama",
      "baseUrl": "http://localhost:11434"
    }
  ],
  "activeModel": "deepseek-r1:8b"
}

基本使用

• 打开聊天面板：使用快捷键或命令面板
• 发送消息：在输入框输入问题，按回车发送
• 选中代码提问：选中代码后发送消息，代码会自动附加上下文
• 切换模式：在 Plan（只读分析）和 Build（允许编辑）之间切换
• 代码补全：开启后在编码时自动触发

支持的 AI 模型

所有 Provider 均支持：

• 流式输出（SSE）：实时显示 AI 回复
• 工具调用：支持 tool_calls 结构化调用和多种文本格式解析
• 中断/取消：随时中止 AI 生成
• 配置验证：自动测试 API 连通性

架构设计

目录结构

zhiqing-ai-helper/
├── extension.js                  # 插件入口（生命周期管理）
├── package.json                  # 插件清单（命令、视图、快捷键、配置）
├── src/
│   ├── statusBar.js              # 状态栏组件
│   ├── commands/
│   │   └── index.js              # 命令注册中心
│   ├── core/
│   │   ├── agent.js              # 🧠 Agent 核心（工具调用循环、消息处理）
│   │   ├── contextCollector.js   # 上下文收集器（编辑器/项目/附件）
│   │   └── session.js            # 会话管理器
│   ├── services/
│   │   ├── llmService.js         # LLM 服务抽象层
│   │   └── providers/
│   │       ├── baseProvider.js   # Provider 基类
│   │       ├── openaiProvider.js # OpenAI 兼容 Provider
│   │       ├── deepseekProvider.js
│   │       ├── qwenProvider.js
│   │       ├── siliconflowProvider.js
│   │       └── ollamaProvider.js
│   ├── tools/
│   │   ├── fileTools.js          # 文件读写工具
│   │   ├── editTools.js          # 代码编辑工具
│   │   ├── searchTools.js        # 搜索工具
│   │   ├── commandTools.js       # 终端命令工具
│   │   └── backupManager.js      # 文件备份管理
│   ├── ui/
│   │   ├── webviewManager.js     # Webview 生命周期管理
│   │   └── inlineCompletion.js   # 行内代码补全
│   ├── utils/
│   │   ├── configManager.js      # 配置管理（加密、持久化）
│   │   ├── logger.js             # 日志系统
│   │   ├── tokenCounter.js       # Token 估算与管理
│   │   └── filters.js            # 代码提取过滤器
│   └── webview/
│       ├── chat.html             # 聊天面板 HTML
│       ├── chat.js               # 聊天面板 JS 逻辑
│       ├── settings.html         # 设置面板
│       ├── highlight-github-dark.css  # 代码高亮主题
│       └── highlight-es.js       # highlight.js ES 模块
├── fonts/                        # 字体资源
└── docs/                         # 文档目录

核心模块

┌─────────────────────────────────────────────────────┐
│                    extension.js                      │
│                  (插件生命周期管理)                    │
├──────────┬──────────┬────────────┬──────────────────┤
│ commands │ statusBar│ webviewMgr │ inlineCompletion │
│ (命令)   │ (状态栏)  │ (聊天面板)  │  (代码补全)      │
└──────────┴────┬─────┴────────────┴──────────────────┘
                │
        ┌───────┴────────┐
        │   Agent (核心)   │◄─── session (会话)
        │  工具调用循环     │◄─── contextCollector (上下文)
        └───────┬────────┘
                │
    ┌───────────┼───────────┐
    │           │           │
┌───┴───┐ ┌────┴────┐ ┌────┴────┐
│ Tools │ │ LLM     │ │ Config  │
│ 工具层 │ │ Service │ │ Manager │
└───┬───┘ └────┬────┘ └─────────┘
    │          │
    │    ┌─────┴──────┐
    │    │ Providers   │
    │    │ ┌─────────┐ │
    │    │ │ OpenAI  │ │
    │    │ │ DeepSeek│ │
    │    │ │ Qwen    │ │
    │    │ │Silicon  │ │
    │    │ │ Ollama  │ │
    │    │ └─────────┘ │
    │    └─────────────┘
    │
┌───┴───────┐
│  Backup   │
│  Manager  │
└───────────┘

数据流

用户输入
    │
    ▼
Webview (chat.js)
    │  postMessage
    ▼
WebviewManager
    │
    ▼
Agent.chat(userMessage)
    │
    ├─► ContextCollector.collect()  → 收集编辑器/项目上下文
    ├─► buildSystemPrompt()        → 构建系统提示词
    │
    ▼
┌───── Agent Loop (最多 20 轮) ◄──────────────────┐
│   │                                               │
│   ▼                                               │
│   LLM Service.chatStream(messages)                │
│   │                                               │
│   ├─► 解析文本回复 → 返回给用户                     │
│   ├─► 解析工具调用 → 执行工具                       │
│   │       │                                       │
│   │       ├─► fileTools (读/写/删/列)              │
│   │       ├─► editTools (searchReplace/applyEdit)  │
│   │       ├─► searchTools (searchCode/findFiles)   │
│   │       ├─► commandTools (executeCommand)        │
│   │       └─► webFetch (HTTP 请求)                 │
│   │                                               │
│   └─► 将工具结果追加到消息历史 ──────────────────────┘
│
    ▼
返回最终结果 → 更新 Webview

Agent 工具系统

Agent 的核心能力来自于它可调用的工具集。AI 模型在回复中生成工具调用指令，Agent 解析并执行这些指令，然后将结果反馈给 AI 进行下一轮推理。

文件操作工具

特性：

• 自动处理 file:// URI 前缀
• URL 编码路径解码
• CJK 路径空格修复
• 行号显示（cat -n 格式）

代码编辑工具

searchReplace 工作流程：

1. 在文件中搜索 oldText
2. 验证匹配唯一性（避免意外替换多处）
3. 执行替换（支持模糊匹配，忽略尾部空白和 CRLF 差异）
4. 自动创建文件备份

applyEdit 工作流程：

1. 接受行号 + 列偏移的精确位置
2. 支持多处编辑，自动从后向前排序避免偏移漂移

搜索工具

特性：

• 递归搜索（最大深度 8 层）
• 自动忽略 node_modules、.git、dist 等目录
• 支持上下文行显示
• Glob 到正则的自动转换

终端命令工具

内置三级安全检查系统（详见命令安全）。

Web 抓取工具

用于查阅文档和在线资源。

工作模式

Plan 模式（分析模式）

• 用途：代码分析、问题诊断、架构讨论
• 权限：只读，Agent 只能读取文件，不能进行任何修改
• 适合场景：
  • 代码审查
  • 理解项目架构
  • 分析 Bug 原因
  • 技术方案讨论

Build 模式（构建模式）

• 用途：实际编码、文件修改、项目构建
• 权限：完整读写，Agent 可以读写文件、执行命令
• 适合场景：
  • 新功能开发
  • Bug 修复
  • 代码重构
  • 项目初始化

切换方式：在聊天面板中点击模式切换按钮，或使用命令面板。

深度控制

深度等级控制 AI 生成回复时的"思考深度"，影响温度参数和最大 Token 数：

代码补全

行内代码补全功能提供类似 GitHub Copilot 的编码体验：

• 触发方式：自动触发（500ms 防抖）或手动触发
• 支持语言：JavaScript、TypeScript、Vue、HTML、CSS、SCSS、Java、Python、PHP、C/C++、Go、Rust、Swift、Kotlin、Ruby、SQL、JSON、Markdown 等 18 种
• 智能跳过：
  • 跳过单行注释（//）
  • 跳过块注释（/* */）
  • 跳过字符串内容（"、'、`）
• 上下文窗口：光标前后各取 20 行代码作为上下文
• 代码提取：自动从 AI 返回的 Markdown 代码块中提取纯代码

安全机制

命令安全

终端命令执行采用三级安全防护：

1. 危险命令黑名单

以下命令将被直接拦截：

rm -rf /           # 递归删除根目录
sudo rm -rf        # 提权递归删除
mkfs               # 格式化磁盘
dd if=             # 磁盘镜像写入
:(){ :|:& };:      # Fork 炸弹
format             # Windows 格式化
shutdown / reboot  # 关机/重启

2. 安全命令白名单

以下命令自动放行：

# 包管理器
npm / yarn / pnpm / bun

# 版本控制（只读操作）
git status / git log / git diff / git branch

# 运行时
node / python / python3 / java

# 代码质量
eslint / prettier / stylelint

# 系统信息
ls / dir / pwd / cat / echo / whoami / date

3. Shell 注入检测

检测并拦截包含以下模式的命令：

• 管道 |
• 分号 ;
• 命令替换 ` 和 $()
• 重定向 >、<
• 逻辑运算 &&、||
• 后台执行 &

不在白名单中的命令需要用户在聊天面板中确认后才能执行。

API Key 加密

• 算法：AES-256-CBC
• 密钥派生：SHA-256(配置目录路径 + Salt)
• 存储：加密后的 Base64 字符串存储在 pref.json 中
• 透明加解密：读取时自动解密，保存时自动加密

文件备份与回滚

• 自动备份：AI 在修改或删除文件前，自动将原文件备份到 %TEMP%/zhiqing-backups/
• 备份目录结构：

  %TEMP%/zhiqing-backups/
  └── backup-{timestamp}/
    ├── file1.js
    ├── file2.css
    └── metadata.json

• 回滚方式：
  • 按 ID 回滚：恢复指定备份
  • 回滚上一步操作：撤销最近一次 AI 修改
  • 回滚上一条消息：撤销上一条消息中的所有修改
  • 回滚全部：撤销当前会话中所有 AI 修改
• 新增文件处理：AI 新创建的文件在回滚时会被删除

会话管理

会话存储位置：

%APPDATA%/HBuilderX/plugins/zhiqing/sessions/
├── session-1703001234567.json
├── session-1703005678901.json
└── ...

配置选项

配置文件路径：%APPDATA%/HBuilderX/plugins/zhiqing/pref.json

模型配置格式

{
  "id": "model-id",
  "name": "显示名称",
  "provider": "deepseek | openai | qwen | siliconflow | ollama",
  "apiKey": "your-api-key",
  "baseUrl": "https://api.example.com/v1",
  "model": "specific-model-name"
}

日志系统

日志配置

• 存储路径：%APPDATA%/HBuilderX/plugins/zhiqing/logs/
• 日志轮转：按天自动轮转，保留最近 7 天
• 日志级别：DEBUG / INFO / WARN / ERROR
• 敏感信息脱敏：自动对 API Key、Token 等敏感信息进行掩码处理

日志文件命名

logs/
├── 2024-01-15.log
├── 2024-01-16.log
├── 2024-01-17.log
└── ...

上下文管理

Token 管理

• 估算方式：基于字符数的启发式估算（约 1 Token ≈ 2-4 字符）
• 上下文压缩：当 Token 使用量达到窗口的 70% 时，自动压缩历史消息
• 自动截断：当 Token 使用量达到 95% 时，自动停止 Agent 循环
• 历史消息管理：智能保留系统提示和最近消息，压缩中间历史

上下文收集

Agent 在每次对话时自动收集以下上下文：

支持的项目类型自动检测：

• uni-app / Vue / React / Angular / TypeScript / Node.js

UI 界面

聊天面板

聊天面板是一个完整的 Web UI，具有以下特性：

• 主题：支持深色/浅色主题切换，偏好持久化到 localStorage
• Markdown 渲染：
  • 标题（h1-h6）
  • 列表（有序/无序）
  • 表格
  • 引用块
  • 代码块（带语法高亮）
  • 行内代码
  • 粗体/斜体/链接
• 思考过程：可折叠展示 AI 的 <think> 思考块
• 工具调用可视化：以 Pill 标签展示工具调用状态和结果
• 会话选择器：侧边栏会话列表
• 文件附件：支持附加文件到聊天上下文
• 代码操作：插入代码到编辑器、复制代码块
• 生成控制：停止生成按钮
• 回滚操作：支持回滚上一步/上一条消息/全部

快捷键

具体快捷键可在 HBuilderX 的 keybindings 中自定义。

开发者指南

项目结构详解

插件入口 (extension.js)

function activate(context) {
  // 1. 初始化日志系统
  initLogger();

  // 2. 加载配置
  initConfig(context);

  // 3. 注册命令
  registerCommands(context);

  // 4. 创建状态栏
  createStatusBar(context);

  // 5. 初始化 LLM 服务
  initLLMService();
}

function deactivate() {
  // 清理资源：停止 Agent、中止请求、销毁 UI
}

Agent 核心 (src/core/agent.js)

Agent 类的 chat() 方法是核心入口：

class Agent {
  async chat(userMessage) {
    // 1. 收集上下文
    const context = await this.contextCollector.collect();

    // 2. 构建系统提示词（含项目类型、工具说明等）
    const systemPrompt = this.buildSystemPrompt(context);

    // 3. 工具调用循环（最多 maxIterations 轮）
    for (let i = 0; i < this.maxIterations; i++) {
      // 调用 LLM（流式）
      const response = await this.llmService.chatStream(messages);

      // 解析文本和工具调用
      const { text, toolCalls } = this.parseResponse(response);

      // 如果没有工具调用，返回文本结果
      if (toolCalls.length === 0) return text;

      // 执行工具并收集结果
      for (const call of toolCalls) {
        const result = await this.executeTool(call);
        messages.push({ role: 'tool', content: result });
      }

      // 检查 Token 用量
      if (this.tokenUsage > 95%) break;
    }
  }
}

LLM Provider 继承关系

BaseProvider (基类)
├── OpenAIProvider (OpenAI 兼容)
│   ├── DeepSeekProvider
│   ├── QwenProvider
│   └── SiliconFlowProvider
└── OllamaProvider (本地模型)

添加新的 LLM Provider

1. 在 src/services/providers/ 下创建新文件
2. 继承 BaseProvider 或 OpenAIProvider
3. 实现 chat() 和 chatStream() 方法
4. 在 llmService.js 中注册新 Provider
5. 在 configManager.js 中添加默认模型配置

// src/services/providers/myProvider.js
const BaseProvider = require('./baseProvider');

class MyProvider extends BaseProvider {
  constructor(config) {
    super(config);
    this.baseUrl = config.baseUrl;
    this.apiKey = config.apiKey;
  }

  async chatStream(messages, onToken, onDone, onError) {
    // 实现流式聊天
  }

  async validateConfig() {
    // 验证 API 连通性
  }
}

module.exports = MyProvider;

添加新工具

1. 在 src/tools/ 下创建或编辑工具文件
2. 实现工具函数
3. 在 src/core/agent.js 中注册工具并添加到系统提示词
4. 实现对应的工具调用解析逻辑

// src/tools/myTools.js
async function myTool(param1, param2) {
  // 实现工具逻辑
  return { success: true, result: '...' };
}

module.exports = { myTool };

依赖说明

开发依赖使用 HBuilderX 内置的 Node.js 运行时，无需额外安装。

常见问题

Q: 如何获取 API Key？

Q: Ollama 如何使用？

1. 安装 Ollama：https://ollama.ai/
2. 拉取模型：ollama pull deepseek-r1:8b
3. 启动 Ollama 服务（默认 http://localhost:11434）
4. 在插件中选择 Ollama 模型即可，无需 API Key

Q: Agent 为什么不执行某些命令？

插件内置了命令安全系统。不在白名单中的命令需要用户确认。你可以在聊天面板中看到确认提示，点击确认后命令才会执行。

Q: 如何回滚 AI 的修改？

• 点击聊天面板中的回滚按钮
• 支持"回滚上一步操作"、"回滚上一条消息"、"回滚全部"
• 备份文件保存在系统临时目录中

Q: Token 不够用怎么办？

1. 降低深度等级（减少每次回复的 Token 消耗）
2. 减少上下文行数设置
3. 使用更大上下文窗口的模型
4. 插件会在 70% 使用率时自动压缩历史消息

Q: 如何查看插件日志？

日志文件位于：

%APPDATA%/HBuilderX/plugins/zhiqing/logs/

按天命名，保留最近 7 天。

更新日志

v2.0.0 (当前版本)

• ✨ 全新 Agent 自主编码系统（最多 20 轮工具调用循环）
• ✨ 多模型支持（DeepSeek / OpenAI / 通义千问 / SiliconFlow / Ollama）
• ✨ 图形化聊天面板（深色/浅色主题、Markdown 渲染、代码高亮）
• ✨ 行内代码补全（18 种语言、智能跳过注释/字符串）
• ✨ 文件备份与回滚系统
• ✨ 三级命令安全检查
• ✨ API Key AES-256-CBC 加密存储
• ✨ Token 智能管理与上下文压缩
• ✨ 多会话管理与持久化
• ✨ 项目类型自动检测与上下文收集
• ✨ 工具调用可视化与状态展示

智清AI助手 — 让 AI 成为你的编码伙伴 🚀