# @gjermundgaraba/effect-actions 中文文档

规范地址：https://npmcn.com/package/%40gjermundgaraba/effect-actions/

版本：0\.31\.0
npm 元数据更新时间：2026-11-10T22:38:19.594Z
中文译文更新时间：2026-11-16T15:18:09.245Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.2 MB，337 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=26\.13\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.3
- 首次发布：2026-09-16T12:13:50.793Z
- 最新版本发布：2026-11-10T22:38:19.097Z
- 近 30 天下载量：7518（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

一次定义效果行动合同,并将其投放到HTTP、MCP、Effect RPC、原生工具包和CLI中.

## 安装

```sh
npm install @gjermundgaraba/effect-actions
```

也可以使用：`pnpm add @gjermundgaraba/effect-actions`、`yarn add @gjermundgaraba/effect-actions`、`bun add @gjermundgaraba/effect-actions`

## README

# 效果动作

定义一次效果动作 。 在HTTP,MCP和Effect RPC上服务,把它作为原生工具箱交给一个模型,从一个CLI上运行. 同样的计划,同样的处理器,Effect自己的服务器和客户端下面. 事件走同样的方式:观看了HTTP,MCP,Effect RPC和CLI,或由webhook提供. 一个同伴包裹, [效果-动作-云层](https://npmcn.com/package/%40gjermundgaraba/effect-actions/packages/cloudflare/),为来自Cloudflare持久对象的HTTP,MCP和RPC路线,事件和包括的网络呼号提供服务.

**如果你是一个编码代理**开始于 [文档/README.md](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/README.md)不在这里。 它将每一项任务、保护一项行动以及限制请求机构,都推到它的网页和例子.

## 看起来是这样

合约上写着一个行动和答案

```ts
const Greet = Action.make("greet", {
  description: "Greet someone by name.",
  input: { name: Schema.String },
  success: Schema.String,
  readOnly: true,
  caller: Action.Anyone,
});
```

一项执行对它的处理者具有约束力:

```ts
const greeting = Action.implement(Greet, ({ name }) =>
  Effect.succeed(`Hello, ${name}!`)
);
```

绑定给它一个路由,供服务器服务,客户端拨打:

```ts
const Http = ActionHttp.make([Greet]); // POST /api/greet
```

东道主想要的每一个表面都有同样的执行:

```ts
const routes = Layer.mergeAll(
  ActionHttp.layer(Http, greeting),
  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" })
);
```

服务 `routes` 带有效果的 `HttpRouter.serve` 和一个平台服务器,作为 [实例/快速启动](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/quickstart) 做,逐个归档,而且你有 `POST /api/greet` 和一个 MCP 工具 `greet` 时间 `/mcp`。同样的 `greeting` 执行工作还包括:

```ts
const { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
const cli = ActionCli.make(greeting, { name: "greetings" }); // greetings greet --name Ada
const remote = ActionCli.remoteCommand(Http, Greet, {
  client: ActionHttp.client(Http, { baseUrl }),
}); // greet --name Ada, over HTTP
const local = Action.client(greeting); // the HTTP client's methods, in process
const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, on the protocol the host provides
```

客户是艾瑟自己的 `HttpApiClient`从同一个合同中打出,每个动作一个方法:

```ts
Effect.gen(function* () {
  const client = yield* ActionHttp.client(Http, { baseUrl });

  return yield* client.greet({ name: "Ada" }); // "Hello, Ada!"
});
```

## 为什么

-   输入,成功和出错被声明一次. 路由,工具,CLI旗,客户端和OpenAPI文档都来源于该声明,因此不能不同意.
-   一个处理器只有在它的动作声明出错误和三个内置错误(400,401,403)时才能失败,每个客户端都会把它们解码为打出值.
-   每个合同都规定谁可以称之为: `caller: Action.Anyone`,或者身份服务 一个打电话者必须拥有。 表面认证受保护动作的请求后再解码其输入,由提供方从自己的符号验证器中创建应用程序.
-   授权书写在一次执行时: `Action.implement(actions, handlers, { authorize })`,用于受保护的行动。 每个表面都比每个操作员先运行 规则读到合同 `readOnly` 而不是手持的突变名称列表.
-   公共和受保护的路由共享一个绑定,一个OpenAPI文档和一个客户端,处理器的启动服务每起一次 [层图](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/Action.md#share-one-build-across-servers)不论有多多的表面为它服务.
-   这些片段是Effect的自有: 一个本地人 `HttpApi`, (中文(简体) ), `McpServer`, (中文(简体) ), `RpcServer` 财务报告和审定财务报表 `RpcClient`,没有SDK运行时的依赖性,所以 OpenAPI, Swagger, Scalar 和 `HttpApiClient` 工作不变.
-   在内存中运行的测试 : `Action.client` 要求正在执行 `Testing.layer(routes)` 为不打开端口而输入客户端的路径和工具服务.

## 安装

```sh
pnpm add @gjermundgaraba/effect-actions effect@~4.1.3
```

它需要TypeScript 7或更新,并且只是无害环境管理([文件/设置](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/setup.md#install)) (中文(简体) ). 添加 `@effect/platform-node@~4.1.3` 从节点服务或运行CLI `@types/node` 联合国 `node:` 进口。 每个模块都是子路径导入( E)`.../Action`, (中文(简体) ), `.../ActionHttp`,...);没有软件包根,所以只包含合同的捆绑永远不会加载服务器.

## 实例

[实例/](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/README.md) 拥有完整的应用程序,每个您可以运行的目录, 有自己的测试, 规定了我们推荐应用程序的方式: 每个域的文件夹, 合同在一个文件里 一个浏览器可以导入, 每一个操作方式有一个入口。 它们是在包件中与图书馆和船只核对和测试的.

-   [快速启动](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/quickstart/):上面的程序.
-   [笔记服务](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/notes-service/):提供无记名认证的服务,JSON API和MCP工具来自一个执行,一个CLI和一个浏览器客户端. 多数应用都是这个.
-   [缩写工具](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/mcp-tools/):一个MCP服务器,其工具包裹了上游HTTP API.
-   [助理人员](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/assistant/):没有服务器,与模型的工具和本地命令的相同执行.
-   [现场记录](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/live-rpc/): 效果 RPC 在一个 WebSocket上.
-   [建筑事件](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/build-events/):事件观看了MCP,HTTP,RPC,一个命令行和webhooks,以及报告进展和回答一流的行动.
-   [厨房下沉](https://npmcn.com/package/%40gjermundgaraba/effect-actions/examples/kitchen-sink/): 在一个应用程序中每个模块和几乎每个选项,从每个模块到显示它的文件都有索引.

## 文档

[文档/](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/README.md) 是为编码代理撰写的:每个模块一个短页,按任务排列,每页链接到显示任务工作的示例文件. 开始于 [文档/README.md](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/README.md)。 。 。 .

## 对于特工

这个 `effect-actions` 技能将文件置于编码代理前。 与 [技能水平](https://github.com/vercel-labs/skills),对于其支持的任何代理人:

```sh
npx skills add gjermundgaraba/effect-actions --skill effect-actions
```

作为克洛德代码插件 :

```text
/plugin marketplace add gjermundgaraba/effect-actions
/plugin install effect-actions@effect-actions-marketplace
```

作为编码插件 :

```sh
codex plugin marketplace add gjermundgaraba/effect-actions
codex plugin add effect-actions@effect-actions-marketplace
```

技能来自 `docs/` 在主分支上,可以领先于最新发布的. 它与示例的链接是输入已安装的软件包的路径, `node_modules/@gjermundgaraba/effect-actions/examples`,一个代理读取的没有网络; 已安装的版本的页面在旁边, 在 `node_modules/@gjermundgaraba/effect-actions/docs`。 。 。 .

## 状态

这个 `effect` 对等区域在 [文件/设置](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/setup.md#install)。动作是无关紧要的 JSON 凌驾于 HTTP、 MCP 和 Effect RPC 之上, 其协议仅说 JSON : 不流出或上传 。 Token验证和授权规则属于应用程序;库提供认证描述符和提供者,运行规则,并回答拒绝. 见 [图书馆留给你的东西](https://npmcn.com/package/%40gjermundgaraba/effect-actions/docs/README.md#what-the-library-leaves-to-you)。 。 。 .

## 鸣谢

一些想法(如原生工具包和CLI预测)的灵感来自优秀的 [鼠关](https://github.com/joelhooks/rat-stack) 由乔尔·胡克所著.

## 捐款

设置 [维特+](https://viteplus.dev/guide/)数字 : `vp install`,则 `vp run ready` 运行每个检查。 更改图书馆的规则在 [一般事务人员(其他职等)](https://github.com/gjermundgaraba/effect-actions/blob/main/AGENTS.md)麻省理工学院有执照.

## 释放

弹出版本 `package.json` 财务报告和审定财务报表 `packages/cloudflare/package.json`,承诺,标记 `v<version>` 并按下标签. `.github/workflows/npm.yml` 然后通过 npm 信任的出版,发布每个尚未有 npm 版本的软件包, 核心首先是. 新软件包的第一版手动发布 `vp pm publish`,然后是 `npm trust github <package> --repo <repo> --file npm.yml` 所以工作流程可以发布下一个.

`.github/workflows/effect-latest.yml` 每周对最新效果4.x进行全面检查,这样可以允许通过微小的释放 `effect` 相对范围.

## 常见问题

### @gjermundgaraba/effect-actions 是什么？

一次定义效果行动合同,并将其投放到HTTP、MCP、Effect RPC、原生工具包和CLI中\.

### 如何安装 @gjermundgaraba/effect-actions？

在项目目录运行 npm install @gjermundgaraba/effect-actions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gjermundgaraba/effect-actions 支持 TypeScript 吗？

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

### @gjermundgaraba/effect-actions 支持 ESM 还是 CommonJS？

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

### @gjermundgaraba/effect-actions 需要什么版本的 Node\.js？

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

### @gjermundgaraba/effect-actions 可以商用吗？

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

### @gjermundgaraba/effect-actions 的下载量有多少？

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

### @gjermundgaraba/effect-actions 还在维护吗？

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

