# 工作空间API

<cite>
**本文引用的文件**
- [src/app/api/workspaces/route.ts](file://src/app/api/workspaces/route.ts)
- [src/app/api/workspaces/[id]/route.ts](file://src/app/api/workspaces/[id]/route.ts)
- [src/app/api/workspaces/[id]/files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts)
- [src/app/api/workspaces/[id]/tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts)
- [src/app/api/workspaces/[id]/forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts)
- [src/app/api/workspaces/[id]/init/route.ts](file://src/app/api/workspaces/[id]/init/route.ts)
- [src/app/api/workspaces/[id]/diff/route.ts](file://src/app/api/workspaces/[id]/diff/route.ts)
- [src/app/api/workspaces/[id]/agents/route.ts](file://src/app/api/workspaces/[id]/agents/route.ts)
- [src/app/api/workspaces/[id]/skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts)
- [src/app/api/workspaces/[id]/agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts)
- [src/app/api/sessions/route.ts](file://src/app/api/sessions/route.ts)
- [src/app/api/sessions/[id]/route.ts](file://src/app/api/sessions/[id]/route.ts)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts)
- [src/app/api/sessions/[id]/clear/route.ts](file://src/app/api/sessions/[id]/clear/route.ts)
- [src/app/api/sessions/[id]/compact/route.ts](file://src/app/api/sessions/[id]/compact/route.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：API使用示例与最佳实践](#附录api使用示例与最佳实践)

## 简介
本文件为Forge工作空间API的权威参考文档，覆盖以下主题：
- 工作空间文件系统：文件浏览、读取、写入、树形结构展示与初始化
- 会话管理：会话创建、查询、更新、删除、消息获取、清空与压缩
- 权限与安全：路径遍历防护、隐藏目录策略、前端权限桥接清理
- 版本与同步：基于git的差异查看（diff）
- 模板与初始化：默认配置文件生成与模板应用
- 实用流程：项目初始化、模板应用、文件同步与版本管理

## 项目结构
工作空间API采用Next.js App Router约定式路由，按功能域组织在src/app/api下：
- 工作空间域：/api/workspaces/[id]/*（含文件、树、初始化、差异等）
- 会话域：/api/sessions/[id]/*（含消息、清空、压缩等）

```mermaid
graph TB
subgraph "工作空间API"
WS_ROOT["/api/workspaces<br/>GET/POST 列表与创建"]
WS_ID["/api/workspaces/[id]<br/>PATCH 更新/DELETE 删除"]
WS_FILES["/api/workspaces/[id]/files<br/>GET/PUT 文件读写"]
WS_TREE["/api/workspaces/[id]/tree<br/>项目树"]
WS_FORGE["/api/workspaces/[id]/forge-tree<br/>.claude子树"]
WS_INIT["/api/workspaces/[id]/init<br/>初始化模板"]
WS_DIFF["/api/workspaces/[id]/diff<br/>git diff"]
WS_AGENTS["/api/workspaces/[id]/agents<br/>子代理管理"]
WS_ATREE["/api/workspaces/[id]/agents-tree<br/>代理树"]
WS_STREE["/api/workspaces/[id]/skills-tree<br/>技能树"]
end
subgraph "会话API"
SES_ROOT["/api/sessions<br/>GET/POST 会话列表与创建"]
SES_ID["/api/sessions/[id]<br/>GET/PATCH/DELETE 查询/更新/删除"]
SES_MSG["/api/sessions/[id]/messages<br/>消息列表"]
SES_CLEAR["/api/sessions/[id]/clear<br/>清空消息"]
SES_COMPACT["/api/sessions/[id]/compact<br/>压缩会话"]
end
WS_ROOT --> WS_ID
WS_ID --> WS_FILES
WS_ID --> WS_TREE
WS_ID --> WS_FORGE
WS_ID --> WS_INIT
WS_ID --> WS_DIFF
WS_ID --> WS_AGENTS
WS_ID --> WS_ATREE
WS_ID --> WS_STREE
SES_ROOT --> SES_ID
SES_ID --> SES_MSG
SES_ID --> SES_CLEAR
SES_ID --> SES_COMPACT
```

图表来源
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/app/api/workspaces/[id]/route.ts](file://src/app/api/workspaces/[id]/route.ts#L1-L33)
- [src/app/api/workspaces/[id]/files/route.ts](file://src/app/api/workspaces/[id]/files/route.ts#L1-L35)
- [src/app/api/workspaces/[id]/tree/route.ts](file://src/app/api/workspaces/[id]/tree/route.ts#L1-L82)
- [src/app/api/workspaces/[id]/forge-tree/route.ts](file://src/app/api/workspaces/[id]/forge-tree/route.ts#L1-L57)
- [src/app/api/workspaces/[id]/init/route.ts](file://src/app/api/workspaces/[id]/init/route.ts#L1-L77)
- [src/app/api/workspaces/[id]/diff/route.ts](file://src/app/api/workspaces/[id]/diff/route.ts#L1-L44)
- [src/app/api/workspaces/[id]/agents/route.ts](file://src/app/api/workspaces/[id]/agents/route.ts#L1-L78)
- [src/app/api/workspaces/[id]/agents-tree/route.ts](file://src/app/api/workspaces/[id]/agents-tree/route.ts#L1-L71)
- [src/app/api/workspaces/[id]/skills-tree/route.ts](file://src/app/api/workspaces/[id]/skills-tree/route.ts#L1-L73)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/sessions/[id]/route.ts](file://src/app/api/sessions/[id]/route.ts#L1-L49)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts#L1-L13)
- [src/app/api/sessions/[id]/clear/route.ts](file://src/app/api/sessions/[id]/clear/route.ts#L1-L19)
- [src/app/api/sessions/[id]/compact/route.ts](file://src/app/api/sessions/[id]/compact/route.ts#L1-L66)

章节来源
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)
- [src/app/api/workspaces/[id]/route.ts:1-33](file://src/app/api/workspaces/[id]/route.ts#L1-L33)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)

## 核心组件
- 工作空间注册与元数据
  - 列表与创建：支持按路径注册工作空间，并自动初始化默认配置目录
  - 更新最近打开时间：访问时刷新last_opened_at
  - 删除：幂等删除，同时清理关联会话
- 文件系统接口
  - 读取指定文件内容
  - 写入文件内容（以JSON形式传入name与content）
- 树形结构
  - 项目树：过滤隐藏目录，限制最大深度，.claude优先
  - Forge树：列出.memory/.agents/.skills及根部配置文件
  - 技能树：扫描skills目录，识别启用状态
  - 代理树：解析代理文件frontmatter，标注模型信息
- 会话管理
  - 创建、查询、更新、删除
  - 消息列表查询
  - 清空消息
  - 压缩会话：将历史消息汇总为一条总结消息
- 初始化与模板
  - 初始化默认配置目录与文件
  - 返回模板内容供Agent使用
- 版本与差异
  - 在项目目录执行git diff，返回差异或友好错误提示

章节来源
- [src/app/api/workspaces/route.ts:8-22](file://src/app/api/workspaces/route.ts#L8-L22)
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- [src/app/api/workspaces/[id]/route.ts:5-17](file://src/app/api/workspaces/[id]/route.ts#L5-L17)
- [src/app/api/workspaces/[id]/route.ts:19-32](file://src/app/api/workspaces/[id]/route.ts#L19-L32)
- [src/app/api/workspaces/[id]/files/route.ts:4-17](file://src/app/api/workspaces/[id]/files/route.ts#L4-L17)
- [src/app/api/workspaces/[id]/files/route.ts:19-34](file://src/app/api/workspaces/[id]/files/route.ts#L19-L34)
- [src/app/api/workspaces/[id]/tree/route.ts:49-81](file://src/app/api/workspaces/[id]/tree/route.ts#L49-L81)
- [src/app/api/workspaces/[id]/forge-tree/route.ts:13-56](file://src/app/api/workspaces/[id]/forge-tree/route.ts#L13-L56)
- [src/app/api/workspaces/[id]/skills-tree/route.ts:53-72](file://src/app/api/workspaces/[id]/skills-tree/route.ts#L53-L72)
- [src/app/api/workspaces/[id]/agents-tree/route.ts:51-70](file://src/app/api/workspaces/[id]/agents-tree/route.ts#L51-L70)
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/sessions/route.ts:18-33](file://src/app/api/sessions/route.ts#L18-L33)
- [src/app/api/sessions/[id]/route.ts:5-12](file://src/app/api/sessions/[id]/route.ts#L5-L12)
- [src/app/api/sessions/[id]/route.ts:14-39](file://src/app/api/sessions/[id]/route.ts#L14-L39)
- [src/app/api/sessions/[id]/route.ts:41-48](file://src/app/api/sessions/[id]/route.ts#L41-L48)
- [src/app/api/sessions/[id]/messages/route.ts:4-12](file://src/app/api/sessions/[id]/messages/route.ts#L4-L12)
- [src/app/api/sessions/[id]/clear/route.ts:5-18](file://src/app/api/sessions/[id]/clear/route.ts#L5-L18)
- [src/app/api/sessions/[id]/compact/route.ts:5-65](file://src/app/api/sessions/[id]/compact/route.ts#L5-L65)
- [src/app/api/workspaces/[id]/init/route.ts:36-76](file://src/app/api/workspaces/[id]/init/route.ts#L36-L76)
- [src/app/api/workspaces/[id]/diff/route.ts:6-43](file://src/app/api/workspaces/[id]/diff/route.ts#L6-L43)

## 架构总览
工作空间API围绕“工作空间”和“会话”两大实体构建，通过数据库持久化元数据，结合本地文件系统实现配置与内容管理；树形结构与初始化逻辑确保用户可直观浏览与快速上手。

```mermaid
graph TB
Client["客户端"] --> WS_API["工作空间API"]
Client --> SES_API["会话API"]
WS_API --> DB["SQLite 数据库"]
WS_API --> FS["本地文件系统"]
WS_API --> GIT["git 可执行程序"]
SES_API --> DB
SES_API --> PERM["权限桥接清理"]
FS --> WS_DIR[".claude 配置目录"]
FS --> PRJ_DIR["项目根目录"]
```

图表来源
- [src/app/api/workspaces/route.ts:1-6](file://src/app/api/workspaces/route.ts#L1-L6)
- [src/app/api/sessions/route.ts:1-4](file://src/app/api/sessions/route.ts#L1-L4)
- [src/app/api/sessions/[id]/route.ts:3-L4](file://src/app/api/sessions/[id]/route.ts#L3-L4)
- [src/app/api/workspaces/[id]/diff/route.ts:4-L5](file://src/app/api/workspaces/[id]/diff/route.ts#L4-L5)

## 详细组件分析

### 工作空间注册与生命周期
- 列表与创建
  - GET：返回已注册工作空间列表，附加名称与存在性标记
  - POST：校验路径存在且为目录；若未注册则插入记录并初始化默认配置目录；更新最近打开时间
- 更新与删除
  - PATCH：更新最近打开时间并返回
  - DELETE：幂等删除；同时清理关联会话

```mermaid
sequenceDiagram
participant C as "客户端"
participant W as "工作空间API"
participant D as "数据库"
participant F as "文件系统"
C->>W : POST /api/workspaces {path}
W->>F : 校验路径存在且为目录
alt 已存在
W->>D : UPDATE 最近打开时间
D-->>W : 返回记录
else 新建
W->>D : INSERT 记录
W->>F : 初始化默认配置目录
D-->>W : 返回新建记录
end
W-->>C : {id, path, name, exists...}
```

图表来源
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)

章节来源
- [src/app/api/workspaces/route.ts:8-22](file://src/app/api/workspaces/route.ts#L8-L22)
- [src/app/api/workspaces/route.ts:24-59](file://src/app/api/workspaces/route.ts#L24-L59)
- [src/app/api/workspaces/[id]/route.ts:5-17](file://src/app/api/workspaces/[id]/route.ts#L5-L17)
- [src/app/api/workspaces/[id]/route.ts:19-32](file://src/app/api/workspaces/[id]/route.ts#L19-L32)

### 文件系统接口
- 读取文件
  - GET /api/workspaces/[id]/files?name=...：校验非法字符后读取，返回内容
- 写入文件
  - PUT /api/workspaces/[id]/files：校验参数与非法字符后写入

```mermaid
flowchart TD
Start(["请求进入"]) --> CheckName["校验 name 参数"]
CheckName --> NameOK{"合法?"}
NameOK -- 否 --> Err400["返回 400 错误"]
NameOK -- 是 --> ReadOrWrite{"GET 还是 PUT"}
ReadOrWrite -- GET --> Read["读取文件内容"]
Read --> Found{"找到?"}
Found -- 否 --> Err404["返回 404"]
Found -- 是 --> OK200["返回 {filename, content}"]
ReadOrWrite -- PUT --> Write["写入文件内容"]
Write --> OK200
```

图表来源
- [src/app/api/workspaces/[id]/files/route.ts:4-L17](file://src/app/api/workspaces/[id]/files/route.ts#L4-L17)
- [src/app/api/workspaces/[id]/files/route.ts:19-L34](file://src/app/api/workspaces/[id]/files/route.ts#L19-L34)

章节来源
- [src/app/api/workspaces/[id]/files/route.ts:4-17](file://src/app/api/workspaces/[id]/files/route.ts#L4-L17)
- [src/app/api/workspaces/[id]/files/route.ts:19-34](file://src/app/api/workspaces/[id]/files/route.ts#L19-L34)

### 树形结构与权限控制
- 项目树
  - 过滤隐藏目录（如node_modules、__pycache__等），.claude始终显示
  - 限制最大深度，文件夹优先于文件排序
- Forge树
  - 展示.memory/.agents/.skills子目录与根部配置文件
- 技能树与代理树
  - 递归扫描，识别启用状态与模型信息
- 安全与权限
  - 路径遍历防护：禁止包含“..”
  - 隐藏目录策略：隐藏以点开头的目录
  - 全局工作空间模式：统一展示~/.claude

```mermaid
flowchart TD
S(["GET /tree"]) --> IsGlobal{"是否全局工作空间?"}
IsGlobal -- 是 --> Ensure["确保 .claude 目录存在"]
Ensure --> BuildG["构建 .claude 树"]
IsGlobal -- 否 --> CheckDB["查询项目路径"]
CheckDB --> Exists{"路径存在?"}
Exists -- 否 --> Empty["返回空树+缺失标记"]
Exists -- 是 --> BuildP["构建项目树"]
BuildG --> R(["返回 {tree}"])
BuildP --> R
```

图表来源
- [src/app/api/workspaces/[id]/tree/route.ts:49-L81](file://src/app/api/workspaces/[id]/tree/route.ts#L49-L81)
- [src/app/api/workspaces/[id]/forge-tree/route.ts:13-L56](file://src/app/api/workspaces/[id]/forge-tree/route.ts#L13-L56)
- [src/app/api/workspaces/[id]/skills-tree/route.ts:53-L72](file://src/app/api/workspaces/[id]/skills-tree/route.ts#L53-L72)
- [src/app/api/workspaces/[id]/agents-tree/route.ts:51-L70](file://src/app/api/workspaces/[id]/agents-tree/route.ts#L51-L70)

章节来源
- [src/app/api/workspaces/[id]/tree/route.ts:13-L47](file://src/app/api/workspaces/[id]/tree/route.ts#L13-L47)
- [src/app/api/workspaces/[id]/tree/route.ts:49-81](file://src/app/api/workspaces/[id]/tree/route.ts#L49-L81)
- [src/app/api/workspaces/[id]/forge-tree/route.ts:13-56](file://src/app/api/workspaces/[id]/forge-tree/route.ts#L13-L56)
- [src/app/api/workspaces/[id]/skills-tree/route.ts:14-L51](file://src/app/api/workspaces/[id]/skills-tree/route.ts#L14-L51)
- [src/app/api/workspaces/[id]/agents-tree/route.ts:16-L49](file://src/app/api/workspaces/[id]/agents-tree/route.ts#L16-L49)

### 会话管理
- 列表与创建
  - GET：自动清理过期会话后返回活跃会话列表
  - POST：创建新会话并返回
- 查询、更新与删除
  - GET/PATCH/DELETE：按ID查询、更新字段、删除并清理权限
- 消息管理
  - GET：按时间顺序返回消息列表
  - POST /clear：清空消息
  - POST /compact：压缩为一条总结消息

```mermaid
sequenceDiagram
participant C as "客户端"
participant S as "会话API"
participant D as "数据库"
participant P as "权限桥接"
C->>S : POST /sessions {title, workspace, model}
S->>D : INSERT 会话
D-->>S : 返回会话
S-->>C : 201 {会话详情}
C->>S : GET /sessions
S->>S : 自动清理过期会话
S->>D : SELECT 活跃会话
D-->>S : 列表
S-->>C : {会话数组}
C->>S : POST /sessions/ : id/compact
S->>D : SELECT 所有消息
S->>S : 生成摘要
S->>D : DELETE + INSERT 总结消息
S-->>C : {ok, compacted}
```

图表来源
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/sessions/route.ts:18-33](file://src/app/api/sessions/route.ts#L18-L33)
- [src/app/api/sessions/[id]/compact/route.ts:5-L65](file://src/app/api/sessions/[id]/compact/route.ts#L5-L65)

章节来源
- [src/app/api/sessions/route.ts:6-16](file://src/app/api/sessions/route.ts#L6-L16)
- [src/app/api/sessions/route.ts:18-33](file://src/app/api/sessions/route.ts#L18-L33)
- [src/app/api/sessions/[id]/route.ts:5-12](file://src/app/api/sessions/[id]/route.ts#L5-L12)
- [src/app/api/sessions/[id]/route.ts:14-39](file://src/app/api/sessions/[id]/route.ts#L14-L39)
- [src/app/api/sessions/[id]/route.ts:41-48](file://src/app/api/sessions/[id]/route.ts#L41-L48)
- [src/app/api/sessions/[id]/messages/route.ts:4-12](file://src/app/api/sessions/[id]/messages/route.ts#L4-L12)
- [src/app/api/sessions/[id]/clear/route.ts:5-18](file://src/app/api/sessions/[id]/clear/route.ts#L5-L18)
- [src/app/api/sessions/[id]/compact/route.ts:5-65](file://src/app/api/sessions/[id]/compact/route.ts#L5-L65)

### 初始化与模板应用
- 初始化默认配置目录与文件
  - 读取内置模板目录（生产环境从资源路径，开发环境从当前目录）
  - 对比前后文件集合，区分新建与跳过的文件
  - 返回模板内容与统计信息
- 使用场景
  - 新项目首次接入
  - 重置或修复配置文件

```mermaid
flowchart TD
Start(["POST /init"]) --> Ensure["确保 .claude 目录存在"]
Ensure --> Snap["快照现有 .md 文件"]
Snap --> Init["初始化默认文件"]
Init --> Diff["计算新建/跳过文件"]
Diff --> ReadT["读取模板内容"]
ReadT --> Resp["返回 {ok, created, skipped, templates}"]
```

图表来源
- [src/app/api/workspaces/[id]/init/route.ts:36-L76](file://src/app/api/workspaces/[id]/init/route.ts#L36-L76)

章节来源
- [src/app/api/workspaces/[id]/init/route.ts:11-L34](file://src/app/api/workspaces/[id]/init/route.ts#L11-L34)
- [src/app/api/workspaces/[id]/init/route.ts:40-L76](file://src/app/api/workspaces/[id]/init/route.ts#L40-L76)

### 版本与差异（Git）
- 在项目目录执行git diff，返回差异内容或友好错误信息
- 全局工作空间不支持该操作

```mermaid
sequenceDiagram
participant C as "客户端"
participant D as "差异API"
participant G as "git"
participant P as "项目目录"
C->>D : GET /workspaces/ : id/diff
D->>P : 获取项目路径
alt 全局工作空间
D-->>C : {message : 不支持}
else 项目工作空间
D->>G : 执行 git diff
alt 无变更
D-->>C : {message : 无未提交变更}
else 有变更
D-->>C : {diff : 输出}
end
end
```

图表来源
- [src/app/api/workspaces/[id]/diff/route.ts:6-L43](file://src/app/api/workspaces/[id]/diff/route.ts#L6-L43)

章节来源
- [src/app/api/workspaces/[id]/diff/route.ts:9-L43](file://src/app/api/workspaces/[id]/diff/route.ts#L9-L43)

### 子代理与技能管理
- 子代理
  - GET：读取agents目录下的Markdown文件，解析frontmatter，返回代理清单
  - POST：创建新的代理文件（避免冲突）
- 技能树与代理树
  - 递归扫描目录，识别启用状态与模型信息，用于UI展示与权限判断

章节来源
- [src/app/api/workspaces/[id]/agents/route.ts:7-L36](file://src/app/api/workspaces/[id]/agents/route.ts#L7-L36)
- [src/app/api/workspaces/[id]/agents/route.ts:38-L78](file://src/app/api/workspaces/[id]/agents/route.ts#L38-L78)
- [src/app/api/workspaces/[id]/skills-tree/route.ts:53-L72](file://src/app/api/workspaces/[id]/skills-tree/route.ts#L53-L72)
- [src/app/api/workspaces/[id]/agents-tree/route.ts:51-L70](file://src/app/api/workspaces/[id]/agents-tree/route.ts#L51-L70)

## 依赖关系分析
- 组件耦合
  - 工作空间API依赖数据库与文件系统；树形构建依赖文件系统遍历
  - 会话API依赖数据库与权限桥接清理
  - 差异API依赖git可执行程序与项目路径解析
- 外部依赖
  - SQLite：存储工作空间与会话元数据
  - 文件系统：.claude配置目录与项目文件
  - Git：版本差异查询
- 循环依赖
  - 未发现直接循环依赖；模块间通过工具函数解耦

```mermaid
graph LR
WS["工作空间API"] --> DB["数据库"]
WS --> FS["文件系统"]
WS --> GIT["git"]
SES["会话API"] --> DB
SES --> PERM["权限桥接"]
```

图表来源
- [src/app/api/workspaces/route.ts:1-6](file://src/app/api/workspaces/route.ts#L1-L6)
- [src/app/api/sessions/route.ts:1-4](file://src/app/api/sessions/route.ts#L1-L4)
- [src/app/api/sessions/[id]/route.ts:3-L4](file://src/app/api/sessions/[id]/route.ts#L3-L4)
- [src/app/api/workspaces/[id]/diff/route.ts:4-L5](file://src/app/api/workspaces/[id]/diff/route.ts#L4-L5)

章节来源
- [src/app/api/workspaces/route.ts:1-6](file://src/app/api/workspaces/route.ts#L1-L6)
- [src/app/api/sessions/route.ts:1-4](file://src/app/api/sessions/route.ts#L1-L4)
- [src/app/api/sessions/[id]/route.ts:3-L4](file://src/app/api/sessions/[id]/route.ts#L3-L4)
- [src/app/api/workspaces/[id]/diff/route.ts:4-L5](file://src/app/api/workspaces/[id]/diff/route.ts#L4-L5)

## 性能考量
- 树形构建
  - 限制最大深度，避免深层目录导致的I/O开销
  - 过滤隐藏目录，减少无效遍历
- 文件读写
  - 严格校验参数与路径，避免不必要的磁盘访问
- 会话压缩
  - 使用事务批量删除与插入，降低锁竞争
- Git操作
  - 设置超时与缓冲区上限，防止大仓库导致阻塞

## 故障排查指南
- 工作空间
  - 路径不存在或非目录：检查POST请求中的path参数
  - 删除后仍需清理会话：确认DELETE调用成功
- 文件系统
  - 返回“非法文件名”：检查name参数中是否包含“..”
  - 文件未找到：确认文件存在于对应工作空间目录
- 树形结构
  - 返回空树且标记缺失：确认项目目录存在
  - Forge树为空：确认初始化已完成
- 会话
  - 压缩失败：检查消息是否存在以及数据库连接
  - 清空失败：确认会话ID有效
- 差异
  - “不是git仓库”或“未安装git”：确认项目目录为git仓库且git可用

章节来源
- [src/app/api/workspaces/route.ts:36-38](file://src/app/api/workspaces/route.ts#L36-L38)
- [src/app/api/workspaces/[id]/files/route.ts:10-L11](file://src/app/api/workspaces/[id]/files/route.ts#L10-L11)
- [src/app/api/workspaces/[id]/files/route.ts:13-L14](file://src/app/api/workspaces/[id]/files/route.ts#L13-L14)
- [src/app/api/workspaces/[id]/tree/route.ts:62-L73](file://src/app/api/workspaces/[id]/tree/route.ts#L62-L73)
- [src/app/api/sessions/[id]/compact/route.ts:32-L42](file://src/app/api/sessions/[id]/compact/route.ts#L32-L42)
- [src/app/api/workspaces/[id]/diff/route.ts:32-L42](file://src/app/api/workspaces/[id]/diff/route.ts#L32-L42)

## 结论
Forge工作空间API提供了完整的工作空间与会话管理能力，结合树形结构与初始化模板，帮助用户高效地组织与维护项目配置。通过严格的路径校验与隐藏策略，保障了安全性与可用性；通过git集成与会话压缩，提升了版本管理与性能表现。

## 附录：API使用示例与最佳实践

- 工作空间
  - 注册工作空间：POST /api/workspaces {path: "..."}；随后GET /api/workspaces获取列表
  - 更新最近打开时间：PATCH /api/workspaces/{id}
  - 删除工作空间：DELETE /api/workspaces/{id}
- 文件系统
  - 读取文件：GET /api/workspaces/{id}/files?name=CLAUDE.md
  - 写入文件：PUT /api/workspaces/{id}/files {name, content}
- 树形结构
  - 项目树：GET /api/workspaces/{id}/tree
  - Forge树：GET /api/workspaces/{id}/forge-tree
  - 技能树：GET /api/workspaces/{id}/skills-tree
  - 代理树：GET /api/workspaces/{id}/agents-tree
- 初始化与模板
  - 初始化：POST /api/workspaces/{id}/init
- 版本与差异
  - 差异：GET /api/workspaces/{id}/diff
- 会话
  - 创建会话：POST /api/sessions {title, workspace, model}
  - 查询会话：GET /api/sessions
  - 更新会话：PATCH /api/sessions/{id} {title/model/workspace/status}
  - 删除会话：DELETE /api/sessions/{id}
  - 获取消息：GET /api/sessions/{id}/messages
  - 清空消息：POST /api/sessions/{id}/clear
  - 压缩会话：POST /api/sessions/{id}/compact

最佳实践
- 在调用文件读写前，先调用树形接口确认文件存在
- 使用初始化接口确保默认配置齐全后再进行后续操作
- 对于大型项目，定期执行会话压缩以降低内存占用
- 使用差异接口监控未提交变更，配合版本管理流程