@codesoul-co/hypha-core / contracts/sandbox-provider
模块用法
用于声明并运行时校验契约。Sandbox provider 模块公开 6 接口、3 类型。
从包入口导入
ts
import type {
SandboxCapabilityDerivationInput,
SandboxCapabilityNegotiationRequest,
SandboxCapabilityNegotiationResult,
SandboxCapabilityRequirement,
SandboxProvider,
SandboxProviderFactory,
SandboxCapabilityName,
SandboxProviderSelection,
} from '@codesoul-co/hypha-core';
// 完整导出列表见下方。使用要点
- 9 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用
import type，运行时不应依赖它们。
公共导出
| Symbol | 种类 | 签名 | 说明 |
|---|---|---|---|
SandboxCapabilityDerivationInput | 接口 | interface SandboxCapabilityDerivationInput | Sandbox Capability Derivation Input 接口，共包含 3 个公开字段或方法。 |
SandboxCapabilityNegotiationRequest | 接口 | interface SandboxCapabilityNegotiationRequest | Sandbox Capability Negotiation Request 接口，共包含 4 个公开字段或方法。 |
SandboxCapabilityNegotiationResult | 接口 | interface SandboxCapabilityNegotiationResult | Sandbox Capability Negotiation Result 接口，共包含 6 个公开字段或方法。 |
SandboxCapabilityRequirement | 接口 | interface SandboxCapabilityRequirement | Sandbox Capability Requirement 接口，共包含 3 个公开字段或方法。 |
SandboxProvider | 接口 | interface SandboxProvider | Sandbox Provider 接口，共包含 11 个公开字段或方法。 |
SandboxProviderFactory | 接口 | interface SandboxProviderFactory | Composition-root contract for constructing a configured SandboxProvider. Concrete adapters own their options; core only knows the provider type and stable id. |
SandboxCapabilityName | 类型 | type SandboxCapabilityName = keyof SandboxProviderCapabilities | Sandbox Capability Name 公共类型别名；完整类型表达式见声明。 |
SandboxProviderSelection | 类型 | type SandboxProviderSelection = Pick<ExecutionEnvironmentSpec, 'provider' | 'providerRef'> | Sandbox Provider Selection 公共类型别名；完整类型表达式见声明。 |
SandboxProviderType | 类型 | type SandboxProviderType = ExecutionEnvironmentSpec['provider'] | Sandbox Provider Type 公共类型别名；完整类型表达式见声明。 |
SandboxCapabilityDerivationInput
Sandbox Capability Derivation Input 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { SandboxCapabilityDerivationInput } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxCapabilityDerivationInput {
environment: ExecutionEnvironmentSpec;
command?: Pick<CommandExecutionRequest, 'snapshotBefore' | 'snapshotAfter' | 'snapshotOnFailure'>;
additionalRequirements?: SandboxCapabilityRequirement[];
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
additionalRequirements | 属性 | additionalRequirements?: SandboxCapabilityRequirement[] | 公开属性；类型、只读和可选状态以签名列为准。 |
command | 属性 | command?: Pick<CommandExecutionRequest, "snapshotBefore" | "snapshotAfter" | "snapshotOnFailure"> | 公开属性；类型、只读和可选状态以签名列为准。 |
environment | 属性 | environment: ExecutionEnvironmentSpec | 公开属性；类型、只读和可选状态以签名列为准。 |
SandboxCapabilityNegotiationRequest
Sandbox Capability Negotiation Request 接口，共包含 4 个公开字段或方法。
- 种类: 接口
- 导入:
import type { SandboxCapabilityNegotiationRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxCapabilityNegotiationRequest {
providerId: string;
capabilities: SandboxProviderCapabilities;
requirements: SandboxCapabilityRequirement[];
evaluatedAt: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
capabilities | 属性 | capabilities: SandboxProviderCapabilities | 公开属性；类型、只读和可选状态以签名列为准。 |
evaluatedAt | 属性 | evaluatedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
requirements | 属性 | requirements: SandboxCapabilityRequirement[] | 公开属性；类型、只读和可选状态以签名列为准。 |
SandboxCapabilityNegotiationResult
Sandbox Capability Negotiation Result 接口，共包含 6 个公开字段或方法。
- 种类: 接口
- 导入:
import type { SandboxCapabilityNegotiationResult } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxCapabilityNegotiationResult {
providerId: string;
compatible: boolean;
capabilities: SandboxProviderCapabilities;
requirements: SandboxCapabilityRequirement[];
missingCapabilities: SandboxCapabilityName[];
evaluatedAt: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
capabilities | 属性 | capabilities: SandboxProviderCapabilities | 公开属性；类型、只读和可选状态以签名列为准。 |
compatible | 属性 | compatible: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
evaluatedAt | 属性 | evaluatedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
missingCapabilities | 属性 | missingCapabilities: (keyof SandboxProviderCapabilities)[] | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
requirements | 属性 | requirements: SandboxCapabilityRequirement[] | 公开属性；类型、只读和可选状态以签名列为准。 |
SandboxCapabilityRequirement
Sandbox Capability Requirement 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { SandboxCapabilityRequirement } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxCapabilityRequirement {
capability: SandboxCapabilityName;
source: 'environment' | 'command' | 'policy' | 'runtime';
reason: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
capability | 属性 | capability: keyof SandboxProviderCapabilities | 公开属性；类型、只读和可选状态以签名列为准。 |
reason | 属性 | reason: string | 公开属性；类型、只读和可选状态以签名列为准。 |
source | 属性 | source: "policy" | "environment" | "command" | "runtime" | 公开属性；类型、只读和可选状态以签名列为准。 |
SandboxProvider
Sandbox Provider 接口，共包含 11 个公开字段或方法。
- 种类: 接口
- 导入:
import type { SandboxProvider } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxProvider {
readonly id: string;
capabilities(): Promise<SandboxProviderCapabilities>;
create(request: SandboxCreateRequest): Promise<SandboxRecord>;
start(request: SandboxStartRequest): Promise<SandboxRecord>;
execute(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
cancel(request: ExecutionCancelRequest): Promise<void>;
terminate(request: SandboxTerminateRequest): Promise<void>;
status(request: SandboxStatusRequest): Promise<SandboxRecord | null>;
cleanup(request: SandboxCleanupRequest): Promise<void>;
health(): Promise<ProviderHealth>;
close?(): Promise<void>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
cancel | 方法 | cancel(request: ExecutionCancelRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
capabilities | 方法 | capabilities(): Promise<SandboxProviderCapabilities> | 公开方法；参数与返回类型以签名列为准。 |
cleanup | 方法 | cleanup(request: SandboxCleanupRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
close | 方法 | close?(): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
create | 方法 | create(request: SandboxCreateRequest): Promise<SandboxRecord> | 公开方法；参数与返回类型以签名列为准。 |
execute | 方法 | execute(request: CommandExecutionRequest): Promise<CommandExecutionResult> | 公开方法；参数与返回类型以签名列为准。 |
health | 方法 | health(): Promise<ProviderHealth> | 公开方法；参数与返回类型以签名列为准。 |
id | 属性 | readonly id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
start | 方法 | start(request: SandboxStartRequest): Promise<SandboxRecord> | 公开方法；参数与返回类型以签名列为准。 |
status | 方法 | status(request: SandboxStatusRequest): Promise<SandboxRecord | null> | 公开方法；参数与返回类型以签名列为准。 |
terminate | 方法 | terminate(request: SandboxTerminateRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
SandboxProviderFactory
Composition-root contract for constructing a configured SandboxProvider. Concrete adapters own their options; core only knows the provider type and stable id.
- 种类: 接口
- 导入:
import type { SandboxProviderFactory } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export interface SandboxProviderFactory {
readonly providerType: SandboxProviderType;
readonly providerId: string;
create(): SandboxProvider | Promise<SandboxProvider>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
create | 方法 | create(): SandboxProvider | Promise<SandboxProvider> | 公开方法；参数与返回类型以签名列为准。 |
providerId | 属性 | readonly providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
providerType | 属性 | readonly providerType: "mock" | "local_process" | "docker" | "remote_sandbox" | "custom" | 公开属性；类型、只读和可选状态以签名列为准。 |
SandboxCapabilityName
Sandbox Capability Name 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { SandboxCapabilityName } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export type SandboxCapabilityName = keyof SandboxProviderCapabilities;SandboxProviderSelection
Sandbox Provider Selection 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { SandboxProviderSelection } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export type SandboxProviderSelection = Pick<ExecutionEnvironmentSpec, 'provider' | 'providerRef'>;SandboxProviderType
Sandbox Provider Type 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { SandboxProviderType } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/sandbox-provider
声明
text
export type SandboxProviderType = ExecutionEnvironmentSpec['provider'];