AI Reader (ReadFree)

Edited FileTree.vue Edited FileTree.vue Viewed FileTree.vue:1-17

如果其他人要运行或使用您上传到 Git 的这个项目，他们通常需要执行以下准备和启动步骤。为了让别人轻松上手，建议您直接将以下指南拷贝到项目的 README.md 中：

---

🚀 MeowFree (ai-reader) 运行与开发指南

欢迎使用 MeowFree！要在您的本地机器上运行或打包本软件，请遵循以下指南。

📋 1. 前置准备环境

在开始之前，请确保您的电脑上已经安装了以下软件环境：

• Node.js：建议安装 v18 或 v20 LTS 版本（下载地址）。
• Git：用于克隆项目代码。
• (可选) Docker Desktop：若需要使用高安全性隔离的本地 Shell 沙箱执行终端命令，建议安装并启动 Docker。

---

🛠️ 2. 本地开发与启动步骤

第一步：克隆项目代码

打开您的终端，执行克隆命令并进入项目目录：

git clone <您的仓库 Git 地址>
cd ai-reader

第二步：安装项目依赖

使用 npm 进行依赖项下载（该过程会根据 package.json 自动安装 Electron、Vite 等库）：

npm install

第三步：启动本地开发环境

运行开发指令，该指令会使用 electron-vite 调起带有热更新（HMR）的客户端窗口：

npm run dev

此时软件窗口应该会正常弹出，就可以在本地进行自测和调试了。

---

📦 3. 打包生成可安装文件（如 .exe）

如果您想生成发给别人直接双击安装的 .exe 安装包（不需要装 Node 即可使用），请执行：

npm run package

打包成功后，可安装的程序文件会输出在本地的 dist/ 或者是 release/ 目录中。

---

⚙️ 4. 首次使用配置说明

第一次打开软件时，其他用户需要进行以下基础配置：

1. 模型配置 (LLM API Key)：
   • 软件首次启动会引导进入设置界面，用户需要填入他们自己的大模型 API 密钥（如 DeepSeek、OpenAI、豆包等）以及对应的 API 代理端点 (API Base URL)。
2. Skill 技能库：
   • 刚克隆时，用户的技能库默认为空。他们可以点击偏好设置中的 Skill 技能库 -> 导入 Skill 导入您共享的 .md 技能规则文件。
3. MCP 扩展工具：
   • 软件会自动开启 Filesystem、DuckDuckGo 等本地内置 MCP 工具。
   • 如果他们想连接自定义 MCP 服务，可直接在 MCP 插件设置 -> 添加自定义 MCP 中添加（例如本地的数据库、搜索引擎等）。

基于 Electron 33 + Vue 3.5 + Element Plus 2.9 的智能 AI 桌面文档阅读器与自主 Agent 平台 版本 v1.1.0 · 兼容豆包 / OpenAI / DeepSeek / 通义千问 API · 支持 Ollama 本地嵌入 内置六阶段 Agent 状态机、MCP 工具生态、Milvus 向量知识库、调度器、桌面宠物、AST 代码索引等完整能力

---

目录

• 项目概述
• 核心特性
• 技术栈
• 环境依赖
• 安装部署
• 项目结构
• 架构总览
• 使用示例
• 核心模块说明
• 数据持久化
• 开发命令
• 常见问题解答
• 更新日志
• 相关文档

---

项目概述

AI Reader（代号 ReadFree）是一款面向开发者和知识工作者的智能桌面应用，将「文档阅读器」「AI Agent 平台」「知识库管理系统」三种能力融合在统一的四栏式工作台中。

应用以 Electron 为壳、Vue 3 为 UI、Node.js 为后端能力底座，通过 contextBridge 安全隔离渲染层与主进程，所有文件、Shell、网络操作均由主进程统一调度。Agent 内核采用 六阶段状态机 驱动（感知 → 评估 → 规划 → 执行 → 反思 → 完成/失败），结合 LangGraph 风格的 StateGraph 引擎实现可循环、可中断、可审批的工具调用流水线。

v1.1.0 在 v1.0.0 基础上引入了完整的 MCP（Model Context Protocol）工具生态，包含文件系统、Docker 沙箱 Shell、Git、AST、Milvus 向量检索、DuckDuckGo 搜索六类子进程工具；新增 调度器（node-cron + setTimeout 双模式）、桌面宠物（独立窗口状态机）、知识库（Milvus + Qwen3-Embedding）、自定义 Agent、AST 代码索引、长期记忆 LRU 淘汰、VS Code 风格 Hunk 级 Diff 审批 等模块。

---

核心特性

Agent 能力

• 六阶段状态机：PERCEIVING → EVALUATING → PLANNING → EXECUTING → REFLECTING → DONE/FAILED
• StateGraph 引擎：agent / tools 双节点循环，支持递归调用与中断恢复
• 流式 SSE 响应：80ms 节流 UI 更新，content / reasoning_content / tool_calls 三路增量
• 深度思考：可开关 reasoning_content，规划与执行阶段独立思考程度配置
• 三级权限审批：Ask（逐次询问）/ Auto（自动批准）/ YOLO（无审批），配合 AsyncMutex 互斥锁

工具生态（MCP）

工具类型	实现方式	说明
Filesystem	MCP 子进程	文件读写、目录遍历、批量操作
Shell	Docker 沙箱子进程	隔离执行命令行，支持超时与权限审批
Git	MCP 子进程	仓库状态、diff、commit、分支管理
AST	tree-sitter 子进程	JS/TS/Python/Bash/CSS 符号索引
Milvus	向量数据库 SDK	知识/主张/证据三类集合检索
DuckDuckGo	MCP 子进程	网络搜索，支持 SafeSearch

知识库

• 双索引：HNSW（向量）+ BM25（全文）混合检索
• 三类集合：knowledge（知识）/ claims（主张）/ evidence（证据）
• 嵌入模型：Qwen3-Embedding-4B（2560 维），通过 Ollama 本地推理
• 哈希缓存：cyrb53 哈希指纹，避免重复嵌入

调度器

• 双模式：node-cron（cron 表达式）+ setTimeout（相对延迟）
• 时区修正：自动处理 DST（夏令时）偏移
• 独立进程：src/main/scheduler.js 独立入口，与主进程解耦
• 任务编辑器：图形化创建、暂停、恢复、删除、立即触发

桌面宠物

• 独立窗口：透明无框、always-on-top、可拖拽
• 状态机：idle / thinking / working / sleeping 等状态动画
• 独立 IPC：与主窗口共享 store 但独立渲染

其他

• 四栏布局：文件树 + Agent 对话 + 计划图谱 + 文档预览，均可折叠
• 长期记忆：LRU 淘汰策略（importance×2 + access_count + 时间衰减）
• Diff 审批：LCS 动态规划算法 + VS Code 风格 Hunk 级批准/拒绝
• 多格式文档：PDF（三阶信号 OCR 判定）/ DOCX / MD / 图片 / 代码
• API Key 加密：Electron safeStorage API 系统级加密存储

---

技术栈

层级	技术	版本
桌面框架	Electron	33
前端框架	Vue 3 (Composition API, <script setup>)	3.5
UI 组件库	Element Plus	2.9
流程图可视化	@vue-flow/core	1.48
Markdown 渲染	marked + highlight.js	18 / 11
构建工具	electron-vite (Vite 5)	2.3
打包	electron-builder (Windows x64)	25
Agent 协议	@modelcontextprotocol/sdk	1.29
向量数据库	@zilliz/milvus2-sdk-node	3.0
AST 解析	tree-sitter + 5 个语言包	0.21
调度器	node-cron	4.6
文档解析	mammoth (docx), pdf-parse + pdfjs-dist (pdf), docx-preview	—
搜索	DuckDuckGo MCP / mcp-searxng	—
语言	纯 JavaScript (ESM + CommonJS)	—

---

环境依赖

必需依赖

依赖	最低版本	说明
Node.js	18.x+	推荐 20.x LTS
npm	9.x+	随 Node.js 安装
Windows	10 / 11 (x64)	当前仅支持 Windows 平台

可选依赖（按功能启用）

依赖	用途	启用条件
Ollama	本地嵌入模型推理（Qwen3-Embedding-4B）	启用知识库向量检索
Docker Desktop	Shell MCP 沙箱隔离执行	启用 Shell 工具
Milvus Server	向量数据库	启用知识库持久化（也可使用内置 Lite 模式）
Git	Git MCP 工具	启用 Git 操作能力

API 密钥（任选其一）

• 豆包（字节跳动） — 默认端点 https://ark.cn-beijing.volces.com/api/v3
• OpenAI — https://api.openai.com/v1
• DeepSeek — https://api.deepseek.com/v1
• 通义千问（阿里云） — https://dashscope.aliyuncs.com/compatible-mode/v1

---

安装部署

一、克隆仓库

git clone <repository-url>
cd Read

二、安装依赖

npm install

提示：若安装 electron 失败，可设置镜像源：

set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install

三、开发模式启动

npm run dev

此命令会启动 electron-vite 开发服务器，三端（main / preload / renderer）支持热重载。首次启动会自动在 %APPDATA%/ai-reader/init/ 下创建默认项目。

四、生产打包

# 仅编译三端代码（不打包）
npm run build

# 编译 + 打包 Windows x64 安装包
npm run package

打包产物位于 dist/ 目录下，包含 NSIS 安装程序和免安装版本。

五、可选组件配置

1. 启用 Ollama 本地嵌入

# 安装 Ollama 后拉取嵌入模型
ollama pull qwen3-embedding:4b
# 启动 Ollama 服务（默认端口 11434）
ollama serve

在应用「设置 → 知识库」中填写 Ollama 端点 http://localhost:11434。

2. 启用 Milvus 向量数据库

# 使用 Docker 快速启动单机版 Milvus
docker run -d --name milvus-standalone \
  -p 19530:19530 -p 9091:9091 \
  milvusdb/milvus:latest \
  milvus run standalone

在应用「设置 → 知识库」中填写 Milvus 地址 localhost:19530。

3. 启用 Docker 沙箱

启动 Docker Desktop，应用会自动检测并在 Shell 工具调用时创建临时容器执行命令。

---

项目结构

Read/
├── README.md                         ← 本文件
├── package.json                      ← 项目配置（v1.1.0）
├── electron.vite.config.mjs          ← electron-vite 三端构建配置（main 多入口）
├── doc_view/                         ← 项目文档目录
│   ├── codewiki.md                   ← 完整代码 Wiki（2568 行）
│   └── Agent.md                      ← Agent 模块设计文档
│
├── src/
│   ├── main/                         ← Electron 主进程
│   │   ├── index.js                  ← 主入口（约 1900 行）：窗口/IPC/文件/会话/记忆
│   │   ├── scheduler.js              ← 调度器独立入口（cron + setTimeout）
│   │   ├── ast-indexer.js            ← tree-sitter AST 符号索引器
│   │   ├── ast-server.js             ← AST 查询服务
│   │   ├── conversation-store.js     ← 会话存储抽象层
│   │   ├── memory-repository.js      ← 长期记忆仓储（LRU 淘汰）
│   │   └── desktop-pet.js            ← 桌面宠物独立窗口管理
│   │
│   ├── preload/
│   │   └── index.js                  ← contextBridge 安全桥接
│   │
│   ├── agent/                        ← Agent 内核模块
│   │   ├── index.js                  ← Agent 主入口（状态机编排）
│   │   ├── perception.js             ← 感知阶段：解析用户输入与环境
│   │   ├── planning.js               ← 规划阶段：生成任务计划
│   │   ├── action.js                 ← 执行阶段：工具调用与编排
│   │   ├── reflection.js             ← 反思阶段：自检与决策
│   │   ├── audit.js                  ← 审核阶段：权限与安全检查
│   │   ├── prompt-builder.js         ← System Prompt 动态构建
│   │   └── memory/                   ← 记忆子系统
│   │       ├── embedding.js          ← Qwen3 嵌入 + cyrb53 哈希缓存
│   │       ├── long-term.js          ← 长期记忆（LRU 淘汰）
│   │       ├── plan-memory.js        ← 计划记忆持久化
│   │       ├── session-memory.js     ← 会话级短期记忆
│   │       └── work-memory.js        ← 工作记忆（当前任务上下文）
│   │
│   ├── utils/                        ← 工具与基础设施
│   │   ├── agentFlow.js              ← Agent 流程引擎（递归循环驱动）
│   │   ├── constants.js              ← 全局常量与枚举
│   │   ├── contextAssembler.js       ← 上下文组装器（消息+记忆+工具）
│   │   ├── customAgents.js           ← 自定义 Agent 配置管理
│   │   ├── diffUtils.js              ← LCS 动态规划 Diff 算法
│   │   ├── llm.js                    ← LLM 消息构建器
│   │   ├── logger.js                 ← 分级日志（主进程落盘）
│   │   ├── markdownUtils.js          ← Markdown 解析与渲染
│   │   ├── memory.js                 ← MemorySystem 类（旧版兼容接口）
│   │   ├── mutex.js                  ← AsyncMutex 异步互斥锁
│   │   ├── ollamaVision.js           ← Ollama 视觉模型调用
│   │   ├── pdfOcr.js                 ← PDF 三阶信号 OCR 判定
│   │   ├── providerAdapter.js        ← 多 LLM Provider 适配层
│   │   ├── schedulerBridge.js        ← 调度器与主进程通信桥
│   │   ├── sse.js                    ← SSE 流式解析器
│   │   ├── tools.js                  ← Agent 内置工具集
│   │   └── graph/
│   │       └── StateGraph.js         ← LangGraph 风格状态图引擎
│   │
│   └── renderer/
│       ├── index.html                ← Vue SPA 入口 HTML
│       └── src/
│           ├── main.js               ← Vue 应用入口
│           ├── App.vue               ← 根组件（四栏布局）
│           ├── assets/
│           │   └── style.css         ← 全局样式
│           ├── stores/
│           │   └── app.js            ← reactive 全局状态（无 Pinia）
│           ├── components/
│           │   ├── SetupPanel.vue    ← 偏好设置主面板
│           │   ├── FileTree.vue      ← 左侧文件树与会话列表
│           │   ├── AgentPanel.vue    ← Agent 对话面板
│           │   ├── PlanGraph.vue     ← 任务计划图谱（@vue-flow）
│           │   ├── DocViewer.vue     ← 文档预览面板
│           │   ├── KnowledgeBase.vue ← 知识库管理界面
│           │   ├── SchedulerPanel.vue ← 调度任务列表
│           │   ├── SchedulerRunLogs.vue ← 调度运行日志
│           │   ├── SchedulerTaskEditor.vue ← 调度任务编辑器
│           │   ├── SlidePanel.vue    ← 侧滑面板容器
│           │   ├── DesktopPet.vue    ← 桌面宠物渲染
│           │   └── settings/         ← 设置子组件
│           │       ├── ApiConfig.vue
│           │       ├── AgentSettings.vue
│           │       ├── KnowledgeSettings.vue
│           │       ├── SchedulerSettings.vue
│           │       ├── ToolSettings.vue
│           │       ├── About.vue
│           │       └── index.js
│           └── ...
│
├── resources/                        ← Electron 图标等资源
├── out/                              ← electron-vite 编译产物
├── dist/                             ← electron-builder 打包产物
└── .reasonix/                        ← App 运行时数据

---

架构总览

整体交互图

渲染进程 (Vue SPA)                              主进程 (Node.js / Electron)
┌─────────────────────────────────────┐     ┌──────────────────────────────────┐
│  App.vue                             │     │  createWindow()                   │
│  ├─ SetupPanel    (条件覆盖)         │     │  └─ BrowserWindow 1400×900       │
│  ├─ FileTree      (左侧 260px)       │ IPC │                                   │
│  ├─ AgentPanel    (中左 380px)       │◄───►│  IPC Handlers (40+ 个)            │
│  ├─ PlanGraph     (中右 380px)       │     │  ├─ 文件操作 / 文档预览            │
│  ├─ DocViewer     (右侧 flex)        │     │  ├─ 会话 CRUD / 记忆管理           │
│  ├─ KnowledgeBase (知识库)           │     │  ├─ 知识库 / AST 索引              │
│  ├─ SchedulerPanel(调度)             │     │  ├─ 调度任务管理                   │
│  └─ DesktopPet    (独立窗口)         │     │  └─ 桌宠状态同步                  │
│                                      │     │                                   │
│  Stores (app.js reactive)            │     │  独立进程:                        │
│  ├─ store (全局状态)                  │     │  ├─ scheduler.js (cron 调度)      │
│  └─ loadConfig()/saveConfig()        │     │  └─ desktop-pet.js (桌宠窗口)     │
│                                      │     │                                   │
│  Utils                               │     │  MCP 子进程生态:                  │
│  ├─ agentFlow.js (流程引擎)          │     │  ├─ Filesystem MCP                │
│  ├─ StateGraph.js (状态图)           │     │  ├─ Shell MCP (Docker 沙箱)       │
│  ├─ sse.js (流式解析)                │     │  ├─ Git MCP                       │
│  ├─ diffUtils.js (Diff 审批)         │     │  ├─ AST MCP (tree-sitter)         │
│  └─ tools.js (内置工具)              │     │  ├─ Milvus MCP (向量检索)         │
└─────────────────────────────────────┘     │  └─ DuckDuckGo MCP (搜索)         │
                                            │                                   │
                                            │  数据持久化:                      │
                                            │  ├─ %APPDATA%/ai-reader/data/     │
                                            │  └─ {project}/.ReadFree/          │
                                            └──────────────────────────────────┘

四栏布局

┌──────────┬──────────────┬──────────────┬──────────────┐
│ FileTree │ AgentPanel   │ PlanGraph    │  DocViewer   │
│ (260px)  │ (380px)      │ (380px)      │  (flex)      │
│          │              │              │              │
│ 项目列表  │ AI 对话      │ 任务图谱      │ 文档预览     │
│ 会话列表  │ 工具时间线    │ @vue-flow    │ 文件树       │
│ 知识库    │ 深度思考      │ 节点+连线     │ 右键菜单     │
│ 调度任务  │ Diff 审批    │              │ PDF/DOCX/MD  │
└──────────┴──────────────┴──────────────┴──────────────┘
        可折叠          可折叠          可折叠

安全隔离

• contextIsolation: true — 渲染进程无法直接访问 Node.js API
• nodeIntegration: false — 禁用 require() 等 Node 能力
• sandbox: false — 允许 preload 使用 Node 模块
• 所有 IPC 通信通过 contextBridge.exposeInMainWorld 暴露的 window.api 进行
• API Key 使用 Electron safeStorage API 系统级加密存储

Agent 状态机

        ┌─────────────┐
        │ PERCEIVING  │ ← 解析用户输入、环境上下文、记忆
        └──────┬──────┘
               ▼
        ┌─────────────┐
        │ EVALUATING  │ ← 评估意图、判断是否需要工具
        └──────┬──────┘
               ▼
        ┌─────────────┐
        │  PLANNING   │ ← 生成任务计划（create_plan 工具）
        └──────┬──────┘
               ▼
        ┌─────────────┐    有 tool_calls
        │  EXECUTING  │ ───────────────► 执行工具 → 反馈结果
        └──────┬──────┘                       │
               │                              │
               ▼                              │
        ┌─────────────┐ <─────────────────────┘
        │ REFLECTING  │ ← 检查结果、决定是否继续
        └──────┬──────┘
               │
        ┌──────┴──────┐
        ▼             ▼
   ┌─────────┐   ┌─────────┐
   │   DONE  │   │ FAILED  │
   └─────────┘   └─────────┘

---

使用示例

示例 1：基本对话

1. 启动应用后，若未配置 API，会自动显示 SetupPanel
2. 在 SetupPanel 中选择 LLM Provider，填写 API Key，点击「测试连接并保存」
3. 进入主界面后，在左侧 FileTree 点击「新建会话」
4. 在 AgentPanel 底部输入框输入消息，按 Enter 或点击发送按钮
5. AI 响应会以流式方式逐字显示，深度思考内容（reasoning_content）折叠展示

示例 2：创建任务计划

向 Agent 发送需要多步骤的任务，例如：

请帮我分析当前项目的代码结构，并生成一份文档大纲

Agent 会调用 create_plan 工具，自动展开 PlanGraph 面板，显示任务步骤节点图：

[步骤1: 扫描目录] → [步骤2: 识别模块] → [步骤3: 生成大纲]
     wait              process              wait

每个步骤的状态会实时更新：wait → process → finish / error。

示例 3：工具调用

Agent 在执行过程中会根据需要调用工具，工具调用时间线显示在消息气泡下方：

🔧 get_current_time
   结果: { "time": "2026/7/13 14:30:00" }

🔧 update_long_term_memory
   action: append, key: memory_episode_recent
   结果: 已追加到长期记忆

示例 4：知识库上传与检索

1. 点击左侧 FileTree 的「知识库」标签
2. 选择目标集合（knowledge / claims / evidence）
3. 点击「上传文档」，选择 PDF / DOCX / MD / TXT 文件
4. 系统自动调用 Ollama 嵌入并写入 Milvus
5. 在对话中提问，Agent 会自动调用 Milvus 工具检索相关知识

示例 5：调度任务

1. 点击左侧「调度」标签进入 SchedulerPanel
2. 点击「新建任务」打开 SchedulerTaskEditor
3. 填写任务名称、cron 表达式（如 0 9 * * 1-5 表示工作日 9 点）或相对延迟
4. 编写任务 prompt（如「每天早上总结昨天的工作进展」）
5. 保存后任务会按计划自动执行，可在 SchedulerRunLogs 查看运行日志

示例 6：Shell 工具（Docker 沙箱）

在对话中请求 Agent 执行命令：

请在当前项目目录执行 npm test 并分析结果

Agent 会调用 Shell MCP 工具，在 Docker 沙箱中执行命令，根据权限模式可能弹出审批对话框。Diff 修改会以 VS Code 风格 Hunk 展示，可逐块批准或拒绝。

示例 7：桌面宠物

点击主界面右上角的桌宠图标，会独立开启一个透明窗口，显示桌宠动画。桌宠会根据 Agent 状态切换表情：思考时显示「...」、工作时显示齿轮旋转、空闲时呼吸动画。

---

核心模块说明

完整的模块说明、函数签名、参数解释、算法实现详见 doc_view/codewiki.md。

1. Agent 内核（src/agent/）

六阶段状态机驱动，核心文件 index.js 编排完整流程。perception.js 解析用户输入与上下文，planning.js 生成结构化计划，action.js 执行工具调用，reflection.js 自检结果，audit.js 权限审核，prompt-builder.js 动态构建 System Prompt。

记忆子系统分五层：embedding（嵌入生成）、long-term（长期 LRU）、plan-memory（计划持久化）、session-memory（会话级）、work-memory（工作记忆）。

2. StateGraph 引擎（src/utils/graph/StateGraph.js）

LangGraph 风格的状态图，支持节点注册、条件边、循环执行。agent 节点调用 LLM，tools 节点执行工具调用，通过条件边实现「有 tool_calls → 执行工具 → 回到 agent」的循环。

3. MCP 工具生态

通过 @modelcontextprotocol/sdk 启动六类子进程，统一通过 stdio 通信。每类工具在主进程注册独立的 client，Agent 调用时通过 executeTool 统一入口分发。

4. 调度器（src/main/scheduler.js）

独立入口，由 electron.vite.config.mjs 配置为 main 的多入口之一。支持 cron 表达式（node-cron）和相对延迟（setTimeout）两种模式，时区自动 DST 修正。通过 schedulerBridge.js 与主进程通信。

5. 知识库（KnowledgeBase.vue + Milvus）

三集合设计：knowledge（事实知识）、claims（断言主张）、evidence（证据支撑）。每集合支持 HNSW + BM25 双索引，混合检索提升召回率。嵌入通过 Ollama 调用 Qwen3-Embedding-4B（2560 维），cyrb53 哈希缓存避免重复计算。

6. Diff 审批（diffUtils.js）

基于 LCS（最长公共子序列）动态规划算法计算文件差异，按 VS Code 风格组织 Hunk，每个 Hunk 可独立批准或拒绝。支持追加/删除/修改三种变更类型识别。

7. 长期记忆 LRU（memory-repository.js）

淘汰公式：score = importance × 2 + access_count + (1 / (days_since_last_access + 1))。score 最低的记忆优先淘汰。记忆按前缀分类：user_base_* / user_context_* / agent_config_* / memory_episode_*。

8. PDF 三阶 OCR（pdfOcr.js）

判定 PDF 是否需要 OCR：一阶检测文本层完整性，二阶检测图像占比，三阶检测扫描质量。根据判定结果决定直接解析或调用 Ollama 视觉模型。

---

数据持久化

%APPDATA%/ai-reader/
├── data/
│   ├── config.json                    ← API 配置（safeStorage 加密）
│   ├── projects.json                  ← 项目路径数组
│   ├── scheduler-tasks.json           ← 调度任务定义
│   └── custom-agents.json             ← 自定义 Agent 配置
│
├── logs/
│   └── app.log                        ← 主进程 + 渲染进程统一日志
│
└── init/                              ← 默认项目（首次启动自动创建）
    └── .ReadFree/
        ├── desktop-topic-titles.json        ← 会话标题
        ├── desktop-topic-created-at.json     ← 创建时间
        ├── desktop-topic-active-at.json      ← 活跃时间
        ├── desktop-topic-title-sources.json  ← 标题来源
        ├── memory.json                       ← 长期记忆 K-V
        ├── plans.json                        ← 计划记忆持久化
        └── sessions/
            └── session_xxx.json              ← { messages, state }

每个用户项目目录下也有独立的 .ReadFree/ 结构。Milvus 数据存储在独立的向量数据库实例中。

---

开发命令

# 安装依赖
npm install

# 启动开发模式（热重载）
npm run dev

# 编译三端代码（main / preload / renderer）
npm run build

# 预览生产构建
npm run preview

# 打包 Windows x64 安装包
npm run package

# 运行调度器单元测试
npm run test:scheduler

构建配置说明

electron.vite.config.mjs 配置了 main 端的多入口：

• index — 主进程入口（src/main/index.js）
• scheduler — 调度器独立入口（src/main/scheduler.js）

renderer 端配置了别名 @ → src/renderer/src。

---

常见问题解答（FAQ）

Q1：启动后显示白屏或无法加载界面

A：检查是否已运行 npm install 安装依赖。开发模式下，首次启动 electron-vite 需要编译三端代码，请耐心等待。若持续白屏，查看终端是否有编译错误，或检查 %APPDATA%/ai-reader/logs/app.log 日志。

Q2：API 连接失败，提示「连接超时」

A：

1. 检查 API Base URL 是否正确（末尾不要加 /）
2. 检查网络是否能访问目标 API 端点
3. 豆包用户确认 API Key 已开通对应模型权限
4. OpenAI 用户若在国内，需配置代理

Q3：知识库上传文档后无法检索

A：

1. 确认 Ollama 服务已启动（ollama serve）
2. 确认已拉取嵌入模型（ollama pull qwen3-embedding:4b）
3. 在「设置 → 知识库」中测试 Ollama 连接
4. 确认 Milvus 服务已启动且地址正确
5. 查看日志是否有嵌入失败或写入错误

Q4：Shell 工具调用一直等待

A：Shell 工具依赖 Docker 沙箱。请确认：

1. Docker Desktop 已启动
2. Docker 守护进程运行正常（docker info）
3. 首次调用会拉取沙箱镜像，可能需要较长时间

Q5：调度任务没有按计划执行

A：

1. 检查 cron 表达式是否正确（使用 crontab.guru 验证）
2. 确认任务未被暂停（SchedulerPanel 中任务状态）
3. 查看 SchedulerRunLogs 中的执行记录
4. 时区按系统时区执行，DST 自动修正

Q6：桌面宠物不显示

A：桌宠是独立窗口，可能被其他窗口遮挡。检查任务栏是否有桌宠图标，或点击主界面右上角的桌宠切换按钮重新激活。

Q7：Agent 一直循环不结束

A：Agent 内核有最大循环次数保护（默认 10 次）。若超限会自动终止并返回错误。可能是 LLM 持续返回 tool_calls 导致，尝试：

1. 关闭深度思考重新发送
2. 清空当前会话重新开始
3. 检查工具返回结果是否合理

Q8：如何切换 LLM Provider

A：点击主界面右上角「设置」图标，进入 SetupPanel → API 配置，选择新的 Provider 并填写 API Key，测试连接后保存即可。配置会通过 safeStorage 加密持久化。

Q9：长期记忆如何管理

A：长期记忆存储在 {project}/.ReadFree/memory.json。Agent 通过 update_long_term_memory 工具自动维护，也可手动编辑 JSON 文件。LRU 淘汰策略自动清理低重要性记忆。

Q10：如何打包给其他用户使用

A：运行 npm run package，在 dist/ 目录下会生成 NSIS 安装程序（.exe）和免安装版本（解压即用）。目标机器需为 Windows 10/11 x64。

---

更新日志

v1.1.0 — 2026-07

新增特性

• Agent 内核重构：引入六阶段状态机（PERCEIVING / EVALUATING / PLANNING / EXECUTING / REFLECTING / DONE/FAILED），替代原 v1.0.0 的简单递归循环
• StateGraph 引擎：LangGraph 风格的状态图，支持节点注册、条件边、循环执行
• MCP 工具生态：新增六类 MCP 子进程工具
  • Filesystem（文件系统操作）
  • Shell（Docker 沙箱命令执行）
  • Git（仓库管理）
  • AST（tree-sitter 代码符号索引，支持 JS/TS/Python/Bash/CSS）
  • Milvus（向量数据库检索）
  • DuckDuckGo（网络搜索）
• 知识库模块：基于 Milvus + Qwen3-Embedding-4B 的向量知识库
  • 三类集合：knowledge / claims / evidence
  • 双索引：HNSW（向量）+ BM25（全文）
  • cyrb53 哈希缓存避免重复嵌入
• 调度器：node-cron + setTimeout 双模式，独立进程入口，时区 DST 修正
  • SchedulerPanel 任务列表
  • SchedulerTaskEditor 图形化编辑
  • SchedulerRunLogs 运行日志查看
• 桌面宠物：独立透明窗口，状态机动画（idle/thinking/working/sleeping）
• 自定义 Agent：用户可创建和配置自定义 Agent 角色
• AST 代码索引：tree-sitter 解析代码符号，支持跨文件引用查找
• 三级权限审批：Ask / Auto / YOLO 模式 + AsyncMutex 互斥锁
• Diff 审批：LCS 动态规划算法 + VS Code 风格 Hunk 级批准/拒绝
• 长期记忆 LRU 淘汰：importance×2 + access_count + 时间衰减评分
• PDF 三阶 OCR 判定：自动检测 PDF 是否需要 OCR，按需调用 Ollama 视觉模型
• API Key 加密：Electron safeStorage 系统级加密存储
• 多 LLM Provider 适配：providerAdapter.js 统一适配豆包/OpenAI/DeepSeek/通义千问

优化改进

• 主进程 IPC handler 数量从 20+ 扩展到 40+
• 流式 SSE 解析增加 80ms 节流，减少 UI 重绘开销
• 全局 store 扩展会话级独立状态（plan / agentStatus / deepThinking 等）
• electron-vite 配置 main 端多入口（index + scheduler）
• 文档预览支持 Ctrl+滚轮缩放
• 会话标题支持 auto / human / summary 三种来源

依赖升级

• 新增 @modelcontextprotocol/sdk ^1.29
• 新增 @zilliz/milvus2-sdk-node ^3.0
• 新增 tree-sitter ^0.21 + 5 个语言包
• 新增 node-cron ^4.6
• 新增 @ericthered926/duckduckgo-mcp-server ^0.6
• 新增 @kevinwatt/shell-mcp ^0.4
• 新增 mcp-searxng ^1.10

文档

• 新增 doc_view/codewiki.md（2568 行完整代码 Wiki）
• README.md 全面升级至 v1.1.0，新增 FAQ、更新日志、使用示例等章节

---

v1.0.0 — 2026-07

首次发布

• Electron 33 + Vue 3.5 + Element Plus 2.9 桌面应用基础架构
• 四栏布局：文件树 + Agent 对话 + 计划图谱 + 文档预览
• Agent 流程引擎（agentFlow.js）：规划/生成 → 执行工具 → 最终输出
• 流式 SSE 响应渲染
• 6 个内置工具：get_current_time / get_weather / get_current_location / update_long_term_memory / create_plan / update_plan_status
• 长期记忆系统（MemorySystem 类）
• 任务计划可视化（PlanGraph + @vue-flow）
• 多格式文档预览（PDF / DOCX / MD / 图片 / 代码）
• 文件树与会话 CRUD
• contextBridge 安全隔离
• electron-builder Windows x64 打包

---

相关文档

• 代码 Wiki（完整） — 2568 行，覆盖全部 59 个源文件、13 个章节、10 个流程图
• Agent 模块设计
• 项目文件说明（旧版）
• Agent 演进规划

---

许可证

本项目为私有项目，未开放开源许可证。如需使用，请联系项目维护者。

---

致谢

• Electron — 跨平台桌面应用框架
• Vue 3 — 渐进式 JavaScript 框架
• Element Plus — Vue 3 UI 组件库
• electron-vite — Electron + Vite 构建工具
• Milvus — 开源向量数据库
• Model Context Protocol — Agent 工具协议
• tree-sitter — 增量解析库
• Ollama — 本地大模型推理
• @vue-flow — Vue 3 流程图库