# 4-6 [done] Tree Command Protocol Cutover Stage 2 v1

> 更新时间：2026-04-18
>
> 目的：冻结树域 command protocol 的长期命名面，并明确 `documents.*` 到 `tree.*` 的兼容迁移口径。

## 1. 结论

长期命名面不再继续扩大 `documents.*`。

固定迁移方向为：

- 兼容层继续保留 `documents.*`
- 长期正式协议统一切到 `tree.*`

## 2. 长期正式命名

冻结如下：

- `tree.node.create`
- `tree.node.rename`
- `tree.node.archive`
- `tree.node.restore`
- `tree.node.purge`
- `tree.subtree.move`
- `tree.subtree.copy`
- `tree.asset.attach`
- `tree.asset.detach`
- `tree.node.embed`

## 3. 当前兼容映射

| 兼容命名 | 长期命名 | 说明 |
| --- | --- | --- |
| `documents.create` | `tree.node.create` | 新建页面 |
| `documents.title.update` | `tree.node.rename` | 重命名页面 |
| `documents.move` | `tree.subtree.move` | 移动子树 |
| `documents.delete` | `tree.node.archive` | 软删除进入回收站 |
| `documents.restore` | `tree.node.restore` | 从回收站恢复 |
| `documents.purge` | `tree.node.purge` | 永久删除 |
| `documents.embed` | `tree.node.embed` | 嵌入页面 |
| `documents.copy_tree` | `tree.subtree.copy` | 复制树 |

## 4. Cutover 顺序

### Stage 2A

- 先在 Rust route / bridge 上接受 `tree.*`
- 同时保留 `documents.*` alias
- 前端 command client 开始显式知道两套名字的对应关系

### Stage 2B

- 主调用路径默认发 `tree.*`
- 兼容入口只用于旧 route / 旧测试 / 旧调试脚本

### Stage 2C

- 删除主路径对 `documents.*` 的依赖
- 仅保留极薄 alias，或在最终阶段删除 alias

## 5. 命名边界

### 5.1 `tree.node.*`

用于单节点生命周期命令：

- `tree.node.create`
- `tree.node.rename`
- `tree.node.archive`
- `tree.node.restore`
- `tree.node.purge`
- `tree.node.embed`

### 5.2 `tree.subtree.*`

用于结构级命令：

- `tree.subtree.move`
- `tree.subtree.copy`

### 5.3 `tree.asset.*`

用于资源挂接：

- `tree.asset.attach`
- `tree.asset.detach`

## 6. 当前约束

- 前端组件不再自己扩散树语义
- tree command client 是唯一稳定入口
- route / bridge / kernel command 的映射必须集中管理

## 7. 完成判定

当以下条件同时成立时，视为 Stage 2 完成：

- 文档明确记录 `documents.*` 到 `tree.*` 的映射
- Rust / 前端都接受 `tree.*`
- 主调用路径默认走 `tree.*`
- `documents.create` 等兼容命名不再是新增主语义入口
