@codesoul-co/hypha-inference / prompt-profile
模块用法
用于使用该功能边界的公共契约与操作。Prompt profile 模块公开 1 类、3 常量、9 接口、2 类型。
从包入口导入
ts
import {
PromptProfileRegistry,
PROMPT_PROFILE_SOURCES,
PROMPT_PROFILE_STATUSES,
promptProfileInputSchema,
} from '@codesoul-co/hypha-inference';
import type {
PromptProfile,
PromptProfileArtifactPort,
PromptProfileInput,
PromptProfileLayer,
PromptProfilePrincipal,
PromptProfileRef,
PromptProfileRegistryOptions,
PromptProfileResolution,
} from '@codesoul-co/hypha-inference';
// 完整导出列表见下方。使用要点
- 11 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用
import type，运行时不应依赖它们。 - 1 个类提供可实例化的运行时实现；构造参数与公开方法在各自条目中完整列出。
- 3 个常量/枚举提供稳定值、Schema、Definition 或默认配置；应复用这些导出，避免在应用中复制内部值。
运行时校验示例
ts
import { promptProfileInputSchema } from '@codesoul-co/hypha-inference';
declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = promptProfileInputSchema.parse(input);配置、网络请求或持久化数据等不可信输入应先通过 Runtime Schema，再传给只接受已校验契约的函数或类。
公共导出
| Symbol | 种类 | 签名 | 说明 |
|---|---|---|---|
PromptProfileRegistry | 类 | new PromptProfileRegistry(options?: PromptProfileRegistryOptions): PromptProfileRegistry | Immutable Prompt Profile revisions plus a CAS-protected publication lifecycle. Active revisions are never overwritten, so a Run can safely keep an exact ref. |
PROMPT_PROFILE_SOURCES | 常量 | const PROMPT_PROFILE_SOURCES: readonly ["system", "developer", "domain", "skill", "mcp", "user"] | 由 prompt-profile 模块导出的 PROMPT PROFILE SOURCES 常量。 |
PROMPT_PROFILE_STATUSES | 常量 | const PROMPT_PROFILE_STATUSES: readonly ["draft", "in_review", "active", "deprecated"] | 由 prompt-profile 模块导出的 PROMPT PROFILE STATUSES 常量。 |
promptProfileInputSchema | 常量 | const promptProfileInputSchema: z.ZodEffects<z.ZodObject<{ id: z.ZodString; version: z.ZodString; name: z.ZodString; description: z.ZodOptional<z.ZodString>; layers: z.ZodArray<z.ZodObject<{ id: z.ZodString; source: z.ZodEnum<["system", "developer", "domain", "skill", "mcp", "user"]>; content: z.ZodString; priority: z.ZodOptional<z.ZodNumber>; trustLevel: z.ZodOptional<z.ZodEnum<["trusted", "reviewed", "untrusted"... | Prompt Profile Input 的运行时 Schema。 |
PromptProfile | 接口 | interface PromptProfile extends PromptProfileInput | Prompt Profile 接口，共包含 31 个公开字段或方法。 |
PromptProfileArtifactPort | 接口 | interface PromptProfileArtifactPort | Prompt Profile Artifact Port 接口，共包含 1 个公开字段或方法。 |
PromptProfileInput | 接口 | interface PromptProfileInput | Prompt Profile Input 接口，共包含 19 个公开字段或方法。 |
PromptProfileLayer | 接口 | interface PromptProfileLayer | Prompt Profile Layer 接口，共包含 7 个公开字段或方法。 |
PromptProfilePrincipal | 接口 | interface PromptProfilePrincipal | Prompt Profile Principal 接口，共包含 7 个公开字段或方法。 |
PromptProfileRef | 接口 | interface PromptProfileRef | Prompt Profile Ref 接口，共包含 3 个公开字段或方法。 |
PromptProfileRegistryOptions | 接口 | interface PromptProfileRegistryOptions | Prompt Profile Registry Options 接口，共包含 3 个公开字段或方法。 |
PromptProfileResolution | 接口 | interface PromptProfileResolution | Prompt Profile Resolution 接口，共包含 6 个公开字段或方法。 |
PromptProfileTraceSink | 接口 | interface PromptProfileTraceSink | Prompt Profile Trace Sink 接口，共包含 1 个公开字段或方法。 |
PromptProfileSource | 类型 | type PromptProfileSource = (typeof PROMPT_PROFILE_SOURCES)[number] | Prompt Profile Source 公共类型别名；完整类型表达式见声明。 |
PromptProfileStatus | 类型 | type PromptProfileStatus = (typeof PROMPT_PROFILE_STATUSES)[number] | Prompt Profile Status 公共类型别名；完整类型表达式见声明。 |
PromptProfileRegistry
Immutable Prompt Profile revisions plus a CAS-protected publication lifecycle. Active revisions are never overwritten, so a Run can safely keep an exact ref.
- 种类: 类
- 导入:
import { PromptProfileRegistry } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export declare class PromptProfileRegistry {
constructor(options?: PromptProfileRegistryOptions);
create(input: PromptProfileInput): PromptProfile;
restore(input: PromptProfile): PromptProfile;
submitForReview(ref: Required<PromptProfileRef>, input: {
expectedLifecycleRevision: number;
reviewedBy: string;
}): PromptProfile;
activate(ref: Required<PromptProfileRef>, input: {
expectedLifecycleRevision: number;
activatedBy: string;
}): PromptProfile;
deprecate(ref: Required<PromptProfileRef>, input: {
expectedLifecycleRevision: number;
deprecatedBy: string;
}): PromptProfile;
get(ref: PromptProfileRef): PromptProfile | null;
list(id?: string, version?: string): PromptProfile[];
clear(): void;
resolve(ref: PromptProfileRef, context: {
variables: Record<string, unknown>;
principal: PromptProfilePrincipal;
maxInlineBytes?: number;
policyRevision?: string;
dependencySnapshotHash?: string;
}): Promise<PromptProfileResolution>;
}公开成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
activate | 方法 | activate(ref: Required<PromptProfileRef>, input: { expectedLifecycleRevision: number; activatedBy: string; }): PromptProfile | 公开方法；参数与返回类型以签名列为准。 |
clear | 方法 | clear(): void | 公开方法；参数与返回类型以签名列为准。 |
constructor | 构造函数 | (options?: PromptProfileRegistryOptions): PromptProfileRegistry | 创建该类的实例。 |
create | 方法 | create(input: PromptProfileInput): PromptProfile | 公开方法；参数与返回类型以签名列为准。 |
deprecate | 方法 | deprecate(ref: Required<PromptProfileRef>, input: { expectedLifecycleRevision: number; deprecatedBy: string; }): PromptProfile | 公开方法；参数与返回类型以签名列为准。 |
get | 方法 | get(ref: PromptProfileRef): PromptProfile | null | 公开方法；参数与返回类型以签名列为准。 |
list | 方法 | list(id?: string, version?: string): PromptProfile[] | 公开方法；参数与返回类型以签名列为准。 |
resolve | 方法 | resolve(ref: PromptProfileRef, context: { variables: Record<string, unknown>; principal: PromptProfilePrincipal; maxInlineBytes?: number; policyRevision?: string; dependencySnapshotHash?: string; }): Promise<PromptProfileResolution> | 公开方法；参数与返回类型以签名列为准。 |
restore | 方法 | restore(input: PromptProfile): PromptProfile | 公开方法；参数与返回类型以签名列为准。 |
submitForReview | 方法 | submitForReview(ref: Required<PromptProfileRef>, input: { expectedLifecycleRevision: number; reviewedBy: string; }): PromptProfile | 公开方法；参数与返回类型以签名列为准。 |
PROMPT_PROFILE_SOURCES
由 prompt-profile 模块导出的 PROMPT PROFILE SOURCES 常量。
- 种类: 常量
- 导入:
import { PROMPT_PROFILE_SOURCES } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export declare const PROMPT_PROFILE_SOURCES: readonly ["system", "developer", "domain", "skill", "mcp", "user"];PROMPT_PROFILE_STATUSES
由 prompt-profile 模块导出的 PROMPT PROFILE STATUSES 常量。
- 种类: 常量
- 导入:
import { PROMPT_PROFILE_STATUSES } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export declare const PROMPT_PROFILE_STATUSES: readonly ["draft", "in_review", "active", "deprecated"];promptProfileInputSchema
Prompt Profile Input 的运行时 Schema。
- 种类: 常量
- 导入:
import { promptProfileInputSchema } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
// 精确类型由包入口解析；完整编译器展开定义见源码链接。
export declare const promptProfileInputSchema: (typeof import('@codesoul-co/hypha-inference'))['promptProfileInputSchema'];该常量的编译器展开类型已压缩；它的公共名称、顶层类型与源码位置仍保留在本条目中。相关输入/输出字段请使用同模块导出的接口、类型或 Runtime Schema。
PromptProfile
Prompt Profile 接口，共包含 31 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfile } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfile extends PromptProfileInput {
revision: number;
lifecycleRevision: number;
status: PromptProfileStatus;
contentHash: string;
createdAt: string;
updatedAt: string;
reviewedBy?: string;
reviewedAt?: string;
activatedBy?: string;
activatedAt?: string;
deprecatedBy?: string;
deprecatedAt?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
activatedAt | 属性 | activatedAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
activatedBy | 属性 | activatedBy?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
agentIds | 属性 | agentIds?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
approvalExpiresAt | 属性 | approvalExpiresAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
contentHash | 属性 | contentHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
createdAt | 属性 | createdAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
dependencySnapshotHash | 属性 | dependencySnapshotHash?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
deprecatedAt | 属性 | deprecatedAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
deprecatedBy | 属性 | deprecatedBy?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
description | 属性 | description?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
domainIds | 属性 | domainIds?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
layers | 属性 | layers: PromptProfileLayer[] | 公开属性；类型、只读和可选状态以签名列为准。 |
lifecycleRevision | 属性 | lifecycleRevision: number | 公开属性；类型、只读和可选状态以签名列为准。 |
maxInlineBytes | 属性 | maxInlineBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
name | 属性 | name: string | 公开属性；类型、只读和可选状态以签名列为准。 |
ownerId | 属性 | ownerId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
policyRevision | 属性 | policyRevision?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
reviewedAt | 属性 | reviewedAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
reviewedBy | 属性 | reviewedBy?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
revision | 属性 | revision: number | 公开属性；类型、只读和可选状态以签名列为准。 |
runId | 属性 | runId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
scope | 属性 | scope?: "domain" | "session" | "run" | "agent" | "user" | "tenant" | "owner" | "global" | 公开属性；类型、只读和可选状态以签名列为准。 |
sessionId | 属性 | sessionId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
status | 属性 | status: "draft" | "active" | "in_review" | "deprecated" | 公开属性；类型、只读和可选状态以签名列为准。 |
tenantId | 属性 | tenantId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
updatedAt | 属性 | updatedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
userId | 属性 | userId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
variableNames | 属性 | variableNames?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
version | 属性 | version: string | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileArtifactPort
Prompt Profile Artifact Port 接口，共包含 1 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileArtifactPort } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileArtifactPort {
store(input: {
profile: Pick<PromptProfile, 'id' | 'version' | 'revision' | 'contentHash'>;
bytes: Uint8Array;
contentHash: string;
mediaType: 'application/json';
metadata: Record<string, unknown>;
}): Promise<{
artifactRef: string;
contentHash: string;
sizeBytes: number;
}>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
store | 方法 | store(input: { profile: Pick<PromptProfile, "id" | "version" | "revision" | "contentHash">; bytes: Uint8Array; contentHash: string; mediaType: "application/json"; metadata: Record<string, unknown>; }): Promise<{ artifactRef: string; contentHash: string; sizeBytes: number; }> | 公开方法；参数与返回类型以签名列为准。 |
PromptProfileInput
Prompt Profile Input 接口，共包含 19 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileInput } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileInput {
id: string;
version: string;
name: string;
description?: string;
layers: PromptProfileLayer[];
variableNames?: string[];
scope?: 'global' | 'tenant' | 'owner' | 'user' | 'agent' | 'domain' | 'session' | 'run';
tenantId?: string;
ownerId?: string;
userId?: string;
sessionId?: string;
runId?: string;
agentIds?: string[];
domainIds?: string[];
policyRevision?: string;
dependencySnapshotHash?: string;
approvalExpiresAt?: string;
maxInlineBytes?: number;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
agentIds | 属性 | agentIds?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
approvalExpiresAt | 属性 | approvalExpiresAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
dependencySnapshotHash | 属性 | dependencySnapshotHash?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
description | 属性 | description?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
domainIds | 属性 | domainIds?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
layers | 属性 | layers: PromptProfileLayer[] | 公开属性；类型、只读和可选状态以签名列为准。 |
maxInlineBytes | 属性 | maxInlineBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
name | 属性 | name: string | 公开属性；类型、只读和可选状态以签名列为准。 |
ownerId | 属性 | ownerId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
policyRevision | 属性 | policyRevision?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
runId | 属性 | runId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
scope | 属性 | scope?: "domain" | "session" | "run" | "agent" | "user" | "tenant" | "owner" | "global" | 公开属性；类型、只读和可选状态以签名列为准。 |
sessionId | 属性 | sessionId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
tenantId | 属性 | tenantId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
userId | 属性 | userId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
variableNames | 属性 | variableNames?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
version | 属性 | version: string | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileLayer
Prompt Profile Layer 接口，共包含 7 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileLayer } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileLayer {
id: string;
source: PromptProfileSource;
content: string;
priority?: number;
trustLevel?: 'trusted' | 'reviewed' | 'untrusted';
provenance?: Record<string, unknown>;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
content | 属性 | content: string | 公开属性；类型、只读和可选状态以签名列为准。 |
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
priority | 属性 | priority?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
provenance | 属性 | provenance?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
source | 属性 | source: "skill" | "domain" | "mcp" | "system" | "user" | "developer" | 公开属性；类型、只读和可选状态以签名列为准。 |
trustLevel | 属性 | trustLevel?: "trusted" | "reviewed" | "untrusted" | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfilePrincipal
Prompt Profile Principal 接口，共包含 7 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfilePrincipal } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfilePrincipal {
principalId: string;
tenantId?: string;
userId?: string;
agentId?: string;
domainId?: string;
sessionId?: string;
runId?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
agentId | 属性 | agentId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
domainId | 属性 | domainId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principalId | 属性 | principalId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
runId | 属性 | runId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sessionId | 属性 | sessionId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
tenantId | 属性 | tenantId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
userId | 属性 | userId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileRef
Prompt Profile Ref 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileRef } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileRef {
id: string;
version?: string;
revision?: number;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
revision | 属性 | revision?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
version | 属性 | version?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileRegistryOptions
Prompt Profile Registry Options 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileRegistryOptions } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileRegistryOptions {
now?: () => string;
artifacts?: PromptProfileArtifactPort;
trace?: PromptProfileTraceSink;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifacts | 属性 | artifacts?: PromptProfileArtifactPort | 公开属性；类型、只读和可选状态以签名列为准。 |
now | 方法 | now?(): string | 公开方法；参数与返回类型以签名列为准。 |
trace | 属性 | trace?: PromptProfileTraceSink | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileResolution
Prompt Profile Resolution 接口，共包含 6 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileResolution } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileResolution {
profileRef: Required<PromptProfileRef>;
profileHash: string;
messages: PromptMessage[];
sizeBytes: number;
cacheHit: boolean;
artifactRef?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
cacheHit | 属性 | cacheHit: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
messages | 属性 | messages: PromptMessage[] | 公开属性；类型、只读和可选状态以签名列为准。 |
profileHash | 属性 | profileHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
profileRef | 属性 | profileRef: Required<PromptProfileRef> | 公开属性；类型、只读和可选状态以签名列为准。 |
sizeBytes | 属性 | sizeBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
PromptProfileTraceSink
Prompt Profile Trace Sink 接口，共包含 1 个公开字段或方法。
- 种类: 接口
- 导入:
import type { PromptProfileTraceSink } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export interface PromptProfileTraceSink {
record(event: {
type: 'prompt.profile.resolved' | 'prompt.profile.cache_hit' | 'prompt.profile.externalized';
profileId: string;
version: string;
revision: number;
contentHash: string;
principalScopeHash: string;
sizeBytes: number;
timestamp: string;
}): Promise<void> | void;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
record | 方法 | record(event: { type: "prompt.profile.resolved" | "prompt.profile.cache_hit" | "prompt.profile.externalized"; profileId: string; version: string; revision: number; contentHash: string; principalScopeHash: string; sizeBytes: number; timestamp: string; }): Promise<void> | void | 公开方法；参数与返回类型以签名列为准。 |
PromptProfileSource
Prompt Profile Source 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { PromptProfileSource } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export type PromptProfileSource = (typeof PROMPT_PROFILE_SOURCES)[number];PromptProfileStatus
Prompt Profile Status 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { PromptProfileStatus } from '@codesoul-co/hypha-inference'; - 源码模块:
prompt-profile
声明
text
export type PromptProfileStatus = (typeof PROMPT_PROFILE_STATUSES)[number];