docs: document background indexing and merged phase two behavior
This commit is contained in:
+9
-1
@@ -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)。
|
||||
|
||||
@@ -34,6 +34,14 @@
|
||||
|
||||
## development：开发说明
|
||||
|
||||
- [工作区后台索引与保存开发说明](development/工作区后台索引与保存开发说明.md)
|
||||
- [Mermaid 预览与缩放开发说明](development/Mermaid预览与缩放开发说明.md)
|
||||
- [扩展安装持久化与社区包开发说明](development/扩展安装持久化与社区包开发说明.md)
|
||||
- [模型上下文管理](development/模型上下文管理.md)
|
||||
- [Markdown 渲染检查](development/Markdown渲染检查.md)
|
||||
- [主题组件覆盖检查](development/主题组件覆盖检查.md)
|
||||
- [第二阶段补充验收工具](development/第二阶段补充验收工具.md)
|
||||
|
||||
- [多模态管线与模型运行开发说明](development/多模态管线与模型运行开发说明.md)
|
||||
- [阶段 F 收尾验收记录](development/阶段F收尾验收记录.md)
|
||||
- [AI Core 与 Agent Core 开发说明](development/AI-Core与Agent-Core开发说明.md)
|
||||
|
||||
@@ -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)。
|
||||
|
||||
@@ -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) 的实现边界、状态和验证步骤为准。
|
||||
|
||||
@@ -33,3 +33,9 @@
|
||||
源码模式展示 Markdown 原文，不隐藏反引号、星号和围栏。脚注、定义列表、Wiki 双链、Obsidian callout、图表以外的自定义围栏等未作为独立渲染扩展启用，不在“已支持”范围内。
|
||||
|
||||
自动检查覆盖解析、DOM 输出、部分编辑交互、保存往返和主题变量。尚未完成所有浏览器、所有输入法及每个主题的逐页截图比对；不能据此宣称像素级视觉验收通过。测试使用隔离样例，没有修改用户笔记。
|
||||
|
||||
## 2026-09-06 Mermaid 补充
|
||||
|
||||
补齐大图居中与完整适配、显示宽度缩放基准、滚轮速度限制、鼠标位置补偿及重开滚动位置清理。修复 Milkdown 段落内边距挤出 foreignObject 标签框的问题，浏览器核对 1、many、contains 完整显示。
|
||||
|
||||
实现原理、测试命令和视觉复核步骤见 [Mermaid 预览与缩放开发说明](Mermaid预览与缩放开发说明.md)。
|
||||
|
||||
@@ -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)。
|
||||
@@ -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)。
|
||||
|
||||
@@ -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 后打开；计算期间修改并保存两次；重新打开确认最后内容；在隔离配置中模拟模型不可用，核对正文保留与索引错误分别显示。
|
||||
|
||||
## 当前限制
|
||||
|
||||
路径登记按磁盘与数据库的路径集合判断变化，不等同于完整外部文件监听。多进程后台调度、生产任务队列、完整失败历史和原生文件监听属于后续工作。不要把当前进程内互斥用于推断多实例安全性。
|
||||
@@ -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)。
|
||||
Reference in New Issue
Block a user