docs: 同步当前工程实现与验证基线

docs/AI笔记软件技术栈说明-团队版-v2.2.md

@@ -4,6 +4,8 @@
 > 适用范围：桌面客户端、本地知识库、RAG、Agent、Skill、多模型接入、多模态处理与可选云同步  
 > 目标读者：前端、Rust 桌面端、Python AI Core、算法、测试与后续接手项目的开发成员
 
+> 实施状态更新：2026-08-30。本文同时包含目标架构和当前实现。当前已完成 Vue Web 联调前端、FastAPI、Knowledge/Retrieval、Agent/Tool/Permission、Skill/Plugin 声明式运行时、Mock/OpenAI-Compatible/Ollama Provider、DeepSeek/OpenAI 预设、模型发现及开发阶段 Fernet 凭据存储。Tauri/Rust Host、Stronghold、真实桌面文件系统、独立 MCP Host、真实多模态模型和 Sync Server 尚未实现。
+
 ---
 
 ## 1. 文档目的
@@ -34,7 +36,7 @@
 | 桌面容器 | Tauri 2 + Rust | 桌面窗口、系统 API、本地文件访问、Sidecar 管理、安全边界 |
 | 前端 | Vue 3 + TypeScript + Vite | 工作区、编辑器、AI 对话、搜索、设置、扩展管理等用户界面 |
 | 状态管理 | Pinia | 管理工作区、编辑器、搜索、会话、Agent、Skill、主题与模型状态 |
-| UI 基础 | Reka UI / Headless Components + Design Token | 通用交互组件和主题化能力 |
+| UI 基础 | 当前公共 Vue 组件 + Element Plus 图标 + Design Token；目标按需引入 Reka UI | 通用交互组件、无障碍交互和主题化能力 |
 | Markdown 编辑器 | Milkdown + CodeMirror 6 | 可视化 Markdown 编辑与源码编辑 |
 | 本地核心服务 | Python + FastAPI + Pydantic v2 | RAG、Agent、Skill、模型访问、多模态、索引和本地 API |
 | Python 打包 | PyInstaller / Nuitka | 将 Python AI Core 打包为 Tauri Sidecar |
@@ -52,9 +54,9 @@
 | ASR | faster-whisper | 音频转写 |
 | 说话人分离 | pyannote.audio | 课堂、会议等多人音频中的说话人区分 |
 | 情感识别 | emotion2vec | 可选音频分析能力 |
-| 密钥存储 | Tauri Stronghold | 保存模型 API Key 和同步凭证 |
+| 密钥存储 | 当前 Fernet 开发存储；目标 Tauri Stronghold | Web 联调期避免明文落盘，桌面集成后保存模型 API Key 和同步凭证 |
 | 云同步 | 独立 Sync Server：FastAPI + PostgreSQL + S3/MinIO | 可选自托管，多设备 Vault 同步、版本管理和设备管理 |
-| 测试 | pytest + 自建 RAG / Agent Dataset | 单元、接口、检索、Agent 和模型适配器测试 |
+| 测试 | pytest + Vitest + 自建 RAG / Agent Dataset | 后端、前端组件、接口、检索、Agent 和模型适配器测试 |
 
 表中的技术选型构成当前开发基线。新增依赖时需要明确其所属层、调用方、运行位置和替换成本，避免同一功能出现多套并行实现。
 
@@ -1146,7 +1148,7 @@ Done
 
 ### 13.4 Provider 配置与 API Key
 
-普通 Provider 配置保存在 SQLite：
+目标桌面架构将普通 Provider 配置保存在 SQLite。当前 Web 联调版由内存 `ProviderRegistry` 持有，AI Core 重启后清空：
 
 ```text
 provider_id
@@ -1157,18 +1159,19 @@ credential_id
 enabled
 ```
 
-Stronghold 保存 `credential_id` 对应的实际 API Key。
+当前开发版使用 Fernet 加密文件保存 `credential_id` 对应的实际 API Key，并允许环境变量回退；Tauri 集成后由 Stronghold 替换该存储实现。
 
 设置页面执行“测试连接”时：
 
 ```text
 读取 Provider Config
-→ Rust Host 读取 Secret
-→ 构造临时 Credential Context
+→ Credential Resolver 按 ID 读取开发密文或环境变量
 → AI Core 调用 Provider
 → 返回连接测试结果
 ```
 
+当前设置页已经提供 OpenAI、DeepSeek 与 Ollama 预设，保存后通过 `/api/providers/{provider_id}/models` 自动发现模型。Credential API 只返回配置状态，不提供任何明文读取接口。
+
 日志中不记录完整 API Key。请求异常信息在进入前端前过滤 Authorization Header 和密钥片段。
 
 ---
@@ -1838,36 +1841,34 @@ ainote/
 
 ### 19.1 基础环境
 
-团队开发机需要准备：
+当前 Web 联调开发机需要准备：
 
 ```text
-Node.js
-pnpm
-Rust toolchain
-Tauri CLI
-Python 3.x
-uv / Poetry（团队确定一种）
+Node.js 22+
+pnpm 10+
+Python 3.11+
+uv
 SQLite
 Git
 ```
 
-Python 环境需要支持 faster-whisper、pyannote.audio、Embedding 和 Reranker 所需依赖。涉及 CUDA 的开发成员可以安装 GPU 版本，基础功能仍需提供 CPU 可运行路径。
+Rust Toolchain 与 Tauri CLI 只在桌面容器阶段安装。当前轻量 Embedding/Reranker 不要求 CUDA；接入 faster-whisper、pyannote.audio 或真实本地模型时再按所选运行时增加 CPU/GPU 依赖。
 
 ### 19.2 本地开发
 
-开发模式下分别启动 AI Core 和 Tauri：
+当前开发模式下分别启动 FastAPI 和 Vite：
 
 ```text
 Terminal A
-services/ai-core
-→ start FastAPI dev server
+cd backend
+uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
 
 Terminal B
-apps/desktop
-→ pnpm tauri dev
+cd frontend
+pnpm dev
 ```
 
-开发配置允许桌面端连接固定开发端口。正式构建时改为 Sidecar 随机端口模式。
+Vite 将 `/api` 与 `/health` 代理到固定开发端口。正式桌面构建时改为 Tauri Sidecar 随机端口和临时访问令牌模式。
 
 ### 19.3 配置
 
@@ -2125,6 +2126,8 @@ Markdown Workspace
 
 第一阶段的 Plugin Runtime 需要完成安装、启用、停用、权限、Tool 注册和至少一个示例 Plugin，建立 Skill 调用 Plugin Tool 的完整链路。
 
+截至 2026-08-30，上述第一阶段后端链路和 Web 联调前端均已完成。当前验证基线为后端 71 项测试、前端 14 项测试及生产构建通过。
+
 第二阶段接入：
 
 ```text
@@ -2133,8 +2136,8 @@ pyannote.audio
 主题导入与社区格式
 MCP Bridge
 Plugin Command / Settings Contribution
-更多 Provider
-Agent Trace 可视化
+更多 Provider Adapter
+高级 Agent Trace 可视化
 RAG / Agent Benchmark
 ```
 
@@ -2188,10 +2191,10 @@ Sync Server 按独立服务开发和部署，不进入桌面客户端核心启
 
 ## 25. 当前技术基线摘要
 
-项目桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 管理元数据、全文索引、向量索引和 Agent Trace。
+目标桌面端采用 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、Embedding、sqlite-vec、RRF 和 Reranker 提供混合检索；Agent Runtime 使用 Tool Registry 操作知识库和任务；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置；Plugin Runtime 通过 Plugin Manifest、Plugin Host 和 MCP Bridge 扩展 Tool、Command、导入导出和受控 UI Contribution，Plugin 注册的 Tool 可以被 Agent 与 Skill 共同使用；Provider Adapter 对接 OpenAI、OpenAI-Compatible、Anthropic 和 Ollama 等模型服务。
+Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 通过 FTS5、轻量 Embedding、sqlite-vec、RRF 和 Reranker 提供混合检索；Agent Runtime 使用 Tool Registry 操作知识库和任务；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置；当前 Plugin Runtime 支持 Manifest、生命周期和声明式白名单 Tool Contribution，独立 Plugin Host 与 MCP Bridge 留待后续。Provider Adapter 当前实现 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama，OpenAI Responses 和 Anthropic Messages 留待后续。
 
-多模态处理使用 faster-whisper 和 pyannote.audio 完成音频转写和说话人分离，emotion2vec 作为扩展分析能力。API Key 和同步凭证存放在 Tauri Stronghold。多设备同步由独立 Sync Server 提供，采用 FastAPI、PostgreSQL 和 S3/MinIO，可由用户自托管。客户端在没有 Sync Server 时保持完整本地功能；连接服务器后同步 Markdown、Assets 和必要配置，各设备自行维护 FTS5、Embedding 和 Vector Index。
+多模态目标方案使用 faster-whisper、pyannote.audio 和可选 emotion2vec；当前只读取 Host 预生成 transcript。API Key 在 Web 联调期由 Fernet 开发存储加密保存，桌面版迁移到 Tauri Stronghold。多设备同步的目标方案为独立、可自托管的 Sync Server，目前尚未实现；本地核心功能不依赖 Sync Server。
 
 该技术基线用于指导当前比赛版本的代码组织、接口设计、模块协作、测试和交付。