@actiondock/core 2.19.0 → 2.20.0

package/dist/runtime/context.js

@@ -1,7 +1,8 @@
+import { assertConcreteConfigKey, assertValidConfigDeclarations, resolveConfigDeclaration, validateConfigValue } from "../project/config-declarations.js";
 import { MemoryProcessDriver, ProcessManager } from "../process/index.js";
 import { createDefaultProcessOwner } from "../invocation/types.js";
 import { resolveEnvValue } from "./env.js";
-import { ActionDockError, INVALID_ACTION_REF, INVALID_STATE } from "../errors.js";
+import { ActionDockError, INVALID_ACTION_REF, INVALID_ARGUMENT, INVALID_STATE } from "../errors.js";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
@@ -20,32 +21,41 @@ export class RuntimeConfig {
     constructor(storage, overrides = {}, projectConfig, globalStorage) {
         this.storage = storage;
         this.overrides = new Map(Object.entries(overrides));
+        assertValidConfigDeclarations(projectConfig?.config);
         this.projectConfig = projectConfig;
         this.globalStorage = globalStorage;
     }
     get(key, defaultValue) {
-        // 委托 describe 五层解析链唯一事实源：整链未命中（source 为 default 且无值）时回退调用方默认值
+        // 委托 describe 五层解析链唯一事实源：整链未命中（source 为 null 且无值）时回退调用方默认值
         const resolved = this.describe(key);
-        if (resolved.source === "default" && resolved.value === undefined) {
+        if (resolved.source === null && resolved.value === undefined) {
             return defaultValue;
         }
+        const resolvedDecl = resolveConfigDeclaration(this.projectConfig?.config, key);
+        validateConfigValue(key, resolved.value, resolvedDecl?.item);
         return resolved.value;
     }
     has(key) {
-        // 委托 describe 五层解析链唯一事实源：default 来源且无值即视为未配置
+        // 委托 describe 五层解析链唯一事实源：来源 null 且无值即视为未配置
         const resolved = this.describe(key);
-        return !(resolved.source === "default" && resolved.value === undefined);
+        return !(resolved.source === null && resolved.value === undefined);
     }
     /**
      * 结构化解析指定配置项的来源与取值视图。
      *
      * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
      * 避免重复实现解析链导致行为漂移。
+     * source 仅表达实际生效值来源；undefined 统一视为未命中并继续向低优先级解析，
+     * null/false/0/空串均为真实值；整链未命中时 source 为 null。
      */
     describe(key) {
-        // 1. CLI 临时参数覆写
+        assertConcreteConfigKey(key);
+        // 1. 运行时固定覆盖与单次调用覆盖（值为 undefined 视为未命中，继续解析链）
         if (this.overrides.has(key)) {
-            return { source: "overrides", value: this.overrides.get(key) };
+            const overrideValue = this.overrides.get(key);
+            if (overrideValue !== undefined) {
+                return { source: "override", value: overrideValue };
+            }
         }
         // 2. 包级持久化存储
         const stored = this.storage.getConfig(key);
@@ -65,13 +75,17 @@ export class RuntimeConfig {
             }
         }
         // 4. 环境变量
-        const itemDef = this.projectConfig?.config?.[key];
+        const resolvedDecl = resolveConfigDeclaration(this.projectConfig?.config, key);
+        const itemDef = resolvedDecl?.item;
         const envResolved = resolveEnvValue(key, itemDef, this.projectConfig?.id);
         if (envResolved !== undefined) {
             return { source: "env", value: envResolved.value };
         }
-        // 5. 项目声明的默认值
-        return { source: "default", value: itemDef?.default };
+        // 5. 项目声明的默认值；仅存在真实生效的 default 值才报 default，整链未命中为 null
+        if (itemDef?.default !== undefined) {
+            return { source: "default", value: itemDef.default };
+        }
+        return { source: null, value: undefined };
     }
 }
 /**
@@ -156,6 +170,38 @@ export class StderrLogger {
         process.stderr.write(this.format("error", message, data) + "\n");
     }
 }
+/**
+ * 校验并规范化 ActionInvokeOptions 调用选项。
+ *
+ * 针对第三参数运行时检查：
+ * - 必须为普通对象或 undefined（2 参数兼容）
+ * - 严禁未知字段（如 profile、server、token 等）
+ * - binding 若存在必须为非空且非全空白字符串
+ */
+function validateActionInvokeOptions(options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    if (typeof options !== "object" ||
+        options === null ||
+        Array.isArray(options) ||
+        (Object.getPrototypeOf(options) !== Object.prototype && Object.getPrototypeOf(options) !== null)) {
+        throw new ActionDockError(INVALID_ARGUMENT, "INVALID_ARGUMENT: ActionInvokeOptions must be a plain object");
+    }
+    const allowedKeys = new Set(["binding"]);
+    for (const key of Reflect.ownKeys(options)) {
+        if (typeof key !== "string" || !allowedKeys.has(key)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `INVALID_ARGUMENT: Unknown option '${String(key)}' in ActionInvokeOptions. Only 'binding' is allowed.`);
+        }
+    }
+    const rawBinding = options.binding;
+    if (rawBinding !== undefined) {
+        if (typeof rawBinding !== "string" || rawBinding.trim() === "") {
+            throw new ActionDockError(INVALID_ARGUMENT, "INVALID_ARGUMENT: 'binding' option must be a non-empty string");
+        }
+    }
+    return options;
+}
 /**
  * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。
  *
@@ -169,17 +215,18 @@ export function createActionContext(options) {
     const signal = options.signal ?? new AbortController().signal;
     const currentRunId = options.runId || crypto.randomUUID();
     const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
-    const invoke = async (action, input) => {
+    const invoke = async (action, input, rawOptions) => {
         if (typeof action !== "string" &&
             (!action || typeof action !== "object" || typeof action.run === "function" || !("actionId" in action))) {
             throw new ActionDockError(INVALID_ACTION_REF, "INVALID_ACTION_REF: ctx.actions.invoke strictly accepts only ActionRef or string, passing ActionDefinition or function is prohibited");
         }
+        const validatedOptions = validateActionInvokeOptions(rawOptions);
         if (options.onActionInvoke) {
-            return (await options.onActionInvoke(action, input, currentRunId));
+            return (await options.onActionInvoke(action, input, currentRunId, validatedOptions));
         }
         throw new ActionDockError(INVALID_STATE, "ActionInvoker not configured with an invocation delegate");
     };
-    const invokerFn = (ref, input) => invoke(ref, input);
+    const invokerFn = (ref, input, invokeOpts) => invoke(ref, input, invokeOpts);
     const invoker = Object.assign(invokerFn, { invoke });
     const defaultOwner = createDefaultProcessOwner();
     const effectiveOwner = options.owner || defaultOwner;

package/dist/runtime/env.js

@@ -142,7 +142,21 @@ export function resolveEnvValue(key, itemDef, packageId) {
     // 4. 原始键名 (例如 apiKey)
     candidateKeys.add(key);
     // 按优先级顺序依次检索环境变量
-    const effectiveType = itemDef?.type || inferTypeFromDefault(itemDef?.default);
+    let effectiveType = itemDef?.type;
+    if (!effectiveType && itemDef?.schema?.type) {
+        if (itemDef.schema.type === "integer" || itemDef.schema.type === "number") {
+            effectiveType = "number";
+        }
+        else if (itemDef.schema.type === "string" ||
+            itemDef.schema.type === "boolean" ||
+            itemDef.schema.type === "object" ||
+            itemDef.schema.type === "array") {
+            effectiveType = itemDef.schema.type;
+        }
+    }
+    if (!effectiveType) {
+        effectiveType = inferTypeFromDefault(itemDef?.default);
+    }
     for (const envKey of candidateKeys) {
         const rawVal = process.env[envKey];
         if (rawVal !== undefined) {

package/dist/runtime/standalone-commands.d.ts

@@ -14,5 +14,5 @@ export interface CommandContext {
 export declare function handleList(ctx: CommandContext, subArgs: string[]): Promise<number>;
 export declare function handleDescribe(ctx: CommandContext, subArgs: string[]): Promise<number>;
 export declare function handleRun(ctx: CommandContext, subArgs: string[], actionArgs: string[], signal?: AbortSignal): Promise<number>;
-export declare function handleConfig(ctx: CommandContext, subArgs: string[]): Promise<number>;
-export declare function handleState(ctx: CommandContext, subArgs: string[]): Promise<number>;
+export declare function handleConfig(ctx: CommandContext, subArgs: string[], flatArgs?: string[], signal?: AbortSignal, stdin?: NodeJS.ReadableStream): Promise<number>;
+export declare function handleState(ctx: CommandContext, subArgs: string[], flatArgs?: string[], signal?: AbortSignal, stdin?: NodeJS.ReadableStream): Promise<number>;

package/dist/runtime/standalone-commands.js

@@ -1,8 +1,9 @@
 import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../utils/intent.js";
-import { resolveExecutionHint } from "../errors.js";
-import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
+import { ActionDockError, INVALID_ARGUMENT, resolveExecutionHint } from "../errors.js";
+import { resolveInput, resolveValueInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
 import { validateActionInputValue } from "../value-validator.js";
+import { assertConcreteConfigKey } from "../project/config-declarations.js";
 import { parseDuration } from "../utils/index.js";
 import { ExitCode } from "./standalone.js";
 export async function handleList(ctx, subArgs) {
@@ -148,7 +149,7 @@ export async function handleRun(ctx, subArgs, actionArgs, signal) {
     }
     let input;
     try {
-        input = await resolveActionInput({
+        input = await resolveInput({
             input: inputStr,
             inputFile,
             stdinField,
@@ -273,7 +274,57 @@ function isServiceCapabilityError(err) {
     return (code === "CAPABILITY_UNAVAILABLE" ||
         code === "TARGET_CAPABILITY_UNAVAILABLE");
 }
-export async function handleConfig(ctx, subArgs) {
+function parseSetInput(subArgs, isState) {
+    const positional = [];
+    const input = {};
+    let namespace;
+    let ttl;
+    for (let i = 1; i < subArgs.length; i++) {
+        const arg = subArgs[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--stdin") {
+            if (input.fromStdin)
+                throw new ActionDockError(INVALID_ARGUMENT, "Duplicate --stdin option");
+            input.fromStdin = true;
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const option = equals < 0 ? arg : arg.slice(0, equals);
+        if (option === "--stdin-field" || (isState && ["-n", "--namespace", "--ttl"].includes(option))) {
+            const value = equals < 0 ? subArgs[++i] : arg.slice(equals + 1);
+            if (value === undefined) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Option '${option}' requires a value`);
+            }
+            if (option === "--stdin-field") {
+                if (input.stdinField !== undefined) {
+                    throw new ActionDockError(INVALID_ARGUMENT, "Duplicate --stdin-field option");
+                }
+                input.stdinField = value;
+            }
+            else if (option === "--ttl") {
+                ttl = parseInt(value, 10);
+            }
+            else {
+                namespace = value;
+            }
+        }
+        else if (arg.startsWith("-") && !/^-\d/.test(arg)) {
+            throw new ActionDockError(INVALID_ARGUMENT, "Unknown set option");
+        }
+        else {
+            positional.push(arg);
+            if (positional.length > 2) {
+                throw new ActionDockError(INVALID_ARGUMENT, "Only one complete positional value is allowed");
+            }
+        }
+    }
+    if (!positional[0])
+        throw new ActionDockError(INVALID_ARGUMENT, "Key is required");
+    input.value = positional[1];
+    return { key: positional[0], input, namespace, ttl };
+}
+export async function handleConfig(ctx, subArgs, flatArgs, signal, stdin) {
     const sub = subArgs[0] || "list";
     if (!ctx.service.management) {
         ctx.writeErr("Error: management port is not enabled on this service");
@@ -281,10 +332,15 @@ export async function handleConfig(ctx, subArgs) {
     }
     if (sub === "list") {
         const views = await ctx.service.management.config.list(ctx.options.packageId);
-        const dict = {};
+        const dict = Object.create(null);
         for (const v of views) {
-            if (v.configured && v.value !== undefined) {
-                dict[v.key] = v.value;
+            if (v.configured) {
+                if (v.secret && v.value === undefined) {
+                    dict[v.key] = "********";
+                }
+                else if (v.value !== undefined) {
+                    dict[v.key] = v.value;
+                }
             }
         }
         ctx.writeOut(JSON.stringify(dict, null, 2));
@@ -298,7 +354,15 @@ export async function handleConfig(ctx, subArgs) {
         }
         try {
             const item = await ctx.service.management.config.get(ctx.options.packageId, key);
-            ctx.writeOut(item.configured ? JSON.stringify(item.value) : "undefined");
+            if (item.redactedPaths.includes("") || (item.configured && item.value === undefined)) {
+                ctx.writeOut("<hidden>");
+            }
+            else if (item.value === undefined) {
+                ctx.writeOut("<not configured>");
+            }
+            else {
+                ctx.writeOut(JSON.stringify(item.value));
+            }
             return ExitCode.SUCCESS;
         }
         catch (err) {
@@ -311,21 +375,27 @@ export async function handleConfig(ctx, subArgs) {
         }
     }
     if (sub === "set") {
-        const key = subArgs[1];
-        const rawVal = subArgs[2];
-        if (!key || rawVal === undefined) {
-            ctx.writeErr("Error: key and value required");
-            return ExitCode.INVALID_ARGUMENT;
-        }
-        let parsed = rawVal;
+        let parsed;
+        let value;
         try {
-            parsed = JSON.parse(rawVal);
+            parsed = parseSetInput(subArgs, false);
+            assertConcreteConfigKey(parsed.key);
+            value = await resolveValueInput({
+                ...parsed.input,
+                flatArgs,
+                signal,
+                stdin,
+                policy: { sanitizeInputErrors: true },
+            });
+            signal?.throwIfAborted();
         }
-        catch {
-            parsed = rawVal;
+        catch (err) {
+            return ctx.emitError(subArgs.includes("--json"), err?.code || "INVALID_ARGUMENT", err?.message || String(err), ExitCode.INVALID_ARGUMENT, {
+                details: err?.details,
+            });
         }
-        await ctx.service.management.config.set(ctx.options.packageId, key, parsed);
-        ctx.writeOut(`Config '${key}' updated`);
+        await ctx.service.management.config.set(ctx.options.packageId, parsed.key, value);
+        ctx.writeOut(`Config '${parsed.key}' updated`);
         return ExitCode.SUCCESS;
     }
     if (sub === "delete") {
@@ -349,7 +419,7 @@ function decodeStateKeyArg(key) {
         return { namespace: "", key };
     }
 }
-export async function handleState(ctx, subArgs) {
+export async function handleState(ctx, subArgs, flatArgs, signal, stdin) {
     const sub = subArgs[0] || "list";
     let namespace;
     let isAll = false;
@@ -405,36 +475,32 @@ export async function handleState(ctx, subArgs) {
         return ExitCode.SUCCESS;
     }
     if (sub === "set") {
-        const key = subArgs[1];
-        const rawVal = subArgs[2];
-        if (!key || rawVal === undefined) {
-            ctx.writeErr("Error: key and value required");
-            return ExitCode.INVALID_ARGUMENT;
-        }
-        let ns = namespace || "";
-        let actualKey = key;
-        if (namespace === undefined) {
-            const decoded = decodeStateKeyArg(key);
-            ns = decoded.namespace;
-            actualKey = decoded.key;
-        }
-        let parsed = rawVal;
+        let parsed;
+        let value;
         try {
-            parsed = JSON.parse(rawVal);
+            parsed = parseSetInput(subArgs, true);
+            value = await resolveValueInput({
+                ...parsed.input,
+                flatArgs,
+                signal,
+                stdin,
+                policy: { sanitizeInputErrors: true },
+            });
+            signal?.throwIfAborted();
         }
-        catch {
-            parsed = rawVal;
+        catch (err) {
+            return ctx.emitError(isJson, err?.code || "INVALID_ARGUMENT", err?.message || String(err), ExitCode.INVALID_ARGUMENT, {
+                details: err?.details,
+            });
         }
-        let ttl;
-        for (let i = 3; i < subArgs.length; i++) {
-            if (subArgs[i] === "--ttl" && i + 1 < subArgs.length) {
-                ttl = parseInt(subArgs[++i], 10);
-            }
-            else if (subArgs[i].startsWith("--ttl=")) {
-                ttl = parseInt(subArgs[i].slice(6), 10);
-            }
+        let ns = parsed.namespace || "";
+        let actualKey = parsed.key;
+        if (parsed.namespace === undefined) {
+            const decoded = decodeStateKeyArg(parsed.key);
+            ns = decoded.namespace;
+            actualKey = decoded.key;
         }
-        await ctx.service.management.state.set(ctx.options.packageId, "", actualKey, parsed, { namespace: ns, ttl });
+        await ctx.service.management.state.set(ctx.options.packageId, "", actualKey, value, { namespace: ns, ttl: parsed.ttl });
         const displayKey = ns ? `${ns}:${actualKey}` : actualKey;
         ctx.writeOut(`State '${displayKey}' updated`);
         return ExitCode.SUCCESS;

package/dist/runtime/standalone-help.d.ts

@@ -1,3 +1,4 @@
+export { parseConfigOverrideAssignment } from "../input/config-override.js";
 export interface ParsedArgs {
     controlArgs: string[];
     actionArgs: string[];

package/dist/runtime/standalone-help.js

@@ -1,3 +1,5 @@
+import { parseConfigOverrideAssignment } from "../input/config-override.js";
+export { parseConfigOverrideAssignment } from "../input/config-override.js";
 export function parseStandaloneArgs(argv) {
     const separator = argv.indexOf("--");
     const controlArgs = separator >= 0 ? argv.slice(0, separator) : argv;
@@ -13,17 +15,15 @@ export function parseStandaloneArgs(argv) {
         else if (arg.startsWith("--data-dir=")) {
             dataDir = arg.slice(11);
         }
-        else if (arg === "--config" && i + 1 < controlArgs.length) {
-            const pair = controlArgs[++i];
-            const [k, ...v] = pair.split("=");
-            if (k)
-                configOverrides[k] = v.join("=");
+        else if (arg === "--config" || arg === "-c") {
+            const pair = controlArgs[++i] ?? "";
+            const { key, value } = parseConfigOverrideAssignment(pair);
+            Object.defineProperty(configOverrides, key, { value, enumerable: true, writable: true, configurable: true });
         }
         else if (arg.startsWith("--config=")) {
             const pair = arg.slice(9);
-            const [k, ...v] = pair.split("=");
-            if (k)
-                configOverrides[k] = v.join("=");
+            const { key, value } = parseConfigOverrideAssignment(pair);
+            Object.defineProperty(configOverrides, key, { value, enumerable: true, writable: true, configurable: true });
         }
         else {
             filteredArgs.push(arg);
@@ -45,10 +45,16 @@ export function printHelp(writeOut, options) {
     writeOut("  <cmd> run <id> [--stdin-field <field>] [-- <assignments...>]");
     writeOut("                                             Bind raw stdin text to an input field");
     writeOut("  <cmd> config list/get/set/delete            Manage package configuration");
+    writeOut("  <cmd> config set <key> [<value> | --stdin]");
+    writeOut("  <cmd> config set <key> [--stdin-field <field>] [-- <assignments...>]");
     writeOut("  <cmd> state list/get/set/delete             Manage shared state store");
+    writeOut("  <cmd> state set <key> [<value> | --stdin] [-n <namespace>] [--ttl <seconds>]");
+    writeOut("  <cmd> state set <key> [--stdin-field <field>] [-n <namespace>] [--ttl <seconds>] [-- <assignments...>]");
+    writeOut("                                             set 整键替换；完整值、--stdin 与结构化输入互斥");
+    writeOut("                                             扁平赋值：field=text 或 field:=json；--stdin-field 保留原始正文");
     writeOut("\nGlobal options:");
     writeOut("  --data-dir <path>                           Custom runtime database directory");
-    writeOut("  --config <KEY=val>                          Temporary config override");
+    writeOut("  --config <KEY=val|KEY:=json>                Temporary config override");
 }
 export function emitError(writeOut, writeErr, isJson, code, message, exitCode, options) {
     if (isJson) {

package/dist/runtime/standalone.js

@@ -149,10 +149,10 @@ export class StandaloneDispatcher {
                     code = await handleRun(ctx, subArgs, actionArgs, control?.signal);
                     break;
                 case "config":
-                    code = await handleConfig(ctx, subArgs);
+                    code = await handleConfig(ctx, subArgs, argv.includes("--") ? actionArgs : undefined, control?.signal);
                     break;
                 case "state":
-                    code = await handleState(ctx, subArgs);
+                    code = await handleState(ctx, subArgs, argv.includes("--") ? actionArgs : undefined, control?.signal);
                     break;
                 default:
                     this.writeErr(`Unknown command: '${command}'`);

package/dist/server/policy.d.ts

@@ -3,144 +3,61 @@ import { ActionDockError } from "../errors.js";
 import type { McpEndpointHandler } from "./mcp-endpoint.js";
 import type { EffectiveServerPolicy, ServerOptions, ServerViewOptions } from "./types.js";
 export { extractBearerToken } from "./security.js";
-/**
- * 动作未列入白名单拒绝访问异常。
- */
+type PolicyAction = {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string;
+/** 校验两类白名单授权；省略或空数组不增加授权，包列表中的独立 * 显式授予全部权限。 */
+export declare function assertServerPolicyValid(item: {
+    packageAllowlist?: unknown;
+    actionAllowlist?: unknown;
+}, scope?: string): void;
+/** 是否显式授予全部包与动作；不替代独立的管理能力门禁。 */
+export declare function isFullAccessGranted(policy?: EffectiveServerPolicy | null): boolean;
 export declare class ActionForbiddenError extends ActionDockError {
     status: number;
     statusCode: number;
     constructor(actionRef: string);
 }
-/**
- * 包未列入白名单拒绝访问异常。
- */
 export declare class PackageNotAllowedError extends ActionDockError {
     status: number;
     statusCode: number;
     constructor(packageId: string);
 }
-/**
- * 归一化后的单个服务视图结构。
- */
 export interface NormalizedServerView {
-    /** 视图唯一标识名称 */
     name: string;
-    /** 该视图生效的统一安全策略 */
     policy: EffectiveServerPolicy;
-    /** 该视图是否启用 MCP 端点 */
     enableMcp: boolean;
-    /** 原始配置选项 */
     rawOptions: ServerViewOptions;
-    /** 为该视图独立装配的 MCP 端点处理器 */
     mcpEndpointHandler?: McpEndpointHandler;
 }
-/**
- * 根据客户端携带的 Token 智能匹配已注册的视图。
- * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
- *
- * @param token 客户端提供的 Bearer Token
- * @param views 可遍历的视图集合
- * @returns 匹配成功的视图对象，未命中返回 undefined
- */
+/** 遍历全部视图并以常数时间比较令牌，避免提前退出泄露匹配位置。 */
 export declare function matchViewByToken(token: string, views: Iterable<NormalizedServerView>): NormalizedServerView | undefined;
-/**
- * 归一化解析服务端配置的所有视图集合。
- * 保证默认视图与显式自定义视图具有统一的数据结构。
- *
- * @param options 服务端配置选项
- * @returns 默认视图与全部视图 Map 映射
- */
+/** 全局选项仅配置默认视图；命名视图独立授权，缺少授权的视图默认拒绝全部。 */
 export declare function normalizeServerViews(options: ServerOptions): {
     defaultView: NormalizedServerView;
     views: Map<string, NormalizedServerView>;
 };
-/**
- * 校验目标动作是否在 actionAllowlist 允许白名单中。
- * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
- * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
- * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
- *
- * @param action 目标动作对象或引用字符串
- * @param allowlist 允许动作白名单列表
- * @returns 是否允许访问
- */
-export declare function isActionAllowed(action: {
-    actionId?: string;
-    id?: string;
-    packageId?: string;
-} | string | null | undefined, allowlist?: string[]): boolean;
-/**
- * 根据生效策略统一判定目标动作是否允许访问。
- * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
- *
- * @param action 目标动作对象或引用字符串
- * @param policy 当前生效的服务端策略
- * @returns 是否允许访问
- */
-export declare function isActionAllowedByPolicy(action: {
-    actionId?: string;
-    id?: string;
-    packageId?: string;
-} | string | null | undefined, policy?: EffectiveServerPolicy): boolean;
-/**
- * 根据生效策略统一判定目标包标识是否允许访问。
- *
- * @param packageId 目标包 ID
- * @param policy 当前生效的服务端策略
- * @returns 是否允许访问
- */
+/** 动作列表仅按全限定引用匹配；省略或空列表不会授予任何动作。 */
+export declare function isActionAllowed(action: PolicyAction | null | undefined, allowlist?: string[]): boolean;
+/** 整包授权与全限定单动作授权取并集；仅缺少策略对象的内部调用不执行过滤。 */
+export declare function isActionAllowedByPolicy(action: PolicyAction | null | undefined, policy?: EffectiveServerPolicy): boolean;
+/** 整包能力授权，不从某个动作的授权推导配置、状态、规程或诊断权限。 */
 export declare function isPackageAllowedByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
-/**
- * 根据生效策略统一判定配置与状态管理路由是否开启。
- *
- * @param policy 当前生效的服务端策略
- * @returns 是否允许管理操作
- */
+/** 单动作授权的包可发现必要身份信息，但不因此获得整包能力。 */
+export declare function isPackageVisibleByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
+export declare function requiresMinimalPackageProjection(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
 export declare function isManagementAllowedByPolicy(policy?: EffectiveServerPolicy): boolean;
-/**
- * 根据生效策略对动作列表进行统一过滤。
- *
- * @param actions 待过滤的动作列表
- * @param policy 当前生效的服务端策略
- * @returns 过滤后允许访问的动作列表
- */
 export declare function filterActionsByPolicy<T extends {
     id: string;
     packageId?: string;
     actionId?: string;
 }>(actions: T[], policy?: EffectiveServerPolicy): T[];
-/**
- * 根据生效策略对包列表进行统一过滤。
- *
- * @param packages 待过滤的包列表
- * @param policy 当前生效的服务端策略
- * @returns 过滤后允许访问的包列表
- */
 export declare function filterPackagesByPolicy<T extends {
     id: string;
 }>(packages: T[], policy?: EffectiveServerPolicy): T[];
-/**
- * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
- *
- * @param action 目标动作对象或引用
- * @param policy 当前生效的服务端策略
- */
-export declare function assertActionAllowedByPolicy(action: {
-    actionId?: string;
-    id?: string;
-    packageId?: string;
-} | string, policy?: EffectiveServerPolicy): void;
-/**
- * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
- *
- * @param packageId 目标包 ID
- * @param policy 当前生效的服务端策略
- */
+export declare function assertActionAllowedByPolicy(action: PolicyAction, policy?: EffectiveServerPolicy): void;
 export declare function assertPackageAllowedByPolicy(packageId: string, policy?: EffectiveServerPolicy): void;
-/**
- * 构造受信任的服务端执行来源快照。
- *
- * 仅挑选 channel、viewName（默认 "default"）与 authenticated（视图配置非空有效令牌）。
- * 严禁暴露令牌原文、片段或摘要。
- */
+/** 只记录受信任的执行来源，不能包含令牌原文、片段或摘要。 */
 export declare function createServerRunOrigin(policy: Pick<EffectiveServerPolicy, "viewName" | "token">, channel: RunOrigin["channel"]): RunOrigin;