# @aalis/api-host-config 中文文档

规范地址：https://npmcn.com/package/%40aalis/api-host-config/

版本：0\.3\.0
npm 元数据更新时间：2026-10-31T01:45:52.809Z
中文译文更新时间：2026-11-08T06:21:29.480Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aalis/api-host-config
原文对照：https://npmcn.com/package/%40aalis/api-host-config/?lang=original
项目主页：https://github.com/AalisLabs/Aalis#readme
源码仓库：https://github.com/AalisLabs/Aalis

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

- 包体积（解压后）：26 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@aalis/core \>=0\.21\.0 \<1\.0\.0
- 首次发布：2026-09-26T22:10:08.217Z
- 最新版本发布：2026-10-31T01:45:52.651Z
- 近 30 天下载量：1879（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

\================================================================================================================================================================================================

## 安装

```sh
npm install @aalis/api-host-config
```

也可以使用：`pnpm add @aalis/api-host-config`、`yarn add @aalis/api-host-config`、`bun add @aalis/api-host-config`

## README

# @aalis/api-host-config

宿主配置文档契约：`host-config` 服务描述符、`HostConfig` 读写面与配置文档类型 `AalisConfig`。不含服务实现。

## 角色

-   `hostConfig`：服务描述符。Node 宿主 `@aalis/runtime` 把配置文档（`aalis.config.yaml`）以它独占登记在根上；别的宿主要让插件读写文档，自己提供。管理类插件（WebUI、市场、CLI、authority）在 `uses` 里声明它。
-   `HostConfig`：文档读写面加 `save()`。读写的是文档形态：schema 里 `secret: true` 的字段在文档里是引用 `{ $secret: '<键>' }`，值在宿主的密钥存储里，插件读原值用自己的 `config`。
    -   读法（`get`、`getAll`、`getPluginConfig`、`getServicePreferences`）返回复制品，写方法存的也是入参的复制品：之后改这些对象都不影响文档，要改经写方法写回。
    -   改插件配置用 `applyPluginConfig(instanceId, submitted)`：拆出密钥、更新运行态、写文档并落盘一步完成，返回 `{ status: 'refused' }` 或 `{ status: 'applied', reloaded, saveError? }`。
    -   `setPluginConfig` 只写文档，密钥字段上的非空明文抛错（宿主查得到 schema 时）。
    -   其余写方法只改文档；启停、服务偏好等管理动作只改运行态，要跨重启保留，调用方两边都写。
-   `ownHostConfig`：只读窄面，与 `hostConfig` 同一个服务名、描述符对象不同。`get()` 返回本实例在文档里那一段的复制品（没有这一段时为空对象），没有写方法。按会话读带标记字段（configSchema 顶层写了 `session` 的字段）的插件在 `uses` 里声明它，不声明整份 `hostConfig`。它只供消费，不能拿去 provide。
-   `'host-config:changed'` 事件：宿主配置文档在内存里确实被改了时由宿主发，参数是 `HostConfigChange`（只改了一个实例的配置段时为 `{ instanceId }`，其余为 `{ document: true }`）。写入相同的值、启停、配置文件解析失败都不发；不表示已落盘，也不保证恰好一次。
-   `AalisConfig`：配置文档类型，也是各域业务字段做 declaration merging 的目标。
-   `ConfigSaveRefusedError` / `isConfigSaveRefused(err)`：配置源有尚未生效的外部修改、宿主为免覆盖而拒写时 `save()` 的拒绝原因，以及用来把它与写入失败区分的判据。判据按错误的 `name` 判定，进程里装有两份本包时也认得。
-   `saveFailureText(err, reconcile)`：落盘失败的那一句（文字对象）。拒写说已在运行态生效、未写入配置文件，并按 `reconcile`（`'reload'` 或 `'restart'`）说之后怎样与文件对齐；其余失败说写入失败、改动保留在文档里。

## 安装

```bash
pnpm add @aalis/api-host-config
```

## 使用

```ts
import { optional } from '@aalis/core';
import { hostConfig } from '@aalis/api-host-config';

// uses: { plugins: pluginsService, doc: optional(hostConfig) }
if ((await plugins.use.disable(id)) && doc.present) {
  doc.use.setPluginEnabled(id, false);
  await doc.use.save();
}
```

扩展文档字段：

```ts
declare module '@aalis/api-host-config' {
  interface AalisConfig {
    myFeature?: { enabled: boolean };
  }
}
```

## 常见问题

### @aalis/api-host-config 是什么？

================================================================================================================================================================================================

### 如何安装 @aalis/api-host-config？

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

### @aalis/api-host-config 支持 TypeScript 吗？

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

### @aalis/api-host-config 支持 ESM 还是 CommonJS？

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

### @aalis/api-host-config 可以商用吗？

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

### @aalis/api-host-config 的下载量有多少？

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

### @aalis/api-host-config 还在维护吗？

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