# mini AI 助手软件需求规格说明书

## 1. 项目概述
本项目旨在构建一个轻量级 **桌面 AI 助手**，它允许用户通过自然语言与一个大语言模型（LLM）交互，并授权该模型执行本地文件系统操作（读写、复制、移动、删除）、Excel 数据处理、以及任意的 Shell 命令（需用户二次确认）。所有操作均在本地回环网络中进行，不依赖任何外部 Web 服务上传文件，从而规避企业或学校对网页上传的拦截策略。

前端采用 **Vue 3** 构建用户界面，后端使用 **Bun**（JavaScript 运行时）提供 HTTP 服务和 LLM 调用能力。整个项目 **纯 JavaScript / TypeScript** 实现，不依赖 Python，不依赖 C/C++ 原生库，所有第三方依赖均为开源纯 JS 模块。

---

## 2. 技术栈

| 层级 | 技术选型 | 说明 |
| :--- | :--- | :--- |
| **前端** | Vue 3 + Vite | 使用 Composition API，组件化开发 |
| | Vue Router（可选） | 若需要多页面视图 |
| | Pinia（可选） | 状态管理（对话历史、配置等） |
| | Markdown 渲染 | `markdown-parser-vue` 或 `@vueuse/head` + `marked` 或 `mermaid`（支持图表） |
| | 表格组件 | 可用 `element-plus` 的 Table 或纯 CSS 表格 |
| | 进度条 | 自定义组件或 `element-plus` 的 Progress |
| | HTTP 客户端 | `axios` 或原生 `fetch` |
| **后端** | Bun 1.0+ | JavaScript/TypeScript 运行时，内置 HTTP 服务器、文件系统 API、子进程 |
| | LLM 调用 | 使用 OpenAI 兼容 API（支持 OpenAI、Groq、本地 Ollama 等） |
| | 文件操作 | 原生 `fs` / `Bun.file` / `Bun.write` |
| | Excel 处理 | `xlsx` (SheetJS) 或 `hucre` / `modern-xlsx`（纯 JS，无原生依赖） |
| | 环境变量 | `dotenv` |
| **依赖管理** | Bun 内置包管理器 | `bun install` |

---

## 3. 用户角色
- **普通用户**：通过对话框向 AI 下达指令，审批危险操作。
- **管理员（可选）**：配置 LLM 参数（API Key、模型、温度）、工作目录白名单等。

---

## 4. 功能需求

### 4.1 对话交互
- **FR1**：前端提供一个聊天界面，支持用户输入文本，并实时显示 AI 的回复。
- **FR2**：支持 Markdown 格式渲染（包括代码块语法高亮、表格、列表、加粗、链接等）。
- **FR3**：对话历史保存在前端内存中，可清空或导出。
- **FR4**：支持流式（SSE）或非流式响应，建议优先实现流式以获得更好体验。

### 4.2 文件系统操作（AI 可调用的工具）
AI 模型将通过函数调用（Function Calling）请求执行以下操作，所有操作需在用户指定的**工作目录**（默认为项目根目录）内进行，防止越权。

| 工具名称 | 功能描述 | 参数 | 是否需审批 |
| :--- | :--- | :--- | :--- |
| `read_file` | 读取指定路径文件内容（文本） | `path` | 否 |
| `write_file` | 将内容写入指定文件（覆盖） | `path`, `content` | 否（仅写入文本） |
| `list_directory` | 列出目录下的文件和子目录 | `path`（可选） | 否 |
| `copy_file` | 复制文件或目录（递归） | `source`, `destination` | 否（但若目标覆盖需提示） |
| `move_file` | 移动/重命名文件或目录 | `source`, `destination` | 否 |
| `delete_file` | 删除文件或空目录 | `path` | **是（需二次确认）** |
| `execute_command` | 执行任意 Shell 命令 | `command` | **是（危险命令需二次确认）** |
| `read_excel` | 读取 Excel 文件，返回 JSON 数据（带行数限制） | `path`, `sheet?`, `limit?` | 否 |
| `write_excel` | 将 JSON 数据写入 Excel 文件 | `path`, `data` (JSON 数组), `sheet?` | 否 |

**审批机制**：当 AI 调用需要审批的工具时，后端不立即执行，而是向前端推送一个“审批请求”消息，包含待执行的命令/操作详情。前端弹窗让用户选择“允许”或“拒绝”，用户确认后，前端再向后端发送批准指令，后端才真正执行并将结果返回给 AI。

### 4.3 Excel 操作特殊要求
- 读取时默认最多返回前 200 行数据（可配置），但会告知总行数和列名，让 AI 据此进行数据分析（如求和、筛选）。
- 支持自动识别日期、数字格式。
- 写入时支持从 JSON 数组生成 Excel 文件，列名自动取自对象键名。

### 4.4 文件拷贝进度展示
- 当 AI 执行 `copy_file` 操作时，若拷贝大文件/目录，后端通过 WebSocket 或 SSE 向前端推送进度百分比。
- 前端在聊天消息中嵌入一个进度条组件，实时更新。

### 4.5 命令执行安全控制
- 后端在执行命令前会检查命令是否包含危险关键字（如 `rm -rf /`, `dd`, `shutdown` 等），若匹配则自动拒绝并提示用户。
- 用户可在配置中启用“严格模式”，禁止任何命令执行（此时 `execute_command` 工具直接返回“禁用”提示）。

### 4.6 多轮对话与上下文记忆
- AI 能记住对话历史（默认保留最近 20 条），并在需要时主动调用工具。
- 用户可手动清空上下文。

---

## 5. 非功能需求

### 5.1 性能
- 页面首次加载时间 ≤ 2 秒（开发环境）。
- 大文件（>100MB）读取或写入时，采用流式处理，避免内存溢出。

### 5.2 安全
- 所有文件操作路径限制在 `process.cwd()` 及其子目录下（可通过环境变量 `WORKSPACE` 修改）。
- 禁止访问系统敏感目录（如 `/etc`, `C:\Windows` 等）。
- 传输层：前后端通信使用 HTTP，仅在本地监听 `127.0.0.1`，默认不对外暴露端口。

### 5.3 可用性
- 界面风格简洁，采用深色/浅色主题（可切换）。
- 消息气泡区分用户和 AI，AI 消息支持 Markdown 渲染。
- 错误信息明确提示，并建议用户如何修改指令。

### 5.4 可扩展性
- 工具函数采用插件化设计，新增工具只需添加定义和执行函数。
- 支持更换 LLM 提供商（只需修改环境变量 `BASE_URL` 和 `API_KEY`）。

### 5.5 兼容性
- 前端运行于现代浏览器（Chrome 90+, Edge 90+, Firefox 88+）。
- 后端仅要求 Bun 1.0+，支持 Windows / macOS / Linux。

---

## 6. 界面设计概要（Vue 组件划分）

- **App.vue**：整体布局，包含头部标题和聊天容器。
- **MessageList.vue**：消息列表，遍历消息数组，根据角色渲染不同样式。
- **MessageBubble.vue**：单条消息，支持 Markdown 渲染和特殊类型（如审批请求、进度条）。
- **InputArea.vue**：输入框 + 发送按钮，支持 Enter 发送。
- **ApprovalDialog.vue**：审批弹窗，显示命令详情并提供允许/拒绝按钮。
- **ProgressBar.vue**：进度条组件，接收百分比值。
- **SettingsDrawer.vue**（可选）：配置 API 密钥、模型参数等。

---

## 7. API 接口设计（前后端通信）

所有接口采用 JSON 格式。

### 7.1 发送消息（含工具调用）
- **Endpoint**: `POST /api/chat`
- **Request Body**:
```json
{
  "messages": [ // 对话历史，至少包含用户最新一条
    { "role": "user", "content": "读取 data.xlsx 并告诉我销售额" }
  ]
}
```
- **Response**（分三种情况）：
  1. **直接回复**（无工具调用）：
```json
{ "type": "done", "message": "销售额为 12345 元" }
```
  2. **需要审批**：
```json
{
  "type": "approval_required",
  "tool_call_id": "call_abc",
  "command": "rm -rf temp",
  "assistant_message": "我想删除 temp 文件夹，请批准"
}
```
  3. **工具执行结果**（已自动完成并返回最终回复）：
```json
{ "type": "done", "message": "已成功写入 Excel 文件" }
```

### 7.2 批准操作
- **Endpoint**: `POST /api/approve`
- **Request Body**:
```json
{
  "tool_call_id": "call_abc",
  "approved": true
}
```
- **Response**: 执行结果（同上面“工具执行结果”格式）

### 7.3 进度推送（WebSocket 或 SSE）
- 若使用 WebSocket，路径 `/ws`，后端在拷贝大文件时推送 `{ "progress": 45 }`。

---

## 8. 部署与运行

- 开发环境：`bun run dev`（同时启动后端和前端，可分别用 `vite` 和 `bun` 热更新）。
- 生产环境：`bun run build` 打包前端，后端使用 `bun server.js` 运行，并静态托管前端构建产物。
- 用户仅需执行 `bun install` 安装依赖，无需全局安装任何程序。

---

## 9. 未来扩展（可选）
- 支持多 Agent 协作（多个角色）。
- 支持语音输入/输出。
- 支持插件市场，用户可自定义工具。

---

## 10. 附录：开源库推荐（符合“纯 JS，无 C 依赖”）

| 功能 | 推荐库 | 理由 |
| :--- | :--- | :--- |
| Excel 读写 | `xlsx` (SheetJS 社区版) | 最成熟，纯 JS，支持 xlsx/xls/csv |
| 或 `modern-xlsx` | 基于 Rust+WASM，但无需本地编译，通过 npm 提供 WASM 文件，也算纯 JS 使用 |
| 进度条（前端） | `element-plus` 或自定义 | UI 组件库自带的进度条 |
| Markdown 渲染 | `marked` + `highlight.js` | 轻量且高度可定制 |
| 表格组件 | `element-plus` Table 或 `ag-grid-community` | 前者轻量，后者功能丰富 |
| 文件操作（后端） | 使用 Bun 内置 API | 无需额外库 |