docs: 重组文档目录并补充CI/CD细则

2026-09-01 09:55:40 +08:00
parent 49dbacb296
commit a5b709a46f
23 changed files with 263 additions and 37 deletions
@@ -0,0 +1,345 @@
+# AI Core 与 Agent Core 开发说明
+
+> 本文档用于团队开发和模块联调，记录当前已经落地的核心边界与使用方式。
+
+> 更新日期：2026-09-01。第一阶段 AI Core、Agent Core、Extension Core 和 Model Core 主链路已经完成；第二阶段 Agent Trace 持久化和可恢复 SSE 已落地，后端当前回归基线为 80 项测试通过。
+
+## 当前实现
+
+当前已经建立第一条可运行链路：
+
+```text
+FastAPI
+→ Provider Registry
+→ Agent Runtime
+→ Permission Manager
+→ Tool Registry
+→ Skill Runtime / Plugin Runtime
+→ Agent Trace / SSE
+```
+
+对应代码：
+
+```text
+backend/app/
+├── providers/
+│   ├── base.py          Provider Protocol 与统一 Turn
+│   ├── registry.py      Provider 注册、发现、模型列表和连接测试
+│   └── mock.py          离线开发 Provider
+├── agent/
+│   ├── runtime.py       Agent Loop、限制、取消、Trace 和 SSE
+│   ├── trace_repository.py Run/Event SQLite 持久化、分页、摘要与脱敏
+│   ├── tools.py         Tool 注册、参数校验、隔离执行和结果转换
+│   ├── permissions.py   权限策略、确认请求和会话授权
+│   └── builtin_tools.py 无副作用的内置开发 Tool
+├── extensions/
+│   └── runtime.py       Skill/Plugin Manifest、生命周期、依赖与 Tool Contribution
+└── container.py         AI Core 依赖组装
+
+backend/extensions/
+├── skills/knowledge-assistant/   内置知识库 Skill
+└── plugins/text-tools/           内置示例 Plugin
+```
+
+Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider 业务逻辑。
+
+## 模块边界
+
+当前实现属于范涵宇负责的 AI Core / Agent Core：
+
+- Provider 抽象与注册；
+- Agent Run 生命周期；
+- Tool Registry；
+- Tool 参数校验与执行隔离；
+- Permission；
+- Step、Timeout、Token Budget、取消；
+- Tool 并发上限与 run 级网络权限；
+- SQLite Trace、分页快照与可恢复 SSE；
+- Skill Manifest、Prompt、Tool/Permission/模型能力解析；
+- Plugin Manifest、生命周期和 Tool Contribution；
+- Skill 调用内置 Tool 与 Plugin Tool；
+- 公共 Contract 和 API 接入。
+
+以下内容保持接口，不在本模块实现：
+
+- Note、NoteBlock、Markdown Parser：由 Knowledge Core 提供；
+- FTS5、Vector、RRF、Reranker、Citation：由 Retrieval Core 提供；
+- 文件系统和 API Key 明文读取：由 Rust Host 提供；
+- MCP Plugin Host、Frontend Extension Slot：按技术基线放在第二阶段实现。
+
+## Provider
+
+默认注册离线 Provider：
+
+```text
+provider_id = mock
+model       = mock-1
+```
+
+它支持：
+
+```text
+chat
+tool_calling
+streaming
+```
+
+普通 Chat 请求：
+
+```json
+{
+  "provider_id": "mock",
+  "model": "mock-1",
+  "messages": [
+    {"role": "user", "content": "hello"}
+  ]
+}
+```
+
+`POST /api/chat` 返回 ModelEvent SSE。OpenAI-Compatible Adapter 直接消费上游 SSE，Ollama Adapter 直接消费 JSONL，`TextDelta` 是真实增量内容，不再等待整段回答完成。
+
+另外已经实现以下可配置 Adapter：
+
+```text
+openai_chat / openai_compatible
+ollama
+```
+
+创建 Ollama Provider：
+
+```json
+{
+  "provider_type": "ollama",
+  "name": "Local Ollama",
+  "base_url": "http://127.0.0.1:11434",
+  "default_model": "qwen3:latest"
+}
+```
+
+创建 OpenAI-Compatible Provider：
+
+```json
+{
+  "provider_type": "openai_compatible",
+  "name": "OpenAI Compatible",
+  "base_url": "https://api.openai.com/v1",
+  "default_model": "<model>",
+  "credential_id": "openai-main"
+}
+```
+
+凭证 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：
+
+```json
+{
+  "input": "hello",
+  "provider_id": "mock",
+  "model": "mock-1",
+  "max_steps": 10
+}
+```
+
+请求：
+
+```text
+POST /api/agent/runs
+```
+
+创建后通过以下接口读取状态和事件：
+
+```text
+GET /api/agent/runs/{run_id}
+GET /api/agent/runs/{run_id}/events
+GET /api/agent/runs/{run_id}/trace?after_sequence=-1&limit=200
+POST /api/agent/runs/{run_id}/cancel
+```
+
+Run 与 AgentEvent 已写入 SQLite，`run_id + sequence` 是幂等键。SSE 每帧包含 `id: sequence`；客户端可以通过 `Last-Event-ID` 请求头或 `after_sequence` 查询参数恢复缺失事件。Trace API 返回平铺事件、下一游标、分页状态、模型/工具调用统计、耗时、Token Usage 和创建 Run 时的配置快照，不负责生成前端树形布局。
+
+运行时内存仍只保留最近 2000 个事件用于实时订阅，完整 Trace 以 SQLite 为准。AI Core 重启后，已经终止的 Run 可以继续查询和回放；重启前未终止的 Run 会收束为 `AGENT_PROCESS_RESTARTED`，避免永久停在 `running`。API Key、Authorization、Password、Secret、常见 `sk-`/Bearer 值在入库前脱敏，超长字符串和集合会截断。
+
+## Tool Calling
+
+当前注册以下内置 Tool：
+
+```text
+system.echo
+math.add
+notes.search
+rag.search
+notes.read
+notes.create
+notes.update
+notes.list
+notes.move
+tasks.create
+tasks.update
+tasks.list
+attachments.read
+audio.transcribe
+```
+
+Mock Provider 使用下面的开发语法产生 Tool Call：
+
+```text
+/tool system.echo {"text":"hello tool"}
+/tool math.add {"left":1,"right":2}
+```
+
+Agent Run 需要显式声明 `allowed_tools`：
+
+```json
+{
+  "input": "/tool math.add {\"left\":1,\"right\":2}",
+  "provider_id": "mock",
+  "model": "mock-1",
+  "allowed_tools": ["math.add"]
+}
+```
+
+Tool 参数由独立 Pydantic Model 再次校验。Tool 的异常、非法参数、超时和权限拒绝统一转换为 `ToolResult`，不会直接打断 API 进程。
+
+`notes.search` / `rag.search` 返回的 Citation 会由 Agent Runtime 收集到 `AgentRun.citations`，并产生 `Citation` Trace Event。Note 写操作调用 `note_service`，检索调用 Retrieval Engine，不直接访问 SQLite。
+
+## Permission
+
+Permission Policy 当前支持：
+
+```text
+allow
+confirm
+deny
+```
+
+需要确认时，Agent 状态进入 `waiting_permission`，并发出 `PermissionRequired` 事件。前端使用：
+
+```text
+POST /api/agent/runs/{run_id}/permissions/{request_id}
+```
+
+提交以下决策之一：
+
+```json
+{"decision":"allow_once"}
+{"decision":"allow_session"}
+{"decision":"deny"}
+```
+
+默认需要确认的高影响权限包括 `notes.write`、`notes.delete`、`tasks.write`、`network.request` 和 `secrets.use`。权限命名空间采用白名单，未知权限默认拒绝。
+
+## Knowledge / Retrieval 接入
+
+Knowledge Core 与 Retrieval Core 已通过 Tool Registry 接入 Agent。Agent Runtime 仍只依赖 Tool Contract，不直接依赖具体服务：
+
+```python
+tool_registry.register(
+    definition=tool_definition,
+    arguments_model=arguments_model,
+    executor=executor,
+)
+```
+
+第一批已经接入：
+
+```text
+notes.search
+notes.read
+notes.create
+notes.update
+notes.list
+rag.search
+```
+
+写操作 Executor 调用 Knowledge Core Service，不直接访问 SQLite；检索 Executor 调用 Retrieval Core Service，不直接拼接 FTS5 或 sqlite-vec SQL。
+
+## Extension Core
+
+### Skill Runtime
+
+Skill Package 由 `skill.yaml` 和可选 `prompt.md` 组成。安装时使用 Pydantic 校验 Manifest，并解析：
+
+```text
+permissions
+tools
+retrieval
+model.required_capabilities
+```
+
+Skill 启用前检查 Tool 是否已注册、Tool 所需权限是否已在 Manifest 声明。创建 Agent Run 时，Skill Runtime 生成 Agent Configuration，注入 System Prompt、允许的 Tool、权限和 Retrieval Config。模型缺少 `chat`、`tool_calling` 等必要 Capability 时拒绝启动。
+
+生命周期接口：
+
+```text
+GET    /api/skills
+POST   /api/skills/install
+GET    /api/skills/{skill_id}
+POST   /api/skills/{skill_id}/enable
+POST   /api/skills/{skill_id}/disable
+DELETE /api/skills/{skill_id}
+```
+
+### Plugin Runtime
+
+第一阶段 Plugin Runtime 完成 Manifest 校验、安装、启用、停用、卸载和 Tool Contribution。第三方代码不会直接 import 到 AI Core；当前 Declarative Plugin Host 只执行宿主实现的白名单 handler，MCP Host 留到第二阶段。
+
+启用 Plugin 时将 Tool 注册到统一 Tool Registry，并标记 `source=plugin`；停用或异常时注销 Tool。启用中的 Skill 依赖某 Plugin Tool 时，Plugin 不能直接卸载。
+
+生命周期接口：
+
+```text
+GET    /api/plugins
+POST   /api/plugins/install
+GET    /api/plugins/{plugin_id}
+POST   /api/plugins/{plugin_id}/enable
+POST   /api/plugins/{plugin_id}/disable
+PUT    /api/plugins/{plugin_id}/permissions
+DELETE /api/plugins/{plugin_id}
+```
+
+Plugin Manifest 中的权限只是声明，不代表已经授权。带权限的 Plugin 安装后进入 `permission_required`，Host 必须通过权限接口记录用户授权，之后才能启用。JSON Schema 在安装阶段校验，Tool 调用时再次校验实际参数。
+
+内置示例 `text-tools` 注册 `text.uppercase`。内置 `knowledge-assistant` Skill 同时声明 `notes.search` 和 `text.uppercase`，用于验证完整链路：
+
+```text
+Skill Manifest
+→ Agent Configuration
+→ Tool Registry
+→ Plugin Tool
+→ Tool Result
+→ Agent Loop
+```
+
+## 当前限制与下一步
+
+前端智能体页面已经完成中文联调：运行状态、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；后续增加按保留策略归档和 Benchmark 引用保护。
+- Permission 已有核心等待/恢复机制，前端确认 UI 已完成联调和中文展示。
+- Task 已持久化到 SQLite；Attachment Tool 读取 Host 管理目录中的 UTF-8 文件。
+- `audio.transcribe` 当前消费 Host 预生成的 transcript；faster-whisper 与说话人分离仍按技术基线在第二阶段接入。
+- Extension 安装记录暂存内存；后续接入持久化 Registry 与版本升级流程。
+- 当前 Plugin Host 只支持内置声明式白名单 handler；MCP Bridge、独立进程健康检查与 UI Contribution 在第二阶段实现。
@@ -0,0 +1,235 @@
+# Knowledge Core 与 Retrieval Core 开发说明
+
+> 本文档用于团队开发和模块联调，记录 Knowledge Core / Retrieval Core 已经落地的
+> 模块边界、数据模型、接口与使用方式，对应分工表中的杨星萱。
+
+> 更新日期：2026-09-01。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 80 项测试通过。
+
+## 当前实现
+
+当前已经建立第一条可运行的检索链路：
+
+```text
+Markdown Vault
+→ Markdown Parser（Block 切分 / heading_path / offset）
+→ SQLite（notes / blocks / FTS5）+ sqlite-vec（vec_blocks）
+→ FTS5(BM25) + Vector(cosine) 双路召回
+→ RRF 融合 → Reranker 精排 → Metadata Filter → 分页
+→ Citation + Snippet
+```
+
+对应代码：
+
+```text
+backend/app/
+├── constants.py          EMBEDDING_DIM = 128
+├── config.py             Settings（data_dir / db_path / vault_path）
+├── textutils.py          分词、FTS 查询串、摘要片段
+├── repository.py         notes / blocks / blocks_fts 读写（领域记录层）
+├── database/
+│   ├── db.py             SQLite 连接 + 事务 + 加载 sqlite-vec
+│   └── migrations.py     轻量迁移（建 notes / blocks / blocks_fts / vec_blocks）
+├── knowledge/
+│   └── parser.py         Markdown → ParsedNote / NoteBlock
+├── retrieval/
+│   ├── embedding.py      EmbeddingProvider 接口 + HashEmbeddingProvider
+│   ├── reranker.py       RerankerProvider 接口 + LexicalReranker
+│   ├── vectorstore.py    VectorStore 接口 + SqliteVecStore
+│   ├── hybrid.py         RRF 融合、分数归一化
+│   └── engine.py         RetrievalEngine（编排检索全流程）
+└── services/
+    ├── note_service.py   Note CRUD + 索引编排
+    └── index_service.py  全量重建、索引状态、任务查询
+```
+
+Router（`backend/app/routes.py`）只负责 HTTP 与错误转换；`/api/notes`、`/api/search`、
+`/api/index/*` 已接入上述服务，其余端点仍由对应模块负责。
+
+## 模块边界
+
+本模块负责（杨星萱）：
+
+- Markdown Vault、Note / NoteBlock 数据模型与解析；
+- SQLite 元数据、FTS5 全文检索、sqlite-vec 向量检索；
+- Embedding、Hybrid RAG、RRF、Reranker、Metadata Filter；
+- Citation 与笔记定位；
+- 检索测试数据。
+
+以下内容保持接口，不在本模块实现：
+
+- Agent Runtime、Tool Registry、Permission：由 Agent Core 提供；
+- Provider Adapter、多模型协议：由 Model Core 提供；
+- Skill / Plugin 生命周期：由 Extension Core 提供；
+- 文件系统与 API Key 明文读取：由 Rust Host 提供。
+
+## 数据模型与稳定 ID
+
+- 笔记元数据存 `notes` 表；正文切成 Block 存 `blocks` 表；`blocks_fts` 是 FTS5 虚拟表；
+  `vec_blocks` 是 sqlite-vec 的 `vec0` 虚拟表。
+- 稳定 ID（内容/路径不变则 ID 不变）：
+
+```text
+note_id  = "note_" + sha256(rel_path)[:16]
+block_id = "blk_"  + sha256(note_id | heading_path | content)[:16]
+citation_id = "cit_" + block_id
+```
+
+> 注意：`note_id` 是稳定业务 ID；移动接口会保留原 ID，文件路径不能代替业务实体 ID。
+
+每个 Block 记录 `heading_path`（章节路径）、`start_offset` / `end_offset`（相对原文的
+字符偏移，用于前端跳转高亮）、`content_hash`、`token_count`。
+
+## 分层依赖
+
+按团队约定，依赖方向为：
+
+```text
+Router（HTTP/错误转换）
+  → Service（note_service / index_service 编排）
+    → Repository（notes/blocks/FTS5 访问）      ← 只在此层访问 SQLite
+    → Retrieval Infra（embedding/reranker/vectorstore）  ← vec0 只在 vectorstore 层访问
+```
+
+- 检索 Executor 调用 `RetrievalEngine`，不直接拼接 FTS5 或 sqlite-vec SQL；
+- 向量实现只在 `retrieval/vectorstore.py`；DB 访问只在 `repository.py`。
+
+## 分词与中文检索
+
+FTS5 默认 `unicode61` 不切分中文，因此统一预分词：ASCII 单词 + CJK 单字 + CJK 相邻双字。
+写入与查询走同一套拆分（`textutils.segment` / `textutils.match_query`），实现中文子串/词级召回。
+
+## Embedding / Reranker（轻量实现，接口可替换）
+
+当前是「统一接口 + 轻量实现」，后续接入真实模型时替换实例即可，不改变上层调用：
+
+- `EmbeddingProvider`（`embed_documents` / `embed_query`）→ `HashEmbeddingProvider`：
+  确定性特征哈希 + L2 归一化，`dim = 128`，`model_id = "hash-v1"`。
+- `RerankerProvider`（`rerank`）→ `LexicalReranker`：分数归一化 + 词重叠加权，
+  `model_id = "lexical-v1"`。
+- `VectorStore`（`upsert` / `delete` / `search` / `clear`）→ `SqliteVecStore`：
+  sqlite-vec `vec0`，相似度取余弦 `score = 1 - distance² / 2`。
+
+## 检索流程
+
+`RetrievalEngine.search(request)`：
+
+1. 按 `mode` 收集候选：`fts` / `vector` 各取 Top `CANDIDATE_POOL = 50`；
+2. `hybrid` 用 RRF（`k = 60`）融合两路排序；
+3. Metadata Filter：`folders` / `note_ids` / `tags` / 时间范围；
+4. `hybrid` 再经 Reranker 精排，其余模式按分数排序；
+5. 分数归一化 → 分页 → 组装 `Citation` 与 `Snippet`。
+
+模块级单例 `engine = RetrievalEngine(HashEmbeddingProvider(), LexicalReranker(), SqliteVecStore())`，
+检索入口统一为 `engine.search(request)`。
+
+## 接口清单
+
+### Note
+
+```text
+GET    /api/notes?limit=&offset=&folder=&tag=
+POST   /api/notes
+GET    /api/notes/{note_id}
+PATCH  /api/notes/{note_id}
+DELETE /api/notes/{note_id}
+POST   /api/notes/{note_id}/move   （已实现，保留 note_id）
+```
+
+创建笔记：
+
+```json
+POST /api/notes
+{"title": "Python 基础", "markdown": "# 变量\n\nPython 是动态类型语言。", "folder": "编程", "tags": ["python"]}
+```
+
+### Search
+
+```text
+POST /api/search
+```
+
+```json
+{"query": "向量数据库", "mode": "hybrid", "limit": 10}
+```
+
+`mode` 取 `fts` / `vector` / `hybrid`；可选 `folders` / `note_ids` / `tags` / 时间范围 /
+`include_snippet`。结果项含 `score`、`snippet` 与 `citation`（`citation_id`、`file_path`、
+`heading_path`、`start_offset`、`end_offset`）。
+
+### Index
+
+```text
+GET  /api/index/status
+POST /api/index/rebuild
+GET  /api/index/jobs/{job_id}
+```
+
+重建（MVP 同步执行，直接返回 `completed`）：
+
+```json
+POST /api/index/rebuild
+{"scope": "all"}
+```
+
+## 检索测试数据
+
+样例 Vault 位于 `backend/data/vault/`，覆盖中英文、多级标题、frontmatter、子目录与不同 tags：
+
+```text
+项目说明.md
+编程/Python 基础语法.md
+编程/向量数据库与相似度检索.md
+产品/RAG 检索增强与引用定位.md
+日记/2026-08-27 周会.md
+```
+
+示例查询：
+
+```text
+POST /api/search {"query": "向量数据库", "mode": "hybrid"}   → 命中《向量数据库与相似度检索》
+POST /api/search {"query": "检索", "mode": "fts", "folders": ["产品"]}   → 只返回 产品/ 下笔记
+POST /api/search {"query": "向量", "mode": "hybrid", "tags": ["向量"]}   → 按 tag 过滤
+```
+
+## 测试
+
+```powershell
+cd backend
+uv run pytest -q
+```
+
+当前后端完整测试共 71 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把
+数据目录/DB/Vault 重定向到临时目录，不读写真实 `backend/data`，任何本机状态下结果确定。
+
+## 配置
+
+```text
+APP_DATA_DIR    默认 backend/data
+APP_DB_PATH     默认 backend/data/app.db
+APP_VAULT_PATH  默认 backend/data/vault
+APP_ATTACHMENTS_PATH 默认 backend/data/attachments
+```
+
+运行期生成的 `backend/data/*.db*` 已被 `.gitignore` 忽略，vault 下的 Markdown 测试数据会提交。
+
+## 接入约定（Agent / 其他模块）
+
+Agent 通过注册 Tool 接入本模块，不让 Agent Runtime 直接依赖具体实现：
+
+```text
+notes.search / notes.read / notes.create / notes.update / notes.list / notes.move
+rag.search
+```
+
+- 写操作 Executor 调用 `note_service`，不直接访问 SQLite；
+- 检索 Executor 调用 `engine.search(request)`，不直接拼接 FTS5 或 sqlite-vec SQL。
+
+## 当前限制与下一步
+
+- `move` 接口已实现，移动文件后保持原 `note_id`，同时原子更新 Block、FTS 和向量索引。
+- Citation 的 `start_offset` / `end_offset` 使用 UTF-16 code unit，直接兼容浏览器编辑器。
+- Markdown 分块会识别 fenced code block，不会把代码中的 `#` 注释误判为标题。
+- Embedding / Reranker 为轻量实现，后续替换为真实模型（接口不变）。
+- 小语料下 hybrid 检索召回偏宽（向量 Top-K 覆盖全部 block），可加相关性阈值收紧。
+- 重建为同步 + 全量，后续接入增量索引与异步任务队列。
+- 检索 Benchmark 待建立。
@@ -0,0 +1,124 @@
+# 前端写作体验优化开发说明
+
+> 更新日期：2026-08-30。本文所述优化均已进入当前分支；前端完整回归基线为 14 项测试通过，TypeScript 检查和 Vite 生产构建通过。
+
+## 1. 本次目标
+
+本次优化聚焦笔记写作主流程，不调整后端接口：
+
+- 将界面中的装饰性 Emoji 统一替换为 Element Plus 图标；
+- 将“写作”模式由 Markdown 源码与预览双栏改为单一可视化编辑区；
+- 为写作区增加标题、加粗、斜体、有序列表、无序列表工具栏；
+- 写作页代码块默认展开为可编辑状态；只读 Markdown 区域使用 Shiki 提供亮暗主题高亮。
+
+## 2. 实现说明
+
+### 2.1 图标体系
+
+新增 `AppIcon.vue` 作为轻量图标出口，页面直接传入 `@element-plus/icons-vue` 组件。侧边栏、文件树、Vault 入口、主题按钮、空状态及扩展列表不再使用 Emoji 表达操作含义。
+
+这样处理后，图标尺寸、颜色和主题状态都由 CSS 统一控制，也避免不同系统 Emoji 字体造成的显示差异。
+
+### 2.2 可视化 Markdown 编辑器
+
+写作模式使用 Milkdown Crepe 渲染 Markdown 文档，磁盘中仍保存标准 Markdown 文本。编辑器监听 Markdown 更新并写回 Pinia 状态，继续复用原有自动保存逻辑。
+
+“源码”模式保留为独立模式，便于需要精确编辑 Markdown 的用户使用；写作模式中不再同时展示 Markdown 源码。
+
+编辑器按当前文件路径重新挂载，保证切换文件、切换源码模式后，展示内容与 Store 中的最新 Markdown 一致。
+
+### 2.3 Markdown 工具栏
+
+写作区顶部提供以下基础格式操作：
+
+- H1 至 H6 标题下拉选择，标题默认使用粗体显示；
+- 加粗；
+- 斜体；
+- 有序列表；
+- 无序列表；
+- 12 px 至 32 px 字号选择；
+- 行内代码与代码块；
+- 行内公式与公式块；
+- 链接插入。
+
+标题、加粗、斜体和列表工具调用 Milkdown Command 修改当前选区或块级结构，因此能正确处理光标、选区和嵌套列表。工具栏使用常见的 `H`、`B`、`I`、`1.` 和 `•` 排版符号，减少图标语义歧义。
+
+标准 Markdown 没有字号语法。字号功能仅在用户已选择文本时生效，并将内容写为兼容 Markdown 的内联 HTML：
+
+```markdown
+<span style="font-size: 18px">选中的文本</span>
+```
+
+Milkdown 自定义插件在写作模式中隐藏 HTML 标记，并通过 ProseMirror Decoration 显示实际字号；切换到源码模式时可以直接看到并修改上述 Markdown 内容。
+
+字号栏同时提供预设下拉框和 `8–96 px` 数值输入框。输入数值后按 Enter 或点击“应用”即可写入当前选区。标题下拉框提供“正文”选项，用于将标题恢复为普通段落；正文显式使用正常字重，只有 H1 至 H6 默认加粗。
+
+选中文本后出现的 Crepe 浮动格式栏使用应用正文前景色、实色描边和悬浮强调色，避免亮暗主题下图标对比度不足。
+
+浮动栏由 Crepe Tooltip Provider 挂载，不保证位于 Vue scoped 样式容器内部，因此对比度规则使用全局 `.milkdown-toolbar` 选择器，并通过主题变量适配亮暗模式。顶部格式按钮统一在 `pointerdown` 阶段阻止默认焦点迁移并执行命令，确保点击工具栏时不会丢失编辑器选区。
+
+有序列表与无序列表使用相同尺寸、相同线条结构的经典列表符号，仅通过左侧的数字或圆点区分类型。亮色主题下，表格边框使用更高对比度的文本辅助色，列表序号、圆点及任务图标也改用辅助文本色并增加字重。
+
+编辑器左侧加号打开的块菜单已完成中文本地化：
+
+- “文本”分组包含正文、H1 至 H6、引用和分割线；
+- “列表”分组包含无序列表、有序列表和任务列表；
+- “插入”分组包含图片、代码块、表格和公式块。
+
+代码语言搜索、复制操作、链接编辑及公式确认浮层也统一使用中文文案。
+
+### 2.4 代码块编辑与 Shiki 高亮
+
+代码高亮使用 Shiki 的 JavaScript 正则引擎，并只注册第一阶段常用语言：Markdown、HTML、CSS、JavaScript、TypeScript、JSON、Python、Shell 和 SQL。未知语言回退为 Markdown 语法展示，不阻塞整篇内容渲染。
+
+Shiki 同时生成 `github-light` 与 `github-dark` 两套 CSS 变量。主题页提供“跟随主题 / GitHub Light / GitHub Dark”选项，通过根节点 `data-code-theme` 切换对应变量，无需重新执行高亮。偏好写入 `editor-appearance`，内置主题和后续主题包也可通过 `ThemeConfig.code_theme` 指定默认代码主题。
+
+代码主题选择器下方使用真实的 `MarkdownContent` 和 Shiki 渲染 TypeScript 示例，选项变化后立即展示对应 GitHub 高亮效果。该预览只存在于主题设置页，不会恢复写作页代码块的额外预览面板。
+
+代码块容器使用 GitHub 风格的背景、边框、6px 圆角、16px 内边距和等宽字体；相关颜色由 `--color-code-*` Token 控制，方便主题商店覆盖。
+
+高亮结果同时生成 `github-light` 和 `github-dark` 颜色变量。根节点的 `data-theme` 变化后由 CSS 选择对应颜色，因此切换主题无需重新解析整篇 Markdown。
+
+写作编辑器中的普通代码块进入文档后直接展开 CodeMirror 编辑区，不再先显示 Shiki 预览，也不再提供“编辑代码/查看高亮”切换，减少一次多余操作。公式块仍由 Milkdown 的 LaTeX 功能负责编辑和渲染。
+
+Shiki 仅应用于：
+
+- AI 对话中的 Markdown 代码块。
+- Search、智能体等复用 `MarkdownContent` 的只读 Markdown 代码块。
+
+Markdown HTML 仍在写入 DOM 前经过 DOMPurify 清理。
+
+## 3. 新增依赖
+
+- `@element-plus/icons-vue`：统一界面图标；
+- `@milkdown/crepe`、`@milkdown/kit`：可视化 Markdown 编辑器及命令；
+- `shiki`、`@shikijs/langs`、`@shikijs/themes`、`@shikijs/engine-javascript`：代码高亮和按需语言注册。
+
+## 4. 验证记录
+
+在 `frontend` 目录执行：
+
+```bash
+pnpm build
+pnpm test
+```
+
+验证结果：TypeScript 类型检查与 Vite 生产构建均通过。当前前端完整回归测试共 14 项；其中写作与文件切换相关回归覆盖：
+
+- 顶部工具栏对选区应用加粗；
+- 浮动工具栏对选区应用斜体；
+- 自定义字号输入写入 Markdown；
+- 标题恢复为普通正文；
+- 连续切换文件后渲染新文件内容；
+- 从文件树连续点击时，活动路径与编辑器内容同步切换；
+- 欢迎笔记的异步初始化不会覆盖用户刚点击的文件。
+
+文件切换失效包含两层原因。第一层是旧实现先更新 `currentFilePath`、后等待文件内容，导致编辑器使用新路径和旧内容提前重建；现在改为文件读取成功后一次性提交路径和内容。第二层是工作区欢迎笔记的异步初始化结束后会无条件设为活动文件，可能覆盖用户在此期间的真实点击；现在点击文件时立即同步工作区活动路径，默认初始化仅在用户尚未选择文件且欢迎笔记确实加载成功时提交。文件读取失败时则恢复点击前的活动文件。
+
+本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步，以及跟随主题、GitHub Light、GitHub Dark 三种代码块设置下的显示效果。
+
+## 5. 后续建议
+
+- 根据真实文档规模评估 Milkdown 与只读 Markdown 高亮模块的懒加载拆包；
+- 为工具栏补充撤销、重做、引用、行内代码和链接；
+- 增加编辑器选区命令与文件切换的组件测试。
@@ -0,0 +1,209 @@
+# 前端壳子与接口层开发说明
+
+> 更新日期：2026-08-30
+> 适用范围：Vue 3 + TypeScript 页面、Workspace、公共 Service、FastAPI 接口适配和 SSE。
+> 文档用途：帮助团队理解当前前端可用能力、模块边界、启动方式和后续页面开发入口。
+
+## 1. 当前实现状态
+
+当前前端已经形成一条可安装、可类型检查、可生产构建和可联调的基础链路：
+
+```text
+Vue Router
+→ App Shell
+→ Pinia Store
+→ Service / FastAPI DTO Adapter
+→ HTTP 或 SSE
+→ FastAPI
+```
+
+当前已经落地的页面和公共界面包括：
+
+- Vault 入口页；
+- 应用标题栏、主侧边栏、辅助侧边栏和状态栏；
+- Workspace 文件树；
+- Markdown 写作/源码模式、手动保存和自动保存状态；
+- 文件打开、新建、删除和重命名交互壳子；
+- Search 查询、筛选、结果列表和 Citation 定位；
+- Chat 会话、Provider/Model/Skill 选择和 SSE 输出；
+- Agent Run 创建、Trace、取消和权限确认；
+- Task 筛选、创建、编辑、状态切换和删除；
+- Skill、Plugin 生命周期管理；
+- Theme 预览、切换和编辑器 Token 覆盖；
+- Settings 的通用、编辑器、Provider、索引、权限和 AI Core 诊断分区；
+- 可收起主导航、功能型二级侧栏、状态栏和 `Ctrl+P` 命令面板。
+- Milkdown 可视化写作、CodeMirror 源码/代码块编辑、Markdown 格式栏和 Shiki 只读代码高亮；
+- OpenAI、DeepSeek、Ollama 预设、自动模型发现和开发阶段加密 API Key 输入；
+- 智能体页面、运行状态、事件、工具和权限详情的中文展示。
+
+原统一占位页已经删除，所有已注册业务路由均指向真实页面。Web Workspace 已通过 FastAPI 连接后端配置的单一真实 Vault，不再回退 Mock 数据；Tauri 多 Vault、原生目录选择、Stronghold 和桌面窗口能力仍在桌面容器阶段接入，不影响页面与 Store 的调用边界。
+
+## 2. 目录与职责
+
+```text
+frontend/src/
+├── components/common/          App Shell、导航、命令面板与扩展公共组件
+├── contracts/index.ts          UI View Model 与 FastAPI Wire DTO
+├── features/                   按页面领域拆分的业务组件
+├── features/editor/            编辑器头部与写作/源码编辑区
+├── features/vault/             Vault 入口
+├── features/workspace/         Workspace 与递归文件树
+├── router/index.ts             页面路由和 Vault Guard
+├── services/                   HTTP、SSE、DTO 映射和模块 API
+├── stores/                     Pinia 状态
+└── styles/tokens.css           Design Token
+```
+
+职责约定：
+
+- Component 不直接拼接后端 URL；
+- Store 负责页面状态和业务操作编排；
+- Service 负责 HTTP/SSE 调用以及 Wire DTO 到 View Model 的转换；
+- `contracts/index.ts` 同时保留界面模型和以 `Api` 开头的 FastAPI DTO，两者不能混用；
+- OpenAPI `/openapi.json` 是后端 Wire Contract 的最终依据。
+
+## 3. 路由与页面壳子
+
+已注册路由：
+
+```text
+/
+/workspace
+/search
+/chat
+/agent/runs/:runId?
+/tasks
+/extensions/skills
+/extensions/plugins
+/themes
+/settings
+```
+
+除 Vault 入口外，其余路由需要先打开 Vault。全部路由均使用懒加载真实页面组件，既保持首屏包体可控，也避免占位页面掩盖缺失实现。
+
+## 4. 页面实现边界
+
+| 页面 | 当前可用能力 | 主要 Store / Service |
+| --- | --- | --- |
+| Workspace | 文件树、新建、重命名、删除、打开、编辑、保存、模式切换 | `workspaceStore`、`editorStore`、`workspaceService` |
+| Search | FTS/Vector/Hybrid、文件夹与标签筛选、结果定位 | `searchStore`、`searchService` |
+| Chat | 会话选择、模型配置、RAG、Skill、SSE、Citation | `chatStore`、`providerStore`、`chatService` |
+| Agent | Run 配置、Tool 选择、Trace SSE、权限确认、取消 | `agentStore`、`agentService` |
+| Tasks | 状态筛选、CRUD、完成与恢复 | `taskStore`、`taskService` |
+| Skills | 列表、详情、安装、启停、卸载 | `skillStore`、`skillService` |
+| Plugins | 列表、权限确认、安装、启停、卸载 | `pluginStore`、`pluginService` |
+| Themes | 主题预览、应用、字体与行高覆盖、恢复默认 | `themeStore` |
+| Settings | 通用、编辑器、Provider、索引、权限、诊断 | `settingsStore`、`providerStore`、相关 Service |
+
+## 5. Workspace 与编辑器
+
+Workspace 当前由以下组件构成：
+
+```text
+WorkspaceView
+├── EditorHeader
+└── EditorPane
+
+SecondarySidebar
+└── FileTreePanel
+    └── FileTreeNode（递归）
+```
+
+文件树把右键目标保存在 `contextTarget`，重命名和删除始终作用于实际被右键的节点，不再依赖当前编辑文件。根目录使用 `/` 表示，新增根级文件时直接写入 Store 顶层数组。
+
+当前 `workspaceService` 是 FastAPI Workspace Adapter。打开 Vault 时只允许后端 `APP_VAULT_PATH` 配置的目录，随后通过 Workspace/Note API 读取真实文件树和 Markdown，并完成文件、目录的新建、重命名、移动、保存和删除。接口错误直接进入统一错误链路，不再用 Mock Fallback 掩盖连接或契约失败。
+
+浏览器不能获得任意本地文件系统权限，因此 Web 模式不提供目录选择和多 Vault 管理。进入桌面端阶段后，由 Tauri Host 实现同一 Service 边界下的原生适配器，组件和 Store 无需感知底层传输变化。
+
+## 6. HTTP 接口层
+
+公共请求由 `apiClient.ts` 处理：
+
+- 支持 GET、POST、PUT、PATCH 和 DELETE；
+- 使用 `VITE_API_BASE_URL`，并兼容旧的 `VITE_API_BASE`；
+- 自动附加 `X-Request-Id`；
+- 将后端统一错误体转换为 `ApiErrorClass`；
+- 204 响应返回 `undefined`。
+
+Service 已适配当前 FastAPI Contract：
+
+| 模块 | 主要适配内容 |
+| --- | --- |
+| Notes | `folder`、`markdown`、直接 Note 响应和 `{items, page}` |
+| Search | 数组筛选字段、`items/page` 响应和 Search View Model 映射 |
+| Chat | `provider_id`、`model`、`messages` 和 ModelEvent SSE |
+| Agent | `input`、秒级 Timeout 字段、Run DTO 和 Permission Decision |
+| Skill / Plugin | 嵌套 `manifest`、安装 `package_path` 和 Plugin Permission PUT |
+| Provider | Provider Type、Capability 数组、模型列表包装和 Test 响应 |
+| Task | `due_at`、分页响应和当前后端支持字段 |
+| Index | `all/notes/vectors` Scope、Job 与状态 DTO |
+| System | `/health` 和 `/api/status` 的真实响应字段 |
+
+界面模型中存在的展示字段不能直接发送给后端。例如 Task View Model 的 `priority` 和 `source` 当前只是界面层字段，Service 创建与更新请求不会把它们发送给不支持这些字段的 FastAPI Contract。
+
+## 7. SSE
+
+`SseClient` 同时服务于 Chat 和 Agent Event：
+
+- 使用与普通 HTTP 相同的 API Base URL；
+- 支持 POST Chat Stream 和 GET Agent Event Stream；
+- 使用 `TextDecoder` 处理 UTF-8 增量字节；
+- 在网络分片之间保留 `event` 和多行 `data` 状态；
+- 以空行作为单个 SSE Event 的结束标志；
+- 识别 `Done`、`RunCompleted`、`RunFailed` 和 `RunCancelled`；
+- 支持 AbortController 主动取消。
+
+Chat Store 已从定时器模拟输出切换为真实 `/api/chat` SSE。默认离线联调配置为：
+
+```text
+provider_id = mock
+model       = mock-1
+```
+
+## 8. 环境和启动
+
+```powershell
+cd frontend
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+联调前在另一个终端启动后端：
+
+```powershell
+cd backend
+uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+生产构建：
+
+```powershell
+cd frontend
+pnpm build
+```
+
+## 9. 当前验证基线
+
+```text
+pnpm build       passed
+pnpm test        27 passed
+uv run pytest    80 passed
+preview smoke    HTTP 200
+git diff --check passed
+```
+
+当前前端使用 Vitest 执行 Store、Workspace API Adapter、SSE 恢复游标、文件树、编辑器组件、智能体标签、轻量动效约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题测试；`pnpm build` 同时执行 `vue-tsc -b` 与 Vite 生产构建。后端测试出现过 `.pytest_cache` 无法写入的 Windows 权限警告，不影响 80 项测试结果，也不涉及产品代码。
+
+Vite 当前会提示 Chat 与 Workspace 的部分异步 Chunk 超过 500 kB，这是 Milkdown、CodeMirror、KaTeX 和 Shiki 等编辑/渲染依赖带来的性能优化项，不影响构建成功或功能正确性；进入桌面打包前应通过手动分包或更细粒度动态加载继续优化。
+
+浏览器可视化冒烟在本次执行环境中因浏览器运行资源缺失未能启动；HTTP 冒烟已确认前端入口、后端健康检查与 OpenAPI 均能访问。进入合并验收前，仍建议团队在本机打开各路由完成一次人工视觉检查。
+
+## 10. 后续开发要求
+
+- 新页面文件与路由修改必须在同一提交中出现；
+- 新增或修改接口时同步更新 FastAPI DTO、Service 映射和接口文档；
+- 不允许用 `as any` 或错误返回类型掩盖 Contract 差异；
+- SSE 相关变更需要覆盖跨 Chunk、CRLF、多行 data、终态事件和取消；
+- Workspace 接入 Tauri 后，需要增加路径规范化、写入失败恢复和外部修改冲突测试；
+- 页面新增交互必须经过键盘、空状态、加载状态、错误状态和窄窗口检查；
+- Workspace 的 Milkdown 写作模式与 CodeMirror 源码模式共享同一 Markdown 数据源；后续修改编辑器时不得改变 Store/Service 边界，并必须保留文件切换、自动保存和选区格式化回归测试。
@@ -0,0 +1,113 @@
+# 前端视觉与轻量动效优化开发说明
+
+> 更新日期：2026-08-30
+> 适用范围：全局 Design Token、App Shell、功能页、卡片、表单、弹窗和轻量交互动效
+
+## 1. 目标
+
+本轮优化不改变页面功能和前后端契约，主要解决原界面层级偏平、组件间距不统一、交互反馈不足的问题，同时为后续主题商店 CSS 注入保留稳定边界。
+
+设计原则：
+
+- 颜色、圆角、阴影、间距和速度继续使用 CSS 变量；
+- 页面与弹窗动画只改变 `opacity` 和 `transform`；
+- 不使用背景模糊、连续粒子、视差、复杂 SVG 或大范围布局动画；
+- 不使用 `transition: all`，只声明需要变化的属性；
+- 尊重系统 `prefers-reduced-motion` 设置；
+- 主题只需覆盖现有 Token，不需要了解组件内部动画实现。
+
+## 2. 全局视觉基线
+
+更新 `tokens.css`：
+
+- 调整四级圆角和阴影，使卡片、弹窗与导航层次更清楚；
+- 调整标题栏、状态栏和双侧栏尺寸；
+- 统一更短的运动时间与缓动曲线；
+- 增加键盘 `focus-visible` 焦点环；
+- 为 checkbox、radio 和 range 使用主题强调色；
+- 窄窗口下收缩辅助侧栏与展开导航宽度；
+- 在减少动态效果模式下，把动画和过渡缩短到近似即时完成。
+
+更新 `features.css`：
+
+- 功能页增加受控内容宽度、响应式留白和低强度主题渐变；
+- 卡片增加边框、阴影与最多 2px 的悬浮位移；
+- 按钮、输入框、Badge、空状态和通知统一交互反馈；
+- 设置页导航改为分段式卡片导航；
+- 弹窗与页面增加一次性淡入和轻微位移动画。
+
+## 3. 页面与布局优化
+
+### 3.1 App Shell
+
+- 主侧栏增加明确的 Active 标记、悬浮反馈和宽度过渡；
+- 辅助侧栏统一为次级 Surface，并改善标题与标签层级；
+- 标题栏应用名改为轻量胶囊标识；
+- 状态栏强化状态点和窄窗口降级；
+- 命令面板增加轻量入场、圆角、阴影和列表反馈。
+
+### 3.2 业务页面
+
+- Search 结果卡片增加左侧强调线和统一内容宽度；
+- Chat 增加消息容器、头像层级、Citation 悬浮反馈和 Composer 顶部阴影；
+- Agent Tool 选择卡增加选中状态，Trace 使用轻量时间线；
+- Task 完成按钮增加主题化状态反馈；
+- Settings 行在悬浮时提供背景提示；
+- Workspace 空状态与 Vault 入口增加清晰的层级和一次性入场动画。
+
+## 4. 动效性能边界
+
+允许的常规动效：
+
+```text
+opacity
+transform: translate / scale / rotate
+background-color
+border-color
+color
+box-shadow
+```
+
+默认禁止：
+
+```text
+transition: all
+backdrop-filter / filter 模糊
+持续改变 width / height / margin / padding 的动画
+无限循环的装饰动画
+全屏高频渐变或粒子动画
+```
+
+状态栏 Spinner 和 AI Core 检查状态点属于有明确状态含义的循环动画，并会被 `prefers-reduced-motion` 全局规则降级。
+
+## 5. 主题商店接入约定
+
+自定义主题优先覆盖以下 Token：
+
+- `--color-background-*`
+- `--color-surface-*`
+- `--color-text-*`
+- `--color-accent-*`
+- `--color-border-*`
+- `--color-code-*`
+- `--shadow-*`
+- `--radius-*`
+- `--motion-*`
+
+主题 CSS 不应给通配选择器增加动画，不应重新启用高成本滤镜，也不应覆盖 `prefers-reduced-motion` 的降级规则。若主题需要完全静态的界面，可把三个 `--motion-*` Token 设置为接近 0ms。
+
+## 6. 验证
+
+新增 `styles/motion.spec.ts`，防止全局样式重新引入 `transition: all`、高成本模糊滤镜或布局型页面入场动画，并约束 Markdown 表格与列表使用独立的高对比度主题变量。
+
+当前验证结果：
+
+```text
+pnpm test   9 files / 23 tests passed
+pnpm build  passed
+git diff --check passed
+```
+
+生产构建仍有已有的大 Chunk 警告，主要来自 Milkdown、CodeMirror、KaTeX 和 Shiki；本轮样式及动效未增加 JavaScript 动画库或运行时依赖。
+
+本轮已完成样式静态检查、自动化测试和生产构建。由于本机内置浏览器运行资源路径缺失，亮色/暗色主题的人工页面巡检需在 PR 验收环境补做。
@@ -0,0 +1,107 @@
+# 模型提供商与模型发现开发说明
+
+> 更新日期：2026-08-30。OpenAI、DeepSeek、Ollama 预设、模型自动发现、默认模型选择和开发阶段加密凭据存储均已实现并接入设置页。
+
+## 1. 本次目标
+
+本次完善设置页的模型提供商配置，不改变 Agent、Chat 和 Skill 对统一 Model Core 接口的依赖：
+
+- 提供 OpenAI、DeepSeek 和 Ollama 配置预设；
+- 保存 Provider 后自动获取该账号或服务当前可用的模型列表；
+- 支持手动刷新模型列表和选择默认模型；
+- 保留自定义 OpenAI-Compatible 服务入口；
+- 不在 Vue、FastAPI 配置或仓库文件中保存、回显 API Key 明文。
+
+## 2. 接口与实现
+
+### 2.1 Provider 预设
+
+新增接口：
+
+```http
+GET /api/providers/presets
+```
+
+预设由后端 `ProviderFactory` 提供，前端只消费名称、协议类型、Base URL 和是否需要凭据等配置元数据，不直接实现厂商协议。
+
+当前预设：
+
+| 提供商 | Provider Type | Base URL | 默认 Credential ID |
+| --- | --- | --- | --- |
+| OpenAI | `openai_chat` | `https://api.openai.com/v1` | `openai` |
+| DeepSeek | `openai_compatible` | `https://api.deepseek.com` | `deepseek` |
+| Ollama | `ollama` | `http://127.0.0.1:11434` | 无 |
+
+OpenAI 和 DeepSeek 都通过项目已有的 `OpenAICompatibleProvider` 访问。模型发现分别请求 Base URL 下的 `/models`，不引入厂商 SDK。
+
+### 2.2 自动获取模型
+
+模型列表继续使用既有接口：
+
+```http
+GET /api/providers/{provider_id}/models
+```
+
+设置页在以下时机调用该接口：
+
+- Provider 列表加载完成后，为所有已启用 Provider 自动刷新；
+- 新增或编辑 Provider 保存成功后自动刷新；
+- 用户点击“刷新模型”时手动刷新；
+- 打开已有 Provider 的编辑窗口时刷新可选模型。
+
+前端按模型名称排序并按 `model_id` 去重。获取结果保存在 `providerStore.modelsByProvider`，加载状态和错误按 Provider 隔离，单个外部服务失败不会阻止其他服务展示。
+
+获取成功后，Provider 卡片展示模型数量和默认模型下拉框。更换默认模型会调用 Provider PATCH 接口写回配置；编辑窗口仍允许手动输入模型 ID，以兼容未出现在列表中的代理模型或部署别名。
+
+### 2.3 错误处理
+
+Provider Adapter 的错误在 FastAPI 路由转换为统一 API Error：
+
+| Provider Error | HTTP 状态 |
+| --- | --- |
+| `PROVIDER_AUTH_FAILED` | 401 |
+| `MODEL_NOT_FOUND` | 404 |
+| `PROVIDER_RATE_LIMITED` | 429 |
+| `PROVIDER_TIMEOUT` | 504 |
+| 其他 Provider 可用性错误 | 502 |
+
+前端在对应 Provider 卡片内展示失败原因，并允许用户修正 Credential ID、Base URL 后重新获取。
+
+## 3. 凭据边界
+
+设置页选择 OpenAI 或 DeepSeek 预设后展示密码类型的 API Key 输入框，不再要求用户理解 Credential ID。输入值只存在于表单的临时 `ref`，不会写入 Pinia 或 localStorage；请求完成、取消表单或失败后都会清空。
+
+API Key 通过独立接口写入：
+
+```http
+GET    /api/credentials/{credential_id}
+PUT    /api/credentials/{credential_id}
+DELETE /api/credentials/{credential_id}
+```
+
+PUT 请求使用 Pydantic `SecretStr` 接收密钥，响应仅包含 Credential ID 和 `configured` 状态。后端使用 Fernet 认证加密，将密文保存到 `data/credentials/credentials.json`，主密钥保存到 `data/credentials/master.key`；目录和文件尽可能设置为仅当前用户可访问并整体排除版本控制。写入采用临时文件替换，避免进程中断留下半写文件。Provider 发起请求时按 Credential ID 解密，解密失败转换为统一 Provider Error，任何读取接口均不返回明文。
+
+本地开发存储的主密钥与密文仍位于同一用户数据目录，因此它解决的是仓库泄漏、普通配置误提交和静态明文暴露，不等同于操作系统安全硬件或 Stronghold。Tauri 集成后应以 Stronghold 实现替换 `EncryptedCredentialStore`。无界面环境仍兼容 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 和 Host 注入的 `AINOTE_CREDENTIAL_<ID>`；设置页保存的本地密钥优先，环境变量仅作为回退。
+
+自动化测试仅使用虚构测试值，验证磁盘文件不包含明文、加解密往返、API 响应不泄密，以及 Provider 能用解密后的值构造 Authorization Header。本次没有使用真实 OpenAI 或 DeepSeek Key，也没有向厂商发起真实请求。
+
+## 4. 验证
+
+后端：
+
+```bash
+cd backend
+uv run pytest -q -p no:cacheprovider
+```
+
+前端：
+
+```bash
+cd frontend
+pnpm test
+pnpm build
+```
+
+自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。
+
+当前完整回归基线：后端 80 项测试、前端 27 项测试通过，前端类型检查和生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。