@codesoul-co/hypha-skills / index

• 包索引: @codesoul-co/hypha-skills
• 源码: packages/skills/src/index.ts
• 导出数: 42

模块用法

聚合 @codesoul-co/hypha-skills 的公共入口导出；应用应从包入口导入这些 Symbol，不应依赖内部文件路径。

从包入口导入

import {
  DefaultSkillPolicy,
  LocalSkillLoader,
  SkillContextLoader,
  SkillRegistry,
  SkillResolver,
  SkillSelector,
  skillActivationPolicySchema,
  skillAssetRefSchema,
} from '@codesoul-co/hypha-skills';

import type {
  AgentCapabilityConstraint,
  EffectiveAgentCapabilitySnapshotInput,
  LoadedSkillAsset,
  LoadedSkillContext,
  LocalSkillLoaderOptions,
  ParsedSkillMarkdown,
  ResolvedSkill,
  SkillActivationPolicy,
} from '@codesoul-co/hypha-skills';

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

使用要点

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

运行时校验示例

import { skillActivationPolicySchema } from '@codesoul-co/hypha-skills';

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

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

公共导出

Symbol	种类	签名	说明
DefaultSkillPolicy	类	new DefaultSkillPolicy(options?: { allowedTrustLevels?: Array<NonNullable<SkillSpec["trustLevel"]>>; requireRegisteredTools?: boolean; }): DefaultSkillPolicy	Default Skill Policy 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。
LocalSkillLoader	类	new LocalSkillLoader(options: LocalSkillLoaderOptions): LocalSkillLoader	Local Skill Loader 类，共公开 3 个构造函数或成员；精确签名见本条目的声明与成员表。
SkillContextLoader	类	new SkillContextLoader(options?: { defaultMaxChars?: number; maxReferences?: number; maxFileBytes?: number; readTimeoutMs?: number; }): SkillContextLoader	Skill Context Loader 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。
SkillRegistry	类	new SkillRegistry(): SkillRegistry	Skill Registry 类，共公开 5 个构造函数或成员；精确签名见本条目的声明与成员表。
SkillResolver	类	new SkillResolver(registry: SkillRegistry): SkillResolver	Skill Resolver 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。
SkillSelector	类	new SkillSelector(registry: SkillRegistry): SkillSelector	Skill Selector 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。
skillActivationPolicySchema	常量	const skillActivationPolicySchema: z.ZodObject<{ mode: z.ZodEnum<["always", "keyword", "regex", "intent", "manual"]>; patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strip", z.ZodTypeAny, { mode: "always" | "keyword" | "regex" | "intent" | "manual"; patterns?: string[] | undefined; }, { mode: "always" | "keyword" | "regex" | "intent" | "manual"; patterns?: string[] | undefined; }>	Skill Activation Policy 的运行时 Schema。
skillAssetRefSchema	常量	const skillAssetRefSchema: z.ZodObject<{ path: z.ZodString; type: z.ZodEnum<["reference", "script", "asset"]>; loadPolicy: z.ZodOptional<z.ZodEnum<["frontmatter_only", "on_activation", "never"]>>; }, "strip", z.ZodTypeAny, { path: string; type: "reference" | "script" | "asset"; loadPolicy?: "never" | "frontmatter_only" | "on_activation" | undefined; }, { path: string; type: "reference" | "script" | "asset"; loadPo...	Skill Asset Ref 的运行时 Schema。
skillRefSchema	常量	const skillRefSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { id: string; version?: string | undefined; }, { id: string; version?: string | undefined; }>	Skill Ref 的运行时 Schema。
skillSpecDefinition	常量	const skillSpecDefinition: SpecSchemaDefinition<SkillSpec>	Skill Spec 的运行时校验入口，组合 Parser、Example 与 JSON Schema。
skillSpecDefinitions	常量	const skillSpecDefinitions: readonly [SpecSchemaDefinition<SkillSpec>]	由 index 模块导出的 Skill Spec Definitions 常量。
skillSpecExample	常量	const skillSpecExample: SkillSpec	Skill Spec 的有效示例值。
skillSpecJsonSchema	常量	const skillSpecJsonSchema: JsonSchema	Skill Spec 的 JSON Schema。
skillSpecJsonSchemas	常量	const skillSpecJsonSchemas: Record<string, JsonSchema>	由 index 模块导出的 Skill Spec JSON Schemas 常量。
skillSpecSchema	常量	const skillSpecSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodString; name: z.ZodOptional<z.ZodString>; owner: z.ZodOptional<z.ZodString>; tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; createdAt: z.ZodOptional<z.ZodString>; updatedAt: z.ZodOptional<z.ZodString>; } & { description: z.ZodString; enabled: z.ZodOptional<z.ZodBoolean>; priority: z.ZodOptional<z.ZodNumber>; activationPolicy: z.ZodOptional<...	Skill Spec 的运行时 Schema。
createEffectiveAgentCapabilitySnapshot	函数	createEffectiveAgentCapabilitySnapshot(input: EffectiveAgentCapabilitySnapshotInput): Readonly<EffectiveAgentCapabilitySnapshot>	Create Effective Agent Capability Snapshot 函数，提供 1 个公开调用签名；参数与返回类型见下表。
listLocalSkillFiles	函数	listLocalSkillFiles(directory: string, recursive?: boolean): Promise<string[]>	List Local Skill Files 函数，提供 1 个公开调用签名；参数与返回类型见下表。
loadSkillMarkdownFile	函数	loadSkillMarkdownFile(filePath: string): Promise<ParsedSkillMarkdown>	Load Skill Markdown File 函数，提供 1 个公开调用签名；参数与返回类型见下表。
parseSkillMarkdown	函数	parseSkillMarkdown(raw: string, filePath: string): ParsedSkillMarkdown	Parse Skill Markdown 函数，提供 1 个公开调用签名；参数与返回类型见下表。
resolveBuiltinSkillsDirectory	函数	resolveBuiltinSkillsDirectory(): string	Resolves the directory that ships Hypha's built-in skills (context-enrichment, intent-classification) inside this npm package. The published tarball includes builtins/ next to dist/, so consumers can load the framework built-ins without a source checkout of the Server.
validateSkillSpec	函数	validateSkillSpec(input: unknown): SkillSpec	Validate Skill Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。
AgentCapabilityConstraint	接口	interface AgentCapabilityConstraint	Agent Capability Constraint 接口，共包含 6 个公开字段或方法。
EffectiveAgentCapabilitySnapshotInput	接口	interface EffectiveAgentCapabilitySnapshotInput	Effective Agent Capability Snapshot Input 接口，共包含 10 个公开字段或方法。
LoadedSkillAsset	接口	interface LoadedSkillAsset extends SkillAssetRef	Loaded Skill Asset 接口，共包含 6 个公开字段或方法。
LoadedSkillContext	接口	interface LoadedSkillContext	Loaded Skill Context 接口，共包含 16 个公开字段或方法。
LocalSkillLoaderOptions	接口	interface LocalSkillLoaderOptions	Local Skill Loader Options 接口，共包含 3 个公开字段或方法。
ParsedSkillMarkdown	接口	interface ParsedSkillMarkdown	Parsed Skill Markdown 接口，共包含 3 个公开字段或方法。
ResolvedSkill	接口	interface ResolvedSkill	Resolved Skill 接口，共包含 3 个公开字段或方法。
SkillActivationPolicy	接口	interface SkillActivationPolicy	Skill Activation Policy 接口，共包含 2 个公开字段或方法。
SkillAssetRef	接口	interface SkillAssetRef	Skill Asset Ref 接口，共包含 3 个公开字段或方法。
SkillContextLoadInput	接口	interface SkillContextLoadInput	Skill Context Load Input 接口，共包含 3 个公开字段或方法。
SkillLoader	接口	interface SkillLoader	Skill Loader 接口，共包含 1 个公开字段或方法。
SkillPolicy	接口	interface SkillPolicy	Skill Policy 接口，共包含 1 个公开字段或方法。
SkillPolicyDecision	接口	interface SkillPolicyDecision	Skill Policy Decision 接口，共包含 6 个公开字段或方法。
SkillPolicyInput	接口	interface SkillPolicyInput	Skill Policy Input 接口，共包含 2 个公开字段或方法。
SkillRef	接口	interface SkillRef	Skill Ref 接口，共包含 2 个公开字段或方法。
SkillResolutionContext	接口	interface SkillResolutionContext	Skill Resolution Context 接口，共包含 8 个公开字段或方法。
SkillSelection	接口	interface SkillSelection	Skill Selection 接口，共包含 4 个公开字段或方法。
SkillSelectionRejection	接口	interface SkillSelectionRejection	Skill Selection Rejection 接口，共包含 2 个公开字段或方法。
SkillSelectionResult	接口	interface SkillSelectionResult	Skill Selection Result 接口，共包含 2 个公开字段或方法。
SkillSpec	接口	interface SkillSpec extends VersionedSpec, SpecMetadata	Skill Spec 接口，共包含 26 个公开字段或方法。
SkillActivationMode	类型	type SkillActivationMode = 'always' | 'keyword' | 'regex' | 'intent' | 'manual'	Skill Activation Mode 公共类型别名；完整类型表达式见声明。

DefaultSkillPolicy

Default Skill Policy 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { DefaultSkillPolicy } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class DefaultSkillPolicy implements SkillPolicy {
    constructor(options?: {
            allowedTrustLevels?: Array<NonNullable<SkillSpec['trustLevel']>>;
            requireRegisteredTools?: boolean;
        });
    evaluate(input: SkillPolicyInput): Promise<SkillPolicyDecision>;
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(options?: { allowedTrustLevels?: Array<NonNullable<SkillSpec["trustLevel"]>>; requireRegisteredTools?: boolean; }): DefaultSkillPolicy	创建该类的实例。
evaluate	方法	evaluate(input: SkillPolicyInput): Promise<SkillPolicyDecision>	公开方法；参数与返回类型以签名列为准。

LocalSkillLoader

Local Skill Loader 类，共公开 3 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { LocalSkillLoader } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class LocalSkillLoader implements SkillLoader {
    constructor(options: LocalSkillLoaderOptions);
    load(): Promise<SkillSpec[]>;
    loadInto(registry: SkillRegistry): Promise<SkillSpec[]>;
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(options: LocalSkillLoaderOptions): LocalSkillLoader	创建该类的实例。
load	方法	load(): Promise<SkillSpec[]>	公开方法；参数与返回类型以签名列为准。
loadInto	方法	loadInto(registry: SkillRegistry): Promise<SkillSpec[]>	公开方法；参数与返回类型以签名列为准。

SkillContextLoader

Skill Context Loader 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { SkillContextLoader } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class SkillContextLoader {
    constructor(options?: {
            defaultMaxChars?: number;
            maxReferences?: number;
            maxFileBytes?: number;
            readTimeoutMs?: number;
        });
    load(input: SkillContextLoadInput): Promise<LoadedSkillContext>;
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(options?: { defaultMaxChars?: number; maxReferences?: number; maxFileBytes?: number; readTimeoutMs?: number; }): SkillContextLoader	创建该类的实例。
load	方法	load(input: SkillContextLoadInput): Promise<LoadedSkillContext>	公开方法；参数与返回类型以签名列为准。

SkillRegistry

Skill Registry 类，共公开 5 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { SkillRegistry } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class SkillRegistry {
    register(skill: SkillSpec): void;
    registerMany(skills: SkillSpec[]): void;
    get(skillId: string): SkillSpec | null;
    list(): SkillSpec[];
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(): SkillRegistry	创建该类的实例。
get	方法	get(skillId: string): SkillSpec | null	公开方法；参数与返回类型以签名列为准。
list	方法	list(): SkillSpec[]	公开方法；参数与返回类型以签名列为准。
register	方法	register(skill: SkillSpec): void	公开方法；参数与返回类型以签名列为准。
registerMany	方法	registerMany(skills: SkillSpec[]): void	公开方法；参数与返回类型以签名列为准。

SkillResolver

Skill Resolver 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { SkillResolver } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class SkillResolver {
    constructor(registry: SkillRegistry);
    resolve(context: SkillResolutionContext): ResolvedSkill[];
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(registry: SkillRegistry): SkillResolver	创建该类的实例。
resolve	方法	resolve(context: SkillResolutionContext): ResolvedSkill[]	公开方法；参数与返回类型以签名列为准。

SkillSelector

Skill Selector 类，共公开 2 个构造函数或成员；精确签名见本条目的声明与成员表。

• 种类: 类
• 导入: import { SkillSelector } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare class SkillSelector {
    constructor(registry: SkillRegistry);
    select(context: SkillResolutionContext): SkillSelectionResult;
}

公开成员

成员	种类	签名	说明
constructor	构造函数	(registry: SkillRegistry): SkillSelector	创建该类的实例。
select	方法	select(context: SkillResolutionContext): SkillSelectionResult	公开方法；参数与返回类型以签名列为准。

skillActivationPolicySchema

Skill Activation Policy 的运行时 Schema。

• 种类: 常量
• 导入: import { skillActivationPolicySchema } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillActivationPolicySchema: z.ZodObject<{ mode: z.ZodEnum<["always", "keyword", "regex", "intent", "manual"]>; patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strip", z.ZodTypeAny, { mode: "always" | "keyword" | "regex" | "intent" | "manual"; patterns?: string[] | undefined; }, { mode: "always" | "keyword" | "regex" | "intent" | "manual"; patterns?: string[] | undefined; }>;

skillAssetRefSchema

Skill Asset Ref 的运行时 Schema。

• 种类: 常量
• 导入: import { skillAssetRefSchema } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillAssetRefSchema: z.ZodObject<{ path: z.ZodString; type: z.ZodEnum<["reference", "script", "asset"]>; loadPolicy: z.ZodOptional<z.ZodEnum<["frontmatter_only", "on_activation", "never"]>>; }, "strip", z.ZodTypeAny, { path: string; type: "reference" | "script" | "asset"; loadPolicy?: "never" | "frontmatter_only" | "on_activation" | undefined; }, { path: string; type: "reference" | "script" | "asset"; loadPolicy?: "never" | "frontmatter_only" | "on_activation" | undefined; }>;

skillRefSchema

Skill Ref 的运行时 Schema。

• 种类: 常量
• 导入: import { skillRefSchema } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillRefSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { id: string; version?: string | undefined; }, { id: string; version?: string | undefined; }>;

skillSpecDefinition

Skill Spec 的运行时校验入口，组合 Parser、Example 与 JSON Schema。

• 种类: 常量
• 导入: import { skillSpecDefinition } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillSpecDefinition: SpecSchemaDefinition<SkillSpec>;

skillSpecDefinitions

由 index 模块导出的 Skill Spec Definitions 常量。

• 种类: 常量
• 导入: import { skillSpecDefinitions } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillSpecDefinitions: readonly [SpecSchemaDefinition<SkillSpec>];

skillSpecExample

Skill Spec 的有效示例值。

• 种类: 常量
• 导入: import { skillSpecExample } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillSpecExample: SkillSpec;

skillSpecJsonSchema

Skill Spec 的 JSON Schema。

• 种类: 常量
• 导入: import { skillSpecJsonSchema } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillSpecJsonSchema: JsonSchema;

skillSpecJsonSchemas

由 index 模块导出的 Skill Spec JSON Schemas 常量。

• 种类: 常量
• 导入: import { skillSpecJsonSchemas } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare const skillSpecJsonSchemas: Record<string, JsonSchema>;

skillSpecSchema

Skill Spec 的运行时 Schema。

• 种类: 常量
• 导入: import { skillSpecSchema } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

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

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

createEffectiveAgentCapabilitySnapshot

Create Effective Agent Capability Snapshot 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { createEffectiveAgentCapabilitySnapshot } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function createEffectiveAgentCapabilitySnapshot(input: EffectiveAgentCapabilitySnapshotInput): Readonly<EffectiveAgentCapabilitySnapshot>;

调用签名

createEffectiveAgentCapabilitySnapshot(input: EffectiveAgentCapabilitySnapshotInput): Readonly<EffectiveAgentCapabilitySnapshot>

参数

参数	类型	必需	说明
input	EffectiveAgentCapabilitySnapshotInput	是	必需参数；接受的值由类型列定义。

返回值

• 类型: Readonly<EffectiveAgentCapabilitySnapshot>
• 说明: 返回值契约由上述类型定义。

listLocalSkillFiles

List Local Skill Files 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { listLocalSkillFiles } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function listLocalSkillFiles(directory: string, recursive?: boolean): Promise<string[]>;

调用签名

listLocalSkillFiles(directory: string, recursive?: boolean): Promise<string[]>

参数

参数	类型	必需	说明
directory	string	是	必需参数；接受的值由类型列定义。
recursive	boolean	否	可选参数；接受的值由类型列定义。

返回值

• 类型: Promise<string[]>
• 说明: 返回值契约由上述类型定义。

loadSkillMarkdownFile

Load Skill Markdown File 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { loadSkillMarkdownFile } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function loadSkillMarkdownFile(filePath: string): Promise<ParsedSkillMarkdown>;

调用签名

loadSkillMarkdownFile(filePath: string): Promise<ParsedSkillMarkdown>

参数

参数	类型	必需	说明
filePath	string	是	必需参数；接受的值由类型列定义。

返回值

• 类型: Promise<ParsedSkillMarkdown>
• 说明: 返回值契约由上述类型定义。

parseSkillMarkdown

Parse Skill Markdown 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { parseSkillMarkdown } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function parseSkillMarkdown(raw: string, filePath: string): ParsedSkillMarkdown;

调用签名

parseSkillMarkdown(raw: string, filePath: string): ParsedSkillMarkdown

参数

参数	类型	必需	说明
raw	string	是	必需参数；接受的值由类型列定义。
filePath	string	是	必需参数；接受的值由类型列定义。

返回值

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

resolveBuiltinSkillsDirectory

Resolves the directory that ships Hypha's built-in skills (context-enrichment, intent-classification) inside this npm package. The published tarball includes builtins/ next to dist/, so consumers can load the framework built-ins without a source checkout of the Server.

• 种类: 函数
• 导入: import { resolveBuiltinSkillsDirectory } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function resolveBuiltinSkillsDirectory(): string;

调用签名

resolveBuiltinSkillsDirectory(): string

Resolves the directory that ships Hypha's built-in skills (context-enrichment, intent-classification) inside this npm package. The published tarball includes builtins/ next to dist/, so consumers can load the framework built-ins without a source checkout of the Server.

参数

无参数。

返回值

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

validateSkillSpec

Validate Skill Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { validateSkillSpec } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export declare function validateSkillSpec(input: unknown): SkillSpec;

调用签名

validateSkillSpec(input: unknown): SkillSpec

参数

参数	类型	必需	说明
input	unknown	是	必需参数；接受的值由类型列定义。

返回值

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

AgentCapabilityConstraint

Agent Capability Constraint 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { AgentCapabilityConstraint } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface AgentCapabilityConstraint {
    allowedToolIds?: string[];
    allowedMCPServerIds?: string[];
    memoryAccess?: EffectiveAgentCapabilitySnapshot['memoryAccess'];
    allowedExecutionProfiles?: string[];
    maximumSideEffectLevel?: SideEffectLevel;
    policyRefs?: string[];
}

契约成员

成员	种类	签名	说明
allowedExecutionProfiles	属性	allowedExecutionProfiles?: string[]	公开属性；类型、只读和可选状态以签名列为准。
allowedMCPServerIds	属性	allowedMCPServerIds?: string[]	公开属性；类型、只读和可选状态以签名列为准。
allowedToolIds	属性	allowedToolIds?: string[]	公开属性；类型、只读和可选状态以签名列为准。
maximumSideEffectLevel	属性	maximumSideEffectLevel?: SideEffectLevel	公开属性；类型、只读和可选状态以签名列为准。
memoryAccess	属性	memoryAccess?: "none" | "read" | "write" | "read_write"	公开属性；类型、只读和可选状态以签名列为准。
policyRefs	属性	policyRefs?: string[]	公开属性；类型、只读和可选状态以签名列为准。

EffectiveAgentCapabilitySnapshotInput

Effective Agent Capability Snapshot Input 接口，共包含 10 个公开字段或方法。

• 种类: 接口
• 导入: import type { EffectiveAgentCapabilitySnapshotInput } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface EffectiveAgentCapabilitySnapshotInput {
    runId: string;
    agentId: string;
    principalId: string;
    tenantId?: string;
    domainId?: string;
    createdAt?: string;
    expiresAt?: string;
    agent: AgentCapabilityConstraint;
    domain: AgentCapabilityConstraint;
    activeSkills: LoadedSkillContext[];
}

契约成员

成员	种类	签名	说明
activeSkills	属性	activeSkills: LoadedSkillContext[]	公开属性；类型、只读和可选状态以签名列为准。
agent	属性	agent: AgentCapabilityConstraint	公开属性；类型、只读和可选状态以签名列为准。
agentId	属性	agentId: string	公开属性；类型、只读和可选状态以签名列为准。
createdAt	属性	createdAt?: string	公开属性；类型、只读和可选状态以签名列为准。
domain	属性	domain: AgentCapabilityConstraint	公开属性；类型、只读和可选状态以签名列为准。
domainId	属性	domainId?: string	公开属性；类型、只读和可选状态以签名列为准。
expiresAt	属性	expiresAt?: string	公开属性；类型、只读和可选状态以签名列为准。
principalId	属性	principalId: string	公开属性；类型、只读和可选状态以签名列为准。
runId	属性	runId: string	公开属性；类型、只读和可选状态以签名列为准。
tenantId	属性	tenantId?: string	公开属性；类型、只读和可选状态以签名列为准。

LoadedSkillAsset

Loaded Skill Asset 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { LoadedSkillAsset } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface LoadedSkillAsset extends SkillAssetRef {
    absolutePath?: string;
    content?: string;
    truncated?: boolean;
}

契约成员

成员	种类	签名	说明
absolutePath	属性	absolutePath?: string	公开属性；类型、只读和可选状态以签名列为准。
content	属性	content?: string	公开属性；类型、只读和可选状态以签名列为准。
loadPolicy	属性	loadPolicy?: "never" | "frontmatter_only" | "on_activation"	公开属性；类型、只读和可选状态以签名列为准。
path	属性	path: string	公开属性；类型、只读和可选状态以签名列为准。
truncated	属性	truncated?: boolean	公开属性；类型、只读和可选状态以签名列为准。
type	属性	type: "reference" | "script" | "asset"	公开属性；类型、只读和可选状态以签名列为准。

LoadedSkillContext

Loaded Skill Context 接口，共包含 16 个公开字段或方法。

• 种类: 接口
• 导入: import type { LoadedSkillContext } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface LoadedSkillContext {
    id: string;
    version: string;
    name?: string;
    description: string;
    instructions?: string;
    references: LoadedSkillAsset[];
    allowedTools: string[];
    requiredTools: string[];
    requiredMCPServers: string[];
    memoryAccessPolicy?: string;
    sideEffectPolicy?: string;
    trustLevel?: SkillSpec['trustLevel'];
    provenance?: Record<string, unknown>;
    policyDecision: SkillPolicyDecision;
    activation: {
        reason: string;
        matchedPatterns: string[];
    };
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
activation	属性	activation: { reason: string; matchedPatterns: string[]; }	公开属性；类型、只读和可选状态以签名列为准。
allowedTools	属性	allowedTools: string[]	公开属性；类型、只读和可选状态以签名列为准。
description	属性	description: string	公开属性；类型、只读和可选状态以签名列为准。
id	属性	id: string	公开属性；类型、只读和可选状态以签名列为准。
instructions	属性	instructions?: string	公开属性；类型、只读和可选状态以签名列为准。
memoryAccessPolicy	属性	memoryAccessPolicy?: string	公开属性；类型、只读和可选状态以签名列为准。
metadata	属性	metadata?: Record<string, unknown>	公开属性；类型、只读和可选状态以签名列为准。
name	属性	name?: string	公开属性；类型、只读和可选状态以签名列为准。
policyDecision	属性	policyDecision: SkillPolicyDecision	公开属性；类型、只读和可选状态以签名列为准。
provenance	属性	provenance?: Record<string, unknown>	公开属性；类型、只读和可选状态以签名列为准。
references	属性	references: LoadedSkillAsset[]	公开属性；类型、只读和可选状态以签名列为准。
requiredMCPServers	属性	requiredMCPServers: string[]	公开属性；类型、只读和可选状态以签名列为准。
requiredTools	属性	requiredTools: string[]	公开属性；类型、只读和可选状态以签名列为准。
sideEffectPolicy	属性	sideEffectPolicy?: string	公开属性；类型、只读和可选状态以签名列为准。
trustLevel	属性	trustLevel?: "trusted" | "reviewed" | "untrusted"	公开属性；类型、只读和可选状态以签名列为准。
version	属性	version: string	公开属性；类型、只读和可选状态以签名列为准。

LocalSkillLoaderOptions

Local Skill Loader Options 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { LocalSkillLoaderOptions } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface LocalSkillLoaderOptions {
    directories: string[];
    recursive?: boolean;
    includeDisabled?: boolean;
}

契约成员

成员	种类	签名	说明
directories	属性	directories: string[]	公开属性；类型、只读和可选状态以签名列为准。
includeDisabled	属性	includeDisabled?: boolean	公开属性；类型、只读和可选状态以签名列为准。
recursive	属性	recursive?: boolean	公开属性；类型、只读和可选状态以签名列为准。

ParsedSkillMarkdown

Parsed Skill Markdown 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { ParsedSkillMarkdown } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface ParsedSkillMarkdown {
    filePath: string;
    slug: string;
    spec: SkillSpec;
}

契约成员

成员	种类	签名	说明
filePath	属性	filePath: string	公开属性；类型、只读和可选状态以签名列为准。
slug	属性	slug: string	公开属性；类型、只读和可选状态以签名列为准。
spec	属性	spec: SkillSpec	公开属性；类型、只读和可选状态以签名列为准。

ResolvedSkill

Resolved Skill 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { ResolvedSkill } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface ResolvedSkill {
    spec: SkillSpec;
    loadedInstructions?: string;
    loadedReferences: SkillAssetRef[];
}

契约成员

成员	种类	签名	说明
loadedInstructions	属性	loadedInstructions?: string	公开属性；类型、只读和可选状态以签名列为准。
loadedReferences	属性	loadedReferences: SkillAssetRef[]	公开属性；类型、只读和可选状态以签名列为准。
spec	属性	spec: SkillSpec	公开属性；类型、只读和可选状态以签名列为准。

SkillActivationPolicy

Skill Activation Policy 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillActivationPolicy } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillActivationPolicy {
    mode: SkillActivationMode;
    patterns?: string[];
}

契约成员

成员	种类	签名	说明
mode	属性	mode: SkillActivationMode	公开属性；类型、只读和可选状态以签名列为准。
patterns	属性	patterns?: string[]	公开属性；类型、只读和可选状态以签名列为准。

SkillAssetRef

Skill Asset Ref 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillAssetRef } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillAssetRef {
    path: string;
    type: 'reference' | 'script' | 'asset';
    loadPolicy?: 'frontmatter_only' | 'on_activation' | 'never';
}

契约成员

成员	种类	签名	说明
loadPolicy	属性	loadPolicy?: "never" | "frontmatter_only" | "on_activation"	公开属性；类型、只读和可选状态以签名列为准。
path	属性	path: string	公开属性；类型、只读和可选状态以签名列为准。
type	属性	type: "reference" | "script" | "asset"	公开属性；类型、只读和可选状态以签名列为准。

SkillContextLoadInput

Skill Context Load Input 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillContextLoadInput } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillContextLoadInput {
    selection: SkillSelection;
    policyDecision: SkillPolicyDecision;
    maxChars?: number;
}

契约成员

成员	种类	签名	说明
maxChars	属性	maxChars?: number	公开属性；类型、只读和可选状态以签名列为准。
policyDecision	属性	policyDecision: SkillPolicyDecision	公开属性；类型、只读和可选状态以签名列为准。
selection	属性	selection: SkillSelection	公开属性；类型、只读和可选状态以签名列为准。

SkillLoader

Skill Loader 接口，共包含 1 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillLoader } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillLoader {
    load(): Promise<SkillSpec[]>;
}

契约成员

成员	种类	签名	说明
load	方法	load(): Promise<SkillSpec[]>	公开方法；参数与返回类型以签名列为准。

SkillPolicy

Skill Policy 接口，共包含 1 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillPolicy } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillPolicy {
    evaluate(input: SkillPolicyInput): Promise<SkillPolicyDecision>;
}

契约成员

成员	种类	签名	说明
evaluate	方法	evaluate(input: SkillPolicyInput): Promise<SkillPolicyDecision>	公开方法；参数与返回类型以签名列为准。

SkillPolicyDecision

Skill Policy Decision 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillPolicyDecision } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillPolicyDecision {
    allowed: boolean;
    reason?: string;
    requiresHumanReview?: boolean;
    allowedTools: string[];
    policyId?: string;
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
allowed	属性	allowed: boolean	公开属性；类型、只读和可选状态以签名列为准。
allowedTools	属性	allowedTools: string[]	公开属性；类型、只读和可选状态以签名列为准。
metadata	属性	metadata?: Record<string, unknown>	公开属性；类型、只读和可选状态以签名列为准。
policyId	属性	policyId?: string	公开属性；类型、只读和可选状态以签名列为准。
reason	属性	reason?: string	公开属性；类型、只读和可选状态以签名列为准。
requiresHumanReview	属性	requiresHumanReview?: boolean	公开属性；类型、只读和可选状态以签名列为准。

SkillPolicyInput

Skill Policy Input 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillPolicyInput } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillPolicyInput {
    selection: SkillSelection;
    context: SkillResolutionContext;
}

契约成员

成员	种类	签名	说明
context	属性	context: SkillResolutionContext	公开属性；类型、只读和可选状态以签名列为准。
selection	属性	selection: SkillSelection	公开属性；类型、只读和可选状态以签名列为准。

SkillRef

Skill Ref 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillRef } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillRef {
    id: string;
    version?: string;
}

契约成员

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

SkillResolutionContext

Skill Resolution Context 接口，共包含 8 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillResolutionContext } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillResolutionContext {
    agentSkillRefs: SkillRef[];
    intent?: string;
    inputText?: string;
    allowedSkills?: string[];
    requiredSkills?: string[];
    manualSkillIds?: string[];
    availableToolRefs?: string[];
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
agentSkillRefs	属性	agentSkillRefs: SkillRef[]	公开属性；类型、只读和可选状态以签名列为准。
allowedSkills	属性	allowedSkills?: string[]	公开属性；类型、只读和可选状态以签名列为准。
availableToolRefs	属性	availableToolRefs?: string[]	公开属性；类型、只读和可选状态以签名列为准。
inputText	属性	inputText?: string	公开属性；类型、只读和可选状态以签名列为准。
intent	属性	intent?: string	公开属性；类型、只读和可选状态以签名列为准。
manualSkillIds	属性	manualSkillIds?: string[]	公开属性；类型、只读和可选状态以签名列为准。
metadata	属性	metadata?: Record<string, unknown>	公开属性；类型、只读和可选状态以签名列为准。
requiredSkills	属性	requiredSkills?: string[]	公开属性；类型、只读和可选状态以签名列为准。

SkillSelection

Skill Selection 接口，共包含 4 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillSelection } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillSelection {
    spec: SkillSpec;
    reason: string;
    matchedPatterns: string[];
    priority: number;
}

契约成员

成员	种类	签名	说明
matchedPatterns	属性	matchedPatterns: string[]	公开属性；类型、只读和可选状态以签名列为准。
priority	属性	priority: number	公开属性；类型、只读和可选状态以签名列为准。
reason	属性	reason: string	公开属性；类型、只读和可选状态以签名列为准。
spec	属性	spec: SkillSpec	公开属性；类型、只读和可选状态以签名列为准。

SkillSelectionRejection

Skill Selection Rejection 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillSelectionRejection } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillSelectionRejection {
    skillId: string;
    reason: string;
}

契约成员

成员	种类	签名	说明
reason	属性	reason: string	公开属性；类型、只读和可选状态以签名列为准。
skillId	属性	skillId: string	公开属性；类型、只读和可选状态以签名列为准。

SkillSelectionResult

Skill Selection Result 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillSelectionResult } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillSelectionResult {
    selected: SkillSelection[];
    rejected: SkillSelectionRejection[];
}

契约成员

成员	种类	签名	说明
rejected	属性	rejected: SkillSelectionRejection[]	公开属性；类型、只读和可选状态以签名列为准。
selected	属性	selected: SkillSelection[]	公开属性；类型、只读和可选状态以签名列为准。

SkillSpec

Skill Spec 接口，共包含 26 个公开字段或方法。

• 种类: 接口
• 导入: import type { SkillSpec } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export interface SkillSpec extends VersionedSpec, SpecMetadata {
    id: string;
    version: string;
    name?: string;
    description: string;
    enabled?: boolean;
    priority?: number;
    activationPolicy?: SkillActivationPolicy;
    instructions?: string;
    references?: SkillAssetRef[];
    scripts?: SkillAssetRef[];
    assets?: SkillAssetRef[];
    allowedTools?: string[];
    requiredTools?: string[];
    requiredMCPServers?: string[];
    memoryAccessPolicy?: string;
    sideEffectPolicy?: string;
    contextBudget?: number;
    inputSchema?: JsonSchema;
    outputContract?: JsonSchema;
    evaluationCases?: string[];
    provenance?: Record<string, unknown>;
    trustLevel?: 'trusted' | 'reviewed' | 'untrusted';
}

契约成员

成员	种类	签名	说明
activationPolicy	属性	activationPolicy?: SkillActivationPolicy	公开属性；类型、只读和可选状态以签名列为准。
allowedTools	属性	allowedTools?: string[]	公开属性；类型、只读和可选状态以签名列为准。
assets	属性	assets?: SkillAssetRef[]	公开属性；类型、只读和可选状态以签名列为准。
contextBudget	属性	contextBudget?: number	公开属性；类型、只读和可选状态以签名列为准。
createdAt	属性	createdAt?: string	公开属性；类型、只读和可选状态以签名列为准。
description	属性	description: string	公开属性；类型、只读和可选状态以签名列为准。
enabled	属性	enabled?: boolean	公开属性；类型、只读和可选状态以签名列为准。
evaluationCases	属性	evaluationCases?: string[]	公开属性；类型、只读和可选状态以签名列为准。
id	属性	id: string	公开属性；类型、只读和可选状态以签名列为准。
inputSchema	属性	inputSchema?: JsonSchema	公开属性；类型、只读和可选状态以签名列为准。
instructions	属性	instructions?: string	公开属性；类型、只读和可选状态以签名列为准。
memoryAccessPolicy	属性	memoryAccessPolicy?: string	公开属性；类型、只读和可选状态以签名列为准。
name	属性	name?: string	公开属性；类型、只读和可选状态以签名列为准。
outputContract	属性	outputContract?: JsonSchema	公开属性；类型、只读和可选状态以签名列为准。
owner	属性	owner?: string	公开属性；类型、只读和可选状态以签名列为准。
priority	属性	priority?: number	公开属性；类型、只读和可选状态以签名列为准。
provenance	属性	provenance?: Record<string, unknown>	公开属性；类型、只读和可选状态以签名列为准。
references	属性	references?: SkillAssetRef[]	公开属性；类型、只读和可选状态以签名列为准。
requiredMCPServers	属性	requiredMCPServers?: string[]	公开属性；类型、只读和可选状态以签名列为准。
requiredTools	属性	requiredTools?: string[]	公开属性；类型、只读和可选状态以签名列为准。
scripts	属性	scripts?: SkillAssetRef[]	公开属性；类型、只读和可选状态以签名列为准。
sideEffectPolicy	属性	sideEffectPolicy?: string	公开属性；类型、只读和可选状态以签名列为准。
tags	属性	tags?: string[]	公开属性；类型、只读和可选状态以签名列为准。
trustLevel	属性	trustLevel?: "trusted" | "reviewed" | "untrusted"	公开属性；类型、只读和可选状态以签名列为准。
updatedAt	属性	updatedAt?: string	公开属性；类型、只读和可选状态以签名列为准。
version	属性	version: string	公开属性；类型、只读和可选状态以签名列为准。

SkillActivationMode

Skill Activation Mode 公共类型别名；完整类型表达式见声明。

• 种类: 类型
• 导入: import type { SkillActivationMode } from '@codesoul-co/hypha-skills';
• 源码模块: index

声明

export type SkillActivationMode = 'always' | 'keyword' | 'regex' | 'intent' | 'manual';