Merge origin/main into feat/export-service
同步 main（054f704），解决 contracts.py / main.py / README.md / 技术栈说明 的合并冲突。 - contracts.py：保留 pydantic 多行导入并新增 RequestOverride - main.py：合并 lifespan（导出孤儿清理 + 转写/本地模型生命周期） - README.md / 技术栈说明：文档取 main 最新版本 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -0,0 +1,69 @@
|
||||
# Tauri / Rust 桌面客户端需求说明（第三阶段）
|
||||
|
||||
状态：需求预留，尚未实现桌面客户端。本文不表示已有可调用的 Tauri Command 或可发布安装包。
|
||||
|
||||
基线日期：2026-09-05。
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
第三阶段在现有 Vue 编辑器和 FastAPI AI Core 上接入 Tauri 2 / Rust Host，提供原生窗口、菜单、多 Vault 文件管理、安全凭据存储和 Sidecar 生命周期管理。
|
||||
|
||||
- Vue 负责页面、编辑事务、主题和交互状态；通过既有 Service 边界调用能力，不在组件中散布平台判断。
|
||||
- Rust Host 负责系统能力、路径权限、原生菜单事件及受控进程生命周期。
|
||||
- FastAPI AI Core 保留笔记解析、索引、检索、模型和 Agent 业务职责；同一文件不得同时由 Host 和 AI Core 无协调地写入。
|
||||
- Web 模式保留可运行能力；桌面专有功能通过能力检测显隐，不用无响应按钮假装已实现。
|
||||
|
||||
架构依据：[技术栈说明](../architecture/AI笔记软件技术栈说明-团队版-v2.3.md)、[前端页面需求](前端页面需求说明-开发版.md)、[第二阶段接口契约](第二阶段接口契约-开发版.md)。
|
||||
|
||||
## 2. 顶部菜单与元数据格式一键导入
|
||||
|
||||
### 2.1 入口预留
|
||||
|
||||
桌面客户端顶部菜单栏的 **段落 → 导入为笔记属性…** 预留元数据格式导入功能，与标题、正文、列表等段落操作归组。它处理笔记内容中的元数据，不是主题包安装入口。
|
||||
|
||||
建议稳定的前端命令标识为 `editor.import-note-properties`，仅为设计标识，尚未注册为 Tauri IPC。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
|
||||
|
||||
### 2.2 输入与转换规则
|
||||
|
||||
1. 无选区时识别当前笔记开头的属性块；有选区时只处理完整的属性块。无活动笔记、加载中、只读或冲突状态下禁用操作，并提供原因。
|
||||
2. 支持标准 YAML frontmatter，以及历史编辑器产生的 `***` 开头、`title:` / `tags:` 字段、横线结尾的兼容形式。普通分隔线、代码块和包含冒号的正文不得被误判。
|
||||
3. 将识别成功的内容规范化到文件头唯一的 `---` frontmatter 中，正文中的旧属性块仅在转换成功后移除。
|
||||
4. 写作模式显示独立标题和可编辑标签；源码模式显示真实 `title` / `tags` 字段。标签必须进入现有保存和索引链路，能被标签筛选使用，不能只创建装饰性标签元素。
|
||||
5. 保留未知属性及其类型，特别是 `embedding_local_only` 等行为配置。复杂 YAML 不得用正则拆分后静默丢弃；无法无损处理时说明原因，并保留原文供源码编辑。
|
||||
6. 标签支持字符串、逗号分隔值和 YAML 列表，去重并保留顺序；中文、空格、转义字符须正确往返。空标签与删除标签有明确语义。
|
||||
7. 已存在 frontmatter 时合并到同一个属性块；字段值冲突时展示差异供用户选择，禁止静默覆盖。重复执行不重复添加标签或属性块。
|
||||
|
||||
### 2.3 编辑与保存行为
|
||||
|
||||
- 无歧义转换一次菜单操作完成，并构成一个可撤销的编辑事务；转换失败不得改变文档或保存状态。
|
||||
- 转换作用于当前内存文档，不先从磁盘读取旧内容覆盖未保存编辑。操作绑定文件标识和文档版本，异步处理期间切换文件或继续编辑时，应取消或重新校验。
|
||||
- 成功后进入现有脏状态和自动保存流程。磁盘保存失败显示可重试状态，撤销／重做同时恢复正文、属性及标签。
|
||||
- 属性块不进入正文大纲；标题跳转、引用定位仍使用完整原文件的正确偏移。写作／源码切换、保存后重开不得改变属性语义。
|
||||
- 当前分支的 `frontend/src/features/editor/noteMetadata.ts` 仅是简单属性块展示与标签编辑基础；桌面阶段需补齐完整解析、合并冲突、单事务撤销和原生菜单分发，不能直接视为本节已经验收。
|
||||
|
||||
## 3. 桌面基础需求
|
||||
|
||||
| 模块 | 第三阶段要求 | 验收要点 |
|
||||
| --- | --- | --- |
|
||||
| 窗口与菜单 | 原生窗口控制、顶部菜单、焦点分发、关闭前未保存处理 | 菜单操作针对活动编辑器；多窗口不串文档；取消关闭保留编辑 |
|
||||
| Vault 与文件系统 | 原生目录选择、多 Vault、最近打开、文件监听、路径规范化 | 未授权目录不可访问；重命名同步树和打开文件；外部修改不静默覆盖 |
|
||||
| 写入与恢复 | 原子写入、版本／内容摘要校验、失败重试和异常退出恢复 | 不产生半写文件；并发保存不覆盖新版本；恢复流程可验证 |
|
||||
| AI Core Sidecar | 启停、健康检查、日志、崩溃恢复、退出清理 | 不残留进程；不可用时显示原因；本地通信有访问控制 |
|
||||
| 凭据 | 按既有架构接入 Stronghold／平台安全存储，制定开发凭据迁移方案 | 前端只持有凭据引用；不回显密钥；失败可恢复且不丢凭据 |
|
||||
| MCP 与插件 | 按已冻结的 Host 沙箱契约落实文件、网络和子进程授权 | 沿用审批边界，不因桌面集成默认放开权限 |
|
||||
| 主题 | 复用主题包校验；原生文件选择和下载适配共用检查流程 | 导入不自动启用；安装失败可恢复；ZIP 路径和资源限制继续有效 |
|
||||
| 外观与导航 | 继承主题、代码配色、相对纸页宽度、文件／大纲切换 | 窗口缩放、高 DPI、深浅主题下无截断；键盘导航完整 |
|
||||
| 发布 | Windows、macOS、Linux 构建与安装验证；签名、升级及回滚方案 | 未准备好签名和回滚前不启用自动更新；平台差异有说明 |
|
||||
|
||||
云同步服务、移动端和主题社区服务端不因本文自动纳入第三阶段必交范围；需要单独确认范围与接口。
|
||||
|
||||
## 4. 开发顺序与验收
|
||||
|
||||
1. 冻结 Host 能力与 Service 适配接口，明确每类数据的写入责任方及权限模型。
|
||||
2. 接入窗口、菜单与编辑命令路由，完成“段落 → 导入为笔记属性…”的编辑器事务。
|
||||
3. 接入 Vault、文件监听、冲突处理、Sidecar 和凭据迁移。
|
||||
4. 完成平台测试、安装包和升级恢复验收。
|
||||
|
||||
元数据导入专项测试至少覆盖：标准／历史格式、普通正文误判、代码围栏、未知字段、复杂 YAML、同名字段冲突、重复导入、中文标签、撤销重做、未保存文档、处理中切换文件、保存失败、重开后标签检索，以及写作／源码模式的大纲与引用偏移。
|
||||
|
||||
第三阶段实现 PR 必须补充实际 Command 名称、输入输出类型、错误码、平台差异和测试证据；在此之前本文所有 Host 能力均标为计划实现。
|
||||
@@ -32,6 +32,8 @@
|
||||
| POST | `/api/notes/{note_id}/move` | 移动笔记 |
|
||||
| POST | `/api/notes/{note_id}/rename` | 重命名笔记文件并保留 Note/Block 身份 |
|
||||
| POST | `/api/search` | FTS、Vector 或 Hybrid 检索 |
|
||||
| GET | `/api/search/history` | 读取当前应用数据库最近 10 条去重搜索记录 |
|
||||
| DELETE | `/api/search/history` | 清空当前应用数据库的搜索记录 |
|
||||
|
||||
### Workspace
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 第二阶段接口契约与开发规划
|
||||
|
||||
阶段 F 实现更新（2026-09-04）：新增持久化媒体任务、附件上传/清理、修订与笔记导出、本地模型管理、Token 用量及提供商请求 JSON。详细路径、字段语义和验证边界见 [多模态管线与模型运行开发说明](../development/多模态管线与模型运行开发说明.md)，以下旧阶段规划与实现不一致时以该说明和 OpenAPI 为准。
|
||||
|
||||
> 文档状态：接口冻结草案
|
||||
>
|
||||
> 更新日期：2026-09-03
|
||||
@@ -1574,3 +1576,19 @@ frontend/src/
|
||||
### Benchmark Embedding 运行归属（阶段 E 集成修复）
|
||||
|
||||
`config_snapshot.local_embedding` 仅表示本地基线；`config_snapshot.embedding` 为 `{ "policy": "per_case", "details": "cases[].embedding" }`。报告与 CaseCompleted 事件的逐样本 `embedding` 包含实际 source（api/local/not_used/unavailable）、model_id、dimensions，以及可选 version、fallback_reason、requested_route、route_version、attempted_space。requested_route 仅含提供商引用、模型、相对端点和维度，不包含 API Key 或凭据引用。FTS 不使用 Embedding，标记 not_used；远程失败或索引不完整回退时记录实际本地模型及原因。
|
||||
|
||||
### 阶段 F 收尾接口补充（2026-09-05）
|
||||
|
||||
CUDA 组件：`GET /api/local-models/runtime-components/cuda` 返回 status、stage、supported、custom_interpreter、cuda_available、可选 torch/error。status 为 checking/not_installed/installing/installed/failed/interrupted；读取只检查现有环境，不下载安装。`POST` 同路径明确触发后台安装，返回 202；重复请求复用当前安装任务。正在推理/排队返回 409 MODEL_IN_USE，缺少 uv 返回 422 UV_NOT_INSTALLED，不支持的平台返回 422 PLATFORM_UNSUPPORTED。阶段进度不冒充字节百分比。关闭后端时回收安装进程树，重启后重新验证环境。
|
||||
|
||||
| 接口/字段 | 行为 |
|
||||
| --- | --- |
|
||||
| `POST /api/media/attachments` | 可选 `Idempotency-Key` Header，16–100 位字母、数字、下划线或连字符。后端持久保存键、文件名、attachment_id 和内容摘要；同键同文件同内容返回同 attachment_id，文件名（含扩展名）或内容不一致返回 409 `IDEMPOTENCY_CONFLICT`。对应附件已清理时返回 409 `IDEMPOTENCY_EXPIRED`，客户端需开始新提交。上传仍受 25 MiB 限制。 |
|
||||
| `TranscriptNoteRequest.update_existing` | 默认 false；true 时将新修订安全写入相同导出选项对应的笔记。无基线返回 409 `NOTE_UPDATE_BASELINE_MISSING`；正文改变返回 409 `NOTE_CONTENT_CONFLICT`。同修订重复调用保持幂等。 |
|
||||
| 本地模型 `disk_bytes` | 权重目录实际字节数；无法读取为 null。与下载 bytes/total 分开。 |
|
||||
| `GET /api/local-models/diagnostics` | `scope=application_last_200_attempts`，应用 SQLite 中最近 200 条诊断，包含调用及回退事件。未实际开始推理时不伪造 actual_device。 |
|
||||
| `GET /api/usage` | 增加 `audio_request_count`、可空的 `audio_seconds`、`audio_covered_requests`，适用原有时间/提供商/模型/来源过滤。次数按 transcription/speaker_matching 实际 attempt；未报告时长不估算。 |
|
||||
| `POST /api/providers/request-rules/validate` | 输入/输出 `{version:1, request_overrides:[...]}`；最多 100 条，复用请求扩展校验，不保存提供商。 |
|
||||
| `POST /api/providers/request-probe` | 输入 `{provider:ProviderCreateRequest, stream:boolean}`；固定短消息真实聊天推理，45 秒超时。成功返回 success/stream/model/message；空响应 422、供应商错误 502、超时 504。只使用 credential_id，不接收明文密钥。 |
|
||||
|
||||
请求预览新增 capability 选择（chat/embedding/transcription/speaker_matching），仍只返回隐藏正文的请求体。实际扩展字段是否被供应商接受，以推理响应为准。
|
||||
|
||||
Reference in New Issue
Block a user