EssenceStream 是一个本地优先的个性化 AI 每日信息简报与知识管理系统。它把数据源采集、内容标准化、简报筛选、知识沉淀、Wiki 修订和受控 Agent 操作组织在同一套本地工作流中，运行数据主要保存在用户指定的数据目录。
Important
当前可靠运行形态是面向单用户可信环境的本机源码部署：Vue/Vite 前端、Node.js/Express 后端、Qdrant 容器和 Python 内容工具链分别运行。仓库暂未提供可直接面向公网部署的一体化生产发布物。
| 能力 | 说明 |
|---|---|
| 每日简报 | 从已启用的数据源发现内容，经过标准化、向量初筛和 LLM 精筛后，生成按日期组织的个性化简报。 |
| 简报总览 | 按日期和月份浏览简报与 Wiki，快速回到历史知识内容。 |
| 数据源管理 | 管理 AlphaXiv、SmolAI、RSSHub 和自定义来源，支持来源测试、启停与健康检查。 |
| 画像与反馈 | 管理用户画像、标签、权重和 Prompt，并将反馈用于后续简报筛选。 |
| 知识工作台 | 导入 URL、文本和文件，生成标准化知识对象，并完成向量/关键字搜索、筛选、准入和状态管理。 |
| Wiki 管理 | 维护正式 Wiki 页面、修订历史、来源引用、提案审核和质量检查。 |
| Agent Wiki 工作台 | 通过受限工具完成知识搜索、事实读取和受控 Wiki 写入，并以变更清单展示及回滚本轮修改。 |
| Memory 记忆 | 按策略抽取、召回、维护和重建 Agent 会话记忆，可在系统或会话级控制是否使用和生成记忆。 |
| 系统运行与观测 | 提供首次配置、模型路由、依赖健康状态、结构化运行记录和本地数据 Git 同步能力。 |
系统从已启用的论文、技术博客和订阅源获取内容，先统一整理网页和文档格式，再分阶段检查重复内容：先过滤同一次采集中的重复地址，再比较整理后的正文特征，最后与历史简报进行跨日期比对，减少相同内容反复出现。
筛选时，确定性规则先排除重复、无效或明显不符合条件的候选；语义相似度用于判断内容与用户兴趣及已有知识的相关程度，并进一步缩小候选范围；大模型只在受控的数量和长度范围内完成最终判断、摘要和排序。最终结果以大模型的语义判断为主，同时参考来源优先级、内容相似度和用户长期偏好，避免把全部候选直接交给模型造成成本、速度和质量失控。
正式 Wiki 正文和修改版本保存在本地，搜索索引只负责加速查询，可以从本地内容重新建立。用户可以按标题、标签、正文关键词、内容含义和时间查找知识；关键词检索通过倒排索引和缓存减少全文扫描，语义检索则用于发现措辞不同但主题相近的内容。
不同搜索方式会组合标题命中、正文相关性、语义相似度和时间条件。语义能力暂时不可用时，系统会依次切换到正文关键词和标题关键词检索，并明确显示当前使用的搜索方式。Wiki 新建、修改或归档后会立即刷新对应索引；索引更新失败时保留已经写入的正文，并将索引标记为可重试状态，而不是丢失用户修改。
用户发送需求后，Agent 会先整理当前会话、相关 Wiki、可用记忆和允许使用的操作。模型每一轮只决定下一步是搜索、读取、请求修改、向用户提问还是生成最终回答；工具执行结果会返回给模型，模型根据新信息继续判断，直到任务完成或需要用户补充。模型判断、工具调用和工具结果会按步骤显示在页面中。
Agent 只能使用白名单能力，并受到最大执行步骤、工具调用次数、整体执行时间、重复调用检测和结果长度限制。目标 Wiki、修改范围或依据不明确时，Agent 会暂停并请求用户补充，不继续猜测。正式修改会先读取并校验当前版本，再形成用户可查看的变更清单；只有内容仍处于修改后的版本时，系统才允许安全回退，避免旧操作覆盖后续更新。
Memory 分为长期偏好和会话经验两类。长期偏好保存用户持续关注的领域、内容类型和明确习惯，为后续简报筛选提供辅助背景；会话经验只从已经完成的 Agent 会话中提取可复用的任务边界、处理经验和用户习惯。仅针对当前任务的临时要求不会自动变成长期记忆。
记忆写入前会判断会话是否完成、内容是否适合长期保存、适用范围是否明确，以及是否包含敏感或可能污染后续任务的信息；有风险的内容会被隔离而不是直接使用。新任务开始时，系统只召回与当前目标真正相关的少量记忆作为辅助提示。Memory 不能替代正式 Wiki，也不能单独支撑知识修改。
- 分阶段使用智能能力：将确定性规则、语义相似度和大模型判断安排在不同阶段，用低成本方法处理重复和缩小范围，把大模型集中在真正需要理解和判断的候选上。
- 多层本地检索与逐级降级：标题、正文关键词和语义搜索共同组成检索能力，并通过倒排索引、缓存和逐级切换保证外部语义能力不可用时，本地 Wiki 仍然可以查询。
- 有边界的 Agent 执行框架：Agent 通过受控循环完成任务，模型只能提出白名单操作请求；系统统一负责参数检查、步骤与时间限制、用户停等和写入版本保护。
- 分层 Memory 与污染控制：记忆在保存前判断是否适合长期复用，在召回前判断是否与当前任务相关，并对敏感或高风险内容进行过滤或隔离。
flowchart LR
User["本地用户 / 浏览器"] --> Client["Vue 3 + Vite 前端"]
Client -->|"/api/v1"| Server["Express + TypeScript 后端"]
Server --> Briefing["每日简报筛选"]
Server --> Knowledge["本地 Wiki 与搜索"]
Server --> Agent["Agent 工作流"]
Server --> Memory["偏好与会话记忆"]
Server --> System["配置、观测与 Git 同步"]
Sources["AlphaXiv / SmolAI / RSSHub / Web"] --> Briefing
Python["Python 内容提取工具链"] -->|"内容解析"| Briefing
Python -->|"文件与网页导入"| Knowledge
Briefing -->|"用户确认后沉淀"| Knowledge
Knowledge -->|"搜索与读取"| Agent
Agent -->|"受控修改"| Knowledge
Memory -->|"用户偏好"| Briefing
Memory -->|"相关会话经验"| Agent
Briefing --> Data["本地 JSON / Markdown / JSONL 数据"]
Knowledge --> Data
Agent --> Data
Memory --> Data
System --> Data
LLM["百炼兼容 LLM / Embedding API"] -->|"筛选与摘要"| Briefing
LLM -->|"决策与回答"| Agent
LLM -->|"记忆整理"| Memory
Qdrant["Qdrant 向量索引"] -->|"语义筛选"| Briefing
Qdrant -->|"语义搜索"| Knowledge
系统仍采用前后端分离的模块化单体架构。前端负责页面交互、请求状态和 Agent 执行过程展示；后端按每日简报、本地 Wiki、Agent 和 Memory 划分业务模块，并通过统一接口访问本地数据和外部智能能力。
每日简报负责采集、去重和分层筛选，本地 Wiki 负责正式内容与检索，Agent 围绕 Wiki 完成受控搜索、读取和修改，Memory 为简报和 Agent 提供经过筛选的偏好与会话经验。LLM、向量索引和 Python 内容工具只承担辅助处理，正式 Wiki 和长期记忆仍保存在本地数据目录。
| 层级 | 主要技术 |
|---|---|
| 前端 | Vue 3、TypeScript、Vite、Pinia、Vue Router、Element Plus |
| 后端 | Node.js、TypeScript、Express、Winston、LangGraph、simple-git |
| LLM | 百炼 OpenAI-compatible Chat / Embedding API，任务级模型路由 |
| 内容处理 | Python 3.11、Scrapling、MarkItDown、Trafilatura、ffmpeg |
| 检索 | Qdrant、本地关键词索引、关系索引 |
| 存储 | 本地 JSON、Markdown、JSONL 与 Git |
| 测试 | Jest、Supertest、Vitest、Vue Test Utils |
完整的新主机部署、首次配置、Qdrant collection 初始化和验收流程，请先阅读：
需要预先安装：
- Git；
- Node.js，项目架构基线为 Node.js 20；
- Python 3.11、pip 和 ffmpeg；
- Docker，用于运行 Qdrant；
- 可调用的百炼或 OpenAI-compatible Chat / Embedding API。
git clone --branch main --single-branch https://github.com/AdrenalineY/EssenceStream.git
cd EssenceStream使用 SSH 时：
git clone --branch main --single-branch git@github.com:AdrenalineY/EssenceStream.git
cd EssenceStream后端和前端分别维护 lockfile，新环境优先使用 npm ci：
cd server
npm ci
cd ../client
npm ci
cd ..
python -m pip install -r server/scripts/requirements-extraction.txtWindows PowerShell：
Copy-Item .env.example .env
Copy-Item .\config\system_config.example.yaml .\config\system_config.yamlLinux：
cp .env.example .env
cp config/system_config.example.yaml config/system_config.yaml至少检查以下配置：
- 根目录
.env中的PORT=3001、CLIENT_PORT=5173和日志级别； config/system_config.yaml中的 LLM、Embedding 和任务模型；content_tools.python_executable是否指向当前主机的 Python 3.11；storage.local_data_dir是否指向专用可写目录；qdrant.url和 collection 名称是否与本地实例一致。
Caution
.env、config/system_config.yaml 和运行数据可能包含密钥或个人数据，均不应提交到源码仓库。仓库已通过 .gitignore 排除这些路径。
以下命令只把端口绑定到本机：
docker run -d --name qdrant --restart unless-stopped \
-p 127.0.0.1:6333:6333 \
-p 127.0.0.1:6334:6334 \
-v qdrant_data:/qdrant/storage \
qdrant/qdrant:latestWindows 也可在可信网络环境中运行：
.\scripts\start-qdrant.ps1终端 1：
cd server
npm run dev终端 2：
cd client
npm run dev打开 http://localhost:5173。首次访问会进入配置向导；保存配置后应按提示重启前后端。
Windows + Conda 环境也可以使用项目脚本：
.\scripts\start-dev.ps1 -CheckOnly
.\scripts\start-dev.ps1该脚本使用名为 essence-stream 的 Conda 环境，详细前置条件见部署指南。
首先检查系统状态：
curl http://localhost:3001/api/v1/system/status然后在 server 目录真实验证 Chat 和 Embedding：
npm run verify-llm全新 Qdrant volume 还需要按真实 Embedding 维度创建 collection。不要猜测向量维度，具体命令和完整 UI 烟测步骤见部署与首次配置指南。
| 目标 | 命令 |
|---|---|
| 后端热重载 | cd server && npm run dev |
| 前端热重载 | cd client && npm run dev |
| 后端类型检查 | cd server && npm run typecheck |
| 前端类型检查 | cd client && npm run typecheck |
| 后端测试 | cd server && npm run test -- --runInBand |
| 前端测试 | cd client && npm run test |
| 后端构建 | cd server && npm run build |
| 前端构建 | cd client && npm run build |
| LLM/Embedding 验证 | cd server && npm run verify-llm |
构建命令用于验证代码可以编译；当前仓库没有内置统一生产启动器、静态资源托管和 /api 反向代理，因此不能仅凭 server/dist 与 client/dist 视为已完成生产部署。
| 路径 | 职责 |
|---|---|
.env |
后端端口、前端端口、日志级别和少量环境覆盖项。 |
config/system_config.yaml |
LLM、模型路由、数据源、Qdrant、Python 工具、数据目录和首次初始化状态。 |
config/system_config.example.yaml |
可提交的本机配置模板。 |
data/ 或自定义 DATA_DIR |
简报、知识对象、Wiki、Agent、Memory 和运行观测数据。 |
Docker volume qdrant_data |
Qdrant 向量索引数据。 |
数据根目录解析优先级为：DATA_DIR 环境变量 > storage.local_data_dir > 项目根目录下的 data/。修改 .env 或 YAML 后应重启后端，使启动期路径和运行配置重新解析。
EssenceStream/
├── client/ # Vue 前端
│ └── src/
│ ├── views/ # 简报、知识、Wiki、Agent、设置等页面
│ ├── components/ # 布局与领域组件
│ ├── stores/ # Pinia 状态管理
│ ├── api/ # /api/v1 客户端
│ └── router/ # 页面路由与首次配置守卫
├── server/ # Express 后端
│ └── src/
│ ├── briefing/ # 简报发现、筛选、生成和渲染
│ ├── content-standardization/ # 内容标准化与 Python 工具桥接
│ ├── knowledge*/ # 知识对象、导入、索引与搜索
│ ├── wiki/ # Wiki 页面、修订、提案和 lint
│ ├── agent/ # Agent 会话、工具、ChangeSet 与 Memory V2
│ ├── memory/ # 用户画像、偏好、权重与 Prompt
│ ├── llm/ # Provider、Embedding、模型路由与运行记录
│ ├── observability/ # RunRecord、事件和状态投影
│ ├── git-sync/ # 本地数据 Git 同步
│ └── routes/ # /api/v1 路由
├── config/ # 可提交模板与本机系统配置
├── data/ # 默认运行数据目录，不提交 Git
├── scripts/ # Windows 开发与 Qdrant 辅助脚本
├── docs/ # 部署、架构、契约和开发文档
└── openspec/ # 规格与变更记录
| 文档 | 内容 |
|---|---|
| Windows / Linux 源码部署与首次配置指南 | 从 GitHub clone 开始的环境准备、配置、首次向导、Qdrant 初始化和验收流程。 |
| 代码取证版架构文档 | 系统上下文、容器/组件视图、运行时数据流和外部依赖。 |
| 代码取证版 PRD | 产品定位、当前用户场景、能力范围和验收口径。 |
| 代码取证版 UX 流程文档 | 页面地图、导航、关键交互序列和前后端依赖。 |
| 代码取证版数据模型 | 领域对象、生命周期、存储路径、索引和写入边界。 |
| 代码取证版 API 契约 | /api/v1 路由、请求响应、DTO 来源和验收入口。 |
- 面向个人知识管理和本地 AI 工作流，以单用户可信环境为运行前提，配置、知识内容和会话数据由用户自行掌控。
- 支持在 Windows 和 Linux 上从 GitHub 源码完成部署、首次配置与验收，前后端可独立启动，各项外部能力可逐项检查。
- 系统状态页集中展示大模型、向量检索、内容解析工具和数据源的运行状态，并提供明确的诊断信息，便于快速定位配置问题。
- 知识搜索组合语义理解与本地关键词匹配，并对索引状态提供清晰反馈；正式简报使用完整筛选链路，确保筛选标准与结果质量保持一致。
- 源码、运行数据和向量索引分离管理，便于独立备份、版本同步、环境迁移和索引重建。
EssenceStream 原创内容采用 MIT License。
仓库包含部分按其各自许可证再分发的第三方 Agent、Prompt、Skill 和生成资产，完整来源、适用范围、固定版本、版权声明和许可证信息见 THIRD_PARTY_NOTICES.md。