Kronecker/NotesAgentic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 7 Wiki Activity

Merge remote-tracking branch 'origin/main' into feat/export-service

Browse Source 
# Conflicts:
#	backend/app/routes.py
This commit is contained in:
yxx
2026-09-06 16:19:37 +08:00
parent c9c5f81d49 5a3546b3ac
commit 966a94cad8
208 changed files with 8233 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+16 -1
View File
@@ -2,7 +2,7 @@
本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。
当前文档基线为 2026-09-05：第一阶段和第二阶段 A～F 工程范围已经合并到 `main`，当前可运行形态仍为 Vue/Vite Web 前端与 FastAPI AI Core。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 尚未接入。
当前文档基线为 2026-09-06：第一阶段和第二阶段 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)。
@@ -18,6 +18,7 @@
## architecture：架构与分工
- [第三阶段实施规划：桌面容器、各社区与 Sync Server（计划）](architecture/第三阶段实施规划.md)
- [AI 笔记软件技术栈说明](architecture/AI笔记软件技术栈说明-团队版-v2.3.md)
- [第一阶段分工表](architecture/第一阶段分工表.md)
- [第二阶段团队分工表](architecture/第二阶段团队分工表.md)
@@ -33,6 +34,18 @@
## development：开发说明
- [前端构建分块优化开发说明](development/前端构建分块优化开发说明.md)
- [工作区后台索引与保存开发说明](development/工作区后台索引与保存开发说明.md)
- [Mermaid 预览与缩放开发说明](development/Mermaid预览与缩放开发说明.md)
- [扩展安装持久化与社区包开发说明](development/扩展安装持久化与社区包开发说明.md)
- [模型上下文管理](development/模型上下文管理.md)
- [Markdown 渲染检查](development/Markdown渲染检查.md)
- [警告框与桌面编辑命令开发说明](development/警告框与桌面编辑命令开发说明.md)
- [标题折叠与样式开发说明](development/标题折叠与样式开发说明.md)
- [主题组件覆盖检查](development/主题组件覆盖检查.md)
- [第二阶段补充验收工具](development/第二阶段补充验收工具.md)
- [多模态管线与模型运行开发说明](development/多模态管线与模型运行开发说明.md)
- [阶段 F 收尾验收记录](development/阶段F收尾验收记录.md)
- [AI Core 与 Agent Core 开发说明](development/AI-Core与Agent-Core开发说明.md)
@@ -81,3 +94,5 @@
- 问题复盘至少写清原因、后果、解决思路、实际方案和验证结果。
- `.local-plans/` 只保存个人或阶段性的本地计划，不属于正式团队文档，不应提交到远程仓库。
- 文档中的“计划实现”和“已经实现”必须明确区分；实现状态以代码、测试和运行时契约为准。
- [Markdown 语法预设与外部文件刷新](development/Markdown语法预设与外部文件刷新.md)
docs/architecture/第三阶段实施规划.md
+279
View File
@@ -0,0 +1,279 @@
# 第三阶段实施规划：桌面容器、扩展社区与多设备同步
> 2026-09-06 后续修复补充：本地扩展安装登记、摘要复核恢复、ZIP 卸载清理以及工作区 context_menu/toolbar 入口已在第二阶段补丁实现。下文原始基线仍保留用于追踪；第三阶段应在此基础上完成迁移、签名、升级事务及生产隔离，不重复建设基础登记。真实质量与厂商验收仍未闭环。
基线日期：2026-09-06。状态：**计划，尚未交付第三阶段**。本规划以当前第二阶段代码及本地验收记录为起点；本次用户明确要求将各社区、Sync Server、Tauri / Rust 容器纳入第三阶段。未勾选项均为待实施，不以文档编写或接口命名代替实现。
## 1. 阶段目标与完成口径
交付一个能够离线工作的桌面笔记应用：用户可选择本地 Vault、可靠保存与恢复文件、运行本地 AI Core、管理受控扩展，并可选择连接独立自托管 Sync Server。主题、Skill、Plugin、MCP 配置、人设及模板拥有可追溯的社区发现和分发入口。关闭社区与同步连接不影响本地编辑、已安装主题和已具备运行条件的本地能力。
第三阶段完成必须同时满足桌面核心、社区分发、同步服务、迁移恢复和发布门禁。Windows 先交付可安装版本，macOS / Linux 随后完成各自构建与实机验收；某平台未通过时必须标为预览或不支持，不以 Windows 结果代替。排期按依赖与交付门推进，具体日期在原型评估后确定。
不纳入本阶段首个稳定版本：移动客户端、多人实时 CRDT 协作、端到端加密同步、跨设备密钥保险库、付费社区与分成、任意远程代码热注入。端到端加密和 CRDT 保留设计接口，不能用预留字段宣传已经支持。
## 2. 当前基线和跨阶段事项
| 范围 | 已有基础 | 第三阶段必须补齐 |
| --- | --- | --- |
| 前端与编辑 | Vue/Vite、写作/源码、真实属性栏、文件/大纲、Markdown、Shiki、Mermaid、主题化控件 | Tauri WebView 实机回归、原生菜单、多窗口焦点、无障碍、缩放及恢复 |
| AI Core | FastAPI、Agent/Tool/Permission、检索、Provider、任务与诊断 | 受控 Sidecar、认证 IPC、应用打包、分 Vault 隔离、迁移与崩溃恢复 |
| 主题 | 文件/URL/ZIP 导入、兼容性与 CSS 校验、隔离预览 | 在线来源、作者与版本索引、撤回、可信更新、资源托管策略 |
| Skill / Plugin | 本地目录与 ZIP 安装、权限/依赖检查、真实 MCP 工具及命令 | 安装记录持久化、升级事务、卸载清理、签名来源、生产隔离、平台兼容 |
| 社区准备包 | `markdown-workbench`、`note-reviewer`、可重复 ZIP 构建及 SHA-256 索引 | 服务端发布与审核、前端索引适配、许可证、更新与撤回流程 |
| MCP | 配置中心、stdio/HTTP/SSE、发现、摘要授权与凭据引用 | 社区配置分发、Host 许可与 OS 限制、生产启动门禁、受控前端扩展点 |
| 同步 | 技术栈中已有目标设计；`server sync/` 当前无实现文件 | 协议、独立服务、客户端队列、冲突、设备身份、部署运维 |
| 原生桌面 | 已有需求文档 | Tauri 工程和 Rust Host 均需建设，不能将 Web 页面当作桌面交付 |
本次社区准备包验证为 70 项相关后端测试通过，并在本地 API 上完成真实 ZIP 导入、启用和命令执行；它不是所有第三阶段功能的验收。开发服务器监听新解压 `.py` 会热重载，当前内存安装记录随之丢失；持久化与开发监听排除规则列为首批问题。
第二阶段待验收事项单独保留：目标 Provider 真实账号兼容性、声纹阈值校准、带标注音频质量、逐字对齐和重叠语音。已有约 37 分 16 秒录音的 CUDA 功能闭环，无参考标注，不能报告 WER/CER、DER 达标。杨星萱负责的检索调优、Benchmark、导出和函数图像须由对应负责人确认状态，不因本规划自动判为完成或重新归责。
## 3. 架构、写入所有权与目录
```mermaid
flowchart TD
UI[Vue 桌面 UI] --> Host[Tauri 2 / Rust Host]
Host --> Files[原生 Vault 与本地 Revision]
Host --> Core[Python AI Core Sidecar]
Host --> Runtime[受控 Plugin / MCP 子进程]
Host --> Credentials[Stronghold / 设备凭据]
Host --> Queue[持久化同步队列]
Queue --> Sync[可选 Sync Server]
Sync --> PG[PostgreSQL]
Sync --> Objects[S3 / MinIO 对象存储]
UI --> Catalog[可选社区目录与分发服务]
Catalog --> Installer[下载、校验、安装事务]
Installer --> Host
```
“Tauri / Rust 容器”指桌面窗口、WebView、IPC、系统能力和受控进程宿主，不是 Docker 容器，也不意味着 Python 或插件天然处于 OS 沙箱。Docker Compose 用于独立部署服务端。
| 数据/操作 | 唯一责任边界 |
| --- | --- |
| 桌面模式 Markdown/附件写入、重命名、删除、同步落盘 | Rust Workspace Service；Vue、AI Core 和同步均经该接口提交 |
| Web 联调文件写入 | 保留现有后端 Workspace Service；同一 Vault 不允许同时处于两套写入所有权模式 |
| 解析、索引、模型、检索、Agent、导出业务 | AI Core；需要写笔记时调用 Host 代理，不能绕过文件版本校验 |
| 本地同步日志、设备游标、待上传任务 | Rust Sync Client 的独立本地存储，与可重建的检索索引分离 |
| 插件安装数据库及授权记录 | Rust Extension Manager；AI Core 获取已校验的配置与工具描述 |
| 同步控制元数据、文件历史 | Sync Server / PostgreSQL；内容对象由对象存储保存 |
| 社区索引、发行包、作者审核 | Community Service，独立于用户私有 Vault、Sync 身份与模型数据 |
建议新增 `frontend/src-tauri/` 和 `frontend/src/services/platform/`；复用 `backend/` AI Core；独立同步服务使用现有 `server sync/` 路径（命令与 CI 必须正确引用含空格目录）。社区服务建议 `community-server/`，共享分发规范与样例保留在 `backend/extensions/community/`，后续迁移须同步链接。目录建议须在 M0 冻结，禁止同时维护两套同步服务入口。
## 4. Tauri / Rust 桌面容器工作包
| ID | 工作包与交付物 | 验收条件 |
| --- | --- | --- |
| D01 | Tauri 2 工程、开发/生产配置、平台能力适配接口、统一错误与取消模型 | 干净机器可构建；Web 模式仍可运行；桌面专有功能有真实能力检测 |
| D02 | 窗口、菜单、托盘、单实例、文件关联、多窗口与会话恢复 | 活动窗口命令不串文档；未保存关闭可取消；路径/文件名包含中文可打开 |
| D03 | 原生 Vault 选择、最近使用、授权撤销、监听器与稳定 file_id | 多 Vault 隔离；外部修改检测；大小写重命名、符号链接、junction、网络盘和盘符变化有明确处理 |
| D04 | 单写入者、expected_hash/version、临时文件+原子替换、恢复日志 | 编辑/同步/Agent 同时写入时返回冲突；掉电/磁盘满不损坏原文件；保存与同步状态分开展示 |
| D05 | AI Core Sidecar 打包、就绪握手、健康检查、重启退避、日志与退出清理 | 无 Python 环境的设备可启动；端口占用、模型不可用、崩溃可诊断；退出后无孤儿进程 |
| D06 | Stronghold 与现有 Fernet 凭据迁移、设备级认证存储 | 前端只拿引用；迁移可重试且幂等；失败保留旧存储；用户确认验证后才清除旧凭据 |
| D07 | 生产 Plugin Host 权限及进程监管 | 权限改变使旧许可失效；拒绝未授权文件/网络/子进程；不能通过命令参数绕过 |
| D08 | 桌面安装、更新、回滚、数据迁移与卸载 | 安装包、更新包签名验证；升级中断可恢复；卸载保留/清理用户数据须明确选择 |
### 4.1 IPC 与 Sidecar
Rust 暴露窄接口，而非任意 shell、任意路径读写或通用 HTTP 转发。建议 Command 分组为 `workspace.*`、`core.*`、`extensions.*`、`credentials.*`、`sync.*`；这是计划命名，实际 Rust 命令表与 DTO 在 M0/M1 固化。请求包含 request_id、vault_id（适用时）、expected_revision、取消标识；响应统一结构化错误。取消和超时不得把已成功落盘的操作显示为已回滚。
Sidecar 与 Host 使用受控本机通道，优先验证 Rust 转发业务请求与事件的方案；若保留 loopback HTTP，必须有每次启动生成的会话凭证、端点与来源校验、握手版本、失效轮换，禁止把端口和 CORS 当认证。握手凭证通过受控进程通道交付，不能写进命令行、URL、诊断包或前端持久存储。只绑定本机，不开放局域网管理接口。远程网页不能调用桌面高权限命令。
打包时锁定 Python 运行时与依赖；不把全部模型权重/CUDA 组件塞进基础安装包。模型按设备选择、固定 revision、分块下载、摘要验证、磁盘检查和取消恢复；模型下载失败不影响编辑。AI Core 与 Host 的版本不兼容时阻止写操作并提供可恢复提示。
### 4.2 原生菜单与编辑事务
落实已有需求中的 **段落 → 导入为笔记属性…**，共享命令标识 `editor.import-note-properties`。必须覆盖标准 frontmatter、历史格式、未知字段保留、冲突预览、单事务撤销重做、处理中切换笔记、保存失败和引用偏移；不得将复杂 YAML 强行降级为装饰性标签。详情沿用[桌面需求文档](../contracts/Tauri-Rust桌面客户端需求说明-第三阶段.md)。
所有窗口复查 Tab/Shift+Tab 焦点循环、IME 回车、系统快捷键、拖动侧栏、对话框内部滚动、长名称、100%/150%/200% 缩放和六种仓库主题。Mermaid 的文字、缩放、滚轮控制和导出引用；Shiki 全语言、行内代码及源码往返均保留回归样例。
### 4.3 凭据和生产隔离门禁
先验证 Stronghold 解锁、锁屏、密码变更、损坏恢复及平台安全存储衔接，再替换开发凭据。不得把 Stronghold 插件接入本身称为完成密钥恢复策略。
MCP 启动许可绑定 package_hash、版本、入口及参数摘要、所需权限、有效期和平台策略。使用参数数组启动，不执行 shell 拼接；限制环境变量、工作目录、资源、网络和文件访问；退出/超时回收进程树。Windows 的 Job Object 等进程管理能力不能单独证明文件/网络隔离；macOS、Linux 也须分别给出可执行策略与突破测试。M0 做平台原型；无法落实的权限必须拒绝或禁用对应插件，不能以“用户点击启用”绕开生产门禁。
## 5. 各社区与统一分发系统
### 5.1 社区覆盖范围
各类别共用来源管理、搜索、详情、发行记录、下载与审核基础设施，但类型校验器和运行权限独立。P0 是首个桌面公开测试前必须完成；P1 仍属于第三阶段整体交付，在 M5 收尾。
| 社区 | 优先级 | 交付内容 | 特有约束 |
| --- | --- | --- | --- |
| Theme 主题社区 | P0 | 预览图、真实组件预览、深浅色/标签筛选、安装更新、作者页 | 受限 CSS、设计变量、资源包策略；预览与宿主隔离；不得执行脚本 |
| Skill 社区 | P0 | Prompt/清单预览、依赖与能力展示、安装更新、示例输入输出 | 安装不代表 Prompt 可信；依赖 Plugin 就绪后才可启用；不得隐式扩大工具范围 |
| Plugin 社区 | P0 | 平台/架构兼容、入口与权限清单、变更记录、签名、卸载与回滚 | 可执行包须通过生产 Host 门禁；版本或权限变更重新授权 |
| MCP 配置社区 | P0 | 服务说明、transport、参数模板、所需凭据名称、导入后测试 | 配置包不是可执行 Plugin；禁止内嵌真实密钥；URL/命令变更重新确认摘要 |
| 人设与对话预设社区 | P1 | 人设、系统提示词、对话对、头像授权信息、差异预览 | 导入为候选项，不静默替换全局人设；凭据、聊天历史不得混入包 |
| 笔记模板/工作流社区 | P1 | 属性 schema、正文模板、任务工作流、预览及输入说明 | 模板实例化生成新内容；可执行流程必须转入 Skill/Plugin 权限体系，不能用模板绕过 |
| 模型运行方案目录 | P1 | 模型来源、许可证、固定 revision、资源要求与已验证平台 | 分发配置与下载引用，不默认镜像大权重或传播受限模型；发布者需注明验收设备 |
社区入口保留各页面上下文：“已安装 / 社区”；统一详情展示来源、版本、大小、摘要、依赖、兼容性、权限、许可证和更新记录。卡片宽度、安装状态、进度、取消、错误、重试、离线缓存及键盘交互沿用公共组件。下载完成与已启用分开显示；缺失依赖可引导安装，但不得自动启用可执行依赖。
### 5.2 社区服务与来源
- 首期支持官方审核源、用户添加的自托管源和本地文件；统一 Source ID、启用状态、缓存时间、信任状态和拉取错误。应用连接 Sync Server 不自动信任同域社区。
- 以现有 `dist/index.json` 作为原型输入，升级到版本化目录 schema。索引字段至少为 namespace/package_id/type/version、显示名、作者 ID、许可证、摘要、大小、平台/架构、最低/最高兼容版本、依赖、权限、发布日期、撤回状态、签名键 ID、发行包地址。截图和说明文档也按不可信内容处理。
- 首期静态索引与不可变 ZIP 可部署于 HTTPS/Gitea Release/对象存储；客户端通过 Adapter 读取。随后 Community API 提供搜索、分页、详情、版本、提交、审核、举报与撤回。路由及 OpenAPI 在 C01 冻结，不能把样例索引当已上线市场。
- 建议接口族：`/catalog/v1/sources`、`/packages`、`/packages/{id}/releases`、`/publish/submissions`、`/moderation/reviews`。消费者只读接口与作者/审核写接口分离；类型、分页、筛选、ETag/缓存和错误约定进入契约测试。
- 作者登录使用独立权限模型，可复用身份组件但不共享私有 Vault 访问令牌。维护者转移、命名空间占用、盗号、版本撤回、举报、封禁和恢复保留审计记录。评分/评论可在 P1 实现，具备限流、举报和内容管理，不能挤占安装安全交付。
### 5.3 安装、升级与持久化
统一状态机：发现 → 下载 → 摘要/签名校验 → 安全解包 → schema/兼容性/依赖检查 → 用户确认 → 原子安装 → 待启用 → 就绪；任一环节失败提供明确状态。安装记录持久化 package_id、来源、版本、摘要、安装目录、授权摘要、启用意图和失败原因，启动时重新校验后恢复，删除/损坏包显示可修复状态。
下载限流、限大小、超时、取消与分块恢复；服务端代抓 URL 时限制协议、重定向和内部网络访问，桌面下载也不得凭社区 URL 获得任意本地文件访问。ZIP 检查路径穿越、Windows 特殊路径、大小写冲突、链接、压缩炸弹、条目数量、资源类型和最终磁盘空间；现有主题与扩展不同大小限制不得无意合并。
SHA-256 只证明完整性，不证明发布者身份。来源签名、信任根、轮换与撤销策略需要单独实现；发行包不可原地替换，修改内容须发布新版本。许可证未明确的准备包不能自动进入正式公共目录。
升级先暂存和校验，再停止旧运行实例、迁移配置、切换版本并健康检查。失败回滚旧包及匹配配置；依赖版本冲突、循环依赖、离线缺包有明确诊断。卸载先检查被依赖关系与运行任务，注销工具/命令、终止进程、清理受管理包和缓存；用户自选目录不得被递归删除。秘密数据删除单独确认。
### 5.4 扩展协议深化与验收包
补齐现有仅声明未完整挂载的 Plugin context_menu、toolbar、sidebar_panel。前端扩展优先使用声明式组件及受限消息协议；若需要独立 WebView，单独 capability、CSP、来源、消息 schema 和资源配额，不能共享主窗口全部 IPC 能力。MCP Resources/Prompts 等新能力先逐项声明支持矩阵；Sampling/Elicitation 涉及额外模型调用或用户输入，必须经内部权限和计费可见性边界，不直接透传。
Theme 至少覆盖六主题组件矩阵；Skill/Plugin 以 `note-reviewer` 与 `markdown-workbench` 作为真实验收包，验证安装→启用→执行→升级→回滚→撤回→卸载；MCP 目录提供无密钥的 stdio 与远程配置模板；人设与模板社区各有可预览、可安装、可删除的实际样例。样例必须与正式 Runtime 共用接口。
## 6. Sync Server 与 Sync Client
### 6.1 独立部署与首期范围
Sync Server 沿用既定 FastAPI + PostgreSQL + S3/MinIO。服务端负责账号、设备、Vault 授权、Revision、对象、游标、配额和变化通知；不承载用户的本地 RAG/Agent/模型运行。自托管是必交内容，托管实例是可选运营形式，客户端协议相同。
首期至少完成单用户多设备、多 Vault 隔离和撤销设备。数据库预留成员角色；多人共享权限在 P1 实现前界面不开放。实时协同不纳入首期。
### 6.2 同步分类
| 数据 | 默认策略 | 处理方式 |
| --- | --- | --- |
| Markdown、用户附件、任务、用户 Skill/配置、主题配置 | 同步 | Stable ID + Revision；任务/config 使用版本化记录，不能把 SQLite 整库复制 |
| 对话、Agent 历史、人设、布局、一般 Provider 参数 | 用户选择后同步 | 提示内容范围；字段白名单；运行中的 Agent 状态不跨设备恢复执行 |
| Plugin/Theme 安装清单 | 可选 | 同步 ID、来源、版本及摘要；另一设备重新下载校验和授权，不传递启用许可 |
| 用户主题资源 | 可选 | 校验后同步受支持资源，不把可执行文件夹视为普通主题 |
| API Key、同步令牌、Plugin 凭据、设备许可 | 禁止普通同步 | 设备本地存储；跨设备凭据需未来独立 E2EE 方案 |
| 索引、向量、模型权重、缓存、日志、临时文件、设备性能配置 | 不同步 | 每设备重建或自行下载；不同 Embedding 配置保持隔离 |
应用 UI 必须说明首期是 HTTPS 传输保护及服务端存储保护，服务器运营者仍可能接触明文内容，不宣传为端到端加密。
### 6.3 标识与协议草案
M0 固化 `Sync Protocol v1`，建议使用 `/sync/v1` 命名空间，与现有本地 `/api` 分开。版本握手必须能拒绝不兼容的客户端；以下为待实现接口族：
| 接口族 | 必须约定 |
| --- | --- |
| auth / sessions | 登录、刷新、注销、失效及限流；不将密码存入客户端配置 |
| devices | 注册、设备列表、撤销、丢失设备处理；撤销后旧令牌不可提交或读对象 |
| vaults / bindings | 远程 Vault 创建/绑定、所有者权限、解除绑定，解除不删除本地文件 |
| objects / uploads | 预申请、上传/续传、摘要验证、完成确认；短时授权绑定用户/Vault/对象/大小 |
| revisions / commit | 幂等键、file_id、base_revision、目标路径、operation、对象摘要与大小 |
| changes / cursor | 单调递增服务端序列、分页、快照边界、游标过期后的全量对账 |
| history / restore | 分页历史、下载旧版本、恢复为新 Revision，不修改历史对象 |
| notifications | WebSocket 通知只作拉取提示；丢消息后仍能通过游标拉全 |
file_id 在重命名/移动后保持不变；device_id 与 vault_id 在本机和远端明确映射。path 不作为身份；版本序列由服务端生成，不以客户端时间判胜。提交包含 `operation_id`、`file_id`、`base_revision`、`content_hash`、`path`、`device_id`；删除用 tombstone，不能靠扫描缺文件直接判断首次绑定应删除远端。
事务边界：先上传并验证对象，再以 PostgreSQL 事务执行 CAS 版本检查、Revision 写入、当前文件元数据更新和变更日志追加。对象未就绪不得提交 Revision；相同幂等键重试返回同一次提交结果。对象引用只有提交后生效；未引用对象由带宽限期的 GC 清理，不能删除历史保留期内的对象。
对象按 Vault 授权，不能因为知道 content_hash 就允许跨用户读取；预签名链接短时有效且不可越权枚举。文件重名、并发移动、删除后重建、大小写/Unicode 规范化、Windows 不可落盘路径分别定义冲突类型与解决 UI。
### 6.4 本地保存与同步事务
本地先保存，再写入持久化同步 outbox；两步之间崩溃通过 Host 写入日志和启动扫描补偿。队列记录稳定操作 ID、文件版本和已确认服务端版本；网络失败不撤销本地保存。支持暂停、限速、退避、取消、断点恢复；大附件上传进度不得阻塞小笔记保存。
拉取先下载到暂存区并校验摘要，再检查当前内存编辑与磁盘版本，最后经同一 Workspace Service 原子落盘。应用来源事件带 origin/revision，文件监听器去重，避免“收到变更→再次上传”的循环。索引在文件提交后异步更新，失败只影响检索状态，不丢文件。
本地有未保存编辑时，远端变化必须进入待处理/冲突状态，不能覆盖编辑器内存。远端对象不存在、摘要错误、磁盘满、文件被占用均留存可重试任务。游标只在本批内容安全应用或持久化冲突记录后推进。
### 6.5 冲突、删除和历史
base_revision 不匹配返回 409 类冲突与当前 Revision；界面展示本地/远端/共同基线及产生原因。用户可保留本地、保留远端、另存副本或手动合并；选择结果再次以新的基线提交。Markdown 首期可提供三方差异，不做无法解释的自动覆盖；二进制保留两份。
必须覆盖编辑/编辑、编辑/删除、删除/删除、移动/编辑、移动/移动、路径冲突、离线长时间后重连。tombstone 保留期和设备游标过期策略一同设计，离线旧设备不能使已删除文件无声复活。恢复历史版本生成新 Revision，并可撤回恢复操作；清空回收站须说明远端与本地影响。
### 6.6 服务端运维与迁移
交付 Docker Compose、环境变量模板、数据库迁移、初始化管理员流程、TLS 反向代理示例、健康/就绪检查、对象存储初始化及故障排查。禁用默认共享密码；凭据只来自部署配置，不入仓库。
记录请求/提交/冲突率、队列滞后、对象失败率、容量和 GC 状态；日志不包含正文、令牌或密钥。账号配额、最大对象大小、速率和异常重试有服务端约束。PG 与对象存储的备份必须共同验证；做一次实际恢复演练，证明 metadata 引用对象完整。迁移失败回滚程序与数据库版本兼容矩阵随发布包交付。
## 7. 多模态、Provider 与内容能力的阶段工作
- OCR：本地模型优先方案、图片/PDF 页面来源、识别框与原文定位、手工校对、任务取消/恢复、输出 Markdown 与索引、资源预算；远程 OCR 由用户明确选择并展示发送范围。
- 音视频：补充有授权且有标注的验收集、CER/WER、说话人 DER/FAR/FRR 与阈值报告。逐字对齐、重叠语音能力若未完成必须显示不支持，禁止伪造时间戳或人数。模型与许可证重新核查，锁定 revision。
- Provider：在获准账号上验证模型发现、上下文容量、压缩提示、工具调用、流式思考/正文、取消及缓存用量字段。离线协议测试与真实厂商证据分开保存，真实调用设置费用上限，凭据不进入样例包或 CI 日志。
- 导出、数学内容和 Benchmark：先由既有负责人提供第二阶段交接清单，再对接桌面保存对话框、字体/图片/公式/图表资源及批量导出。保留 Document AST / Exporter Adapter，不在 Host 重写一套内容转换器。
- 使用统计：桌面、本地模型与远程 Provider 来源一致；未知与零区分；按实际消耗的分模型柱块、饼图、缓存口径和日期范围在全部主题及 WebView 上回归。统计不等同厂商账单。
## 8. 迁移与向后兼容
| 迁移对象 | 步骤与恢复 |
| --- | --- |
| Web 单 Vault → 桌面多 Vault | 识别旧目录，备份元数据，保持 note_id/file_id 对应关系，校验文件摘要和数量；索引可重建，正文不能覆盖 |
| Fernet → Stronghold | 按 credential_id 迁移、验证、记录版本，失败重试；迁移完成前保留旧存储，不向 UI 返回明文 |
| 内存扩展记录 → 持久化安装库 | 探测用户认可的受管理包、重新校验、不自动继承高权限；重启恢复与包损坏修复必须实测 |
| 旧主题/Skill/Plugin → 社区版本 | ID/来源/版本/摘要关联，未知来源标本地；配置迁移保留备份，用户修改包不能静默覆盖 |
| 首次绑定同步 | 本地/远端清单对账、显示新增和冲突，不以空 Vault 向另一端下发批量删除；绑定信息可撤销 |
| 升级与降级 | Schema 版本门禁，升级前备份；不支持降级的数据库禁止旧客户端写入，提供恢复路径 |
## 9. 实施里程碑与依赖
以下任务全部未验收。开发可以并行，发布必须按门禁顺序推进；预计工期由原型结果和各负责人可用时间评估，不在缺少依据时承诺周数。
| 里程碑 | 任务 ID / 交付 | 前置 | 退出条件 |
| --- | --- | --- | --- |
| M0 范围和契约冻结 | D01 原型；C01 包与来源 schema；S01 Sync v1；安全与迁移 ADR；第二阶段交接 | 当前基线与本规划 | 字段、错误、版本、写入权、平台支持及负责人确认；可运行最小 Host/同步 CAS 原型 |
| M1 本地桌面闭环 | D01–D06；扩展持久化 C02；模型运行适配 | M0 | 不联网可打开/编辑/重开 Vault；Sidecar/凭据/原生菜单可用；重启不丢扩展记录 |
| M2 安全扩展与社区 Alpha | D07；C03 下载/升级/回滚；C04 Theme/Skill/Plugin/MCP 社区 | M1、C01 | 真实包安装执行；来源与权限校验；撤回和失败回滚；未过隔离门禁的代码不可运行 |
| M3 同步服务 Alpha | S02 身份/设备；S03 对象/Revision/CAS；S04 Compose/备份 | S01，可与 M1/M2 开发并行 | 双客户端协议测试、越权拒绝、对象和历史一致、服务恢复演练 |
| M4 桌面同步 Beta | S05 outbox/拉取；S06 冲突/历史/设备撤销；多 Vault | M1、M3 | 两台真实设备断网编辑后无丢失同步；冲突可解释，删除不复活，撤销即时生效 |
| M5 全社区与内容能力 | C05 人设/模板/模型方案目录；前端扩展点；OCR与质量专项 | M2，既有负责人交接 | 各社区真实样例闭环；数据同步分类落实；专项有记录或明确阻塞项 |
| M6 发布候选 | D08；性能/安全/升级/三平台验证；运维手册 | M2、M4、M5 | P0/P1 退出项全部通过；不以豁免未披露的问题宣布第三阶段完成 |
每个任务 PR 包含：用户场景、代码与 Contract、错误和取消路径、自动测试、实际运行证据、迁移与回滚、平台差异。每个里程碑更新“待开始/进行中/待验收/通过/阻塞”及证据链接，不用测试总数计算完成率。
## 10. 建议分工与协作
延续第二阶段模块 ownership；以下为第三阶段建议，须在 M0 由团队确认，不构成人员工期承诺。
| 责任域 | 建议牵头 | 协作与交付边界 |
| --- | --- | --- |
| 总体契约、Rust Host、AI Core Sidecar、Plugin/MCP 安全、Sync Server | 范涵宇；Sync 可拆出独立服务负责人 | 给前端提供稳定 Adapter/Fixture；给内容侧提供文件事件、版本及任务接口 |
| 桌面 Vue、主题与所有社区 UI、同步状态/冲突 UI、窗口与无障碍 | 吉海燕 | 与 Host 对齐菜单/IPC；与内容侧对齐图表、导出和引用定位 |
| Knowledge/Retrieval、Benchmark、内容导出/数学渲染、OCR内容入库 | 杨星萱，具体 OCR 分配待确认 | 先明确既有模块完成状态；负责对应质量与内容语义验收，不默认承担 Rust/服务运维 |
| 社区审核、许可证、发布密钥、服务器运维 | 指定发布维护者，M0 必须落实到人 | 不把高权限发布凭据交给普通包作者；开发审阅与发布审批分开 |
关键交接物：Host DTO 与 mock adapter → 前端；Sync v1 测试向量 → Rust Client/Server 双方；统一文件事件和稳定 ID → Knowledge；包 schema/权限差异 → 社区 UI；AST/资源清单 → 导出；质量数据和授权范围 → Benchmark。接口未就绪可用显式 Fixture 开发，发布验收不得用 Fixture 代替真实链路。
## 11. 验收矩阵与发布门禁
| 类别 | 必测场景 | 证据 |
| --- | --- | --- |
| 桌面文件 | 新建/重命名/外部修改/并发保存/磁盘满/掉电恢复/多窗口 | 原文摘要、事件序列、恢复结果及 UI 实测 |
| IPC/进程 | 非授权来源、跨窗口命令、取消、超时、重启退避、退出进程树 | 失败请求日志与 OS 进程/访问测试，不含秘密 |
| 安装更新 | 恶意 ZIP、篡改摘要、撤回签名、版本冲突、缺依赖、升级中断 | 每类包自动化及一次真实安装/执行/回滚 |
| 主题与交互 | 六主题、长字段、缩放、IME、Tab、滚动、Mermaid、Shiki | 公共组件测试 + 三种 WebView 的实际截图/操作记录 |
| 同步正确性 | 双设备同改/删除/重命名、离线重连、重复请求、乱序通知、游标过期 | 可复现测试向量，最终文件/Revision/摘要一致；冲突保留两端 |
| 同步权限 | 跨用户/Vault对象读取、设备撤销、过期上传链接、配额限制 | 服务端集成与负向测试 |
| 运维 | PG/对象存储重启、备份还原、迁移失败、TLS错误 | 实际部署步骤、恢复日志及未恢复风险 |
| 内容/模型 | 中文/复杂 Markdown、OCR校对、音频标注、Provider真实字段 | 功能与质量分开报告；硬件、版本、样本授权明确 |
M0 先固定基准数据集与测试设备，再制定 P95 启动、打开文件、保存、索引、同步吞吐和内存阈值。测试至少包括 10000 篇小笔记、大文档、100 MiB 附件、频繁重命名和断续网络；量化目标写入 Benchmark 配置后再对外承诺，不能由单台机器一次测量推导通用指标。
CI 运行前端类型/测试/生产构建、后端回归、Rust fmt/clippy/test、协议兼容与迁移测试、包可重复构建/摘要/内容扫描和三平台构建。真实模型、签名和实机测试由受控环境执行，结果作为发布门禁；不在 PR 注入发布密钥。
发布候选必须满足：无已知数据丢失或越权缺陷；核心路径阻断问题清零；备份恢复和上一版本升级通过；许可证与第三方通知齐全；安装/更新签名就绪；社区可撤回发行包；自托管手册可由另一台干净设备复现。尚未完成的功能在 UI 和发布说明中明确标识，阻塞必交目标时不得宣布阶段完成。
## 12. 文档与决策维护
本规划是第三阶段范围和执行总入口；技术选型仍参照[技术栈说明](AI笔记软件技术栈说明-团队版-v2.3.md)，桌面细则参照[桌面需求](../contracts/Tauri-Rust桌面客户端需求说明-第三阶段.md)。后续新增 Host IPC、Sync v1、Community Package/Registry 契约进入 `docs/contracts/`；实现和运维说明分别进入 `docs/development/`、`docs/guides/`；当前临时打包规范仍在根 README，不把临时格式散放到 docs。
M0 必须关闭的决策：平台隔离能力与不支持策略、Host通信及令牌交付、Python打包方式、安装记录与同步元数据库所有权、社区签名/许可证/来源信任、Sync对象保留与GC、首次绑定和删除恢复语义、平台首发支持矩阵、负责人和容量预算。决策记录含备选、选择理由、验证证据和可逆性。
本次核对的官方资料（2026-09-06，仅支持相关技术边界，不表示本项目已接入）：
- [Tauri capabilities](https://v2.tauri.app/security/capabilities/)：约束窗口/WebView 的能力访问；应用自定义命令需纳入显式权限设计，不能自动等同 OS 沙箱。
- [Tauri Sidecar](https://v2.tauri.app/develop/sidecar/)：外部二进制的打包与调用机制；各平台 Sidecar 构建和进程策略仍由项目完成。
- [Tauri Stronghold](https://v2.tauri.app/plugin/stronghold/)：凭据容器接入基础；迁移、解锁与恢复仍需专项设计。
- [Tauri Updater](https://v2.tauri.app/plugin/updater/)：更新分发及签名接入依据；应用签名、升级事务和数据回滚分别验收。
docs/architecture/第二阶段团队分工表.md
+24
View File
@@ -1,5 +1,29 @@
# 第二阶段团队分工表
## 2026-09-06 复核修复补充（不含杨侧验收）
- Agent 增加断点续读、有界重连和手动恢复；连接中断不再隐藏仍在运行任务的取消入口。
- 本地扩展安装库支持重启恢复、包摘要复核和受管理 ZIP 卸载清理。变更后的包需重新安装审查；目录安装保留用户源码。
- 工作区已挂载编辑器右键及扩展工具栏入口，与已有 palette/详情命令共同使用后端命令校验；执行上下文保留选区快照。
- 新增真实 Mermaid 6 图型 × 6 主题回归入口，以及参考转写 CER/WER/DER 评分和受限 Provider 连接探针。工具使用与边界见 `docs/development/第二阶段补充验收工具.md`。
- 逐字强制对齐、多人重叠分离仍未实现；无标注录音不能完成质量验收，真实厂商专项也不能用一次连接测试替代。以下较早记录中的测试数和延期状态属于历史基线。
## 2026-09-05 当前完成情况补充（不含杨侧验收）
以下状态补充早期任务清单，历史未勾选项不再单独作为实时完成率依据。杨星萱负责的 Benchmark、检索调优、导出及函数图像不在本次验收范围。
- A/B/C/C.1/D 基础工程已落地；E 的离线协议验证已通过，真实目标厂商专项待完成。
- Theme：补齐 SemVer 最低版本拒绝、文件/URL/ZIP 共用校验及安装前隔离视觉预览。
- Mermaid：真实编辑器及 Markdown 预览接入缩放、重置、大图查看；编辑器预览复制导致的异步标记丢失已修复。
- Agent Trace：支持关键词、事件类型、工具及仅错误筛选，保留树的祖先节点和引用定位。
- F：本地 Qwen3-ASR、ERes2NetV2、Bekko 已完成 37 分 16 秒录音的 CUDA 转写、片段聚类、笔记及向量检索闭环，约 661 秒生成 441 片段；无参考标注，质量专项保持未完成。
- Provider：卡片显示启用状态，支持直接启停与保存失败反馈。
- Plugin context_menu/toolbar 按已有本地计划仍是后续增强，当前实际挂载 command_palette 与详情命令；不将声明 Contract 视为已挂载。
- 逐字强制对齐、多人重叠语音未实现；说话人阈值、准确率、真实厂商专项未验收。Tauri/Rust、生产沙箱仍属于后续阶段。
本轮自动化基线为后端 577 项、前端 280 项及前端生产构建通过。长录音无标注，测试通过不等于质量或所有第二阶段专项全部完成。详细证据见 `docs/development/阶段F收尾验收记录.md`；本地运行文件不提交。
## 一、阶段目标
第二阶段延续第一阶段已经形成的模块边界，重点推进多模态输入、MCP 与 Plugin 扩展、更多 Provider、RAG / Agent Benchmark、多格式导出、主题社区格式、Agent Trace 可视化、Mermaid 渲染和函数图像绘制。
docs/contracts/Tauri-Rust桌面客户端需求说明-第三阶段.md
+5 -3
View File
@@ -2,7 +2,7 @@
状态：需求预留，尚未实现桌面客户端。本文不表示已有可调用的 Tauri Command 或可发布安装包。
基线日期：2026-09-05。
基线日期：2026-09-06。第三阶段完整范围与实施顺序见[第三阶段实施规划](../architecture/第三阶段实施规划.md)。
## 1. 目标与边界
@@ -21,7 +21,9 @@
桌面客户端顶部菜单栏的 **段落 → 导入为笔记属性…** 预留元数据格式导入功能，与标题、正文、列表等段落操作归组。它处理笔记内容中的元数据，不是主题包安装入口。
建议稳定的前端命令标识为 `editor.import-note-properties`，仅为设计标识，尚未注册为 Tauri IPC。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
稳定的前端命令标识为 `editor.import-note-properties`，已进入前端 v1 命令目录，但属性转换处理器与 Tauri IPC 尚未实现。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
Markdown 格式（含警告框）与元数据共用 `editorCommandService` 的能力查询和命令分发接口，详见 [警告框与桌面编辑命令开发说明](../development/警告框与桌面编辑命令开发说明.md)。Host 根据 supported / enabled 显隐或禁用菜单，不能把已预留的命令 ID 当作已可执行能力；原生快捷键不绕过活动文档、只读和冲突检查。
### 2.2 输入与转换规则
@@ -55,7 +57,7 @@
| 外观与导航 | 继承主题、代码配色、相对纸页宽度、文件／大纲切换 | 窗口缩放、高 DPI、深浅主题下无截断；键盘导航完整 |
| 发布 | Windows、macOS、Linux 构建与安装验证；签名、升级及回滚方案 | 未准备好签名和回滚前不启用自动更新；平台差异有说明 |
云同步服务、移动端和主题社区服务端不因本文自动纳入第三阶段必交范围；需要单独确认范围与接口。
根据 2026-09-06 的范围确认，各扩展社区、独立 Sync Server 和桌面同步客户端正式纳入第三阶段，具体工作包与验收门禁见[第三阶段实施规划](../architecture/第三阶段实施规划.md)。本文聚焦桌面客户端细则；移动端仍不属于本阶段首个稳定版本范围。
## 4. 开发顺序与验收
docs/contracts/后端接口契约-开发版.md
+10 -1
View File
@@ -42,7 +42,7 @@ Web 联调阶段只暴露后端通过 `APP_VAULT_PATH` 配置的单一 Vault，
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/workspace` | 获取当前 Vault、文件数和索引同步状态 |
| POST | `/api/workspace/open` | 打开配置的 Vault；磁盘路径集变化时重建索引 |
| POST | `/api/workspace/open` | 打开配置的 Vault；路径集变化时先登记文件与 FTS，再调度后台向量更新 |
| GET | `/api/workspace/tree` | 获取真实 Markdown 文件和目录树 |
| POST | `/api/workspace/folders` | 新建目录 |
| POST | `/api/workspace/folders/rename` | 重命名目录并同步 Note 路径 |
@@ -198,3 +198,12 @@ RunCancelled
- `GET /api/index/status` 额外返回 `total_notes: int` 和 `total_blocks: int`，来自当前 SQLite 索引；未建立内容索引时为 0。
- `GET /api/permissions/policy` 返回 `Record<string, "allow" | "confirm" | "deny">`，值取自后端当前生效的 PermissionPolicy。此接口只读，不提供全局修改能力，运行时权限确认仍使用既有 Agent permission endpoint。
## 2026-09-06：后台索引补充
- `POST /api/workspace/open` 返回可使用的 WorkspaceSnapshot，不等待向量推理。
- `PATCH /api/notes/{note_id}` 成功代表正文、元数据和 FTS 已保存；后台向量失败不撤销这次保存。
- `GET /api/index/status` 新增 `vector_refresh_required: boolean`，表示工作区或笔记存在向量待处理标记。该字段不是进度百分比；任务失败时也可为 true。
- `POST /api/index/rebuild` 仍仅支持全量重建，并等待结果；不要将上述异步语义推广到所有索引 API。
状态、恢复限制与验证见 [工作区后台索引与保存开发说明](../development/工作区后台索引与保存开发说明.md)。
docs/development/Knowledge与Retrieval-Core开发说明.md
+6
View File
@@ -235,3 +235,9 @@ rag.search
- RAG Benchmark 已建立：`POST /api/benchmarks/rag/runs` 创建即返回 queued、后台 Task 执行，
通过 SSE 实时推送进度，报告含逐 Case 结果与 `total_cases` / `successful_cases` / `failed_cases` / `failure_rate`。
- Agent Benchmark 暂缓，待 Agent Runtime 完成后交付。
## 2026-09-06 实现补充
上文的 MVP 同步说明是早期基线。当前打开 Vault 和 HTTP PATCH 保存已拆分即时元数据 / FTS 与后台向量计算；手动全量重建仍等待完成。生产 Embedding 使用实际模型和隔离向量空间，HashEmbedding 仅用于测试。
后续维护以 [工作区后台索引与保存开发说明](工作区后台索引与保存开发说明.md) 的实现边界、状态和验证步骤为准。
docs/development/Markdown渲染检查.md
+43
View File
@@ -0,0 +1,43 @@
# Markdown 渲染检查
日期：2026-09-05。范围为当前工程启用的 CommonMark、GFM、Milkdown Crepe 扩展及静态 Markdown 预览，不代表所有 Markdown 方言。
## 本次修复
- 行内代码：保留普通输入规则，为绕过 `handleTextInput` 的浏览器文本输入与输入法组合结束增加单反引号补偿处理。跳过代码节点、已有代码标记、转义反引号；不改写文件中的转义文本。同时识别先输入空反引号对、再移入填字的路径，并在转换后保留继续输入的代码标记；空反引号对序列化时的转义不会阻断识别。回归测试覆盖缺失事件数据、替换文本、延迟组合结束与粘贴/撤销排除。独立浏览器编辑器已实测逐字输入、段落/行内换行，以及先输入反引号对再向中间填入 s。
- 工具栏：未选中文字时，行内代码按钮可切换后续输入的代码标记；此前上游命令在空选区直接返回。
- 样式：工作区与静态预览使用主题代码背景、文字及边框变量，避免行内代码与正文难以区分。
- 静态预览：补齐 `$...$`、`$$...$$` 和编辑器保存的 `LaTeX` 围栏公式；代码中的公式符号保持原文。公式使用 KaTeX，禁用可信 HTML 命令并经过最终清理。
- 静态表格：恢复 GFM 中间、右侧对齐，避免通用单元格样式覆盖对齐属性。
## 检查矩阵
| 格式 | 工作区编辑 | 静态预览 | 验证 |
| --- | --- | --- | --- |
| H1–H6 | 标题节点 | 标题元素 | 新增格式矩阵 |
| 粗体、斜体、删除线 | 标记渲染 | strong / em / del | 新增格式矩阵 |
| 单反引号、多反引号代码 | 行内代码；保存保留定界符 | code，转义内容不执行 | 加载、普通键入、组合输入、工具栏与序列化 |
| 有序、无序、嵌套列表 | 列表节点 | ol / ul | 新增格式矩阵 |
| 任务列表 | GFM 任务项 | 禁用复选框 | 格式矩阵及 GFM 输出 |
| 引用、分割线 | 原生节点 | blockquote / hr | 新增格式矩阵 |
| 链接、引用式链接、图片 | Crepe 原生组件 | 安全链接及图片 | 静态格式矩阵；图片实际加载受路径可访问性影响 |
| GFM 表格 | 表格组件 | table；主题边框和对齐 | 格式矩阵、对齐规则检查 |
| 硬换行、转义符 | 编辑器保留 Markdown 语义 | br / 转义文本 | 静态格式矩阵 |
| 围栏代码、未知语言 | CodeMirror / Shiki | Shiki；未知语言回退纯文本 | 既有语言测试与新增回退测试 |
| 行内、块级数学公式 | Crepe LaTeX | KaTeX | 编辑器格式矩阵与新增静态公式测试 |
| Mermaid | 图形预览 | SVG 图形 | 既有主题、错误回退、大图文字及缩放测试 |
| YAML 元数据 | 独立属性栏 | 普通 Markdown 场景不视为属性表单 | 既有标题、标签、引号、锚点、编码与往返测试 |
| 自定义字号 span | 装饰渲染 | 清理后 HTML | 既有字号标记测试 |
| 原始 HTML | 编辑器按自身 HTML 节点规则保留 | 清理后展示，脚本及事件属性移除 | 新增安全 HTML 测试 |
源码模式展示 Markdown 原文，不隐藏反引号、星号和围栏。脚注、定义列表、Wiki 双链、图表以外的自定义围栏等未作为独立渲染扩展启用，不在“已支持”范围内。
2026-09-06 补充：GitHub alerts 与 Obsidian callout 已在工作区和静态预览接入，包含常用类型/别名、自定义标题、嵌套与折叠。语法、命令接口与验证方法见 [警告框与桌面编辑命令开发说明](警告框与桌面编辑命令开发说明.md)。
自动检查覆盖解析、DOM 输出、部分编辑交互、保存往返和主题变量。尚未完成所有浏览器、所有输入法及每个主题的逐页截图比对；不能据此宣称像素级视觉验收通过。测试使用隔离样例，没有修改用户笔记。
## 2026-09-06 Mermaid 补充
补齐大图居中与完整适配、显示宽度缩放基准、滚轮速度限制、鼠标位置补偿及重开滚动位置清理。修复 Milkdown 段落内边距挤出 foreignObject 标签框的问题，浏览器核对 1、many、contains 完整显示。
实现原理、测试命令和视觉复核步骤见 [Mermaid 预览与缩放开发说明](Mermaid预览与缩放开发说明.md)。
docs/development/Markdown语法预设与外部文件刷新.md
+48
View File
@@ -0,0 +1,48 @@
# Markdown 语法预设与外部文件刷新
日期：2026-09-06。
## 1. 设置入口与范围
“设置 → 编辑器 → Markdown 语法预设”管理语法与编辑行为，独立于“标题样式”的字号、字体和字重设置。
支持 ATX/Setext 标题、无序列表标记、有序列表递增、代码围栏、裸链接识别、数学公式、警告框、Mermaid、代码行号、自动换行、缩进和工具栏新建代码块的默认语言。Setext 只作用于 H1/H2。提供扩展、GitHub 和基础三组内置配置，支持最多 20 个命名自定义预设，同名保存替换旧配置。
配置保存在本机 localStorage 的 `markdown-preferences`，读取时校验。静态预览即时应用；写作编辑器在下次打开时应用，避免切换设置重建正在编辑的文档。写作模式保存会统一整篇正文的语法标记，源码模式保留手写语法。关闭扩展后对应内容按普通 Markdown/代码展示。
本次不是完整复制 Typora：未提供上下标、高亮、智能标点、physics 包及导出公式选项。基础配置仍支持现有 GFM 表格等功能。
## 2. 主题与折叠
六个主题共用语义颜色和表单控件。内置浅色、深色、护眼更新为 1.3.0；纸间时光 1.8.0；Ocean Blue 1.5.0；Midnight Purple 2.3.0。社区预览增加语法控件和标题折叠样本。
标题箭头使用统一 CSS 形状，默认隐藏，悬停标题或键盘聚焦按钮时显示；无悬停能力的触摸设备保持可见。用户自定义标题外观独立于主题配色。
## 3. 外部文件刷新与保存保护
Web 当前采用串行后台轮询：前一次完成后间隔两秒，在窗口聚焦时也检查。隐藏页面暂停读取，卸载移除监听。此机制不是原生文件事件监听；第三阶段可由 Tauri 文件事件替代。
`GET /workspace/tree` 检查磁盘新增、删除和重命名，为新文件登记元数据及全文索引，向量任务继续后台执行。前端保留文件夹展开状态，并丢弃过期请求响应。读取失败保留旧树并显示重试入口。
当前打开且未修改的文件检测到外部正文变化后更新编辑器；存在本地编辑时保留缓冲区，停止自动保存并提示冲突。重新加载磁盘版本需要用户确认。原文件删除或移动后，隐藏不可用的重新加载入口，提供下载当前 Markdown 副本和确认关闭笔记；取消关闭或确认期间正文改变时保留缓冲区。关闭后可重新选择其他文件，不再阻塞导航。`PATCH /notes/{note_id}` 新增可选 `expected_content_hash`（原始正文 UTF-8 SHA-256，64 位小写十六进制），保存前校验，不匹配返回 `NOTE_CONTENT_CONFLICT`，防止覆盖外部修改。
范围限制：现有文件的外部正文修改会刷新当前编辑器，但本轮目录检查不会据此重建其搜索索引；可通过重建索引同步检索内容。
## 4. 验证方法
```powershell
cd frontend
npm run test
npm run build
cd ..
backend/.venv/Scripts/python.exe -m pytest backend/tests/test_workspace.py backend/tests/test_workspace_background.py -q -p no:cacheprovider
```
手工验证：
1. 保存并重新应用命名预设，刷新后确认保留；重新打开笔记，检查 Setext、列表和代码围栏的源码。
2. 切换六个主题，在社区预览和工作区检查控件、警告框、标题箭头；移出标题后箭头隐藏，Tab 聚焦仍可操作。
3. 在系统文件管理器新增、重命名、删除 Markdown 文件，保持前端可见，确认树自动更新且目录展开状态保留。
4. 分别在正文未修改、有未保存编辑时从外部修改同一文件，验证自动加载与冲突保护；拒绝重新加载应保留编辑内容。
本次自动验证覆盖预设持久化、解析选项隔离、写作语法输出、标题折叠、树刷新竞态、外部文件登记及保存冲突。
docs/development/Mermaid预览与缩放开发说明.md
+46
View File
@@ -0,0 +1,46 @@
# Mermaid 预览与缩放开发说明
> 本文档用于前端开发和图表渲染联调。
>
> 更新日期：2026-09-06。代码基线：`a5c44c4`。
## 当前实现
工作区和静态 Markdown 通过 `mermaidService.ts` 串行渲染，使用主题变量与 Mermaid strict 模式。工作区由 `mermaidPreview.ts` 发布当前版本预览；`DiagramInteractions.vue` 提供缩放和大图交互。
- 行内按钮在悬停或键盘焦点进入时显示；触屏保留操作入口。
- 行内中键点击 SVG 后进入滚轮缩放，移动鼠标或窗口失焦退出。
- 大图直接使用滚轮缩放，缩放范围为 20%～500%。
- 行内首次缩放以实际显示宽度为基准，避免受容器限制的图表跳回原始宽度。
- 大图打开时根据原始比例与可用窗口宽高确定 100% 基准，清除旧滚动位置并居中；100% 不一定等于 SVG 原始像素宽度。
- 滚轮增量按时间和 delta 限制，宽度变化使用 180ms 过渡；支持减少动态效果偏好。
- 过渡期间根据鼠标位置补偿内外滚动容器。受滚动边界限制时，不能保证鼠标锚点在任意位置绝对不动。
## 文字裁切的原因与修复
Mermaid 的 HTML 标签放在固定尺寸的 SVG `foreignObject` 中。Milkdown 的正文段落规则会给内部 p 增加上下各 4px 内边距，导致关系标注超出文字框。工作区现在对图表内部 p 清除段落内边距和外边距，并继承图表行高、字重。
大图复制 SVG 时保留 `foreignObject`，先清理嵌入 HTML，再清理整个 SVG，移除脚本及事件属性。不能为了保留标签而关闭安全清理。
类图未声明方法时，其方法区为空是正常结构。排查时应先对照源码，再检查 DOM 标签、尺寸和裁切范围。
## 验证方法
在 frontend 目录执行：
```powershell
pnpm exec vitest run src/components/common/DiagramInteractions.spec.ts src/features/editor/diagramIntegration.spec.ts src/features/editor/mermaidPreview.spec.ts
pnpm exec vue-tsc -b
```
使用 Vault 中“功能演示/03 Mermaid 图表集.md”手动检查：
1. 检查流程图、时序图、类图、状态图、ER 图和甘特图。
2. 类图的 1、many、contains 应完整显示；查看内部 p 的 padding 应为 0。
3. 甘特图大图初始应完整适配；放大后可通过滚动条查看超出部分。
4. 连续滚轮输入不应首次跳大；移动鼠标后行内滚轮模式退出。
5. 关闭并重开大图，不保留上次滚动位置。
浏览器实测中，关系标注文字高度约 16.5px，对应 16.5px 的 SVG 标签框；contains 约 24px，对应 24px 框。该结果不替代所有主题、字体、浏览器的视觉验收。
相关格式范围见 [Markdown 渲染检查](Markdown渲染检查.md)。
docs/development/Plugin-Command与Settings开发说明.md
+6
View File
@@ -115,3 +115,9 @@ pnpm build
阶段 D 测试覆盖注册/注销生命周期、位置过滤、参数与 Context 校验、上下文裁剪、设置影响命令执行、声明式 Secret Resolver 与越权拒绝、真实 MCP Command Target 与 Agent Tool 隔离、必填 Secret 传递、外部 Schema 引用拒绝、定长 Secret Reference、篡改引用的跨命名空间阻断、Secret 删除与卸载失败回滚、Provider/通用凭据命名空间隔离、五类设置字段、Schema 版本冲突、Secret 密文与清理、损坏存储、空 Command 列表等无效贡献文件、OpenAPI 路径、前端 Service 请求格式、Host 状态展示和动态 Secret 表单。
生产构建仍会报告现有大 Chunk 警告，不影响构建成功；该问题属于前端按路由和 Markdown 依赖拆包的后续性能任务。
## 2026-09-06 安装状态补充
ZIP 导入和安装日志已接入。安装路径、包摘要、启用状态及 Plugin 授权可以在本地恢复；用户目录安装源与受管理 ZIP 解压目录使用不同卸载边界。功能示例包已入库，远程社区服务仍属计划。
详见 [扩展安装持久化与社区包开发说明](扩展安装持久化与社区包开发说明.md)。
docs/development/主题组件覆盖检查.md
+46
View File
@@ -0,0 +1,46 @@
# 主题组件覆盖检查（2026-09-05）
本次检查仓库内 3 个内置主题和 3 个社区预设，共扫描 105 个前端源文件的组件与语义样式变量。用户自行导入的第三方 CSS 不在仓库中，不据此声称已验收。
## 范围与结果
扫描到 70 个颜色、字体、间距、圆角、阴影、动效和行高变量引用，修复后未定义引用数为 0。颜色及控件样式由共享 token、组件样式和主题覆盖共同提供；继承共享样式不等于未适配。新增 `themeCoverage.spec.ts` 保持全源文件变量引用检查，并检查社区预设的交互色、Markdown 色及 color-scheme。
| 主题 | 新版本 | 修正 |
| --- | --- | --- |
| Light / Dark | 1.1.1 | 原生表单控件底色及浏览器 color-scheme |
| Sepia | 1.1.1 | 控件底色、焦点、按下态、柔和悬停色 |
| Ocean Blue | 1.3.1 | 活动态、反色文字、禁用色、Markdown 表格与标记色 |
| Midnight Purple | 2.1.1 | 深色 color-scheme、原生控件及上述交互/Markdown 色 |
| 纸间时光 | 1.6.1 | 新增分模型统计、缓存说明、数据提示及大图查看样式 |
MCP JSON 编辑器错误引用的 `--font-family-mono` 已改为共享 `--font-ui-mono`。全局原生控件底色使用零优先级选择器，组件和主题仍可覆盖。旧版社区主题需在主题页点击“更新”；不会覆盖用户自行修改的已安装 CSS。
这是全仓库静态样式覆盖和功能回归检查，不是所有屏幕尺寸下的逐页视觉验收，也不把变量有定义等同于对比度全部达标。
## 用量与交互
柱状图按日期和来源聚合，再以 Provider ID + 模型 ID 分割同柱。模型分段之和与来源总计一致；同一来源使用色彩深浅区分，提供商柱保留斜纹。缺失计数仍显示“未提供”，不补估历史值。
缓存命中率只对同时提供命中和未命中计数的请求计算：命中合计除以这些请求的输入合计；缺少输入时分母使用命中加未命中。本次本地记录检查中的两次 DeepSeek 调用，厂商明确报告命中 0，未命中分别为 1015、1219，写入缺失。没有新增外部模型调用。
AI 对话 Enter 发送，Shift+Enter 换行，输入法确认和长按 Enter 不触发重复发送。Mermaid 普通预览控件在悬停/键盘聚焦时显示，触屏保留按钮；大图可直接滚轮缩放，普通预览需中键启用。滚轮归一化并按时间限制缩放速度，每秒连续输入不会无限叠加瞬时倍率。
## 下拉与折叠控件补充
编辑器外观行统一为标签、38px 控件、说明三层，避免只有代码主题字段带说明时将其他控件拉偏。补齐所有原生 details 的 `ui-disclosure` 样式，统一折叠箭头、展开背景和边框。下拉框增加共享箭头、选项配色、焦点及禁用态；支持 `appearance: base-select` 的浏览器使用可主题化选项面板，其他浏览器保留原生选择行为并应用可支持的颜色。原生系统弹出层的完整装饰不能仅靠 CSS 在所有浏览器中保证。
## 6107b7f 后续遗漏修复
- 任务、MCP、主题导入、社区预览、Agent 权限确认接入 AppDialog：原生顶层遮罩、内部滚动、祖先滚动锁及焦点归还。滚动锁使用引用计数，嵌套弹窗关闭不会提前解锁背景。权限确认禁止 Escape/点击遮罩隐式关闭；MCP 忙碌时禁止隐式关闭。人设弹窗补用同一滚动锁。
- 修复音视频三处、请求 JSON 一处 textarea 的单行高度覆盖；使用 textarea 样式、最小高度和纵向拉伸。单行高度规则仅匹配 input.input 与 select。
- Agent 工具原文和 Trace 完整数据接入 ui-disclosure，并合并重复容器规则。Provider 预设选中态使用主题强调色。
- 音视频页面标题和内容宽度对齐共享布局。纸间时光补充工具选择卡片的轻量纸张边框，版本 1.6.2；旧版更新入口及应用后 CSS 刷新已有自动测试。其余社区主题复用公共控件修复，未无意义提升包版本。
- 安装前预览加载真实 tokens.css 与 features.css，并增加多行/单行/下拉/禁用/展开折叠/错误标签/Markdown/图表配色及长标识样例；保留无脚本 sandbox 与 CSP，不改宿主主题。
验证：六主题在 1280、600、360 像素浏览器窗口下检查；样例 iframe 内容宽度分别为 660、508、268px，均无水平溢出，多行框均为 100px。实际任务页弹窗矩形覆盖 1280×720 全视口，焦点进入表单，Escape 关闭后回到新建按钮；实际术语校对框为 100px 并支持纵向拉伸。
可重复的隔离浏览器入口与操作说明位于 `frontend/tests/visual/README.md`，支持六主题、长内容弹窗和真实编辑器输入。测试不访问用户笔记或调用模型。组件样例矩阵并不等同于所有业务数据、浏览器和完整色彩对比度验收；不声称完成未执行的全页面截图或性能优化。
最终验证：56 个测试文件、323 项前端测试通过；生产构建通过。复扫结果：未接入共享样式的 details 为 0，误用 input 类的 textarea 为 0。
docs/development/前端构建分块优化开发说明.md
+43
View File
@@ -0,0 +1,43 @@
# 前端构建分块优化开发说明
> 更新日期：2026-09-06。基于 main 的 64af068 进行构建对比；以下结果为本地生产构建，不是网络耗时或性能评分。
## 当前方案
- Mermaid 由静态导入改成第一次渲染或校验图表时动态导入。复用加载 Promise，加载失败清除缓存以允许重试，主题初始化与渲染继续串行执行。
- CodeMirror 基础模块、ProseMirror 和 Milkdown 分组缓存。仅显式选中的模块进入手动分组，不吸收所有传递依赖。
- CodeMirror 语言解析器、全部 Shiki 语法和 Mermaid 图型继续按需加载。不能将所有语言打入 editor vendor，否则会反而增加编辑器的首次加载量。
- KaTeX 按实际安装版本分组，避免合并项目版本和依赖内版本。不强制升级第三方依赖的数学解析器。
- 启用 Vite manifest，并提供 build:report 脚本用于持续比较入口静态依赖。
## 构建观察
数值按十进制 kB 计算。静态闭包包括入口 JS 与递归 imports，去重后求和；不包含 CSS、字体、运行时动态导入或浏览器缓存。gzip 为每个 JS 文件压缩后求和，不代表服务器必然启用该压缩。
| 检查项 | 优化前 | 优化后 |
| --- | --- | --- |
| 聊天页静态 JS 闭包 | 约 1563.5 kB | 约 894 kB |
| 聊天页闭包 gzip | 约 451.6 kB | 约 292 kB |
| VisualMarkdownEditor 单包 | 约 1145.8 kB | 约 20 kB，核心依赖转入独立块 |
| 首屏静态 JS 闭包 | 约 409.7 kB | 约 409 kB，基本不变 |
组件单包缩小不等于整个编辑器只需要 20 kB。编辑器仍需要加载基础框架、核心依赖和实际用到的语法。此次主要减少普通 Markdown 页对 Mermaid 的提前加载，并改善模块缓存边界；未测量真实启动耗时，不能声称首屏提速比例。
## 验证方法
在 frontend 目录执行：
```powershell
pnpm build
pnpm build:report
pnpm test
pnpm exec vite preview --host 127.0.0.1 --port 4173
```
build:report 读取 dist/.vite/manifest.json，输出入口闭包大小与最大的 15 个 JS 块。对比时保存相同构建环境的两份输出；更新依赖后需重新测量。
本轮前端 345 项测试通过，类型检查及生产构建通过。已在生产预览打开工作区和真实 Mermaid 示例笔记，确认编辑器与 SVG 加载，未发现控制台 error。Shiki 全语言覆盖仍由既有语言测试检查。
## 保留的大块与边界
C++、Emacs Lisp 等语法、Oniguruma WASM、部分 Mermaid 图型及 Mermaid 核心仍可能超过 500 kB。这些资源保留按需加载，不裁减语言支持，也不提高警告阈值来隐藏问题。首次打开复杂图表或对应语言仍有加载成本；后续可基于真实请求和设备数据评估 Worker、资源预热及库版本升级。
docs/development/多模态管线与模型运行开发说明.md
+8
View File
@@ -144,3 +144,11 @@ cd backend
.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
```
## 2026-09-05 长录音与 Provider 状态补充
- 附件上传上限为 128 MiB。超过 25 MiB 的音频必须明确选择 `local_only=true`；可联网任务仍限制为 25 MiB，前后端及路由均检查。解码时长仍限制为一小时。
- 本地解码允许跳过少量损坏音频包，按包中可取得的时长补静音，并返回 `MEDIA_CORRUPT_PACKETS_SKIPPED:<数量>`。超过 100 个损坏包则失败；缺少有效包时长时无法承诺时间对齐，应结合原音频复核。此处理不能恢复丢失语音。
- Provider 卡片显示“已启用/已停用”，支持直接启停。保存成功后更新状态；失败保留原状态。停用或保存期间禁用测试与刷新模型操作。
- 37 分 16 秒的用户录音已完成 CUDA 转写、片段级说话人聚类、笔记生成、本地向量索引及检索命中。无参考标注，不报告准确率。详见《阶段F收尾验收记录》的长录音补充；此前短样本记录保留为历史证据。
docs/development/工作区后台索引与保存开发说明.md
+67
View File
@@ -0,0 +1,67 @@
# 工作区后台索引与保存开发说明
> 本文档用于团队开发和联调，说明 Web Workspace 的打开、保存与后台向量更新边界。
>
> 更新日期：2026-09-06。代码基线：`a5c44c4`，已随 PR #31 合并到 `main`。
## 当前实现
打开知识库和保存正文不再等待 Embedding 推理。Markdown 是正文载体；SQLite 元数据和 FTS 可先使用，向量结果随后更新。这里的后台任务是 AI Core 进程内的 asyncio 任务，不是独立队列服务，也不是 Tauri 后台服务。
| 操作 | 请求完成前 | 后台阶段 |
| --- | --- | --- |
| 打开 Vault | 校验配置路径；路径集合变化时登记新文件、删除失效记录并返回真实文件树 | 标记需要更新时自动全量计算向量 |
| HTTP PATCH 保存笔记 | 写正文、解析元数据、更新 FTS、清理旧向量并持久化待处理标记 | 按笔记计算向量，核对版本后写入 |
| 手动全量重建 | HTTP 请求仍等待全量重建结果 | 推理期间不持有 Vault 写锁，提交阶段原子替换 |
`note_service.update_note` 的 `defer_vectors` 默认仍为 `False`；HTTP PATCH 路由显式传入 `True`。创建、移动及其他内部调用不能据此宣称已经全部后台化。
## 代码入口
| 文件 | 职责 |
| --- | --- |
| `backend/app/services/workspace_service.py` | 文件登记、打开工作区、触发后台任务 |
| `backend/app/services/note_service.py` | 正文保存、即时元数据与全文索引 |
| `backend/app/services/index_service.py` | 后台任务去重、全量与单笔记向量更新、状态与关闭 |
| `backend/app/services/coordination.py` | Vault 写入互斥 |
| `frontend/src/features/vault/VaultEntry.vue` | 等待提示、超时错误及重试 |
| `frontend/src/stores/editor.ts` | 保存快照、状态及连续输入补存 |
| `frontend/src/components/common/AppShell.vue` | 每轮请求结束后间隔 5 秒刷新索引状态 |
## 一致性与恢复
- 文件登记和保存的待处理标记与索引写入使用同一 SQLite 事务。
- `workspace_vectors_pending=1` 表示工作区全量向量需要更新；`note_vectors_pending:<note_id>=1` 表示该笔记有待处理工作。
- 模型推理在写锁外执行；提交前重新核对磁盘快照或笔记记录。版本不一致时不写入旧结果，后台循环重新处理。
- 保存接口成功后，“已保存”代表正文和全文索引已写入，不代表向量已经就绪。向量不可用期间，语义检索可能尚未覆盖刚保存的内容。
- 模型失败保留待处理标记，正文不会因后台失败回滚。重新打开 Vault 可再次调度；不是保证持续重试的生产任务队列。
- 关闭后端会取消进程内后台任务；持久化标记保留。任务详情、活动任务 ID 和错误信息仍主要保存在内存，重启后不会保留完整任务历史。
- 前端保存期间继续输入时，当前请求完成后仍保持 dirty，并安排后续自动保存；落盘失败显示 save_failed。
## 状态与接口
`GET /api/index/status` 新增 `vector_refresh_required: boolean`，表示仍有待处理标记。它与 `status` 一起使用：失败、等待和运行中都可能需要向量更新。`pending_jobs` 不是百分比或剩余笔记数。
打开 Vault 请求超时为 15 秒；诊断和状态请求为 10 秒。超时表示前端停止等待，不保证服务端操作已经取消，不应因此认定保存成功或失败。
## 验证方法
在 backend 目录执行：
```powershell
uv run pytest tests/test_workspace.py tests/test_workspace_background.py -q -p no:cacheprovider
```
在 frontend 目录执行：
```powershell
pnpm exec vitest run src/services/apiClient.spec.ts src/stores/editorSave.spec.ts
```
回归覆盖：模型等待期间仍可打开工作区和创建目录、重复打开去重、快照变化重算、连续保存保留最新标题和标签、模型失败不回滚正文、重新打开恢复处理、请求超时及自动补存。
手动联调请使用测试 Vault：新增 Markdown 后打开；计算期间修改并保存两次；重新打开确认最后内容；在隔离配置中模拟模型不可用，核对正文保留与索引错误分别显示。
## 当前限制
路径登记按磁盘与数据库的路径集合判断变化，不等同于完整外部文件监听。多进程后台调度、生产任务队列、完整失败历史和原生文件监听属于后续工作。不要把当前进程内互斥用于推断多实例安全性。
docs/development/扩展安装持久化与社区包开发说明.md
+45
View File
@@ -0,0 +1,45 @@
# 扩展安装持久化与社区包开发说明
> 本文档用于 Skill、Plugin 安装及社区示例包开发。
>
> 更新日期：2026-09-06。代码基线：`a5c44c4`；社区服务仍处于第三阶段规划。
## 当前实现
`backend/app/extensions/archive.py` 解析上传 ZIP，`installed.py` 为运行时增加本地安装日志。`extension-installations.sqlite3` 位于 data_dir 下，记录包路径、内容摘要、启用状态、插件授权及受管理目录；成功解压的包保存在 `extension-packages`，供后续命令读取。
| 环节 | 行为 |
| --- | --- |
| 安装 ZIP | 最大 10 MiB，解压总量最大 50 MiB，最多 2048 条目 |
| 路径检查 | 拒绝目录穿越、链接、特殊文件、加密条目、重复及大小写冲突路径 |
| 包布局 | 根目录或唯一顶层目录包含 skill.yaml / plugin.yaml |
| 重启恢复 | 校验目录和内容摘要后恢复安装状态；插件恢复授权 |
| 包内容变化 | 不自动启用变化后的包，需重新安装并检查权限 |
| 卸载 | 受管理 ZIP 目录可清理；用户目录安装源不删除 |
安装持久化不等于操作系统级沙箱、签名验证或远程社区服务上线。生产隔离、社区发布治理与签名机制仍按第三阶段规划推进。
## 社区示例
源码与打包入口位于 `backend/extensions/community/`。`note-reviewer` 为笔记审阅 Skill，`markdown-workbench` 为可执行 Plugin。功能、安装和测试输入见该目录 README 与各包 README。
重新打包：
```powershell
cd backend
uv run python extensions/community/build_packages.py
```
仅在需要更新社区示例产物时执行，并核对 dist 中 ZIP 和 index.json 是否与源码一致。
## 验证方法
在 backend 目录执行：
```powershell
uv run pytest tests/test_extension_archive.py tests/test_installed_extensions.py tests/test_community_packages.py -q -p no:cacheprovider
```
手动使用测试数据目录安装示例包，启用并调用；重启后端后确认状态恢复。对包副本修改内容再重启，应出现恢复失败提示。卸载目录安装包时，原目录应继续存在。
生产社区规划见 [第三阶段实施规划](../architecture/第三阶段实施规划.md)，命令和设置接口见 [Plugin Command 与 Settings 开发说明](Plugin-Command与Settings开发说明.md)。
docs/development/标题折叠与样式开发说明.md
+52
View File
@@ -0,0 +1,52 @@
# 标题折叠与样式开发说明
日期：2026-09-06。范围为工作区写作模式的章节折叠，以及正文标题外观偏好。
## 1. 章节边界与交互
H1–H6 标题旁在悬停时显示统一折叠箭头；键盘聚焦也显示，触摸设备保持可见。章节从标题之后开始，结束于同一容器内下一个同级或更高级标题；末尾没有后续内容的标题不显示按钮。引用等容器中的标题只影响所在容器，不折叠外部正文。
- 工具栏使用单个按钮：有可见章节展开时显示“全部折叠”，否则显示“全部展开”。父章节隐藏的子章节不影响按钮判断，其自身折叠状态仍保留。无可折叠章节时按钮禁用。
- 折叠父章节不会清空子章节的折叠状态。
- 折叠时若选区在将隐藏的正文中，光标先移到标题。
- 从大纲、查找或键盘跳到隐藏内容时，展开包含目标的章节，避免隐藏光标。
- 折叠只影响当前编辑器视图，不修改 Markdown，不触发文档脏状态，也不占用撤销历史。重开文件恢复展开；源码模式与静态预览不进行章节折叠。
实现位于 `headingFolding.ts`：插件状态保存标题位置，通过事务映射跟随文档编辑；删除或改成正文的标题会从状态中清理。Decoration 隐藏完整块，widget 提供可聚焦的折叠按钮。章节范围按标题栈计算，并按不可变文档缓存；隐藏范围合并后遍历节点，避免每个节点重复扫描全部标题。
## 2. 标题样式设置
入口为“设置 → 编辑器 → 标题样式”，主题页“编辑器外观”中也提供同一组件。
- 默认跟随当前主题，不覆盖主题字号、字体与粗细。
- 启用自定义后，分别调整 H1–H6 字号（12–72 px）和字重（400–800 的五个档位）。
- 标题字体可跟随正文，或使用系统衬线、无衬线、等宽字体。
- 面板即时预览，工作区正文和静态 Markdown 预览使用同一偏好。
- 不影响笔记属性栏的标题、侧栏大纲字号或页面标题，不改写源文件中的标题级别。
- “恢复跟随主题”清除自定义覆盖；主题页“恢复默认”也重置标题设置。
偏好由 `headingAppearance` store 保存到本机 `editor-heading-appearance`。读取时校验字体枚举、字重与字号范围；应用 CSS 前再次规范化，避免空输入、无效存储或异常大数影响布局。刷新后恢复设置，切换主题保留自定义偏好。用户显式启用的覆盖只作用于 Markdown 标题，优先于主题规则；颜色继续跟随主题。
## 3. 桌面命令预留
既有 `editorCommandService` v1 增加三个可执行 ID：
| 命令 | 行为 |
| --- | --- |
| editor.heading.toggle-fold | 切换选区所在章节的折叠状态 |
| editor.heading.fold-all | 折叠所有有内容的章节 |
| editor.heading.unfold-all | 展开所有章节 |
均不需要参数，沿用活动文档、模式与冲突检查。原生快捷键仍由第三阶段容器绑定，此处不注册系统级快捷键。
## 4. 验证
```sh
cd frontend
npm run test -- src/features/editor/headingFolding.spec.ts src/features/editor/VisualMarkdownEditor.spec.ts src/features/editor/HeadingStyleSettings.spec.ts src/stores/headingAppearance.spec.ts
npm run build
```
自动检查覆盖章节边界、嵌套容器、隐藏选区迁移、父子折叠状态、大纲目标展开、序列化保持、设置保存恢复、输入校验和面板恢复默认。
手动检查：打开“功能演示 / 01 Markdown 与大纲”，依次折叠 H2 与 H1，再从大纲跳转；确认隐藏内容重新显示。打开设置调整 H1 字号与 H2 粗细，返回笔记检查外观，刷新后检查偏好仍在；关闭自定义后依次切换六个主题核对主题原有样式。
docs/development/模型上下文管理.md
+45
View File
@@ -0,0 +1,45 @@
# 模型上下文管理
核对日期：2026-09-05。
Provider 表单按精确模型 ID 保存 `context_policies`，包含窗口、输出预留、触发比例、处理模式和摘要提示词。旧配置默认空列表，未配置模型保持原行为。窗口是用户设置的预算，不会改变厂商限制；同一厂商的不同模型、地域和部署不能共用推测的窗口规格。
## 请求行为
- 发送前对系统提示词、文本历史、工具定义、调用参数和输出格式进行 UTF-8 长度估算（字节数 / 2 向上取整，加 64）。这是启发式检测，不能替代厂商 tokenizer，也不能准确预测隐藏思考开销。
- 输入预算为窗口减去输出预留；请求输出上限和自定义输出、思考参数会纳入预算。未指定输出上限时使用配置的输出预留。
- 达到输入预算的触发比例后，“检测”模式停止请求并提示调整配置或新建会话。“压缩”模式额外调用当前模型，摘要仅替换本次请求中的旧历史，数据库原始记录不变。每次超阈值请求重新生成摘要，摘要调用单独计入用量。
- 压缩保留系统消息和最近两个用户回合；只有两个回合时保留最新回合。摘要作为用户角色的参考材料，不提升为系统指令。
- 无旧历史、附件、工具调用链、摘要请求超限、空摘要或压缩未缩短等情况停止，不截断原文、不循环重试。摘要失败仍可能产生已发生的厂商用量。
- 流式聊天通过 `ContextStatus` 提示成功压缩，通过 `Error` / `Done` 提示检测失败。此实现不是厂商原生 compaction，也不通过缓存命中率判断是否压缩。
## 官方文档依据
表单提供对应文档链接。只有核对到精确模型 ID 的值用于建议；未识别型号显示可编辑的 32,768 初始预算，并明确其不是厂商规格。
| 预设 | 参考文档与限制 |
| --- | --- |
| OpenAI Chat / Responses | [上下文状态](https://developers.openai.com/api/docs/guides/conversation-state)：输入、输出和推理共用模型窗口，原生压缩是独立功能。 |
| Anthropic | [上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows)、[Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)：原生压缩有独立的模型与接口约束。 |
| DeepSeek | [模型规格](https://api-docs.deepseek.com/quick_start/pricing/)：按实际模型核对窗口和输出上限，不根据缓存计数猜测压缩。 |
| Ollama | [Context length](https://docs.ollama.com/context-length)：实际窗口还受服务端配置和设备资源限制。 |
| Kimi | [Chat API](https://platform.kimi.com/docs/api/chat)：按具体模型核对请求限制。 |
| 百炼 Qwen | [文本模型](https://help.aliyun.com/zh/model-studio/text-generation-model)：型号和地域影响上下文、输入、输出限制。 |
| 智谱 GLM | [模型概览](https://docs.bigmodel.cn/cn/guide/start/model-overview)：按具体模型填写。 |
| 火山方舟 | [官方文档入口](https://www.volcengine.com/docs/82379)：接入点需以实际部署型号为准，本次不预填统一容量。 |
| 硅基流动 | [文本生成](https://docs.siliconflow.cn/docs/userguide/capabilities/text-generation)：各模型 context_length 不同，以模型广场为准。 |
| 百度千帆 | [上下文管理](https://cloud.baidu.com/doc/qianfan-docs/s/Imkdq47r5)：部分思考模型 max_tokens 仅限制回答，max_completion_tokens 包含思考。 |
| 腾讯混元 | [官方产品动态](https://cloud.tencent.com/document/product/1729/97765)：不同型号存在独立输入、输出限制，不预填厂商统一容量。 |
| MiniMax | [OpenAI 兼容接口](https://platform.minimaxi.com/docs/api-reference/text-openai-api)：M3 为 1,000,000；文档列出的 M2.x 为 204,800。仅对列出的精确 ID 提供建议。 |
| 阶跃星辰 | [模型概览](https://platform.stepfun.com/docs/zh/guides/models/overview)：按实际型号核对。 |
## 验证范围
离线测试覆盖预算触发、模型隔离、无副作用压缩、工具历史保护、单条输入超限、无效摘要、输出覆盖参数、流式错误事件以及配置校验。前端覆盖保存恢复与切换地址清理配置。没有调用用户的真实厂商账号进行收费验收。
## 全局人设
`GET /api/settings/persona` 和 `PUT /api/settings/persona` 管理此 AI Core 的唯一全局人设，保存在 SQLite 中。包含名称、系统提示词、结构化 user/assistant 对话对和乐观锁版本。设置页“通用”及聊天页均可打开同一表单。头像仍仅保存在本机浏览器。
所有通过 ProviderFactory 创建的模型调用（普通对话与智能体、流式与非流式）在上下文预算检查前读取最新全局配置，将非空系统人设与对话示例追加到调用方原有系统提示词，保留 RAG 和任务约束。浏览器不再拼接本地人设，因此不会因更换浏览器丢失或重复注入。清空并保存后不再注入。厂商测试推理同样经过此边界；应用内部的历史摘要生成使用独立摘要提示词，避免人设干扰摘要格式。Mock 演示适配器不模拟真实系统提示词执行效果。
docs/development/第二阶段补充验收工具.md
+45
View File
@@ -0,0 +1,45 @@
# 第二阶段补充验收工具
这些工具补充证据采集，不以生成报告代替验收。没有标注的录音不能计算准确率；连接测试通过也不等于 Provider 全协议通过。
## 本地开发启动与扩展恢复
在 backend 目录执行 `.venv/Scripts/python.exe scripts/dev-server.py`。热重载仅监听 app，ZIP 解压目录不触发重载。
扩展安装库为应用数据目录下的 extension-installations.sqlite3。重启恢复前校验包摘要；包缺失或变化不会沿用原权限启动，管理页显示恢复提示。重新安装前需检查文件和权限。ZIP 卸载仅清理由导入器登记的管理目录，从目录安装不会删除用户源码。
## 转写参考数据评分
参考与预测文件均为 UTF-8 JSON 数组，每条包含秒单位的 start、end、text、speaker。参考必须来自人工校对或获准标注集，不能把同一份模型输出复制为参考。
也支持应用作业 JSON 的 segments 数组以及原生 start_time / end_time 字段，时间单位仍为秒。
```json
[{"start": 0, "end": 2.5, "text": "你好 世界", "speaker": "speaker_A"}]
```
```powershell
.venv/Scripts/python.exe scripts/score-transcript.py reference.json hypothesis.json --output scores.json
```
报告只保存聚合分数，不保存正文。CER 做 NFC 归一化并忽略空白；WER 按空白分词，中文连续文本优先看 CER。大小写和标点保留。空参考拒绝评分；空文本分母显示 null，不冒充 0%。比较超过 2000 万单元时拒绝，需分成较短且分别人工标注的录音进行验收。
说话人评分按全时间轴、零 collar、包含重叠语音计算 DER，使用一对一最优说话人映射，不要求预测编号与参考编号相同。最多 12 个说话人 ID；缺标签时不可用。该口径必须随结果保留，不能与不同 collar/UEM 规则的第三方分数直接比较。
脚本不设虚构达标阈值，quality_gate 固定 not_evaluated。阈值需在验收集和任务要求确定后另行批准。FAR/FRR 属于说话人验证专项，不能用这里的 DER 代替。当前 ASR 仍无逐字强制对齐和重叠分离，不因可对重叠参考评分就变成支持这些能力。
## Provider 专项证据
```powershell
.venv/Scripts/python.exe scripts/provider-acceptance.py --provider 已配置ID --model 已配置模型ID --output provider-plan.json
```
默认只生成待验收矩阵，不调用厂商。确认测试账号及可能费用后添加 `--execute`，经本地 AI Core 执行一次连接测试，不读取密钥，也不保存远端原始错误、请求头或响应正文。最多一次测试请求，不自动重试。
模型发现、工具往返、思考/正文流、取消、缓存命中/未命中、上下文限制、压缩仍逐项 pending，需要专门真实场景补证。overall 保持 not_accepted，禁止仅凭连接成功签署全部通过。当前用户录音无标注、各厂商专项未完整实测的状态保持不变。
## 浏览器回归
启动 frontend 后打开 `/tests/visual/mermaid-matrix.html`，使用真实 Mermaid 服务串行渲染 6 种图型 × 6 种内置/社区主题；顶部给出完成数和逐项结果。`?theme=paper-moments` 可单独检查该主题的最终外观。
该矩阵检查 SVG、可见尺寸、文本存在和错误；不把 DOM 文本存在当成所有字形都可见的截图结论。还需观察大图、缩放与窄屏。`/tests/visual/index.html?case=dialog` 用于弹窗内部滚动与焦点；主题预览样例涵盖输入、下拉、折叠、卡片、表格与代码。
docs/development/警告框与桌面编辑命令开发说明.md
+90
View File
@@ -0,0 +1,90 @@
# 警告框与桌面编辑命令开发说明
日期：2026-09-06。范围为前端渲染与命令边界；不包含 Tauri IPC、原生菜单或系统级快捷键注册。
## 1. 格式与渲染
使用引用块语法。GitHub 的 NOTE、TIP、IMPORTANT、WARNING、CAUTION 均可渲染；同时支持 Obsidian 的常用类型、别名、标题、嵌套与折叠。
```markdown
> [!WARNING]- 自定义标题
> 提示正文，支持 **粗体**、`行内代码`、列表等 Markdown。
>
> > [!TIP]+ 嵌套提示
> > 展开内容
```
无 `+` / `-` 时不可折叠；`+` 默认展开，`-` 默认折叠。点击折叠只改变本次显示状态，不自动改写源文件中的默认状态。标题作为文本显示，不执行 HTML。未知类型使用 note 外观并保留类型名。
| 规范类型 | 兼容别名 |
| --- | --- |
| note | — |
| abstract | summary、tldr |
| info、todo | — |
| tip | hint |
| important | — |
| success | check、done |
| question | help、faq |
| warning | caution、attention |
| failure | fail、missing |
| danger | error |
| bug、example | — |
| quote | cite |
工作区顶部“提示框”选择器可插入模板。编辑器保留原生 blockquote 文档节点，以 NodeView 展示标题与折叠按钮，装饰隐藏标记；选区进入标记时显示原文以便修改。序列化仅取消引用首行提示标记的转义，避免保存后退回普通引用。代码中的标记不转换。写作模式会规范化 Markdown 转义；需要永久展示字面标记时使用行内代码或围栏代码。
静态预览使用 marked 的 blockquote renderer，折叠使用原生 details / summary，内容仍经过 DOMPurify。两个入口共享 `callouts.ts` 与 `callouts.css`；颜色继承主题的 info、warning、success、error、surface 和 text 变量，不另存固定浅色配色。因此已有主题和符合主题规范的导入主题均可继承。
## 2. 桌面命令边界 v1
入口：`frontend/src/services/editorCommandService.ts`。
- `editorCommandVersion`：当前版本 1。
- `getEditorCommandCapabilities()`：返回每个稳定命令 ID 的 supported 与 enabled。预留 ID 不等于已经实现。
- `executeEditorCommand(id, params?)`：返回 `{ ok: true }` 或 `{ ok: false, reason }`。reason 为 unsupported、unavailable、invalid-params、failed。
- `registerEditorCommands(target)`：由活动编辑器注册处理器，返回注销函数。旧组件注销不清除替代组件的注册。
成功表示处理器接受并执行了命令；具体格式操作仍遵循编辑器的选区规则。命令不直接写磁盘，变更进入既有脏状态、撤销与自动保存链路。无活动文件、源码模式、只读、冲突、编辑器加载中或文件已切换时禁用当前处理器。
| 已接入 ID（统一加 editor. 前缀） | params |
| --- | --- |
| bold、italic、ordered-list、bullet-list、inline-code、code-block、inline-math、math-block、paragraph | 无 |
| heading | 整数 1–6 |
| font-size | 有限数值 8–96，单位 px；作用于选区 |
| insert-markdown | 非空 Markdown 字符串，最多 100000 字符 |
| callout | `{ type, title?, body?, fold? }`；fold 为空串、+ 或 -；标题不可换行 |
目录还预留删除线、任务列表、引用、Mermaid、链接、图片、表格、分隔线、硬换行、引用式链接、HTML、撤销/重做，以及 `editor.import-note-properties`、`editor.metadata.edit`、`editor.metadata.title`、`editor.metadata.tags`。这些单独的处理器尚未接入，返回 unsupported；现阶段复杂格式可通过 insert-markdown 插入。元数据不得通过普通正文插入接口冒充属性导入。
第三阶段由 Host 将原生菜单/快捷键映射到上述 ID。快捷键表需支持平台差异与用户改键，过滤表单、输入法组合与弹窗焦点；不要重复绑定浏览器和 Milkdown 已有按键。宿主只能调用允许的命令，不执行任意脚本。元数据处理器须按已有桌面需求完成无损 YAML 合并、版本检查、冲突提示及属性/正文一并撤销后才可标记 supported。
## 3. 验证方法
在 frontend 运行：
```sh
npm run test -- src/utils/callouts.spec.ts src/services/editorCommandService.spec.ts src/features/editor/VisualMarkdownEditor.spec.ts
npm run build
```
- callouts：逐个类型与别名、大小写、嵌套、默认折叠、空正文、未知类型、标题注入、普通引用和代码排除。
- 编辑器：初始解析、直接输入标记、按钮折叠、序列化往返、命令参数校验和冲突禁用。
- 命令服务：能力查询、无活动目标、未知命令、未实现命令和旧目标注销隔离。
- 启动开发服务器，访问 `/tests/visual/callouts.html?theme=paper-moments`；依次替换 light、dark、sepia、ocean-blue、midnight-purple。左右分别是工作区和静态预览，核对边框、标题、正文、嵌套与折叠；缩窄窗口检查换行。
此项不宣称支持所有 Markdown 方言；脚注、定义列表、Wiki 双链及 `:::` 等其他警告框语法仍需独立扩展。原生快捷键和元数据转换属于第三阶段验收。
## 4. 六主题适配补充
主题新增 `--color-callout-info/success/warning/danger/important/quote` 六个语义变量。每种类型继续使用共享组件结构，标题、边框与淡色背景取同一语义配色。未知导入主题未定义这些变量时，默认继承其已有状态色。折叠标题补齐悬停、键盘焦点与不可折叠标题状态。
| 主题 | 本次版本 | 外观 |
| --- | --- | --- |
| light、dark、sepia | 1.2.0 | 分别使用浅色、深色、暖色配色 |
| paper-moments | 1.7.0 | 纸张边框、虚线内描边和轻投影；嵌套取消重复投影 |
| ocean-blue | 1.4.0 | 海蓝与低亮度状态色 |
| midnight-purple | 2.2.0 | 深色表面与高亮度状态色 |
修正工作区基础选择器覆盖类型颜色的问题，默认色使用低优先级规则。社区预览 iframe 同步载入共享 callouts CSS，并展示 14 种规范类型、默认展开/折叠及嵌套样例。主题安装与预览使用同一 CSS 来源，纸间时光下载包的清单和样式同步更新；已安装旧版可通过主题页既有更新入口升级。
验证增加六主题 × 六配色在实际 8% 混色背景上的标题对比度检查（至少 4.5:1），工作区选择器覆盖回归，以及六主题预览结构检查。此检查针对不透明 sRGB 配色，不代替每个平台的字体与截图验收。
docs/development/阶段F收尾验收记录.md
+21 -1
View File
@@ -47,9 +47,29 @@ CPU 与 CUDA 分别创建隔离 Vault、附件目录和 SQLite，只读取固定
## 未关闭的专项验收
- 带参考转写和说话人标注的真实课程长录音尚未提供，不能报告 CER/WER、DER、阈值或长音频吞吐达标。
- 已提供无标注长录音，CUDA 功能与单次耗时验证见下文。参考转写和说话人标注仍缺失，不能报告 CER/WER、DER、阈值或业务吞吐达标。
- 现阶段时间戳为片段级；逐字强制对齐、同段多人/重叠语音仍未实现，不将片段聚类视为完整说话人分离。
- 外部供应商特殊 JSON 的兼容性，需要在目标账号和模型上点击实际推理验证；离线协议通过不替代厂商验收。
- Tauri/Rust Host 和生产 MCP 沙箱按后续阶段安排；本轮数据持久化在后端 SQLite/Vault，为桌面集成保留稳定接口。
结论：阶段 F 本轮工程收尾已实现并完成 CPU/CUDA 功能验收；上述质量及外部服务专项保持待验收状态，不标记为全部通过。分支仍需独立审阅后决定合并。
## 2026-09-05 长录音补充验收
用户授权使用本机 CUDA，只做本地处理。使用隔离的 SQLite、附件目录与 Vault，读取已安装的固定 revision 权重；原音频、转写正文和独立运行报告保留在被忽略的 `.local-plans`，不入库。
| 观察项 | 本次结果 |
| --- | --- |
| 输入 | MP3，89,424,101 字节，2235.60 秒（约 37 分 16 秒） |
| 转写与片段聚类 | completed；441 个片段，5 个说话人聚类 |
| 两环节总耗时 | 约 661 秒（轮询含最多约 10 秒误差），RTF 约 0.296 |
| Qwen3-ASR 实际设备 / 加载 / 推理 | cuda:0 / 10.52 秒 / 607.78 秒 |
| ERes2NetV2 实际设备 / 加载 / 推理 | cuda:0 / 3.97 秒 / 28.88 秒 |
| 后续链路 | Markdown 笔记生成、本地 Bekko 索引、向量检索命中均通过 |
| 隐私标记 | 导出笔记保留 `embedding_local_only: true` |
| 警告 | 1 个损坏音频包按时长补静音；说话人结果为片段级 |
最初实测暴露了 25 MiB 限制和单个损坏 MP3 包导致整任务失败，已修复并用同一输入重新跑通。5 个聚类不是已确认的真实人数；没有参考转写或说话人标注，因此不计算 CER/WER、DER 或 FAR/FRR。单次耗时也不作为跨设备吞吐承诺。逐字对齐、重叠语音和目标厂商真实验收仍未关闭。
本轮自动化基线：后端 577 项、前端 280 项通过，前端类型与生产构建通过；构建仍有既有大 chunk 提示。离线 Provider 测试不代替目标账号实测。