docs: 重写 README.md 适配 v3.0 Tool Calling 架构

README.md

@@ -2,7 +2,7 @@
 
 基于 TypeScript + Electron 的 [Ollama](https://ollama.com) 桌面 AI 聊天客户端，专为 Windows 打造。
 
-![版本](https://img.shields.io/badge/version-2.0.0--desktop-brightgreen)
+![版本](https://img.shields.io/badge/version-3.0.0--desktop-brightgreen)
 ![平台](https://img.shields.io/badge/platform-Windows%20x64-blue)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6)
 ![Electron](https://img.shields.io/badge/Electron-33-47848f)
@@ -20,9 +20,33 @@
 - **多模态** — 图片上传，自动检测 Vision 模型能力
 - **文件分析** — 支持 50+ 种文本/代码格式，单文件 ≤500KB
 
+### 🔧 Tool Calling — AI 本地文件操作（v3.0 新增）
+AI 可以在对话中主动调用本地工具来完成任务，所有操作在用户可视化监督下执行：
+
+| 工具 | 说明 | 安全级别 |
+|------|------|----------|
+| 📄 `read_file` | 读取文件内容（≤1MB，支持行范围） | 自动 |
+| ✏️ `write_file` | 写入文件（自动创建父目录） | 需确认 |
+| 📁 `list_directory` | 列出目录（支持递归、隐藏文件） | 自动 |
+| 🔍 `search_files` | 按文件名/内容搜索（支持正则、扩展名过滤） | 自动 |
+| 📂 `create_directory` | 创建目录（递归创建） | 需确认 |
+| 🗑️ `delete_file` | 删除文件/目录 | 需确认 |
+| 💻 `run_command` | 执行 Shell 命令（默认禁用） | 需确认 |
+
+**Agent Loop**：用户请求 → 模型返回 tool_calls → 客户端执行 → 回传结果 → 循环直到无工具调用，支持流式 + 并行调用 + 最大 10 轮保护。
+
+**安全模型**：
+- 路径白名单/黑名单（自动屏蔽 `/etc`, `/sys`, `.ssh` 等）
+- 命令黑名单（`rm -rf /`, `mkfs`, 反弹 shell 检测等）
+- 高风险操作弹出确认对话框（内容预览 + 一键取消）
+- 系统提示词自动注入安全规则
+
+> ⚠️ 需要模型支持 Tool Calling（推荐 Qwen3、Llama 3.1+、Mistral）
+
 ### 🧠 RAG 知识库
 - 文档上传 → 自动分块 → 向量化 → IndexedDB 持久化
 - 语义检索增强问答，支持多集合管理
+- IVF 索引优化（K-Means 聚类 + 倒排索引）
 - 需嵌入模型（如 `nomic-embed-text`）
 
 ### 🤖 Agent 预设
@@ -32,7 +56,7 @@
 
 ### 📦 数据
 - 历史记录 IndexedDB 持久化，支持搜索、分页
-- 导出格式：Markdown / HTML / TXT / JSON / .metona 加密备份
+- 导出格式：Markdown / HTML / TXT / .metona 加密备份
 - .metona 格式支持 AES-256-GCM 加密（HTTPS）或 XOR 混淆（HTTP）
 
 ### 🖥️ 桌面原生
@@ -55,8 +79,8 @@
 
 | 文件 | 类型 |
 |------|------|
-| `Metona Ollama Setup 2.0.0.exe` | NSIS 安装包（可选目录、创建快捷方式） |
+| `Metona Ollama Setup 3.0.0.exe` | NSIS 安装包（可选目录、创建快捷方式） |
-| `MetonaOllama-Portable-2.0.0.exe` | 绿色便携版（免安装，双击即用） |
+| `MetonaOllama-Portable-3.0.0.exe` | 绿色便携版（免安装，双击即用） |
 
 > ⚠️ 未签名版本，首次运行 Windows 可能弹出安全警告，点击「仍要运行」即可。
 
@@ -74,7 +98,7 @@
 ```bash
 git clone https://gitee.com/thzxx/metona-ollama.git
 cd metona-ollama
-git checkout metona-ollama-desktop-v2
+git checkout metona-ollama-desktop-v3
 
 # 安装依赖（国内使用 npmmirror 加速）
 npm config set registry https://registry.npmmirror.com
@@ -90,7 +114,7 @@ npm start
 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
 ```
 
-> 💡 Linux 交叉编译 Windows 安装包需安装 Wine：`apt install wine`
+> 💡 Linux 交叉编译 Windows 安装包需安装 Wine：`apt install wine`，详细构建指南见 [docs/BUILD.md](docs/BUILD.md)
 
 ### 常用命令
 
@@ -108,8 +132,8 @@ npm run dist:portable    # 仅便携版
 
 | 文件 | 说明 |
 |------|------|
-| `release/Metona Ollama Setup 2.0.0.exe` | NSIS 安装包 |
+| `release/Metona Ollama Setup 3.0.0.exe` | NSIS 安装包 |
-| `release/MetonaOllama-Portable-2.0.0.exe` | 绿色便携版 |
+| `release/MetonaOllama-Portable-3.0.0.exe` | 绿色便携版 |
 | `dist/main/` | 主进程编译输出 |
 | `dist/renderer/` | 渲染进程构建输出 |
 
@@ -125,12 +149,14 @@ metona-ollama/
 │   │   ├── preload.ts                 # contextBridge 安全暴露
 │   │   ├── menu.ts                    # 原生菜单系统
 │   │   ├── tray.ts                    # 系统托盘
-│   │   ├── ipc.ts               # IPC 处理器
+│   │   ├── ipc.ts                     # IPC 处理器（含 Tool Calling）
-│   │   └── utils.ts             # 主进程工具函数
+│   │   ├── utils.ts                   # 主进程工具函数
+│   │   ├── tool-handlers.ts           # 🔧 工具执行器（7 个工具实现）
+│   │   └── tool-security.ts           # 🔧 路径/命令安全检查
 │   └── renderer/                      # 渲染进程（TypeScript）
 │       ├── index.html                 # 渲染进程入口 HTML
 │       ├── main.ts                    # 渲染进程入口
-│       ├── types.d.ts           # 完整类型定义
+│       ├── types.d.ts                 # 完整类型定义（含 Tool Calling）
 │       ├── api/
 │       │   └── ollama.ts              # Ollama REST API 封装
 │       ├── db/
@@ -138,22 +164,25 @@ metona-ollama/
 │       ├── state/
 │       │   └── state.ts               # 响应式状态管理
 │       ├── components/                # UI 组件
-│       │   ├── chat-area.ts     # 消息渲染、流式更新
+│       │   ├── chat-area.ts           # 消息渲染、工具调用卡片
-│       │   ├── input-area.ts    # 输入、文件上传
+│       │   ├── input-area.ts          # 输入、Agent Loop 触发
 │       │   ├── header.ts              # 顶部导航
 │       │   ├── model-bar.ts           # 模型选择栏
-│       │   ├── settings-modal.ts
+│       │   ├── settings-modal.ts      # 设置面板（含 Tool Calling 开关）
-│       │   ├── history-modal.ts
+│       │   ├── history-modal.ts       # 历史记录
 │       │   ├── kb-modal.ts            # 知识库管理
 │       │   ├── preset-bar.ts          # Agent 预设栏
+│       │   ├── tool-confirm-modal.ts  # 🔧 工具调用确认对话框
 │       │   ├── toast.ts               # 通知组件
 │       │   └── lightbox.ts            # 图片预览
 │       ├── services/
 │       │   ├── rag.ts                 # RAG 检索增强生成
-│       │   ├── vector-store.ts  # 向量存储 + 相似度搜索
+│       │   ├── vector-store.ts        # 向量存储 + IVF 索引
-│       │   ├── document-processor.ts
+│       │   ├── document-processor.ts  # 文档分块
-│       │   ├── preset-manager.ts
+│       │   ├── preset-manager.ts      # Agent 预设管理
-│       │   └── crypto.ts        # AES-256-GCM / XOR 加密
+│       │   ├── crypto.ts              # AES-256-GCM / XOR 加密
+│       │   ├── tool-registry.ts       # 🔧 工具注册与调度中心
+│       │   └── agent-engine.ts        # 🔧 Agent Loop 核心引擎
 │       ├── utils/
 │       │   ├── utils.ts               # 工具函数
 │       │   ├── sanitizer.ts           # HTML 净化器
@@ -161,6 +190,9 @@ metona-ollama/
 │       └── styles/
 │           └── style.css              # Windows 11 Fluent Design 样式
 ├── assets/icons/                      # 图标资源
+├── docs/
+│   ├── BUILD.md                       # 构建指南（踩坑记录）
+│   └── V3-TOOL-CALLING.md            # Tool Calling 技术设计文档
 ├── vite.config.ts                     # Vite 构建配置
 ├── tsconfig.json                      # 渲染进程 TypeScript 配置
 ├── tsconfig.main.json                 # 主进程 TypeScript 配置
@@ -177,7 +209,7 @@ metona-ollama/
 | `GET /api/ps` | 运行中模型 | 设置面板 |
 | `GET /api/version` | Ollama 版本 | 连接检测 |
 | `POST /api/show` | 模型详情（能力检测） | Think/Vision 检测 |
-| `POST /api/chat` | 流式聊天（核心） | 消息发送 |
+| `POST /api/chat` | 流式聊天（核心，支持 tools） | 消息发送 / Agent Loop |
 | `POST /api/embed` | 生成嵌入向量 | RAG 知识库 |
 
 ---
@@ -191,6 +223,8 @@ metona-ollama/
 | 上下文长度 | 24576 tokens | `options.num_ctx` |
 | 温度 | 0.7 | `options.temperature` |
 | Think 模式 | 关闭 | `think` |
+| 工具调用 | 关闭（v3.0 新增） | `tools` |
+| 命令执行 | 关闭（v3.0 新增） | — |
 
 ---
 
@@ -199,24 +233,43 @@ metona-ollama/
 - **TypeScript 5.7** — 严格类型，完整接口定义
 - **Electron 33** — 桌面封装（Windows x64）
 - **Vite 5** — 渲染进程构建、HMR 热更新
-- **IndexedDB** — 异步持久化
+- **IndexedDB** — 异步持久化（对话 + 向量）
 - **Fetch + ReadableStream** — 流式 NDJSON 解析
 - **CSS Variables** — 暗色主题，毛玻璃效果
 - **electron-builder** — NSIS + Portable 打包
+- **零外部依赖** — Markdown 解析器、SHA-256、HTML 净化器全部内联实现
 
 ---
 
 ## 🔒 安全
 
+### 应用安全
 - 内置 HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查）
 - Markdown 链接仅允许 `http:` / `https:` / `mailto:` / `tel:`
 - 阻止 `javascript:` / `vbscript:` / `data:` 协议注入
 - contextIsolation + IPC 白名单 + 单实例锁
 
+### Tool Calling 安全（v3.0）
+- **路径黑名单**：自动屏蔽 `/etc`, `/sys`, `/proc`, `/dev`, `~/.ssh`, `~/.gnupg` 等
+- **写操作白名单**：仅允许用户目录下的写入
+- **命令黑名单**：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等
+- **用户确认**：写入/删除/命令执行必须用户确认
+- **安全提示词注入**：自动向 system prompt 追加工具使用安全规则
+
 ---
 
 ## 📋 更新日志
 
+### v3.0.0
+- 🔧 **Tool Calling — AI 本地文件操作系统**
+  - 7 个工具：`read_file` / `write_file` / `list_directory` / `search_files` / `create_directory` / `delete_file` / `run_command`
+  - Agent Loop 引擎：流式多轮工具调用循环，支持并行调用
+  - 安全模型：路径白名单/黑名单、命令过滤、用户确认对话框
+  - 工具调用可视化卡片（参数、状态、结果预览）
+  - 设置面板新增工具调用开关
+- ⚡ Agent Loop 触发逻辑替代普通单轮对话（工具开启时自动生效）
+- 🎨 工具调用卡片样式（5 种状态：等待确认/执行中/完成/失败/已取消）
+
 ### v2.0.0
 - ⚡ **TypeScript 全面重写** — 所有代码从 JavaScript 迁移至 TypeScript，严格类型定义
 - 🏗️ **Vite 构建系统** — 替代零构建，支持模块化打包