# @decocms/runtime 中文文档

规范地址：https://npmcn.com/package/%40decocms/runtime/

版本：3\.0\.2
npm 元数据更新时间：2026-09-22T17:08:03.334Z
中文译文更新时间：2026-11-11T19:29:35.322Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40decocms/runtime
原文对照：https://npmcn.com/package/%40decocms/runtime/?lang=original
项目主页：https://github.com/decocms/studio#readme
源码仓库：https://github.com/decocms/studio

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

- 包体积（解压后）：272 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.0\.0
- 运行依赖：6 个
- peer 依赖：ai ^7\.0\.107
- 首次发布：2025-11-10T16:05:10.838Z
- 最新版本发布：2026-09-22T17:08:02.929Z
- 近 30 天下载量：8464（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 107 个）

## 中文简介

为在 Studio 后面构建 MCP 应用程序提供框架,其中包含有打入的工具,绑定,认证,OAuth,资源,提示,和触发等.

## 安装

```sh
npm install @decocms/runtime
```

也可以使用：`pnpm add @decocms/runtime`、`yarn add @decocms/runtime`、`bun add @decocms/runtime`

## README

# @ decocms/ 运行时间

提供在 Studio 后方使用已键入的 MCP 应用程序构建框架 工具、绑定、认证、OAuth、资源、提示和触发.

| 属性 | 数值 |
| --- | --- |
| 工作空间 | `@decocms/runtime` (单位:千美元)`packages/runtime`(中文(简体) ) |
| 仁爱 | 公共MCP应用框架 |
| 运行时间 | 节点.js 24+; Web 获取 API |
| 分发 | 公共 npm 软件包 |

## 概览

`@decocms/runtime` mCP 服务器连接到 录音室 它将申报工具、提示、资源、代理和约束转化为 获取兼容的处理器 。 运行时间还提供请求扫描工作室 上下文,用于身份、连接元数据、证书、, 并呼叫绑定MCP.

该包通过明确的包子路径暴露出源类型Script. 消费者 只能导入拥有所需能力的子路径.

## 责任

-   以 Zod 输入和输出计划创建 MCP 工具 .
-   将工具、提示、资源和事件处理器挂载在一个兼容的MCP上 服务器.
-   解析 Studio 请求的上下文和每个请求的绑定连接 .
-   强制获得经认证的受保护工具、提示和资源.
-   当 OAuth 配置存在时服务 OAuth 元数据和 OAuth 路由 .
-   通过金库客户端曝光范围访问 Studio 管理的证书.
-   创建触发管理工具并发送触发回调到 Studio.
-   为连接代理、 MCP 客户端根、 资产和decopilot 提供助手 应用.

## 使用量

在 MCP 应用程序中安装软件包 :

```bash
bun add @decocms/runtime
```

定义工具并导出运行时间处理器 :

```ts
import {
  withRuntime,
} from "@decocms/runtime";
import {
  createTool,
  ensureAuthenticated,
} from "@decocms/runtime/tools";
import { z } from "zod";

const greet = createTool({
  id: "GREET",
  description: "Greet the signed-in user",
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ context, runtimeContext }) => {
    const user = ensureAuthenticated(runtimeContext);

    return {
      message: `Hello, ${context.name}. Signed in as ${user.email}.`,
    };
  },
});

export default withRuntime({
  tools: [greet],
});
```

`withRuntime()` 返回带有 `fetch()` 处理者。 它为MCP服务 结束点 `/mcp`,代表任何与任择申请不符的请求 `fetch` 处理器,并应用配置的 CORS 和 OAuth 行为.

提示和资源使用相同的请求上下文:

```ts
import { createPrompt, createResource } from "@decocms/runtime";
import { z } from "zod";

const reviewPrompt = createPrompt({
  name: "review",
  description: "Review a change",
  argsSchema: {
    path: z.string().optional(),
  },
  execute: ({ args }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review ${args.path ?? "the current change"}.`,
        },
      },
    ],
  }),
});

const statusResource = createResource({
  uri: "studio://status",
  name: "Status",
  mimeType: "application/json",
  read: () => ({
    uri: "studio://status",
    mimeType: "application/json",
    text: JSON.stringify({ ready: true }),
  }),
});
```

`createPrompt()` 财务报告和审定财务报表 `createResource()` 默认时保护他们的处理者。 使用 明确 `createPublicPrompt()` 或者说 `createPublicResource()` 仅当 内容在没有工作室身份的情况下可以安全曝光.

## 建筑

`withRuntime()` 是构成根。 对于收到的每项请求,它:

1.  将Cononic Studio环境域规范化,并支持遗留别名.
2.  创建包含身份和约束状态的请求范围上下文.
3.  初始化已配置绑定 .
4.  将 MCP 请求发送到由工具、 提示、 资源创建的服务器, 特工和事件处理员.
5.  应用 OAuth 和 CORS 围绕结果的行为.
6.  回到自己的应用程序 `fetch()` 非运行时间路线的操作者.

请求上下文以同步请求范围化存储. 接收工具代码 作为第二个背景 `execute()` 参数; 不应读取环境 HTTP 对象或从全进程状态重建 Studio 身份.

绑定描述连接执行的MCP能力. `withBindings()` 解决对请求的约束,同时 `BindingOf`, (中文(简体) ), `AgentOf`,以及 `proxyConnectionForId()` 向需要的消费者提供类型的准入模式 给他们打电话.

## 发展

从寄存器根运行包检查 :

```bash
bun run --cwd=packages/runtime check
bun run --cwd=packages/runtime test
```

延长时运行焦点测试文件 :

```bash
bun test packages/runtime/src/tools.test.ts
```

执行前的格式和插入寄存器更改 :

```bash
bun run fmt
bun run lint
```

## 边界

-   这个软件包是一个MCP应用框架,而不是工作室控制平面. 这个 不得导入服务器执行细节 `apps/api` 或用户界面细节 `apps/web`。 。 。 .
-   将请求范围运行时间上下文作为身份授权, Studio 元数据 和捆绑服务 不要在请求间缓存 .
-   一种工具之所以得不到保护,只是因为它在MCP端点后行走。 打电话 `ensureAuthenticated()` 在需要用户的工具中.
-   提示和资源默认得到认证。 公共变体必须曝光 只有非敏感数据.
-   信誉访问是选入和范围限制的. 永远不要要求更多的证书 并且从未坚持返回的秘密.
-   已发布的包需要节点.js 24或更新. 个人助手使用网络 获取 API; 文件备份触发存储等针对环境的帮助 资产服务器还需要其记录主机能力.
-   遗产 `MESH_*` 环境领域和环境领域 `meshUrl` 仍然是相容性别名. 新代码必须使用 `STUDIO_*` 名称和名称 `studioUrl`。 。 。 .

## 导出表面

| 导入 | 目的 |
| --- | --- |
| `@decocms/runtime` | 运行时的构成、 提示、 资源、 绑定、 请求上下文、 MCP stubs 和 Studio 库客户端 |
| `@decocms/runtime/proxy` | MCP 代理客户端原始 |
| `@decocms/runtime/client` | 运行时工具调用 HTTP 端点的客户端 |
| `@decocms/runtime/bindings` | 具有约束力的声明、登记帮助者和具有约束力的初始化 |
| `@decocms/runtime/asset-server` | 静态和单页申请资产 |
| `@decocms/runtime/tools` | 工具创建加即时、资源、代理和认证原始 |
| `@decocms/runtime/decopilot` | 调试应用程序助手 |
| `@decocms/runtime/triggers` | 触发定义、配置工具和召回 |
| `@decocms/runtime/trigger-storage` | 模拟、 Studio KV 和 JSON 文件触发器 |

这是唯一得到支持的软件包切入点。 在下面不导入文件 `@decocms/runtime/src`。 。 。 .

## 认证和证书访问

`ensureAuthenticated(runtimeContext)` 返回工作室用户或当 请求未经认证。 它是受保护工具的正常护卫.

需要工作室管理的证书的应用程序声明明确 绑定范围权限并创建从靴子拖曳到的客户端 `configuration.onInstall` 或者说 `configuration.onChange`数字 :

```ts
import {
  CREDENTIAL_ACCESS_TOKEN_READ_SCOPE,
  createStudioVaultClient,
  type ConfigurationScope,
} from "@decocms/runtime";
import type { StudioVaultBootstrap } from "@decocms/runtime/tools";

const scopes = [
  `github::${CREDENTIAL_ACCESS_TOKEN_READ_SCOPE}`,
] satisfies ConfigurationScope[];

function vaultClient(bootstrap: StudioVaultBootstrap) {
  return createStudioVaultClient({
    baseUrl: bootstrap.baseUrl,
    org: bootstrap.org,
    token: bootstrap.token,
  });
}
```

使用 `CREDENTIAL_ACCESS_TOKEN_READ_SCOPE` 供供应商访问符和 `CREDENTIAL_CONFIGURATION_READ_SCOPE` 用于非证书配置. 刷新令牌和OAuth客户端的秘密留在工作室金库里,而不是 申请提交合同的一部分.

## 触发和持久性

`createTriggers()` 创建 `TRIGGER_LIST` 财务报告和审定财务报表 `TRIGGER_CONFIGURE` 输入工具 触发定义。 内容 `notify()` 方法是指故意起火并遗忘: 发送失败会被记录下来,不会被扔回网络处理器.

触发配置为进程本地化, 除非应用程序提供一个 `TriggerStorage`启用 `StudioKV` 当工作室 KV 可用时, `JsonFileStorage` 仅用于适当的本地节点/分机部署,或提供适配器,由 应用程序的持久存储.

## 配置、约束和事件

`configuration.state` 接受持续 MCP 配置的 Zod 方案. `BindingOf()` 选项 已输入客户端 `STUDIO_REQUEST_CONTEXT.state`。在 `configuration.scopes`; 工作室在配置时评价这些范围 连接.

`configuration.onChange` 运行配置更新并接收解析 州,授予范围, 和可选的金库靴子. `configuration.onInstall` 运行第一个保存的配置并接收代理提供 帮手 因为网络或部署失败 中断这些回调的工作.

`events.handlers` 通过绑定密钥宣告 CloudEvent 处理器或 `SELF`。 。 。 . 运行时间显示相应的 `ON_EVENTS` 并同时支持两个批次 结果和每个事件的结果。 本订户合同不提供 发布者或发送队列。 呼叫者自有交付和重试;操作者必须 处理重复的事件.

何时 `oauth` 配置,运行时间服务保护资源元数据, 授权服务器元数据、授权、召回、符号和动态客户端 登记路线。 应用程序提供供应商特定授权 和交换证物的行为.

可选 `cors` 属性控制运行时间 CORS 处理; 设置为 `false` 改为 禁用内置层。 可选申请 `fetch()` 处理器接收 不匹配运行时间、 OAuth 或工具调用路径的请求.

## 相关文件

-   [绑定指南](https://npmcn.com/package/%40decocms/runtime/src/bindings/README.md)
-   [仓库准则](https://npmcn.com/package/AGENTS.md)
-   [测试战略](https://npmcn.com/package/TESTING.md)

## 常见问题

### @decocms/runtime 是什么？

为在 Studio 后面构建 MCP 应用程序提供框架,其中包含有打入的工具,绑定,认证,OAuth,资源,提示,和触发等\.

### 如何安装 @decocms/runtime？

在项目目录运行 npm install @decocms/runtime，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7\.0\.107）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @decocms/runtime 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/decocms\_\_runtime 是否存在。

### @decocms/runtime 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @decocms/runtime 需要什么版本的 Node\.js？

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

### @decocms/runtime 可以商用吗？

@decocms/runtime 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @decocms/runtime 的下载量有多少？

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

### @decocms/runtime 还在维护吗？

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