# @astrale-domains/shell 中文文档

规范地址：https://npmcn.com/package/%40astrale-domains/shell/

版本：0\.2\.0
npm 元数据更新时间：2026-11-07T13:19:45.716Z
中文译文更新时间：2026-11-07T16:47:16.723Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：2.6 MB，430 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- peer 依赖：@astrale-os/sdk \>=0\.6\.0-beta\.60 \<1\.0\.0
- 首次发布：2026-08-21T21:38:59.234Z
- 最新版本发布：2026-11-07T13:19:45.520Z
- 近 30 天下载量：4514（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

Astrale Shell 域名计划和远程产品实施

## 安装

```sh
npm install @astrale-domains/shell
```

也可以使用：`pnpm add @astrale-domains/shell`、`yarn add @astrale-domains/shell`、`bun add @astrale-domains/shell`

## README

# 贝壳域

Shell拥有每个人的账户(`User`他们的团体`Group`)),其作用(包括:`Role`页:1 简介 `workspace.member` ⊂ `workspace.admin` 和原子 `user.reader`, (中文(简体) ), `user.writer`, (中文(简体) ), `group.reader`, (中文(简体) ), `group.writer`, (中文(简体) ), `directory.provisioner`),视图为没有配置文件的账户 陆地上的土地(`view_access`),实例命名空间及其别名,以及一个应用程序视图,其 进入点。 所有权威都来自克内尔角色,由克内尔直接或通过团体持有 `extends_with`;目录可能提供账户和组。 设计、其法律以及 修正案载于 [`docs/design/accounts-and-roles.md`](https://npmcn.com/package/%40astrale-domains/docs/design/accounts-and-roles.md)· ; 每一个法律的执行和测试 [`docs/accounts/laws.tsv`](https://npmcn.com/package/%40astrale-domains/docs/accounts/laws.tsv),每个 假设情况的证据 [`docs/accounts/scenarios.tsv`](https://npmcn.com/package/%40astrale-domains/docs/accounts/scenarios.tsv)。 。 。 .

角色前的模型保存在它的呼叫者 `legacy/` 文件夹,列于 [`legacy/LEDGER.md`](https://npmcn.com/package/%40astrale-domains/shell/legacy/LEDGER.md) 方法 [`docs/legacy.md`](https://npmcn.com/package/%40astrale-domains/docs/legacy.md); 内容 说明如下: [`docs/legacy/shell-domain-before-roles.md`](https://npmcn.com/package/%40astrale-domains/docs/legacy/shell-domain-before-roles.md)。 。 。 .

## 合同

| 方法 | 来电 | 获准 | 投入 | 产出 |
| --- | --- | --- | --- | --- |
| `User.create` | 静态 | `user.writer` | `{ email, name, givenName?, familyName?, attributes? }` | `{ user, created }` |
| `User.invite` | 静态 | `user.writer` | `{ user, profile?: 'member' | 'admin' }` | `{ invitationId, user, state }` |
| `User.update` | 账户 | `user.writer` | `{ name?, email?, givenName?, familyName?, icon?, attributes? }` | `{}` |
| `User.updateProfile` | 账户 | 持有者 | `{ name?, icon? }` | `{}` |
| `User.saveSettings` | 账户 | 账户本身 | `{ set?, unset? }` | `{ settings }` |
| `User.deactivate`, (中文(简体) ), `User.reactivate`, (中文(简体) ), `User.delete` | 账户 | `user.writer` | `{}` | `{}` |
| `User.provision` | 静态 | `directory.provisioner` | `{ directory, externalId, email, name, givenName?, familyName?, active }` | `{ user, created, adopted }` |
| `User.deprovision` | 静态 | `directory.provisioner` | `{ directory, externalId }` | `{}` |
| `Group.create` | 静态 | `group.writer` | `{ name, description?, icon?, attributes? }` | `{ group }` |
| `Group.update`, (中文(简体) ), `Group.delete` | 组合 | `group.writer` | `{ name?, description?, icon?, attributes? }`, (中文(简体) ), `{}` | `{}` |
| `Group.assignMember`, (中文(简体) ), `Group.unassignMember` | 静态 | `group.writer`, (中文(简体) ), `directory.provisioner` | `{ member, group }` (单位:千美元)`@NodeId` 路径) | `{}` |
| `Group.provision` | 静态 | `directory.provisioner` | `{ directory, externalId, name }` | `{ group, created }` |
| `Group.deprovision` | 静态 | `directory.provisioner` | `{ directory, externalId }` | `{}` |
| `disconnectDirectory` | 函数 | `directory.provisioner` | `{ directory }` | `{ users, groups }` |
| `WorkspaceSettings.save` | `/:shell.astrale.ai:core.settings` | `workspace.admin` | `{ set?, unset? }` | `{ settings }` |

拒绝(`reason.code`,家属: `USER_EMAIL_INVALID` (评价-错误); `USER_NOT_FOUND`, (中文(简体) ), `GROUP_NOT_FOUND` (NOT FOUND) (中文(简体) ); `USER_EMAIL_TAKEN`, (中文(简体) ), `USER_DIRECTORY_MANAGED`, (中文(简体) ), `USER_ADMINISTRATOR_PROTECTED`, (中文(简体) ), `USER_LAST_ADMINISTRATOR`, (中文(简体) ), `USER_ACTIVE`, (中文(简体) ), `USER_SUSPENDED`, (中文(简体) ), `PROFILE_NOT_HELD`, (中文(简体) ), `GROUP_DIRECTORY_MANAGED`, (中文(简体) ), `GROUP_NOT_DIRECTORY_MANAGED`, (中文(简体) ), `GROUP_ROLE_PROTECTED` (详细情况) `{ role }`, (中文(简体) ), `GROUP_MEMBERSHIP_CYCLE`, (中文(简体) ), `DIRECTORY_CONFLICT` (详细情况) `{ user }`, (中文(简体) ), `ACCOUNT_CHANGED`, (中文(简体) ), `GROUP_CHANGED` 成员 方法保存 `INVALID_GROUP_MEMBERSHIP_REFERENCE`, (中文(简体) ), `GROUP_MEMBERSHIP_ENDPOINTS_UNAVAILABLE`, (中文(简体) ), `GROUP_MEMBERSHIP_CONFLICT`, (中文(简体) ), `GROUP_MEMBERSHIP_UNCONFIRMED`,邀请 `INVITATION_CONFLICT`, (中文(简体) ), `INVITATION_REJECTED`设置方法 `SETTINGS_TOO_MANY`, (中文(简体) ), `SETTINGS_NAME_REPEATED` (评价-错误), `SETTINGS_NOT_FOUND` (NOT FOUND), (英语:, `SETTINGS_CHANGED` (冲突)。 SDK没有FORBIDDEN的家族: 一项禁止为了 账户的状况、一个集团或其打电话者回答CONFLICT.

用户和组声明不写规则:只有他们的方法来写,然后是Shell的授权 克内尔无法说明的法律(U1-U6,G2-G4). 需要账户的域询问 `user.writer` (和 `user.reader`在释放时, `requirements({ roles: [{ role: S.core.nodes['user.writer'], members: [requirements.domain] }] })`, (中文(简体) ), 将自己的记录与账户连接起来,并用自己的功能进行测试 `hasRole` 政策。 每个字都保留 `frozen` =: `suspended` 或者说 `directoryActive === false` (U2):该 Kernel拒绝验证一个被冻结的账户.

## 设置

设置是最多64个名字的 JSON 对象, 应用程序选择并验证 本身( GUI 存储) `dock`, (中文(简体) ), `wallpaper`, (中文(简体) ), `appearance`, (中文(简体) ), `locale`...):新设置不需要 壳放出. `UserSettings` 持有一个人的账户 `user_settings` 财务报告和审定财务报表 第一次更改时创建; 只有账户本身读和写它们, 没有角色读取另一个 被删除的账户. `WorkspaceSettings`一个核心节点 `/:shell.astrale.ai:core.settings`,持有工作空间的默认和定制:每个人 阅读它,管理员保存它。 更改合并到存储对象 : `set` 写名字, `unset` 脱去,在它读到的修订版上; 当另一个窗口先写时, Shell读到 并再次合并,所以两者都不消除.

## 邀请

`User.invite` 授予配置文件( e)`extends_with` 改为 `profile.<name>`),然后请管理员发送 通过壳牌公司的入学整合邀请,该整合包含 `{ user, email, profile, requestId, requestedBy }`:电子邮件是账户的自有. 它的提供人薄荷薄荷 一种有引用约束的果壳证明 为它配置的 HTTPS 入侵观众。 返回的待发邀请无法证明电子邮件 交货或完成登记。 管理员将已核实的电子邮件的第一个签名绑定到 账户(U8).

## 释放

`domain.ts` 宣布角色和范围. `workspace.admin` 每一贝壳作用和可给予的 Kernel 角色 (R2); 捆绑成员 QQ 管理员和原子角色 释放成员 (AM1); 成员持有核心 `writer`,管理核心 `admin`; 没有配置文件持有核心 `reader`,哪个管理员 凡只开放其见解者,均得享受它的报酬 内核 `authority.reader`, (中文(简体) ), `graph.reader` 财务报告和审定财务报表 `graph.writer`。安装它需要安装器 赋予它所约束的每一个角色:根.

## 查看访问

**给一个身份的视图决定它在哪里降落, 而不是它读的.** `view_access` 运行 从任何身份——一个账户,一个组,一个角色——到一个Kernel视图;每个端与它的 节点. 管理员用"变相"来写;管理员用"变相"来写;或边民的观众和成员用"变相"来读. 访客登陆是自己的查询(`@astrale-os/shell`: `workspace.member` 打开工作空间; 其他人读 内核 `reader`,它持有的意见.

## 命名空间和别名

**一个别名 一个节点。 它不给任何好处.** 名称最多指定一个节点 每个作者的命名空间 : `alias` 宣告内核密钥 `unique: [['source', 'slug']]` 联合国 所以Kernel拒绝在任何突变、壳牌或一种 管理员自己的 `mutate`。边缘身份每个命名空间最多有一个别名。 一个别名 是一个路径, `/:shell.astrale.ai:core.views~"shell.astrale.ai:class.alias"(roadmap)`,并达到 节点只供读者读取该节点. 它的目标终点接受任何节点,一个类舍 不拥有,所以其节点被删除时其别名会解去; Namespace stay.

核心命名空间 `views` 保存打开的名字 `/v/<name>`名称空间和别名声明 `read: true` 财务报告和审定财务报表 `traverse: true`:一个读者列出并沿用它可能读取的节点的别名, 对任何其他节点的别名并不存在。 贝壳,通过它的别名,边缘, 找到每个名字的节点,甚至一个它不读.

`link` 命名目标路径到达的任何节点, 无论域拥有它: 一个别名不给任何东西, 每个读者只看见其阅读的节点的别名。 仅提供节点 管理员认为是接口的礼貌, 而不是服务器的保证; 任何已学习的作者 从突变的定位器中找到路径是否达到节点.

| 方法 | 电话 | 拒绝 |
| --- | --- | --- |
| 链接 | 一次有壳牌权威的突变 其定位器解决了 `target` | `INVALID_NAME`, (中文(简体) ), `TARGET_NOT_FOUND`, (中文(简体) ), `NAME_TAKEN`, (中文(简体) ), `TARGET_ALREADY_ALIASED` |
| 取消链接 | 一个是用壳牌的威信读出别名Path,一个是突变 | `INVALID_NAME`, (中文(简体) ), `NAME_NOT_FOUND` |
| 重命名 | 相同; 将名称重命名为不写 | `INVALID_NAME`, (中文(简体) ), `NAME_NOT_FOUND`, (中文(简体) ), `NAME_TAKEN` |

名字是小写中的边缘弹道( Edge sults) (`INVALID_NAME`) (中文(简体) ). 这条规则是Shell的:一个管理员 写入 `mutate` 绕过它,从来没有键。 除了钥匙以外,没有什么能保护一个名字的独特性. `unlink` 财务报告和审定财务报表 `rename` 更改化名时,只保留他们读取的名字,所以 同时重命名答案 `NAME_NOT_FOUND` 而不是改变另一个名字。 贝壳映射克内尔 密封拒绝 :

| 内核拒绝变异 | 链接 | 取消链接 | 重命名 |
| --- | --- | --- | --- |
| `MUTATION_POST_STATE_INVALID`规则 `duplicate-key` | `NAME_TAKEN` | 宣传 | `NAME_TAKEN` |
| `MUTATION_PRECONDITION_FAILED` (别名"边缘"存在,已消失,或带有另一个名称) | `TARGET_ALREADY_ALIASED` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |
| `MUTATION_LOCATOR_INVALID` (目标路径达到节点,或目标被删除) | `TARGET_NOT_FOUND` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |

其他的失败都会蔓延. `workspace.admin` 持有者拨打三种方法并写入 `alias` 边由他们自己的突变.

## 版本数

域名的版本是 `version` 联 合 国 `domain/package.json`,请写出 也写到根上 `package.json`,项目,什么 `astrale-domain publish` 读取。 一个 数字名称 npm 软件包 `@astrale-domains/shell` 和登记册 `shell.astrale.ai@<version>`,所以一个实例按数字安装一个已出版的版本:

```sh
astrale domain install shell.astrale.ai@<version> -i <instance> --as <instance>-root
```

`shell.astrale.ai@<major>.<minor>` 安装该行最稳定版本. 域名 发布稳定版本,从0.1.1起;0.1.0起,首次出版,命名为0.1.0-β.51 释放.

## 来源和资格

每个声明,查询和突变都有自己的语义文件. 地层根是外层; 集成/提供者拥有外部效果、观点/ ui 拥有 目录表面。 运行时有一个默认导出并绑定每个处理器 . Dataset 由 root astrale.config.ts 懒得引用 .

域名作者从@astrale-domains/ shell 导入 Schema; 平台工人使用明文 /域和/运行时输出. 创建/登记、安装当局、邀请 交付,运行时间回放和浏览器渲染是单独的资质边界. 重新设计行政组成、公布登记册组和真正的邀请/创建 出行的路口仍然是出行出行的出行口;这一来源的README并不是这些出行口经过的证据.

### 出版边界

`@astrale-domains/shell` 是可执行的平台软件包,也是对普通软件的故意例外 域名出版产品. 它发布远程壳牌域定义和平台所需的运行时间 通过明确规定的工人部署 `./domain` 财务报告和审定财务报表 `./runtime` 子路径,而其根仍然 只有司马 因此,它的构建将明确的根源汇编为: `tsconfig.package.json` 并适用 壳牌公司所属的规范化和对发射平台关闭的检查。 仅源 `#` 化名为 重写到相对的联署材料和宣言参考文献,因此消费者路径绘图无法捕捉私人壳牌 类型。 Tarball 合格后核查出口的准确性、孤立的亚道、缺乏来源 地图,并仅使用公共 npm 依赖性安装.

一般情况 `astrale-domain package` 命令只保留Schema,只显示域根加 软件包元数据。 此 Shell 例外不得复制到普通产品域或用于 削弱SDK合同。 部署消费者必须使用明确可执行的子路径,从而连接 schema 导入无法通过 Shell 的私人应用程序或运行时间执行 .

源、包和确定性测试资格仍然有别于安装设备, 发布软件包、浏览器和现场证据。 Shell 不代理认证 符;标准域符交换由协议,服务器,和SDK所拥有.

## 常见问题

### @astrale-domains/shell 是什么？

Astrale Shell 域名计划和远程产品实施

### 如何安装 @astrale-domains/shell？

在项目目录运行 npm install @astrale-domains/shell，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@astrale-os/sdk（\>=0\.6\.0-beta\.60 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @astrale-domains/shell 支持 TypeScript 吗？

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

### @astrale-domains/shell 支持 ESM 还是 CommonJS？

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

### @astrale-domains/shell 需要什么版本的 Node\.js？

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

### @astrale-domains/shell 可以商用吗？

@astrale-domains/shell 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @astrale-domains/shell 的下载量有多少？

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

### @astrale-domains/shell 还在维护吗？

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