@actiondock/core 2.18.0 → 2.20.0

package/dist/package/runtime.js

@@ -5,7 +5,8 @@ import { createNodePlatform } from "../platform/index.js";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { RuntimeConfig } from "../runtime/context.js";
 import { normalizeActionCollection } from "../runtime/action-collection.js";
-import { isSecretConfigKey, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { redactConfigValue, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { assertConcreteConfigKey, assertValidConfigDeclarations, isConfigTemplate, resolveConfigDeclaration, validateConfigValue, } from "../project/config-declarations.js";
 import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
 import { createPackageIdentity } from "../runtime/identity.js";
 import { ACTION_NOT_FOUND, ActionDockError, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, INVOCATION_UNSUPPORTED, NOT_FOUND, SERVICE_CLOSED, } from "../errors.js";
@@ -127,6 +128,9 @@ export class DefaultPackageRuntime {
             };
         }
         this.packageRoot = packageRoot;
+        if (projectConfig.config !== undefined) {
+            assertValidConfigDeclarations(projectConfig.config);
+        }
         this.projectConfig = projectConfig;
         // 兼容未在公开选项契约中显式声明的包实例标识与代系标识内部参数透传
         this.identity = options.identity || createPackageIdentity({
@@ -679,9 +683,18 @@ export class DefaultPackageRuntime {
     }
     async listConfig() {
         this.assertOpen();
-        const declared = this.projectConfig.config || {};
-        const stored = (await this.prepareStorageAsync()).listConfig();
-        const allKeys = Array.from(new Set([...Object.keys(declared), ...Object.keys(stored)]));
+        const packageStorage = await this.prepareStorageAsync();
+        const globalStorage = await this.ensureGlobalStorage();
+        const declaredKeys = Object.keys(this.projectConfig.config || {}).filter((k) => !isConfigTemplate(k));
+        const packageStoredKeys = Object.keys(packageStorage.listConfig());
+        const globalStoredKeys = Object.keys(globalStorage.listConfig());
+        const overrideKeys = Object.keys(this.options.configOverrides || {});
+        const allKeys = Array.from(new Set([
+            ...declaredKeys,
+            ...packageStoredKeys,
+            ...globalStoredKeys,
+            ...overrideKeys,
+        ])).filter((k) => !isConfigTemplate(k));
         const views = [];
         for (const key of allKeys) {
             const item = await this.getConfig(key);
@@ -693,27 +706,33 @@ export class DefaultPackageRuntime {
     }
     async getConfig(key) {
         this.assertOpen();
-        const itemDef = this.projectConfig.config?.[key];
-        const isSecret = isSecretConfigKey(key, itemDef);
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
         // 委托 RuntimeConfig 五层优先级链单一事实源，避免重复实现解析链
         const resolved = this.ensureRuntimeConfig().describe(key);
-        // overrides 来源对外统一星现为包级覆盖视角
-        const source = resolved.source === "overrides" ? "package" : resolved.source;
-        const configured = resolved.source !== "default";
+        // configured 显式判定：仅真实显式来源（override/package/global/env）为 true，
+        // default 与整链未命中（source null）均为 false，不得依赖与 "default" 的不等比较
+        const configured = resolved.source !== null && resolved.source !== "default";
+        const redacted = redactConfigValue(resolved.value, decl?.item);
         return {
             key,
             configured,
-            secret: isSecret,
-            source,
-            value: isSecret ? undefined : resolved.value,
+            secret: redacted.secret,
+            source: resolved.source,
+            value: redacted.value,
+            redactedPaths: redacted.redactedPaths,
         };
     }
     async setConfig(key, value) {
         this.assertOpen();
+        assertConcreteConfigKey(key);
+        const decl = resolveConfigDeclaration(this.projectConfig.config, key);
+        validateConfigValue(key, value, decl?.item);
         await (await this.prepareStorageAsync()).setConfig(key, value);
     }
     async deleteConfig(key) {
         this.assertOpen();
+        assertConcreteConfigKey(key);
         return await (await this.prepareStorageAsync()).deleteConfig(key);
     }
     /**
@@ -851,13 +870,31 @@ export class DefaultPackageRuntime {
             if (typeof storage.listRunsByRequestIds !== "function") {
                 return [];
             }
-            let records = storage.listRunsByRequestIds(options.requestIds);
+            let records = storage.listRunsByRequestIds(options.requestIds, options);
             if (options.actionId) {
                 records = records.filter((r) => r.actionId === options.actionId);
             }
             if (options.status) {
                 records = records.filter((r) => r.status === options.status);
             }
+            if (options.channel) {
+                records = records.filter((r) => r.origin?.channel === options.channel);
+            }
+            if (options.view) {
+                records = records.filter((r) => r.origin?.viewName === options.view);
+            }
+            if (options.since) {
+                records = records.filter((r) => r.startedAt >= options.since);
+            }
+            if (options.until) {
+                records = records.filter((r) => r.startedAt <= options.until);
+            }
+            if (options.rootRunId) {
+                records = records.filter((r) => r.rootRunId === options.rootRunId);
+            }
+            if (options.parentRunId) {
+                records = records.filter((r) => r.parentRunId === options.parentRunId);
+            }
             records.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
             if (typeof options.offset === "number" && options.offset > 0) {
                 records = records.slice(options.offset);
@@ -870,6 +907,12 @@ export class DefaultPackageRuntime {
         const records = storage.listRuns({
             actionId: options?.actionId,
             status: options?.status,
+            channel: options?.channel,
+            view: options?.view,
+            since: options?.since,
+            until: options?.until,
+            rootRunId: options?.rootRunId,
+            parentRunId: options?.parentRunId,
             limit: options?.limit,
             offset: options?.offset,
         });
@@ -897,18 +940,42 @@ export class DefaultPackageRuntime {
             return storage.countRuns({
                 actionId: options?.actionId,
                 status: options?.status,
+                channel: options?.channel,
+                view: options?.view,
+                since: options?.since,
+                until: options?.until,
+                rootRunId: options?.rootRunId,
+                parentRunId: options?.parentRunId,
                 requestIds: options?.requestIds,
             });
         }
         if (options?.requestIds && options.requestIds.length > 0) {
             if (typeof storage.listRunsByRequestIds === "function") {
-                let records = storage.listRunsByRequestIds(options.requestIds);
+                let records = storage.listRunsByRequestIds(options.requestIds, options);
                 if (options.actionId) {
                     records = records.filter((r) => r.actionId === options.actionId);
                 }
                 if (options.status) {
                     records = records.filter((r) => r.status === options.status);
                 }
+                if (options.channel) {
+                    records = records.filter((r) => r.origin?.channel === options.channel);
+                }
+                if (options.view) {
+                    records = records.filter((r) => r.origin?.viewName === options.view);
+                }
+                if (options.since) {
+                    records = records.filter((r) => r.startedAt >= options.since);
+                }
+                if (options.until) {
+                    records = records.filter((r) => r.startedAt <= options.until);
+                }
+                if (options.rootRunId) {
+                    records = records.filter((r) => r.rootRunId === options.rootRunId);
+                }
+                if (options.parentRunId) {
+                    records = records.filter((r) => r.parentRunId === options.parentRunId);
+                }
                 return records.length;
             }
             return 0;
@@ -916,9 +983,32 @@ export class DefaultPackageRuntime {
         const records = storage.listRuns({
             actionId: options?.actionId,
             status: options?.status,
+            channel: options?.channel,
+            view: options?.view,
+            since: options?.since,
+            until: options?.until,
+            rootRunId: options?.rootRunId,
+            parentRunId: options?.parentRunId,
             limit: 100_000,
         });
-        return records.length;
+        let filtered = records;
+        if (options?.actionId)
+            filtered = filtered.filter((r) => r.actionId === options.actionId);
+        if (options?.status)
+            filtered = filtered.filter((r) => r.status === options.status);
+        if (options?.channel)
+            filtered = filtered.filter((r) => r.origin?.channel === options.channel);
+        if (options?.view)
+            filtered = filtered.filter((r) => r.origin?.viewName === options.view);
+        if (options?.since)
+            filtered = filtered.filter((r) => r.startedAt >= options.since);
+        if (options?.until)
+            filtered = filtered.filter((r) => r.startedAt <= options.until);
+        if (options?.rootRunId)
+            filtered = filtered.filter((r) => r.rootRunId === options.rootRunId);
+        if (options?.parentRunId)
+            filtered = filtered.filter((r) => r.parentRunId === options.parentRunId);
+        return filtered.length;
     }
     async clearRuns(options) {
         this.assertOpen();

package/dist/platform/types.d.ts

@@ -1,8 +1,9 @@
-import type { ProcessAPI } from "@actiondock/sdk";
+import type { ActionInvokeOptions, ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../storage/clock.js";
 import type { ModuleLoader } from "./module-loader.js";
 import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 import type { EventSink } from "../runtime/events.js";
+import type { PackageRuntime } from "../package/types.js";
 /**
  * 跨运行时持久化存储工厂配置选项。
  */
@@ -42,6 +43,48 @@ export interface StorageFactory {
      */
     createGlobalStorage(options?: GlobalStorageFactoryOptions): RuntimeStorage;
 }
+/**
+ * 动作调用目标解析结果。
+ */
+export interface InvocationTargetResolution {
+    /** 目标 PackageRuntime 实例 */
+    readonly runtime: PackageRuntime;
+    /** 可选调用作用域，用于区分调用目标与环路死锁检测身份 */
+    readonly scope?: string;
+    /** 是否强制要求调用方显式声明 uses 依赖 */
+    readonly requiresExplicitUses?: boolean;
+}
+/**
+ * 动作调用发起方元数据信息。
+ */
+export interface InvocationCallerInfo {
+    /** 调用发起方包标识 */
+    readonly packageId: string;
+    /** 调用发起方 Action 动作标识 */
+    readonly actionId?: string;
+}
+/**
+ * 运行时平台调用目标解析器端口契约。
+ * 允许底层运行时平台在 Host 选择执行目标阶段介入目标解析，提供自定义 PackageRuntime。
+ */
+export interface InvocationTargetResolver {
+    /**
+     * 解析指定 Action 引用与调用选项对应的目标 PackageRuntime。
+     *
+     * @param action 规范化 Action 引用元数据
+     * @param options 动作调用选项（包含命名 binding 等）
+     * @param caller 发起调用的调用方元数据
+     * @returns 目标解析结果；返回的 Runtime 由 Host 接管生命周期；未命中返回 undefined 交由默认主链处理
+     */
+    resolve(action: {
+        packageId: string;
+        actionId: string;
+    }, options: ActionInvokeOptions | undefined, caller: InvocationCallerInfo): InvocationTargetResolution | undefined;
+    /**
+     * 清理端口缓存和附属资源，不重复关闭已移交 Host 的 Runtime。
+     */
+    close?(): Promise<void>;
+}
 /**
  * 运行时底层环境核心标准契约。
  * 提供统一的运行时契约，屏蔽宿主平台与测试沙箱环境的实现差异。
@@ -61,4 +104,8 @@ export interface RuntimePlatform {
      * 可选执行事件接收器，宿主可注入，缺省由上层默认构造。
      */
     readonly eventSink?: EventSink;
+    /**
+     * 可选动作调用目标解析器端口，用于宿主环境自定义动作调用路由（例如测试具名 Mock 模拟目标）。
+     */
+    readonly invocationTargets?: InvocationTargetResolver;
 }

package/dist/project/config-declarations.d.ts

@@ -0,0 +1,61 @@
+import type { ConfigItemDefinition } from "./types.js";
+/**
+ * 判定指定配置键名是否为通配模板键。
+ *
+ * @param key 待检测的配置键名
+ */
+export declare function isConfigTemplate(key: string): boolean;
+/**
+ * 断言键名为具体配置键，拒绝空字符串、非字符串以及模板通配键。
+ *
+ * @param key 待检查的具体配置键名
+ */
+export declare function assertConcreteConfigKey(key: string): void;
+/**
+ * 解析配置项命中结果结构。
+ */
+export interface ResolvedConfigDeclaration {
+    /** 命中声明所登记的原始键名（具体键或模板键） */
+    key: string;
+    /** 声明的配置定义元数据 */
+    item: ConfigItemDefinition;
+    /** 若通过模板匹配命中，则返回命中的模板表达式 */
+    template?: string;
+}
+/**
+ * 解析并匹配指定配置键在声明字典中的定义项。
+ *
+ * 匹配优先级规则：
+ * - 具体声明键严格优先于任何模板通配键；
+ * - 模板只允许包含单个星号（*），匹配一个或多个合法标识字符（[A-Za-z0-9_.-]）；
+ * - 多个模板同时命中时，优先选取前缀最长者，前缀长度相同时选取后缀最长者，杜绝对象枚举遍历顺序影响。
+ *
+ * @param config 声明的配置定义字典
+ * @param key 实际访问或配置的具体键名
+ */
+export declare function resolveConfigDeclaration(config: Record<string, ConfigItemDefinition> | undefined, key: string): ResolvedConfigDeclaration | undefined;
+/**
+ * 校验配置声明集合中的通配模板与受限 Schema 规范。
+ * 针对历史无模板、无 Schema 项保持完全兼容。
+ *
+ * @param config 待校验的配置声明定义
+ * @returns 错误信息字符串数组，无错误返回空数组
+ */
+export declare function validateConfigDeclarations(config: unknown): string[];
+/**
+ * 断言配置声明集合完全合法。
+ * 若存在非法模板或不合规 Schema 抛出 MANIFEST_INVALID 异常。
+ *
+ * @param config 待校验的配置声明定义
+ */
+export declare function assertValidConfigDeclarations(config: unknown): void;
+/**
+ * 校验指定配置数据值是否符合绑定的 Schema 契约。
+ * 仅在声明了 schema 且数据值不为 undefined 时执行校验。
+ * 错误信息输出键名与失败路径原因，严禁包含实际数据值。
+ *
+ * @param key 配置项键名
+ * @param value 待校验的具体数据值
+ * @param item 配置项元数据定义
+ */
+export declare function validateConfigValue(key: string, value: unknown, item?: ConfigItemDefinition): void;

package/dist/project/config-declarations.js

@@ -0,0 +1,297 @@
+import { ActionDockError, CONFIG_VALUE_INVALID, INVALID_ARGUMENT, MANIFEST_INVALID, } from "../errors.js";
+import { validateSchema, validateSchemaOnly } from "../schema/validator.js";
+/**
+ * 判定指定配置键名是否为通配模板键。
+ *
+ * @param key 待检测的配置键名
+ */
+export function isConfigTemplate(key) {
+    return typeof key === "string" && key.includes("*");
+}
+/**
+ * 断言键名为具体配置键，拒绝空字符串、非字符串以及模板通配键。
+ *
+ * @param key 待检查的具体配置键名
+ */
+export function assertConcreteConfigKey(key) {
+    if (typeof key !== "string" || key.length === 0 || key.includes("*")) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Concrete configuration key expected, received invalid key: '${key}'`);
+    }
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * 解析并匹配指定配置键在声明字典中的定义项。
+ *
+ * 匹配优先级规则：
+ * - 具体声明键严格优先于任何模板通配键；
+ * - 模板只允许包含单个星号（*），匹配一个或多个合法标识字符（[A-Za-z0-9_.-]）；
+ * - 多个模板同时命中时，优先选取前缀最长者，前缀长度相同时选取后缀最长者，杜绝对象枚举遍历顺序影响。
+ *
+ * @param config 声明的配置定义字典
+ * @param key 实际访问或配置的具体键名
+ */
+export function resolveConfigDeclaration(config, key) {
+    if (!config || typeof config !== "object" || typeof key !== "string") {
+        return undefined;
+    }
+    // 具体键严格优先
+    if (Object.prototype.hasOwnProperty.call(config, key)) {
+        return {
+            key,
+            item: config[key],
+        };
+    }
+    const candidates = [];
+    for (const [declaredKey, item] of Object.entries(config)) {
+        if (!isConfigTemplate(declaredKey)) {
+            continue;
+        }
+        const parts = declaredKey.split("*");
+        if (parts.length !== 2) {
+            continue;
+        }
+        const [prefix, suffix] = parts;
+        const pattern = new RegExp(`^${escapeRegex(prefix)}([A-Za-z0-9_.-]+)${escapeRegex(suffix)}$`);
+        if (pattern.exec(key)?.[0] === key) {
+            candidates.push({
+                templateKey: declaredKey,
+                item,
+                prefixLength: prefix.length,
+                suffixLength: suffix.length,
+            });
+        }
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    // 判定最长前缀再最长后缀，稳定按字典序平局兜底
+    candidates.sort((a, b) => {
+        if (b.prefixLength !== a.prefixLength) {
+            return b.prefixLength - a.prefixLength;
+        }
+        if (b.suffixLength !== a.suffixLength) {
+            return b.suffixLength - a.suffixLength;
+        }
+        return a.templateKey.localeCompare(b.templateKey);
+    });
+    const best = candidates[0];
+    return {
+        key: best.templateKey,
+        item: best.item,
+        template: best.templateKey,
+    };
+}
+/** 受限 JSON Schema 允许的白名单关键字集合 */
+const ALLOWED_SCHEMA_KEYWORDS = new Set([
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "secret",
+]);
+/** 模板键中严禁声明的保留字段 */
+const FORBIDDEN_TEMPLATE_FIELDS = ["required", "default", "env"];
+function validateSchemaNode(schemaNode, path, errors) {
+    if (typeof schemaNode !== "object" || schemaNode === null || Array.isArray(schemaNode)) {
+        errors.push(`Schema at '${path}' must be an object`);
+        return;
+    }
+    for (const k of Object.keys(schemaNode)) {
+        if (!ALLOWED_SCHEMA_KEYWORDS.has(k)) {
+            errors.push(`Schema at '${path}' contains unsupported keyword '${k}'`);
+        }
+    }
+    const node = schemaNode;
+    if (node.type !== undefined) {
+        if (typeof node.type !== "string" ||
+            !["object", "array", "string", "integer", "number", "boolean"].includes(node.type)) {
+            errors.push(`Schema at '${path}' property 'type' must be one of "object", "array", "string", "integer", "number", "boolean"`);
+        }
+    }
+    if (node.properties !== undefined) {
+        if (typeof node.properties !== "object" ||
+            node.properties === null ||
+            Array.isArray(node.properties)) {
+            errors.push(`Schema at '${path}' property 'properties' must be an object`);
+        }
+        else {
+            for (const [propName, child] of Object.entries(node.properties)) {
+                validateSchemaNode(child, `${path}/properties/${propName}`, errors);
+            }
+        }
+    }
+    if (node.required !== undefined) {
+        if (!Array.isArray(node.required) ||
+            node.required.some((r) => typeof r !== "string")) {
+            errors.push(`Schema at '${path}' property 'required' must be an array of strings`);
+        }
+    }
+    if (node.additionalProperties !== undefined) {
+        if (typeof node.additionalProperties === "boolean") {
+            // 允许布尔配置
+        }
+        else if (typeof node.additionalProperties === "object" &&
+            node.additionalProperties !== null &&
+            !Array.isArray(node.additionalProperties)) {
+            validateSchemaNode(node.additionalProperties, `${path}/additionalProperties`, errors);
+        }
+        else {
+            errors.push(`Schema at '${path}' property 'additionalProperties' must be a boolean or a schema object`);
+        }
+    }
+    if (node.items !== undefined) {
+        if (typeof node.items === "object" &&
+            node.items !== null &&
+            !Array.isArray(node.items)) {
+            validateSchemaNode(node.items, `${path}/items`, errors);
+        }
+        else {
+            errors.push(`Schema at '${path}' property 'items' must be a schema object`);
+        }
+    }
+    if (node.enum !== undefined) {
+        if (!Array.isArray(node.enum)) {
+            errors.push(`Schema at '${path}' property 'enum' must be an array`);
+        }
+    }
+    if (node.minLength !== undefined) {
+        if (typeof node.minLength !== "number" ||
+            !Number.isInteger(node.minLength) ||
+            node.minLength < 0) {
+            errors.push(`Schema at '${path}' property 'minLength' must be a non-negative integer`);
+        }
+    }
+    if (node.maxLength !== undefined) {
+        if (typeof node.maxLength !== "number" ||
+            !Number.isInteger(node.maxLength) ||
+            node.maxLength < 0) {
+            errors.push(`Schema at '${path}' property 'maxLength' must be a non-negative integer`);
+        }
+    }
+    if (node.minimum !== undefined) {
+        if (typeof node.minimum !== "number" || !Number.isFinite(node.minimum)) {
+            errors.push(`Schema at '${path}' property 'minimum' must be a number`);
+        }
+    }
+    if (node.maximum !== undefined) {
+        if (typeof node.maximum !== "number" || !Number.isFinite(node.maximum)) {
+            errors.push(`Schema at '${path}' property 'maximum' must be a number`);
+        }
+    }
+    if (node.secret !== undefined) {
+        if (typeof node.secret !== "boolean") {
+            errors.push(`Schema at '${path}' property 'secret' must be a boolean`);
+        }
+    }
+}
+/**
+ * 校验配置声明集合中的通配模板与受限 Schema 规范。
+ * 针对历史无模板、无 Schema 项保持完全兼容。
+ *
+ * @param config 待校验的配置声明定义
+ * @returns 错误信息字符串数组，无错误返回空数组
+ */
+export function validateConfigDeclarations(config) {
+    if (config === undefined || config === null) {
+        return [];
+    }
+    if (typeof config !== "object" || Array.isArray(config)) {
+        return ["Config declaration must be an object"];
+    }
+    const errors = [];
+    for (const [key, item] of Object.entries(config)) {
+        const isTemplate = isConfigTemplate(key);
+        if (isTemplate) {
+            const starCount = (key.match(/\*/g) || []).length;
+            if (starCount !== 1) {
+                errors.push(`Config template key '${key}' must contain exactly one '*' wildcard`);
+            }
+            if (item && typeof item === "object") {
+                for (const forbidden of FORBIDDEN_TEMPLATE_FIELDS) {
+                    if (forbidden in item) {
+                        errors.push(`Config template '${key}' must not declare '${forbidden}' property`);
+                    }
+                }
+            }
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            if (isTemplate)
+                errors.push(`Config template '${key}' must declare an object`);
+            continue;
+        }
+        const itemDef = item;
+        if ((isTemplate || "schema" in itemDef) && itemDef.secret !== undefined && typeof itemDef.secret !== "boolean") {
+            errors.push(`Config item '${key}' property 'secret' must be a boolean`);
+        }
+        if ("schema" in itemDef && itemDef.schema !== undefined) {
+            if (typeof itemDef.schema !== "object" ||
+                itemDef.schema === null ||
+                Array.isArray(itemDef.schema)) {
+                errors.push(`Config item '${key}' schema must be an object`);
+                continue;
+            }
+            // 递归白名单与属性类型校验
+            validateSchemaNode(itemDef.schema, `config['${key}'].schema`, errors);
+            // 外层 type 与根 schema.type 一致性检查（外层 number 与模式 integer 允许兼容）
+            if (itemDef.type !== undefined && itemDef.schema.type !== undefined) {
+                if (itemDef.type === "number") {
+                    if (itemDef.schema.type !== "number" && itemDef.schema.type !== "integer") {
+                        errors.push(`Config item '${key}' outer type 'number' is incompatible with schema type '${itemDef.schema.type}'`);
+                    }
+                }
+                else if (itemDef.type !== itemDef.schema.type) {
+                    errors.push(`Config item '${key}' outer type '${itemDef.type}' is incompatible with schema type '${itemDef.schema.type}'`);
+                }
+            }
+            // 利用现有 Ajv 进行 Schema 编译合法性校验
+            const ajvCheck = validateSchemaOnly(itemDef.schema, {});
+            if (!ajvCheck.valid && ajvCheck.errors) {
+                for (const err of ajvCheck.errors) {
+                    if (err.startsWith("Schema compilation error:")) {
+                        errors.push(`Config item '${key}' schema failed compilation: ${err}`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * 断言配置声明集合完全合法。
+ * 若存在非法模板或不合规 Schema 抛出 MANIFEST_INVALID 异常。
+ *
+ * @param config 待校验的配置声明定义
+ */
+export function assertValidConfigDeclarations(config) {
+    const errors = validateConfigDeclarations(config);
+    if (errors.length > 0) {
+        throw new ActionDockError(MANIFEST_INVALID, `Invalid configuration declarations: ${errors.join("; ")}`, { errors });
+    }
+}
+/**
+ * 校验指定配置数据值是否符合绑定的 Schema 契约。
+ * 仅在声明了 schema 且数据值不为 undefined 时执行校验。
+ * 错误信息输出键名与失败路径原因，严禁包含实际数据值。
+ *
+ * @param key 配置项键名
+ * @param value 待校验的具体数据值
+ * @param item 配置项元数据定义
+ */
+export function validateConfigValue(key, value, item) {
+    if (!item?.schema || value === undefined) {
+        return;
+    }
+    const result = validateSchema(item.schema, value);
+    if (!result.valid) {
+        const reasons = (result.errors || []).join("; ");
+        throw new ActionDockError(CONFIG_VALUE_INVALID, `Configuration value for '${key}' failed schema validation: ${reasons}`, { key, errors: result.errors });
+    }
+}

package/dist/project/index.d.ts

@@ -1,3 +1,4 @@
+export { loadActionBindings, validateActionBindings, resolveActionBinding, hasRemoteActionBinding, validateCanonicalActionRef, validateBindingName, type ActionBindings, type ActionBindingTarget, } from "../invocation/bindings.js";
 export * from "./digest.js";
 export * from "./init.js";
 export * from "./loader.js";
@@ -7,10 +8,12 @@ export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMet
 export * from "./types.js";
 export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, type TraverseDirectoryEntry, type TraverseDirectoryOptions, } from "../utils/index.js";
-export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
+export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, redactConfigValue, redactConfigValueForDeclarations, type RedactResult, } from "../storage/mask.js";
+export { isConfigTemplate, resolveConfigDeclaration, validateConfigDeclarations, assertValidConfigDeclarations, assertConcreteConfigKey, validateConfigValue, type ResolvedConfigDeclaration, } from "./config-declarations.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
-export { resolveActionInput, buildActionDescribePayload, formatActionDetail, type FormatActionDetailOptions, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, type AnnotationInspectionResult, type ActionOutputContractInput, type ActionOutputContractAnalysis, type OutputContractDiagnostic, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
+export { resolveInput, resolveActionInput, resolveValueInput, hasValueInput, parseValueLiteral, buildActionDescribePayload, formatActionDetail, type FormatActionDetailOptions, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, type AnnotationInspectionResult, type ActionOutputContractInput, type ActionOutputContractAnalysis, type OutputContractDiagnostic, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveInputOptions, type ResolveValueInputOptions, type ResolveActionInputOptions, type InputResolutionPolicy, type ReadStdinBoundedOptions, } from "../input/index.js";
 export { validateActionInputValue } from "../value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
+export { parseConfigOverrideAssignment } from "../input/config-override.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";
 export { filterWithFallbackInfo, compileIntentRegex, matchIntent, type Extractor, } from "../utils/intent.js";