docs: translate remaining non-README documentation

This commit is contained in:
Tianyi Cui
2026-07-26 02:33:29 +08:00
parent 5f04c92f15
commit 30db52fa4b
102 changed files with 3859 additions and 82 deletions

View File

@@ -0,0 +1,84 @@
# 5. 配置
[English](05-config.md) | 中文
每个 `cordis.yml` 配置项都可以携带 `config` 块,插件则声明一个 schema在运行 `apply` 前验证该块。错误配置会导致加载失败,并给出准确的错误:插件绝不会在配置不完整时启动。
## 可配置插件
创建 `config-demo.ts`,并将其放在 `tmp/cordis-tutorial` 中:
```ts
import type { Context } from 'cordis'
import Schema from 'schemastery'
export const name = 'config-demo'
export interface Config {
greeting: string
targets: string[]
}
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Hello'),
targets: Schema.array(String).default(['world']),
})
export function apply(ctx: Context, config: Config) {
for (const target of config.targets) {
console.log(`${config.greeting}, ${target}!`)
}
}
```
导出的 `Config` 既是 TypeScript 接口,也是同名的运行时 schema消费方获得类型Cordis 获得验证器。本仓库使用 [Schemastery](https://github.com/shigma/schemastery) 定义 schemaCordis 本身接受任意 [Standard Schema](https://standardschema.dev/) 验证器,因此将普通对象导出为 `Config` 无法工作。
对其进行配置:
```yaml
- name: './config-demo.ts'
config:
targets: ['alpha', 'beta']
```
运行:
```
Hello, alpha!
Hello, beta!
```
未提供 `greeting`,因此 schema 默认值会将其补齐:`apply` 始终会收到完整且经过验证的配置。
## 明确报错
现在向它传入无效内容:
```yaml
- name: './config-demo.ts'
config:
targets: 'not-an-array'
```
```
ValidationError: invalid config:
- $.targets expected array but got not-an-array (at targets)
```
插件的 fiber 进入 FAILED 状态,本教程的启动器打印错误后以状态码 1 退出。如果某个插件的 schema 有效配置命名了不可用的资源或提供方,该插件也应当在能解析该引用时立即拒绝。
## 计算得到的配置值
本仓库使用的 loader 支持 `!!js` 标签,用于必须在加载时计算的配置值,例如从环境中读取 API key
```yaml
- name: '@deepseek-ai/dsh-llm-deepseek'
config:
apiKey: !!js process.env.DEEPSEEK_API_KEY
```
`!!js` **仅在 `config` 内有效**。配置项元数据(`name``id``disabled``inject` 等)是静态的;`disabled: !!js ...` 会生成一个真值表达式对象,始终禁用该配置项。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
下一章:[组合与 HMR](06-composition-and-hmr.md):将 `cordis.yml` 视为应用。
[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)