Agent Board
262e66b02e
Retire ACP/Hermes/OpenCode surfaces and rename hermes_tools to mnote_agent_tools so Page AI stays on Pi Lab only. Add Chrome vault extension + extension token route, pre-release purge design, and soft-retire legacy smokes for the small-group production cut.
172 lines
7.1 KiB
Markdown
172 lines
7.1 KiB
Markdown
# MNote 架构
|
||
|
||
> 更新时间：2026-07-25
|
||
> 本文只描述**当前**产品形态与运行分层。协作规则见 `AGENTS.md`；预发瘦身见 `design/10-review/process/22-pre-release-legacy-purge-v1.md`；产品化收口见 `design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md`。
|
||
|
||
## 1. 产品形态
|
||
|
||
```text
|
||
MNote = VSCode 简化版工作区
|
||
+ tiptap Markdown 编辑器（leptos-tiptap island）
|
||
+ Pi Lab Page AI
|
||
+ LightRAG 知识库
|
||
+ simplemindmap / OnlyOffice
|
||
+ Vault 密码箱
|
||
+ Wolai 主题 Web 壳
|
||
+ libSQL 控制面（默认 libsql-local）
|
||
```
|
||
|
||
| 层 | 当前真源 / Owner |
|
||
|----|------------------|
|
||
| 工作区数据 | workspace folder；页面正文为 `.md` |
|
||
| 树 / 资源语义 | Rust kernel（`core-protocol` + `bridge-runtime`） |
|
||
| Web 入口 | `mnote-web`，公开端口 **3000** |
|
||
| 控制面 | libSQL/Turso store：auth、membership、share、sync state、AI policy / Pi scope |
|
||
| Page AI | Pi Lab（`/api/page-ai/pi/*`） |
|
||
| 知识库 | LightRAG + `mnote.knowledge_rag.*` |
|
||
| 密码箱 | Vault（store + web routes + extension/agent token） |
|
||
| 编辑投影 | Page Aggregate（`mnote.page_aggregate.v1`）；tiptap 为显示层 |
|
||
|
||
一句话：
|
||
|
||
> **工作区文件夹是数据真相，Rust kernel 持有语义，libSQL 持有控制面，前端只消费稳定 projection。**
|
||
|
||
### 1.1 云首发
|
||
|
||
- 与本地同栈：Pi Lab、LightRAG、OnlyOffice、Vault、树/文档主链。
|
||
- 控制面推荐 **`libsql-local`**：服务器上独立文件库，不依赖外部 Turso 账号；运维简单、可备份导出。
|
||
- `turso-remote` / replica：可选增强，不是首发前置条件。
|
||
- 部署包不含 `reference-code/`、`recycle/`、debug shell 默认路由。
|
||
|
||
## 2. 分层
|
||
|
||
### 2.1 Workspace / Storage
|
||
|
||
- 默认 source：`local_folder`（本机或服务器磁盘路径）
|
||
- 管理员通过控制面授权可读写目录
|
||
- 页面内上传默认 sibling assets；正文存相对 Markdown 链接
|
||
- `.md` / 附件 / mindmap / OnlyOffice **不**迁入 control-plane DB
|
||
|
||
### 2.2 Kernel / Projection
|
||
|
||
- `core-protocol`：树、资源、页面、AI access scope、page body write 等协议
|
||
- `bridge-runtime` + `mnote-web`：LocalFS → 稳定 projection / command
|
||
- 前端消费：`file_tree`、`page_tree`、`page_aggregate`、tree command result
|
||
|
||
| 层 | 角色 |
|
||
|----|------|
|
||
| Resource Tree | kernel 对象组织真源 |
|
||
| File Tree | 主组织投影；页面正文 `{title}.md` |
|
||
| Page Tree | 导航投影；不持有结构真相 |
|
||
|
||
正式命令面：`tree.*`。
|
||
|
||
### 2.3 Web Shell / Editor
|
||
|
||
- Owner：`mnote-web`（Rust SSR + browser runtime）
|
||
- 文档页：`leptos-tiptap` island + `browser/*.js`
|
||
- 正文保存：`page.body.write` / `/api/page-body/write`（文件版本）
|
||
- Watcher：clean 自动刷新；dirty 冲突态，不静默覆盖
|
||
- Realtime：WS `/api/realtime/ws` + SSE `/api/tree/events`
|
||
- Mindmap：视图/挂件；OnlyOffice：独立编辑器经资源进入
|
||
|
||
### 2.4 Page Aggregate
|
||
|
||
- 读取：`mnote.page_aggregate.v1`（`/api/page-aggregate/:id`）
|
||
- 本地正文真相是 `.md`；aggregate 是投影
|
||
|
||
### 2.5 Page AI（Pi Lab）
|
||
|
||
```text
|
||
当前页 → 真实 .md
|
||
→ AiAccessScope / allowed roots / selection
|
||
→ Pi Lab（/api/page-ai/pi/*）
|
||
→ agent patch/diff 写文件
|
||
→ watcher / BufferStore → Page Aggregate + tiptap
|
||
```
|
||
|
||
- Session / run / tool event 默认落 control-plane；Pi JSONL 为 runtime 工作副本
|
||
- Agent 工具 HTTP：`/api/mnote/tools/{manifest,call,audit}`
|
||
- 工具实现目录：`rust/crates/mnote-web/src/mnote_agent_tools/`
|
||
- Pi 直接依赖其中 `knowledge_rag` 的 agent 输出整形，以及 skill pack（含 `mnote-vault`）
|
||
- 流式 apply + suggest/review：Phase C 冻结
|
||
|
||
### 2.6 Knowledge RAG（LightRAG）
|
||
|
||
- ingestion / query / citation / open-reference 主路径：LightRAG
|
||
- MNote 维护 source registry、权限、FileTree 灯号、status UI、citation 映射、tool facade
|
||
- Agent 工具：`mnote.knowledge_rag.status` / `query` / `section_context` / `open_reference`
|
||
|
||
### 2.7 Vault
|
||
|
||
- 服务端 store + `/api/vault/*` 工作台；extension/agent 经 capability token
|
||
- 策略与 agent 用法：`/home/lix/.agent-infra/vault-policy.md`、`$mnote-vault`
|
||
|
||
### 2.8 Control-plane
|
||
|
||
```text
|
||
ControlPlaneStore
|
||
└── TursoControlPlaneStore mnote-web 唯一运行时
|
||
├── libsql-local 默认 / 云首发推荐
|
||
├── turso-remote 可选托管
|
||
├── turso-local-replica
|
||
└── turso-synced
|
||
```
|
||
|
||
| 变量 | 用途 | 默认 |
|
||
|------|------|------|
|
||
| `MNOTE_CONTROL_PLANE_BACKEND` | 后端模式 | `libsql-local` |
|
||
| `MNOTE_TURSO_LOCAL_PATH` | local 文件 | `/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db` |
|
||
| `MNOTE_TURSO_DATABASE_URL` | remote URL | — |
|
||
| `MNOTE_TURSO_AUTH_TOKEN` | remote token | — |
|
||
|
||
- 只存元数据：users、sessions、workspaces、directory grants、share、sync state、AI policy/runtime、audit
|
||
- `sqlite` 不得作为 mnote-web runtime
|
||
- 备份：admin export → 再导入 libSQL；不回退 SQLite 运行
|
||
|
||
### 2.9 代码入口
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| `rust/crates/core-protocol/` | Kernel 类型与 projection 协议 |
|
||
| `rust/crates/bridge-runtime/` | query / command / traversal |
|
||
| `rust/crates/mnote-web/` | 3000 gateway、SSR、API、realtime |
|
||
| `rust/crates/mnote-web/browser/` | Sidebar / FileTree / document / Page AI host |
|
||
| `rust/spikes/leptos-tiptap-spike/` | 文档页编辑 island |
|
||
| `rust/crates/mnote-vault-core/` | Vault 核心 |
|
||
| `src/components/onlyoffice/` | OnlyOffice 静态资源 |
|
||
|
||
## 3. 当前收口缺口
|
||
|
||
阶段：local-first **MVP 后**；重点是统一与产品化，以及预发前去掉非首发代码面。
|
||
|
||
1. **WorkspacePath / ObjectIdentity** — 路径与 identity 统一到 kernel
|
||
2. **DocumentBuffer / BufferStore** — 多 tab 仲裁与冲突 UI
|
||
3. **Page Aggregate** — 以 Rust snapshot 为单一运行时真相
|
||
4. **tree command context** — 菜单 / 快捷键 / AI enablement 同一 context
|
||
5. **tree live cache** — watcher + WS/SSE 收进同一 cache
|
||
6. **管理员目录授权 UI**
|
||
7. **冲突合并 UI**
|
||
8. **agent 写入审计**
|
||
9. **本地轻量搜索**
|
||
10. **分享与同步闭环**
|
||
11. **插件资源模型** — mindmap / office 作为 Resource Tree 对象
|
||
12. **预发瘦身** — 删除非 Pi 的 agent 宿主与巨型兼容网关；工具包重命名；见 `22-pre-release-legacy-purge-v1.md`
|
||
|
||
## 4. 设计索引（当前）
|
||
|
||
| 主题 | 文档 |
|
||
|------|------|
|
||
| 预发瘦身 | `design/10-review/process/22-pre-release-legacy-purge-v1.md` |
|
||
| 总收口 | `design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md` |
|
||
| tree-first kernel | `design/01-tree-first-graph-kernel/reference/1-tree-first-graph-kernel-v1.md` |
|
||
| control-plane | `design/02-convex-rust-long-term-architecture/process/2-9-turso-control-plane-cutover-v1.md` |
|
||
| Page Aggregate | `design/05-editor-mainline/` |
|
||
| AI 文件编辑 | `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md` |
|
||
| LightRAG | `design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md` |
|
||
| Vault | `design/12-vault/` |
|
||
|
||
---
|
||
|
||
`CURRENT_ARCHITECTURE.md` 为兼容指针，内容以本文为准。
|