@actiondock/core 2.19.0 → 2.20.0

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";

package/dist/project/index.js

@@ -1,3 +1,4 @@
+export { loadActionBindings, validateActionBindings, resolveActionBinding, hasRemoteActionBinding, validateCanonicalActionRef, validateBindingName, } from "../invocation/bindings.js";
 export * from "./digest.js";
 export * from "./init.js";
 export * from "./loader.js";
@@ -7,12 +8,14 @@ export { SNAPSHOT_TRACKED_FILES, isProjectLockHeld, acquireProjectLock, runFroze
 export * from "./types.js";
 export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, } from "../utils/index.js";
-export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
+export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, redactConfigValue, redactConfigValueForDeclarations, } from "../storage/mask.js";
+export { isConfigTemplate, resolveConfigDeclaration, validateConfigDeclarations, assertValidConfigDeclarations, assertConcreteConfigKey, validateConfigValue, } from "./config-declarations.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
 // 动作入参解析、输出契约分析、校验与格式化（含 BOM 剥离与标准输入有界读取的单一事实源转引）
-export { resolveActionInput, buildActionDescribePayload, formatActionDetail, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
+export { resolveInput, resolveActionInput, resolveValueInput, hasValueInput, parseValueLiteral, buildActionDescribePayload, formatActionDetail, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, mapInputValidationFailure, stripBom, readStdinBounded, } 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, } from "../utils/intent.js";

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.19.0",
+            "@actiondock/sdk": "^2.20.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.19.0",
+            "@actiondock/testing": "^2.20.0",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/project/loader.js

@@ -4,6 +4,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { NodeModuleLoader, unwrapDefaultExport } from "../platform/module-loader.js";
 import { ActionDockError, ACTION_LOAD_FAILED, describeActionLoadFailure, INVALID_ACTION_ID, INVALID_JSON, INVALID_PACKAGE_ID, INVALID_PLAYBOOK_ID, MANIFEST_LOAD_FAILED, PLAYBOOK_NOT_FOUND, PROJECT_CONFIG_NOT_FOUND, } from "../errors.js";
 import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
+import { assertValidConfigDeclarations } from "./config-declarations.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
  *
@@ -68,6 +69,9 @@ export function loadProjectConfig(projectRoot) {
         if (parsed.playbooksDir) {
             assertWithinProjectRoot(projectRoot, parsed.playbooksDir, "playbooksDir");
         }
+        if (parsed.config !== undefined) {
+            assertValidConfigDeclarations(parsed.config);
+        }
         return parsed;
     }
     catch (err) {

package/dist/project/manifest.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { assertValidConfigDeclarations, validateConfigDeclarations } from "./config-declarations.js";
 import { isPathOutsideBoundary, PACKAGE_ID_REGEX } from "../utils/index.js";
 import { ActionDockError, MANIFEST_CORRUPTED, MANIFEST_INVALID, MANIFEST_READ_FAILED, UNSUPPORTED_MANIFEST_SCHEMA, } from "../errors.js";
 export const MANIFEST_FILE_NAME = "actiondock.json";
@@ -38,6 +39,9 @@ export function loadManifest(projectRoot) {
     if (!parsed.id) {
         parsed.id = basename(projectRoot);
     }
+    if (parsed.config !== undefined) {
+        assertValidConfigDeclarations(parsed.config);
+    }
     return parsed;
 }
 /**
@@ -65,6 +69,12 @@ export function validateManifest(manifest, options) {
             errors.push(`Manifest 'id' is invalid: '${m.id}' (must match ${PACKAGE_ID_REGEX})`);
         }
     }
+    if (m.config !== undefined) {
+        const configErrors = validateConfigDeclarations(m.config);
+        for (const err of configErrors) {
+            errors.push(err);
+        }
+    }
     if (m.actions !== undefined) {
         if (!m.actions || typeof m.actions !== "object" || Array.isArray(m.actions)) {
             errors.push("Manifest 'actions' must be an object");

package/dist/project/types.d.ts

@@ -2,6 +2,34 @@
  * 配置项的值类型枚举。用于自动类型推断与环境变量自动转换。
  */
 export type ConfigValueType = "string" | "number" | "boolean" | "object" | "array";
+/**
+ * 配置值受限模式定义契约。
+ * 仅允许受支持的纯受限关键字集合，禁止动态计算或高级条件指令。
+ */
+export interface ConfigValueSchema {
+    /** 节点数据类型 */
+    type?: "object" | "array" | "string" | "integer" | "number" | "boolean";
+    /** 对象属性字段子模式映射 */
+    properties?: Record<string, ConfigValueSchema>;
+    /** 必填属性字段列表 */
+    required?: string[];
+    /** 额外属性放行策略（布尔开关或子模式） */
+    additionalProperties?: boolean | ConfigValueSchema;
+    /** 数组元素子模式 */
+    items?: ConfigValueSchema;
+    /** 枚举有效值列表 */
+    enum?: unknown[];
+    /** 字符串最小字符长度 */
+    minLength?: number;
+    /** 字符串最大字符长度 */
+    maxLength?: number;
+    /** 数值最小值约束 */
+    minimum?: number;
+    /** 数值最大值约束 */
+    maximum?: number;
+    /** 是否为敏感字段（仅可在模式节点中扩展指定） */
+    secret?: boolean;
+}
 /**
  * 在 actiondock.json 中声明的单项配置定义。
  */
@@ -20,6 +48,8 @@ export interface ConfigItemDefinition {
     required?: boolean;
     /** 是否允许单次调用覆盖 */
     allowInvocationOverride?: boolean;
+    /** 配置值验证与字段级脱敏所绑定的受限模式定义 */
+    schema?: ConfigValueSchema;
 }
 /**
  * 单个 Action 在 actiondock.json 清单中的声明项。

package/dist/runtime/context.d.ts

@@ -1,7 +1,8 @@
-import type { ActionContext, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
+import type { ActionContext, ActionInvokeOptions, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
 import type { ProjectConfig } from "../project/types.js";
 import type { RuntimeStorage } from "../storage/types.js";
 import { ProcessManager, type ProcessOwner } from "../process/index.js";
+import type { ConfigSource } from "../service/types.js";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
@@ -26,9 +27,11 @@ export declare class RuntimeConfig implements Config {
      *
      * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
      * 避免重复实现解析链导致行为漂移。
+     * source 仅表达实际生效值来源；undefined 统一视为未命中并继续向低优先级解析，
+     * null/false/0/空串均为真实值；整链未命中时 source 为 null。
      */
     describe<T = unknown>(key: string): {
-        source: "overrides" | "package" | "global" | "env" | "default";
+        source: ConfigSource | null;
         value: T | undefined;
     };
 }
@@ -81,7 +84,7 @@ export interface ContextOptions {
     owner?: ProcessOwner;
     progress?: ProgressReporter;
     logger?: Logger;
-    onActionInvoke?: (action: ActionRef | string, input: unknown, parentRunId?: string) => Promise<unknown>;
+    onActionInvoke?: (action: ActionRef | string, input: unknown, parentRunId?: string, options?: ActionInvokeOptions) => Promise<unknown>;
 }
 /**
  * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。