From 0b20bad0a8aec00cec0fea5f01a7d248a76fa0c0 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Mon, 31 Aug 2026 20:08:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E7=AC=AC=E4=BA=8C?= =?UTF-8?q?=E9=98=B6=E6=AE=B5=E6=8A=80=E6=9C=AF=E6=A0=88=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 5 +- ...队版-v2.2.md => AI笔记软件技术栈说明-团队版-v2.3.md} | 266 ++++++++++++++++-- docs/前端页面需求说明-开发版.md | 2 +- 3 files changed, 244 insertions(+), 29 deletions(-) rename docs/{AI笔记软件技术栈说明-团队版-v2.2.md => AI笔记软件技术栈说明-团队版-v2.3.md} (81%) diff --git a/README.md b/README.md index 0ec3f54..e615c0c 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ python --version uv --version ``` -当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/AI笔记软件技术栈说明-团队版-v2.2.md` 安装 Rust Toolchain 与 Tauri CLI。 +当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/AI笔记软件技术栈说明-团队版-v2.3.md` 安装 Rust Toolchain 与 Tauri CLI。 ## 首次初始化 @@ -126,8 +126,9 @@ pnpm test | 文档 | 用途 | | --- | --- | -| [技术栈说明](docs/AI笔记软件技术栈说明-团队版-v2.2.md) | 目标架构、当前实施边界与模块依赖 | +| [技术栈说明](docs/AI笔记软件技术栈说明-团队版-v2.3.md) | 目标架构、第二阶段技术边界与模块依赖 | | [第一阶段分工表](docs/第一阶段分工表.md) | 成员职责、协作关系与当前交付状态 | +| [第二阶段分工表](docs/第二阶段团队分工表.md) | 第二阶段人员职责、任务顺序、协作关系与验收项 | | [第一阶段测试验证操作手册](docs/第一阶段测试验证操作手册.md) | 自动化测试、接口主链路、前端人工验收与记录模板 | | [后端接口契约](docs/后端接口契约-开发版.md) | HTTP/SSE 接口、错误和当前实现状态 | | [AI Core 与 Agent Core](docs/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | diff --git a/docs/AI笔记软件技术栈说明-团队版-v2.2.md b/docs/AI笔记软件技术栈说明-团队版-v2.3.md similarity index 81% rename from docs/AI笔记软件技术栈说明-团队版-v2.2.md rename to docs/AI笔记软件技术栈说明-团队版-v2.3.md index d02d226..2e7652a 100644 --- a/docs/AI笔记软件技术栈说明-团队版-v2.2.md +++ b/docs/AI笔记软件技术栈说明-团队版-v2.3.md @@ -1,10 +1,11 @@ # AI 笔记软件技术栈说明 > 文档性质：团队技术基线 +> 基线版本：v2.3 > 适用范围：桌面客户端、本地知识库、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 尚未实现。 +> 实施状态更新：2026-08-31。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段已完成 Vue Web 联调前端、FastAPI、Knowledge/Retrieval、Agent/Tool/Permission、Skill/Plugin 声明式运行时、Mock/OpenAI-Compatible/Ollama Provider、DeepSeek/OpenAI 预设、模型发现及开发阶段 Fernet 凭据存储。第二阶段在现有边界上接入真实音频处理、MCP、Plugin Command/Settings、Provider 协议增强、Benchmark、文档导出、主题包、Agent Trace、Mermaid 和函数图像。Tauri/Rust Host、Stronghold、真实桌面文件系统和 Sync Server 仍未实现。 --- @@ -38,6 +39,8 @@ | 状态管理 | Pinia | 管理工作区、编辑器、搜索、会话、Agent、Skill、主题与模型状态 | | UI 基础 | 当前公共 Vue 组件 + Element Plus 图标 + Design Token；目标按需引入 Reka UI | 通用交互组件、无障碍交互和主题化能力 | | Markdown 编辑器 | Milkdown + CodeMirror 6 | 可视化 Markdown 编辑与源码编辑 | +| 图表渲染 | Mermaid + 受控 SVG 输出 | Markdown 流程图、时序图等图表的预览与静态导出 | +| 函数图像 | `FunctionPlot` 结构化模型 + Renderer Adapter | 二维函数解析、交互预览与导出静态图 | | 本地核心服务 | Python + FastAPI + Pydantic v2 | RAG、Agent、Skill、模型访问、多模态、索引和本地 API | | Python 打包 | PyInstaller / Nuitka | 将 Python AI Core 打包为 Tauri Sidecar | | 笔记存储 | Markdown + Assets | 保存用户正文和附件 | @@ -49,14 +52,16 @@ | Agent | 自研 Agent Runtime | 模型推理、工具选择、工具调用、结果回灌、运行控制 | | Skill | 自研声明式 Skill Runtime | 复用提示词、工具集合、权限和检索配置 | | Plugin | 自研 Plugin Runtime + Plugin Manifest + MCP Bridge | 扩展程序能力、Tool、外部服务集成和受控 UI Contribution | +| Theme | Theme Manifest + Design Token + 受限 CSS | 本地主题包导入、预览、启停与社区格式兼容 | | LLM | 自研 Provider Adapter | 统一不同模型服务商的输入、输出、Streaming 与 Tool Calling | | 模型协议 | OpenAI Responses / Chat Completions compatible / Anthropic Messages / Ollama | 用户自定义模型接入 | | ASR | faster-whisper | 音频转写 | | 说话人分离 | pyannote.audio | 课堂、会议等多人音频中的说话人区分 | | 情感识别 | emotion2vec | 可选音频分析能力 | +| 文档导出 | Document AST + Exporter Adapter | Markdown 到 HTML、PDF、DOCX，并保留图表、公式和代码块 | | 密钥存储 | 当前 Fernet 开发存储；目标 Tauri Stronghold | Web 联调期避免明文落盘，桌面集成后保存模型 API Key 和同步凭证 | | 云同步 | 独立 Sync Server：FastAPI + PostgreSQL + S3/MinIO | 可选自托管，多设备 Vault 同步、版本管理和设备管理 | -| 测试 | pytest + Vitest + 自建 RAG / Agent Dataset | 后端、前端组件、接口、检索、Agent 和模型适配器测试 | +| 测试 | pytest + Vitest + 版本化 RAG / Agent Dataset | 后端、前端组件、接口、检索质量、Agent 行为和模型适配器测试 | 表中的技术选型构成当前开发基线。新增依赖时需要明确其所属层、调用方、运行位置和替换成本，避免同一功能出现多套并行实现。 @@ -392,6 +397,22 @@ Reka UI / Headless Components 提供 Dialog、Popover、Menu、Tabs、Select、T 业务组件中优先引用 Design Token。主题包负责覆盖 Token 和允许开放的组件样式。主题加载器需要限制资源路径，避免主题 CSS 引用 Vault 外的任意本地文件。 +### 5.5 Theme Package 与社区格式 + +第二阶段统一 Theme Package 的本地分发格式： + +```text +my-theme/ +├── theme.yaml +├── theme.css +├── preview.png +└── README.md +``` + +`theme.yaml` 至少声明 `id`、`name`、`version`、`author` 和 `min_app_version`。导入流程固定为 Manifest 校验、CSS 安全检查、隔离预览、安装、启用；停用或卸载后必须恢复内置 Design Token，不残留全局样式。 + +主题 CSS 只能使用开放的 Token 和宿主允许的稳定选择器，不允许脚本、远程资源、任意本地路径、`@import` 或覆盖安全相关界面。第二阶段只定义本地导入和社区包兼容格式，不把联网 Theme Marketplace 作为客户端依赖。 + --- ## 6. Markdown 编辑与知识结构 @@ -472,6 +493,32 @@ Save Markdown 外部编辑器修改文件时也走相同流程。索引任务写入 `index_jobs`，前端可以展示待处理、处理中和失败状态。 +### 6.5 Mermaid Code Block + +Mermaid 使用标准 fenced code block 持久化，Markdown 文件仍是唯一正文来源： + +````markdown +```mermaid +flowchart LR + A[Markdown] --> B[Renderer] +``` +```` + +前端识别代码块后调用 Mermaid Renderer 生成 SVG。渲染必须支持亮暗主题、编辑后重新计算、错误占位、缩放查看和销毁旧实例。生成的 SVG 经过净化后才能插入 DOM；导出链路使用同一份 Mermaid 源码生成稳定的 SVG 或图片，不能抓取编辑器界面截图。 + +### 6.6 函数图像 Block + +函数图像采用独立 fenced block，并在实现稳定后冻结语法： + +````markdown +```function-plot +y = x^2 +y = sin(x) +``` +```` + +解析层将文本转换为与渲染库无关的 `FunctionPlot`，至少包含表达式、定义域、显示范围、坐标轴和渲染配置。表达式解析不得使用 `eval` 或执行任意 JavaScript。交互预览和导出共享同一数据模型；HTML 可以保留交互渲染，PDF/DOCX 使用 SVG 或栅格化静态图。 + --- ## 7. SQLite 与数据归属 @@ -628,7 +675,9 @@ class EmbeddingProvider(Protocol): async def embed_query(self, query: str) -> list[float]: ... ``` -默认配置使用本地 BGE-M3 类模型。模型名称和具体推理实现由配置决定，索引记录需要保存 embedding model id 和向量维度。用户更换模型后，由索引服务识别维度或模型变化并提示重新建立向量索引。 +目标默认配置使用本地 BGE-M3 类模型。当前第一阶段实现是 128 维 `HashEmbeddingProvider`，只用于离线跑通向量存储、索引更新和 Hybrid 链路，不代表真实语义召回质量。第二阶段接入真实 Embedding 时继续实现相同接口，上层 Retrieval Core 不依赖具体模型运行时。 + +索引记录需要保存 embedding model id、模型版本、向量维度和归一化方式。用户更换模型或任一索引兼容字段变化后，索引服务必须将旧向量标记为不可用并要求重建，禁止把不同模型生成的向量写入同一索引空间。 ### 9.5 RRF 与 Reranker @@ -771,6 +820,25 @@ audio.transcribe Tool Executor 对参数再次进行 Pydantic 校验。文件修改类 Tool 调用 Knowledge Core，不允许 Tool 自行读取或修改 SQLite 表。 +### 10.4 Agent Trace Contract + +第二阶段的 Trace 不从前端临时状态反推，而由 Agent Runtime 产生可回放事件。一个 Trace 至少覆盖： + +```text +Run Started / Completed / Failed / Cancelled +Model Call Started / Completed +Thinking / Text Delta +Tool Call / Tool Result +Permission Required / Resolved +Citation +Usage +Error +``` + +每个事件携带 `run_id`、单调递增的 `sequence`、时间戳和结构化 `data`。Tool 事件额外记录调用 ID、参数摘要、耗时、权限结果、输出摘要和错误；Provider 事件记录 Provider、模型、Usage 和耗时，但不得记录 API Key、完整敏感正文或未经净化的第三方响应。 + +前端先按 `run_id + sequence` 回放和去重，再构建 Trace Tree。Benchmark 复用同一事件流统计工具选择、步骤、延迟和 Token Usage，不另建一套只供测试使用的 Agent 执行协议。持久化层接入后，SSE 使用 `Last-Event-ID` 或等价游标恢复中断连接。 + --- ## 11. Skill Runtime @@ -916,7 +984,7 @@ Manifest 进入安装流程前使用 Pydantic Schema 校验。Plugin ID、版本 ### 12.3 Plugin Contribution -第一阶段允许 Plugin 声明以下 Contribution： +Plugin Manifest 可以声明以下 Contribution： ```text Tool @@ -929,6 +997,10 @@ Settings Section 其中 Tool 面向 Agent；Command 面向命令面板和快捷操作；Importer / Exporter 用于文件格式扩展；Sidebar Panel 和 Settings Section 为前端提供受控扩展位置。 +第一阶段只落地声明式 Tool Contribution。第二阶段新增 Command 和 Settings Contribution：Command 由后端注册为稳定 ID、标题、参数和执行目标，前端只消费 Contribution Contract；Settings Schema 首批只允许 `string`、`number`、`boolean`、`select` 和 `secret reference`，由宿主动态生成表单。 + +Secret Setting 只保存 Credential ID，明文通过 Secret API 写入凭据存储，不进入 Manifest、Plugin Storage、Pinia 或 Agent Trace。Importer、Exporter 和 Sidebar Panel 保留现有 Manifest 扩展位，未完成宿主实现前不得标记为可用。 + Contribution 由宿主应用决定挂载位置。Plugin 不直接修改应用路由、Pinia Store 或核心数据库 Schema。 ### 12.4 Plugin Host @@ -990,6 +1062,20 @@ Tool Registry 仍使用项目自己的 `ToolDefinition` 和 `ToolResult`。MCP B MCP 能力首先用于 Tool 和 Resource 类扩展。需要复杂 UI 的插件通过 Frontend Extension Slot 单独处理。 +第二阶段 MCP Bridge 至少覆盖以下协议边界： + +```text +Server Process / Connection Lifecycle +initialize 与 capability negotiation +tools/list 与 ToolDefinition 映射 +tools/call 与 ToolResult 映射 +超时、取消和进程退出 +协议错误与业务错误转换 +健康检查与 Tool 注销 +``` + +首个宿主实现优先支持本地 `stdio` 传输；其他传输在兼容性测试后增加。外部 Server 的 Tool 名称进入项目注册表前添加 Plugin 命名空间，并校验 JSON Schema、权限和重复 ID。MCP 内容不得绕过项目自己的 Permission、超时、日志净化和结果大小限制。 + ### 12.6 Frontend Extension Slot 前端预留受控扩展点： @@ -1066,6 +1152,8 @@ Plugin Storage API 负责访问该目录。插件不能通过自身目录拼接 需要保存密钥的 Plugin 通过 Secret API 请求独立 Credential ID，由 Stronghold 保存实际值。 +第二阶段 Plugin 安装记录、启停状态、授权、配置 Schema 版本和 Contribution 元数据需要持久化。应用启动时先恢复元数据，再启动已启用的 Host；恢复失败的 Plugin 保持隔离并标记为 `error`，不能留下已注册但没有可用执行后端的 Tool 或 Command。 + --- ## 13. Provider Adapter 与模型接入 @@ -1146,6 +1234,8 @@ Done 前端 Streaming UI 只认识这些事件类型。 +第二阶段 Provider 兼容性不以 Adapter 数量为目标，而以同一组行为测试为准：普通对话、Streaming、Tool Calling、Reasoning Event、取消、Usage 和错误映射。优先验证 OpenAI Responses、OpenAI Chat Completions、OpenAI-Compatible、Anthropic Messages 与 Ollama；不支持的 Capability 必须在请求前拒绝，不能静默丢弃 Tool 或附件。 + ### 13.4 Provider 配置与 API Key 目标桌面架构将普通 Provider 配置保存在 SQLite。当前 Web 联调版由内存 `ProviderRegistry` 持有，AI Core 重启后清空： @@ -1204,6 +1294,23 @@ text 内容结构化模块将 Transcript 整理为 Markdown，同时保留音频时间信息，后续 RAG 引用可以跳回音频片段。 +音频管线使用后台 Job，不在 HTTP 请求中长时间同步阻塞。转写结果统一为： + +```text +job_id +attachment_id +language +segments[] + speaker + start_time + end_time + text +status +error +``` + +`pyannote.audio` 和 `faster-whisper` 通过独立 Adapter 加载，模型下载、设备选择、精度、批量大小和缓存目录由配置管理。缺少说话人模型时可以只返回时间戳转写，但必须明确标记 diarization 不可用；模型失败不能生成伪造的 completed 结果。 + ### 14.2 OCR OCR 作为 Media Pipeline 的输入适配能力，用于图片笔记、白板照片、PPT 截图和扫描资料。OCR 输出进入附件文本索引，也可以由用户选择生成 Markdown。 @@ -1214,6 +1321,39 @@ OCR 引擎在当前技术栈中尚未固定，调用接口先定义为 `OCRProvi emotion2vec 作为音频扩展分析模块。输出可以附加到音频段元数据，不参与核心 RAG 索引和 Agent 启动流程。 +### 14.4 Document AST 与多格式导出 + +第二阶段建立统一导出链路： + +```text +Markdown +→ Markdown AST +→ Document AST +→ DocumentExporter + ├── HtmlExporter + ├── PdfExporter + └── DocxExporter +``` + +`Document AST` 是导出器共享的中间表示，覆盖标题、段落、列表、表格、图片、引用、代码块、数学公式、Mermaid 和函数图像。Exporter 不直接解析编辑器 DOM，避免不同界面状态产生不同输出。 + +统一接口返回文件、MIME、警告和失败节点： + +```python +class DocumentExporter(Protocol): + async def export( + self, + document: Document, + options: ExportOptions, + ) -> ExportResult: ... +``` + +HTML 导出保留结构化语义和受控样式；PDF 与 DOCX 在不支持交互内容时使用静态 SVG 或图片。具体底层库在 PoC 后冻结，但必须封装在 Exporter Adapter 内，不允许导出库的数据结构渗透到 Knowledge Core。 + +### 14.5 可视化内容的统一静态输出 + +Mermaid Renderer 和 Function Plot Renderer 除前端预览外，都必须提供可重复的静态输出接口。导出器只消费 SVG、PNG 或带尺寸信息的资源引用，不调用 Vue 组件。渲染结果按源码 Hash、主题和渲染器版本缓存；源码、主题或版本变化时缓存失效。 + --- ## 15. 安全与权限 @@ -1793,6 +1933,8 @@ ainote/ │ │ ├── skills/ │ │ ├── providers/ │ │ ├── media/ +│ │ ├── extensions/ +│ │ ├── export/ │ │ └── database/ │ └── tests/ │ @@ -1813,7 +1955,11 @@ ainote/ │ ├── benchmarks/ │ ├── rag/ +│ │ ├── datasets/ +│ │ └── reports/ │ └── agent/ +│ ├── datasets/ +│ └── reports/ │ ├── infra/ │ └── cloud/ @@ -1832,6 +1978,8 @@ ainote/ - VectorStore 具体实现只出现在 Retrieval 基础设施层。 - 内置 Skill 放在 `skills/builtin`，不硬编码在 Agent Runtime。 - Plugin Runtime、Plugin Host 和 MCP Bridge 位于 Extension Core，对第三方插件暴露的稳定接口放在 `packages/plugin-sdk`。 +- Mermaid 与函数图像的 Markdown 源码解析归编辑/文档模型，交互渲染归前端 Renderer，静态渲染契约由 Export Service 复用。 +- Document AST 和 Exporter Adapter 位于 Export Service，导出器不得读取 Vue 组件 DOM 或 Provider 内部状态。 - 内置 Plugin 放在 `plugins/builtin`，通过与第三方 Plugin 相同的 Contribution 接口注册。 - Benchmark 数据和运行脚本放在 `benchmarks`。 @@ -1902,13 +2050,15 @@ Python 使用 pytest。重点覆盖： - Plugin Manifest； - Plugin Lifecycle； - Plugin Tool Registration； -- MCP Bridge； +- MCP 生命周期、Tool 映射、取消与异常退出； - Provider Adapter； - 权限判断； - API 错误转换。 前端测试重点覆盖 Store、Service 和关键交互流程。Rust 侧覆盖路径处理、Sidecar 启停和 Secret 访问封装。 +第二阶段还需要增加 Theme Manifest/CSS 安全校验、Mermaid 错误与主题切换、Function Plot 表达式拒绝策略、Document AST 快照和 HTML/PDF/DOCX 导出回归测试。多模态测试使用小型固定音频 Fixture，模型级测试与不下载模型的快速单元测试分组执行。 + ### 20.2 RAG Benchmark RAG Dataset 结构： @@ -1933,12 +2083,13 @@ Hybrid + Reranker 核心指标： ```text +Hit@1 +Hit@5 Recall@K -Hit@K MRR -Citation Precision -Citation Recall -Latency +Citation Hit Rate +P50 Latency +P95 Latency ``` Benchmark 参数、Embedding 模型、Reranker、数据集版本和运行环境需要一起记录，保证不同实验结果可以复现。 @@ -1953,12 +2104,13 @@ Agent Dataset 保存任务目标、允许工具、期望工具序列和结果条 Task Success Rate Tool Selection Accuracy Tool Argument Accuracy +Invalid Tool Call Rate Average Steps Average Latency Token Usage ``` -Agent Benchmark 同时记录模型 Provider 和模型版本。 +Agent Benchmark 同时记录模型 Provider、模型版本、Skill、可用工具集合、运行配置和 Dataset 版本。指标直接从 Agent Trace Contract 计算，测试框架不得绕过权限或使用另一套 Tool 执行器。 --- @@ -2077,6 +2229,47 @@ Audio → RAG Index ``` +### 21.8 MCP Tool 接入 + +```text +Enable Plugin +→ Start MCP Server +→ MCP initialize / tools/list +→ Validate Schema and Permission +→ Namespace Tool ID +→ Register Tool Registry +→ Agent Tool Call +→ MCP tools/call +→ Normalize ToolResult / Error +→ Agent Trace +``` + +### 21.9 Mermaid 与函数图像 + +```text +Markdown Fenced Block +→ Parse Source +→ Mermaid / FunctionPlot Model +→ Renderer Adapter +├── Interactive Preview +└── Sanitized SVG / Image + → Export Service +``` + +### 21.10 多格式文档导出 + +```text +Markdown +→ Markdown AST +→ Document AST +→ Resolve Assets / Formula / Diagram / Plot +→ Select Exporter +├── HTML +├── PDF +└── DOCX +→ ExportResult + Warnings +``` + --- ## 22. 异常处理与恢复 @@ -2106,7 +2299,7 @@ SQLite 索引损坏或版本不一致时，应用允许重建 `.ainote/app.db` ## 23. 当前版本实施边界 -第一阶段开发围绕能够形成完整桌面知识工作流的能力展开： +第一阶段围绕可联调的本地知识工作流建立基础接口： ```text Markdown Workspace @@ -2124,23 +2317,42 @@ Markdown Workspace → Plugin Manifest / Tool Contribution ``` -第一阶段的 Plugin Runtime 需要完成安装、启用、停用、权限、Tool 注册和至少一个示例 Plugin，建立 Skill 调用 Plugin Tool 的完整链路。 +第一阶段 Plugin Runtime 已完成安装、启用、停用、权限和声明式 Tool 注册，建立 Skill 调用 Plugin Tool 的基础链路。Command、Settings 和 MCP 执行不计入第一阶段完成项。 -截至 2026-08-30，上述第一阶段后端链路和 Web 联调前端均已完成。当前验证基线为后端 71 项测试、前端 14 项测试及生产构建通过。 +截至 2026-08-31，上述第一阶段后端链路和 Web 联调前端均已完成。当前验证基线为后端 71 项测试、前端 23 项测试及生产构建通过。向量链路当前使用 `HashEmbeddingProvider` 验证工程正确性，真实 Embedding 召回质量不属于该测试结论。 -第二阶段接入： +第二阶段在既有 Contract 上接入： ```text -faster-whisper -pyannote.audio -主题导入与社区格式 -MCP Bridge -Plugin Command / Settings Contribution -更多 Provider Adapter -高级 Agent Trace 可视化 -RAG / Agent Benchmark +Multimodal +├── faster-whisper +└── pyannote.audio + +Extension / Model +├── MCP Bridge +├── Plugin Command Contribution +├── Plugin Settings Contribution +└── Provider Streaming / Tool Calling / Error Mapping 增强 + +Quality +├── RAG Benchmark +├── Agent Benchmark +└── Retrieval 参数调优 + +Content Output +├── Markdown → HTML / PDF / DOCX +├── Mermaid 编辑、预览与静态导出 +└── Function Plot 解析、预览与静态导出 + +Frontend Extension +├── Theme Package 导入与社区包格式 +├── Agent Trace 可视化 +├── Plugin Command UI +└── Plugin Settings UI ``` +上述列表描述第二阶段技术范围，不表示能力已经实现。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。 + 第三阶段处理： ```text @@ -2154,7 +2366,7 @@ Plugin 安装清单同步 Skill 分发 Plugin 分发与社区仓库 Plugin Sidebar Panel 等前端扩展点 -Theme 社区 +联网 Theme Marketplace OCR 深度集成 更多多模态能力 扩展协议 @@ -2162,7 +2374,7 @@ OCR 深度集成 Sync Server 按独立服务开发和部署，不进入桌面客户端核心启动依赖。第一版同步完成文件级 Revision、多设备增量同步和冲突保留后，再评估端到端加密与实时协同编辑。 -阶段划分用于安排开发顺序。模块接口在第一阶段完成时确定基础版本，后续功能通过现有接口扩展。 +阶段划分用于限定交付范围。人员分工、任务顺序和协作安排以阶段分工表为准，不在技术栈说明中重复维护；本文只维护技术选型、模块边界和跨模块 Contract。 --- @@ -2193,8 +2405,10 @@ 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、轻量 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 留待后续。 +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 配置。 -多模态目标方案使用 faster-whisper、pyannote.audio 和可选 emotion2vec；当前只读取 Host 预生成 transcript。API Key 在 Web 联调期由 Fernet 开发存储加密保存，桌面版迁移到 Tauri Stronghold。多设备同步的目标方案为独立、可自托管的 Sync Server，目前尚未实现；本地核心功能不依赖 Sync Server。 +当前 Plugin Runtime 支持 Manifest、生命周期和声明式白名单 Tool Contribution；第二阶段通过 MCP Bridge 接入隔离 Tool，并增加 Command 与 Settings Contribution。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。 该技术基线用于指导当前比赛版本的代码组织、接口设计、模块协作、测试和交付。 diff --git a/docs/前端页面需求说明-开发版.md b/docs/前端页面需求说明-开发版.md index c794ca4..4f8c750 100644 --- a/docs/前端页面需求说明-开发版.md +++ b/docs/前端页面需求说明-开发版.md @@ -2,7 +2,7 @@ > 文档用途：供团队在第一阶段进行页面设计、Vue 开发、前后端联调和验收。 > 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。 -> 依据：`第一阶段分工表.md`、`AI笔记软件技术栈说明-团队版-v2.2.md`、`后端接口契约-开发版.md`。 +> 依据：`第一阶段分工表.md`、`AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`。 > 实现状态：更新至 2026-08-30。全部已注册业务路由均已有真实页面；Markdown 写作/源码模式、Search、Chat、智能体执行轨迹、扩展管理、设置、Provider 预设、模型发现和开发阶段加密凭据输入均已落地。当前仍以 Web Mock Workspace 代替 Tauri 文件系统。