# @dotcms/ai 中文文档

规范地址：https://npmcn.com/package/%40dotcms/ai/

版本：26\.11\.17-1
npm 元数据更新时间：2026-11-17T15:16:05.083Z
中文译文更新时间：2026-11-17T17:26:50.998Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcms/ai
原文对照：https://npmcn.com/package/%40dotcms/ai/?lang=original
项目主页：https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/ai/README.md
源码仓库：https://github.com/dotCMS/core#main

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

- 包体积（解压后）：1.9 MB，85 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2026-06-25T20:20:48.551Z
- 最新版本发布：2026-11-17T15:16:04.905Z
- 近 30 天下载量：5004（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

DotCMS代理运行时间——安全地运行模型写作或人文写作的代码来对抗dotCMS实例,其认证和政策拥有在一个地方.

## 安装

```sh
npm install @dotcms/ai
```

也可以使用：`pnpm add @dotcms/ai`、`yarn add @dotcms/ai`、`bun add @dotcms/ai`

## README

# @ dotcms/ai (英语)

每一个其他CMS 手一个AI a _固定工具菜单_ ——它只能做供应商预先建造的. `@dotcms/ai` 做相反的:模型写出代码,运行时间运行在一个沙盒中,与整个dotCMS API相对应,其认证和政策拥有在一个地方. 天花板不是工具列表;而是API本身.

你带来了任何驱动器——一个模型,一个代理框架,一个像n8n的自动化工具. 这是他们下面的行刑层: 里面没有LLM, 它只运行代码,安全.

这也是层点CMS自有的MCP服务器和一党代理运行的. 我们上船,不只是出版.

### 建筑管理

安全不是你打开的设定,而是运行时间的形状:

-   **你的纪念品从不进入沙盒.** Auth 在主机一侧被注入; 执行代码无法读取 .
-   **适应器是唯一的出路.** 沙盒代码到达网络/主机 _仅限_ 通过你给予的适配器——直接 `fetch`编号 :`require`编号 :`process.env` 被删除.
-   **水面由你决定.** 允许列表(或键入) `defineAdapter` 操作)限制任何代码——模型写作或不写——能够达到的. 展览 `scan` 财务报告和审定财务报表 `read`; 从不曝光 `delete`。允许列表在点块和编码点块解析后判断实际要求的路径,所以 `/allowed/../elsewhere` 不能滑过它。 它还匹配整个路径段: 允许 `/api/v1/content` 允许结束点和它下面的一切,不是 `/api/v1/contenttype`。不是绝对路径的条目(`''`,空白,相对)在运行时间或工具被创建时会丢出,所以一个打字失败了,而不是打开API; `'/'` 是允许每一条道路的明确途径.

## 安装

```bash
npm install @dotcms/ai
```

## 我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 `@dotcms/*` 货包船 **完全相同的版本编号** 作为点CMS的发布,它是为(例如:点CMS)而建的 `26.7.14-1` → `@dotcms/client@26.7.14-1`, (中文(简体) ), `@dotcms/react@26.7.14-1`,等等).

**简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.**

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的任何东西,因此一个更老的SDK通常会针对一个更新的点CMS实例继续做得很好. 但偶尔,发布会包含真正的突破性变化——如果你的SDK比那个点还老,它会停止正确工作.

你不需要自己追踪:你的点CMS实例总是知道它仍然支持的最古老的SDK版本,SDK会自动对照它进行自我检查. 如果你使用太老了的SDK,你就会在控制台上看到一个明确的警告,要你升级.

**建议:** 将您的 SDK 标注在与您点CMS 实例相同的版本上, 只有在您升级了点CMS 时, 或控制台命令您这样做时才会撞出它们 .

> **在LTS发布?** LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,使用所发布的SDK版本,以在您LTS版本或之前最接近的常规发布.
> 
> 想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 [发布和支持生命周期( S)](https://dev.dotcms.com/docs/release-support-lifecycle)。 。 。 .

## 前门——一跑一跑 二动词

```ts
import { createRuntime } from '@dotcms/ai/runtime';

const dotcms = createRuntime({
    url,          // dotCMS instance URL
    token,        // dotCMS auth token — NEVER enters the sandbox
    allow,        // optional allow-list/policy (string[] of paths, matched with everything under them; or a predicate)
    sessionId,    // context-cache + isolation key
    includeSpec,  // inject the `spec` global for the search use case
    timeout       // sandbox wall-clock timeout (ms)
});

await dotcms.request(opts);   // DIRECT — you write the call. No worker.
await dotcms.run(code);       // SANDBOXED — a model wrote `code`.
```

**保持表面小的一条规则:** `request` 默认值. `run` 只为代码你做了 **没有** 写( 模型有) 。 如果你自己写电话,你不需要 `run`。 。 。 . `run(code)` 已执行 _作为_ "给一个工人 `api.request` 转发至 `dotcms.request`" ——两个动词共用一个适配器,一个认证路径,一个允许列表,一个错误模型,不能漂移.

## 软件包地理学——一个软件包,子路径作为接缝

| 子路径 | 观众 | 包含 | 普通吗? |
| --- | --- | --- | --- |
| `@dotcms/ai/runtime` | 多数呼叫者——前门 | `createRuntime`, (中文(简体) ), `defineAdapter`错误 | 点CMS 有线 |
| `@dotcms/ai/sandbox` | 电源用户/自定义适配器 | `createSandbox`, (中文(简体) ), `defineAdapter`, (中文(简体) ), `Executor`类型、错误 | **完全通用、强化** |
| `@dotcms/ai/adapter` | 电力用户 | `dotcmsAdapter`, (中文(简体) ), `requestCore`,上下文加载+缓存 | 特定点CMS |
| `@dotcms/ai/spec` | 搜索使用大小写 | openAPI 光谱( opt- in; 使 ~400KB 远离默认路径) | 特定点CMS |
| `@dotcms/ai/tools` | 主机建立自己的 MCP 服务器或代理 | 每个工具一个工厂(`searchTool`, (中文(简体) ), `executeTool`, (中文(简体) ), `pageCreateTool`(......)及其背后的行动(......)`createPage`, (中文(简体) ), `placeContent`, (中文(简体) ), `verifyPage`, (中文(简体) ), `uploadAssets`, (中文(简体) ), `downloadAssets`(中文(简体) ) | dotCMS专有, **顶层, 强化** |

`@dotcms/ai` 是一个纯粹的命名空间——没有赤裸的导入;一切通过子路径到达。 这是一个 **伞** 用于生长:未来AI表面(RAG,嵌入物,自定义剂,取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.

地层只有一个方向: `tools` 以 `runtime`,以 `adapter` 财务报告和审定财务报表 `sandbox`。林特规则保持 `sandbox` 没有点CMS代码, 并且保持所有的东西在下面 `tools` 从进口,所以赤裸裸的 `@dotcms/ai/runtime` 导入绝不在工具描述中拉动或 `node:fs`。 。 。 .

## 现成的工具—— `@dotcms/ai/tools`

同样的7个工具点CMS自己的MCP服务器船,为您包装. 您带来了主机( 一个 MCP 服务器, 一个代理环路, 一个工作流程节点); 这些工具带来了调制的描述, 经验证的输入策略和每个后面的尖端处理 .

| 工厂 | 工具名称 | 它会做什么 | 只读 | 决定 |
| --- | --- | --- | --- | --- |
| `searchTool` | `search` | 模型写 JS 探索捆绑的 OpenAPI spec | 对 | `{ result: string }` |
| `executeTool` | `execute` | 模版JS称沙盒中的点CMS API | 没有 | `{ result: string }` |
| `pageCreateTool` | `page_create` | 创建并发布一个页面, 先创建其文件夹, 这样 URL 无法崩溃 | 没有 | `CreatePageManifest` |
| `pagePlaceContentTool` | `page_place_content` | 将内容放在页面槽中而不擦去它没有触及的槽 | 没有 | `PagePlaceContentManifest` |
| `pageVerifyTool` | `page_verify` | 渲染一页并诊断空位、吞入 VTL 错误和 stale 缓存 | 对 | `VerifyPageManifest` |
| `uploadAssetsTool` | `upload_assets` | 将本地目录作为文件资产上传到 dotCMS | 没有 | `UploadAssetsManifest` |
| `downloadAssetsTool` | `download_assets` | 将 dotCMS 文件资产流到本地目录 | 没有 | `DownloadAssetsManifest` |

创建一个 **连接**,“点CMS实例”和“识别工具”的作用是,然后为每个工具调用一个工厂,通过连接。 AI SDK生态系统中的大多数工具包都是这样工作的.

```ts
import { generateText } from 'ai';
import { dotcmsConnection, pageCreateTool, pageVerifyTool, searchTool } from '@dotcms/ai/tools';

const dotcms = dotcmsConnection({ url: 'https://demo.dotcms.com', token });

const result = await generateText({
    model,
    prompt: 'Create a /books page and check that it renders',
    tools: {
        search: searchTool(dotcms),
        page_create: pageCreateTool(dotcms),
        page_verify: pageVerifyTool(dotcms)
    }
});
```

每个工具都是平庸的对象—— `name`, (中文(简体) ), `title`, (中文(简体) ), `description`, (中文(简体) ), `inputSchema` (佐德语), `annotations` (MCP的只读/破坏性/单发/开放世界提示), `execute` 财务报告和审定财务报表 `toModelOutput` ——塑造了Vercel AI SDK和MCP TypeScript SDK的预期方式. 每个结果都是一个对象,正如Google ADK所要求的. 包裹全靠他们.

**连接.** 您提供 URL 和符号; 工具永远不会去寻找它们 。 数值可以是字符串或解析器 。 每一次通话都会读出解析器,其中涵盖了旋转符号,秘密管理器,以及懒地读取自己配置的主机:

```ts
const dotcms = dotcmsConnection({
    url: 'https://demo.dotcms.com',
    token: () => secrets.get('dotcms-token'),     // string | () => string | undefined | Promise<…>
    onCall: (event) => tracer.record(event),       // optional: fired around every request
    onContextError: (label, error) => log(label, error),
    onResolveError: (field, error) => log(`dotCMS ${field} resolver failed`, error)
});
```

连接没有状态,也没有请求 。 一个服务于许多用户的主机,比如一个每个用户OAuth的远程MCP服务器,或者一个每个用户一个会话的代理机,每个会话都会与该用户的令牌创建一个连接,并从中构建出它的工具.

**工具选项** 描述工具,而不是呼叫者。 他们去工厂的第二个论点:

```ts
const tools = {
    page_create: pageCreateTool(dotcms),
    page_verify: pageVerifyTool(dotcms, { requestTimeout: 10_000 }),
    execute: executeTool(dotcms, { allow: ['/api/v1/content', '/api/content/_search'] })
};
```

你从来不告诉一个工具 哪个终点呼叫—— 每个工具都拥有它 **执行** 这个 每个固定用途工具都确切地声明它所呼唤的终点、方法和路径,任何其他请求都用 `POLICY` 在它到达电线前失败. `page_create` 知道它需要文件夹,内容类型和工作流程起火端点,所以不需要列出它们,也不能通过漏出一个来打破. 一个错误进入 `page_verify`,或者一个页面路径形状 攀爬到别处,仍然无法通过 渲染和站点端点。 这个包 `search` 沙盒也一样 `api` 适配器为 `execute`,而它的允许列表(上下文已读出,没有其他内容)就是使得它只读.

例外的是 `execute`,其中 _模式_ 选择终点. `executeTool` 带 `allow`,同样的允许列表 `createRuntime` 绑定模型的代码 上下文是 `sites` 编号 : `contentTypes` 编号 : `languages` 编号 : `currentUser` 全球总是允许, `GET` 只能这样,所以一个狭义的列表 永远不会默默地空出它们.

| 选项 | 工具 | 默认 |
| --- | --- | --- |
| `allow` | `executeTool` | 无 – 模型的代码可以调用任何令牌允许的端点(其他工具总是限于自己的端点) |
| `timeout` | `executeTool` | 45 000毫秒沙盒墙上 |
| `includeStacks` | `executeTool` | 假 —— 主机堆栈痕迹从模型中扣取 |
| `requestTimeout` | 页面和资产工具 | 每个请求3万毫秒;每个文件的资产工具包括转让 |
| `root` | 资产工具 - **所需经费** | 无 – 该模型的本地目录 `src` 编号 : `dest` 必须留在里面, 符号链接解决 |
| `maxFileBytes` | `uploadAssetsTool` | 100 MB — 一个更大的文件在被读取前失败; 其他的仍然上传. `Infinity` 举起它 |
| `maxFiles` | `uploadAssetsTool` | 1 000个文件(之后) `include`是一个 `VALIDATION` 在发送任何信息之前失败 . `Infinity` 举起它 |
| `maxScannedEntries` | `uploadAssetsTool` | 二万人——走着 `src` 站在那里,对齐 `include` 或者不是,作为一个 `VALIDATION` 失败. `Infinity` 举起它 |

**资产工具需要 `root`。 。 。 .** `uploadAssetsTool` 财务报告和审定财务报表 `downloadAssetsTool` 触摸本地磁盘,由模型选择路径。 没有边界,主机服务器的 `upload_assets` 将读取该过程可以使用的任何目录(并通过dotCMS服务),以及 `download_assets` 将写入任何目录。 命名模型可能使用的工作空间 :

```ts
uploadAssetsTool(dotcms, { root: '/srv/agent-workspace' })
downloadAssetsTool(dotcms, { root: '/srv/agent-workspace' })
```

路径在同义链接解析后被比较:从根中指出的一个链接被拒绝,通过同义链接写入的下载也会被拒绝. `root: '/'` 是一个明确的全磁盘选择, 本地代理作为自己的用户。 dotCMS MCP服务器使用.

**文件大小 .** 两个方向不同:

-   **下载流.** 每个文件的字节从响应直接到磁盘,一次一个块,因此无论文件大小(测量:一个200 MB资产,增长不到40 MB),内存都保持平平. 以临时名称命名的文件,只有在完成后才重新命名为原地,因此,中断的移交不会留下部分文件或损坏它所取代的文件.
-   **上传将每个文件保存一次.** 文件以磁盘背面的 Blob 打开,从未复制过或基数64-被工具编码,但 `fetch` 在发送前收集一个请求正体入内存:被测量在节点22上,一个1GB的文件成本约为1GB. 文件一次一个,所以一个批次 花费它最大的文件,而不是它的总数。 因为模型选择 `src`, (中文(简体) ), `uploadAssetsTool` 默认执行限制 : `maxFileBytes` (100 MB,也是上传的内存绑定),, `maxFiles` (1 000美元)和 `maxScannedEntries` (20 000个条目走过,如此广阔) `src` 有个窄的 `include` 没有走到底。 直接 `uploadAssets` 除非您通过相同的选项,否则操作是无限制的.

两个方向也以 `requestTimeout`,它覆盖每个文件的整个传输:在慢链接上为大文件提升.

**`execute` 从来没有扔过.** 它验证输入对象 `inputSchema` (它来自模型,所以这是信任边界), 运行工具,并解决上表中的结果——或 `ToolFailure`数字 : `{ ok: false, code, retryable, error, status? }`编辑 `retryable` 旗帜存在,因为模型不能 `instanceof` 需要告诉它再次尝试是否有帮助. `isToolFailure(result)` 告诉两者分开. `code` 是一个 `ToolFailureCode`其中一个 `VALIDATION`, (中文(简体) ), `POLICY`, (中文(简体) ), `HTTP`, (中文(简体) ), `NETWORK`, (中文(简体) ), `TIMEOUT`, (中文(简体) ), `ABORT`, (中文(简体) ), `SANDBOX`, (中文(简体) ), `RUNTIME`, (中文(简体) ), `CONFIGURATION` 或者说 `UNKNOWN`,因此一个在它上切换的主机会完成,一个错误的密码不会编译.

**输入和列表类型.** 每个工厂返回一个 `DotCMSTool` 谁 `execute` 输入从它自己的计划中输入:调用 `pageVerifyTool(dotcms).execute({ path: 42 })` 是一个编译错误,您的编辑器完成字段。 这是你写代码的方便;上面的运行时间检查仍然适用,因为一个模型发送的东西从来没有过打字检查. 在一个列表或地图中保存有不同计划的工具, 并调用选择的模型, 键入其中 `AnyDotCMSTool[]`页:1 `execute` 带 `unknown`,每个工具都可以指定.

**没有I/O在创建.** 也没有 `dotcmsConnection` 任何I/O都不是工厂;每次通话都会解决和检查连接。 一个例外是您自己的静态配置: a `allow` 条目 `executeTool` 当工具创建时,这不是一条路径,因为它是一个安全边界。 因此,一个主机开始之前,它的证书 仍然靴子和列出它的工具 `CONFIGURATION` 失败而不是主机崩溃 。 包含一个空值,一个解析器返回 `undefined`和一个解析器投出。 当解析器抛出时,只告诉模型无法解决连接. 机密管理器的错误可以携带路径,密钥名或主机名,所以真正的错误只能通过连接的 `onResolveError` 钩;返回的失败不携带. 每一次呼叫还构建了新的运行时间,因此实例背景(站点,内容类型,语言)从一个呼叫到另一个呼叫都永远不会停滞.

**模特儿所见所闻.** 每个工具决定其成果如何达到模式. `search`编号 :`execute` 声明文本窗体,其余部分显示为结构化的JSON(同样是任何失败). 在AI SDK中,工具的 `toModelOutput` 自动取出。 MCP 等仅文本的传输系统将工具称为自己的 `toText(result)`,它应用了同样的规则:代码文本未脱逃,其他所有漂亮印刷的JSON.

**将每个工具登记在其下 `name`。 。 。 .** 描述中用这些名字来称呼他们的兄弟姐妹(使用 `search` 工具,“优先” `page_create`" (中文(简体) ). 一个以另一个名称注册的工具仍然有效,但该模型被指向不存在的一个.

### 使用 MCP 类型脚本 SDK

工具对象已经有效 `registerTool` 相会. 剩下的只是MCP的文本信封:

```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { dotcmsConnection, pageVerifyTool, searchTool, type AnyDotCMSTool } from '@dotcms/ai/tools';

const dotcms = dotcmsConnection({ url, token });
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
const tools: AnyDotCMSTool[] = [searchTool(dotcms), pageVerifyTool(dotcms)];

for (const tool of tools) {
    server.registerTool(tool.name, tool, async (args) => ({
        content: [{ type: 'text', text: tool.toText(await tool.execute(args)) }]
    }));
}
```

### 与 Google ADK 连接

阿达克的 `FunctionTool` 直接将 Zod 计划作为 `parameters`数字 :

```ts
import { FunctionTool, LlmAgent } from '@google/adk';
import { dotcmsConnection, pageVerifyTool, searchTool, type AnyDotCMSTool } from '@dotcms/ai/tools';

const dotcms = dotcmsConnection({ url, token });
const tools: AnyDotCMSTool[] = [searchTool(dotcms), pageVerifyTool(dotcms)];

const agent = new LlmAgent({
    model: 'gemini-flash-latest',
    name: 'dotcms_agent',
    instruction: 'Help authors manage their dotCMS site.',
    tools: tools.map(
        (t) =>
            new FunctionTool({
                name: t.name,
                description: t.description,
                parameters: t.inputSchema,
                execute: (input) => t.execute(input)
            })
    )
});
```

计划是Zod 4. 你的框架和 `@dotcms/ai` 必须解决 **不变** Zod安装,正常安装就是如此. 如果您给第二个副本下针, TypeScript 会拒绝 `inputSchema` 其中框架预计它自己的Zod类型.

### 用一个框架来取出JSON Schema

Anthropic和OpenAI SDKs,n8n等取取了JSON Schema而不是Zod. 把它从 **投入** 边,因此默认保留字段可选。 否则,模型被告知 它必须发送每一个:

```ts
import { z } from 'zod';
import { dotcmsConnection, pageVerifyTool, searchTool, type AnyDotCMSTool } from '@dotcms/ai/tools';

const dotcms = dotcmsConnection({ url, token });
const tools: AnyDotCMSTool[] = [searchTool(dotcms), pageVerifyTool(dotcms)];
const definitions = tools.map((t) => ({
    name: t.name,
    description: t.description,
    input_schema: z.toJSONSchema(t.inputSchema, { io: 'input' })
}));

// …when the model asks for a tool:
const result = await tools.find((t) => t.name === block.name)?.execute(block.input);
```

### 选择地表

表面正是您导入和注册的。 展览 `search` 财务报告和审定财务报表 `page_verify` (两个只读工具),且模型不能创建或删除任何东西——两者都持有 `GET`s 由他们自己的许可列表, 不只是他们的说明。 每个固定用途工具只能达到自己的终点. `execute` 是无限的,所以绑定 `allow`或者别管了.

### 工具背后的行动

这些工具在键入操作上进行格式化,这些操作也输出出. 它们是直接路径,工具级对应 `request()`: 当 **你们** 写电话 输入的选项,一个输入的运算表会出来,错误会从上面的一个等级中抛出.

```ts
import { createRuntime } from '@dotcms/ai/runtime';
import { createPage, placeContent, verifyPage } from '@dotcms/ai/tools';

const dotcms = createRuntime({ url, token });

const page = await createPage({ dotcms, site: 'demo.dotcms.com', urlPath: '/books', title: 'Books', template: templateId });
await placeContent({ dotcms, path: page.fullPath, site: 'demo.dotcms.com', slots: [{ slot: 1, contentlets: [bookId] }] });
const report = await verifyPage({ dotcms, path: page.fullPath, site: 'demo.dotcms.com' });
```

运行时间从 `createRuntime` 与每个工具调用构建的时间不同 `signal` 改为 `request` 如果你需要的话. `uploadAssets` 财务报告和审定财务报表 `downloadAssets` 读取和写入本地文件系统,所以需要节点或 Bun.

## 自定义、 输入操作 - `defineAdapter`

而不是允许在通用 `request`,显示 **名称操作** 一个LLM可以按名称调用,有Zod验证输入和宣布的输出合同. 这是实际中受管制的道路——模型所见 `scan`没有 `/api/**`数字 :

```ts
import { defineAdapter, createSandbox } from '@dotcms/ai/sandbox';
import { z } from 'zod';

const a11y = defineAdapter({
    name: 'a11y',
    methods: {
        scan: {
            description: 'Scan a page URL; returns axe findings',
            input:  z.object({ url: z.string().url() }),
            output: z.object({ findings: z.object({ violations: z.array(z.any()) }).loose() }),
            handler: ({ url }, { request }) =>
                request({ method: 'POST', path: '/api/v1/page-scanner/a11y/check', body: { url } })
        }
    }
});

const sandbox = createSandbox({
    adapters: [a11y],
    timeout: 120_000,
    request: (opts) => dotcms.request(opts) // host capability; the runtime provides one
});
await sandbox.run(`return (await a11y.scan({ url: 'https://demo.dotcms.com/' })).findings.violations;`);
```

-   **`input` 强制** - 这是 _信托_ 边界(args出自模型代码;在处理器运行前验证).
-   **`output` 用于任何建模适配器** - 这是 _工具合同_ 边框(结果为LLM计划相对;成为自动生成的工具定义)。 使用 **松散/通过** 输出计数,所以一个新的 REST 字段不会违反合同。 适配器 _无_ `output` 被打成不能接触模型,并且从自动生成的工具描述中扣取(`describeAdapterForLLM`) (中文(简体) ).

## 错误模式

单打分级,表面相同自 `request()` 财务报告和审定财务报表 `run()` (一个) `requestCore`: `ValidationError`, (中文(简体) ), `PolicyError`, (中文(简体) ), `HttpError` (卡车状况+身体), `NetworkError` (完全没有反应:拒绝、重置、DNS), `TimeoutError`, (中文(简体) ), `AbortError`, (中文(简体) ), `SandboxError`, (中文(简体) ), `RuntimeError` 所有子类 `DotCMSError`,每个有稳定 `code` 和相册 `toJSON()`。MCP工具构建的模型化字符串是 _顶部格式化_ 这一模式——在 `@dotcms/ai/tools` 格式化为 `ToolFailure` 每个工具都会在失败时解决, 这将添加 `retryable` 标记一个模型需要决定是否再次尝试.

```ts
import { isDotCMSError, HttpError } from '@dotcms/ai/runtime';
try { await dotcms.request({ path: '/api/v1/site' }); }
catch (e) { if (e instanceof HttpError) console.error(e.status, e.body); }
```

## 威胁模式——能力限制,而不是对抗性隔离

以上治理为: **信任的代码生成器的能力限制** 它阻止了自己的模特做不该做的事 而不是攻击者逃跑.

-   **停止意外外出 :** `fetch`编号 :`XMLHttpRequest`编号 :`WebSocket`编号 :`EventSource`编号 :`sendBeacon` 抛出; `require` 删除; 动态 `import()` 在源一级被屏蔽( 所以) `import('node:fs')`编号 :`import('node:net')` 无法重新打开主机访问); `process.env` 空出;工人产下 `env:{}`。 。 。 .
-   **停止运行成本 :** 时钟超时, `resourceLimits` 内存/盒盖,以及 `AbortSignal` 连接到适配器的呼叫中, 因此暂停会中止飞行主机的工作 .
-   **不停止敌对密码.** 用户代码运行通过 `new AsyncFunction(code)` 与工人一样的 V8 隔离 —— 敌对代码可以到达共享的全球 `import()` block是一个源级的后卫(不会对故意的混淆进行硬化). 威胁是"我们自己的模型 幻觉a `DELETE` 或无限循环,"而不是"攻击者提交恶意JS"

**如果您必须运行真正不信任的代码, 请带入您自己的进程/微VM 隔离 .**

## 支持矩阵

-   **节点** 第20条, **阿宝** (本地网络工人). 两个工人的后端行为都一样.
-   **OpenAPI spec QQ服务器版本 :** `@dotcms/ai/spec` 生成于 a _具体_ dotCMS实例(参见"再生谱"). 它是被过滤的快照,而不是活合同——如果它与你所建造的相对面不同,那么它就针对目标服务器重新生成.
-   **塞姆维尔:** 子路径是公共API的一部分;对任何子路径的突破性改变是一个主要.

## 重生成光谱

`src/generated/spec.json` 实值 **构建生成并被忽略** - 它没有承诺。 这个 `build`编号 :`test`编号 :`serve` 目标运行 `sdk-ai:generate-spec` 自动( 通过) `dependsOn`),所以你很少用手操作;这样做只是为了刷新本地副本或检查输出.

```bash
# Defaults to https://demo.dotcms.com/api/openapi.json
pnpm nx run sdk-ai:generate-spec

# Override with a different instance (URL or local file path):
pnpm nx run sdk-ai:generate-spec -- http://localhost:8080/api/openapi.json
```

脚本将 spec 过滤到末尾 `ALLOWED_PREFIXES` (见 `scripts/spec-transform.ts`),保留请求/答复 `$ref`s,和树 `components.schemas` 来说明这些终点 保存中 `$ref`s(而不是去引用) dedups 共享计划并保持文件小(~400KB). 输出为紧凑 JSON( 只读机器) – 使用 `jq` 检查它。 因为光谱是在建设时再生的,所以没有什么可承诺的.

## 图标

```bash
pnpm nx run sdk-ai:build                       # Build (ESM + CJS, dual)
pnpm nx run sdk-ai:test                        # Run tests
pnpm nx run sdk-ai:lint                        # Lint src + scripts
pnpm nx run sdk-ai:generate-spec -- <url-or-path>  # Refresh spec.json
```

## 常见问题

### @dotcms/ai 是什么？

DotCMS代理运行时间——安全地运行模型写作或人文写作的代码来对抗dotCMS实例,其认证和政策拥有在一个地方\.

### 如何安装 @dotcms/ai？

在项目目录运行 npm install @dotcms/ai，或使用 pnpm add / yarn add / bun add。

### @dotcms/ai 支持 TypeScript 吗？

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

### @dotcms/ai 支持 ESM 还是 CommonJS？

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

### @dotcms/ai 需要什么版本的 Node\.js？

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

### @dotcms/ai 可以商用吗？

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

### @dotcms/ai 的下载量有多少？

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

### @dotcms/ai 还在维护吗？

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

