# 持久化插件拆分指南

## 当前结论

项目已经从临时动态脚本整理成根目录可安装的持久化 Harness bundle。`src/**` 是唯一业务源码，`lib/**` 是构建产物，不允许在 `lib` 中手工修改。

当前拆分适合继续扩展：Host、Client、共享契约和 Harness adapter 已分层；下一阶段不应再做大搬家，而应按功能热点逐步把较大的模块拆小。

## 当前模块职责

| 模块 | 允许负责 | 不允许负责 |
| --- | --- | --- |
| `src/index.ts` | Host 装配、路由分发、生命周期 | 会话扫描、改名/归档算法、版本兼容分支 |
| `src/host/data.ts` | 快照、缓存、授权、子代理、Agent 状态 | UI、HTTP 解析、DSH service key |
| `src/host/mutations.ts` | 标题与归档用例 | 页面状态、布局、直接读取 Cordis key |
| `src/host/http-guard.ts` | 方法/header/origin/body 边界 | 业务授权 |
| `src/client/index.ts` | Client 装配、slot 注册、共享 UI 状态 | 布局算法、DSH slot 字符串 |
| `src/client/canvas.tsx` | React 生命周期与模块编排 | Host 调用细节、版本判断 |
| `src/client/canvas-interactions.ts` | 手势和用户动作 | DOM 元素构造、DSH service key |
| `src/client/canvas-elements.tsx` | 纯展示 | 网络、mutation |
| `src/client/layout.ts` | 纯布局和连线 | React、网络、缓存 |
| `src/client/api.ts` | 同源 transport 和错误转换 | 业务状态 |
| `src/platform/adapters/*` | DSH 名称/形状转换 | 业务规则 |
| `src/shared/*` | 稳定内部/wire contract | 具体运行时调用 |

## 推荐的下一阶段拆分

### 1. Host data（优先级中）

`host/data.ts` 同时包含多种状态容器，新增复杂查询前再拆：

```text
host/data/
  snapshot-service.ts
  workspace-membership.ts
  agent-status.ts
  subagent-index.ts
  cache.ts
```

触发条件：文件继续增加约 150 行，或某个缓存需要独立配置/测试。拆分时保持 `createDataOps` 作为门面，调用方不变。

### 2. Client interactions（优先级中）

`canvas-interactions.ts` 可按用户动作拆：

```text
client/interactions/
  pointer-controller.ts
  navigation.ts
  rename-action.ts
  archive-action.ts
  viewport.ts
```

触发条件：增加新手势、撤销/重做或键盘完整支持。每个 action 接收显式依赖，禁止重新调用 `ctx.get`。

### 3. Canvas state（优先级较低）

当前共享状态足够小。若增加过滤、搜索、分组、快照时间线，再引入 reducer/store：

```text
client/state/
  model.ts
  reducer.ts
  selectors.ts
```

不要为了目录整齐提前引入状态库。

## 新功能应放在哪里

| 新功能 | 建议位置 |
| --- | --- |
| 节点搜索/过滤 | `client/state` + `canvas-elements`，不改 Host contract（除非需要服务端查询） |
| 自定义颜色/标签 | `shared/contract` + Host mapper + Client display |
| 导出图片/JSON | 新建 `client/features/export`，只消费快照 |
| 取消归档 | 新 Host port/mutation + adapter 能力；没有官方可逆 API 前不要模拟 |
| 增量快照 | 新 Host snapshot index + wire revision，保留全量 fallback |
| 多版本 Harness | 新增 `platform/adapters/<version>` |
| 新 transport | 新建 `platform/transport`，让 `api.ts` 只保留门面 |

## 依赖方向

允许：

```text
entry -> adapter + core
core -> shared contracts
adapter -> shared DSH contracts
client display -> layout/geometry
client action -> transport + stable services
```

禁止：

```text
shared -> host/client
layout -> React/DOM/fetch
host business -> client
client business -> raw Cordis service key
core -> specific adapter implementation
```

## 拆分执行方法

1. 先给原行为补测试。
2. 新建目标模块并移动纯逻辑，不同时改变业务。
3. 保留原门面导出，减少调用面变化。
4. `npm run typecheck` 和 `npm test`。
5. 再单独提交行为变更及其测试。
6. 更新架构文档和 adapter 边界测试。

一次提交不要同时做“目录搬迁、契约变化、UI 重做、Harness 升级”。这些变化应可独立回滚。

## 完成标准

- `src/**` 是唯一源码；
- service/slot/event 名只在 adapter；
- 新功能有生产产物测试；
- 写操作有授权和稳定错误码；
- 缓存有 TTL、容量上限和失效路径；
- 生命周期有 disposer/abort；
- `npm run verify` 通过；
- Harness 相关变化完成真实 UI 冒烟。