Merge origin/master into worktree/retire-fixmes-20260807

2026-08-08 00:49:58 +08:00
parent a8a12ffc23 a29a0a4773
commit 3d1e4d31e1
160 changed files with 2174 additions and 957 deletions
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -426,7 +426,7 @@ Source: [`packages/compact/compact-tool-result-prune/src/types.ts:4`](../package
 ```ts config-catalog
 /** Plugin config: file location and hot-reload behavior. */
 export interface Config {
-  /** Credentials document path; defaults to `.env` under the harness home. */
+  /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
  path?: string
  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
  dshHome?: string
@@ -437,7 +437,7 @@ export interface Config {
 }
 ```

-Source: [`packages/credentials/credentials-local/src/index.ts:26`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)

 ## `@deepseek-ai/dsh-frontend-static`

@@ -679,17 +679,9 @@ Requires: `llm`
 * reasoning effort resolves to `high`.
 */
 export interface Config {
-  /**
-   * Trimmed literal API key; whitespace-only is absent, so it resolves through
-   * {@link apiKeyEnv} like an omitted one. Prefer {@link apiKeyEnv} to keep
-   * secrets out of configuration files. {@link resolveAdapterOptions} also
-   * format-checks what remains: a value no HTTP header can carry fails there
-   * rather than inside `fetch`.
-   */
-  apiKey?: string
  /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
  apiKeyEnv?: string
-  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
+  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
  baseURL?: string
  /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
  thinking?: 'enabled' | 'disabled'
@@ -724,7 +716,7 @@ export interface DeepSeekCatalogModel {

 Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)

-Source: [`packages/llm/llm-deepseek/src/index.ts:60`](../packages/llm/llm-deepseek/src/index.ts)
+Source: [`packages/llm/llm-deepseek/src/index.ts:61`](../packages/llm/llm-deepseek/src/index.ts)

 ## `@deepseek-ai/dsh-llm-pi-ai`

@@ -743,12 +735,6 @@ export interface Config {

 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
-  /**
-   * Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its
-   * provider-native ambient discovery. Trimmed and format-checked by {@link resolveProfiles}; a
-   * value no HTTP header can carry fails there rather than inside `fetch`.
-   */
-  apiKey?: string
  /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
  apiKeyEnv?: string
  /** Name shown by configuration surfaces; defaults to the route key. */
@@ -819,7 +805,7 @@ export interface PiAiModelProfile {

 Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)

-Source: [`packages/llm/llm-pi-ai/src/config.ts:126`](../packages/llm/llm-pi-ai/src/config.ts)
+Source: [`packages/llm/llm-pi-ai/src/config.ts:120`](../packages/llm/llm-pi-ai/src/config.ts)

 ## `@deepseek-ai/dsh-llm-replay`

@@ -2413,7 +2399,7 @@ export interface Config {
 }
 ```

-Source: [`packages/web/web-search-deepseek/src/index.ts:43`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:44`](../packages/web/web-search-deepseek/src/index.ts)

 ## `@deepseek-ai/dsh-web-search-exa`

@@ -2435,7 +2421,7 @@ export interface Config {
 }
 ```

-Source: [`packages/web/web-search-exa/src/index.ts:37`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)

 ## `@deepseek-ai/dsh-web-search-perplexity`

@@ -2457,7 +2443,7 @@ export interface Config {
 }
 ```

-Source: [`packages/web/web-search-perplexity/src/index.ts:31`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)

 ## `@deepseek-ai/dsh-workflow-workerthread`

@@ -2604,6 +2590,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
+- `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
 - `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
--- a/docs/cordis-tutorial/05-config.i18n.yaml
+++ b/docs/cordis-tutorial/05-config.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/05-config.md
-05-config.md: fc19add239636fa9e7071d9c77e48595caec1f08
-05-config.zh.md: 0c8170f518f0c87ab5c754606436496a4ff9d51e
+05-config.md: 8d4043e33a58fc425d82d9846ff82473bcdef4c1
+05-config.zh.md: e9463bd34e9c72dbae7b1ceb9907e35edf7b773b
--- a/docs/cordis-tutorial/05-config.md
+++ b/docs/cordis-tutorial/05-config.md
@@ -69,12 +69,12 @@ The plugin's fiber goes to FAILED, and this tutorial's launcher exits with statu

 ## Computed config values

-The loader used in this repo supports a `!!js` tag for config values that must be computed at load time, such as reading an API key from the environment:
+The loader used in this repo supports a `!!js` tag for config values that must be computed at load time:

 ```yaml
- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: './config-demo.ts'
  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
 ```

 `!!js` works **only inside `config`**. Entry metadata (`name`, `id`, `disabled`, `inject`, ...) is static; `disabled: !!js ...` produces a truthy expression object that always disables the entry. See [loader configuration](../cordis-primer.md#loader-configuration).
--- a/docs/cordis-tutorial/05-config.zh.md
+++ b/docs/cordis-tutorial/05-config.zh.md
@@ -69,12 +69,12 @@ ValidationError: invalid config:

 ## 计算得到的配置值

-本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值，例如从环境中读取 API key：
+本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值：

 ```yaml
- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: './config-demo.ts'
  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
 ```

 `!!js` **仅在 `config` 内有效**。Cordis 配置项的元数据（`name`、`id`、`disabled`、`inject` 等）是静态的；`disabled: !!js ...` 会生成一个真值表达式对象，始终禁用该 Cordis 配置项。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
--- a/docs/core-data-structures/credentials.i18n.yaml
+++ b/docs/core-data-structures/credentials.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/credentials.md
-credentials.md: 3f6fcd127d01e2c49e17c70c002bebe9f363e951
-credentials.zh.md: b5d2d9e164a85ce090790635c438b768cae4c9ca
+credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
+credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
--- a/docs/core-data-structures/credentials.md
+++ b/docs/core-data-structures/credentials.md
@@ -24,7 +24,7 @@ type CredentialRef = Branded<'CredentialRef'>
 interface ResolvedCredential {
  /** The non-empty secret value. */
  value: string
-  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
  source: string
 }
 ```
--- a/docs/core-data-structures/credentials.zh.md
+++ b/docs/core-data-structures/credentials.zh.md
@@ -24,7 +24,7 @@ type CredentialRef = Branded<'CredentialRef'>
 interface ResolvedCredential {
  /** The non-empty secret value. */
  value: string
-  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
  source: string
 }
 ```
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -10,6 +10,7 @@ flowchart TD
  subgraph group_util["packages/util"]
    pkg_atomic_write["atomic-write"]
    pkg_brand["brand"]
+    pkg_environment["environment"]
    pkg_native_command["native-command"]
    pkg_paths["paths"]
    pkg_retention["retention"]
@@ -292,6 +293,7 @@ flowchart TD
  end
  pkg_atomic_write --> pkg_invariants
  pkg_brand --> pkg_invariants
+  pkg_environment --> pkg_invariants
  pkg_native_command --> pkg_invariants
  pkg_paths --> pkg_invariants
  pkg_retention --> pkg_invariants
@@ -350,11 +352,13 @@ flowchart TD
  pkg_typert_loader --> pkg_invariants
  pkg_typert_loader --> pkg_typert_registry
  pkg_llm_deepseek --> pkg_credentials
+  pkg_llm_deepseek --> pkg_environment
  pkg_llm_deepseek --> pkg_invariants
  pkg_llm_deepseek --> pkg_llm
  pkg_llm_deepseek --> pkg_settings
  pkg_llm_deepseek --> pkg_timeout
  pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_environment
  pkg_llm_pi_ai --> pkg_invariants
  pkg_llm_pi_ai --> pkg_llm
  pkg_llm_pi_ai --> pkg_settings
@@ -374,6 +378,7 @@ flowchart TD
  pkg_api_gateway --> pkg_typert_registry
  pkg_credentials_local --> pkg_atomic_write
  pkg_credentials_local --> pkg_credentials
+  pkg_credentials_local --> pkg_environment
  pkg_credentials_local --> pkg_invariants
  pkg_credentials_local --> pkg_paths
  pkg_lsp --> pkg_brand
@@ -404,8 +409,10 @@ flowchart TD
  pkg_web_fetch_local --> pkg_invariants
  pkg_web_fetch_local --> pkg_timeout
  pkg_web_fetch_local --> pkg_web
+  pkg_web_search_exa --> pkg_environment
  pkg_web_search_exa --> pkg_invariants
  pkg_web_search_exa --> pkg_web
+  pkg_web_search_perplexity --> pkg_environment
  pkg_web_search_perplexity --> pkg_invariants
  pkg_web_search_perplexity --> pkg_web
  pkg_spill --> pkg_brand
@@ -418,6 +425,7 @@ flowchart TD
  pkg_llm_replay --> pkg_invariants
  pkg_llm_replay --> pkg_llm
  pkg_llm_replay --> pkg_session
+  pkg_app_boot --> pkg_environment
  pkg_app_boot --> pkg_invariants
  pkg_app_boot --> pkg_paths
  pkg_app_boot --> pkg_system_prompt
@@ -472,6 +480,7 @@ flowchart TD
  pkg_skill_local --> pkg_skill
  pkg_web_search_deepseek --> pkg_agent
  pkg_web_search_deepseek --> pkg_credentials
+  pkg_web_search_deepseek --> pkg_environment
  pkg_web_search_deepseek --> pkg_invariants
  pkg_web_search_deepseek --> pkg_session
  pkg_web_search_deepseek --> pkg_web
@@ -1151,6 +1160,7 @@ flowchart TD
 | [`invariants`](../packages/support/invariants) | `support` | — |
 | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/support/invariants) |
 | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/support/invariants) |
+| [`environment`](../packages/util/environment) | `util` | [`invariants`](../packages/support/invariants) |
 | [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/support/invariants) |
 | [`paths`](../packages/util/paths) | `util` | [`invariants`](../packages/support/invariants) |
 | [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
@@ -1190,13 +1200,13 @@ flowchart TD
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
-| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
-| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
@@ -1205,12 +1215,12 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
-| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
-| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
@@ -1223,7 +1233,7 @@ flowchart TD
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`skill`](../packages/skill/skill) |
-| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/config.md
-config.md: 0f1a99ed0afdab13d052ae2714fc2e1718d3d85e
-config.zh.md: 74e14e4e6e1fbb38a7a8d5167a4747080a662128
+config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
+config.zh.md: ce965dfc67c759ffcbad7b044b74abb2025851c2
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -18,10 +18,6 @@ A minimal configuration is a list of plugin entries:
 ```yaml
 - id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models:
-      - deepseek-v4-flash

 - id: bash
  name: '@deepseek-ai/dsh-bash-local'
@@ -53,15 +49,14 @@ Cordis starts sibling entries concurrently. A plugin declares required services

 `dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, then each `--patch <path>` overlay, then CLI-flag patches. Later layers win per row.

-A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
+A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKeyEnv` and `baseURL`, so restate every key the row must retain.

 ## JavaScript values and environment variables

-The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
+The Cordis loader evaluates runtime expressions tagged with `!!js` for non-secret runtime values. Bundled LLM adapters carry credential references such as `apiKeyEnv`; the value belongs in an environment layer or `$DSH_HOME/.credentials.yaml`, not Cordis configuration.

 ```yaml
 config:
-  apiKey: !!js process.env.DEEPSEEK_API_KEY
  cwd: !!js process.cwd()
 ```

--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -18,10 +18,6 @@ Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及
 ```yaml
 - id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models:
-      - deepseek-v4-flash

 - id: bash
  name: '@deepseek-ai/dsh-bash-local'
@@ -53,15 +49,14 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务

 `dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。

-补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
+补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。

 ## JavaScript 值和环境变量

-Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。
+Cordis loader 会求值以 `!!js` 标记的运行时表达式，用于非机密的运行时值。仓库内置的 LLM（大语言模型）适配器携带 `apiKeyEnv` 等凭据引用；对应的值应放在环境层或 `$DSH_HOME/.credentials.yaml`，而不是 Cordis 配置中。

 ```yaml
 config:
-  apiKey: !!js process.env.DEEPSEEK_API_KEY
  cwd: !!js process.cwd()
 ```

--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/index.md
-index.md: 4bb9f2e0056792a160877515f142eb36d4f680ac
-index.zh.md: 2792547a146b5ca6186bcb69c1c026744e80b326
+index.md: ede09506a996193fe5cf4ae6cd9b64d3529798a6
+index.zh.md: 5f72a6d3099d2d4721eccebae92eacfe72d33bce
--- a/docs/user/guide/index.md
+++ b/docs/user/guide/index.md
@@ -11,8 +11,6 @@ Harness implements every capability an AI agent needs—including LLM calls, too
 ```yaml
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY

 # Select the one-shot application
 - id: cli-agent
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -11,8 +11,6 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
 ```yaml
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY

 # Select the one-shot application
 - id: cli-agent
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
-providers.md: 5234f5bb03755c11652eb23f3c5d677fa3cddb40
-providers.zh.md: a54819cab8524a6007c335ad70cecd6516bba25b
+providers.md: 5fd11f3753468f9eccd318045b1ac5f6b3a21622
+providers.zh.md: 3e71e3fb2c64fb71fed196433175c860d3f6c817
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -31,7 +31,7 @@ That holds for providers that authenticate with an API key. The catalog also car

 **Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.

-Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.env`, and the profile records only the variable name that references it.
+Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.credentials.yaml`, and the profile records only the variable name that references it.

 ## settings.yaml for advanced configuration

@@ -89,9 +89,9 @@ Model ids are not lifecycle configuration. Requesting a model the route does not

 ## Credentials

-Prefer `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. A literal `apiKey` is the escape hatch. Omitting both is what leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold.
+Use `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. Omitting it leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold.

-References resolve from `$DSH_HOME/.env` — what the Models page's key fields write — and from the matching environment variable when no credential service is mounted. One credential serves every model on its route.
+Under `dsh`, references resolve from the inherited environment, the Models page's `$DSH_HOME/.credentials.yaml` store, the invoking directory's `.env`, then `$DSH_HOME/.env`. Without a credential service, a reference reads only the matching environment variable. One credential serves every model on its route.

 ## Point an agent at the new provider

--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -31,7 +31,7 @@ Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配

 **让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。

-密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.env`，profile 里只记录引用它的变量名。
+密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.credentials.yaml`，profile 里只记录引用它的变量名。

 ## settings.yaml：进阶配置

@@ -89,9 +89,9 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上

 ## 凭据

-优先用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件；`apiKey` 字面量是应急出口。两者都不给，才表示这个路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。
+使用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件。省略它会让路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。

-引用解析自 `$DSH_HOME/.env`（模型页的密钥输入框写的就是它），没有挂载凭据服务时则直接读同名环境变量。一份凭据供该路由上的所有模型使用。
+在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。

 ## 让 agent 用上新提供方