From 3872ef330497a3abedaa9161275889cf4233dce0 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Sun, 30 Aug 2026 15:15:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E5=BD=93=E5=89=8D?= =?UTF-8?q?=E5=B7=A5=E7=A8=8B=E5=AE=9E=E7=8E=B0=E4=B8=8E=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 33 ++++++++++- backend/README.md | 13 ++++- docs/AI-Core与Agent-Core开发说明.md | 14 ++++- docs/AI笔记软件技术栈说明-团队版-v2.2.md | 55 ++++++++++--------- docs/Git使用细则-团队开发版.md | 3 + docs/Knowledge与Retrieval-Core开发说明.md | 8 ++- ...Knowledge与Retrieval-Core问题与修复复盘.md | 3 +- docs/前端写作体验优化开发说明.md | 5 +- docs/前端合并审阅问题与修复复盘.md | 10 +++- docs/前端壳子与接口层开发说明.md | 14 +++-- docs/前端页面需求说明-开发版.md | 10 +++- docs/后端全面审阅问题与修复复盘.md | 6 +- docs/后端接口契约-开发版.md | 12 +++- docs/模型提供商与模型发现开发说明.md | 4 ++ docs/第一阶段分工表.md | 12 ++++ 15 files changed, 155 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 0ab01bc..6850459 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ > 本文件用于团队开发期间快速配置环境和启动项目，不是正式的项目 README。 +> 当前基线：2026-08-30。第一阶段 Web 联调版的前端页面、Knowledge/Retrieval Core、AI/Agent Core、Extension Core、Provider 预设与本地加密凭据链路均已实现；Tauri Host、Stronghold、真实桌面文件系统和 Sync Server 尚未接入。 + ## 当前目录 ```text @@ -14,7 +16,7 @@ NotesAgent/ ## 开发环境 -当前前后端壳子需要： +当前开发版需要： | 环境 | 要求 | 说明 | | --- | --- | --- | @@ -34,7 +36,7 @@ python --version uv --version ``` -当前壳子暂不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/AI笔记软件技术栈说明-团队版-v2.2.md` 安装 Rust Toolchain 与 Tauri CLI。 +当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/AI笔记软件技术栈说明-团队版-v2.2.md` 安装 Rust Toolchain 与 Tauri CLI。 ## 首次初始化 @@ -109,8 +111,35 @@ cd frontend pnpm build ``` +前端单元与组件测试： + +```powershell +cd frontend +pnpm test +``` + +当前回归基线为后端 71 项测试、前端 14 项测试，且生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 + 构建产物位于 `frontend/dist`，该目录不提交到 Git。 +## 文档导航 + +| 文档 | 用途 | +| --- | --- | +| [技术栈说明](docs/AI笔记软件技术栈说明-团队版-v2.2.md) | 目标架构、当前实施边界与模块依赖 | +| [第一阶段分工表](docs/第一阶段分工表.md) | 成员职责、协作关系与当前交付状态 | +| [后端接口契约](docs/后端接口契约-开发版.md) | HTTP/SSE 接口、错误和当前实现状态 | +| [AI Core 与 Agent Core](docs/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | +| [Knowledge 与 Retrieval Core](docs/Knowledge与Retrieval-Core开发说明.md) | Block、索引、混合检索和 Citation | +| [模型提供商与模型发现](docs/模型提供商与模型发现开发说明.md) | Provider 预设、模型发现和凭据边界 | +| [前端页面需求](docs/前端页面需求说明-开发版.md) | 页面、交互、状态与验收基线 | +| [前端实现说明](docs/前端壳子与接口层开发说明.md) | 当前前端目录、Service、SSE 和运行边界 | +| [前端写作体验](docs/前端写作体验优化开发说明.md) | Milkdown、CodeMirror、格式栏和 Shiki | +| [Git 使用细则](docs/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | +| [后端审阅复盘](docs/后端全面审阅问题与修复复盘.md) | 后端问题原因、后果与修复方案 | +| [Knowledge/Retrieval 复盘](docs/Knowledge与Retrieval-Core问题与修复复盘.md) | 检索与事务问题复盘 | +| [前端审阅复盘](docs/前端合并审阅问题与修复复盘.md) | 前端工程、契约和交互问题复盘 | + ## 日常开发注意事项 - Python 依赖统一修改 `backend/pyproject.toml`，修改后执行 `uv sync`。 diff --git a/backend/README.md b/backend/README.md index 25cfbc0..dc18dfb 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,7 +1,9 @@ -# Backend +# Notes Agent Backend FastAPI + Pydantic 的本地 AI Core / Agent Core。项目使用 uv 管理依赖和虚拟环境。 +当前实现包含 Knowledge/Retrieval、Chat、Agent Runtime、Tool/Permission、Skill/Plugin、Provider Adapter、任务、索引和开发阶段凭据加密存储。Provider 支持 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama；OpenAI Responses、Anthropic Messages、MCP 独立 Host 和真实语音模型仍属于后续阶段。 + ```powershell uv sync uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 @@ -13,6 +15,15 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 - 健康检查： - API 文档： +- OpenAPI： + +运行回归测试： + +```powershell +uv run pytest +``` + +当前基线为 71 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 团队接口清单见 `../docs/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/docs/AI-Core与Agent-Core开发说明.md b/docs/AI-Core与Agent-Core开发说明.md index 4eea0cd..34f042c 100644 --- a/docs/AI-Core与Agent-Core开发说明.md +++ b/docs/AI-Core与Agent-Core开发说明.md @@ -2,6 +2,8 @@ > 本文档用于团队开发和模块联调，记录当前已经落地的核心边界与使用方式。 +> 更新日期：2026-08-30。第一阶段 AI Core、Agent Core、Extension Core 和 Model Core 主链路已经完成，后端当前回归基线为 71 项测试通过。 + ## 当前实现 当前已经建立第一条可运行链路： @@ -125,20 +127,26 @@ ollama } ``` -凭证 ID `openai-main` 对应 Sidecar 进程中的临时环境变量 `AINOTE_CREDENTIAL_OPENAI_MAIN`。环境变量由 Rust Host 从 Stronghold 读取后注入，不写入 Provider Config、日志或前端 Store。 +凭证 ID `openai-main` 可以对应开发环境变量 `AINOTE_CREDENTIAL_OPENAI_MAIN`。当前 Web 联调版也允许设置页通过 Credential API 提交 API Key，由 `EncryptedCredentialStore` 使用 Fernet 加密保存；前端 Store、Provider Config、日志和读取响应都不保存或返回明文。未来接入 Tauri 后，由 Rust Host 从 Stronghold 注入或替换存储实现。 Provider 配置生命周期接口已经可用： ```text GET /api/providers +GET /api/providers/presets POST /api/providers GET /api/providers/{provider_id} PATCH /api/providers/{provider_id} DELETE /api/providers/{provider_id} GET /api/providers/{provider_id}/models POST /api/providers/test +GET /api/credentials/{credential_id} +PUT /api/credentials/{credential_id} +DELETE /api/credentials/{credential_id} ``` +设置页现已提供 OpenAI、DeepSeek 和 Ollama 预设，并在保存后自动获取、排序和去重模型列表。模型发现会区分凭据缺失、鉴权失败、限流、超时和上游不可用等错误。 + ## Agent Run 创建普通 Agent Run： @@ -321,10 +329,12 @@ Skill Manifest ## 当前限制与下一步 +前端智能体页面已经完成中文联调：运行状态、Agent Event、内置 Tool、Permission 和常用事件详情字段均通过集中标签映射展示中文；`notes.search` 等技术 ID 继续保留，便于与后端 Trace、日志和接口契约对应。 + - 已实现 Mock、OpenAI-Compatible Chat Completions 与 Ollama Adapter；OpenAI Responses 和 Anthropic Messages 尚未实现。 - Provider 配置暂存内存，后续通过 Repository 接入 SQLite；PATCH 已支持用显式 `null` 清空 base URL、默认模型和凭据引用。 - Run/Trace 暂存内存；下一步抽象 Repository 并接入 SQLite。 -- Permission 已有核心等待/恢复机制，前端确认 UI 尚未联调。 +- Permission 已有核心等待/恢复机制，前端确认 UI 已完成联调和中文展示。 - Task 已持久化到 SQLite；Attachment Tool 读取 Host 管理目录中的 UTF-8 文件。 - `audio.transcribe` 当前消费 Host 预生成的 transcript；faster-whisper 与说话人分离仍按技术基线在第二阶段接入。 - Extension 安装记录暂存内存；后续接入持久化 Registry 与版本升级流程。 diff --git a/docs/AI笔记软件技术栈说明-团队版-v2.2.md b/docs/AI笔记软件技术栈说明-团队版-v2.2.md index 5971855..d02d226 100644 --- a/docs/AI笔记软件技术栈说明-团队版-v2.2.md +++ b/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。 该技术基线用于指导当前比赛版本的代码组织、接口设计、模块协作、测试和交付。 diff --git a/docs/Git使用细则-团队开发版.md b/docs/Git使用细则-团队开发版.md index 07e82e8..9c58767 100644 --- a/docs/Git使用细则-团队开发版.md +++ b/docs/Git使用细则-团队开发版.md @@ -2,6 +2,8 @@ > 本文档用于 Notes Agent 团队日常开发。目标是让三名成员可以并行开发、稳定联调，并确保 `main` 始终处于可运行状态。 +> 更新日期：2026-08-30。当前远程只使用 `gitea`，功能分支不添加个人或工具名称前缀；合并门槛为相关测试、前端生产构建、文档同步和 `git diff --check` 全部通过。 + ## 1. 仓库与远程 团队代码统一使用 Gitea： @@ -68,6 +70,7 @@ chore/backend-dependencies - 一个分支只处理一个主要问题； - 不使用 `test1`、`new`、`final`、`xxx-dev` 等无法识别用途的名称； - 功能合入后删除远程分支，避免长期堆积。 +- 不在分支名前添加 `codex/`、成员姓名或设备名；归属由提交作者、Issue 和 PR Reviewer 表达。 ## 3. 模块分工与改动边界 diff --git a/docs/Knowledge与Retrieval-Core开发说明.md b/docs/Knowledge与Retrieval-Core开发说明.md index ebb7648..45f6cee 100644 --- a/docs/Knowledge与Retrieval-Core开发说明.md +++ b/docs/Knowledge与Retrieval-Core开发说明.md @@ -3,6 +3,8 @@ > 本文档用于团队开发和模块联调，记录 Knowledge Core / Retrieval Core 已经落地的 > 模块边界、数据模型、接口与使用方式，对应分工表中的杨星萱。 +> 更新日期：2026-08-30。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 71 项测试通过。 + ## 当前实现 当前已经建立第一条可运行的检索链路： @@ -72,7 +74,7 @@ block_id = "blk_" + sha256(note_id | heading_path | content)[:16] citation_id = "cit_" + block_id ``` -> 注意：MVP 阶段 `note_id` 由相对路径派生，移动文件会改变 ID；后续 `move` 流程会保留原 ID。 +> 注意：`note_id` 是稳定业务 ID；移动接口会保留原 ID，文件路径不能代替业务实体 ID。 每个 Block 记录 `heading_path`（章节路径）、`start_offset` / `end_offset`（相对原文的 字符偏移，用于前端跳转高亮）、`content_hash`、`token_count`。 @@ -130,7 +132,7 @@ POST /api/notes GET /api/notes/{note_id} PATCH /api/notes/{note_id} DELETE /api/notes/{note_id} -POST /api/notes/{note_id}/move （501，待定语义） +POST /api/notes/{note_id}/move （已实现，保留 note_id） ``` 创建笔记： @@ -196,7 +198,7 @@ cd backend uv run pytest -q ``` -当前后端完整测试共 62 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把 +当前后端完整测试共 71 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把 数据目录/DB/Vault 重定向到临时目录，不读写真实 `backend/data`，任何本机状态下结果确定。 ## 配置 diff --git a/docs/Knowledge与Retrieval-Core问题与修复复盘.md b/docs/Knowledge与Retrieval-Core问题与修复复盘.md index 928b85c..b7fd887 100644 --- a/docs/Knowledge与Retrieval-Core问题与修复复盘.md +++ b/docs/Knowledge与Retrieval-Core问题与修复复盘.md @@ -3,6 +3,8 @@ > 本文记录 `feat/knowledge-retrieval-core` 合并前后的两轮代码审阅、问题复现、修复过程与工程经验。 > 它既是团队内部的问题档案，也可作为后续技术文档、课程报告和博客文章的素材底稿。 +> 2026-08-30 状态补充：本文中的 43 项测试是当时该模块的历史基线，不应替换为当前全仓测试数。相关修复仍有效，当前完整后端回归为 71 项通过，Knowledge/Retrieval 已通过 `notes.*` 与 `rag.search` Tool 接入 Agent Runtime。 + ## 1. 背景 Knowledge Core 与 Retrieval Core 建立了项目第一条完整的本地知识检索链路： @@ -499,4 +501,3 @@ backend/app/knowledge/parser.py Block ID 与 tags 解析语义 backend/tests/test_retrieval.py 审阅回归测试 docs/Knowledge与Retrieval-Core开发说明.md 模块开发说明 ``` - diff --git a/docs/前端写作体验优化开发说明.md b/docs/前端写作体验优化开发说明.md index 94bb869..78cfb68 100644 --- a/docs/前端写作体验优化开发说明.md +++ b/docs/前端写作体验优化开发说明.md @@ -1,5 +1,7 @@ # 前端写作体验优化开发说明 +> 更新日期：2026-08-30。本文所述优化均已进入当前分支；前端完整回归基线为 14 项测试通过，TypeScript 检查和 Vite 生产构建通过。 + ## 1. 本次目标 本次优化聚焦笔记写作主流程，不调整后端接口： @@ -76,6 +78,7 @@ Milkdown 自定义插件在写作模式中隐藏 HTML 标记，并通过 ProseMi Shiki 仅应用于： - AI 对话中的 Markdown 代码块。 +- Search、智能体等复用 `MarkdownContent` 的只读 Markdown 代码块。 Markdown HTML 仍在写入 DOM 前经过 DOMPurify 清理。 @@ -94,7 +97,7 @@ pnpm build pnpm test ``` -验证结果：TypeScript 类型检查与 Vite 生产构建均通过。组件回归测试共 7 项，全部通过： +验证结果：TypeScript 类型检查与 Vite 生产构建均通过。当前前端完整回归测试共 14 项；其中写作与文件切换相关回归覆盖： - 顶部工具栏对选区应用加粗； - 浮动工具栏对选区应用斜体； diff --git a/docs/前端合并审阅问题与修复复盘.md b/docs/前端合并审阅问题与修复复盘.md index 2249db4..2643ef3 100644 --- a/docs/前端合并审阅问题与修复复盘.md +++ b/docs/前端合并审阅问题与修复复盘.md @@ -4,6 +4,8 @@ > 涉及提交：`f9efc4f`，合并提交 `c6c28e4`。 > 文档用途：记录前端分支合并后暴露的问题域、形成原因、实际后果、修复思路和落地方案，供后续技术文档、比赛材料与博客写作使用。 +> 2026-08-30 状态补充：在本文两轮修复之后，项目又完成 Milkdown 写作工具栏、文件切换二次竞态修复、Shiki 只读高亮、Provider 预设/模型发现/加密 API Key 输入，以及智能体页面汉化。当前前端回归基线为 14 项测试和生产构建通过。 + ## 1. 结论 原前端提交一次增加了 42 个文件和约 8000 行内容，但没有在提交前执行成功的生产构建。合并后同时存在工程配置、组件完整性、接口契约、流式协议和文件树状态五个问题域。 @@ -229,7 +231,7 @@ git diff --check ```text frontend production build passed 73 frontend modules transformed -62 backend tests passed +71 backend tests passed preview returned HTTP 200 git diff --check passed ``` @@ -274,3 +276,9 @@ git diff --check passed | F-19 | 编辑器外观启动时被默认值覆盖 | Theme Store 的立即监听早于 `initTheme` 执行，先把默认值写进 Local Storage | 增加 Hydration 状态，初始化前监听只更新 CSS，不持久化；读取本地配置完成后再允许写入 | 安全边界：Markdown 解析结果不得直接使用未经清洗的 `v-html`。DOMPurify 是渲染链路的必需依赖，后续升级 `marked` 或允许扩展 Markdown 时也必须保留清洗步骤。 + +## 13. 写作、Provider 与智能体页面的后续修复 + +第三轮交互完善继续处理了文件切换、Markdown 选区格式、代码块默认状态、亮暗主题对比度和浮动工具栏失效问题。Provider 设置页增加 OpenAI、DeepSeek、Ollama 预设与模型自动发现，API Key 改为提交给后端加密保存，不进入 Pinia 或 Local Storage。智能体页面的运行状态、事件、工具、权限及导航文案已完成中文化，同时保留技术 ID 便于排障。 + +该轮新增 Store、Workspace、文件树、编辑器和中文标签回归测试；当前结果为前端 14 项、后端 71 项测试通过，生产构建通过。 diff --git a/docs/前端壳子与接口层开发说明.md b/docs/前端壳子与接口层开发说明.md index 735c321..f5ad5a8 100644 --- a/docs/前端壳子与接口层开发说明.md +++ b/docs/前端壳子与接口层开发说明.md @@ -1,6 +1,6 @@ # 前端壳子与接口层开发说明 -> 更新日期：2026-08-29 +> 更新日期：2026-08-30 > 适用范围：Vue 3 + TypeScript 页面、Workspace、公共 Service、FastAPI 接口适配和 SSE。 > 文档用途：帮助团队理解当前前端可用能力、模块边界、启动方式和后续页面开发入口。 @@ -32,6 +32,9 @@ Vue Router - Theme 预览、切换和编辑器 Token 覆盖； - Settings 的通用、编辑器、Provider、索引、权限和 AI Core 诊断分区； - 可收起主导航、功能型二级侧栏、状态栏和 `Ctrl+P` 命令面板。 +- Milkdown 可视化写作、CodeMirror 源码/代码块编辑、Markdown 格式栏和 Shiki 只读代码高亮； +- OpenAI、DeepSeek、Ollama 预设、自动模型发现和开发阶段加密 API Key 输入； +- 智能体页面、运行状态、事件、工具和权限详情的中文展示。 原统一占位页已经删除，所有已注册业务路由均指向真实页面。当前 Workspace 文件能力仍使用 Web Mock Adapter；Tauri 文件系统、Stronghold 和桌面窗口能力应在桌面容器阶段接入，不影响页面与 Store 的调用边界。 @@ -181,12 +184,15 @@ pnpm build ```text pnpm build passed -uv run pytest 62 passed +pnpm test 14 passed +uv run pytest 71 passed preview smoke HTTP 200 git diff --check passed ``` -当前前端没有单独的单元测试脚本，`pnpm build` 同时执行 `vue-tsc -b` 与 Vite 生产构建。后端测试出现过一次 `.pytest_cache` 无法写入的 Windows 权限警告，不影响 62 项测试结果，也不涉及产品代码。 +当前前端使用 Vitest 执行 Store、Workspace、文件树和编辑器组件测试；`pnpm build` 同时执行 `vue-tsc -b` 与 Vite 生产构建。后端测试出现过 `.pytest_cache` 无法写入的 Windows 权限警告，不影响 71 项测试结果，也不涉及产品代码。 + +Vite 当前会提示 Chat 与 Workspace 的部分异步 Chunk 超过 500 kB，这是 Milkdown、CodeMirror、KaTeX 和 Shiki 等编辑/渲染依赖带来的性能优化项，不影响构建成功或功能正确性；进入桌面打包前应通过手动分包或更细粒度动态加载继续优化。 浏览器可视化冒烟在本次执行环境中因浏览器运行资源缺失未能启动；HTTP 冒烟已确认前端入口、后端健康检查与 OpenAPI 均能访问。进入合并验收前，仍建议团队在本机打开各路由完成一次人工视觉检查。 @@ -198,4 +204,4 @@ git diff --check passed - SSE 相关变更需要覆盖跨 Chunk、CRLF、多行 data、终态事件和取消； - Workspace 接入 Tauri 后，需要增加路径规范化、写入失败恢复和外部修改冲突测试； - 页面新增交互必须经过键盘、空状态、加载状态、错误状态和窄窗口检查； -- Workspace 的写作/源码模式目前共享同一 Markdown 数据源，后续接入 Milkdown 与 CodeMirror 6 时不得改变 Store/Service 边界或造成切换丢稿。 +- Workspace 的 Milkdown 写作模式与 CodeMirror 源码模式共享同一 Markdown 数据源；后续修改编辑器时不得改变 Store/Service 边界，并必须保留文件切换、自动保存和选区格式化回归测试。 diff --git a/docs/前端页面需求说明-开发版.md b/docs/前端页面需求说明-开发版.md index 624ebce..c794ca4 100644 --- a/docs/前端页面需求说明-开发版.md +++ b/docs/前端页面需求说明-开发版.md @@ -4,6 +4,8 @@ > 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。 > 依据：`第一阶段分工表.md`、`AI笔记软件技术栈说明-团队版-v2.2.md`、`后端接口契约-开发版.md`。 +> 实现状态：更新至 2026-08-30。全部已注册业务路由均已有真实页面；Markdown 写作/源码模式、Search、Chat、智能体执行轨迹、扩展管理、设置、Provider 预设、模型发现和开发阶段加密凭据输入均已落地。当前仍以 Web Mock Workspace 代替 Tauri 文件系统。 + ## 1. 第一阶段目标 桌面端需要形成一条可以完整演示的本地知识工作流： @@ -34,7 +36,7 @@ | --- | --- | | 框架 | Vue 3、Composition API、TypeScript、Vite | | 状态管理 | Pinia，只保存跨组件或跨页面状态 | -| UI 基础 | Reka UI / Headless Components | +| UI 基础 | 当前为项目公共组件、CSS Design Token 与 Element Plus 图标；复杂无障碍 Headless 组件后续按需引入 Reka UI | | 编辑器 | Milkdown 为默认编辑模式，CodeMirror 6 为源码模式 | | 桌面容器 | Tauri 2；文件、密钥、Sidecar 和系统能力通过 Rust Command | | 本地 AI API | FastAPI；普通请求使用 HTTP JSON，流式数据使用 SSE | @@ -611,18 +613,22 @@ Settings 使用分区导航，不把全部配置堆在一个表单中。 - 测试连接并显示耗时； - 根据 Capability 标记是否支持 Chat、Tool Calling、Vision、Streaming 等。 -API Key 输入后立即交给 Rust Stronghold，前端仅保存 `credential_id`。页面回显只能显示“已配置/未配置”，不得回显完整密钥。 +当前 Web 联调阶段，API Key 通过 Credential API 交给 FastAPI，由 Fernet 加密保存；前端仅在提交期间持有明文，Provider 和 Store 只保留 `credential_id`。页面只能回显“已配置/未配置”，不得回显完整密钥。Tauri 集成后由 Stronghold 替换后端开发存储实现，接口边界保持不变。 接口： ```text GET /api/providers +GET /api/providers/presets POST /api/providers GET /api/providers/{provider_id} PATCH /api/providers/{provider_id} DELETE /api/providers/{provider_id} GET /api/providers/{provider_id}/models POST /api/providers/test +GET /api/credentials/{credential_id} +PUT /api/credentials/{credential_id} +DELETE /api/credentials/{credential_id} ``` ### 14.4 Index 与 Models diff --git a/docs/后端全面审阅问题与修复复盘.md b/docs/后端全面审阅问题与修复复盘.md index 740c3d6..97482af 100644 --- a/docs/后端全面审阅问题与修复复盘.md +++ b/docs/后端全面审阅问题与修复复盘.md @@ -4,6 +4,8 @@ > 审阅范围：FastAPI、Knowledge / Retrieval Core、Agent Core、Extension Core、Provider Adapter、公共接口和后端开发文档。 > 文档用途：记录问题形成原因、实际影响、修复判断和落地方案，供后续开发文档、比赛材料与技术博客使用。 +> 2026-08-30 状态补充：本文记录的缺陷均保持修复。此后又加入 Provider 预设、模型发现、DeepSeek/OpenAI 凭据解析和 Fernet 加密存储，当前完整后端回归基线为 71 项测试通过。 + ## 1. 审阅结论 审阅前的主链路已经能够运行，原有 50 项测试全部通过，但测试没有覆盖首次失败、畸形扩展包、代码型 Markdown、浏览器字符偏移和真实 Provider Streaming 等边界。 @@ -303,7 +305,7 @@ git diff --check 验证结果： ```text -62 passed +71 passed compileall passed uv lock --check passed git diff --check passed @@ -321,6 +323,8 @@ git diff --check passed - Attachment 与 transcript Tool； - Provider PATCH 显式 null； - OpenAI SSE 与 Ollama JSONL 增量事件。 +- Provider 预设、模型发现、凭据缺失/鉴权错误映射； +- 凭据密文落盘、API 不回显明文及 Provider 解密读取。 ## 14. 后续工作 diff --git a/docs/后端接口契约-开发版.md b/docs/后端接口契约-开发版.md index 71f13bd..f35d76f 100644 --- a/docs/后端接口契约-开发版.md +++ b/docs/后端接口契约-开发版.md @@ -1,6 +1,6 @@ # 后端接口契约（开发版） -> 本文档记录当前前后端联调使用的接口壳子。业务服务尚未实现，最终字段以 FastAPI 运行时生成的 OpenAPI 为准。 +> 更新日期：2026-08-30。本文档记录当前前后端联调使用的已实现接口；机器可读字段、校验规则和响应模型以 FastAPI 运行时生成的 OpenAPI 为准。 ## 契约入口 @@ -68,12 +68,16 @@ | 方法 | 路径 | 用途 | | --- | --- | --- | | GET | `/api/providers` | 获取 Provider 配置列表 | +| GET | `/api/providers/presets` | 获取 OpenAI、DeepSeek 与 Ollama 配置预设 | | POST | `/api/providers` | 新建 Provider 配置 | | GET | `/api/providers/{provider_id}` | 获取 Provider 配置 | | PATCH | `/api/providers/{provider_id}` | 更新 Provider 配置 | | DELETE | `/api/providers/{provider_id}` | 删除 Provider 配置 | | GET | `/api/providers/{provider_id}/models` | 获取模型及 Capability 列表 | | POST | `/api/providers/test` | 测试 Provider 连接 | +| GET | `/api/credentials/{credential_id}` | 查询凭据是否已配置，不返回明文 | +| PUT | `/api/credentials/{credential_id}` | 加密保存开发阶段 API Key | +| DELETE | `/api/credentials/{credential_id}` | 删除已保存凭据 | Provider Contract 只传递 `credential_id` 或临时 `credential_context_id`。当前前后端开发阶段通过独立的 `PUT /api/credentials/{credential_id}` 接收 API Key，并立即加密落盘；该接口只返回配置状态，不返回密钥。Provider CRUD、模型列表和测试接口均不携带明文 API Key。Tauri 集成后由 Stronghold 接管存储实现。 @@ -99,8 +103,8 @@ Provider Contract 只传递 `credential_id` 或临时 `credential_context_id`。 ```json { "error": { - "code": "NOT_IMPLEMENTED", - "message": "The contract is available, but its business service is not implemented.", + "code": "RESOURCE_NOT_FOUND", + "message": "Resource was not found.", "details": {} } } @@ -155,6 +159,8 @@ RunCancelled ## 当前实现状态 +更新至 2026-08-30：后端 71 项回归测试通过。 + - Chat、Agent Run、Agent Events、Tool 列表、Provider 配置生命周期、模型列表和连接测试已经接入 AI Core。 - Provider Adapter 当前包含 Mock、真正增量 SSE 的 OpenAI-Compatible Chat Completions，以及 Ollama JSONL Streaming。 - Notes、Search、Index、Skills、Plugins、Tasks 和 Provider 生命周期均已接入业务服务。 diff --git a/docs/模型提供商与模型发现开发说明.md b/docs/模型提供商与模型发现开发说明.md index 91b5385..c5eb90f 100644 --- a/docs/模型提供商与模型发现开发说明.md +++ b/docs/模型提供商与模型发现开发说明.md @@ -1,5 +1,7 @@ # 模型提供商与模型发现开发说明 +> 更新日期：2026-08-30。OpenAI、DeepSeek、Ollama 预设、模型自动发现、默认模型选择和开发阶段加密凭据存储均已实现并接入设置页。 + ## 1. 本次目标 本次完善设置页的模型提供商配置，不改变 Agent、Chat 和 Skill 对统一 Model Core 接口的依赖： @@ -101,3 +103,5 @@ pnpm build ``` 自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。 + +当前完整回归基线：后端 71 项测试、前端 14 项测试通过，前端生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。 diff --git a/docs/第一阶段分工表.md b/docs/第一阶段分工表.md index 440bb98..9a9a2a5 100644 --- a/docs/第一阶段分工表.md +++ b/docs/第一阶段分工表.md @@ -1,5 +1,17 @@ # 第一阶段分工表 +> 状态更新：2026-08-30。本文保留原始职责划分，同时记录当前交付状态。第一阶段后端目标已完成，前端 Web 联调页面已完成；尚未纳入本阶段完成项的是 Tauri Host、Stronghold、真实桌面文件系统、独立 MCP Plugin Host、真实音频模型和 Sync Server。 + +## 当前交付状态 + +| 领域 | 当前状态 | 说明 | +| --- | --- | --- | +| Desktop Frontend / UI | Web 联调版已完成 | 全部业务路由、Markdown 写作/源码编辑、Chat、Search、Agent、扩展管理、设置页和 Provider 配置已落地 | +| Knowledge / Retrieval Core | 第一阶段已完成 | Markdown Block、SQLite/FTS5、sqlite-vec、Hybrid/RRF/Reranker、Citation 与事务修复均已覆盖测试 | +| AI / Agent Core | 第一阶段已完成 | Streaming、Agent Loop、Tool、Permission、Trace、Skill/Plugin 与 Knowledge/Retrieval 调用链已落地 | +| Model Core | 第一阶段已完成 | Mock、OpenAI Chat/OpenAI-Compatible、DeepSeek 预设、Ollama、模型发现和加密凭据链路可用 | +| Desktop Host / Sync | 后续阶段 | Tauri、Stronghold、系统文件访问、Sidecar 生命周期和云同步尚未实现 | + ## 总分工表 | 成员 | 主要职责 | 第一阶段负责模块 | 具体工作内容 | 主要交付物 | -- 2.43.0