# 工作空间文件系统

<cite>
**本文引用的文件**
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)
- [layout.tsx](file://src/app/layout.tsx)
- [page.tsx](file://src/app/page.tsx)
- [forge-file-editor.tsx](file://src/components/layout/forge-file-editor.tsx)
- [left-sidebar.tsx](file://src/components/layout/left-sidebar.tsx)
- [right-sidebar.tsx](file://src/components/layout/right-sidebar.tsx)
- [project-modal.tsx](file://src/components/layout/project-modal.tsx)
- [use-workspaces.ts](file://src/hooks/use-workspaces.ts)
- [workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts)
- [files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts)
- [agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts)
- [skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts)
- [diff/route.ts](file://src/app/api/workspaces/[id]/diff/route.ts)
- [init/route.ts](file://src/app/api/workspaces/[id]/init/route.ts)
- [fs/import/route.ts](file://src/app/api/workspaces/[id]/fs/import/route.ts)
- [upload/route.ts](file://src/app/api/upload/[filename]/route.ts)
- [marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)
- [templates/init/CLAUDE.md](file://templates/init/CLAUDE.md)
- [templates/init/SOUL.md](file://templates/init/SOUL.md)
- [templates/init/IDENTITY.md](file://templates/init/IDENTITY.md)
- [templates/init/MEMORY.md](file://templates/init/MEMORY.md)
- [templates/init/HEARTBEAT.md](file://templates/init/HEARTBEAT.md)
- [templates/init/USER.md](file://templates/init/USER.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统围绕“工作空间”概念构建，采用虚拟文件系统（VFS）与本地文件系统结合的方式，将每个工作空间映射到本地目录，并在其中维护两套结构：
- 项目根目录：存放实际业务文件
- 配置目录 .claude/：存放工作空间配置、规则、记忆体等上下文文件

该系统提供：
- 虚拟文件系统架构与路径解析
- 项目树构建与文件操作接口
- 文件上传/下载与导入导出机制
- 权限控制与安全校验
- 工作空间初始化、模板管理与项目克隆
- 文件监听、变更通知与冲突处理
- 压缩、缓存策略与性能优化
- 抽象层、路径解析与跨平台兼容

## 项目结构
从仓库结构可见，前端使用 Next.js App Router，后端 API 通过 app/api 下的路由实现；核心文件系统逻辑位于 src/lib 目录，Electron 主进程负责桌面应用集成。

```mermaid
graph TB
subgraph "前端"
UI["页面与组件<br/>layout.tsx / page.tsx"]
Editor["文件编辑器<br/>forge-file-editor.tsx"]
Sidebar["侧边栏<br/>left-sidebar.tsx / right-sidebar.tsx"]
Hooks["工作空间钩子<br/>use-workspaces.ts"]
end
subgraph "后端 API"
WSRoute["工作空间路由<br/>workspaces/route.ts"]
Tree["树形接口<br/>tree/route.ts / forge-tree/route.ts / agents-tree/route.ts / skills-tree/route.ts"]
Files["文件接口<br/>files/route.ts"]
Diff["差异接口<br/>diff/route.ts"]
Init["初始化接口<br/>init/route.ts"]
Import["导入接口<br/>fs/import/route.ts"]
Upload["上传接口<br/>upload/[filename]/route.ts"]
Market["市场接口<br/>marketplace/route.ts / save-from-workspace/route.ts"]
end
subgraph "核心库"
FS["工作空间文件系统<br/>workspace-fs.ts"]
MP["市场文件系统<br/>marketplace-fs.ts"]
DB["数据库<br/>db.ts"]
Data["数据目录<br/>forge-data.ts"]
end
subgraph "桌面集成"
Main["主进程<br/>electron/main.ts"]
Preload["预加载<br/>electron/preload.ts"]
end
UI --> Hooks
Hooks --> WSRoute
WSRoute --> Tree
WSRoute --> Files
WSRoute --> Diff
WSRoute --> Init
WSRoute --> Import
WSRoute --> Upload
WSRoute --> Market
Tree --> FS
Files --> FS
Diff --> FS
Init --> FS
Import --> FS
Upload --> Data
Market --> MP
FS --> DB
FS --> Data
Main --> FS
Preload --> FS
```

图表来源
- [layout.tsx](file://src/app/layout.tsx)
- [page.tsx](file://src/app/page.tsx)
- [forge-file-editor.tsx](file://src/components/layout/forge-file-editor.tsx)
- [left-sidebar.tsx](file://src/components/layout/left-sidebar.tsx)
- [right-sidebar.tsx](file://src/components/layout/right-sidebar.tsx)
- [use-workspaces.ts](file://src/hooks/use-workspaces.ts)
- [workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts)
- [files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts)
- [agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts)
- [skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts)
- [diff/route.ts](file://src/app/api/workspaces/[id]/diff/route.ts)
- [init/route.ts](file://src/app/api/workspaces/[id]/init/route.ts)
- [fs/import/route.ts](file://src/app/api/workspaces/[id]/fs/import/route.ts)
- [upload/route.ts](file://src/app/api/upload/[filename]/route.ts)
- [marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)

章节来源
- [layout.tsx](file://src/app/layout.tsx)
- [page.tsx](file://src/app/page.tsx)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)

## 核心组件
- 工作空间文件系统（workspace-fs.ts）
  - 提供工作空间路径解析、.claude/ 与项目根目录的文件操作、上下文加载、规则加载、记忆归档等能力
  - 支持全局工作空间（~/.claude）与普通工作空间（项目/.claude）
- 市场文件系统（marketplace-fs.ts）
  - 提供模板目录扫描、模板与工作空间之间的复制、排除策略（如 MEMORY.md、memory/、HEARTBEAT.md）
- 数据目录与数据库（forge-data.ts、db.ts）
  - 统一数据目录 ~/.forge/ 的获取与迁移，数据库初始化与迁移脚本
- 桌面集成（electron/main.ts、electron/preload.ts）
  - 主进程与渲染进程的安全桥接，暴露受限 API

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [db.ts](file://src/lib/db.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)

## 架构总览
工作空间文件系统以“工作空间 ID”为入口，通过数据库查询项目路径，再在项目根目录与 .claude/ 配置目录之间进行文件操作。模板系统独立于工作空间，存储在 ~/.forge/marketplace/<templateId>/ 中，支持双向复制。

```mermaid
graph TB
WS["工作空间 ID"]
DB["数据库<br/>workspaces 表"]
Proj["项目根目录"]
Forge[".claude/ 配置目录"]
MP["市场模板目录<br/>~/.forge/marketplace/<templateId>"]
WS --> DB
DB --> Proj
Proj --> Forge
Forge --> WS
Proj < --> MP
```

图表来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 详细组件分析

### 虚拟文件系统与路径解析
- 全局工作空间
  - 使用常量标识与 HOME 目录下的 ~/.claude/ 作为根
- 普通工作空间
  - 通过数据库 workspaces 表查询 path 字段，得到项目根目录
  - .claude/ 位于项目根目录下
- 安全路径解析
  - 所有相对路径操作均进行 “..” 检查与 resolve 校验，防止路径穿越
- 默认文件与目录
  - 初始化时确保标准子目录存在（memory、skills、agents、rules）
  - 默认配置文件（CLAUDE.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md）

```mermaid
flowchart TD
Start(["开始"]) --> CheckWS["判断是否为全局工作空间"]
CheckWS --> |是| Home["返回 HOME 目录"]
CheckWS --> |否| QueryDB["查询数据库 workspaces 表"]
QueryDB --> Found{"找到记录？"}
Found --> |否| ThrowErr["抛出错误：未找到工作空间"]
Found --> |是| GetPath["获取项目路径"]
GetPath --> MakeForge["拼接 .claude/ 路径"]
Home --> MakeForge
MakeForge --> End(["结束"])
```

图表来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [db.ts](file://src/lib/db.ts)

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [db.ts](file://src/lib/db.ts)

### 项目树构建与文件操作接口
- 项目树
  - 通过 tree/route.ts、forge-tree/route.ts、agents-tree/route.ts、skills-tree/route.ts 返回树形结构
  - marketplace-fs.ts 提供模板树构建 buildTemplateTree
- 文件操作
  - .claude/ 内部文件：createForgeFile/renameForgeEntry/deleteForgeEntry
  - 项目根文件：createProjectFile/renameProjectEntry/deleteProjectEntry
  - 通用读写：readWorkspaceFile/writeWorkspaceFile
- 安全与校验
  - 所有重命名/删除/创建前检查目标是否存在、父目录是否存在并递归创建
  - 路径中禁止出现 “..”

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "API 路由"
participant FS as "workspace-fs"
participant OS as "文件系统"
C->>API : "POST /api/workspaces/[id]/files"
API->>FS : "createProjectFile(workspaceId, relativePath, content)"
FS->>FS : "校验相对路径合法性"
FS->>OS : "mkdir -p 父目录"
FS->>OS : "写入文件"
OS-->>FS : "成功"
FS-->>API : "返回成功"
API-->>C : "201 Created"
```

图表来源
- [files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)

章节来源
- [tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts)
- [forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts)
- [agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts)
- [skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts)
- [files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

### 文件上传下载与导入导出
- 上传
  - 上传接口将文件写入 Forge 数据目录 uploads 子目录，路径由 forge-data.ts 提供
- 导入
  - fs/import/route.ts 将外部内容导入工作空间 .claude/ 或项目根目录
- 下载
  - 可通过文件读取接口或直接访问 uploads 目录中的文件（受权限控制）

```mermaid
sequenceDiagram
participant C as "客户端"
participant U as "upload/[filename]/route.ts"
participant FD as "forge-data.ts"
participant FS as "文件系统"
C->>U : "POST /api/upload/[file]"
U->>FD : "getUploadsDir()"
FD-->>U : "返回 uploads 路径"
U->>FS : "写入文件"
FS-->>U : "完成"
U-->>C : "201 Created"
```

图表来源
- [upload/route.ts](file://src/app/api/upload/[filename]/route.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)

章节来源
- [upload/route.ts](file://src/app/api/upload/[filename]/route.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [fs/import/route.ts](file://src/app/api/workspaces/[id]/fs/import/route.ts)

### 权限控制与安全验证
- 路径安全
  - 所有相对路径操作均进行 “..” 过滤与 resolve 校验，避免路径穿越
- 目录隔离
  - .claude/ 与项目根目录分离，限制可写范围
- 模板复制排除
  - marketplace 复制时排除 MEMORY.md、memory/、HEARTBEAT.md，避免污染用户记忆
- 数据目录统一
  - 通过环境变量 FORGE_DATA_DIR 控制数据目录位置，便于沙箱化部署

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)

### 工作空间初始化、模板管理与项目克隆
- 初始化
  - ensureWorkspaceDir：轻量级保证 .claude/ 存在且包含标准子目录
  - initializeWorkspaceDir：完整初始化，含默认文件与历史迁移（.forge → .claude）
- 模板管理
  - marketplace 目录结构与 .claude/ 一致，支持从工作空间复制到模板、从模板复制到工作空间
  - 模板树 buildTemplateTree 支持最大深度控制
- 项目克隆
  - marketplace/save-from-workspace/route.ts 将当前工作空间 .claude/ 结构保存为模板
  - marketplace/route.ts 提供模板列表与操作入口

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "save-from-workspace/route.ts"
participant FS as "workspace-fs.ts"
participant MP as "marketplace-fs.ts"
C->>API : "POST /api/marketplace/save-from-workspace"
API->>FS : "ensureWorkspaceDir"
FS-->>API : "完成"
API->>MP : "copyClaudeToTemplate(projectPath, templateId)"
MP-->>API : "完成"
API-->>C : "200 OK"
```

图表来源
- [save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)

### 文件监听、变更通知与冲突解决
- 监听与通知
  - 建议在渲染进程中通过轮询或基于文件系统事件（需 Electron 集成）检测 .claude/ 与项目根目录变化
  - 变更后触发树刷新与编辑器状态更新
- 冲突解决
  - 对于同名文件，优先保留用户修改；导入时可提供覆盖/跳过策略
  - 记忆归档 archiveOldMemories 自动清理旧日志，减少冲突

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)

### 上下文加载与规则系统
- 工作空间上下文
  - loadWorkspaceContext 动态读取 .claude/ 根目录所有 .md 文件，按字母序拼接，排除 CLAUDE.md 与 MEMORY.md
- 记忆上下文
  - loadMemoryContext 仅加载 MEMORY.md 前 200 行与最近两天的每日记忆，避免启动时加载过多内容
- 规则系统
  - loadRulesContext 递归读取 rules/ 下 .md 文件，支持 YAML frontmatter 的 paths 字段进行条件加载

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)

### 模板与默认文件
- 模板目录
  - templates/init/ 下包含默认配置文件，用于新工作空间初始化
- 默认文件清单
  - CLAUDE.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md

章节来源
- [templates/init/CLAUDE.md](file://templates/init/CLAUDE.md)
- [templates/init/SOUL.md](file://templates/init/SOUL.md)
- [templates/init/IDENTITY.md](file://templates/init/IDENTITY.md)
- [templates/init/MEMORY.md](file://templates/init/MEMORY.md)
- [templates/init/HEARTBEAT.md](file://templates/init/HEARTBEAT.md)
- [templates/init/USER.md](file://templates/init/USER.md)

## 依赖关系分析
- workspace-fs.ts 依赖 db.ts 获取项目路径，依赖 forge-data.ts 获取数据目录
- marketplace-fs.ts 依赖 forge-data.ts 获取市场目录
- Electron 主进程与预加载脚本为渲染进程提供受限 API，保障文件系统调用安全

```mermaid
graph LR
FS["workspace-fs.ts"] --> DB["db.ts"]
FS --> Data["forge-data.ts"]
MP["marketplace-fs.ts"] --> Data
Main["electron/main.ts"] --> FS
Preload["electron/preload.ts"] --> FS
```

图表来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [db.ts](file://src/lib/db.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [main.ts](file://electron/main.ts)
- [preload.ts](file://electron/preload.ts)

## 性能考虑
- 启动时加载策略
  - 仅加载必要的上下文片段，MEMORY.md 限制行数，规则按需加载
- 目录扫描
  - 树构建时限制最大深度，避免深层目录造成性能问题
- I/O 优化
  - 批量读取与写入，避免频繁小文件操作
- 缓存策略
  - 对热点文件（如 CLAUDE.md、常用规则）可引入内存缓存，定期失效
- 归档与清理
  - archiveOldMemories 自动清理旧日志，降低磁盘压力

章节来源
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 故障排查指南
- 工作空间未找到
  - 检查数据库 workspaces 表中是否存在对应记录
- 路径非法
  - 确认相对路径不包含 “..”，并进行 resolve 校验
- 权限不足
  - 确认运行用户对 ~/.forge/ 与项目目录具有读写权限
- 模板复制失败
  - 检查模板目录是否存在，确认未被排除的文件是否正确复制
- 数据迁移异常
  - 查看 migrateFromOldDataDir 的日志输出，确认新旧目录结构

章节来源
- [db.ts](file://src/lib/db.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [forge-data.ts](file://src/lib/forge-data.ts)
- [marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 结论
该工作空间文件系统通过清晰的抽象层与严格的路径安全策略，实现了对 .claude/ 与项目根目录的统一管理。配合模板系统与上下文加载机制，满足了多工作空间、多模板场景下的高效开发与协作需求。建议在生产环境中结合文件系统事件与缓存策略进一步提升性能与用户体验。

## 附录
- 关键 API 路由
  - 工作空间：/api/workspaces
  - 树形：/api/workspaces/[id]/tree, /api/workspaces/[id]/forge-tree, /api/workspaces/[id]/agents-tree, /api/workspaces/[id]/skills-tree
  - 文件：/api/workspaces/[id]/files
  - 差异：/api/workspaces/[id]/diff
  - 初始化：/api/workspaces/[id]/init
  - 导入：/api/workspaces/[id]/fs/import
  - 上传：/api/upload/[filename]
  - 市场：/api/marketplace, /api/marketplace/save-from-workspace

章节来源
- [workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts)
- [forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts)
- [agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts)
- [skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts)
- [files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [diff/route.ts](file://src/app/api/workspaces/[id]/diff/route.ts)
- [init/route.ts](file://src/app/api/workspaces/[id]/init/route.ts)
- [fs/import/route.ts](file://src/app/api/workspaces/[id]/fs/import/route.ts)
- [upload/route.ts](file://src/app/api/upload/[filename]/route.ts)
- [marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)