# 代理和技能API

<cite>
**本文引用的文件**
- [src/app/api/agents/route.ts](file://src/app/api/agents/route.ts)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts)
- [src/app/api/skills/route.ts](file://src/app/api/skills/route.ts)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts)
- [src/app/api/mcp/route.ts](file://src/app/api/mcp/route.ts)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/hooks/use-agents.ts](file://src/hooks/use-agents.ts)
- [src/hooks/use-skills.ts](file://src/hooks/use-skills.ts)
- [src/lib/mcp-test.ts](file://src/lib/mcp-test.ts)
</cite>

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

## 简介
本文件为 Forge 的“代理与技能API”提供权威参考，覆盖以下主题：
- 代理配置管理的REST接口：创建、查询、更新、删除与绑定技能
- 技能系统的API接口：注册、查询、更新、删除与作用域管理
- MCP 服务器集成的API规范与连接测试
- 插件扩展机制（通过外部 MCP 服务器）
- 代理配置模板、技能开发规范与API调用示例
- 权限控制、安全验证与性能监控要点

## 项目结构
本项目采用 Next.js App Router 的约定式路由组织 API，核心API位于 src/app/api 下，数据访问封装在 src/lib/db.ts 中，类型定义在 src/lib/types.ts，前端 Hook 封装在 src/hooks 下。

```mermaid
graph TB
subgraph "API 路由层"
A1["/api/agents<br/>GET/POST"]
A2["/api/agents/[id]<br/>GET/PATCH/DELETE"]
A3["/api/agents/[id]/skills<br/>GET/PUT"]
S1["/api/skills<br/>GET/POST"]
S2["/api/skills/[id]<br/>GET/PATCH/DELETE"]
M1["/api/mcp<br/>GET/POST"]
M2["/api/mcp/[id]<br/>GET/PATCH/DELETE"]
M3["/api/mcp/[id]/test<br/>POST"]
end
subgraph "数据层"
D["数据库(better-sqlite3)<br/>agents/skills/mcp_servers/agent_skills"]
end
subgraph "类型与工具"
T["类型定义(types.ts)"]
U1["代理Hook(use-agents.ts)"]
U2["技能Hook(use-skills.ts)"]
UT["MCP测试工具(mcp-test.ts)"]
end
A1 --> D
A2 --> D
A3 --> D
S1 --> D
S2 --> D
M1 --> D
M2 --> D
M3 --> D
M3 --> UT
U1 --> A1
U1 --> A2
U1 --> A3
U2 --> S1
U2 --> S2
T --> U1
T --> U2
```

图表来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L1-L57)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L1-L31)
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L1-L44)
- [src/app/api/mcp/route.ts:1-32](file://src/app/api/mcp/route.ts#L1-L32)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts#L1-L44)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L1-L38)
- [src/lib/db.ts:52-98](file://src/lib/db.ts#L52-L98)
- [src/lib/types.ts:76-119](file://src/lib/types.ts#L76-L119)
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/hooks/use-skills.ts:30-77](file://src/hooks/use-skills.ts#L30-L77)
- [src/lib/mcp-test.ts:9-51](file://src/lib/mcp-test.ts#L9-L51)

章节来源
- [src/lib/db.ts:52-98](file://src/lib/db.ts#L52-L98)
- [src/lib/types.ts:76-119](file://src/lib/types.ts#L76-L119)

## 核心组件
- 代理管理API：提供代理列表、创建、单个查询、更新、删除以及技能绑定管理
- 技能管理API：提供技能列表、创建、查询、更新、删除与作用域
- MCP 服务器API：提供服务器列表、创建、查询、更新、删除与连接测试
- 数据模型：SQLite 表结构与迁移逻辑，确保兼容性与演进
- 类型系统：统一前后端数据结构，保证字段一致性
- 前端 Hook：封装常用 CRUD 操作，简化组件使用

章节来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L1-L57)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L1-L31)
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L1-L44)
- [src/app/api/mcp/route.ts:1-32](file://src/app/api/mcp/route.ts#L1-L32)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts#L1-L44)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L1-L38)
- [src/lib/db.ts:52-98](file://src/lib/db.ts#L52-L98)
- [src/lib/types.ts:76-119](file://src/lib/types.ts#L76-L119)
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/hooks/use-skills.ts:30-77](file://src/hooks/use-skills.ts#L30-L77)

## 架构总览
下图展示从客户端到API再到数据库与外部MCP服务器的交互路径。

```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "代理API"
participant S as "技能API"
participant M as "MCP API"
participant DB as "数据库"
participant MT as "MCP测试工具"
C->>A : "GET /api/agents"
A->>DB : "查询代理列表"
DB-->>A : "返回代理数组"
A-->>C : "JSON 代理列表"
C->>S : "POST /api/skills"
S->>DB : "插入新技能"
DB-->>S : "返回新技能"
S-->>C : "JSON 新技能"
C->>M : "POST /api/mcp/ : id/test"
M->>DB : "读取服务器配置"
M->>MT : "testMcpServer(protocol, config)"
MT-->>M : "返回连接状态"
M->>DB : "写回状态"
M-->>C : "连接结果"
```

图表来源
- [src/app/api/agents/route.ts:5-17](file://src/app/api/agents/route.ts#L5-L17)
- [src/app/api/skills/route.ts:11-26](file://src/app/api/skills/route.ts#L11-L26)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/db.ts:89-98](file://src/lib/db.ts#L89-L98)
- [src/lib/mcp-test.ts:9-51](file://src/lib/mcp-test.ts#L9-L51)

## 详细组件分析

### 代理管理API
- 列表与创建
  - GET /api/agents：返回所有代理，并附加每个代理绑定的技能ID列表
  - POST /api/agents：创建新代理，生成唯一ID，填充默认字段，返回新建代理（含空技能ID列表）
- 单个代理操作
  - GET /api/agents/[id]：按ID查询代理，同时返回绑定技能ID
  - PATCH /api/agents/[id]：动态更新多个字段（名称、描述、模型、权限模式、主代理标记、父代理、启用状态、指令、Soul、Identity、工具配置等），自动更新时间戳
  - DELETE /api/agents/[id]：删除指定代理
- 技能绑定管理
  - GET /api/agents/[id]/skills：列出该代理已绑定的技能ID
  - PUT /api/agents/[id]/skills：替换绑定的所有技能ID（事务内先清空再批量插入）

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "代理API"
participant DB as "数据库"
C->>API : "PATCH /api/agents/ : id"
API->>DB : "UPDATE agents... (动态字段拼接)"
DB-->>API : "更新成功"
API->>DB : "查询 agent_skills 获取 skill_ids"
DB-->>API : "返回 skill_ids"
API-->>C : "返回更新后的代理(含skill_ids)"
```

图表来源
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L14-L49)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L12-L31)

章节来源
- [src/app/api/agents/route.ts:5-41](file://src/app/api/agents/route.ts#L5-L41)
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L4-L56)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L4-L31)

### 技能管理API
- 列表与创建
  - GET /api/skills：按更新时间倒序返回技能列表
  - POST /api/skills：创建新技能，生成唯一ID，默认内容包含YAML头部与标题
- 单个技能操作
  - GET /api/skills/[id]：按ID查询技能
  - PATCH /api/skills/[id]：动态更新名称、描述、作用域、启用状态与内容
  - DELETE /api/skills/[id]：删除指定技能

```mermaid
flowchart TD
Start(["请求进入 /api/skills/[id] PATCH"]) --> Parse["解析请求体字段"]
Parse --> Fields{"是否有可更新字段？"}
Fields --> |否| Err["返回错误：无可用字段"]
Fields --> |是| Build["构建SQL SET 子句与参数"]
Build --> Exec["执行 UPDATE 并写入 updated_at"]
Exec --> Reload["重新查询技能记录"]
Reload --> Done(["返回更新后的技能"])
Err --> Done
```

图表来源
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L12-L36)

章节来源
- [src/app/api/skills/route.ts:5-26](file://src/app/api/skills/route.ts#L5-L26)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L4-L43)

### MCP 服务器集成API
- 列表与创建
  - GET /api/mcp：返回所有MCP服务器
  - POST /api/mcp：创建新服务器，自动对配置进行连接测试并写回状态
- 单个服务器操作
  - GET /api/mcp/[id]：按ID查询服务器
  - PATCH /api/mcp/[id]：动态更新名称、协议、配置、启用状态与状态
  - DELETE /api/mcp/[id]：删除指定服务器
- 连接测试
  - POST /api/mcp/[id]/test：根据协议与配置进行连接测试，更新状态并返回结果

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "MCP 测试API"
participant DB as "数据库"
participant MT as "MCP测试工具"
C->>API : "POST /api/mcp/ : id/test"
API->>DB : "SELECT protocol, config FROM mcp_servers WHERE id=?"
DB-->>API : "返回服务器配置"
API->>MT : "testMcpServer(protocol, config)"
MT-->>API : "connected/disconnected/error"
API->>DB : "UPDATE mcp_servers SET status=? WHERE id=?"
API-->>C : "返回测试结果"
```

图表来源
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/mcp-test.ts:9-51](file://src/lib/mcp-test.ts#L9-L51)
- [src/lib/db.ts:89-98](file://src/lib/db.ts#L89-L98)

章节来源
- [src/app/api/mcp/route.ts:6-31](file://src/app/api/mcp/route.ts#L6-L31)
- [src/app/api/mcp/[id]/route.ts](file://src/app/api/mcp/[id]/route.ts#L4-L43)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)
- [src/lib/mcp-test.ts:9-51](file://src/lib/mcp-test.ts#L9-L51)

### 数据模型与关系
- 表结构概览
  - agents：代理基本信息、权限模式、主代理标记、父代理、启用状态、指令、Soul、Identity、工具配置、时间戳
  - skills：技能信息、作用域(workspace/global)、启用状态、内容、时间戳
  - agent_skills：代理与技能的多对多关联
  - mcp_servers：MCP服务器配置、协议、启用状态、连接状态、时间戳
- 关系图

```mermaid
erDiagram
AGENTS {
text id PK
text name
text description
text model
text permission_mode
boolean is_main
text parent_id FK
boolean enabled
text instructions
text soul
text identity
text tools_config
text created_at
text updated_at
}
SKILLS {
text id PK
text name
text description
text scope
boolean enabled
text content
text created_at
text updated_at
}
AGENT_SKILLS {
text agent_id PK,FK
text skill_id PK,FK
}
MCP_SERVERS {
text id PK
text name
text protocol
text config
boolean enabled
text status
text created_at
text updated_at
}
AGENTS ||--o{ AGENT_SKILLS : "绑定"
SKILLS ||--o{ AGENT_SKILLS : "绑定"
```

图表来源
- [src/lib/db.ts:52-98](file://src/lib/db.ts#L52-L98)

章节来源
- [src/lib/db.ts:52-98](file://src/lib/db.ts#L52-L98)

### 类型系统与前端Hook
- 类型定义
  - Agent、Skill、McpServer 等核心类型，统一字段命名与可选值
- 前端Hook
  - useAgents：封装代理的增删改查与技能绑定更新
  - useSkills：封装技能的增删改查
- 作用
  - 统一数据映射、简化API调用、提升开发效率

章节来源
- [src/lib/types.ts:76-119](file://src/lib/types.ts#L76-L119)
- [src/hooks/use-agents.ts:24-102](file://src/hooks/use-agents.ts#L24-L102)
- [src/hooks/use-skills.ts:17-77](file://src/hooks/use-skills.ts#L17-L77)

## 依赖关系分析
- 组件耦合
  - API 路由直接依赖数据库模块；MCP 测试API依赖独立的测试工具模块
  - 前端 Hook 仅依赖对应API，不直接访问数据库
- 外部依赖
  - better-sqlite3：本地嵌入式数据库
  - fetch：用于HTTP/SSE MCP连接测试
- 可能的循环依赖
  - 当前结构清晰，API 路由、数据库、工具模块之间为单向依赖

```mermaid
graph LR
R["API 路由"] --> DB["数据库模块"]
R --> T["类型定义"]
RT["MCP 测试API"] --> MT["MCP测试工具"]
RT --> DB
H1["use-agents Hook"] --> R
H2["use-skills Hook"] --> R
```

图表来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L1-L38)
- [src/lib/db.ts:1-10](file://src/lib/db.ts#L1-L10)
- [src/lib/types.ts:1-20](file://src/lib/types.ts#L1-L20)
- [src/lib/mcp-test.ts:1-10](file://src/lib/mcp-test.ts#L1-L10)
- [src/hooks/use-agents.ts:1-10](file://src/hooks/use-agents.ts#L1-L10)
- [src/hooks/use-skills.ts:1-10](file://src/hooks/use-skills.ts#L1-L10)

章节来源
- [src/lib/db.ts:1-10](file://src/lib/db.ts#L1-L10)
- [src/lib/mcp-test.ts:1-10](file://src/lib/mcp-test.ts#L1-L10)
- [src/hooks/use-agents.ts:1-10](file://src/hooks/use-agents.ts#L1-L10)
- [src/hooks/use-skills.ts:1-10](file://src/hooks/use-skills.ts#L1-L10)

## 性能考量
- 数据库优化
  - WAL 模式与外键约束开启，提升并发与一致性
  - 为消息表建立索引以加速会话查询
- API 设计
  - 批量更新时使用事务（如代理技能绑定）减少多次往返
  - 查询时按需返回必要字段，避免冗余数据传输
- 前端缓存
  - Hook 内维护内存状态，减少重复请求
- MCP 测试
  - 使用超时限制与最小化网络开销，避免阻塞主线程

## 故障排查指南
- 代理相关
  - 404：代理不存在或被删除
  - 400：PATCH 请求未携带可更新字段
- 技能相关
  - PATCH 无字段更新：检查请求体字段是否合法
- MCP 测试
  - 返回 error：命令不存在或HTTP/SSE不可达
  - 返回 disconnected：缺少必要配置（如命令或URL）
- 数据库
  - 首次访问触发迁移：若出现异常，检查数据目录权限与迁移脚本

章节来源
- [src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L37-L48)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L26-L35)
- [src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L19-L37)
- [src/lib/db.ts:226-320](file://src/lib/db.ts#L226-L320)

## 结论
本API体系围绕“代理—技能—MCP服务器”三要素构建，提供完备的CRUD与状态管理能力。通过类型系统与Hook封装，既保证了后端稳定性，也提升了前端开发体验。建议在生产环境中结合权限控制与审计日志进一步强化安全与可观测性。

## 附录

### 代理配置模板
- 必填字段
  - id：系统生成
  - name：代理名称
  - model：模型标识
  - permission_mode：权限模式（confirm/full）
  - tools_config：工具开关配置（字符串化对象）
- 可选字段
  - description、instructions、soul、identity、parent_id、is_main、enabled
- 技能绑定
  - 通过 /api/agents/:id/skills 接口管理

章节来源
- [src/lib/types.ts:89-105](file://src/lib/types.ts#L89-L105)
- [src/app/api/agents/route.ts:19-41](file://src/app/api/agents/route.ts#L19-L41)
- [src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L12-L31)

### 技能开发规范
- 作用域
  - workspace：工作区可见
  - global：全局可见
- 默认内容
  - 包含YAML头部与标题，便于渲染与检索
- 更新策略
  - 使用 PATCH 接口按需更新字段，避免全量覆盖

章节来源
- [src/lib/types.ts:76-85](file://src/lib/types.ts#L76-L85)
- [src/app/api/skills/route.ts:11-26](file://src/app/api/skills/route.ts#L11-L26)
- [src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L12-L36)

### API 调用示例（路径）
- 创建代理
  - 方法与路径：POST /api/agents
  - 请求体字段参考：name、model、permission_mode、tools_config 等
  - 返回：新建代理对象（含空技能ID列表）
  - 参考路径：[src/app/api/agents/route.ts:19-41](file://src/app/api/agents/route.ts#L19-L41)
- 更新代理
  - 方法与路径：PATCH /api/agents/[id]
  - 请求体字段：支持 name、description、model、permission_mode、is_main、parent_id、enabled、instructions、soul、identity、tools_config 等
  - 返回：更新后的代理（含 skill_ids）
  - 参考路径：[src/app/api/agents/[id]/route.ts](file://src/app/api/agents/[id]/route.ts#L14-L49)
- 绑定技能
  - 方法与路径：PUT /api/agents/[id]/skills
  - 请求体：{ skill_ids: [string[]] }
  - 返回：{ ok: true }
  - 参考路径：[src/app/api/agents/[id]/skills/route.ts](file://src/app/api/agents/[id]/skills/route.ts#L12-L31)
- 创建技能
  - 方法与路径：POST /api/skills
  - 请求体字段：name、scope、content 等
  - 返回：新建技能对象
  - 参考路径：[src/app/api/skills/route.ts:11-26](file://src/app/api/skills/route.ts#L11-L26)
- 更新技能
  - 方法与路径：PATCH /api/skills/[id]
  - 请求体字段：name、description、scope、enabled、content
  - 返回：更新后的技能对象
  - 参考路径：[src/app/api/skills/[id]/route.ts](file://src/app/api/skills/[id]/route.ts#L12-L36)
- 创建MCP服务器
  - 方法与路径：POST /api/mcp
  - 请求体字段：name、protocol、config
  - 返回：新建服务器对象（带初始状态）
  - 参考路径：[src/app/api/mcp/route.ts:12-31](file://src/app/api/mcp/route.ts#L12-L31)
- 测试MCP连接
  - 方法与路径：POST /api/mcp/[id]/test
  - 返回：{ ok, message 或 error }
  - 参考路径：[src/app/api/mcp/[id]/test/route.ts](file://src/app/api/mcp/[id]/test/route.ts#L8-L37)

### 权限控制与安全验证
- 权限模式
  - confirm：需要确认
  - full：完全授权
- 工具开关
  - 通过 tools_config 控制具体工具的启用/禁用
- 安全建议
  - 对外部MCP服务器进行严格配置校验与连接测试
  - 对API请求进行输入校验与最小权限原则

章节来源
- [src/lib/types.ts:87-101](file://src/lib/types.ts#L87-L101)
- [src/app/api/mcp/route.ts:12-31](file://src/app/api/mcp/route.ts#L12-L31)
- [src/lib/mcp-test.ts:9-51](file://src/lib/mcp-test.ts#L9-L51)

### 性能监控建议
- 数据库层面
  - 监控 WAL 与外键约束对写入的影响
  - 对高频查询建立合适索引
- API层面
  - 对批量更新使用事务，减少锁竞争
  - 对MCP测试设置合理超时与重试策略
- 前端层面
  - 缓存最近查询结果，减少重复请求