# 仓库协作指南（AGENTS）

## 主线（一句话）

tree-first kernel + local-first 工作区；真相 = 本地 folder + `.md`；**mnote-web:3000**；Page AI = **Pi Lab only**；控制面默认 **libsql-local**；知识库 LightRAG；Vault + `$mnote-vault`。  
SSOT：`ARCHITECTURE.md`。预发：`design/10-review/process/22-pre-release-legacy-purge-v1.md`。

## 云首发必须保留

工作区树文档 · Pi Lab · LightRAG · OnlyOffice · Vault · libsql-local。  
勿当主链宣传：第三方 ACP 宿主、默认 debug tree shell。

## 约束

- 树/边/结构只在 Rust kernel；UI 不拼第二套真相。  
- 浏览器禁止新增 `setInterval` 轮询 → WS/SSE/watcher/command/MO。  
- 标题/设置/正文 → Page Aggregate；树变更 → `tree.*`。  
- AI 写文件：scope + roots + Pi patch/diff + 版本 + watcher（Phase C 流式 apply 冻结）。  
- `mnote_agent_tools/` 与 `/api/mnote/tools/*` **不可整目录误删**。

## 目录

| 路径 | 用途 |
|------|------|
| `rust/crates/core-protocol` · `bridge-runtime` · `mnote-web` | 协议 / query-command / 3000 |
| `mnote-web/browser` · `leptos-tiptap-spike` | 前端 runtime / 编辑 island |
| `mnote-vault-core` · `src/components/onlyoffice` | Vault · OO |
| `recycle/` · `reference-code/` | 非实现依据；**不进部署包** |

## 协作

- 只改任务相关文件；不覆盖用户改动。  
- design：`process/` 可执行，`done/` 完成。bugs 镜像大类。  
- CodeGraph 结构问题；`rg` 字面量。热启：`npm run dev:hot`。测：`cargo test -p mnote-web`。

## 账号（dev，勿混）

| 账号 | 角色 |
|------|------|
| `mnote-admin` | ops admin |
| `mnote-e2e` | `ai_service`（非 admin） |
| 其它 | human |

详情与密码：`scripts/TESTING_REFERENCE.md`。登录走标准 `/auth`（无快速登录）。

## 指针

- Vault：`vault-policy.md` · `$mnote-vault`（pack id `mnote-vault`）。  
- **知识中枢**（非 LightRAG）：`/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space`  
  - 查 → `INDEX.md`；更 → 事实变更时；写/多域 → `$mnote-e2e-knowledge-hub`