# AiCodexTool

**Repository Path**: qsdream/ai-codex-tool

## Basic Information

- **Project Name**: AiCodexTool
- **Description**: 一个AI的Agent工具，简易版工具可以调用第三方api模型使用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Codex Tool

一个基于 **Electron + React + TypeScript + Vite** 的桌面 AI 编程助手原型，目标是做一个类似 Codex / Cursor 的本地桌面开发工具。

当前版本已经具备基础骨架：
- 本地项目目录浏览
- Monaco 代码编辑器
- AI 聊天窗口
- API Key / 模型地址 / 模型选择
- 主进程代理 AI 请求
- 流式输出
- AI 修改文件并返回 diff 预览

---

## 技术栈

- Electron
- React
- TypeScript
- Vite
- Monaco Editor
- IPC
- contextBridge

---

## 当前功能

### 1. AI 配置
支持在界面中配置：
- API Key
- Base URL（OpenAI 兼容格式）
- Model

例如可用于：
- OpenAI
- OpenRouter
- 自建 OpenAI-compatible 网关
- 兼容代理层

---

### 2. 本地项目浏览
左侧文件树支持：
- 打开本地项目目录
- 递归展示目录结构
- 点击文件读取内容

实现位置：
- `src/main/services/file.service.ts`
- `src/main/ipc/file.ipc.ts`
- `src/renderer/App.tsx`

---

### 3. 代码编辑
中间区域使用 Monaco Editor：
- 打开代码文件
- 编辑代码
- 保存到本地磁盘

实现位置：
- `src/renderer/components/MonacoEditorView.tsx`
- `src/renderer/App.tsx`

---

### 4. AI 聊天
右侧 AI 面板支持：
- 输入问题
- 将当前文件作为上下文发送给 AI
- 流式显示 AI 返回内容

实现位置：
- `src/main/services/ai.service.ts`
- `src/main/ipc/ai.ipc.ts`
- `src/preload/index.ts`
- `src/renderer/App.tsx`

---

### 5. AI 代码修改与 Diff
支持基于当前文件和用户指令：
- 请求 AI 生成修改后的完整代码
- 在主进程生成 unified diff
- 在界面中显示 diff 文本预览

实现位置：
- `src/main/services/ai.service.ts`
- `src/main/services/diff.service.ts`
- `src/main/ipc/ai.ipc.ts`
- `src/renderer/App.tsx`

---

## 安全设计

本项目遵循以下安全原则：

### API Key 不暴露给渲染进程网络层
所有 AI 请求都通过 **Electron 主进程** 发出。

### 使用 contextBridge 暴露白名单 API
渲染进程只能通过 `window.api` 调用受控方法。

实现位置：
- `src/preload/index.ts`

### 禁止直接开放 Node 能力给渲染进程
主窗口启用了：
- `contextIsolation: true`
- `nodeIntegration: false`

实现位置：
- `src/main/main.ts`

### 限制文件访问范围
当前文件服务只允许在用户选定的 workspace 内读写文件，避免路径逃逸。

实现位置：
- `src/main/services/file.service.ts`

---

## 项目结构

```bash
src/
├─ main/                    # Electron 主进程
│  ├─ ipc/                  # IPC handler
│  ├─ services/             # AI / 文件 / 配置 / diff 服务
│  └─ main.ts               # Electron 启动入口
├─ preload/
│  └─ index.ts              # contextBridge 安全桥
├─ renderer/                # React UI
│  ├─ components/           # Monaco 等组件
│  ├─ styles/               # 样式
│  ├─ App.tsx               # 主界面
│  └─ main.tsx              # React 入口
└─ shared/                  # 主进程与渲染进程共享类型
   ├─ ipc.ts
   └─ types.ts
```

---

## 开发启动

### 1. 安装依赖

```bash
npm install
```

### 2. 启动开发环境

```bash
npm run dev
```

这会同时启动：
- Vite Renderer
- TypeScript watch（main/preload）
- Electron

---

## 构建

```bash
npm run build
```

构建内容：
- `dist/`：渲染进程产物
- `dist-electron/`：主进程与 preload 产物

---

## 已实现的核心文件

- `src/main/main.ts`
- `src/preload/index.ts`
- `src/main/ipc/index.ts`
- `src/main/ipc/file.ipc.ts`
- `src/main/ipc/config.ipc.ts`
- `src/main/ipc/ai.ipc.ts`
- `src/main/services/file.service.ts`
- `src/main/services/config.service.ts`
- `src/main/services/ai.service.ts`
- `src/main/services/diff.service.ts`
- `src/renderer/App.tsx`
- `src/renderer/components/MonacoEditorView.tsx`

---

## 当前限制

当前版本是 MVP 骨架，暂未包含：
- 会话历史持久化
- Monaco Diff Editor 可视化对比
- 多文件上下文选择器
- patch 直接应用
- 模型提供商适配器抽象层
- 打包发布配置
- 更安全的系统级密钥存储（如 keytar）

---

## 下一步建议

建议后续继续迭代：

1. 接入 **Monaco Diff Editor**
2. 支持 **多文件选择作为上下文**
3. 增加 **聊天历史持久化**
4. 抽象 **OpenAI / Claude / OpenRouter Provider Adapter**
5. 增加 **一键应用 AI patch**
6. 加入 **工作区索引 / RAG / Agent 模式**

---

## 许可证

当前仓库未添加 License，如需开源发布，建议补充 MIT License 或 Apache-2.0。