# 市场和模板
**本文引用的文件**
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/components/marketplace/template-list-panel.tsx](file://src/components/marketplace/template-list-panel.tsx)
- [src/components/marketplace/template-editor-panel.tsx](file://src/components/marketplace/template-editor-panel.tsx)
- [src/components/views/marketplace-view.tsx](file://src/components/views/marketplace-view.tsx)
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [src/app/api/marketplace/[id]/route.ts](file://src/app/api/marketplace/[id]/route.ts)
- [src/app/api/marketplace/[id]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/route.ts)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts)
- [src/app/api/marketplace/save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [templates/init/CLAUDE.md](file://templates/init/CLAUDE.md)
- [templates/init/MEMORY.md](file://templates/init/MEMORY.md)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向Forge的“市场与模板”子系统，系统性阐述模板市场的架构设计、模板存储与版本控制机制、模板生命周期（创建/编辑/发布/使用）、模板编辑器能力（Markdown渲染、文件管理、依赖配置）、模板导入导出与一键复用流程，并给出API接口定义、搜索与过滤策略以及推荐思路，帮助开发者高效利用模板生态加速AI智能体项目的开发与交付。
## 项目结构
市场与模板相关代码主要分布在以下区域：
- 前端视图与交互：Marketplace视图、模板列表面板、模板编辑器面板
- 数据访问与状态：React Hook封装的市场数据访问
- 后端API：模板元数据、树形目录、文件读写、FS操作、导入、使用、从工作区保存等
- 文件系统工具：模板目录扫描、复制、安全路径解析
- 类型定义：模板实体类型
- 初始化模板：内置示例模板文件
```mermaid
graph TB
subgraph "前端"
MV["MarketplaceView
选择与布局"]
TLP["TemplateListPanel
模板列表/搜索/上下文菜单"]
TEP["TemplateEditorPanel
树/编辑/预览/拖拽/粘贴"]
UMP["useMarketplace Hook
模板增删改查"]
end
subgraph "后端API"
API_ROOT["/api/marketplace
GET/POST 模板列表/新建"]
API_ID["/api/marketplace/[id]
PATCH/DELETE 重命名/删除"]
API_TREE["/api/marketplace/[id]/tree
返回模板树"]
API_FILES["/api/marketplace/[id]/files
GET/PUT 文件读写"]
API_FS["/api/marketplace/[id]/fs
POST/PATCH/DELETE FS操作"]
API_IMPORT["/api/marketplace/[id]/fs/import
外部文件导入"]
API_USE["/api/marketplace/[id]/use
一键复用到工作区"]
API_SAVE_WS["/api/marketplace/save-from-workspace
从工作区保存为模板"]
end
subgraph "文件系统与数据库"
FS["marketplace-fs 工具
模板目录/树构建/复制"]
DB["SQLite 数据库
marketplace_templates 表"]
end
MV --> TLP
MV --> TEP
TLP --> UMP
TEP --> API_TREE
TEP --> API_FILES
TEP --> API_FS
TEP --> API_IMPORT
TEP --> API_USE
UMP --> API_ROOT
UMP --> API_ID
API_ROOT --> DB
API_ID --> DB
API_TREE --> FS
API_FILES --> FS
API_FS --> FS
API_USE --> FS
API_SAVE_WS --> FS
FS --> DB
```
图表来源
- [src/components/views/marketplace-view.tsx:16-109](file://src/components/views/marketplace-view.tsx#L16-L109)
- [src/components/marketplace/template-list-panel.tsx:26-247](file://src/components/marketplace/template-list-panel.tsx#L26-L247)
- [src/components/marketplace/template-editor-panel.tsx:40-647](file://src/components/marketplace/template-editor-panel.tsx#L40-L647)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/app/api/marketplace/route.ts:7-39](file://src/app/api/marketplace/route.ts#L7-L39)
- [src/app/api/marketplace/[id]/route.ts](file://src/app/api/marketplace/[id]/route.ts#L6-L46)
- [src/app/api/marketplace/[id]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/route.ts#L5-L19)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L7-L70)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L15-L128)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L7-L32)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L7-L68)
- [src/app/api/marketplace/save-from-workspace/route.ts:6-48](file://src/app/api/marketplace/save-from-workspace/route.ts#L6-L48)
- [src/lib/marketplace-fs.ts:27-158](file://src/lib/marketplace-fs.ts#L27-L158)
章节来源
- [src/components/views/marketplace-view.tsx:16-109](file://src/components/views/marketplace-view.tsx#L16-L109)
- [src/components/marketplace/template-list-panel.tsx:26-247](file://src/components/marketplace/template-list-panel.tsx#L26-L247)
- [src/components/marketplace/template-editor-panel.tsx:40-647](file://src/components/marketplace/template-editor-panel.tsx#L40-L647)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
## 核心组件
- 市场数据Hook：封装模板列表、创建、重命名、删除、选中态管理，统一调用REST API
- 模板列表面板：支持搜索、创建、重命名、上下文菜单（重命名/删除）、一键使用
- 模板编辑器面板：树形文件管理、Markdown源码编辑与预览、分屏模式、自动换行、拖拽/粘贴导入、保存
- API层：提供模板元数据、树、文件、FS操作、导入、使用、从工作区保存等接口
- 文件系统工具：模板目录结构扫描、安全路径解析、模板与工作区之间的复制
章节来源
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/components/marketplace/template-list-panel.tsx:26-247](file://src/components/marketplace/template-list-panel.tsx#L26-L247)
- [src/components/marketplace/template-editor-panel.tsx:40-647](file://src/components/marketplace/template-editor-panel.tsx#L40-L647)
- [src/lib/marketplace-fs.ts:27-158](file://src/lib/marketplace-fs.ts#L27-L158)
## 架构总览
模板系统采用“前端组件 + React Hook + Next.js App Router API”的分层设计：
- 前端负责UI与交互，通过HTTP请求与后端API通信
- 后端API负责业务逻辑与数据持久化，模板元数据存于SQLite，模板文件存于本地目录
- 文件系统工具提供安全的目录遍历、树构建与复制操作
```mermaid
sequenceDiagram
participant 用户 as "用户"
participant 列表 as "TemplateListPanel"
participant 钩子 as "useMarketplace"
participant 视图 as "MarketplaceView"
participant 编辑器 as "TemplateEditorPanel"
participant API树 as "GET /tree"
participant API文件 as "GET/PUT /files"
participant APIFS as "POST/PATCH/DELETE /fs"
participant API导入 as "POST /fs/import"
participant API使用 as "POST /use"
用户->>列表 : 选择模板/点击使用
列表->>钩子 : 调用 create/rename/delete
钩子->>API树 : 获取模板树
API树-->>编辑器 : 返回树结构
用户->>编辑器 : 选择文件/编辑/保存
编辑器->>API文件 : 读取/写入文件
编辑器->>APIFS : 创建/重命名/删除文件/目录
编辑器->>API导入 : 从系统剪贴板导入文件
用户->>视图 : 点击使用模板
视图->>API使用 : 复制模板到工作区并创建会话
```
图表来源
- [src/components/marketplace/template-list-panel.tsx:26-247](file://src/components/marketplace/template-list-panel.tsx#L26-L247)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/components/views/marketplace-view.tsx:35-68](file://src/components/views/marketplace-view.tsx#L35-L68)
- [src/components/marketplace/template-editor-panel.tsx:83-131](file://src/components/marketplace/template-editor-panel.tsx#L83-L131)
- [src/app/api/marketplace/[id]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/route.ts#L5-L19)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L7-L70)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L15-L128)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L7-L32)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L7-L68)
## 详细组件分析
### 组件A：模板市场视图与交互
- 负责模板列表与编辑器的布局与尺寸调整
- 提供“使用模板”流程：打开目录对话框，调用使用API，注册工作区并创建会话，跳转到新工作区
- 与模板列表面板、编辑器面板、工作区Hook协作
```mermaid
flowchart TD
Start(["进入市场视图"]) --> SelectTpl["选择模板"]
SelectTpl --> UseBtn{"点击使用？"}
UseBtn -- 否 --> Edit["在编辑器中继续编辑"]
UseBtn -- 是 --> PickDir["弹出目录选择器"]
PickDir --> CallUse["调用 /api/marketplace/{id}/use"]
CallUse --> RegWS["注册/更新工作区"]
RegWS --> NewSess["创建会话"]
NewSess --> Nav["导航到新工作区/会话"]
Nav --> End(["完成"])
```
图表来源
- [src/components/views/marketplace-view.tsx:35-68](file://src/components/views/marketplace-view.tsx#L35-L68)
章节来源
- [src/components/views/marketplace-view.tsx:16-109](file://src/components/views/marketplace-view.tsx#L16-L109)
### 组件B：模板列表面板
- 支持搜索过滤、创建/重命名/删除模板
- 右键上下文菜单提供重命名/删除
- 一键使用模板，触发使用流程
章节来源
- [src/components/marketplace/template-list-panel.tsx:26-247](file://src/components/marketplace/template-list-panel.tsx#L26-L247)
### 组件C：模板编辑器面板
- 文件树：支持展开/折叠、搜索、右键菜单（新建文件/文件夹/重命名/删除）
- 编辑：Markdown源码编辑、预览、分屏、自动换行、快捷键保存
- 文件系统：内部拖拽移动、外部文件拖拽导入、剪贴板粘贴导入
- 安全：所有FS操作均进行路径合法性校验，防止越权
```mermaid
sequenceDiagram
participant 用户 as "用户"
participant 树 as "文件树"
participant 编辑 as "编辑器"
participant APIFS as "POST/PATCH/DELETE /fs"
participant API导入 as "POST /fs/import"
participant API文件 as "GET/PUT /files"
用户->>树 : 右键菜单 新建文件/文件夹
树->>APIFS : 创建
用户->>树 : 右键菜单 重命名/删除
树->>APIFS : 重命名/删除
用户->>树 : 拖拽文件
树->>APIFS : 重命名/移动
用户->>树 : 外部拖拽文件
树->>API导入 : 导入到目标目录
用户->>编辑 : 选择文件
编辑->>API文件 : 读取文件内容
用户->>编辑 : 修改内容并保存
编辑->>API文件 : 写入文件内容
```
图表来源
- [src/components/marketplace/template-editor-panel.tsx:83-131](file://src/components/marketplace/template-editor-panel.tsx#L83-L131)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L15-L128)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L7-L32)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L7-L70)
章节来源
- [src/components/marketplace/template-editor-panel.tsx:40-647](file://src/components/marketplace/template-editor-panel.tsx#L40-L647)
### 组件D：文件系统与模板存储
- 模板根目录位于用户数据目录下的marketplace子目录
- 每个模板对应一个独立目录，结构与工作区的.claude目录一致
- 提供树构建、安全复制（模板↔工作区）、排除规则（如HEARTBEAT、MEMORY）
章节来源
- [src/lib/marketplace-fs.ts:27-158](file://src/lib/marketplace-fs.ts#L27-L158)
### 组件E：市场数据Hook
- 封装模板列表、创建、重命名、删除、刷新
- 与REST API对接，映射数据库行到前端类型
章节来源
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/lib/types.ts:213-221](file://src/lib/types.ts#L213-L221)
## 依赖关系分析
```mermaid
graph LR
TEP["TemplateEditorPanel"] --> API_TREE["/tree"]
TEP --> API_FILES["/files"]
TEP --> API_FS["/fs"]
TEP --> API_IMPORT["/fs/import"]
TEP --> API_USE["/use"]
UMP["useMarketplace"] --> API_ROOT["/marketplace"]
UMP --> API_ID["/marketplace/{id}"]
API_TREE --> FS["marketplace-fs.buildTemplateTree"]
API_FILES --> FS
API_FS --> FS
API_USE --> FS
API_SAVE_WS --> FS
FS --> DB["SQLite: marketplace_templates"]
API_ROOT --> DB
API_ID --> DB
```
图表来源
- [src/components/marketplace/template-editor-panel.tsx:83-131](file://src/components/marketplace/template-editor-panel.tsx#L83-L131)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/app/api/marketplace/route.ts:7-39](file://src/app/api/marketplace/route.ts#L7-L39)
- [src/app/api/marketplace/[id]/route.ts](file://src/app/api/marketplace/[id]/route.ts#L6-L46)
- [src/app/api/marketplace/[id]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/route.ts#L5-L19)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L7-L70)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L15-L128)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L7-L32)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L7-L68)
- [src/app/api/marketplace/save-from-workspace/route.ts:6-48](file://src/app/api/marketplace/save-from-workspace/route.ts#L6-L48)
- [src/lib/marketplace-fs.ts:27-158](file://src/lib/marketplace-fs.ts#L27-L158)
章节来源
- [src/lib/marketplace-fs.ts:27-158](file://src/lib/marketplace-fs.ts#L27-L158)
- [src/app/api/marketplace/route.ts:7-39](file://src/app/api/marketplace/route.ts#L7-L39)
- [src/app/api/marketplace/[id]/route.ts](file://src/app/api/marketplace/[id]/route.ts#L6-L46)
## 性能考量
- 树构建与文件读取：对大模板建议限制最大深度或延迟加载；当前实现提供最大深度参数，可按需调整
- 拖拽与粘贴：外部文件导入采用乐观更新与后续刷新，避免阻塞UI
- 搜索：前端模板名称搜索与树内文件搜索均为轻量计算，注意大数据量时的节流
- I/O：批量导入/复制应合并为一次请求，减少往返次数
## 故障排查指南
- 模板未显示或为空：检查模板目录是否存在、权限是否正确、树构建是否抛错
- 文件保存失败：确认路径合法、父目录已创建、UTF-8编码写入成功
- 使用模板报错：确认目标路径存在且为目录、模板ID有效、数据库记录存在
- FS操作被拒绝：检查路径是否包含非法片段、是否越权访问模板根目录外
- 从工作区保存失败：确认工作区存在、.claude目录存在、复制过程无异常
章节来源
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L15-L70)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L33-L128)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L20-L68)
- [src/lib/marketplace-fs.ts:97-158](file://src/lib/marketplace-fs.ts#L97-L158)
## 结论
Forge的模板系统以“安全、直观、可扩展”为核心设计原则：模板以文件形式存储，结合SQLite元数据管理，前后端职责清晰；编辑器提供丰富的文件管理与导入能力；使用流程一键完成从模板到工作区的落地。该体系可作为AI智能体项目快速复用与规模化交付的基础设施。
## 附录
### 模板市场API一览
- GET /api/marketplace — 获取模板列表（按更新时间倒序）
- POST /api/marketplace — 创建空模板（返回新建模板）
- PATCH /api/marketplace/[id] — 重命名模板
- DELETE /api/marketplace/[id] — 删除模板（物理删除目录）
- GET /api/marketplace/[id]/tree — 获取模板树形结构
- GET /api/marketplace/[id]/files — 读取文件内容
- PUT /api/marketplace/[id]/files — 写入文件内容
- POST /api/marketplace/[id]/fs — 创建文件/文件夹
- PATCH /api/marketplace/[id]/fs — 重命名/移动文件/文件夹
- DELETE /api/marketplace/[id]/fs — 删除文件/文件夹
- POST /api/marketplace/[id]/fs/import — 从系统路径导入文件到模板
- POST /api/marketplace/[id]/use — 使用模板创建项目（复制到工作区并创建会话）
- POST /api/marketplace/save-from-workspace — 从工作区保存为模板
章节来源
- [src/app/api/marketplace/route.ts:7-39](file://src/app/api/marketplace/route.ts#L7-L39)
- [src/app/api/marketplace/[id]/route.ts](file://src/app/api/marketplace/[id]/route.ts#L6-L46)
- [src/app/api/marketplace/[id]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/route.ts#L5-L19)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts#L7-L70)
- [src/app/api/marketplace/[id]/fs/route.ts](file://src/app/api/marketplace/[id]/fs/route.ts#L15-L128)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L7-L32)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L7-L68)
- [src/app/api/marketplace/save-from-workspace/route.ts:6-48](file://src/app/api/marketplace/save-from-workspace/route.ts#L6-L48)
### 模板创建、编辑、发布与使用流程
- 创建：前端调用新建模板API，后端创建目录并插入元数据
- 编辑：编辑器读取/写入文件，支持拖拽/粘贴导入
- 发布：从工作区保存为模板，复制.claude内容到模板目录
- 使用：选择模板并指定工作区目录，后端复制模板到.claude，注册工作区并创建会话
```mermaid
flowchart TD
C["创建模板"] --> E["编辑模板树/文件"]
E --> P["从工作区保存为模板"]
P --> U["使用模板到工作区"]
U --> R["注册工作区/创建会话"]
R --> D["开始开发"]
```
图表来源
- [src/app/api/marketplace/route.ts:17-39](file://src/app/api/marketplace/route.ts#L17-L39)
- [src/app/api/marketplace/save-from-workspace/route.ts:33-47](file://src/app/api/marketplace/save-from-workspace/route.ts#L33-L47)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L25-L63)
### 模板编辑器使用指南
- Markdown渲染：支持源码编辑、预览、分屏对比
- 文件管理：树形浏览、搜索、新建/重命名/删除、拖拽移动
- 依赖配置：模板即文件，可在文件中声明依赖与配置（例如模型、工具、提示词），由工作区加载
- 一键复用：编辑完成后直接使用模板创建新项目
章节来源
- [src/components/marketplace/template-editor-panel.tsx:556-647](file://src/components/marketplace/template-editor-panel.tsx#L556-L647)
### 模板导入导出与手动编辑
- 导入：支持外部文件拖拽、剪贴板粘贴导入，自动创建父目录
- 导出：使用模板一键复制到目标工作区.claude目录
- 手动编辑：通过文件树选择文件，编辑器提供Markdown语法高亮与实时预览
章节来源
- [src/components/marketplace/template-editor-panel.tsx:214-240](file://src/components/marketplace/template-editor-panel.tsx#L214-L240)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts#L30-L32)
- [src/app/api/marketplace/[id]/use/route.ts](file://src/app/api/marketplace/[id]/use/route.ts#L35-L36)
### 搜索、过滤与推荐
- 搜索：前端模板名称搜索与树内文件搜索
- 过滤：按名称包含匹配
- 推荐：可基于最近使用时间、使用频率、模板评分（可扩展）进行排序与置顶
章节来源
- [src/components/marketplace/template-list-panel.tsx:77-79](file://src/components/marketplace/template-list-panel.tsx#L77-L79)
- [src/app/api/marketplace/route.ts:10-14](file://src/app/api/marketplace/route.ts#L10-L14)
### 初始化模板参考
- CLAUDE.md：工作区配置说明与行为规范
- MEMORY.md：长期记忆模板头文件
章节来源
- [templates/init/CLAUDE.md:1-82](file://templates/init/CLAUDE.md#L1-L82)
- [templates/init/MEMORY.md:1-4](file://templates/init/MEMORY.md#L1-L4)