Kronecker/NotesAgentic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 5 Wiki Activity

Merge remote-tracking branch 'origin/main' into feat/knowledge-retrieval-core

Browse Source 
# Conflicts:
#	README.md
#	backend/app/routes.py
#	docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md
#	docs/development/Knowledge与Retrieval-Core开发说明.md
This commit is contained in:
yxx
2026-09-03 23:45:52 +08:00
parent 3bd475dc15 78e8e3e33b
commit ae65c64c8f
76 changed files with 8530 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md
+6 -6
View File
@@ -5,7 +5,7 @@
> 适用范围：桌面客户端、本地知识库、RAG、Agent、Skill、多模型接入、多模态处理与可选云同步
> 目标读者：前端、Rust 桌面端、Python AI Core、算法、测试与后续接手项目的开发成员
> 实施状态更新：2026-09-03。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段已完成 Vue Web 联调前端、FastAPI、Knowledge/Retrieval、Agent/Tool/Permission、Skill/Plugin 声明式运行时、Mock/OpenAI-Compatible/Ollama Provider、DeepSeek/OpenAI 预设、模型发现及开发阶段 Fernet 凭据存储。Web Workspace 已通过 FastAPI 接入后端配置的真实单 Vault；第二阶段 Agent Trace 持久化、分页快照、可恢复 SSE、stdio MCP Bridge 与隔离 Plugin Host 已完成；RAG Benchmark 检索评测（Dataset 加载、异步运行、SSE 进度、指标聚合与报告）已完成，Agent Benchmark 暂缓。后续继续接入真实音频处理、Plugin Command/Settings、Provider 协议增强、文档导出、主题包、Trace 可视化、Mermaid 和函数图像。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统和 Sync Server 仍未实现。
> 实施状态更新：2026-09-03。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段已完成 Vue Web 联调前端、FastAPI、Knowledge/Retrieval、Agent/Tool/Permission、Skill/Plugin 声明式运行时、Mock/OpenAI-Compatible/Ollama Provider、DeepSeek/OpenAI 预设、模型发现及开发阶段 Fernet 凭据存储。Web Workspace 已通过 FastAPI 接入后端配置的真实单 Vault；第二阶段 Agent Trace 持久化、分页快照、可恢复 SSE、stdio MCP Bridge、隔离 Plugin Host、Plugin Command 与 Plugin Settings/Secret Contract 已完成；RAG Benchmark 检索评测（Dataset 加载、异步运行、SSE 进度、指标聚合与报告）已完成，Agent Benchmark 暂缓。后续继续接入真实音频处理、Provider 协议增强、文档导出、主题包、Trace 可视化、Mermaid 和函数图像。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统和 Sync Server 仍未实现。
---
@@ -1050,7 +1050,7 @@ Python 包形式的 MCP Server 推荐使用固定版本的 `uvx --isolated --fro
MCP Bridge 用于接入具有 MCP Server 接口的插件或外部工具服务。
当前已实现本地 stdio 首版：Plugin Runtime 在授权后的启用阶段启动独立 Server 进程，完成 `initialize`、capability negotiation、分页 `tools/list`、`tools/call`、取消、超时、异常退出和 Host Restart。实现接受 `2025-11-25`、`2025-06-18`、`2025-03-26` 与 `2024-11-05` 协议版本；Streamable HTTP、Resource、Prompt、Sampling 与操作系统级沙箱仍属于后续范围。
当前 Plugin Runtime 已实现本地 stdio Host：在授权后的启用阶段启动独立 Server 进程，完成 `initialize`、capability negotiation、分页 `tools/list`、`tools/call`、取消、超时、异常退出和 Host Restart。独立 MCP Server Registry 另行支持 stdio、Streamable HTTP 与旧 HTTP+SSE 兼容，包括 Session、协议 Header、认证 Header Secret、测试门禁和 Tool 动态映射。实现接受 `2025-11-25`、`2025-06-18`、`2025-03-26` 与 `2024-11-05` 协议版本；Plugin Manifest 的 Streamable HTTP、Resource、Prompt、Sampling 与操作系统级沙箱仍属于后续范围。
MCP Tool 进入系统后的调用路径为：
@@ -2333,7 +2333,7 @@ Markdown Workspace
第一阶段 Plugin Runtime 已完成安装、启用、停用、权限和声明式 Tool 注册，建立 Skill 调用 Plugin Tool 的基础链路。Command、Settings 和 MCP 执行不计入第一阶段完成项。
截至 2026-09-01，上述第一阶段后端链路和 Web 联调前端均已完成；第二阶段前置的 Workspace 去 Mock 联调、Agent Trace 持久化/恢复接口以及 stdio MCP Bridge / Plugin Host 也已完成。当前验证基线为后端 92 项测试、前端 27 项测试及生产构建通过。向量链路当前使用 `HashEmbeddingProvider` 验证工程正确性，真实 Embedding 召回质量不属于该测试结论。
截至 2026-09-03，上述第一阶段后端链路和 Web 联调前端均已完成；第二阶段的 Workspace 去 Mock 联调、Agent Trace 持久化/恢复接口、stdio MCP Bridge / Plugin Host，以及 Plugin Command/Settings 前后端闭环也已完成。Plugin 详情页现已提供 Host 状态、重启、动态设置、Secret 管理和命令执行，全局命令面板可加载 Plugin Command。当前验证基线为后端 136 项测试、前端 32 项测试、TypeScript 类型检查及生产构建通过。向量链路当前使用 `HashEmbeddingProvider` 验证工程正确性，真实 Embedding 召回质量不属于该测试结论。
第二阶段在既有 Contract 上接入：
@@ -2365,7 +2365,7 @@ Frontend Extension
└── Plugin Settings UI
```
上述列表描述第二阶段技术范围，其中 stdio MCP Bridge 已实现，其余能力以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。
上述列表描述第二阶段技术范围，其中 stdio MCP Bridge、Plugin Command Contribution 和 Plugin Settings Contribution 后端 Contract 已实现，其余能力以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。
第三阶段处理：
@@ -2419,9 +2419,9 @@ Sync Server 按独立服务开发和部署，不进入桌面客户端核心启
目标桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript；当前可运行形态是 Vue/Vite Web 前端加 FastAPI。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 已管理笔记元数据、全文索引、向量索引、任务及 Agent Trace；Provider/Extension Registry 当前仍为内存实现。
Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 当前通过 FTS5、`HashEmbeddingProvider`、sqlite-vec、RRF 和轻量 Reranker 跑通混合检索，真实 Embedding 与正式 Benchmark 在第二阶段接入；Agent Runtime 使用 Tool Registry 操作知识库和任务，并将扩展 Agent Trace Contract 供可视化和 Benchmark 共用；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置。
Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 当前通过 FTS5、`HashEmbeddingProvider`、sqlite-vec、RRF 和轻量 Reranker 跑通混合检索，真实 Embedding 与正式 Benchmark 仍待第二阶段后续接入；Agent Runtime 使用 Tool Registry 操作知识库和任务，并已持久化可供前端可视化与 Benchmark 共用的 Agent Trace Contract；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置。
当前 Plugin Runtime 支持 Manifest、生命周期和声明式白名单 Tool Contribution，并已通过 stdio MCP Bridge 接入独立进程 Tool、Host 状态与重启接口；Command 与 Settings Contribution 尚待后续阶段实现。Provider Adapter 当前实现 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama，第二阶段按统一行为测试完善 OpenAI Responses、Anthropic Messages 等协议。多模态目标方案使用 faster-whisper、pyannote.audio 和可选 emotion2vec；当前只读取 Host 预生成 transcript。
当前 Plugin Runtime 支持 Manifest、生命周期、声明式白名单 Tool Contribution、Plugin Command 与 Plugin Settings/Secret，并已通过 stdio MCP Bridge 接入独立进程 Tool、专用 MCP Command Target、Host 状态与重启接口。Provider Adapter 当前实现 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama，OpenAI Responses、Anthropic Messages 等协议仍待第二阶段后续完善。多模态目标方案使用 faster-whisper、pyannote.audio 和可选 emotion2vec；当前只读取 Host 预生成 transcript。
第二阶段内容输出以 Document AST、Exporter Adapter、Mermaid Renderer 和 Function Plot Renderer 为共同边界，支持 HTML、PDF、DOCX 与静态图导出。Theme Package 使用 Manifest、Design Token 和受限 CSS 实现本地导入；联网主题市场不属于本阶段核心依赖。API Key 在 Web 联调期由 Fernet 开发存储加密保存，桌面版迁移到 Tauri Stronghold。多设备同步的目标方案为独立、可自托管的 Sync Server，目前尚未实现；本地核心功能不依赖 Sync Server。
docs/architecture/第一阶段分工表.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 第一阶段分工表
> 状态更新：2026-08-30。本文保留原始职责划分，同时记录当前交付状态。第一阶段后端目标已完成，前端 Web 联调页面已完成；尚未纳入本阶段完成项的是 Tauri Host、Stronghold、真实桌面文件系统、独立 MCP Plugin Host、真实音频模型和 Sync Server。
> 状态更新：2026-09-02。本文保留第一阶段原始职责划分和交付口径。第一阶段后端目标与前端 Web 联调页面均已完成；第二阶段此后又完成 Agent Trace 持久化与 SSE 恢复、独立 stdio MCP Plugin Host 和 Plugin Command/Settings 后端 Contract。Tauri Host、Stronghold、原生多 Vault 文件系统、真实音频模型和 Sync Server 仍未实现。
## 当前交付状态
docs/architecture/第二阶段团队分工表.md
+15 -15
View File
@@ -6,9 +6,9 @@
第二阶段继续保持第一阶段的模块 ownership：
- 范涵宇：Agent Core、Extension Core、Model Core、Multimodal、整体架构与代码审阅。
- 范涵宇：Agent Core、Extension Core、Model Core、Multimodal、Plugin Command / Settings UI、整体架构与代码审阅。
- 杨星萱：Knowledge Core、Retrieval Core、Benchmark、文档导出、函数图像绘制。
- 吉海燕：Frontend、Theme、Agent Trace、Plugin UI Contribution、Mermaid 渲染。
- 吉海燕：Frontend、Theme、Agent Trace、Mermaid 渲染。
---
@@ -16,9 +16,9 @@
| 成员 | 主要负责方向 | 第二阶段任务 | 配合事项 |
| --- | --- | --- | --- |
| 范涵宇 | Agent Core / Extension Core / Model Core / Multimodal / 总体架构 | faster-whisper、pyannote.audio、MCP Bridge、Plugin Command Contribution 后端、Plugin Settings Contribution 后端、更多 Provider、整体集成、代码审阅与统筹 | 与吉海燕联调 Plugin Command / Settings 前端；为杨星萱的 Agent Benchmark 提供 Agent Trace、Tool Call 等测试接口 |
| 范涵宇 | Agent Core / Extension Core / Model Core / Multimodal / 总体架构 | faster-whisper、pyannote.audio、MCP Bridge、Plugin Command / Settings 前后端闭环、更多 Provider、整体集成、代码审阅与统筹 | 为杨星萱的 Agent Benchmark 提供 Agent Trace、Tool Call 等测试接口 |
| 杨星萱 | Knowledge Core / Retrieval Core / Benchmark / Export / 数学内容渲染 | RAG Benchmark、Agent Benchmark 基础设施、Markdown → HTML / PDF / DOCX、函数图像绘制与渲染支持、Retrieval 调优 | 与范涵宇确认 Agent Benchmark 事件和测试数据结构；与吉海燕联调函数图像在编辑器和预览区中的展示 |
| 吉海燕 | Frontend / Theme / Visualization | Theme Import、Theme Manifest、社区主题格式、Agent Trace 可视化、Plugin Command / Settings 前端、Mermaid 渲染支持 | 与范涵宇联调 Plugin Contribution Contract 与 AgentEvent；与杨星萱联调函数图像及导出预览 |
| 吉海燕 | Frontend / Theme / Visualization | Theme Import、Theme Manifest、社区主题格式、Agent Trace 可视化、Mermaid 渲染支持 | 与范涵宇联调 AgentEvent；与杨星萱联调函数图像及导出预览 |
---
@@ -384,7 +384,7 @@ Metadata Filter
---
## 五、吉海燕
## 五、前端展示层（吉海燕；5.4—5.5 由范涵宇负责）
### 5.1 Theme Import
@@ -488,7 +488,7 @@ Error
- 用户取消；
- Citation 跳转。
### 5.4 Plugin Command 前端
### 5.4 Plugin Command 前端（范涵宇）
负责 Command Contribution 在前端呈现。
@@ -502,7 +502,7 @@ Toolbar Action
前端使用 Plugin Contribution Contract，不直接解析插件后端 Manifest。
### 5.5 Plugin Settings 前端
### 5.5 Plugin Settings 前端（范涵宇）
根据范涵宇提供的 Plugin Settings Schema 动态生成设置表单。
@@ -572,9 +572,9 @@ Mermaid 渲染需要与 Theme Design Token 联动。
| --- | --- | --- |
| MCP Bridge → Agent Tool | 范涵宇 | 杨星萱 |
| Plugin Command Runtime | 范涵宇 | 吉海燕 |
| Plugin Command UI | 吉海燕 | 范涵宇 |
| Plugin Command UI | 范涵宇 | 吉海燕 |
| Plugin Settings Runtime | 范涵宇 | 吉海燕 |
| Plugin Settings UI | 吉海燕 | 范涵宇 |
| Plugin Settings UI | 范涵宇 | 吉海燕 |
| Agent Benchmark Framework | 杨星萱 | 范涵宇 |
| Agent Trace Event Contract | 范涵宇 | 吉海燕、杨星萱 |
| Agent Trace Visualization | 吉海燕 | 范涵宇 |
@@ -748,8 +748,10 @@ Markdown
- [ ] 两者能组合生成带时间戳和 Speaker 的 Transcript；
- [x] MCP Server 能通过 MCP Bridge 注册 Tool；
- [x] Agent 能调用 MCP Tool；
- [ ] Plugin Command Contribution 后端可注册；
- [ ] Plugin Settings Contribution 后端可解析；
- [x] Plugin Command Contribution 后端可注册；
- [x] Plugin Settings Contribution 后端可解析；
- [x] Plugin Command 可以显示并从前端执行；
- [x] Plugin Settings 可以动态生成设置项并独立提交 Secret；
- [ ] Provider Adapter 的 Streaming / Tool Calling / Error Mapping 稳定；
- [ ] 完成跨模块接口审阅和第二阶段集成。
@@ -773,8 +775,6 @@ Markdown
- [ ] Theme 可以启用、停用和卸载；
- [ ] Agent Trace 可以展示完整 Tool Call 顺序；
- [ ] Trace Node 可以查看参数、结果、耗时和错误；
- [ ] Plugin Command 可以显示在前端；
- [ ] Plugin Settings 可以动态生成设置项；
- [ ] Markdown Mermaid Code Block 可以渲染；
- [ ] Mermaid 支持主题切换；
- [ ] Mermaid 渲染错误可以明确展示；
@@ -791,6 +791,8 @@ Markdown
├── MCP Bridge
├── Plugin Command Runtime
├── Plugin Settings Runtime
├── Plugin Command UI
├── Plugin Settings UI
├── Provider Adapter
├── Code Review
└── Integration / Coordination
@@ -812,8 +814,6 @@ Markdown
├── Theme Import
├── Theme Community Format
├── Agent Trace Visualization
├── Plugin Command UI
├── Plugin Settings UI
└── Mermaid
├── Markdown Rendering
├── Theme Adaptation