mnote/design/00-clean/2026-05-20-cleanup-summary.md

# 2026-05-20 项目清理总结

## 背景

本轮清理目标是为当前 MNote 主线实现收窄项目工作区，减少历史 AIChem / Wolai / Graphify / 构建缓存 / 本地沙箱残留对开发、索引和依赖判断的干扰。

清理过程中采用的核心规则：

- `.gitignore` 不等于无用；被 ignore 的内容可能仍是外部辅助功能或本地运行缓存。
- `recycle/` 才按“确认无当前作用或待回收隔离”处理。
- 对不确定内容优先移动到 `/mnt/Data1T/mnote/recycle`，不直接物理删除。
- `reference-code` 是参考代码，不进入 CodeGraph 主索引，但不代表可删除。
- `.pnpm-store`、`.playwright-mcp` 等本地功能或缓存目录若曾被 Git 跟踪，处理重点是停止跟踪或替换本地缓存，不直接删除其功能。

## 已完成清理

### 1. Graphify 退役与 CodeGraph 接管

已卸载 / 隔离 Graphify 相关内容，并将历史 Graphify 目录移动到：

- `recycle/20260520-graphify-uninstall/`
- `recycle/20260520-graph-cleanup/`

当前选择 CodeGraph 作为主代码图谱工具。原因是 CodeGraph 更适合开发态持续更新：有 MCP 工具、AST 结构化查询、索引状态检查和 symbol/caller/callee/impact 查询能力。

已完成 CodeGraph 配置与验证：

- Codex 已有 `codegraph_*` MCP 工具可用。
- Reasonix 已补充 CodeGraph MCP 使用指南。
- 项目 `AGENTS.md` / `REASONIX.md` 已加入 CodeGraph 使用规则。
- 主索引继续排除 `reference-code`、`tmp`、`test-results`、`recycle`、`.playwright-mcp`、沙箱目录、生成缓存、spike 构建产物等。

最新验证：

```bash
codegraph status
```

结果：

- Files: `295`
- Nodes: `8,035`
- Edges: `24,035`
- DB Size: `50.86 MB`
- Backend: `native`
- 状态：`Index is up to date`

### 2. Convex 目录规范

已修正 `scripts/run-convex-deploy.js`：

- 不再 fallback 到 `recycle/wolai-frontend/convex`
- 只从根 `convex/` 部署
- 若 active deploy source 缺失，应显式失败，而不是静默回退到 recycle

已更新说明：

- `recycle/20260522-convex-runtime-retirement/infra/convex/README.md`
- `AGENTS.md`
- `REASONIX.md`

当前约束：

- 根 `convex/` 是 active functions deploy source。
- `recycle/wolai-frontend/convex` 不允许作为当前 fallback。
- 若 runtime 仍需要旧 functions，应迁回 active 区或明确放入外部辅助区；不能从 recycle 继续运行。

### 3. package 依赖与历史 Electron 配置清理

已从根 `package.json` 清理历史 Electron 相关配置：

- 移除 Electron / electron-builder 相关依赖与配置。
- 移除 `desktop-electron` 历史引用。
- 移除 `appId=org.aichem.mnote` 旧 AIChem 命名残留。

已更新：

- `package.json`
- `package-lock.json`
- `pnpm-lock.yaml`

当前根依赖验证：

```bash
npm ls --depth=0 --json
```

当前只保留：

- `@playwright/test`
- `convex`
- `playwright`

另外，已清理 `node_modules/.electron-alyHT01H` 断开的 Electron 临时 symlink。

### 4. 本地 / 沙箱残留移动到 recycle

以下目录已按“本地残留候选”移动到：

- `recycle/20260520-local-sandbox-cleanup/`

涉及内容包括：

- `home/`
- `.sandbox-home`
- `.sandbox-tmp`
- `recycle/20260522-convex-runtime-retirement/local-state/.convex-tmp`

当前该回收目录体积约 `912K`。

### 5. 构建缓存与大目录移动到 recycle

以下构建缓存 / 依赖缓存已移动到：

- `recycle/20260520-build-cache-cleanup/`

涉及内容包括：

- `rust/spikes/leptos-tiptap-spike/target`
- 根 `rust/target`
- `test/agent-browser-lab/node_modules`
- `reference-code` 下若干 `target` / `node_modules` / `.next` 构建缓存

当前该回收目录体积约 `53G`。

说明：

- 根 `rust/target` 历史上存在被 Git 跟踪的构建产物，已先做停止跟踪处理，再移动。
- 这些内容是构建缓存或历史依赖缓存，不应进入 CodeGraph 主索引。
- 因为已移入 `recycle`，当前还没有物理删除；后续若确认无需回滚，可再删除该回收目录释放空间。

### 6. `.pnpm-store` 清理与替换

原 `.pnpm-store` 约 `2.6G`，包含大量历史前端依赖缓存，例如 Next、BlockNote、Tiptap、Supabase、Radix、Cloudflare / Wrangler 等。当前根锁文件已经不再引用这些历史包。

处理流程：

1. 先用干净 store 目录 `.pnpm-store-clean` 按当前 `pnpm-lock.yaml` 重新安装。
2. 验证干净 store 可用。
3. 将旧 `.pnpm-store` 移动到 `recycle/20260520-pnpm-store-legacy/.pnpm-store`。
4. 将 `.pnpm-store-clean` 切回标准路径 `.pnpm-store`。
5. 重新安装当前依赖，确保 `node_modules` 指向标准 `.pnpm-store`。
6. 清理 `node_modules/.electron-alyHT01H` 断链。

当前验证：

```bash
pnpm store status --store-dir .pnpm-store
```

结果：

```text
Packages in the store are untouched
```

当前体积：

- `.pnpm-store`: `308M`
- `node_modules`: `2.0M`
- `recycle/20260520-pnpm-store-legacy`: `2.6G`

### 7. `.playwright-mcp` 和 `.pnpm-store` 的 Git 跟踪问题

已按规则处理“停止跟踪”方向，而不是删除本地功能。

当前工作区仍会显示大量 `.pnpm-store` / `.playwright-mcp` 的删除状态，这是因为这些历史缓存文件曾被 Git 跟踪，而本轮清理目标是让缓存退出版本控制焦点。

后续提交时应确认：

- `.pnpm-store` 不应继续作为源码资产跟踪。
- `.playwright-mcp` 不应继续作为源码资产跟踪。
- 当前活跃 `.pnpm-store` 是本地依赖缓存，可重建。
- 历史旧 store 已在 `recycle/20260520-pnpm-store-legacy/` 中保留，便于回滚。

## 旧命名和历史配置处理

本轮还处理了以下历史残留：

- 根 `package.json` 中 `org.aichem.mnote` 旧 appId 已移除。
- `desktop-electron` 历史配置已移除；当前桌面主路径是 Rust。
- `scripts/cloudflared/config.yml.example` 中旧 `*.aichem.dpdns.org` 域名已作为旧域名残留识别并纳入清理检查范围。

## 当前保留但不进入主索引的内容

以下内容不应进入 CodeGraph 主索引，但不是“可删除”的含义：

- `design/05-editor-mainline/reference-code/`
- `tmp/`
- `test-results/`
- `recycle/`
- `.playwright-mcp/`
- 构建缓存、生成缓存、spike 输出目录

这符合当前规则：主索引只聚焦当前功能实现，参考代码和本地辅助内容不干扰结构分析。

## 验证记录

已执行并通过的关键验证：

```bash
codegraph status
pnpm store status --store-dir .pnpm-store
npm ls --depth=0 --json
find -L node_modules -maxdepth 2 -type l -printf 'BROKEN %p -> %l\n'
```

验证结论：

- CodeGraph 主索引可用且 up to date。
- 当前 `.pnpm-store` 可用，且体积已收缩到 `308M`。
- 当前 `node_modules` 依赖树只包含当前根依赖。
- `node_modules` 不再存在断开的 Electron symlink。

## 后续建议

### 可在确认后物理删除的回收目录

以下目录已经移入 `recycle`，当前不再作为 active 实现路径使用。若后续运行一段时间确认无回滚需求，可以物理删除以释放空间：

- `recycle/20260520-build-cache-cleanup/`，约 `53G`
- `recycle/20260520-pnpm-store-legacy/`，约 `2.6G`
- `recycle/20260520-graphify-uninstall/`，约 `433M`
- `recycle/20260520-local-sandbox-cleanup/`，约 `912K`
- `recycle/20260520-graph-cleanup/`，约 `40K`

### 仍需持续遵守的规则

- 不把 `.gitignore` 内容直接等同于废弃内容。
- 不从 `recycle` 中回退引用运行时代码。
- 新增 CodeGraph 主索引排除项时，应优先判断其是否属于参考代码、生成缓存、测试输出、回收区或本地辅助功能。
- 后续依赖变化后应重新运行 `pnpm install`，CodeGraph 在代码变化后需要重建或等待 watcher 更新；若排除规则变化，需显式重新初始化 / 重建索引。