# @amaster\.ai/admin-sdk 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/admin-sdk/

版本：1\.1\.72
npm 元数据更新时间：2026-11-05T13:04:10.737Z
中文译文更新时间：2026-11-08T03:07:39.934Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/admin-sdk
原文对照：https://npmcn.com/package/%40amaster.ai/admin-sdk/?lang=original

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

- 包体积（解压后）：175 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-24T11:54:11.581Z
- 最新版本发布：2026-11-05T13:04:10.536Z
- 近 30 天下载量：1926（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：144（近 12 个月 144 个）

## 中文简介

Amaster 平台的管理员 SDK — 服务器侧用户、角色、权限和org 管理

## 安装

```sh
npm install @amaster.ai/admin-sdk
```

也可以使用：`pnpm add @amaster.ai/admin-sdk`、`yarn add @amaster.ai/admin-sdk`、`bun add @amaster.ai/admin-sdk`

## README

# @amaster.ai/admin-sdk (英语)

Amaster平台的服务器端管理器 SDK. 通过内部API管理用户,角色,权限和部门. 设计用途 **边缘函数** (德诺)和Node.js后端——使用原生 `fetch`,没有浏览器 API.

## 边缘函数 QQ( AI \*\*\*)

62\. 阿马斯特边缘功能 . . `env` SDK: 说吧

```typescript
import { AdminSDK } from "npm:@amaster.ai/admin-sdk";

export default async function (request: Request, env: Env): Promise<Response> {
  const admin = new AdminSDK({
    appId: env.appId,
    env: env.appEnv,
    serviceKey: env.vars["APP_SECRET"],
  });

  // 权限校验
  const { allow } = await admin.auth.checkPermission("user-uid", {
    resource: "page",
    action: "access",
  });
  if (!allow) return Response.json({ error: "Forbidden" }, { status: 403 });

  // 创建用户
  const user = await admin.users.create({
    email: "new@example.com",
    password: "Secure@123",
    displayName: "New User",
  });

  return Response.json({ user });
}
```

**参数映射**数字 :`env.appId` - 开口`env.appEnv` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这里是`env.vars["APP_SECRET"]` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}服务主题 BaseurL。

## 安装

```bash
pnpm add @amaster.ai/admin-sdk
# or
npm install @amaster.ai/admin-sdk
```

## 快速启动

```typescript
import { AdminSDK } from "@amaster.ai/admin-sdk";

const admin = new AdminSDK({
  baseURL: process.env.RUNTIME_URL || "http://localhost:3000",
  appId: process.env.APP_ID!,
  env: process.env.ENV || "dev",
  serviceKey: process.env.SERVICE_KEY, // Required for internal API calls
});

// Check if a user can access a resource
const result = await admin.auth.checkPermission("user-uid-here", {
  resource: "page",
  action: "access",
  resourceId: "dashboard",
});
if (!result.allow) throw new Error("Forbidden");

// Functional permission and data scope are separate. For model data,
// append rowFilter to the JSONQL query before reading or mutating rows.
// `scope === "none"` is represented by an always-false rowFilter.
const runtimeRowConstraint = result.rowFilter?.filter;

// Create a user
const user = await admin.users.create({
  email: "new@example.com",
  password: "Secure@123",
  displayName: "New User",
});

// Assign a role to the user (use uid, not numeric id)
await admin.roles.assign(roleId, {
  assigneeType: "user",
  assigneeUid: user.uid,
});
```

## 环境变量

| 变量 | 说明 | 示例 |
| --- | --- | --- |
| `RUNTIME_URL` | 运行时服务基地 URL | `http://runtime:3000` |
| `APP_ID` | 应用程序 ID (x- tenant- id) | `d9990247` |
| `ENV` | 环境(x-env) | `dev` | `prod` |
| `SERVICE_KEY` | 内部 API 认证的服务密钥 | (从Amaster控制台) |

## API 概览

### `admin.auth` ——权限检查(不需要用户令牌)

| 方法 | 说明 |
| --- | --- |
| `checkPermission(uid, { resource, action, resourceId? })` | 检查用户是否有权限 |
| `getRules(uid)` | 为用户获取完整的ACL规则( 角色+权限) |

```typescript
// Single permission check
const { allow, scope, resolved, rowFilter, roles, permissions } = await admin.auth.checkPermission(uid, {
  resource: "order",
  action: "read",
});

if (!allow) throw new Error("Forbidden");
// `own`, `dep`, `dep_and_sub`, `mixed`, and `none` all require the business
// data path to consume rowFilter. `none` contains an always-false condition.
const runtimeRowConstraint = rowFilter?.filter;

// Batch: fetch rules once, check locally
const rules = await admin.auth.getRules(uid);
const canExport = rules.permissions.some(
  (p) => p.resource === "report" && p.action === "export"
);
```

### `admin.users` ——用户 CRUD

| 方法 | 说明 |
| --- | --- |
| `list(params?)` | 列表用户( pageination, search) |
| `get(uid)` | 通过 UID 获取用户 |
| `create(params)` | 创建用户 |
| `update(uid, params)` | 更新用户 |
| `delete(uid)` | 删除用户 |

```typescript
const { list, total } = await admin.users.list({ query: "zhang", pageSize: 20 });
const user = await admin.users.get("abc-uid");
await admin.users.update(user.uid, { displayName: "New Name" });
```

### `admin.roles` 角色管理

| 方法 | 说明 |
| --- | --- |
| `list()` | 列出所有角色 |
| `get(id)` | 通过ID获取角色 |
| `create(params)` | 创建角色 |
| `update(id, params)` | 更新角色 |
| `delete(id)` | 删除角色( 仅非系统) |
| `assign(roleId, params)` | 指定用户/配置/团队的角色 |
| `unassign(roleId, params)` | 删除任务 |
| `listAssignees(roleId)` | 职责受让人名单 |
| `getUserRoles(uid)` | 获取指定给用户的角色 |

```typescript
// Prefer assigneeUid for users
await admin.roles.assign(roleId, {
  assigneeType: "user",
  assigneeUid: user.uid,
});

// For department/team/role, use assigneeId
await admin.roles.assign(roleId, {
  assigneeType: "department",
  assigneeId: 5,
});

const roles = await admin.roles.getUserRoles(user.uid);
```

### `admin.permissions` 授权定义和任务

| 方法 | 说明 |
| --- | --- |
| `list()` | 列出所有权限 |
| `create(params)` | 创建权限 |
| `update(id, params)` | 更新权限 |
| `delete(id)` | 删除权限 |
| `listForRole(roleId)` | 列出一个角色的权限 |
| `assignToRole(roleId, params)` | 指定角色权限 |
| `removeFromRole(roleId, permId)` | 从角色中删除权限 |
| `updateRolePermissionScope(...)` | 更新角色授权范围 |
| `assignToUser(uid, params)` | 直接用户权限(例外) |
| `removeFromUser(uid, permId)` | 删除用户权限 |
| `listForUser(uid)` | 列出用户权限例外 |
| `updateUserPermissionScope(...)` | 更新用户权限范围 |

```typescript
const perm = await admin.permissions.create({
  resource: "order",
  action: "export",
  name: "导出订单",
});

await admin.permissions.assignToRole(roleId, {
  permissionId: perm.id,
  scopeType: "dep",
});

// User-level override (bypasses role)
await admin.permissions.assignToUser(uid, {
  permissionId: perm.id,
  scopeType: "custom",
  scopeFilter: JSON.stringify({ id: [1, 2, 3] }),
});
```

### `admin.departments` 部门及成员

| 方法 | 说明 |
| --- | --- |
| `list()` | 列出所有部门 |
| `get(id)` | 联系部门 |
| `create(params)` | 创建部门 |
| `update(id, params)` | 更新部门 |
| `delete(id)` | 删除部门 |
| `listUsers(id, includeChildren?)` | 名单 部门成员 |
| `addUser(deptId, params)` | 向部门添加用户( 使用用户Uid) |
| `removeUser(deptId, userUid)` | 从部门删除用户 |

```typescript
const dept = await admin.departments.create({ name: "技术部", parentId: 1 });
await admin.departments.addUser(dept.id, {
  userUid: user.uid,
  position: "工程师",
  isPrimary: true,
});
await admin.departments.removeUser(dept.id, user.uid);
```

## Deno / 边缘函数

边缘功能 `npm:` 页:1 `env` 获取(QQEDGE 函数 QQ)。

## 标识符: UID vs 数字 ID

-   **用户编号** (弦等为. `"abc-123-def"`: 主要用户标识符. 用于 `users.get/update/delete`, (中文(简体) ), `roles.assign` (Assigneee Uid), (英语), `departments.addUser/removeUser`, (中文(简体) ), `auth.checkPermission`, (中文(简体) ), `permissions.assignToUser`。 。 。 .
-   **数字标识** (数字):数据库编号。 用于角色,权限,部门和角色指定者取景. API支持时优先使用UID.

## 类型(AI参考)

所有类型都从包中导出. 关键:

| 类型 | 使用大小写 |
| --- | --- |
| `AdminSDKOptions` | 构造选项 |
| `CheckPermissionParams`, (中文(简体) ), `CheckPermissionResult` | `auth.checkPermission` |
| `CreateUserParams`, (中文(简体) ), `CreateUserResult`, (中文(简体) ), `UserDetail` | 用户 CRUD |
| `RoleAssignParams`, (中文(简体) ), `Role` | 角色分配(使用) `assigneeUid` (供用户使用) |
| `AssignPermissionToRoleParams`, (中文(简体) ), `AssignPermissionToUserParams` | 权限指派 |
| `AddDepartmentMemberParams` | 部门成员(使用) `userUid`(中文(简体) ) |

```typescript
import type { AdminSDKOptions, CreateUserParams, RoleAssignParams } from "@amaster.ai/admin-sdk";
```

## 处理错误

```typescript
import { AdminSDK, AdminSDKError } from "@amaster.ai/admin-sdk";

try {
  await admin.users.get("invalid-uid");
} catch (err) {
  if (err instanceof AdminSDKError) {
    console.error(err.status, err.message); // 404, "user not found"
  }
}
```

## 许可证

麻省理工学院

### 将一个已有的用户预设为 WeCom

```ts
await admin.auth.bindUserOAuth(userUid, {
  provider: "wecom",
  providerUserId: "enterprise-member-userid",
});
```

只使用服务器 : `POST /api/internal/auth/users/{uid}/oauth-bindings` 与 环境范围服务密钥。边缘函数必须认证其呼叫器 并在调用前授权用户管理。 使用稳定的应用程序 UID, 不是数字数据库 ID 。 相同的约束是一意孤行的;冲突再起 409,永远不要移动一个身份。 失踪/残疾用户返回404人。 只有 WeCom 是 已支持。 使用来自预定企业的经核实的成员身份; 此操作 不获取 WeCom 联系信息或证明会员资格。 部署 在使用方法前匹配运行时端点.

## 常见问题

### @amaster\.ai/admin-sdk 是什么？

Amaster 平台的管理员 SDK — 服务器侧用户、角色、权限和org 管理

### 如何安装 @amaster\.ai/admin-sdk？

在项目目录运行 npm install @amaster\.ai/admin-sdk，或使用 pnpm add / yarn add / bun add。

### @amaster\.ai/admin-sdk 支持 TypeScript 吗？

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

### @amaster\.ai/admin-sdk 支持 ESM 还是 CommonJS？

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

### @amaster\.ai/admin-sdk 可以商用吗？

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

### @amaster\.ai/admin-sdk 的下载量有多少？

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

### @amaster\.ai/admin-sdk 还在维护吗？

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