更新记录

0.1.2（2026-05-10） 下载此版本

1.0.0.2

0.1.0（2026-05-10） 下载此版本

初始版本

平台兼容性

HBuilderX插件通用注意事项

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

rookieape AI 完整使用说明

rookieape AI 是一个运行在 HBuilderX 右侧面板中的 AI 编程助手插件。它参考 Codex 的交互方式，支持自然对话、项目扫描、自动读取当前文件、指定路径读取、多文件修改、可审查 diff、权限控制、自动检测、还原和项目记忆。

本文档已做脱敏处理：所有本机路径、项目路径、用户目录和密钥值均使用占位符表示。

目录

• 主要能力
• 安装与打开
• 首次配置
• 对话输入框
• 智能等级
• 权限模式
• 自动修改代码
• 查看、审核和应用变更
• 自动新增文件
• 自动检测
• 还原修改
• 附件和图片
• 项目记忆
• 受保护路径
• 右键菜单和快捷键
• 常见问题

主要能力

• 右侧挂载式 AI 对话窗口，不使用独立弹窗。
• 支持 OpenAI 兼容 /chat/completions 接口。
• 支持配置 base_url、密钥、服务商、模型、智能等级、推理强度和上下文范围。
• 无需选中代码，直接描述需求即可让 Agent 自动读取当前文件和项目。
• 支持在消息中指定相对路径或绝对路径，Agent 会优先读取指定文件。
• 支持扫描整个项目，综合页面配置、源码文件、项目结构和项目记忆定位修改点。
• 支持自动新增文件，并同步接入引用、路由、菜单或配置。
• 支持上传文本文件、代码文件和图片；输入框可直接粘贴图片。
• 支持按上下键选择历史消息。
• 支持修改对比、审核应用、丢弃、还原上次修改。
• 支持 默认权限、自动审核、完全访问权限、只读 四种权限模式。
• 应用修改后会执行基础检查，并可运行项目验证命令。
• HBuilderX 关闭后会保存最近对话和项目记忆。

安装与打开

插件目录示例：

<HBuilderX安装目录>\plugins\hbuaiassistant

打开方式：

1. 打开 HBuilderX。
2. 进入 视图 -> 插件扩展视图。
3. 选择 rookieape AI。
4. 右侧会出现 AI 对话面板。

也可以从顶部菜单 工具 中执行：

• rookieape AI: 打开右侧对话
• rookieape AI: 配置 base_url / API Key

更新插件文件后，如果界面没有立即变化，请重启 HBuilderX，或重新打开插件扩展视图。

首次配置

在右侧面板点击 设置，填写连接参数：

填写后点击：

• 测试连接: 验证接口是否可用。
• 保存配置: 保存当前设置。

密钥也可以通过环境变量提供。请只在本机环境变量或 HBuilderX 配置中保存真实密钥，不要写入说明文档、截图或代码仓库。

对话输入框

底部输入框参考 Codex 的操作方式：

• +: 上传附件。
• 权限模式: 控制是否允许写入文件。
• 服务商: OpenAI、DeepSeek、Qwen 或自定义。
• 模型: 选择实际请求的模型。
• 智能等级: 控制项目扫描范围和推理强度。
• ↑: 发送消息。
• ■: 任务运行时显示，点击可停止当前模型请求。

快捷键：

• Enter: 发送。
• Shift + Enter: 换行。
• ↑ / ↓: 在输入框为空或光标位于边界时切换历史消息。

智能等级

智能等级会影响：

• 推理强度。
• 当前文件上下文字符数。
• 项目扫描文件数。
• 单文件扫描字节数。

权限模式

推荐日常使用 默认权限。如果希望更接近 Codex 的自动完成体验，可以使用 自动审核。只有在明确信任当前任务和项目状态时才使用 完全访问权限。

自动修改代码

直接描述需求即可，例如：

把首页改成学生管理页面，包含学生列表、搜索、新增、删除和统计卡片

Agent 会自动：

1. 读取当前打开文件。
2. 识别项目根目录。
3. 扫描相关项目文件。
4. 结合项目记忆判断修改范围。
5. 生成修改方案和变更集。
6. 在对话中展示 diff。
7. 根据权限模式等待审核，或自动审核后写入。

如果指定文件路径，Agent 会优先读取该文件：

修改 pages/index/index.vue，把首页做成课程列表

也可以使用脱敏后的绝对路径占位符：

修改 <项目根目录>\pages\index\index.vue，增加登录状态恢复

建议在说明、截图或工单中使用 <项目根目录>、<用户目录>、<HBuilderX安装目录> 等占位符，不要暴露真实本机路径。

查看、审核和应用变更

当 Agent 生成可审查修改时，对话中会出现变更卡片。

变更卡片支持：

• 查看变更文件数量。
• 查看新增/删除行数。
• 展开每个文件的 diff。
• 撤销: 丢弃当前待应用修改。
• 审核: 应用当前修改。
• ↕: 展开或收起 diff。

底部变更摘要只会在存在真实待审核修改时显示。点击 查看更改 会跳转到最近一次 diff 并自动展开。

自动新增文件

当需求需要新增页面、组件、工具函数或配置文件时，Agent 可以自动生成新文件。例如：

新增一个课程详情页，并把 pages.json 路由配置好

插件会要求 Agent 同步完成必要接入，例如：

• 新增页面文件。
• 修改页面配置。
• 添加组件引用。
• 添加路由或菜单配置。
• 添加必要的样式或状态逻辑。

如果同名文件已经存在，插件会阻止覆盖，避免误删已有代码。

自动检测

应用修改后，插件会先做基础检查：

• JSON 解析检查。
• JavaScript 语法检查。
• Vue SFC 基础检查。
• Git 冲突标记检查。
• NUL 字符检查。

如果配置了验证命令，还会运行项目脚本。

验证命令 可配置为：

auto

表示自动识别项目脚本中的：

• lint
• test
• build

也可以配置为安全脚本命令：

npm run build

跳过验证：

none

默认命令策略只允许安全的包管理器脚本命令，例如 npm、pnpm、yarn、bun 的项目脚本。

还原修改

每次应用修改前，插件会保存快照。

如需还原：

1. 打开 设置。
2. 点击 还原上次修改。

还原会恢复最近一次应用前的文件内容。

附件和图片

点击输入框左下角 + 可以上传附件。

支持：

• 文本文件。
• 代码文件。
• JSON、Markdown、配置文件。
• 图片。

也可以直接把截图粘贴到输入框。

限制：

• 单次最多 6 个附件。
• 图片最大 5MB。
• 文本文件最多读取 80000 字符。
• 二进制文件只发送文件名、类型和大小。

图片理解需要所选模型支持视觉输入。

项目记忆

插件会按项目保存：

• 最近任务。
• 最近修改文件。
• 检测结果。
• 项目摘要。
• 常见偏好。

脱敏后的记忆文件位置示例：

<用户主目录>\.rookieape-ai\memory.json

脱敏后的最近会话位置示例：

<用户主目录>\.rookieape-ai\chat-session.json

清除记忆：

1. 打开 设置。
2. 点击 清除记忆。

新会话：

点击顶部 新会话，可以清空当前对话显示。

注意：最近会话可能包含你粘贴的图片 data URL 或文本附件内容。如果不希望保留，请使用 新会话 或删除对应本地会话文件。

受保护路径

默认不会修改这些内容：

• .env
• .env.*
• *.pem
• *.key
• *.p12
• *.cer
• *.crt
• 锁文件
• 依赖目录
• 构建产物目录
• 版本控制目录

可以在设置中修改：

• 受保护路径
• 允许写入目录
• 允许修改扩展名

请不要把真实密钥、证书、私钥或生产环境配置放入对话、附件或说明文档。

右键菜单和快捷键

在编辑器中右键可使用：

• rookieape AI: 打开右侧对话
• rookieape AI: 修改选中代码
• rookieape AI: 解释选中代码

快捷键：

Ctrl + Alt + A

macOS：

Command + Alt + A

常见问题

提示密钥未配置

打开 设置，填写服务商密钥并保存。也可以使用本机环境变量提供密钥。不要把真实密钥写进文档或提交到仓库。

请求失败

检查：

• base_url 是否正确。
• 密钥是否有效。
• 当前模型名称是否存在。
• 第三方接口是否兼容 OpenAI /chat/completions。
• 网络代理或防火墙是否阻止请求。

没有自动修改文件

可能原因：

• 当前权限模式是 只读。
• Agent 没有生成可应用变更集。
• 文件扩展名不在允许列表中。
• 文件命中了受保护路径。
• 文件在生成 diff 后被手动改过，插件阻止覆盖。

可以继续补充需求或明确文件路径后重新发送。

指定路径仍提示没有打开文件

请使用清晰路径格式，例如：

修改 pages/index/index.vue，增加学生搜索

或：

路径: pages/index/index.vue
需求: 把页面改成课程列表

绝对路径建议在对外文档中脱敏：

路径: <项目根目录>\pages\index\index.vue

自动检测失败

先查看检测输出。常见原因：

• 项目依赖未安装。
• 项目脚本本身失败。
• 修改后出现语法错误。
• 验证命令不符合安全命令策略。