@actiondock/core 2.18.0 → 2.20.0

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.18.0",
+            "@actiondock/sdk": "^2.20.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.18.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 运行时上下文。

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}'`);