# 仓库协作指南（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 dev: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`。
- 账号角色（7-76 方案 A，**勿混用**）：
  | 账号 | 定位 | 密码（本地/dev） | admin 能力 |
  |------|------|------------------|------------|
  | `mnote-admin` / `mnote.admin@example.com` | **ops admin**（`/admin/*`、代签、policy） | `MnoteAdmin123!` | 是 |
  | `mnote-e2e` / `mnote.e2e@example.com` | **AI 主体** `ai_service`（私有工作区/知识库） | `MnoteE2E123!` | **否** |
  | `liaibo` 等 | 普通 human user | 各自密码 | **否** |
- 登录走 **标准** `/auth` 表单或 `/api/auth`（已移除「测试账号快速登录」）；开发对标生产。
- Admin 列表真源：`access-policy.json` 的 `admins` + `MNOTE_ADMIN_USER_IDS`（默认仅 `mnote-admin`）。

## 前端测试

- 真实渲染：`/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 策略。