# @beignet/agent-auth-better-auth 中文文档

规范地址：https://npmcn.com/package/%40beignet/agent-auth-better-auth/

版本：0\.0\.65
npm 元数据更新时间：2026-11-07T23:22:31.500Z
中文译文更新时间：2026-11-09T19:47:26.403Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：56.5 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：0 个
- peer 依赖：zod ^4\.6\.6，better-auth \>=1\.7\.7 \<1\.8\.0，@beignet/core \>=0\.0\.3 \<1\.0\.0，@better-auth/agent-auth \>=0\.6\.2 \<0\.7\.0
- 首次发布：2026-07-12T01:16:00.937Z
- 最新版本发布：2026-11-07T23:22:31.317Z
- 近 30 天下载量：1769（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

Beignet 代理能力更好的 Auth 代理 Auth 适配器

## 安装

```sh
npm install @beignet/agent-auth-better-auth
```

也可以使用：`pnpm add @beignet/agent-auth-better-auth`、`yarn add @beignet/agent-auth-better-auth`、`bun add @beignet/agent-auth-better-auth`

## README

# @ beignet/ agent-auth-better-auth (英语)

> **运行时间 :** Beignet需要Node.js 22.12或更新. Bun是可选的.

> \[叹息\] Beignet是实验性的α软件. 这个 `0.0.x` 包行为早期 评估,且在框架结算时,API可能在发布之间发生变化.

通过 Better Auth 代理显示一个打入的 Beignet 代理能力注册 Auth 插件 。 Beignet 拥有能力验证, 应用程序上下文, 使用大小写 执行、追踪和仪器。 Auth代理拥有注册, JWT 核查、赠款、限制、核准和协议的持久性.

## 安装

```bash
bun add @beignet/core @beignet/agent-auth-better-auth \
  @better-auth/agent-auth@0.6.2 better-auth@1.7.14 zod@^4.6.6
```

该桥支持 Auth 代理 `>=0.6.2 <0.7.0` 和更好的奥特 `>=1.7.7 <1.8.0`,与佐德 `^4.6.6`。命令为认证版本打针 碧网共证.

## 确定能力

```typescript
// lib/agent-capabilities.ts
import { createAgentCapabilities } from "@beignet/core/agent-capabilities";
import type { AppContext } from "@/app-context";

export type AgentPrincipal = {
  agentId: string;
  userId: string;
};

export const { defineAgentCapability, defineAgentCapabilityRegistry } =
  createAgentCapabilities<AppContext, AgentPrincipal>();
```

```typescript
// features/issues/agent-capabilities.ts
import { z } from "zod";
import { createIssueUseCase } from "./use-cases";
import { defineAgentCapability } from "@/lib/agent-capabilities";

export const createIssueCapability = defineAgentCapability("issues.create", {
  description: "Create an issue in one workspace.",
  input: z.object({
    workspaceId: z.string().min(1),
    title: z.string().min(1),
  }),
  output: z.object({ id: z.string(), title: z.string() }),
  async handle({ ctx, input }) {
    const { workspaceId: _workspaceId, ...useCaseInput } = input;
    return createIssueUseCase.run({ ctx, input: useCaseInput });
  },
});
```

## 创建注册和执行器

```typescript
import { createAgentCapabilityExecutor } from "@beignet/core/agent-capabilities";
import { appError } from "@/features/shared/errors";
import { createIssueCapability } from "@/features/issues/agent-capabilities";
import { defineAgentCapabilityRegistry } from "@/lib/agent-capabilities";
import { getServer } from "@/server";

export const agentCapabilityRegistry =
  defineAgentCapabilityRegistry([createIssueCapability]);

export const agentCapabilityExecutor = createAgentCapabilityExecutor({
  registry: agentCapabilityRegistry,
  async createContext({ principal, input }) {
    const server = await getServer();
    const membership = await server.ports.members.findMembership({
      workspaceId: input.workspaceId,
      userId: principal.userId,
    });
    if (!membership) throw appError("NotAWorkspaceMember");

    return server.createServiceContext({
      asUser: { id: principal.userId, role: membership.role },
      tenantId: input.workspaceId,
    });
  },
});
```

执行器在上下文构建前验证参数并验证 处理器在归还给Auth探员之前是结果 上下文解析器必须 从权威的应用州获得租户成员资格,而不是代理权利.

## 添加 Auth 代理桥

```typescript
import { agentAuth } from "@better-auth/agent-auth";
import { betterAuth } from "better-auth";
import { APIError } from "better-auth/api";
import { createBetterAuthAgentCapabilityAdapter } from
  "@beignet/agent-auth-better-auth";
import {
  agentCapabilityExecutor,
  agentCapabilityRegistry,
} from "@/server/agent-capabilities";

const agentCapabilities = createBetterAuthAgentCapabilityAdapter({
  registry: agentCapabilityRegistry,
  executor: agentCapabilityExecutor,
  principal({ agentSession }) {
    if (!agentSession.userId) {
      throw new APIError("FORBIDDEN", {
        message: "A delegated user is required.",
      });
    }
    return {
      agentId: agentSession.agentId,
      userId: agentSession.userId,
    };
  },
  metadata: {
    "issues.create": {
      approvalStrength: "session",
      requiredConstraints: ["workspaceId"],
    },
  },
});

export const auth = betterAuth({
  // database, sessions, and other app-owned configuration
  plugins: [
    agentAuth({
      ...agentCapabilities,
      providerName: "example",
      modes: ["delegated"],
    }),
  ],
});
```

登记后 `agentAuth(...)`重新创造出更好的奥斯计划 数据库适配器并应用由此产生的迁移。 后重复此步骤 更新添加或修改的代理 Auth 或更改更好的 Auth 插件 数据库字段,因此注册、赠款和协议状态匹配运行时间. 从更好的 Auth 升级应用程序 `1.7.0`– 说吧 –`1.7.2` 必须放松遗产 `account.issuer` 尽管Auth探员仍然坚持 `0.6.2`。跟踪 [Auth 1.7 更好的移徙指导](https://beignetjs.com/authentication#upgrade-an-existing-app-to-better-auth-17) 在部署更新的运行时间之前.

如果认证初始化和服务器组成相互依赖,请提供 懒惰的执行者, 而不是建立应用程序的代理 :

```typescript
import { agentCapabilityRegistry } from "@/lib/agent-capability-registry";

const agentCapabilities = createBetterAuthAgentCapabilityAdapter({
  registry: agentCapabilityRegistry,
  executor: () =>
    import("@/server/agent-capabilities").then(
      ({ agentCapabilityExecutor }) => agentCapabilityExecutor,
    ),
  principal({ agentSession }) {
    if (!agentSession.userId) {
      throw new APIError("FORBIDDEN", {
        message: "A delegated user is required.",
      });
    }
    return { agentId: agentSession.agentId, userId: agentSession.userId };
  },
});
```

在不导入服务器的模块中保留运输安全注册 组成; 只有执行器需要动态服务器导入 . 适配器在第一次执行时加载执行器并记住第一次执行 成功解析温模块实例的寿命。 同时 执行共享初始化; 失败解析没有缓存 .

Zod schemas默认转换为协议JSON Schema. 通过一个贝格网 `SchemaConverter` 结束 `schemaConverter` 当使用另一个标准Schema时 图书馆。 在适配器创建时转换运行, 从而在不支持的计划中失败 而不是第一个代理请求.

Auth代理授权在援引前对原始论点施加限制 适配器。 适配器还在执行时核实活动赠款 仍然包含当前在 `requiredConstraints`这个 防止在能力元数据完成后继续使用较旧的广泛赠款 收紧了 取消或转移过期的赠款,以便代理商可以要求替换 具有新要求范围的赠款.

Beignet 也拒绝在计划验证更改字段时引用 受现行赠款的限制。 保留受限制的标识符和金额 未变形;未受限制的领域仍可实现正常化. 适配器在验证前将活动受限值抓取一次, 并检查随后用于上下文构建的精确解析输入 和处决.

此桥有意使用 Auth 的默认能力执行 终点 不暴露定制能力 `location` 元数据因为 自定义位置将请求发送到一个应用程序拥有的路由并绕过此桥 验证、上下文、制约稳定性、追踪和产出保证.

适配器保留有意的更好的 Auth `APIError` 失败。 已宣布为 贝格网 `AppError` 失败时使用其稳定应用代码作为代理 Auth 错误代码 。 个人执行也保留了 AppError HTTP 状态; 批量执行报告每个项目为失败, 并保存代码没有 每个项目 HTTP 状态。 无效的参数成为 Auth 代理 `invalid_request` 错误; 未知的能力使用 `capability_not_found`; 无效输出和 意外失败变为已编辑 `internal_error` 回应。 掷出 `APIError` 或声明 `AppError` 只有当失败是故意安全的 来接收一个特工.

在此只支持同步请求/响应能力结果 释放。 Auth探员仍保持同步投票结果 由Beignet执行人负责生产.

## 测试

使用适配器测试子路径进行练习 `onExecute` 没有制造 更好的 Auth 内部端点上下文 :

```typescript
import { createBetterAuthAgentCapabilityTestContext } from
  "@beignet/agent-auth-better-auth/testing";

await agentCapabilities.onExecute?.(
  createBetterAuthAgentCapabilityTestContext({
    capability: "issues.create",
    arguments: { workspaceId: "workspace_1", title: "Fix login" },
    constraints: { workspaceId: "workspace_1" },
  }),
);
```

## 代理技能

这个包装的是谭斯塔克特意技能: `@beignet/agent-auth-better-auth#agent-capabilities`定义时加载 能力登记册、构建授权的服务环境或线路 奥特特工.

## 常见问题

### @beignet/agent-auth-better-auth 是什么？

Beignet 代理能力更好的 Auth 代理 Auth 适配器

### 如何安装 @beignet/agent-auth-better-auth？

在项目目录运行 npm install @beignet/agent-auth-better-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.6\.6）、better-auth（\>=1\.7\.7 \<1\.8\.0）、@beignet/core（\>=0\.0\.3 \<1\.0\.0）、@better-auth/agent-auth（\>=0\.6\.2 \<0\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beignet/agent-auth-better-auth 支持 TypeScript 吗？

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

### @beignet/agent-auth-better-auth 支持 ESM 还是 CommonJS？

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

### @beignet/agent-auth-better-auth 需要什么版本的 Node\.js？

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

### @beignet/agent-auth-better-auth 可以商用吗？

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

### @beignet/agent-auth-better-auth 的下载量有多少？

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

### @beignet/agent-auth-better-auth 还在维护吗？

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