# 市场服务

<cite>
**本文引用的文件**
- [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]/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]/tree/route.ts](file://src/app/api/marketplace/[id]/tree/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/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/lib/types.ts](file://src/lib/types.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
</cite>

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

## 简介
本文件系统化梳理市场服务（Marketplace）的设计与实现，覆盖模板市场架构、解决方案管理、版本控制机制、模板导入导出流程、依赖解析与兼容性检查、市场搜索与分类筛选、推荐算法、模板验证与安全扫描、质量评估、发布流程与社区贡献、审核机制、模板缓存与增量更新以及离线支持方案等主题。文档以代码为依据，结合可视化图示帮助读者快速理解并高效使用该功能模块。

## 项目结构
市场服务由三层组成：
- API 层：提供 REST 接口，负责模板生命周期管理、文件读写、树形目录访问、从工作区保存模板、使用模板创建项目等。
- 文件系统层：封装模板在本地文件系统中的存储与操作，包括复制、排除规则、路径校验与安全限制。
- 前端交互层：提供模板列表面板与模板编辑器面板，支持搜索、上下文菜单、拖拽/粘贴导入、实时保存与预览。

```mermaid
graph TB
subgraph "前端"
TL["模板列表面板<br/>TemplateListPanel"]
TE["模板编辑器面板<br/>TemplateEditorPanel"]
HM["市场钩子<br/>useMarketplace"]
end
subgraph "API 层"
MP["GET/POST 模板列表<br/>/api/marketplace"]
MPID["PATCH/DELETE 模板<br/>/api/marketplace/:id"]
TREE["GET 模板树<br/>/api/marketplace/:id/tree"]
FILES["GET/PUT 文件内容<br/>/api/marketplace/:id/files"]
FS["POST/PATCH/DELETE FS<br/>/api/marketplace/:id/fs"]
IMPORT["POST 导入文件<br/>/api/marketplace/:id/fs/import"]
USE["POST 使用模板创建项目<br/>/api/marketplace/:id/use"]
SAVEWS["POST 从工作区保存模板<br/>/api/marketplace/save-from-workspace"]
end
subgraph "文件系统层"
FSUTIL["marketplace-fs 工具集<br/>构建树/复制/导入/路径校验"]
end
TL --> HM
TE --> HM
HM --> MP
HM --> MPID
TE --> TREE
TE --> FILES
TE --> FS
TE --> IMPORT
TE --> USE
MP --> SAVEWS
MPID --> FSUTIL
TREE --> FSUTIL
FILES --> FSUTIL
FS --> FSUTIL
IMPORT --> FSUTIL
USE --> FSUTIL
SAVEWS --> FSUTIL
```

图表来源
- [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/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [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/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

章节来源
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [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)

## 核心组件
- 数据模型与类型
  - 市场模板类型：包含 id、名称、创建时间、更新时间。
  - 数据库表：marketplace_templates 存储模板元数据；sessions/workspaces 等表支撑会话与工作区关联。
- 前端状态与交互
  - useMarketplace 钩子：拉取模板列表、创建/重命名/删除模板、选择模板、刷新。
  - 模板列表面板：支持搜索、右键菜单、新建/重命名/删除、使用模板。
  - 模板编辑器面板：树形文件浏览、文件内容编辑/预览、拖拽/粘贴导入、保存、上下文菜单。
- 文件系统工具
  - marketplace-fs：模板根目录管理、树形扫描、.claude/ 复制策略、路径解析与安全校验、外部文件导入。

章节来源
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/db.ts](file://src/lib/db.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/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 架构总览
市场服务采用“前端 React 组件 + Next.js API 路由 + 本地文件系统”的分层架构。API 路由通过 better-sqlite3 访问本地数据库，模板文件存储于用户数据目录下的 marketplace 子目录中，遵循安全路径解析与防越权策略。

```mermaid
graph TB
UI["UI 组件<br/>列表/编辑器"] --> Hook["React 钩子<br/>useMarketplace"]
Hook --> API["Next.js API 路由"]
API --> DB["SQLite 数据库<br/>better-sqlite3"]
API --> FS["本地文件系统<br/>~/.forge/marketplace/<id>"]
FS --> FSUTIL["marketplace-fs 工具集"]
```

图表来源
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 详细组件分析

### 模板市场 API 流程
- 列出模板：GET /api/marketplace
- 创建空模板：POST /api/marketplace
- 重命名/删除模板：PATCH/DELETE /api/marketplace/:id
- 获取模板树：GET /api/marketplace/:id/tree
- 读取/写入文件：GET/PUT /api/marketplace/:id/files
- 文件系统操作：POST/PATCH/DELETE /api/marketplace/:id/fs
- 从工作区保存模板：POST /api/marketplace/save-from-workspace
- 使用模板创建项目：POST /api/marketplace/:id/use
- 从外部导入文件：POST /api/marketplace/:id/fs/import

```mermaid
sequenceDiagram
participant C as "客户端"
participant L as "模板列表面板"
participant U as "useMarketplace 钩子"
participant A as "API 路由"
participant D as "数据库"
participant F as "文件系统"
C->>L : 打开市场视图
L->>U : 触发拉取模板列表
U->>A : GET /api/marketplace
A->>D : 查询 marketplace_templates
D-->>A : 返回模板列表
A-->>U : JSON 响应
U-->>L : 更新状态
L->>U : 新建模板(名称)
U->>A : POST /api/marketplace
A->>F : 创建模板目录
A->>D : 插入记录
A-->>U : 返回新模板
U-->>L : 刷新列表
```

图表来源
- [src/components/marketplace/template-list-panel.tsx](file://src/components/marketplace/template-list-panel.tsx)
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

章节来源
- [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)

### 模板编辑器与文件系统操作
- 树形浏览：GET /api/marketplace/:id/tree → marketplace-fs.buildTemplateTree
- 新建/重命名/删除：POST/PATCH/DELETE /api/marketplace/:id/fs
- 读取/写入文件：GET/PUT /api/marketplace/:id/files
- 外部导入：POST /api/marketplace/:id/fs/import（支持 Finder 拖放与剪贴板粘贴）
- 使用模板创建项目：POST /api/marketplace/:id/use → 复制到 .claude/ 并注册工作区/会话

```mermaid
flowchart TD
Start(["进入模板编辑器"]) --> LoadTree["请求模板树<br/>GET /api/marketplace/:id/tree"]
LoadTree --> RenderTree["渲染文件树"]
RenderTree --> SelectFile{"选择文件?"}
SelectFile --> |是| ReadFile["GET /api/marketplace/:id/files"]
ReadFile --> Edit["编辑/预览"]
Edit --> Save{"保存?"}
Save --> |是| PutFile["PUT /api/marketplace/:id/files"]
Save --> |否| Wait["等待操作"]
PutFile --> UpdateMeta["更新模板更新时间"]
UpdateMeta --> RenderTree
SelectFile --> |否| FSOp{"FS 操作?"}
FSOp --> |新建| PostFS["POST /api/marketplace/:id/fs"]
FSOp --> |重命名| PatchFS["PATCH /api/marketplace/:id/fs"]
FSOp --> |删除| DelFS["DELETE /api/marketplace/:id/fs"]
PostFS --> RenderTree
PatchFS --> RenderTree
DelFS --> RenderTree
RenderTree --> Import{"外部导入?"}
Import --> |是| PostImport["POST /api/marketplace/:id/fs/import"]
PostImport --> RenderTree
RenderTree --> UseTpl{"使用模板?"}
UseTpl --> |是| PostUse["POST /api/marketplace/:id/use"]
PostUse --> Done(["完成"])
UseTpl --> |否| End(["退出"])
```

图表来源
- [src/components/marketplace/template-editor-panel.tsx](file://src/components/marketplace/template-editor-panel.tsx)
- [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/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

章节来源
- [src/components/marketplace/template-editor-panel.tsx](file://src/components/marketplace/template-editor-panel.tsx)
- [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/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

### 模板导入导出与依赖解析
- 从工作区保存模板：POST /api/marketplace/save-from-workspace
  - 从数据库查询工作区路径，调用 marketplace-fs.copyClaudeToTemplate 将 .claude/ 内容复制到模板目录，并插入数据库记录。
- 从外部导入文件：POST /api/marketplace/:id/fs/import
  - 安全校验目标路径不得越权；避免覆盖时自动追加后缀；成功后更新模板更新时间。
- 依赖解析与兼容性检查
  - 当前实现未显式提供依赖声明与解析逻辑；建议在模板元数据中引入依赖字段并在导入时进行兼容性校验（例如版本范围、工具链要求）。

```mermaid
sequenceDiagram
participant WS as "工作区"
participant API as "保存模板 API"
participant FS as "marketplace-fs"
participant DB as "数据库"
WS->>API : POST /api/marketplace/save-from-workspace {workspaceId,name}
API->>DB : 查询工作区路径
DB-->>API : 返回路径
API->>FS : copyClaudeToTemplate(WS路径, 模板ID)
FS-->>API : 复制完成
API->>DB : 插入 marketplace_templates 记录
API-->>WS : 返回新模板
```

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

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

### 搜索、分类筛选与推荐算法
- 搜索与筛选
  - 前端模板列表面板支持按名称过滤；可扩展为正则匹配、标签过滤、时间范围筛选等。
- 分类与标签
  - 可在模板元数据中增加分类/标签字段，配合前端筛选器实现多维筛选。
- 推荐算法
  - 基于使用频率、最近更新时间、相似模板关联度等构建简单推荐；复杂场景可引入协同过滤或向量检索。

章节来源
- [src/components/marketplace/template-list-panel.tsx](file://src/components/marketplace/template-list-panel.tsx)

### 模板验证、安全扫描与质量评估
- 安全与合规
  - 路径解析严格限制在模板目录内，禁止 .. 越权；文件读写均进行相对路径解析与边界校验。
  - 导入外部文件时确保目标路径在模板目录范围内，避免覆盖敏感文件。
- 质量评估
  - 建议在导入/保存时执行基础校验：文件大小限制、非法字符检测、敏感内容扫描（如密钥、令牌）、Markdown 语法检查等。
- 版本控制与变更追踪
  - 模板记录包含 created_at/updated_at 字段；可在导入/保存时记录变更日志，便于审计与回滚。

章节来源
- [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/lib/db.ts](file://src/lib/db.ts)

### 发布流程、社区贡献与审核机制
- 发布流程
  - 从工作区保存模板 → 编辑完善 → 导入外部资源 → 质量检查 → 提交审核 → 公开展示。
- 社区贡献
  - 支持通过拖拽/粘贴导入外部文件；建议提供模板规范与示例，引导高质量贡献。
- 审核机制
  - 建议引入审核状态字段与审批流程，对敏感模板（含密钥、脚本等）进行人工复核。

章节来源
- [src/app/api/marketplace/save-from-workspace/route.ts](file://src/app/api/marketplace/save-from-workspace/route.ts)
- [src/components/marketplace/template-editor-panel.tsx](file://src/components/marketplace/template-editor-panel.tsx)

### 模板缓存、增量更新与离线支持
- 缓存策略
  - 前端 useMarketplace 缓存模板列表；编辑器面板缓存当前选中文件内容与滚动位置。
- 增量更新
  - 文件保存后仅更新模板的 updated_at；树形结构按需刷新；外部导入后统一刷新树。
- 离线支持
  - 本地数据库与文件系统可离线访问；网络异常时前端提示重试；API 层返回明确错误码以便前端处理。

章节来源
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/components/marketplace/template-editor-panel.tsx](file://src/components/marketplace/template-editor-panel.tsx)
- [src/app/api/marketplace/[id]/files/route.ts](file://src/app/api/marketplace/[id]/files/route.ts)
- [src/app/api/marketplace/[id]/fs/import/route.ts](file://src/app/api/marketplace/[id]/fs/import/route.ts)

## 依赖关系分析
- 组件耦合
  - 前端面板依赖 useMarketplace 钩子；钩子依赖 Next.js API 路由；API 路由依赖数据库与文件系统工具。
- 外部依赖
  - better-sqlite3：轻量级本地数据库。
  - Node.js fs/path：文件系统操作与路径解析。
- 潜在风险
  - 路径校验依赖严格的相对路径解析；任何绕过都会导致越权访问。
  - 大型模板的树形扫描可能影响性能，建议限制最大深度与并发。

```mermaid
graph LR
Panel["模板面板"] --> Hook["useMarketplace"]
Hook --> API["API 路由"]
API --> DB["better-sqlite3"]
API --> FSUtil["marketplace-fs"]
FSUtil --> FS["文件系统"]
```

图表来源
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

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

## 性能考虑
- I/O 优化
  - 树形扫描默认限制最大深度；大目录建议懒加载子节点。
  - 批量导入时合并多次请求，减少数据库更新次数。
- 数据库
  - WAL 模式提升并发读写性能；索引已存在用于消息查询，模板列表按更新时间排序。
- 前端
  - 缓存模板列表与当前文件内容；长列表虚拟化；键盘快捷键减少重复点击。

## 故障排查指南
- 常见错误与处理
  - 模板不存在：检查模板 ID 是否正确；确认数据库记录存在。
  - 路径越权：确保相对路径不包含 ..；导入目标必须位于模板目录内。
  - 文件不存在：确认文件名与路径大小写；检查是否被排除（如 MEMORY.md、memory 目录）。
  - 权限不足：检查模板目录权限；确保进程有读写权限。
- 日志与调试
  - API 层返回明确错误码与消息；前端捕获并提示用户。
  - 建议在 marketplace-fs 中增加更详细的日志输出，定位复制/导入失败原因。

章节来源
- [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/lib/marketplace-fs.ts](file://src/lib/marketplace-fs.ts)

## 结论
市场服务以简洁可靠的分层设计实现了模板的全生命周期管理：从创建、编辑、导入到使用与发布。通过严格的路径校验与数据库驱动的元数据管理，保障了安全性与一致性。建议后续增强依赖解析、质量评估与审核流程，以满足更复杂的模板生态需求。

## 附录
- 数据库表结构要点
  - marketplace_templates：id、name、created_at、updated_at
  - sessions/workspaces：支撑会话与工作区关联
- 前端类型
  - MarketplaceTemplate：模板数据模型
- 文件系统约定
  - 模板根目录：~/.forge/marketplace/<templateId>/
  - 复制策略：.claude/ 内容复制，排除 MEMORY.md、memory 目录、HEARTBEAT.md

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