lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b798f628ee5a9da86c009ea1626be9a37c8c75ef
mnote/AGENTS.md
T
Agent Board b798f628ee chore: land tree view-state, vault, Pi module split, and repo hygiene 
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.
2026-07-21 05:13:05 +08:00

7.7 KiB
Raw Blame History

仓库协作指南（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 注入短段。
Reference in New Issue View Git Blame Copy Permalink