mnote/AGENTS.md

# 仓库协作指南（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 注入短段。