AI AI 开发工具箱

AI 开发工具箱操作手册

AI 开发工具箱 是面向本地软件开发工作的桌面应用，提供项目工作区、JSON 处理、API 调试、Git 辅助、GeoJSON 体检、AI 代码解释、AI 代码生成、AI 历史复用和应用设置等能力。

当前版本：0.1.0

目录

安装与启动

使用发布包

发布产物位于 release/ 目录：

release/AI 开发工具箱 Setup 0.1.0.exe
release/AI 开发工具箱 0.1.0.exe
release/win-unpacked/AI 开发工具箱.exe

双击对应 exe 即可启动。首次启动后，应用会自动创建本地数据库和运行数据目录。

从源码启动

需要安装 Node.js 和 npm。Windows PowerShell 下建议使用 npm.cmd：

npm.cmd install
npm.cmd run dev

首次配置

AI 功能需要配置至少一个兼容 OpenAI Chat Completions 协议的平台。可以使用 .env 文件，也可以在应用的 设置 页面保存。

使用 .env

复制 .env.example 为 .env，按需填写：

SILICONFLOW_API_KEY=
SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
OPENAI_COMPATIBLE_API_KEY=
OPENAI_COMPATIBLE_BASE_URL=https://api.example.com/v1

API Key 不会写入 SQLite。通过设置页保存 API Key 时，会写入项目根目录 .env。

在设置页配置

  1. 打开左侧 设置。
  2. 选择模型平台，例如 SiliconFlow、OpenAI、DeepSeek 或 OpenAI 兼容平台。
  3. 填写 Base URL、模型名称、API Key 和请求超时。
  4. 点击保存。
  5. 使用连接测试确认模型可用。

界面导航

应用左侧为模块导航：

顶部的最近项目下拉框可快速切换项目上下文。

项目工作区

项目工作区用于把 AI 历史、API 请求集合、Git 默认目录和地理体检记录关联到具体项目。

新增项目

  1. 打开 项目工作区。
  2. 点击新建或选择项目目录。
  3. 填写项目名称、目录、标签和说明。
  4. 点击 保存项目。

保存后，该项目会出现在左侧项目列表和顶部最近项目入口中。

编辑项目

  1. 在项目列表中选择项目。
  2. 修改名称、目录、标签或说明。
  3. 点击 保存项目。

删除项目

  1. 选择项目。
  2. 点击删除按钮。
  3. 在确认弹窗中确认。

删除项目工作区不会删除本地源码目录。

项目包

项目包用于迁移项目相关数据，包括项目记录、AI 历史、API 请求和地理体检历史。

JSON 工具

格式化 JSON

  1. 打开 JSON工具。
  2. 将 JSON 粘贴到输入区。
  3. 选择缩进。
  4. 点击格式化。

压缩 JSON

  1. 输入 JSON。
  2. 点击压缩。
  3. 输出区会显示去除空白后的 JSON。

校验 JSON

  1. 输入 JSON。
  2. 点击校验。
  3. 状态栏会显示校验结果；格式错误时会显示错误原因。

路径查询

  1. 输入有效 JSON。
  2. 在路径查询中输入字段路径。
  3. 查看匹配结果。

API 测试

API 测试支持请求调试、环境变量、请求集合、请求历史、OpenAPI 导入和项目接口自动发现。

发送请求

  1. 打开 API测试。
  2. 选择项目工作区。
  3. 选择请求方法。
  4. 输入 URL。相对路径可以使用 {{baseUrl}} 前缀。
  5. 按需填写 Headers、Query、Body 和断言。
  6. 点击发送。

响应区域会显示状态码、耗时、响应头和响应 Body。

保存请求

  1. 完成请求配置。
  2. 填写请求名称。
  3. 点击保存。

保存后的请求会进入 API 请求集合，并可按分组折叠查看。

导入 OpenAPI / Swagger

  1. 打开 API测试。
  2. 选择项目。
  3. 导入 OpenAPI / Swagger JSON。
  4. 在预览结果中检查接口数量和分组。
  5. 确认后导入为请求集合。

自动发现项目 API

  1. 先在 项目工作区 保存项目目录。
  2. 打开 API测试 并选择项目。
  3. 点击项目 API 自动扫描。
  4. 应用会异步扫描后端 Spring Controller 和前端 fetch / axios 调用。
  5. 扫描完成后按 Controller 或来源文件分组预览。
  6. 确认后导入请求集合。

自动发现以静态扫描为主，动态拼接 URL 和复杂框架约定需要人工复核。

AI 分析响应

  1. 先完成一次请求。
  2. 确认 AI 平台已配置。
  3. 点击 AI 分析。
  4. 查看 Markdown 渲染后的分析结果。

分析历史会写入 AI 历史，并可在 AI历史中心 检索。

Git 助手

Git 助手用于查看仓库状态、差异、提交历史，并辅助生成变更说明和提交信息。

设置工作目录

  1. 打开 Git助手。
  2. 选择项目工作区，或手动输入 Git 仓库目录。
  3. 点击执行命令。

查看状态、日志和差异

暂存文件

  1. 在变更列表中勾选文件。
  2. 点击批量暂存或批量取消暂存。
  3. 对单个文件也可以使用行内暂存按钮。

生成 Git AI 内容

  1. 确认 AI 配置可用。
  2. 选择 Git AI 模板。
  3. 点击生成 Git 变更说明 或 Commit Message。
  4. 需要提交时，可将生成的 Commit Message 填入提交信息区域。

Git AI 输出会保存到历史记录。

地理数据体检

地理数据模块用于分析 GeoJSON 数据质量。

分析 GeoJSON

  1. 打开 地理数据。
  2. 选择项目。
  3. 填写报告名称。
  4. 粘贴 GeoJSON，或导入 .json/.geojson 文件。
  5. 选择字段模板，或手动填写必填属性。
  6. 点击分析。

分析结果包括：

使用字段模板

内置模板包括：

点击模板后，必填属性会自动填入。

导出报告

分析完成后可以导出：

历史报告可按项目查看、载入、删除或清空。

AI 解释代码

解释代码

  1. 打开 AI解释代码。
  2. 选择项目。
  3. 选择 Prompt 模板。
  4. 填写模板变量。
  5. 粘贴需要解释的代码。
  6. 点击执行。

输出支持 Markdown 渲染。生成过程中可以停止。

使用历史

AI 生成代码

生成代码

  1. 打开 AI生成代码。
  2. 选择项目。
  3. 选择 Prompt 模板。
  4. 填写需求描述。
  5. 点击生成。

输出支持 Markdown 渲染。

复制代码块

生成结果包含代码块时，可以直接复制第一个代码块，用于快速粘贴到编辑器。

使用历史

AI 生成历史支持查看详情、复制、重新执行和删除。

AI 历史中心

AI 历史中心统一管理代码解释、代码生成、API 分析、Git 变更说明和 Commit Message 历史。

检索历史

  1. 打开 AI历史中心。
  2. 选择项目或全部项目。
  3. 选择任务类型。
  4. 输入关键词。
  5. 按需开启只看收藏。

查看和复用

清理历史

点击清空按钮会清理当前筛选结果中的历史记录。执行前会弹出确认。

设置与数据维护

模型设置

设置页支持：

可配置 Base URL、模型、API Key 和请求超时，并执行连接测试。

Prompt 模板

设置页集中管理 Prompt 模板：

  1. 选择任务类型。
  2. 选择已有模板或新建模板。
  3. 编辑模板名称和内容。
  4. 使用变量预览模板。
  5. 保存模板。

模板变量使用双花括号，例如：

请解释以下代码：

{{ code }}

可为项目设置默认模板。

数据库信息

设置页会显示：

开发环境数据库默认位于：

data/devtools-codex.db

打包环境会使用 Electron userData/data 目录，避免安装目录不可写。

数据库维护

支持以下操作：

清理和恢复操作会先要求确认。

导入导出

设置页支持：

项目工作区支持：

导入文件会进行格式校验。格式无效时不会部分写入。

导出 JSON 使用统一结构：

{
  "version": 1,
  "type": "prompt-templates",
  "exportedAt": "2026-05-07T00:00:00.000Z",
  "items": []
}

开发与发布命令

本地开发

npm.cmd install
npm.cmd run dev

验证

npm.cmd run typecheck
npm.cmd test
npm.cmd run build

build 会执行 ESLint、Prettier 检查、TypeScript 检查、Electron/Vite 构建和构建产物校验。

打包

npm.cmd run pack
npm.cmd run dist

发布前检查

发布前至少确认：

常见问题

AI 功能提示未配置 API Key

检查 .env 或设置页是否填写了当前平台的 API Key。切换平台后，需要确认对应平台的 Base URL 和 Key 都已保存。

模型连接失败

检查：

API 自动发现结果不完整

自动发现基于静态扫描。以下情况可能需要手动补充：

Git 助手没有输出

确认工作目录是 Git 仓库，且本机已安装 Git。项目工作区路径不一定等于 Git 仓库根目录，必要时手动填写仓库目录。

打包时出现 spawn EPERM

这通常是安全策略或沙箱限制导致 esbuild 子进程无法启动。请在普通 PowerShell 或允许子进程执行的环境中运行：

npm.cmd run dist

PowerShell 显示中文乱码

文件本身使用 UTF-8。若 PowerShell 输出乱码，可使用支持 UTF-8 的终端，或通过编辑器查看 Markdown 文件。