diff --git a/packages/shell/shell-env/README.i18n.yaml b/packages/shell/shell-env/README.i18n.yaml index 63f09470f2..eac66fcb65 100644 --- a/packages/shell/shell-env/README.i18n.yaml +++ b/packages/shell/shell-env/README.i18n.yaml @@ -21,8 +21,8 @@ en: bab0b75fb967d41a zh: 8f636d9965d01ad1 /deepseek-ai-dsh-shell-env/use-this-package/adding-your-own-environment-facts: - en: 21ef223626e35905 - zh: 5c468055099b0135 + en: 14da34f853d089be + zh: 5ad3942aa5321893 /deepseek-ai-dsh-shell-env/use-this-package/choosing-the-harness-home: en: 0041438f2b7f7e4f zh: 93fa165b07adcdf4 diff --git a/packages/shell/shell-env/README.md b/packages/shell/shell-env/README.md index c2507b3c7c..86037caffe 100644 --- a/packages/shell/shell-env/README.md +++ b/packages/shell/shell-env/README.md @@ -50,7 +50,7 @@ export function apply(ctx: Context): void { } ``` -Contributors must declare every key they return; returning an undeclared or non-string value fails the call. Registration is disposed with the registering plugin, so hot-reloading a plugin removes its facts. +Contributors must declare every key they return; returning an undeclared or non-string value fails the call with `ShellEnvError` (`SHELL_ENV_CONTRIBUTION_INVALID`). Registration is disposed with the registering plugin, so hot-reloading a plugin removes its facts. ### Choosing the Harness home diff --git a/packages/shell/shell-env/README.zh.md b/packages/shell/shell-env/README.zh.md index 8860c11b54..a3d4a98516 100644 --- a/packages/shell/shell-env/README.zh.md +++ b/packages/shell/shell-env/README.zh.md @@ -50,7 +50,7 @@ export function apply(ctx: Context): void { } ``` -contributor 必须声明它返回的每个键;返回未声明或非字符串的值会让该次调用失败。注册随注册插件的释放而释放,因此热重载插件会移除它的事实。 +contributor 必须声明它返回的每个键;返回未声明或非字符串的值会让该次调用以 `ShellEnvError`(`SHELL_ENV_CONTRIBUTION_INVALID`)失败。注册随注册插件的释放而释放,因此热重载插件会移除它的事实。 ### 选择 Harness 主目录 diff --git a/packages/shell/shell-env/package.json b/packages/shell/shell-env/package.json index 4fb761f034..4fb7d7de4f 100644 --- a/packages/shell/shell-env/package.json +++ b/packages/shell/shell-env/package.json @@ -36,7 +36,8 @@ "@deepseek-ai/dsh-app-boot": "workspace:*", "@deepseek-ai/dsh-home-paths": "workspace:*", "@deepseek-ai/dsh-shell": "workspace:*", - "@deepseek-ai/dsh-tools": "workspace:*" + "@deepseek-ai/dsh-tools": "workspace:*", + "@deepseek-ai/dsh-llm": "workspace:*" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:~" diff --git a/packages/shell/shell-env/src/index.ts b/packages/shell/shell-env/src/index.ts index d53a393a8d..aa3012e2b4 100644 --- a/packages/shell/shell-env/src/index.ts +++ b/packages/shell/shell-env/src/index.ts @@ -14,6 +14,7 @@ import z from '@deepseek-ai/schemastery' import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell' import type { DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-shell' import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-home-paths' +import { HarnessError } from '@deepseek-ai/dsh-llm' import type { ToolExecution } from '@deepseek-ai/dsh-tools' // Declares `Context.profileContext`, the launcher-provided profile the built-ins read. import type {} from '@deepseek-ai/dsh-app-boot' @@ -24,6 +25,31 @@ declare module '@deepseek-ai/cordis' { } } +/** + * Every {@link ShellEnvError} code: + * - `SHELL_ENV_CONTRIBUTION_INVALID` — a registered contributor returned an undeclared key or a non-string value; the + * shell command does not run, and the contributing plugin must be fixed. + */ +export const SHELL_ENV_ERROR_CODES = ['SHELL_ENV_CONTRIBUTION_INVALID'] as const + +/** One code from {@link SHELL_ENV_ERROR_CODES}. */ +export type ShellEnvErrorCode = typeof SHELL_ENV_ERROR_CODES[number] + +/** Shell environment failure carrying a stable {@link ShellEnvErrorCode}. */ +export class ShellEnvError extends HarnessError { + override readonly code: ShellEnvErrorCode + + /** + * @param message - names the contributor and the offending key. + * @param code - the failure class consumers route on. + */ + constructor(message: string, code: ShellEnvErrorCode) { + super(message, code) + this.name = 'ShellEnvError' + this.code = code + } +} + export const name = 'shell-env' export const inject: string[] = [] @@ -182,10 +208,13 @@ export class ShellEnvRegistry extends Service { for (const [rawKey, value] of Object.entries(resolved)) { const key = rawKey as DshEnvironmentKey if (!Object.hasOwn(contributor.variables, key)) { - throw new Error(`bash env contributor "${contributor.name}" returned undeclared key "${key}"`) + throw new ShellEnvError(`bash env contributor "${contributor.name}" returned undeclared key "${key}"`, 'SHELL_ENV_CONTRIBUTION_INVALID') } if (typeof value !== 'string') { - throw new Error(`bash env contributor "${contributor.name}" returned a non-string value for "${key}"`) + throw new ShellEnvError( + `bash env contributor "${contributor.name}" returned a non-string value for "${key}"`, + 'SHELL_ENV_CONTRIBUTION_INVALID', + ) } values[key] = value } diff --git a/packages/shell/shell-env/tests/shell-env.spec.ts b/packages/shell/shell-env/tests/shell-env.spec.ts index e14d41b06c..74590aa42e 100644 --- a/packages/shell/shell-env/tests/shell-env.spec.ts +++ b/packages/shell/shell-env/tests/shell-env.spec.ts @@ -192,6 +192,7 @@ describe('ShellEnvRegistry', () => { }) expect(() => registry.collect(execution())).toThrow(/drifted-provider.*DSH_UNDECLARED/) + expect(() => registry.collect(execution())).toThrow(expect.objectContaining({ name: 'ShellEnvError', code: 'SHELL_ENV_CONTRIBUTION_INVALID' })) }) it('rejects non-string values returned by a contributor', () => { @@ -203,6 +204,7 @@ describe('ShellEnvRegistry', () => { }) expect(() => registry.collect(execution())).toThrow(/wrong-value-type.*non-string.*DSH_STRING/) + expect(() => registry.collect(execution())).toThrow(expect.objectContaining({ name: 'ShellEnvError', code: 'SHELL_ENV_CONTRIBUTION_INVALID' })) }) it('removes an effect-scoped contributor when its plugin is disposed', async () => { diff --git a/packages/shell/shell-env/tsconfig.json b/packages/shell/shell-env/tsconfig.json index fc6a34b571..ae66c37da9 100644 --- a/packages/shell/shell-env/tsconfig.json +++ b/packages/shell/shell-env/tsconfig.json @@ -28,6 +28,9 @@ }, { "path": "../../boot/app-boot" + }, + { + "path": "../../llm/llm" } ] }