lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
262e66b02e6ede6f5c45c70e8bceb50191b599c6
mnote/AGENTS.md
T
Agent Board 262e66b02e feat: purge legacy agent hosts and land vault Chrome extension path 
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.
2026-07-25 14:25:37 +08:00

6.5 KiB
Raw Blame History

仓库协作指南（AGENTS）

当前主线

  • 产品：tree-first graph kernel + local-first 工作区；云首发同栈（单机/云服务器均可部署）。
  • 形态：VSCode 简化版工作区 + leptos-tiptap Markdown + Pi Lab Page AI + LightRAG + mindmap/OnlyOffice + Wolai 主题壳 + libSQL 控制面 + Vault。
  • 数据真相：本地（或服务器上的）workspace folder；页面正文为 .md。
  • 控制面：MNOTE_CONTROL_PLANE_BACKEND=libsql-local 为默认与云首发推荐（独立部署、无需 Turso 云账号）；turso-remote / turso-local-replica 仅在明确需要托管同步时使用。sqlite 不是 mnote-web 运行时。
  • Web：mnote-web 为 3000 唯一公开入口。kernel 持有树/边/projection/command；前端只消费稳定 projection。
  • Page AI：Pi Lab（/api/page-ai/pi/*）为唯一产品入口。
  • 知识库：LightRAG + mnote.knowledge_rag.* / /api/knowledge-rag/*。
  • 正文保存：page.body.write + 文件版本；AI 写文件：授权 scope + allowed roots + Pi patch/diff + watcher。
  • 架构 SSOT：ARCHITECTURE.md。预发瘦身清单：design/10-review/process/22-pre-release-legacy-purge-v1.md。产品化收口：design/10-review/process/21-mvp-post-architecture-closure-checklist-v1.md。

云首发范围（必须保留）

能力 入口 / 说明
工作区 + 树 + 文档 kernel + FileTree/PageTree + leptos-tiptap
Page AI Pi Lab
知识库 LightRAG
办公文档 OnlyOffice（附件/资源进入）
密码箱 Vault + $mnote-vault
控制面 libsql-local（auth / membership / share / AI policy / Pi scope）

不在首发产品面、且不得在文档中当作可选主链宣传的路径：旧 agent 网关、第三方 ACP 宿主、OpenCode 代理壳、debug tree shell（默认关闭）。清理顺序与可删文件见 purge 清单。

组件定位

组件 定位
leptos-tiptap island 文档页默认编辑 runtime；非对象真源
Mindmap tree-first 视图/挂件；非真相层
OnlyOffice 独立页面编辑器；经附件/资源进入
LightRAG + Pi 知识库与 Page AI 默认融合
Vault 本机/服务器密码箱；AI 经 capability token 读密
Resource → File → Page Tree 对象真源 → 主组织投影 → 导航投影

Runtime 模块定位

  • Browser：rust/crates/mnote-web/browser/
    • Sidebar：sidebar-tree-runtime.js（及 workspace / page tree / filetree / upload 等）
    • FileTree：filetree-*.js
    • Page AI host：sidebar-page-ai-*.js（默认 Pi Lab）
    • 文档 host：document-editor-adapter-runtime.js
  • Island：rust/spikes/leptos-tiptap-spike/src/editor_runtime/
  • 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
rust/crates/mnote-web/browser/ 浏览器 runtime JS
rust/spikes/leptos-tiptap-spike/ 文档页编辑 island
rust/crates/mnote-vault-core/ Vault 核心
src/components/onlyoffice/ OnlyOffice 静态与插件
wolai-backend/app/ 辅助后端 / 异步（非 3000 主入口）
recycle/ 回收区；不作为实现依据
reference-code/ 对照参考；不进部署包

架构约束

  • 树 / 页面结构 / 引用边：落 Rust kernel，禁止 UI 拼第二套真相。
  • 浏览器主链禁止新增 setInterval / 周期轮询；用 WS/SSE、watcher、command result、MutationObserver。
  • 标题 / 页面设置 / 正文：收口 Page Aggregate。
  • 新建/重命名/移动/归档：tree.*。
  • AI 正文：文件引用 + AiAccessScope + Pi patch/diff + 版本冲突 + watcher。Phase C 流式 apply 冻结。
  • Page AI 宿主为原生 Pi Lab runtime；普通 UI 不得出现第二套 agent 切换入口。
  • Agent 工具包：rust/crates/mnote-web/src/mnote_agent_tools/（HTTP 面 /api/mnote/tools/*；Pi / LightRAG / skill / OnlyOffice live tools 依赖，不可整目录误删）。
  • 架构判断：ARCHITECTURE.md → 对应 design/** process/done 稿。

设计稿目录规则

  • design/01-* … design/12-*：process/ 可执行，done/ 已完成，reference/ 参考，draft/ 未成形。
  • 已完成主线稿迁 done/；被覆盖旧稿迁 design/old/ 并标 [recycle]。
  • design/90-reference/ 只放参考资料。

Bugs 目录规则

  • 镜像 design 大类；process/ 未修完，done/ 已验证。
  • 壳/Sidebar/文档页体验 → 05-editor-mainline/；projection/selection/DnD/tree → 04-tree-domain/。

协作边界

  • 只改与任务直接相关的文件；不覆盖用户已有改动；无关脏改动保持不动。
  • Subagent 为受控叶子：限定读写范围与验证命令；主控复核 diff/证据后才采纳。
  • 同一写入范围同时只允许一个 writer。

CodeGraph

  • 结构性代码问题优先 CodeGraph MCP（explore / impact）。
  • 改代码后 codegraph sync .；大重构或索引异常 codegraph index . --force。
  • 字面文本/日志字符串优先 rg。

Reference-Code

  • 优先 reference-code/sidex-main；reference-code/vscode 为裁剪辅助。
  • 每次只对照一个切面；不要把参考项目 UI 状态当成 MNote 新事实源。

常用命令

  • 热启动：npm run desktop:hot → http://localhost:3000
  • 测试：cargo test -p mnote-web
  • Control-plane 默认：MNOTE_CONTROL_PLANE_BACKEND=libsql-local
  • 云首发：同 libsql-local + 服务器本地数据目录；需要托管再换 turso-remote

Smoke 与测试账号

  • 基线：scripts/TESTING_REFERENCE.md；默认入口 3000 + leptos-tiptap + local-first + libSQL auth。
  • 禁止 smoke 用 sqlite3 CLI 直写 control-plane；seed 走 Rust API / scripts/lib/control-plane-dev-seed.js。
  • 测试账号：mnote.e2e@example.com / MnoteE2E123! / mnote-e2e；优先 /auth「测试账号快速登录」。

前端测试

  • 真实渲染：/doko；交互回归：浏览器自动化。
  • 主页/Sidebar/文档首屏优先复用 scripts/task*-smoke.js。

编码

  • UTF-8；TS/TSX 2 空格；Python 4 空格。

密码箱 / agent skills（薄指针）

  • 策略 SSOT：/home/lix/.agent-infra/vault-policy.md；skill $mnote-vault（skills/mnote-vault）。
  • Page AI pack 注册：agent tool pack 内 skill 模块 id mnote-vault（仅放 skills/ 不够）。
  • 勿在本文件复制完整 vault 策略。
Reference in New Issue View Git Blame Copy Permalink