Agent Board
b798f628ee
Persist PageTree expand state via control-plane view-state and align chevron/DOM with restored expansion; keep Sidex-style shallow page-tree scan and drop the unused recursive scanner that only added cargo noise. Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi into a module package, and retire Hermes/ACP/OpenHub recycle + root harness evidence from the index while gitignoring recycle and local diag dumps. Archive superseded design/bugs docs under old/, point architecture at ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor regressions so the working tree can stay clean.
128 lines
7.7 KiB
Markdown
128 lines
7.7 KiB
Markdown
# 仓库协作指南（AGENTS）
|
||
|
||
## 当前主线
|
||
|
||
- 方向：`tree-first graph kernel` + local-first MVP 后阶段（底座统一、compat 瘦身、产品化闭环）。
|
||
- 产品形态：`VSCode 简化版工作区 + leptos-tiptap Markdown + Pi Rust Page AI + LightRAG + mindmap/office 插件 + Wolai 主题壳 + Turso/libSQL 控制面`。
|
||
- 数据真相：本地 workspace folder；页面正文为 `.md`。控制面：Turso/libSQL（auth / membership / share / sync / AI policy / Pi scope）。
|
||
- Page AI：Pi Lab 为 3000 默认且唯一产品级入口。ACP/Hermes/Reasonix、OpenHub、旧 `/api/hermes/*` 等为兼容/legacy，不得新增能力；退役须原子覆盖。
|
||
- Web：`mnote-web` 为 3000 唯一公开入口。kernel 持有树/边/projection/command 语义；前端只消费稳定 projection。
|
||
- 正文保存：`page.body.write` + 文件版本；AI 普通 Markdown：授权文件 + allowed roots + Pi patch/diff + watcher。知识库：LightRAG + `mnote.knowledge_rag.*`。
|
||
- 架构正文：只读 `ARCHITECTURE.md`（`CURRENT_ARCHITECTURE.md` 为兼容指针）。执行稿：`design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md`。
|
||
|
||
## 组件定位
|
||
|
||
| 组件 | 定位 |
|
||
|------|------|
|
||
| `leptos-tiptap` island | 文档页默认编辑 runtime；非对象真源 |
|
||
| Mindmap | tree-first 视图/挂件；非真相层 |
|
||
| OnlyOffice | 独立页面编辑器；经附件/资源进入 |
|
||
| LightRAG + Pi | 知识库与 Page AI 默认融合 |
|
||
| Resource → File → Page Tree | 对象真源 → 主组织投影 → 导航投影 |
|
||
|
||
## Runtime 模块定位
|
||
|
||
- Browser：`rust/crates/mnote-web/browser/`
|
||
- Sidebar：`sidebar-tree-runtime.js`（及 workspace / page tree / filetree / upload 等子模块）
|
||
- FileTree：`filetree-runtime.js`、`filetree-selection-runtime.js`、`filetree-context-menu-runtime.js`、`filetree-dnd-runtime.js`、`filetree-keyboard-runtime.js`
|
||
- Page AI host：`sidebar-page-ai-runtime.js`（owner `07-ai`）
|
||
- 文档 host：`document-editor-adapter-runtime.js`
|
||
- debug tree shell：`tree-shell-runtime.js`（默认关闭）
|
||
- Island：`rust/spikes/leptos-tiptap-spike/src/editor_runtime/`（勿把新行为继续堆进根 `lib.rs`，除非 wasm entry / 薄壳）
|
||
- SSR 注入：`layout.rs` / `tree.rs` / `web_shell.rs` — 非大型 JS 功能定位入口
|
||
|
||
## 目录优先级
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `rust/crates/core-protocol/` | Kernel 类型、projection 协议 |
|
||
| `rust/crates/bridge-runtime/` | query / command / traversal |
|
||
| `rust/crates/mnote-web/` | 3000 route、transport、projection、compat |
|
||
| `rust/crates/mnote-web/browser/` | 浏览器 runtime JS |
|
||
| `rust/spikes/leptos-tiptap-spike/` | 文档页编辑 island |
|
||
| `wolai-backend/app/` | 辅助后端 / 异步 |
|
||
| `src/components/onlyoffice/` | OnlyOffice 静态与插件 |
|
||
| `recycle/` | 历史回收；默认不作为实现依据 |
|
||
|
||
## 架构约束
|
||
|
||
- 树 / 页面结构 / 引用边：优先落 Rust kernel，禁止 UI 拼第二套真相。
|
||
- `compat route` 只承接过渡流量，不堆长期业务。
|
||
- 浏览器主链禁止新增 `setInterval` / 周期轮询刷新（树、文档、附件、AI 面板等）；用 WS/SSE、watcher、command result、`MutationObserver`。legacy/debug 若保留轮询须写明原因与退出条件。
|
||
- 标题 / 页面设置 / 正文：收口 Page Aggregate；不在壳外侧拼第二份页面真相。
|
||
- 新建/重命名/移动/归档：`tree.*`；`documents.*` 仅兼容。
|
||
- local-first AI 正文：文件引用 + `AiAccessScope` + Pi patch/diff + 版本冲突 + watcher；`mnote.doc.*` / `mnote.block.*` 仅 cloud/remote/compat 或结构辅助。Phase C 流式 apply 冻结。
|
||
- Page AI / 知识库首屏：对话与任务区优先；debug/health 放折叠区。
|
||
- Page AI 宿主改原生 Pi Lab runtime；禁止 DOM 注入伪装第三方；普通 UI 不得出现 fallback 切换入口。
|
||
- 知识库：LightRAG + `mnote.knowledge_rag.*` / `/api/knowledge-rag/*`。
|
||
- 架构判断优先：`ARCHITECTURE.md`，再查对应 `design/**` process/done 稿。
|
||
|
||
## 设计稿目录规则
|
||
|
||
- `design/01-*` … `design/10-*`：`process/` 可执行，`done/` 已完成，`reference/` 参考，`draft/` 未成形。
|
||
- 已完成主线稿必须迁入 `done/`；被覆盖且非 done 的旧稿迁 `design/old/` 并标 `[recycle]`。
|
||
- `design/90-reference/` 只放参考资料。
|
||
|
||
## Bugs 目录规则
|
||
|
||
- 镜像 design 大类；`process/` 未修完，`done/` 已验证。
|
||
- 按真正 owner 归类：壳/Sidebar/文档页体验 → `05-editor-mainline/`；projection/selection/DnD/tree command → `04-tree-domain/`。
|
||
- MVP 阶段发现 bug 时判断是否系统缺口；边界不清先问用户。
|
||
|
||
## 协作边界
|
||
|
||
- 只改与任务直接相关的文件；不覆盖用户已有改动；无关脏改动保持不动。
|
||
- UI 异常先查 debug shell / compat / 轮询是否混入主链。
|
||
- 发现轮询先评估事件驱动替代，再决定是否保留临时 fallback。
|
||
- Subagent 为受控叶子：任务书限定读写范围、验证命令、交付与禁止项；不得再启 runner/worktree 或改任务书。主控复核 diff/证据后才采纳。
|
||
- 同一写入范围同时只允许一个 writer（主控或一个 worker）；写入范围失效须先取消 worker 再改。
|
||
- 最终测试/回复前确认实现型 subagent 已完成、已取消，或输出已标不采纳。
|
||
|
||
## CodeGraph
|
||
|
||
- 结构性代码问题优先 CodeGraph MCP（search / callers / callees / impact / explore）。
|
||
- 改代码后 `codegraph sync .`；大重构或索引异常 `codegraph index . --force`。
|
||
- 提交前再 sync，确认无 pending；字面文本/日志字符串才优先用 `rg`。
|
||
|
||
## Reference-Code
|
||
|
||
- 优先 `reference-code/sidex-main`（完整 VSCode 工作台）；`reference-code/vscode` 为裁剪辅助。
|
||
- 每次只对照一个切面；区分可直接采用的交互模型 vs 不符合 local-first/tree-first 的细节。
|
||
- 不要把参考项目 UI 状态当成 MNote 新事实源。
|
||
|
||
## 常用命令
|
||
|
||
- 热启动：`npm run desktop:hot` → `http://localhost:3000`
|
||
- 测试：`cargo test -p mnote-web`
|
||
- 后端：`cd wolai-backend && uvicorn app.main:app --reload --port 8000`
|
||
- Control-plane：默认 `MNOTE_CONTROL_PLANE_BACKEND=libsql-local`；云端用 `turso-remote` / `turso-local-replica` + URL/token。`sqlite` 非 mnote-web 运行时。
|
||
|
||
## Smoke 与测试账号
|
||
|
||
- 基线：`scripts/TESTING_REFERENCE.md`；默认入口 `3000 + leptos-tiptap + local-first + Turso/libSQL auth`。
|
||
- 禁止 smoke 用 `sqlite3` CLI 直写 control-plane；seed 走 Rust API / `scripts/lib/control-plane-dev-seed.js` / `control-plane-test-env.js`。
|
||
- 测试账号：`mnote.e2e@example.com` / `MnoteE2E123!` / `mnote-e2e`；优先 `/auth`「测试账号快速登录」，勿用 `MNOTE_DEV_AUTH=1` 跳过真实 auth。
|
||
|
||
## 前端测试
|
||
|
||
- 看真实渲染：`/doko`；交互回归：浏览器自动化。
|
||
- 主页/Sidebar/文档首屏优先复用 `scripts/task*-smoke.js`。
|
||
- 高 CPU/内存：先查 debug shell、compat fallback、重复请求、轮询。
|
||
|
||
## Wolai-aline
|
||
|
||
- 启用 wolai-aline skill + `design/08-wolai-aline-test-flow/reference/wolai-aline-test-flow-v1.md`。
|
||
- 流程：Wolai 基线（默认只读）→ 本地 RED smoke → 实现 → 验证 → subagent 浏览器对标 → 截图复核。
|
||
- 浏览器对标用 subagent，只验证与截图；写入需明确授权与沙盒页。
|
||
- 登录态：`tmp/wolai-playwright-profile`；滑块验证不绕过，记录阻塞。
|
||
|
||
## 编码
|
||
|
||
- UTF-8；TS/TSX 2 空格；Python 4 空格。
|
||
|
||
## 密码箱 / agent skills（薄指针）
|
||
|
||
- 密码箱策略 SSOT：`/home/lix/.agent-infra/vault-policy.md`；skill `$mnote-vault`（`skills/mnote-vault`，全局 symlink 到 Codex/Hermes/Grok）。
|
||
- Page AI pack 注册：`hermes_tools/skill.rs` id `mnote-vault`（仅放 `skills/` 不够）。
|
||
- 勿在本文件复制完整 vault 策略；Paseo 经 `daemon.appendSystemPrompt` 全 agent 注入短段。
|