miniai/doc/需求.md

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:

{
  "messages": [ // 对话历史，至少包含用户最新一条
    { "role": "user", "content": "读取 data.xlsx 并告诉我销售额" }
  ]
}

• Response（分三种情况）：
  1. 直接回复（无工具调用）：

{ "type": "done", "message": "销售额为 12345 元" }

2. 需要审批：

{
  "type": "approval_required",
  "tool_call_id": "call_abc",
  "command": "rm -rf temp",
  "assistant_message": "我想删除 temp 文件夹，请批准"
}

3. 工具执行结果（已自动完成并返回最终回复）：

{ "type": "done", "message": "已成功写入 Excel 文件" }

7.2 批准操作

• Endpoint: POST /api/approve
• Request Body:

{
  "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	无需额外库