# @cicctencent/agent-server 中文文档

规范地址：https://npmcn.com/package/%40cicctencent/agent-server/

版本：1\.0\.86
npm 元数据更新时间：2026-11-06T01:36:28.948Z
中文译文更新时间：2026-11-09T18:58:49.236Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cicctencent/agent-server
原文对照：https://npmcn.com/package/%40cicctencent/agent-server/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.5 MB，1124 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.17\.0
- 运行依赖：15 个
- 首次发布：2026-06-24T14:52:55.381Z
- 最新版本发布：2026-11-06T01:36:28.752Z
- 近 30 天下载量：1834（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：173（近 12 个月 173 个）

## 中文简介

代理-核心的服务器层工具包——代理初始化,SSE流化,内置工具,连接器,聊天/设定/记忆服务与SPI可扩展性.

## 安装

```sh
npm install @cicctencent/agent-server
```

也可以使用：`pnpm add @cicctencent/agent-server`、`yarn add @cicctencent/agent-server`、`bun add @cicctencent/agent-server`

## README

# @cicctencent/agent-server

Server-layer toolkit for `@cicctencent/agent-core` — Agent 初始化、SSE 流式推送、内置工具、沙箱、MCP 桥接、知识库、Chat/Settings/Memory/Security 服务，通过 SPI 接口实现可定制性。

**框架无关**：不依赖 Express/Fastify/Koa，通过 `SSEResponse` 接口适配任意 HTTP 框架。

## 架构

```
┌─────────────────────────────────────────────────┐
│  Layer 3: 应用层 (如 workai)                    │
│  路由、认证、DB 模型、业务逻辑、doc-generator    │
├─────────────────────────────────────────────────┤
│  Layer 2: @cicctencent/agent-server (本包)      │
│  Agent 初始化、SSE、Chat、工具、沙箱、MCP 桥接   │
│  KB、安全审计、连接器框架，通过 SPI 自定义        │
├─────────────────────────────────────────────────┤
│  Layer 1: @cicctencent/agent-core               │
│  纯引擎：LLM 编排、工具执行、MCP、Memory、A2A     │
└─────────────────────────────────────────────────┘
```

## 快速开始

```typescript
import { createAgentServer, createBuiltinTools, createSafetyAuditMiddleware } from '@cicctencent/agent-server';
import { createLLMProvider } from '@cicctencent/agent-core';
import express from 'express';

const app = express();

const server = createAgentServer({
  llmProvider: createLLMProvider({
    provider: 'openai',
    model: 'gpt-4',
    apiKey: process.env.OPENAI_API_KEY!,
  }),
  tools: createBuiltinTools(),
  middleware: [createSafetyAuditMiddleware()],
});

// runAgentStream 接收 SSEResponse 接口，Express Response 天然兼容
app.post('/api/work/chat/stream', async (req, res) => {
  await server.runAgentStream(res, {
    content: req.body.content,
    threadId: req.body.threadId,
  });
});

app.listen(3000);
```

## 框架无关

`agent-server` 不依赖任何 HTTP 框架。`runAgentStream` / `reconnectAgentStream` 接收 `SSEResponse` 接口：

```typescript
interface SSEResponse {
  write(data: string): void;
  end(): void;
  readonly writableEnded: boolean;
  setHeader(name: string, value: string | number): void;
  flushHeaders?(): void;
  status?(code: number): void;
  json?(data: any): void;
}
```

Express `Response`、Fastify `Reply`（适配后）、原生 `http.ServerResponse` 均可适配。

## SPI 自定义

agent-server 采用 **SPI (Service Provider Interface)** 设计模式，所有核心组件都可以替换。

### 设计原则

```
┌─────────────────────────────────────────────────────────────┐
│                    agent-server SPI                          │
│                                                              │
│  核心：只定义接口（能力契约）                                  │
│  ├── SSEResponseAdapter    ← SSE 流式响应能力                 │
│  ├── ChatStoreProvider     ← 对话存储能力                     │
│  ├── SettingsProvider      ← 设置存储能力                     │
│  └── AgentProfileProvider  ← Agent Profile 能力              │
│                                                              │
│  可选：提供参考实现（开箱即用）                                │
│  ├── KoaSSEAdapter         ← Koa/MidwayJS 参考               │
│  ├── ExpressSSEAdapter     ← Express 参考                    │
│  └── JsonFileStorage       ← JSON 文件存储参考               │
│                                                              │
│  业务层：完全自主                                             │
│  ├── 直接使用参考实现                                         │
│  ├── 继承扩展                                                 │
│  └── 完全自己实现                                             │
└─────────────────────────────────────────────────────────────┘
```

### 快速示例

```typescript
import {
  createAgentServer,
  KoaSSEAdapter,
  type ChatStoreProvider,
  type BaseThreadEntity,
  type BaseMessageEntity,
} from '@cicctencent/agent-server';

// 1. 定义自定义实体（可以添加额外字段）
interface MyThread extends BaseThreadEntity {
  userId: string;           // 额外字段
  applicationId: number;    // 额外字段
}

// 2. 实现 ChatStoreProvider（使用任意存储技术）
class MyChatStore implements ChatStoreProvider<MyThread, MyMessage> {
  async getThreads(userId?: string): Promise<MyThread[]> {
    // 使用 TypeORM / Prisma / Mongoose / 任意存储
    return this.database.query('SELECT * FROM threads WHERE userId = ?', userId);
  }
  // ... 实现其他方法
}

// 3. 创建 AgentServer，注入自定义实现
const server = createAgentServer({
  llmProvider: myProvider,
  chatStoreProvider: new MyChatStore(),  // 替换默认实现
});

// 4. 在 MidwayJS/Koa 中使用 SSE 适配器
@Get('/chat/stream')
async chatStream(@Ctx() ctx: Context) {
  const adapter = new KoaSSEAdapter(ctx);
  await server.runAgentStream(adapter, { content: 'Hello' });
}
```

### 组件级使用（不依赖工厂）

```typescript
import {
  KoaSSEAdapter,
  writeSSE,
  createBuiltinTools,
  MemoryService,
} from '@cicctencent/agent-server';

// 只使用需要的组件，不使用 createAgentServer
const tools = createBuiltinTools();
const memoryService = new MemoryService('./data');

@Get('/stream')
async stream(@Ctx() ctx: Context) {
  const adapter = new KoaSSEAdapter(ctx);
  writeSSE(adapter, 'start', { message: 'Hello' });
}
```

### SPI 接口清单

| 接口 | 默认实现 | 用途 |
| --- | --- | --- |
| `SettingsProvider<TSettings>` | `DefaultSettingsProvider` | 设置持久化（泛型） |
| `ChatStoreProvider<TThread, TMessage>` | `DefaultChatStoreProvider` | 对话 CRUD + 历史重建（泛型） |
| `PromptBuilderProvider` | `DefaultPromptBuilder` | 系统提示词构建 |
| `ModelConfigResolver` | — | 模型配置解析 |
| `MCPServiceProvider` | — | MCP 服务器管理 |
| `SkillServiceProvider` | — | 技能 CRUD 管理 |
| `ConnectorServiceProvider` | — | 数据源连接器管理 |
| `AgentProfileProvider<TProfile>` | `DefaultAgentProfileProvider` | 多 Agent 配置管理（泛型） |
| `SSEResponseAdapter` | `KoaSSEAdapter` / `ExpressSSEAdapter` | SSE 流式响应适配 |
| `KVStorageAdapter` | `JsonFileKVStorage` | 键值存储抽象 |
| `ListStorageAdapter<T>` | `JsonFileListStorage` | 列表存储抽象 |

### 详细文档

完整的 SPI 使用指南请参考 [src/spi/README.md](https://npmcn.com/package/%40cicctencent/agent-server/src/spi/README.md)，包含：

-   所有接口的详细定义
-   TypeORM / Prisma / Mongoose 实现示例
-   MidwayJS + TypeORM 完整模板
-   常见问题解答

## 模块清单

### 核心工厂

-   `createAgentServer(options)` — 创建 AgentServer 实例

### 默认 SPI 实现

-   `DefaultSettingsProvider` — JSON 文件设置存储
-   `DefaultChatStoreProvider` — JSON 文件对话存储 + 历史重建
-   `DefaultAgentProfileProvider` — JSON 文件 Agent Profile 管理
-   `DefaultPromptBuilder` — 系统提示词构建器

### 服务

-   `MemoryService` / `getMemoryService()` — 长期记忆持久化
-   `getEnginePool()` — AgentEngine 实例复用池
-   `getRunRegistry()` — Agent 运行会话注册表
-   `getSecurityPolicy()` / `updateSecurityPolicy()` — 安全策略管理
-   `assessToolRisk()` / `isLowRiskTool()` — 工具风险评估
-   `createPermissionRequest()` / `findApprovedPermission()` — 权限审批
-   `appendAuditLog()` / `listAuditLogs()` — 审计日志
-   `createSafetyAuditMiddleware()` — 安全审计中间件
-   `logEvent()` / `setLogTransport()` — 可观测性
-   `saveArtifact()` / `resolveArtifactPath()` / `getMimeType()` — Artifact 存储
-   `getWorkspaces()` / `createWorkspace()` / `ensureDefaultWorkspace()` — 工作空间 CRUD

### SSE

-   `writeSSE()` / `initSSEResponse()` — SSE 事件写入（框架无关）
-   `runAgentSSEStream()` — Agent SSE 流式推送

### 内置工具

-   `createBuiltinTools(options?)` — 聚合所有内置工具（含 docgen）
-   `createFilesystemTools()` — execute\_command, read\_terminal, write\_file, read\_file, search\_code, edit\_file, append\_file
-   `createDiscoveryTools()` — read\_tool\_doc, load\_skill, read\_tool\_result, read\_offload
-   `createWebTools()` — web\_fetch, http\_request, browser\_navigate
-   `createMemoryTools()` — save\_memory, recall\_memory, delete\_memory
-   `createSandboxTools()` — run\_script, show\_widget, save\_artifact
-   `createAutomationTools()` — create\_automation, list\_automations, delete\_automation
-   `createDocgenTools(options?)` — create\_presentation, create\_document, create\_pdf, create\_report
-   `createArtifactInspectTools()` — inspect\_artifact, list\_artifacts（只读产物静态自检与产物清单）

#### 文档生成（docgen）

`createBuiltinTools()` / `createDocgenTools()` 支持 `options.templatesDir` 指定应用层主题模板根目录：

```typescript
const tools = createBuiltinTools({
  templatesDir: '/abs/path/to/your-app/data/_shared/docs',
});
```

主题解析优先级：`options.templatesDir` → 代码内置 `DEFAULT_THEME`（始终可用）。旧的消费方数据目录 `getProjectDataPath('doc-templates')` 回退已移除，应用层须通过 `templatesDir` 显式传入模板目录。也可在运行时通过 `ToolContext.custom.templatesDir` 按请求覆盖。

> ⚠️ 文档生成依赖 `ctx.custom.sandbox` 与 `ctx.emitArtifact`（由引擎注入），请确保运行时上下文携带这些字段。 完整的主题目录布局、Schema 与接入示例见仓库 [docs/DOCGEN.md](https://npmcn.com/docs/DOCGEN.md)。

### 工具执行器

-   `LocalShellExecutor` — 基于 child\_process 的 Shell 执行器
-   `LocalFileSystemExecutor` — 基于 fs/promises 的文件系统执行器

### 沙箱

-   `LocalSandbox` — 进程级沙箱实例（隔离文件系统 + Shell + 脚本执行）
-   `LocalSandboxManager` / `getSandboxManager()` — 沙箱生命周期管理器
-   `ProcessCodeSandbox` — 结构化代码执行沙箱（stdout/stderr/files/charts）
-   `SandboxFileSystemExecutor` — 沙箱内文件系统执行器（路径穿越防护）
-   `SandboxShellExecutor` — 沙箱内 Shell 执行器（命令黑名单 + 环境变量过滤）

### MCP 桥接

-   `ApiBridgeClient` — HTTP API → MCP 桥接客户端
-   `buildFromTemplate` — 通用模板请求构建器（配置驱动）
-   `resolveBodyTemplate()` — `${param|default}` 模板解析
-   `importFromOpenAPI()` — OpenAPI 3.x / Swagger 2.0 → MCP 工具定义
-   类型：`RequestBuilderFn`, `AuthConfig`, `ResponseConfig`, `TemplateBuilderExtra`

### 知识库

-   `FileKnowledgeBase` — 基于文件的知识库（文档分块 + embedding 存储）
-   `EmbeddingVectorIndex` — 基于 Embedding 的向量索引
-   `parseDocument()` — 文档解析与分块（Markdown/TXT/JSON）

### 连接器

-   `registerAdapter()` / `getAdapter()` — 数据源适配器注册表

### 存储

-   `JsonStore` / `JsonListStore` — 通用 JSON 文件存储
-   `McpServerStore` — 目录型 MCP 服务器存储
-   `getToolResultStore()` — 工具结果存储单例
-   `FileNoteStore` — 工作空间笔记存储（agent.md）
-   `WorkspaceStore` / `getWorkspaceStore()` — 工作空间存储
-   `AutomationStore` / `getAutomationStore()` — 自动化任务存储
-   `AutomationRunStore` / `getAutomationRunStore()` — 自动化执行记录存储

### 数据模型

-   `AutomationEntity` / `AutomationRunEntity` / `AutomationStatus` — 自动化任务类型

### 工具函数

-   `getProjectDataPath()` / `ensureDataDir()` — 数据目录管理
-   `expandEnvVars()` — 环境变量展开
-   `setAppName()` / `getAppName()` — 应用名设置
-   `ensureDefaultData()` — 默认数据文件复制

## AgentServer API

```typescript
interface AgentServer {
  agentSystem: AgentSystem;
  registerTool(tool): void;
  unregisterTool(name): void;
  registerMiddleware(mw): void;
  unregisterMiddleware(name): void;
  runAgentStream(res: SSEResponse, params: RunAgentParams, signal?): Promise<void>;
  reconnectAgentStream(res: SSEResponse, threadId): Promise<void>;
  getEngineForProfile(profileId?, canDelegateOverride?): Promise<AgentEngine>;
  abortAgent(threadId): boolean;
  steerAgent(sessionId, message): boolean;
  clearEnginePool(): void;
  refreshLLMConfig(): void;
  refreshAgentConfig(): void;
  getRegisteredTools(): ToolInfo[];
  getLoadedSkills(): SkillInfo[];
  isAgentAvailable(): boolean;
  checkRunStatus(threadId): RunStatus;
  providers: { ... };
}
```

### RunAgentParams

```typescript
interface RunAgentParams {
  content: string | ContentPart[];   // 用户输入
  threadId?: string;                  // 对话线程 ID（不传则不持久化）
  agentProfileId?: number;            // Agent Profile ID
  traceId?: string;                   // 追踪 ID
  tenant?: TenantContext;             // 多租户上下文
  allowedSpecialistIds?: number[];    // 允许委派的 Specialist ID 列表
  customContext?: Record<string, unknown>; // 自定义上下文
  testMode?: boolean;                 // 测试模式：禁用委派，不持久化
}
```

### getEngineForProfile(profileId?, canDelegateOverride?)

获取指定 Profile 的 AgentEngine 实例（带缓存）。

-   `profileId` — Agent Profile ID，不传使用默认
-   `canDelegateOverride` — 强制覆盖委派策略（`false` = 禁用委派，用于测试模式）
-   返回带 `delegate_task` 工具的引擎（如果 `canDelegate` 为 `true`）
-   测试模式使用独立缓存 key（`_nodelegate`），不污染正常引擎缓存

### REST A2A 自定义 Action

远程 REST A2A Agent 支持自定义 action 后缀，通过 `restA2AConfig` 配置：

```typescript
restA2AConfig: {
  capabilityId: 'data_query_assistant',
  streamAction: 'stream',    // 流式端点后缀，默认 'stream'
  invokeAction: 'run',       // 同步端点后缀，默认 'invoke'
  fallbackToSync: false,     // 流式失败时不回退到同步
}
```

URL 构建规则：

-   用户配置的 `remoteUrl` 如果已带 action 后缀（如 `.../data_query_assistant:stream`），系统会自动剥离旧后缀，再拼接配置的 action
-   如果 URL 不含 `/capabilities/` 路径，系统会自动补全 `/api/v1/a2a/capabilities/{capabilityId}` 前缀

## Optional Dependencies

以下依赖为可选（`optionalDependencies`），仅在用到对应功能时需要安装：

| 依赖 | 用途 |
| --- | --- |
| `jsonpath-plus` | MCP api-bridge 响应提取 |
| `@apidevtools/swagger-parser` | OpenAPI 导入 |
| `fast-glob` | search\_code 工具 |
| `turndown` / `html-to-text` | web\_fetch 工具 HTML 转换 |
| `cheerio` / `axios` | web\_fetch 网页解析；http\_request 等网络工具（出网代理经 agent-core 共享 HttpClient） |

未安装时对应工具会在运行时报错，不影响其他功能。

## 构建

```bash
cd packages/agent-server
npm run build
```

## 常见问题

### @cicctencent/agent-server 是什么？

代理-核心的服务器层工具包——代理初始化,SSE流化,内置工具,连接器,聊天/设定/记忆服务与SPI可扩展性\.

### 如何安装 @cicctencent/agent-server？

在项目目录运行 npm install @cicctencent/agent-server，或使用 pnpm add / yarn add / bun add。

### @cicctencent/agent-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cicctencent/agent-server 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cicctencent/agent-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.17\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cicctencent/agent-server 可以商用吗？

@cicctencent/agent-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cicctencent/agent-server 的下载量有多少？

根据 npm 官方下载统计，@cicctencent/agent-server 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,834 次，日均约 61 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cicctencent/agent-server 还在维护吗？

最新版本 1\.0\.86 发布于 2026/11/06（3 天前）；至今共发布 173 个版本，其中过去 12 个月发布了 173 个；首次发布于 2026/06/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。