Skip to content

@codesoul-co/hypha-inference / agent-prompts

模块用法

用于使用该功能边界的公共契约与操作。Agent prompts 模块公开 1 类、3 常量、2 函数、8 接口、2 类型。

从包入口导入

ts
import {
  AgentPromptRegistry,
  agentPromptRefSchema,
  agentPromptSpecSchema,
  agentPromptVariableSpecSchema,
  agentPromptSubjectHash,
  renderAgentPrompt,
} from '@codesoul-co/hypha-inference';

import type {
  AgentPromptApproval,
  AgentPromptPrincipal,
  AgentPromptRef,
  AgentPromptResolution,
  AgentPromptResolutionContext,
  AgentPromptSpec,
  AgentPromptVariableSpec,
  ResolvedAgentPromptBlock,
} from '@codesoul-co/hypha-inference';

// 完整导出列表见下方。

使用要点

  • 10 个类型/接口用于应用代码、Adapter 或测试中的静态契约;请使用 import type,运行时不应依赖它们。
  • 1 个类提供可实例化的运行时实现;构造参数与公开方法在各自条目中完整列出。
  • 2 个函数是该模块的直接操作入口;每个 overload 的必需/可选参数与返回类型均在下方列出。
  • 3 个常量/枚举提供稳定值、Schema、Definition 或默认配置;应复用这些导出,避免在应用中复制内部值。

运行时校验示例

ts
import { agentPromptRefSchema } from '@codesoul-co/hypha-inference';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = agentPromptRefSchema.parse(input);

配置、网络请求或持久化数据等不可信输入应先通过 Runtime Schema,再传给只接受已校验契约的函数或类。

公共导出

Symbol种类签名说明
AgentPromptRegistrynew AgentPromptRegistry(): AgentPromptRegistryAgent Prompt Registry 类,共公开 6 个构造函数或成员;精确签名见本条目的声明与成员表。
agentPromptRefSchema常量const agentPromptRefSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; required: z.ZodOptional<z.ZodBoolean>; priority: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { id: string; version?: string | undefined; priority?: number | undefined; required?: boolean | undefined; }, { id: string; version?: string | undefined; priority?: number | undefined; required?: boolean | undefined; }>Agent Prompt Ref 的运行时 Schema。
agentPromptSpecSchema常量const agentPromptSpecSchema: z.ZodEffects<z.ZodObject<{ id: z.ZodString; version: z.ZodString; name: z.ZodString; description: z.ZodOptional<z.ZodString>; role: z.ZodEnum<["system", "developer"]>; template: z.ZodString; variables: z.ZodOptional<z.ZodArray<z.ZodObject<{ name: z.ZodString; type: z.ZodEnum<["string", "number", "boolean", "array", "object"]>; required: z.ZodOptional<z.ZodBoolean>; default: z.ZodOption...Agent Prompt Spec 的运行时 Schema。
agentPromptVariableSpecSchema常量const agentPromptVariableSpecSchema: z.ZodObject<{ name: z.ZodString; type: z.ZodEnum<["string", "number", "boolean", "array", "object"]>; required: z.ZodOptional<z.ZodBoolean>; default: z.ZodOptional<z.ZodUnknown>; description: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { name: string; type: "string" | "number" | "boolean" | "object" | "array"; description?: string | undefined; default?: unknown; requi...Agent Prompt Variable Spec 的运行时 Schema。
agentPromptSubjectHash函数agentPromptSubjectHash(spec: Pick<AgentPromptSpec, "id" | "version" | "revision" | "contentHash">): stringAgent Prompt Subject Hash 函数,提供 1 个公开调用签名;参数与返回类型见下表。
renderAgentPrompt函数renderAgentPrompt(spec: AgentPromptSpec, variables: Record<string, unknown>): stringRender Agent Prompt 函数,提供 1 个公开调用签名;参数与返回类型见下表。
AgentPromptApproval接口interface AgentPromptApprovalAgent Prompt Approval 接口,共包含 14 个公开字段或方法。
AgentPromptPrincipal接口interface AgentPromptPrincipalAgent Prompt Principal 接口,共包含 4 个公开字段或方法。
AgentPromptRef接口interface AgentPromptRefAgent Prompt Ref 接口,共包含 4 个公开字段或方法。
AgentPromptResolution接口interface AgentPromptResolutionAgent Prompt Resolution 接口,共包含 3 个公开字段或方法。
AgentPromptResolutionContext接口interface AgentPromptResolutionContextAgent Prompt Resolution Context 接口,共包含 3 个公开字段或方法。
AgentPromptSpec接口interface AgentPromptSpecAgent Prompt Spec 接口,共包含 19 个公开字段或方法。
AgentPromptVariableSpec接口interface AgentPromptVariableSpecAgent Prompt Variable Spec 接口,共包含 5 个公开字段或方法。
ResolvedAgentPromptBlock接口interface ResolvedAgentPromptBlockResolved Agent Prompt Block 接口,共包含 18 个公开字段或方法。
AgentPromptRole类型type AgentPromptRole = 'system' | 'developer'Agent Prompt Role 公共类型别名;完整类型表达式见声明。
AgentPromptVariableType类型type AgentPromptVariableType = 'string' | 'number' | 'boolean' | 'array' | 'object'Agent Prompt Variable Type 公共类型别名;完整类型表达式见声明。

AgentPromptRegistry

Agent Prompt Registry 类,共公开 6 个构造函数或成员;精确签名见本条目的声明与成员表。

  • 种类: 类
  • 导入: import { AgentPromptRegistry } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export declare class AgentPromptRegistry {
    register(input: AgentPromptSpec, options?: {
            replace?: boolean;
            expectedRevision?: number;
        }): AgentPromptSpec;
    unregister(id: string, version?: string): boolean;
    get(id: string, version?: string): AgentPromptSpec | null;
    list(): AgentPromptSpec[];
    resolve(refs: AgentPromptRef[], context: AgentPromptResolutionContext): AgentPromptResolution;
}

公开成员

成员种类签名说明
constructor构造函数(): AgentPromptRegistry创建该类的实例。
get方法get(id: string, version?: string): AgentPromptSpec | null公开方法;参数与返回类型以签名列为准。
list方法list(): AgentPromptSpec[]公开方法;参数与返回类型以签名列为准。
register方法register(input: AgentPromptSpec, options?: { replace?: boolean; expectedRevision?: number; }): AgentPromptSpec公开方法;参数与返回类型以签名列为准。
resolve方法resolve(refs: AgentPromptRef[], context: AgentPromptResolutionContext): AgentPromptResolution公开方法;参数与返回类型以签名列为准。
unregister方法unregister(id: string, version?: string): boolean公开方法;参数与返回类型以签名列为准。

agentPromptRefSchema

Agent Prompt Ref 的运行时 Schema。

  • 种类: 常量
  • 导入: import { agentPromptRefSchema } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export declare const agentPromptRefSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; required: z.ZodOptional<z.ZodBoolean>; priority: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { id: string; version?: string | undefined; priority?: number | undefined; required?: boolean | undefined; }, { id: string; version?: string | undefined; priority?: number | undefined; required?: boolean | undefined; }>;

agentPromptSpecSchema

Agent Prompt Spec 的运行时 Schema。

  • 种类: 常量
  • 导入: import { agentPromptSpecSchema } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
// 精确类型由包入口解析;完整编译器展开定义见源码链接。
export declare const agentPromptSpecSchema: (typeof import('@codesoul-co/hypha-inference'))['agentPromptSpecSchema'];

该常量的编译器展开类型已压缩;它的公共名称、顶层类型与源码位置仍保留在本条目中。相关输入/输出字段请使用同模块导出的接口、类型或 Runtime Schema。

agentPromptVariableSpecSchema

Agent Prompt Variable Spec 的运行时 Schema。

  • 种类: 常量
  • 导入: import { agentPromptVariableSpecSchema } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export declare const agentPromptVariableSpecSchema: z.ZodObject<{ name: z.ZodString; type: z.ZodEnum<["string", "number", "boolean", "array", "object"]>; required: z.ZodOptional<z.ZodBoolean>; default: z.ZodOptional<z.ZodUnknown>; description: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { name: string; type: "string" | "number" | "boolean" | "object" | "array"; description?: string | undefined; default?: unknown; required?: boolean | undefined; }, { name: string; type: "string" | "number" | "boolean" | "object" | "array"; description?: string | undefined; default?: unknown; required?: boolean | undefined; }>;

agentPromptSubjectHash

Agent Prompt Subject Hash 函数,提供 1 个公开调用签名;参数与返回类型见下表。

  • 种类: 函数
  • 导入: import { agentPromptSubjectHash } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export declare function agentPromptSubjectHash(spec: Pick<AgentPromptSpec, 'id' | 'version' | 'revision' | 'contentHash'>): string;

调用签名

text
agentPromptSubjectHash(spec: Pick<AgentPromptSpec, "id" | "version" | "revision" | "contentHash">): string

参数

参数类型必需说明
specPick<AgentPromptSpec, "id" | "version" | "revision" | "contentHash">必需参数;接受的值由类型列定义。

返回值

  • 类型: string
  • 说明: 返回值契约由上述类型定义。

renderAgentPrompt

Render Agent Prompt 函数,提供 1 个公开调用签名;参数与返回类型见下表。

  • 种类: 函数
  • 导入: import { renderAgentPrompt } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export declare function renderAgentPrompt(spec: AgentPromptSpec, variables: Record<string, unknown>): string;

调用签名

text
renderAgentPrompt(spec: AgentPromptSpec, variables: Record<string, unknown>): string

参数

参数类型必需说明
specAgentPromptSpec必需参数;接受的值由类型列定义。
variablesRecord<string, unknown>必需参数;接受的值由类型列定义。

返回值

  • 类型: string
  • 说明: 返回值契约由上述类型定义。

AgentPromptApproval

Agent Prompt Approval 接口,共包含 14 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptApproval } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptApproval {
    taskId: string;
    subjectType: 'agent_prompt';
    subjectHash: string;
    promptId: string;
    promptVersion: string;
    promptRevision: number;
    contentHash: string;
    approvedBy: string;
    principalId?: string;
    tenantId?: string;
    agentId?: string;
    domainId?: string;
    expiresAt?: string;
    status: 'approved';
}

契约成员

成员种类签名说明
agentId属性agentId?: string公开属性;类型、只读和可选状态以签名列为准。
approvedBy属性approvedBy: string公开属性;类型、只读和可选状态以签名列为准。
contentHash属性contentHash: string公开属性;类型、只读和可选状态以签名列为准。
domainId属性domainId?: string公开属性;类型、只读和可选状态以签名列为准。
expiresAt属性expiresAt?: string公开属性;类型、只读和可选状态以签名列为准。
principalId属性principalId?: string公开属性;类型、只读和可选状态以签名列为准。
promptId属性promptId: string公开属性;类型、只读和可选状态以签名列为准。
promptRevision属性promptRevision: number公开属性;类型、只读和可选状态以签名列为准。
promptVersion属性promptVersion: string公开属性;类型、只读和可选状态以签名列为准。
status属性status: "approved"公开属性;类型、只读和可选状态以签名列为准。
subjectHash属性subjectHash: string公开属性;类型、只读和可选状态以签名列为准。
subjectType属性subjectType: "agent_prompt"公开属性;类型、只读和可选状态以签名列为准。
taskId属性taskId: string公开属性;类型、只读和可选状态以签名列为准。
tenantId属性tenantId?: string公开属性;类型、只读和可选状态以签名列为准。

AgentPromptPrincipal

Agent Prompt Principal 接口,共包含 4 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptPrincipal } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptPrincipal {
    principalId: string;
    tenantId?: string;
    agentId?: string;
    domainId?: string;
}

契约成员

成员种类签名说明
agentId属性agentId?: string公开属性;类型、只读和可选状态以签名列为准。
domainId属性domainId?: string公开属性;类型、只读和可选状态以签名列为准。
principalId属性principalId: string公开属性;类型、只读和可选状态以签名列为准。
tenantId属性tenantId?: string公开属性;类型、只读和可选状态以签名列为准。

AgentPromptRef

Agent Prompt Ref 接口,共包含 4 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptRef } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptRef {
    id: string;
    version?: string;
    required?: boolean;
    priority?: number;
}

契约成员

成员种类签名说明
id属性id: string公开属性;类型、只读和可选状态以签名列为准。
priority属性priority?: number公开属性;类型、只读和可选状态以签名列为准。
required属性required?: boolean公开属性;类型、只读和可选状态以签名列为准。
version属性version?: string公开属性;类型、只读和可选状态以签名列为准。

AgentPromptResolution

Agent Prompt Resolution 接口,共包含 3 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptResolution } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptResolution {
    instructions: string;
    blocks: ResolvedAgentPromptBlock[];
    missing: AgentPromptRef[];
}

契约成员

成员种类签名说明
blocks属性blocks: ResolvedAgentPromptBlock[]公开属性;类型、只读和可选状态以签名列为准。
instructions属性instructions: string公开属性;类型、只读和可选状态以签名列为准。
missing属性missing: AgentPromptRef[]公开属性;类型、只读和可选状态以签名列为准。

AgentPromptResolutionContext

Agent Prompt Resolution Context 接口,共包含 3 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptResolutionContext } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptResolutionContext {
    variables: Record<string, unknown>;
    principal: AgentPromptPrincipal;
    approvals?: AgentPromptApproval[];
}

契约成员

成员种类签名说明
approvals属性approvals?: AgentPromptApproval[]公开属性;类型、只读和可选状态以签名列为准。
principal属性principal: AgentPromptPrincipal公开属性;类型、只读和可选状态以签名列为准。
variables属性variables: Record<string, unknown>公开属性;类型、只读和可选状态以签名列为准。

AgentPromptSpec

Agent Prompt Spec 接口,共包含 19 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptSpec } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptSpec {
    id: string;
    version: string;
    name: string;
    description?: string;
    role: AgentPromptRole;
    template: string;
    variables?: AgentPromptVariableSpec[];
    stable?: boolean;
    cacheable?: boolean;
    ownerId?: string;
    tenantId?: string;
    scope?: 'global' | 'tenant' | 'owner';
    trustLevel?: 'trusted' | 'reviewed' | 'untrusted';
    agentIds?: string[];
    domainIds?: string[];
    provenance?: Record<string, unknown>;
    revision?: number;
    contentHash?: string;
    metadata?: Record<string, unknown>;
}

契约成员

成员种类签名说明
agentIds属性agentIds?: string[]公开属性;类型、只读和可选状态以签名列为准。
cacheable属性cacheable?: boolean公开属性;类型、只读和可选状态以签名列为准。
contentHash属性contentHash?: string公开属性;类型、只读和可选状态以签名列为准。
description属性description?: string公开属性;类型、只读和可选状态以签名列为准。
domainIds属性domainIds?: string[]公开属性;类型、只读和可选状态以签名列为准。
id属性id: string公开属性;类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性;类型、只读和可选状态以签名列为准。
name属性name: string公开属性;类型、只读和可选状态以签名列为准。
ownerId属性ownerId?: string公开属性;类型、只读和可选状态以签名列为准。
provenance属性provenance?: Record<string, unknown>公开属性;类型、只读和可选状态以签名列为准。
revision属性revision?: number公开属性;类型、只读和可选状态以签名列为准。
role属性role: AgentPromptRole公开属性;类型、只读和可选状态以签名列为准。
scope属性scope?: "tenant" | "owner" | "global"公开属性;类型、只读和可选状态以签名列为准。
stable属性stable?: boolean公开属性;类型、只读和可选状态以签名列为准。
template属性template: string公开属性;类型、只读和可选状态以签名列为准。
tenantId属性tenantId?: string公开属性;类型、只读和可选状态以签名列为准。
trustLevel属性trustLevel?: "trusted" | "reviewed" | "untrusted"公开属性;类型、只读和可选状态以签名列为准。
variables属性variables?: AgentPromptVariableSpec[]公开属性;类型、只读和可选状态以签名列为准。
version属性version: string公开属性;类型、只读和可选状态以签名列为准。

AgentPromptVariableSpec

Agent Prompt Variable Spec 接口,共包含 5 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { AgentPromptVariableSpec } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface AgentPromptVariableSpec {
    name: string;
    type: AgentPromptVariableType;
    required?: boolean;
    default?: unknown;
    description?: string;
}

契约成员

成员种类签名说明
default属性default?: unknown公开属性;类型、只读和可选状态以签名列为准。
description属性description?: string公开属性;类型、只读和可选状态以签名列为准。
name属性name: string公开属性;类型、只读和可选状态以签名列为准。
required属性required?: boolean公开属性;类型、只读和可选状态以签名列为准。
type属性type: AgentPromptVariableType公开属性;类型、只读和可选状态以签名列为准。

ResolvedAgentPromptBlock

Resolved Agent Prompt Block 接口,共包含 18 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { ResolvedAgentPromptBlock } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export interface ResolvedAgentPromptBlock {
    id: string;
    type: 'prompt-template';
    role: AgentPromptRole;
    content: string;
    hash: string;
    stable: boolean;
    cacheable: boolean;
    order: number;
    templateId: string;
    templateVersion: string;
    templateRevision: number;
    templateContentHash: string;
    scope: 'global' | 'tenant' | 'owner';
    trustLevel: 'trusted' | 'reviewed' | 'untrusted';
    ownerId?: string;
    tenantId?: string;
    provenance?: Record<string, unknown>;
    metadata?: Record<string, unknown>;
}

契约成员

成员种类签名说明
cacheable属性cacheable: boolean公开属性;类型、只读和可选状态以签名列为准。
content属性content: string公开属性;类型、只读和可选状态以签名列为准。
hash属性hash: string公开属性;类型、只读和可选状态以签名列为准。
id属性id: string公开属性;类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性;类型、只读和可选状态以签名列为准。
order属性order: number公开属性;类型、只读和可选状态以签名列为准。
ownerId属性ownerId?: string公开属性;类型、只读和可选状态以签名列为准。
provenance属性provenance?: Record<string, unknown>公开属性;类型、只读和可选状态以签名列为准。
role属性role: AgentPromptRole公开属性;类型、只读和可选状态以签名列为准。
scope属性scope: "tenant" | "owner" | "global"公开属性;类型、只读和可选状态以签名列为准。
stable属性stable: boolean公开属性;类型、只读和可选状态以签名列为准。
templateContentHash属性templateContentHash: string公开属性;类型、只读和可选状态以签名列为准。
templateId属性templateId: string公开属性;类型、只读和可选状态以签名列为准。
templateRevision属性templateRevision: number公开属性;类型、只读和可选状态以签名列为准。
templateVersion属性templateVersion: string公开属性;类型、只读和可选状态以签名列为准。
tenantId属性tenantId?: string公开属性;类型、只读和可选状态以签名列为准。
trustLevel属性trustLevel: "trusted" | "reviewed" | "untrusted"公开属性;类型、只读和可选状态以签名列为准。
type属性type: "prompt-template"公开属性;类型、只读和可选状态以签名列为准。

AgentPromptRole

Agent Prompt Role 公共类型别名;完整类型表达式见声明。

  • 种类: 类型
  • 导入: import type { AgentPromptRole } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export type AgentPromptRole = 'system' | 'developer';

AgentPromptVariableType

Agent Prompt Variable Type 公共类型别名;完整类型表达式见声明。

  • 种类: 类型
  • 导入: import type { AgentPromptVariableType } from '@codesoul-co/hypha-inference';
  • 源码模块: agent-prompts

声明

text
export type AgentPromptVariableType = 'string' | 'number' | 'boolean' | 'array' | 'object';