From c2e3a17c05d13ecd1b44f0610559ad8d908ca137 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Sat, 5 Sep 2026 02:23:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E4=B8=8E=E6=9C=AC=E5=9C=B0=E6=A8=A1=E5=9E=8B?= =?UTF-8?q?=E6=8A=80=E6=9C=AF=E6=A0=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 186 ++++++++---------- backend/README.md | 93 +++++++-- docs/README.md | 6 +- .../AI笔记软件技术栈说明-团队版-v2.3.md | 71 ++++--- frontend/README.md | 77 ++++++++ 5 files changed, 287 insertions(+), 146 deletions(-) create mode 100644 frontend/README.md diff --git a/README.md b/README.md index 60ca8e2..02ae516 100644 --- a/README.md +++ b/README.md @@ -1,153 +1,133 @@ -# Notes Agent（暂命名） 团队开发说明 +# NotesAgent -> 本文件用于团队开发期间快速配置环境和启动项目，不是正式的项目 README。 +NotesAgent 是本地优先的 AI 笔记与知识库项目。当前可运行形态为 Vue/Vite Web 前端与 FastAPI AI Core：Markdown 和附件保存在本地 Vault，SQLite 管理元数据、全文索引、向量空间、搜索历史、会话、任务、Agent Trace、多模态任务及运行诊断。 -> 当前基线：2026-09-03。第一阶段 Web 联调前后端已经完成；第二阶段已完成 Workspace 去 Mock、Agent Trace 持久化与 SSE 恢复、stdio MCP Bridge、隔离 Plugin Host、Plugin Command/Settings，以及独立 MCP Server 配置中心 C.1（stdio、Streamable HTTP 与旧 SSE 兼容）。真实音频、Provider 协议增强、Benchmark、导出、主题包、Trace 可视化、Mermaid 与函数图像仍在后续开发；Tauri Host、Stronghold、原生多 Vault 文件系统和 Sync Server 尚未接入。 +截至 2026-09-05，第一阶段及第二阶段 A～F 的工程范围已经合并到 `main`。当前已完成真实 Workspace、混合检索与知识库问答、Agent/Tool/Permission、Skill/Plugin、MCP 配置与调用、模型提供商与路由、RAG Benchmark，以及本地 Embedding、音频转写和片段级声纹聚类。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 尚未接入。 -## 当前目录 +## 目录 ```text NotesAgent/ ├── frontend/ Vue 3 + TypeScript + Vite 前端 -├── backend/ FastAPI + Pydantic 后端 +├── backend/ FastAPI AI Core、SQLite 与本地模型运行管理 ├── docs/ 架构、契约、开发说明、协作规范与问题复盘 └── server sync/ 云同步服务预留目录，当前未实现 ``` +## 当前能力 + +- 工作区：打开一个后端配置的真实 Vault，编辑 Markdown，管理文件与目录。 +- 检索与问答：FTS5、sqlite-vec、RRF 与轻量词面精排；搜索历史持久化到后端 SQLite；AI 对话自动检索知识库并返回 Citation。 +- Agent 与扩展：持久化 Trace、可恢复 SSE、Tool/Permission、Skill、Plugin Command/Settings/Secret、隔离 Plugin Host。 +- MCP：独立配置 stdio、Streamable HTTP 和旧 SSE Server，发现并调用工具；生产 stdio 沙箱等待 Tauri Host。 +- 模型服务：OpenAI Chat/Compatible、OpenAI Responses、Anthropic Messages、Ollama；国内常用提供商 logo 预设、独立凭据、模型发现和自定义请求 JSON。 +- 多模态：API 优先，未配置或响应无效时回退本地；`local_only` 禁止远程调用。任务、修订、事件、来源和回退原因写入 SQLite。 +- 模型运行：默认 CPU，可选 CUDA 12.8 组件；固定模型 revision，按需启动独立子进程，交互检索优先排队，CUDA 初始化或显存失败时用同一冻结配置在 CPU 重试一次。 +- 可观测性：输入、输出、缓存命中、推理 Token 与音频用量卡片；本地运行诊断保留最近 200 条，不保存正文、文件路径、密钥或异常全文。 + +## 本地模型 + +| 能力 | 当前模型 | 许可 | 说明 | +| --- | --- | --- | --- | +| 默认 Embedding | `hotchpotch/bekko-embedding-v1-a8m` | MIT | 384 维，中文检索默认选择 | +| 可选 Embedding | `ibm-granite/granite-embedding-97m-multilingual-r2` | Apache-2.0 | 384 维，多语言备选 | +| 音频转写与语言识别 | `Qwen/Qwen3-ASR-0.6B` | Apache-2.0 | 返回片段级时间边界 | +| 声纹提取与匹配 | `iic/speech_eres2netv2_sv_zh-cn_16k-common` | Apache-2.0 | 192 维声纹，供相似度和片段聚类使用 | + +模型权重按代码中的固定 revision 下载并校验，推理阶段离线读取。当前说话人处理是能量分段、ASR 片段与 ERes2NetV2 聚类，不包含逐字强制对齐、同段多人或重叠语音分离。`HashEmbeddingProvider` 只用于确定性测试注入。 + ## 开发环境 -当前开发版需要： +| 环境 | 要求 | +| --- | --- | +| Git | 较新稳定版 | +| Node.js | 22+，推荐 24 | +| pnpm | 10+ | +| Python | 3.11+，推荐 3.12 | +| uv | 较新稳定版 | -| 环境 | 要求 | 说明 | -| --- | --- | --- | -| Git | 较新稳定版 | 代码版本管理 | -| Node.js | 22 或更高版本 | 推荐使用 Node.js 24 | -| pnpm | 10 或更高版本 | 前端依赖与脚本管理 | -| Python | 3.11 或更高版本 | 推荐使用 Python 3.12 | -| uv | 较新稳定版 | 后端依赖和虚拟环境管理 | +当前 Web 联调不需要 Rust 和 Tauri。桌面端集成时再安装 Rust Toolchain 与 Tauri CLI。 -检查本机环境： +## 初始化与启动 -```powershell -git --version -node --version -pnpm --version -python --version -uv --version -``` - -当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md` 安装 Rust Toolchain 与 Tauri CLI。 - -## 首次初始化 - -### 后端 +安装 API 与前端依赖： ```powershell cd backend uv sync -cd .. -``` - -`uv sync` 会根据 `backend/pyproject.toml` 安装依赖，并自动创建和管理 `backend/.venv`，不需要手动创建或激活虚拟环境。 - -### 前端 - -```powershell -cd frontend +cd ../frontend pnpm install cd .. ``` -## 启动开发环境 - -前端和后端需要在两个终端中分别启动。 - -### 终端一：启动后端 +在两个终端分别启动： ```powershell +# 终端一 cd backend uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 -``` -后端地址： - -- 健康检查： -- 服务状态： -- API 文档： -- OpenAPI JSON： - -#### 开发环境使用外部模型 - -在“设置 → 模型提供商”中选择 DeepSeek 或 OpenAI 预设后，直接在密码输入框填写 API Key。前端只在提交期间持有该值，不写入 Pinia 或 localStorage；AI Core 将其加密保存到本机 `backend/data/credentials/`，Provider 配置只保留内部 Credential ID。 - -该目录同时包含本地开发用主密钥和密文，并已加入 `.gitignore`。这提供本地静态加密和完整性校验，但不能替代操作系统凭据库。开始 Tauri 桌面集成后，应将存储实现迁移到 Stronghold，保留现有 Credential API 与 Provider 接口边界。 - -无界面或自动化环境仍可使用 `DEEPSEEK_API_KEY`、`OPENAI_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；设置页保存的本地密钥优先，环境变量仅在本地未保存对应 Credential ID 时作为回退。密钥不得写入仓库文件、README、Issue、提交信息或聊天记录。 - -### 终端二：启动前端 - -```powershell +# 终端二 cd frontend pnpm dev ``` -前端地址： +前端地址为 ，Vite 将 `/api` 和 `/health` 代理到 。后端提供健康检查 `/health`、服务状态 `/api/status`、API 文档 `/docs` 和机器可读契约 `/openapi.json`。 -开发环境中，Vite 会将 `/api` 和 `/health` 请求代理到 `http://127.0.0.1:8000`。联调时应先启动后端，再启动或刷新前端。 +## 安装本地模型运行组件 + +API 环境保留在 `backend/.venv`，模型依赖安装到独立环境。默认安装 CPU： + +```powershell +./backend/scripts/install-model-runtime.ps1 +``` + +CUDA 为 Windows 可选组件，可在“设置 → 模型提供商 → 本地模型”中安装，也可保留 CPU 环境并创建独立 CUDA 环境： + +```powershell +./backend/scripts/install-model-runtime.ps1 -Device cuda -RuntimeDirectory ./backend/.venv-models-cuda +$env:APP_MODEL_PYTHON = (Resolve-Path ./backend/.venv-models-cuda/Scripts/python.exe).Path +``` + +脚本固定 `torch`/`torchaudio` 2.9.1，CPU 使用官方 CPU wheel，CUDA 使用 cu128 wheel；脚本不会安装或修改 NVIDIA 驱动。模型权重需要在设置页显式下载，不会在推理时自动下载。 + +## 模型提供商与凭据 + +在“设置 → 模型提供商”中选择预设或创建自定义提供商。API Key 只在前端提交期间存在，不写入 Pinia 或 `localStorage`；后端将密文和开发主密钥保存到已忽略的 `backend/data/credentials/`，Provider 配置只保存 Credential ID。 + +无界面环境可使用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_`。当前 Fernet 存储用于 Web 联调，桌面端将沿用 Credential API 边界迁移到 Stronghold。 ## 测试与构建 -后端测试： - ```powershell cd backend uv run pytest -``` -前端类型检查及生产构建： - -```powershell -cd frontend +cd ../frontend +pnpm test pnpm build ``` -前端单元与组件测试： +阶段 F 合并时的回归基线为后端 559 项、前端 103 项测试通过，TypeScript 类型检查与生产构建通过。存在一条既有 Starlette/httpx 弃用提示和 Vite 大 bundle 提示；测试数量以当前分支实际输出和 CI 为准。 -```powershell -cd frontend -pnpm test -``` - -当前回归基线为后端 218 项测试、前端 32 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 - -构建产物位于 `frontend/dist`，该目录不提交到 Git。 - -## 文档导航 +## 文档 | 文档 | 用途 | | --- | --- | -| [文档总索引](docs/README.md) | 文档分类、阅读顺序和维护规则 | -| [技术栈说明](docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md) | 目标架构、第二阶段技术边界与模块依赖 | -| [第二阶段分工表](docs/architecture/第二阶段团队分工表.md) | 第二阶段人员职责、任务顺序、协作关系与验收项 | -| [后端接口契约](docs/contracts/后端接口契约-开发版.md) | HTTP/SSE 接口、错误和当前实现状态 | -| [第二阶段接口契约](docs/contracts/第二阶段接口契约-开发版.md) | 第二阶段公共 DTO、计划接口、SSE、错误码与联调顺序 | -| [AI Core 与 Agent Core](docs/development/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | -| [MCP Bridge 与 Plugin Host](docs/development/MCP-Bridge与Plugin-Host开发说明.md) | stdio MCP、隔离进程、Tool 映射、状态与错误边界 | -| [Plugin Command 与 Settings](docs/development/Plugin-Command与Settings开发说明.md) | Command Registry、Settings Schema、Secret 引用与联调边界 | -| [Plugin Command 与 Settings 复盘](docs/retrospectives/Plugin-Command与Settings问题与修复复盘.md) | 阶段 D 连续审阅发现的安全、事务、Schema 与运行时契约问题 | -| [Git 使用细则](docs/guides/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | -| [CI/CD 细则](docs/guides/CI-CD细则-团队开发版.md) | Gitea 流水线、质量门禁、产物、发布与回滚规则 | -| [Agent Trace 复盘](docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md) | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 | +| [文档总索引](docs/README.md) | 全部架构、契约、开发说明和复盘入口 | +| [前端 README](frontend/README.md) | 前端结构、运行方式和数据边界 | +| [后端 README](backend/README.md) | API Core、模型运行与配置 | +| [技术栈说明](docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md) | 当前技术基线、目标桌面架构与模块边界 | +| [多模态与模型运行](docs/development/多模态管线与模型运行开发说明.md) | 模型 revision、CPU/CUDA、路由、用量和接口 | +| [阶段 F 收尾验收](docs/development/阶段F收尾验收记录.md) | 自动化、CPU/CUDA 真实闭环和未关闭专项 | +| [后端接口契约](docs/contracts/后端接口契约-开发版.md) | 当前 HTTP/SSE 接口说明 | +| [第二阶段接口契约](docs/contracts/第二阶段接口契约-开发版.md) | 第二阶段公共 DTO 与行为边界 | -## 日常开发注意事项 +## 开发约定 -- Python 依赖统一修改 `backend/pyproject.toml`，修改后执行 `uv sync`。 -- 前端依赖统一使用 pnpm 安装，不要混用 npm 或 yarn。 -- `backend/.venv`、`frontend/node_modules`、`frontend/dist` 均为本地生成目录，不提交到 Git。 -- API 默认监听 `127.0.0.1:8000`，前端默认监听 `127.0.0.1:5173`。 -- 后端附件目录默认是 `backend/data/attachments`，可通过 `APP_ATTACHMENTS_PATH` 覆盖；该目录由桌面 Host 管理。 -- 跨模块接口发生变化时，需要同步更新前后端类型和 `docs` 中的接口说明。 -- 当前已实现接口见 `docs/contracts/后端接口契约-开发版.md`，第二阶段规划接口见 `docs/contracts/第二阶段接口契约-开发版.md`；已实现能力以 `/openapi.json` 为准。 -- 前端页面、交互、状态管理及当前阶段后续页面需求见 `docs/contracts/前端页面需求说明-开发版.md`。 -- 分支、提交、Pull Request、Review 和冲突处理规范见 `docs/guides/Git使用细则-团队开发版.md`。 -- CI 检查、产物、发布和回滚规范见 `docs/guides/CI-CD细则-团队开发版.md`。 +- 后端依赖统一修改 `backend/pyproject.toml` 并执行 `uv sync`；模型依赖由 `backend/scripts/model-requirements.lock` 锁定。 +- 前端依赖统一使用 pnpm，不混用 npm 或 yarn。 +- `backend/.venv*`、模型权重、`frontend/node_modules` 和 `frontend/dist` 都是本地产物，不提交 Git。 +- 前端不直接访问 SQLite 或厂商模型协议；持久数据通过 FastAPI 服务读写。 +- 接口或数据结构变化时，同一提交同步更新前后端类型、契约和开发说明。 +- 当前行为以代码、测试和运行中的 `/openapi.json` 为准；规划能力必须在文档中明确标注。 diff --git a/backend/README.md b/backend/README.md index 9884ac7..0fd7751 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,34 +1,103 @@ -# Notes Agent Backend +# NotesAgent Backend -FastAPI + Pydantic 的本地 AI Core / Agent Core。项目使用 uv 管理依赖和虚拟环境。 +NotesAgent Backend 是基于 Python 3.11+、FastAPI、Pydantic v2 和 SQLite 的本地 AI Core / Agent Core，使用 uv 管理 API 依赖和虚拟环境。 -当前实现包含 Knowledge/Retrieval、Chat、Agent、Tool/Permission、Skill/Plugin、MCP、模型提供商与多模态任务。支持 OpenAI Chat/Compatible、Responses、Anthropic Messages 和 Ollama；真实本地 Embedding、ASR、声纹模型默认 CPU，CUDA 显式选装。操作系统级 Plugin 沙箱仍属于后续阶段。 +当前实现包含 Knowledge/Retrieval、Chat、Agent、Tool/Permission、Skill/Plugin、MCP、模型提供商、RAG Benchmark、多模态任务、本地模型调度、Token/音频用量和运行诊断。数据持久化位于后端 SQLite 与 Vault；Tauri Sidecar 生命周期、Stronghold 和操作系统级 Plugin 沙箱属于后续桌面阶段。 + +## 初始化与运行 ```powershell uv sync uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` -`uv sync` 首次运行时会自动创建由 uv 管理的 `.venv`，无需手动执行 `python -m venv` 或激活环境。 - -启动后可访问： +`uv sync` 会创建并管理 `backend/.venv`，无需手动激活环境。启动后可访问： - 健康检查： +- 服务状态： - API 文档： - OpenAPI： -运行回归测试： +## 核心模块 + +| 目录 | 职责 | +| --- | --- | +| `app/knowledge`、`app/retrieval` | Markdown 解析、FTS5、sqlite-vec、RRF、真实 Embedding 路由和 Citation | +| `app/agent` | Agent Runtime、Tool 调用、权限与持久化 Trace | +| `app/extensions` | Skill、Plugin Host、MCP Registry 与 stdio/HTTP/SSE Bridge | +| `app/providers` | OpenAI Chat/Compatible、Responses、Anthropic Messages、Ollama 与能力路由 | +| `app/local_models` | 模型目录、固定 revision 下载、独立进程、设备回退和队列调度 | +| `app/services` | 索引、知识库上下文、转写、搜索历史、用量和诊断等应用服务 | +| `app/benchmarks` | 版本化 RAG Dataset、异步评测、指标与报告 | + +## 模型路由 + +Embedding、音频转写和声纹匹配遵循同一规则： + +1. 配置可用 API 时先调用 API； +2. API 失败或返回无效结果时回退本地模型； +3. 未配置 API 时直接使用本地模型； +4. `local_only` 请求只允许本地模型； +5. 响应和诊断记录实际来源、设备及回退原因。 + +生产向量按 Provider、模型、revision、接口和维度隔离，切换空间后需要重建索引。Markdown 和 FTS 在模型不可用时仍可保存与查询；`HashEmbeddingProvider` 仅供测试显式注入。 + +## 本地模型运行环境 + +API 的 `backend/.venv` 与模型环境分离。默认安装 CPU 运行组件： + +```powershell +./scripts/install-model-runtime.ps1 +``` + +可选 CUDA 环境： + +```powershell +./scripts/install-model-runtime.ps1 -Device cuda -RuntimeDirectory ./.venv-models-cuda +$env:APP_MODEL_PYTHON = (Resolve-Path ./.venv-models-cuda/Scripts/python.exe).Path +``` + +脚本固定 `torch`/`torchaudio` 2.9.1，CUDA 使用 cu128 wheel，不安装驱动。其余模型依赖由 `scripts/model-requirements.lock` 锁定，包含 `qwen-asr`、`sentence-transformers`、ModelScope 和 PyAV。 + +| 能力 | 模型 | 固定 revision | 许可 | +| --- | --- | --- | --- | +| 默认 Embedding | `hotchpotch/bekko-embedding-v1-a8m` | `c721113d59a1d91b447450324f51c4b3332c924a` | MIT | +| 可选 Embedding | `ibm-granite/granite-embedding-97m-multilingual-r2` | `835ad14087e140460703cf0fae09f97d469d65c2` | Apache-2.0 | +| 音频转写 | `Qwen/Qwen3-ASR-0.6B` | `5eb144179a02acc5e5ba31e748d22b0cf3e303b0` | Apache-2.0 | +| 声纹匹配 | `iic/speech_eres2netv2_sv_zh-cn_16k-common` | `3317286545c587ae682dbc166831d9448780eebb` | Apache-2.0 | + +模型运行时默认 CPU。任务在独立子进程中按需加载并在结束后释放；队列中查询 Embedding、媒体任务、后台索引的优先级依次降低。CUDA 不可用、初始化失败或显存不足时，系统清理失败进程并以同一冻结配置在 CPU 重试一次。 + +音频由 PyAV 解码为 16 kHz 单声道，经过能量分段、Qwen3-ASR 和 ERes2NetV2 片段聚类。当前只提供片段级时间戳，不支持逐字对齐、同段多人和重叠语音分离。 + +## Provider 与凭据 + +支持 OpenAI Chat/Compatible、OpenAI Responses、Anthropic Messages 和 Ollama。Provider 配置可分别绑定聊天、Embedding、转写和声纹能力，并通过受限的自定义请求 JSON 合并厂商扩展字段。 + +API Key 可由前端设置页写入，也可通过 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入。开发环境使用 Fernet 密文存储，接口不返回明文；`plugin.*` 是 Plugin Settings 的保留凭据命名空间。 + +## 测试 ```powershell uv run pytest ``` -阶段 F 后端基线为 472 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 +阶段 F 合并基线为 559 项测试通过，另有一条既有 Starlette/httpx 弃用提示。真实模型冒烟脚本： -本地模型 CPU/CUDA 安装、多模态任务、Token 用量与自定义 JSON 见 [多模态管线与模型运行开发说明](../docs/development/多模态管线与模型运行开发说明.md)。 +```powershell +.venv/Scripts/python scripts/local-model-smoke.py bekko --download +.venv/Scripts/python scripts/local-model-smoke.py qwen3-asr --download --audio C:/path/to/speech.wav +.venv/Scripts/python scripts/local-model-smoke.py eres2netv2 --download --audio C:/path/to/speech.wav --reference C:/path/to/reference.wav +``` -团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 +## 相关文档 -AI Core 与 Agent Core 的模块边界、Mock Provider 和 Tool Calling 调试方式见 `../docs/development/AI-Core与Agent-Core开发说明.md`。 +- [后端接口契约](../docs/contracts/后端接口契约-开发版.md) +- [第二阶段接口契约](../docs/contracts/第二阶段接口契约-开发版.md) +- [多模态管线与模型运行](../docs/development/多模态管线与模型运行开发说明.md) +- [阶段 F 收尾验收](../docs/development/阶段F收尾验收记录.md) +- [AI Core 与 Agent Core](../docs/development/AI-Core与Agent-Core开发说明.md) +- [Knowledge 与 Retrieval Core](../docs/development/Knowledge与Retrieval-Core开发说明.md) +- [阶段 F：Embedding 与知识库问题](../docs/retrospectives/阶段F-Embedding与知识库问题与解决方案.md) -Knowledge Core 与 Retrieval Core 的模块边界、数据模型、接口与检索流程见 `../docs/development/Knowledge与Retrieval-Core开发说明.md`。 +机器可读接口以运行中的 `/openapi.json` 为准。 diff --git a/docs/README.md b/docs/README.md index 7c4f180..056265c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,10 @@ 本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。 +当前文档基线为 2026-09-05：第一阶段和第二阶段 A～F 工程范围已经合并到 `main`，当前可运行形态仍为 Vue/Vite Web 前端与 FastAPI AI Core。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 尚未接入。 + +仓库入口文档：[项目 README](../README.md)、[前端 README](../frontend/README.md)、[后端 README](../backend/README.md)。 + ## 目录分类 | 目录 | 内容 | 适用场景 | @@ -29,7 +33,7 @@ ## development：开发说明 - [多模态管线与模型运行开发说明](development/多模态管线与模型运行开发说明.md) - +- [阶段 F 收尾验收记录](development/阶段F收尾验收记录.md) - [AI Core 与 Agent Core 开发说明](development/AI-Core与Agent-Core开发说明.md) - [Knowledge 与 Retrieval Core 开发说明](development/Knowledge与Retrieval-Core开发说明.md) - [Benchmark 开发说明](development/Benchmark开发说明.md) diff --git a/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md b/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md index ce7ce33..e53323a 100644 --- a/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md +++ b/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md @@ -5,7 +5,7 @@ > 适用范围：桌面客户端、本地知识库、RAG、Agent、Skill、多模型接入、多模态处理与可选云同步 > 目标读者：前端、Rust 桌面端、Python AI Core、算法、测试与后续接手项目的开发成员 -> 实施状态更新：2026-09-04。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段已完成 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 已完成。阶段 E 已完成 Responses/Anthropic 协议、国内 logo 预设、Provider 配置恢复和 Embedding/转写/声纹 API 路由；本地语音模型仍为阶段 F 接口预留。RAG Benchmark 检索评测（Dataset 加载、异步运行、SSE 进度、指标聚合与报告）已完成，Agent Benchmark 暂缓。后续继续接入真实音频处理、文档导出、主题包、Trace 可视化、Mermaid 和函数图像。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统和 Sync Server 仍未实现。 +> 实施状态更新：2026-09-05。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段及第二阶段 A～F 工程范围已经合并到 `main`：Vue Web 联调前端、FastAPI、真实单 Vault、Knowledge/Retrieval、知识库 Chat、Agent/Tool/Permission、Skill/Plugin、MCP 配置与调用、Provider 多协议与国内 logo 预设、RAG Benchmark、本地 Embedding、音频转写、片段级声纹聚类、CPU/CUDA 运行管理及用量诊断均已实现。当前生产 Embedding 使用固定 revision 的 Bekko A8M，Granite 97M Multilingual r2 可选；音频本地链路使用 Qwen3-ASR-0.6B 与 ERes2NetV2。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 仍未实现；逐字强制对齐、重叠语音分离及带标注长音频质量验收尚未完成。 --- @@ -47,17 +47,17 @@ | 元数据 | SQLite | 笔记元数据、Block、标签、会话、Trace、任务、索引状态 | | 全文检索 | SQLite FTS5 | 关键词、标题、术语、标签等文本检索 | | 向量检索 | sqlite-vec + VectorStore | 本地语义检索 | -| Embedding | 可插拔 EmbeddingProvider，默认本地 BGE-M3 类模型 | 为 Note Block 生成向量 | -| Reranker | BGE reranker 类 Cross-Encoder | 对候选检索结果进行精排 | +| Embedding | 可插拔 EmbeddingProvider；默认 Bekko A8M，可选 Granite 97M Multilingual r2 | 为 Note Block 生成 384 维向量，并按模型空间隔离索引 | +| Reranker | 当前 `LexicalReranker`；保留 `RerankerProvider` 替换边界 | 对 RRF 候选进行词面重叠与原始分数加权精排 | | 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 | 可选音频分析能力 | +| ASR | Qwen3-ASR-0.6B | 本地音频转写与语言识别，返回片段级时间边界 | +| 声纹匹配与片段聚类 | ERes2NetV2 中文声纹模型 | 两段音频相似度与转写片段 speaker 聚类 | +| 情感识别 | Provider 接口预留，尚未选择运行模型 | 后续可选音频分析能力 | | 文档导出 | Document AST + Exporter Adapter | Markdown 到 HTML、PDF、DOCX，并保留图表、公式和代码块 | | 密钥存储 | 当前 Fernet 开发存储；目标 Tauri Stronghold | Web 联调期避免明文落盘，桌面集成后保存模型 API Key 和同步凭证 | | 云同步 | 独立 Sync Server：FastAPI + PostgreSQL + S3/MinIO | 可选自托管，多设备 Vault 同步、版本管理和设备管理 | @@ -675,13 +675,15 @@ class EmbeddingProvider(Protocol): async def embed_query(self, query: str) -> list[float]: ... ``` -目标默认配置使用本地 BGE-M3 类模型。当前第一阶段实现是 128 维 `HashEmbeddingProvider`，只用于离线跑通向量存储、索引更新和 Hybrid 链路，不代表真实语义召回质量。第二阶段接入真实 Embedding 时继续实现相同接口，上层 Retrieval Core 不依赖具体模型运行时。 +生产默认配置使用 `hotchpotch/bekko-embedding-v1-a8m`，可选 `ibm-granite/granite-embedding-97m-multilingual-r2`，两者均输出 384 维向量。模型权重使用代码目录中审阅过的固定 revision，下载后校验，推理阶段离线读取。`HashEmbeddingProvider` 仅供测试显式注入，不进入生产检索回退。 + +Embedding 支持 Provider API 与本地模型路由：配置可用 API 时优先调用，响应失败或无效时回退本地模型；未配置 API 时直接使用本地模型；`local_only` 禁止远程调用。索引和查询冻结同一份模型与设备配置，并记录实际来源和回退原因。 索引记录需要保存 embedding model id、模型版本、向量维度和归一化方式。用户更换模型或任一索引兼容字段变化后，索引服务必须将旧向量标记为不可用并要求重建，禁止把不同模型生成的向量写入同一索引空间。 ### 9.5 RRF 与 Reranker -FTS5 和 Vector Search 分别产生候选集合，经 RRF 进行排名融合。融合后的候选交给 BGE reranker 类 Cross-Encoder 进行精排。 +FTS5 和 Vector Search 分别产生候选集合，经 RRF 进行排名融合。当前 `LexicalReranker` 使用词面重叠和归一化原始分数做确定性精排；`RerankerProvider` 接口保留后续替换 Cross-Encoder 的边界，当前阶段没有随本地模型运行环境安装独立 Reranker 权重。 初始参数可以采用： @@ -1268,7 +1270,7 @@ enabled → 返回连接测试结果 ``` -当前设置页已经提供 OpenAI、DeepSeek 与 Ollama 预设，保存后通过 `/api/providers/{provider_id}/models` 自动发现模型。Credential API 只返回配置状态，不提供任何明文读取接口。 +当前设置页提供 OpenAI、DeepSeek、通义千问、Kimi、智谱、豆包、腾讯混元、百度千帆、MiniMax、阶跃星辰、硅基流动和 Ollama 等带 logo 预设，也支持自定义兼容服务。保存后通过 `/api/providers/{provider_id}/models` 自动发现模型；聊天、Embedding、转写和声纹能力可独立绑定。Credential API 只返回配置状态，不提供任何明文读取接口。 日志中不记录完整 API Key。请求异常信息在进入前端前过滤 Authorization Header 和密钥片段。 @@ -1282,16 +1284,19 @@ enabled ```mermaid flowchart LR - A["Audio"] --> D["pyannote.audio"] - D --> S["Speaker Segments"] - S --> W["faster-whisper"] - W --> T["Timestamped Transcript"] + A["Audio"] --> X["PyAV Decode · 16 kHz Mono"] + X --> V["Energy Segmentation"] + V --> W["Qwen3-ASR-0.6B"] + V --> S["ERes2NetV2 Embeddings"] + W --> T["Segment Transcript"] + S --> SC["Speaker Clustering"] + SC --> T T --> C["Content Structuring"] C --> M["Markdown Note"] M --> I["Index Pipeline"] ``` -pyannote.audio 生成说话人区间；faster-whisper 对各区间进行转写。最终 Transcript 至少包含： +PyAV 将音轨解码为 16 kHz 单声道，能量分段后由 Qwen3-ASR-0.6B 转写；ERes2NetV2 为片段提取 192 维声纹并按相似度聚类。最终 Transcript 至少包含： ```text speaker @@ -1317,7 +1322,9 @@ status error ``` -`pyannote.audio` 和 `faster-whisper` 通过独立 Adapter 加载，模型下载、设备选择、精度、批量大小和缓存目录由配置管理。缺少说话人模型时可以只返回时间戳转写，但必须明确标记 diarization 不可用；模型失败不能生成伪造的 completed 结果。 +本地模型由独立运行环境和子进程按需加载，模型下载、固定 revision、设备、超时、内存预算和缓存目录由配置管理。转写与声纹也可以绑定 Provider API；API 无配置或返回无效时回退本地，`local_only` 请求禁止远程调用。缺少声纹模型时只能返回没有 speaker 的片段并明确标记 diarization 不可用，模型失败不能生成伪造的 completed 结果。 + +当前时间信息为能量分段产生的片段级边界，不是逐字强制对齐。ERes2NetV2 聚类不能处理同一片段内多人或重叠发言，因此不将当前能力描述为完整说话人分离。 ### 14.2 OCR @@ -1325,9 +1332,9 @@ OCR 作为 Media Pipeline 的输入适配能力，用于图片笔记、白板照 OCR 引擎在当前技术栈中尚未固定，调用接口先定义为 `OCRProvider`，具体实现完成 PoC 后确定。 -### 14.3 emotion2vec +### 14.3 音频情感分析 -emotion2vec 作为音频扩展分析模块。输出可以附加到音频段元数据，不参与核心 RAG 索引和 Agent 启动流程。 +音频情感分析保留 Provider/Adapter 扩展位置，当前阶段未选定或集成本地运行模型。未来输出可以附加到片段元数据，但不参与核心 RAG 索引和 Agent 启动流程。 ### 14.4 Document AST 与多格式导出 @@ -1630,7 +1637,7 @@ Agent 中间运行状态 设备级性能配置 ``` -例如 Client A 使用本地 BGE-M3，Client B 使用另一种 Embedding Provider。服务器只同步 Markdown。Client B 收到文件后按照自己的 Embedding 配置生成向量，并写入本机 VectorStore。 +例如 Client A 使用本地 Bekko A8M，Client B 使用 Granite 或 API Embedding Provider。服务器只同步 Markdown。Client B 收到文件后按照自己的 Embedding 配置生成向量，并写入本机对应的隔离向量空间。 ### 16.5 多设备同步流程 @@ -2010,7 +2017,7 @@ SQLite Git ``` -Rust Toolchain 与 Tauri CLI 只在桌面容器阶段安装。当前轻量 Embedding/Reranker 不要求 CUDA；接入 faster-whisper、pyannote.audio 或真实本地模型时再按所选运行时增加 CPU/GPU 依赖。 +Rust Toolchain 与 Tauri CLI 只在桌面容器阶段安装。本地模型依赖与 API 环境分离，默认使用 CPU；Windows 可以通过设置页或 `backend/scripts/install-model-runtime.ps1 -Device cuda` 显式安装 PyTorch 2.9.1 cu128 运行组件。CPU 与 CUDA 环境可并存，安装脚本不安装或修改 NVIDIA 驱动，也不要求 vLLM 或 FlashAttention。 ### 19.2 本地开发 @@ -2233,10 +2240,11 @@ Agent Runtime ```text Audio -→ pyannote.audio -→ Speaker Segments -→ faster-whisper -→ Timestamped Transcript +→ PyAV 解码为 16 kHz 单声道 +→ 能量分段 +→ Qwen3-ASR-0.6B 片段转写 +→ ERes2NetV2 声纹提取与片段聚类 +→ 片段级时间戳 Transcript → Content Structuring → Markdown → Note Core @@ -2333,14 +2341,17 @@ Markdown Workspace 第一阶段 Plugin Runtime 已完成安装、启用、停用、权限和声明式 Tool 注册，建立 Skill 调用 Plugin Tool 的基础链路。Command、Settings 和 MCP 执行不计入第一阶段完成项。 -截至 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 召回质量不属于该测试结论。 +截至 2026-09-05，上述第一阶段链路和第二阶段 A～F 工程范围均已合并。除 Workspace、Agent Trace、MCP、Plugin Command/Settings 外，当前还包含 Provider 多协议与国内预设、真实 Embedding 路由与隔离向量空间、RAG Benchmark、Qwen3-ASR 转写、ERes2NetV2 声纹匹配与片段聚类、CPU/CUDA 组件管理、请求 JSON、Token/音频用量及运行诊断。阶段 F 合并验证基线为后端 559 项测试、前端 103 项测试、TypeScript 类型检查及生产构建通过。 + +Bekko A8M 与 Granite 97M Multilingual r2 在 8 篇短文、6 条改写查询的小样本冒烟中均得到 Hit@1、Recall@5、MRR 1.0；该结果只证明中文检索闭环可运行，不足以区分质量优劣。CPU/CUDA 已完成短音频到知识库检索的真实闭环；带标注课程长音频的 WER/CER、DER、重叠语音和吞吐仍需专项验收。 第二阶段在既有 Contract 上接入： ```text Multimodal -├── faster-whisper -└── pyannote.audio +├── Qwen3-ASR-0.6B +├── ERes2NetV2 片段声纹聚类 +└── API → 本地模型回退路由 Extension / Model ├── MCP Bridge（stdio 首版已实现） @@ -2365,7 +2376,7 @@ Frontend Extension └── Plugin Settings UI ``` -上述列表描述第二阶段技术范围，其中 stdio MCP Bridge、Plugin Command Contribution 和 Plugin Settings Contribution 后端 Contract 已实现，其余能力以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。 +上述列表描述第二阶段技术范围。多模态、MCP Bridge、Plugin Command/Settings、RAG Benchmark 和 Provider 增强已经实现；Agent Benchmark、内容导出、Mermaid/函数图像完整编辑导出及社区主题包仍以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。 第三阶段处理： @@ -2417,11 +2428,11 @@ Sync Server 按独立服务开发和部署，不进入桌面客户端核心启 ## 25. 当前技术基线摘要 -目标桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript；当前可运行形态是 Vue/Vite Web 前端加 FastAPI。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 已管理笔记元数据、全文索引、向量索引、任务及 Agent Trace；Provider/Extension Registry 当前仍为内存实现。 +目标桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript；当前可运行形态是 Vue/Vite Web 前端加 FastAPI。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 已管理笔记元数据、全文索引、向量索引、搜索历史、Provider 配置、任务、多模态记录及 Agent Trace；MCP Server 配置持久化到后端数据目录，运行时 Tool/Extension Registry 在进程启动后按持久配置重建。 -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 配置。 +Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 通过 FTS5、sqlite-vec、RRF 和 `LexicalReranker` 运行混合检索，生产 Embedding 默认使用 Bekko A8M、可选 Granite 97M Multilingual r2 或 Provider API，并按模型空间隔离索引；`HashEmbeddingProvider` 仅用于测试。RAG Benchmark 已接入版本化 Dataset、异步运行、SSE 进度、指标和报告。Agent Runtime 使用 Tool Registry 操作知识库和任务，并持久化可供前端和 Benchmark 共用的 Agent Trace Contract；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置。 -当前 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。 +当前 Plugin Runtime 支持 Manifest、生命周期、声明式白名单 Tool Contribution、Plugin Command 与 Plugin Settings/Secret，并已通过 MCP Bridge 接入 stdio、Streamable HTTP 和旧 SSE Server。Provider Adapter 已实现 OpenAI Chat/OpenAI-Compatible、OpenAI Responses、Anthropic Messages 与 Ollama，并支持模型发现、独立凭据和受限自定义请求 JSON。多模态本地链路使用 PyAV、Qwen3-ASR-0.6B 和 ERes2NetV2，默认 CPU、CUDA 显式选装；API 无配置或无效时回退本地模型。当前声纹聚类只处理片段，不等同于完整说话人分离。 第二阶段内容输出以 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/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..55acd8c --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,77 @@ +# NotesAgent Frontend + +NotesAgent Frontend 是基于 Vue 3、TypeScript、Vite、Pinia、Vue Router、Milkdown 和 CodeMirror 6 的 Web 联调前端。当前页面调用 FastAPI 真实接口，不使用业务 Mock 作为运行时回退；测试文件中的 mock 只用于隔离单元和组件测试。 + +## 初始化与运行 + +```powershell +pnpm install +pnpm dev +``` + +开发地址为 。Vite 将 `/api` 和 `/health` 转发到 ，因此联调前需要先启动后端。 + +## 页面与能力 + +| 路由 | 当前能力 | +| --- | --- | +| `/`、`/workspace` | 选择当前 Vault、浏览目录、编辑和保存 Markdown | +| `/search` | 全文、向量和混合检索；从后端读取并清空搜索历史 | +| `/chat` | 流式 AI 对话、知识库上下文与 Citation | +| `/agent/runs/:runId?` | 创建 Agent 运行，查看可恢复 Trace 与 Tool/Permission 事件 | +| `/media` | 上传音频、创建/取消/重试转写、修订结果并生成知识库笔记 | +| `/tasks` | 管理用户、笔记和 Agent 产生的任务 | +| `/extensions/skills` | Skill 安装、启停与配置 | +| `/extensions/mcp` | stdio、Streamable HTTP、旧 SSE Server 配置与工具发现 | +| `/extensions/plugins` | Plugin Host、Command、Settings、Secret 与 MCP 状态 | +| `/themes` | 内置 Design Token 主题和编辑器显示偏好 | +| `/settings` | Provider、模型路由、本地模型、CPU/CUDA 组件、请求 JSON、用量与诊断 | + +## 技术结构 + +| 目录 | 职责 | +| --- | --- | +| `src/features` | 按页面和业务域组织的 Vue 组件 | +| `src/stores` | Pinia 状态与页面编排 | +| `src/services` | FastAPI HTTP/SSE 客户端和 DTO 转换 | +| `src/contracts` | 与后端契约对应的 TypeScript 类型 | +| `src/components` | 应用壳、命令面板和共享组件 | +| `src/utils` | Markdown 清洗、Shiki 高亮等纯工具 | +| `src/styles` | Design Token、布局、主题和动效 | + +编辑器使用 Milkdown/Crepe 与 CodeMirror 6；Markdown 展示使用 marked、DOMPurify 和 Shiki。Provider logo 位于 `src/assets/providers`，授权与来源说明随目录保存。 + +## 数据边界 + +- 笔记、附件、搜索历史、会话、任务、Trace、模型配置和多模态结果都通过 FastAPI 读写。 +- API Key 只存在于密码输入和提交请求期间，不进入 Pinia 或 `localStorage`。 +- 页面内存可以保存尚未提交的临时状态；后端已经接收的任务和结果由 SQLite/Vault 持久化。 +- 主题、编辑器偏好、侧栏状态和最近 Vault 路径目前保存在浏览器 `localStorage`；它们是设备界面偏好，不作为笔记或模型业务数据。Tauri 集成时由桌面配置存储接管。 +- 前端不直接访问 SQLite，不拼装第三方模型协议；Provider Adapter 和请求覆盖规则由后端执行。 +- 后端不可用时页面显示连接或操作错误，不生成演示数据替代真实结果。 + +当前仍运行在 Web/Vite 环境。后续 Tauri 集成将复用现有 Service/Contract 边界，并由 Rust Host 接管窗口、Vault 选择、Sidecar、Stronghold 和生产沙箱。 + +## 模型设置 + +设置页支持带 logo 的提供商预设、模型发现、聊天/Embedding/转写/声纹能力绑定，以及按 capability、model 和 stream 条件匹配的自定义请求 JSON。请求预览不联网；“发送测试推理请求”使用当前草稿和已保存凭据执行真实短请求。 + +本地模型页显示固定 revision、许可、下载状态和实际磁盘占用。CPU 是默认运行方式；Windows 可从页面安装独立 CUDA 12.8 组件，安装过程不修改显卡驱动。当前模型选型详见[多模态管线与模型运行](../docs/development/多模态管线与模型运行开发说明.md)。 + +## 测试与构建 + +```powershell +pnpm test +pnpm type-check +pnpm build +``` + +阶段 F 合并基线为 29 个测试文件、103 项测试通过，TypeScript 类型检查与 Vite 生产构建通过；构建仍有既有大 bundle 提示。产物位于 `dist`，不提交 Git。 + +## 开发约定 + +- 依赖统一使用 pnpm 管理，不混用 npm 或 yarn。 +- 新接口先更新 `src/contracts` 与 `src/services`，页面和 Store 不直接散落 `fetch` 协议细节。 +- 异步页面需要处理加载、空数据、后端错误、重复提交和迟到响应。 +- 功能行为或契约变化时，同一提交同步更新测试和相关文档。 +- 页面需求见[前端页面需求说明](../docs/contracts/前端页面需求说明-开发版.md)，后端行为以运行时 `/openapi.json` 为准。