@gjermundgaraba/effect-actions

中文文档
0.31.0发布于 2026/11/11MITES Module零依赖构建来源已验证近 30 天下载 7518

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

中文使用文档
文档目录10 节
  1. 看起来是这样
  2. 为什么
  3. 安装
  4. 实例
  5. 文档
  6. 对于特工
  7. 状态
  8. 鸣谢
  9. 捐款
  10. 释放

效果动作

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

如果你是一个编码代理开始于 文档/README.md不在这里。 它将每一项任务、保护一项行动以及限制请求机构,都推到它的网页和例子.

看起来是这样

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

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

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

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

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

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

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

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

服务 routes 带有效果的 HttpRouter.serve 和一个平台服务器,作为 实例/快速启动 做,逐个归档,而且你有 POST /api/greet 和一个 MCP 工具 greet 时间 /mcp。同样的 greeting 执行工作还包括:

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从同一个合同中打出,每个动作一个方法:

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文档和一个客户端,处理器的启动服务每起一次 层图不论有多多的表面为它服务.
  • 这些片段是Effect的自有: 一个本地人 HttpApi, (中文(简体) ), McpServer, (中文(简体) ), RpcServer 财务报告和审定财务报表 RpcClient,没有SDK运行时的依赖性,所以 OpenAPI, Swagger, Scalar 和 HttpApiClient 工作不变.
  • 在内存中运行的测试 : Action.client 要求正在执行 Testing.layer(routes) 为不打开端口而输入客户端的路径和工具服务.

安装

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

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

实例

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

  • 快速启动:上面的程序.
  • 笔记服务:提供无记名认证的服务,JSON API和MCP工具来自一个执行,一个CLI和一个浏览器客户端. 多数应用都是这个.
  • 缩写工具:一个MCP服务器,其工具包裹了上游HTTP API.
  • 助理人员:没有服务器,与模型的工具和本地命令的相同执行.
  • 现场记录: 效果 RPC 在一个 WebSocket上.
  • 建筑事件:事件观看了MCP,HTTP,RPC,一个命令行和webhooks,以及报告进展和回答一流的行动.
  • 厨房下沉: 在一个应用程序中每个模块和几乎每个选项,从每个模块到显示它的文件都有索引.

文档

文档/ 是为编码代理撰写的:每个模块一个短页,按任务排列,每页链接到显示任务工作的示例文件. 开始于 文档/README.md。 。 。 .

对于特工

这个 effect-actions 技能将文件置于编码代理前。 与 技能水平,对于其支持的任何代理人:

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

作为克洛德代码插件 :

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

作为编码插件 :

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 对等区域在 文件/设置。动作是无关紧要的 JSON 凌驾于 HTTP、 MCP 和 Effect RPC 之上, 其协议仅说 JSON : 不流出或上传 。 Token验证和授权规则属于应用程序;库提供认证描述符和提供者,运行规则,并回答拒绝. 见 图书馆留给你的东西。 。 。 .

鸣谢

一些想法(如原生工具包和CLI预测)的灵感来自优秀的 鼠关 由乔尔·胡克所著.

捐款

设置 维特+数字 : vp install,则 vp run ready 运行每个检查。 更改图书馆的规则在 一般事务人员(其他职等)麻省理工学院有执照.

释放

弹出版本 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 共发布 39 个版本,首次发布于 2026/09/16;过去 12 个月发布了 39 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.31.0latest2026/11/115 天前
0.30.02026/11/0511 天前
0.29.02026/11/0313 天前
0.28.02026/11/0214 天前
0.27.02026/11/0214 天前
0.26.12026/11/0214 天前

其他发布通道:rc → 0.1.0-rc.2。

关于 @gjermundgaraba/effect-actions 的常见问题

@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 和提交记录判断。