@actiondock/core 2.5.1 → 2.7.0

package/dist/input/advice.js

@@ -0,0 +1,767 @@
+import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
+const RECOGNIZED_SCHEMA_TYPES = new Set([
+    "object",
+    "array",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+]);
+const COMPLEX_KEYWORDS = [
+    "oneOf",
+    "anyOf",
+    "allOf",
+    "$ref",
+    "not",
+    "if",
+    "then",
+    "else",
+    "patternProperties",
+    "dependentSchemas",
+    "dependentRequired",
+    "propertyNames",
+    "unevaluatedProperties",
+];
+function isPlainObject(val) {
+    return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+function isJsonValueLike(val) {
+    if (typeof val === "function" ||
+        typeof val === "symbol" ||
+        typeof val === "undefined" ||
+        typeof val === "bigint") {
+        return false;
+    }
+    if (typeof val === "number" && (!Number.isFinite(val) || Number.isNaN(val))) {
+        return false;
+    }
+    return true;
+}
+function createMalformedAdvice(message) {
+    return {
+        version: 1,
+        analysisMode: "declared-properties-only",
+        analysisStatus: "malformed",
+        analysisCode: "MALFORMED_SCHEMA",
+        analysisMessage: message,
+        schemaState: "complex",
+        inputFeasibility: "possible-or-unknown",
+        flatAvailable: false,
+        requiredSatisfiable: null,
+        flatCandidate: false,
+        schemaRecommendedMode: "full-json",
+        fields: [],
+    };
+}
+/**
+ * 依据 inputSchema 构造 v1 版本的 Action 输入编码顾问报告（机器契约）。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 遵循技术设计文档规范的结构化输入建议
+ */
+export function buildCliInputAdviceV1(schema) {
+    // 1. Schema Sanity 阶段（Section 44）
+    // 1.1 根形状检查（Section 44.1）
+    if (schema === undefined) {
+        return {
+            version: 1,
+            analysisMode: "declared-properties-only",
+            analysisStatus: "ok",
+            schemaState: "absent",
+            inputFeasibility: "possible-or-unknown",
+            flatAvailable: false,
+            requiredSatisfiable: null,
+            flatCandidate: false,
+            schemaRecommendedMode: "full-json",
+            fields: [],
+        };
+    }
+    if (typeof schema === "boolean") {
+        if (schema === false) {
+            return {
+                version: 1,
+                analysisMode: "declared-properties-only",
+                analysisStatus: "ok",
+                schemaState: "reject-all",
+                inputFeasibility: "known-impossible",
+                feasibilityCode: "SCHEMA_REJECTS_ALL",
+                flatAvailable: false,
+                requiredSatisfiable: false,
+                flatCandidate: false,
+                schemaRecommendedMode: "none",
+                fields: [],
+            };
+        }
+        return {
+            version: 1,
+            analysisMode: "declared-properties-only",
+            analysisStatus: "ok",
+            schemaState: "any",
+            inputFeasibility: "possible-or-unknown",
+            flatAvailable: false,
+            requiredSatisfiable: null,
+            flatCandidate: false,
+            schemaRecommendedMode: "full-json",
+            fields: [],
+        };
+    }
+    if (!isPlainObject(schema)) {
+        return {
+            version: 1,
+            analysisMode: "declared-properties-only",
+            analysisStatus: "malformed",
+            analysisCode: "MALFORMED_SCHEMA",
+            analysisMessage: "Schema root must be undefined, boolean, or a plain object",
+            schemaState: "complex",
+            inputFeasibility: "possible-or-unknown",
+            flatAvailable: false,
+            requiredSatisfiable: null,
+            flatCandidate: false,
+            schemaRecommendedMode: "full-json",
+            fields: [],
+        };
+    }
+    const s = schema;
+    // 1.2 关键字形状检查（Section 44.2）
+    // 检查 type
+    if (s.type !== undefined) {
+        if (typeof s.type === "string") {
+            if (!RECOGNIZED_SCHEMA_TYPES.has(s.type)) {
+                return createMalformedAdvice(`Unrecognized type keyword: '${s.type}'`);
+            }
+        }
+        else if (Array.isArray(s.type)) {
+            if (s.type.length === 0) {
+                return createMalformedAdvice("Type array must not be empty");
+            }
+            const seen = new Set();
+            for (const t of s.type) {
+                if (typeof t !== "string" || !RECOGNIZED_SCHEMA_TYPES.has(t)) {
+                    return createMalformedAdvice(`Unrecognized type in type array: '${String(t)}'`);
+                }
+                if (seen.has(t)) {
+                    return createMalformedAdvice(`Duplicate type in type array: '${t}'`);
+                }
+                seen.add(t);
+            }
+        }
+        else {
+            return createMalformedAdvice("Type keyword must be a string or array of strings");
+        }
+    }
+    // 检查 properties
+    if (s.properties !== undefined) {
+        if (!isPlainObject(s.properties)) {
+            return createMalformedAdvice("Properties keyword must be a plain object");
+        }
+        for (const [propKey, propVal] of Object.entries(s.properties)) {
+            if (typeof propVal !== "boolean" && !isPlainObject(propVal)) {
+                return createMalformedAdvice(`Property '${propKey}' schema must be a boolean or plain object`);
+            }
+            if (isPlainObject(propVal)) {
+                if (propVal.type !== undefined) {
+                    if (typeof propVal.type === "string") {
+                        if (!RECOGNIZED_SCHEMA_TYPES.has(propVal.type)) {
+                            return createMalformedAdvice(`Unrecognized type '${propVal.type}' in property '${propKey}'`);
+                        }
+                    }
+                    else if (Array.isArray(propVal.type)) {
+                        if (propVal.type.length === 0) {
+                            return createMalformedAdvice(`Type array in property '${propKey}' must not be empty`);
+                        }
+                        const seen = new Set();
+                        for (const t of propVal.type) {
+                            if (typeof t !== "string" || !RECOGNIZED_SCHEMA_TYPES.has(t)) {
+                                return createMalformedAdvice(`Unrecognized type '${String(t)}' in property '${propKey}'`);
+                            }
+                            if (seen.has(t)) {
+                                return createMalformedAdvice(`Duplicate type '${t}' in property '${propKey}'`);
+                            }
+                            seen.add(t);
+                        }
+                    }
+                    else {
+                        return createMalformedAdvice(`Type in property '${propKey}' must be string or array of strings`);
+                    }
+                }
+                if (propVal.enum !== undefined) {
+                    if (!Array.isArray(propVal.enum) || propVal.enum.length === 0) {
+                        return createMalformedAdvice(`Enum in property '${propKey}' must be a non-empty array`);
+                    }
+                }
+                if (propVal.const !== undefined) {
+                    if (!isJsonValueLike(propVal.const)) {
+                        return createMalformedAdvice(`Const in property '${propKey}' must be a valid JSON value literal`);
+                    }
+                }
+                if (propVal.items !== undefined) {
+                    if (typeof propVal.items !== "boolean" &&
+                        !isPlainObject(propVal.items) &&
+                        !Array.isArray(propVal.items)) {
+                        return createMalformedAdvice(`Items in property '${propKey}' must be boolean, plain object, or array`);
+                    }
+                }
+            }
+        }
+    }
+    // 检查 required
+    if (s.required !== undefined) {
+        if (!Array.isArray(s.required)) {
+            return createMalformedAdvice("Required keyword must be an array of strings");
+        }
+        const seen = new Set();
+        for (const item of s.required) {
+            if (typeof item !== "string") {
+                return createMalformedAdvice("Every item in required array must be a string");
+            }
+            if (seen.has(item)) {
+                return createMalformedAdvice(`Duplicate required property: '${item}'`);
+            }
+            seen.add(item);
+        }
+    }
+    // 检查 additionalProperties
+    if (s.additionalProperties !== undefined) {
+        if (typeof s.additionalProperties !== "boolean" &&
+            !isPlainObject(s.additionalProperties)) {
+            return createMalformedAdvice("AdditionalProperties keyword must be a boolean or plain object");
+        }
+    }
+    // 检查 items
+    let isTupleItems = false;
+    if (s.items !== undefined) {
+        if (typeof s.items === "boolean" || isPlainObject(s.items)) {
+            // 合法
+        }
+        else if (Array.isArray(s.items)) {
+            isTupleItems = true;
+        }
+        else {
+            return createMalformedAdvice("Items keyword must be boolean, plain object, or array");
+        }
+    }
+    // 检查 enum
+    if (s.enum !== undefined) {
+        if (!Array.isArray(s.enum) || s.enum.length === 0) {
+            return createMalformedAdvice("Enum keyword must be a non-empty array");
+        }
+    }
+    // 检查 const
+    if (s.const !== undefined) {
+        if (!isJsonValueLike(s.const)) {
+            return createMalformedAdvice("Const keyword must be a valid JSON value literal");
+        }
+    }
+    // 检查 applicators
+    if (s.oneOf !== undefined && !Array.isArray(s.oneOf)) {
+        return createMalformedAdvice("OneOf keyword must be an array");
+    }
+    if (s.anyOf !== undefined && !Array.isArray(s.anyOf)) {
+        return createMalformedAdvice("AnyOf keyword must be an array");
+    }
+    if (s.allOf !== undefined && !Array.isArray(s.allOf)) {
+        return createMalformedAdvice("AllOf keyword must be an array");
+    }
+    if (s.$ref !== undefined && typeof s.$ref !== "string") {
+        return createMalformedAdvice("$ref keyword must be a string");
+    }
+    if (s.not !== undefined && typeof s.not !== "boolean" && !isPlainObject(s.not)) {
+        return createMalformedAdvice("Not keyword must be a boolean or plain object");
+    }
+    if (s.if !== undefined && typeof s.if !== "boolean" && !isPlainObject(s.if)) {
+        return createMalformedAdvice("If keyword must be a boolean or plain object");
+    }
+    if (s.then !== undefined && typeof s.then !== "boolean" && !isPlainObject(s.then)) {
+        return createMalformedAdvice("Then keyword must be a boolean or plain object");
+    }
+    if (s.else !== undefined && typeof s.else !== "boolean" && !isPlainObject(s.else)) {
+        return createMalformedAdvice("Else keyword must be a boolean or plain object");
+    }
+    // 2. 语义分类阶段（Section 45）
+    if (Object.keys(s).length === 0) {
+        return {
+            version: 1,
+            analysisMode: "declared-properties-only",
+            analysisStatus: "ok",
+            schemaState: "any",
+            inputFeasibility: "possible-or-unknown",
+            flatAvailable: false,
+            requiredSatisfiable: null,
+            flatCandidate: false,
+            schemaRecommendedMode: "full-json",
+            fields: [],
+        };
+    }
+    const hasComplexKeyword = isTupleItems ||
+        COMPLEX_KEYWORDS.some((kw) => s[kw] !== undefined);
+    let schemaState;
+    if (hasComplexKeyword) {
+        schemaState = "complex";
+    }
+    else if (s.type === "object") {
+        schemaState = "object";
+    }
+    else if (typeof s.type === "string" && s.type !== "object") {
+        schemaState = "json-only";
+    }
+    else if (Array.isArray(s.type)) {
+        schemaState = "complex";
+    }
+    else if (s.type === undefined &&
+        (s.properties !== undefined || s.required !== undefined || s.additionalProperties !== undefined)) {
+        schemaState = "complex";
+    }
+    else {
+        schemaState = "complex";
+    }
+    const analysisStatus = schemaState === "complex" ? "unsupported" : "ok";
+    const analysisCode = schemaState === "complex"
+        ? isTupleItems
+            ? "UNSUPPORTED_SCHEMA_SHAPE"
+            : "COMPLEX_SCHEMA"
+        : undefined;
+    const analysisMessage = schemaState === "complex"
+        ? "Complex schema structure is not supported for flat encoding"
+        : undefined;
+    // 3. 输入可行性判定（Section 47）
+    const requiredList = Array.isArray(s.required) ? s.required : [];
+    const properties = isPlainObject(s.properties) ? s.properties : {};
+    let inputFeasibility = "possible-or-unknown";
+    let feasibilityCode;
+    if (requiredList.some(isForbiddenActionInputPropertyName)) {
+        inputFeasibility = "known-impossible";
+        feasibilityCode = "REQUIRED_FIELD_FORBIDDEN";
+    }
+    else if (requiredList.some((k) => properties[k] === false)) {
+        inputFeasibility = "known-impossible";
+        feasibilityCode = "REQUIRED_FIELD_REJECTS_ALL";
+    }
+    else if (s.additionalProperties === false &&
+        requiredList.some((k) => !(k in properties))) {
+        inputFeasibility = "known-impossible";
+        feasibilityCode = "REQUIRED_FIELD_DISALLOWED_BY_ADDITIONAL_PROPERTIES";
+    }
+    // 4. 字段建议生成（Section 50）
+    const fields = [];
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const isReq = requiredList.includes(key);
+        if (isForbiddenActionInputPropertyName(key)) {
+            fields.push({
+                path: key,
+                inputAllowed: false,
+                flatSafe: false,
+                required: isReq,
+                reason: "FORBIDDEN_PROPERTY",
+                fallback: null,
+                ...(isPlainObject(propSchema) && propSchema.description
+                    ? { description: propSchema.description }
+                    : {}),
+                hint: "Globally forbidden property",
+            });
+            continue;
+        }
+        if (propSchema === false) {
+            fields.push({
+                path: key,
+                inputAllowed: false,
+                flatSafe: false,
+                required: isReq,
+                reason: "PROPERTY_SCHEMA_FALSE",
+                fallback: null,
+                hint: "Property schema rejects all values",
+            });
+            continue;
+        }
+        if (!isFlatPathPropertyName(key)) {
+            const typeStr = isPlainObject(propSchema) && propSchema.type
+                ? String(propSchema.type)
+                : "any";
+            fields.push({
+                path: key,
+                inputAllowed: true,
+                flatSafe: false,
+                required: isReq,
+                type: typeStr,
+                reason: "UNSAFE_FLAT_PROPERTY",
+                fallback: "stdin-json",
+                ...(isPlainObject(propSchema) && propSchema.description
+                    ? { description: propSchema.description }
+                    : {}),
+                hint: "Property name contains unsafe characters for flat encoding",
+            });
+            continue;
+        }
+        // Flat-safe property
+        if (propSchema === true) {
+            fields.push({
+                path: key,
+                inputAllowed: true,
+                flatSafe: true,
+                required: isReq,
+                type: "any",
+                operator: ":=",
+                encoding: "json",
+                assignmentTemplate: `${key}:=JSON`,
+            });
+            continue;
+        }
+        const propObj = propSchema;
+        const propType = propObj.type;
+        const desc = propObj.description;
+        // Section 46: enum/const 规则：
+        // enum/const 绝不改变 operator 选择，仅显式单一 schema.type 决定 operator。
+        // 无显式 type 时不推断类型，推荐 full-json，flatSafe: false。
+        if (typeof propType === "string") {
+            if (propType === "string") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: "string",
+                    operator: "=",
+                    encoding: "string",
+                    assignmentTemplate: `${key}=TEXT`,
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else if (propType === "number" || propType === "integer") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: propType,
+                    operator: ":=",
+                    encoding: "json-number",
+                    assignmentTemplate: `${key}:=NUMBER`,
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else if (propType === "boolean") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: "boolean",
+                    operator: ":=",
+                    encoding: "json-boolean",
+                    assignmentTemplate: `${key}:=BOOLEAN`,
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else if (propType === "null") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: "null",
+                    operator: ":=",
+                    encoding: "json-null",
+                    assignmentTemplate: `${key}:=null`,
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else if (propType === "array") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: "array",
+                    operator: ":=",
+                    encoding: "json-array",
+                    assignmentTemplate: `${key}:=JSON`,
+                    hint: "建议使用 --input-file 或标准输入传递数组结构",
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else if (propType === "object") {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: true,
+                    required: isReq,
+                    type: "object",
+                    operator: ":=",
+                    encoding: "json-object",
+                    assignmentTemplate: `${key}:=JSON`,
+                    hint: "大型结构建议使用 --input-file",
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+            else {
+                fields.push({
+                    path: key,
+                    inputAllowed: true,
+                    flatSafe: false,
+                    required: isReq,
+                    type: propType,
+                    reason: "UNSAFE_FLAT_PROPERTY",
+                    fallback: "stdin-json",
+                    ...(desc ? { description: desc } : {}),
+                });
+            }
+        }
+        else {
+            // 无显式单一类型（如 union type 或无 type 的 enum/const）
+            fields.push({
+                path: key,
+                inputAllowed: true,
+                flatSafe: false,
+                required: isReq,
+                type: Array.isArray(propType) ? propType.join(" | ") : "any",
+                reason: "UNSAFE_FLAT_PROPERTY",
+                fallback: "stdin-json",
+                ...(desc ? { description: desc } : {}),
+            });
+        }
+    }
+    // 5. requiredSatisfiable 计算（Section 48）
+    let requiredSatisfiable = null;
+    if (schemaState === "json-only") {
+        requiredSatisfiable = false;
+    }
+    else if (schemaState === "complex") {
+        requiredSatisfiable = null;
+    }
+    else if (schemaState === "object") {
+        if (requiredList.length === 0) {
+            requiredSatisfiable = true;
+        }
+        else {
+            let hasNull = false;
+            let allSafe = true;
+            for (const reqKey of requiredList) {
+                if (isForbiddenActionInputPropertyName(reqKey)) {
+                    requiredSatisfiable = false;
+                    allSafe = false;
+                    break;
+                }
+                const field = fields.find((f) => f.path === reqKey);
+                if (!field) {
+                    if (s.additionalProperties === false) {
+                        requiredSatisfiable = false;
+                        allSafe = false;
+                        break;
+                    }
+                    else {
+                        hasNull = true;
+                        continue;
+                    }
+                }
+                if (!field.inputAllowed ||
+                    field.flatSafe === false ||
+                    !field.operator ||
+                    !field.encoding) {
+                    requiredSatisfiable = false;
+                    allSafe = false;
+                    break;
+                }
+            }
+            if (allSafe) {
+                requiredSatisfiable = hasNull ? null : true;
+            }
+        }
+    }
+    // 6. flatAvailable, flatCandidate, schemaRecommendedMode（Section 49）
+    const flatAvailable = fields.some((f) => f.flatSafe && f.operator !== undefined);
+    const flatCandidate = schemaState === "object" && requiredSatisfiable === true && flatAvailable;
+    let schemaRecommendedMode;
+    if (inputFeasibility === "known-impossible") {
+        schemaRecommendedMode = "none";
+    }
+    else if (schemaState === "json-only" || schemaState === "complex") {
+        schemaRecommendedMode = "full-json";
+    }
+    else if (schemaState === "object" && flatCandidate) {
+        schemaRecommendedMode = "flat";
+    }
+    else {
+        schemaRecommendedMode = "full-json";
+    }
+    return {
+        version: 1,
+        analysisMode: "declared-properties-only",
+        analysisStatus,
+        ...(analysisCode ? { analysisCode } : {}),
+        ...(analysisMessage ? { analysisMessage } : {}),
+        schemaState,
+        inputFeasibility,
+        flatAvailable,
+        requiredSatisfiable,
+        flatCandidate,
+        schemaRecommendedMode,
+        ...(feasibilityCode ? { feasibilityCode } : {}),
+        fields,
+    };
+}
+export const FLAT_SAFE_KEY_REGEX = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+export const FLAT_ENCODING_GUIDELINES = [
+    "字符串: path=TEXT",
+    "JSON 标量与结构: path:=JSON (例如 count:=1, enabled:=true)",
+    "数组元素: path.INDEX=... (例如 items.0=first)",
+    "提示: 复杂嵌套或大段文本建议使用 --input 或 --input-file",
+];
+/**
+ * 依据 inputSchema 构造统一的 Action 输入编码建议。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 结构化编码建议报告
+ */
+export function buildActionInputAdvice(schema) {
+    if (typeof schema === "boolean") {
+        if (schema === false) {
+            return {
+                flatSupported: false,
+                hasFlatFields: false,
+                fields: [],
+                requiredTemplates: [],
+                optionalTemplates: [],
+                notes: ["布尔模式 false：拒绝所有输入，任何调用参数均判定为非法"],
+            };
+        }
+        return {
+            flatSupported: false,
+            hasFlatFields: false,
+            fields: [],
+            requiredTemplates: [],
+            optionalTemplates: [],
+            notes: [
+                "布尔模式 true：接受任意合法 JSON 输入；调用时无需指定必填参数，非对象根输入请使用 --input-file 或 --input",
+            ],
+        };
+    }
+    if (!schema || typeof schema !== "object") {
+        return {
+            flatSupported: false,
+            hasFlatFields: false,
+            fields: [],
+            requiredTemplates: [],
+            optionalTemplates: [],
+            notes: ["根模式未声明输入字段，直接调用或使用 --input-file / --input '{}'"],
+        };
+    }
+    const s = schema;
+    // 校验根模式是否为 object 类型
+    if (s.type !== undefined && s.type !== "object") {
+        return {
+            flatSupported: false,
+            hasFlatFields: false,
+            fields: [],
+            requiredTemplates: [],
+            optionalTemplates: [],
+            notes: [
+                `根模式类型为 '${s.type}'，不支持扁平赋值，建议使用 --input-file 或 --input`,
+            ],
+        };
+    }
+    const properties = (s.properties || {});
+    const required = Array.isArray(s.required) ? s.required : [];
+    const propKeys = Object.keys(properties);
+    if (propKeys.length === 0) {
+        return {
+            flatSupported: false,
+            hasFlatFields: false,
+            fields: [],
+            requiredTemplates: [],
+            optionalTemplates: [],
+            notes: ["根模式无声明属性，不支持扁平赋值，建议使用 --input-file 或 --input '{}'"],
+        };
+    }
+    const fields = [];
+    const requiredTemplates = [];
+    const optionalTemplates = [];
+    const notes = [];
+    for (const key of propKeys) {
+        const prop = properties[key] || {};
+        const typeStr = prop.type ? String(prop.type) : "any";
+        const isReq = required.includes(key);
+        const isFlatSafe = FLAT_SAFE_KEY_REGEX.test(key);
+        let assignmentTemplate;
+        let hint;
+        if (isFlatSafe) {
+            if (prop.type === "string") {
+                assignmentTemplate = `${key}=TEXT`;
+            }
+            else if (prop.type === "number" || prop.type === "integer") {
+                assignmentTemplate = `${key}:=NUMBER`;
+            }
+            else if (prop.type === "boolean") {
+                assignmentTemplate = `${key}:=BOOLEAN`;
+            }
+            else if (prop.type === "array" &&
+                prop.items &&
+                typeof prop.items === "object" &&
+                prop.items.type === "string") {
+                assignmentTemplate = `${key}.0=TEXT`;
+            }
+            else if (prop.type === "array" &&
+                prop.items &&
+                typeof prop.items === "object" &&
+                (prop.items.type === "number" || prop.items.type === "integer")) {
+                assignmentTemplate = `${key}.0:=NUMBER`;
+            }
+            else if (prop.type === "array" &&
+                prop.items &&
+                typeof prop.items === "object" &&
+                prop.items.type === "boolean") {
+                assignmentTemplate = `${key}.0:=BOOLEAN`;
+            }
+            else if (prop.type === "array") {
+                assignmentTemplate = `${key}:=JSON`;
+                hint = "数组结构建议使用 --input-file";
+            }
+            else if (prop.type === "object") {
+                assignmentTemplate = `${key}:=JSON`;
+                hint = "大型结构建议使用 --input-file";
+            }
+            else {
+                assignmentTemplate = `${key}:=JSON`;
+                hint = "复杂或未知类型建议使用 --input-file";
+            }
+            if (isReq) {
+                if (assignmentTemplate) {
+                    requiredTemplates.push(assignmentTemplate);
+                }
+            }
+            else {
+                if (assignmentTemplate) {
+                    optionalTemplates.push(assignmentTemplate);
+                }
+            }
+        }
+        else {
+            hint = "包含非安全字符，建议使用 --input-file";
+            notes.push(`属性 '${key}' 包含非安全字符，不支持扁平赋值，建议使用 --input-file`);
+        }
+        fields.push({
+            path: key,
+            type: typeStr,
+            required: isReq,
+            flatSafe: isFlatSafe,
+            assignmentTemplate,
+            hint,
+            description: prop.description,
+        });
+    }
+    const hasFlatFields = fields.some((f) => f.flatSafe && f.assignmentTemplate !== undefined);
+    // 仅当根模式为对象且所有 required 字段均具备 flatSafe 赋值方案时为 true
+    const allRequiredFlatSafe = required.every((reqKey) => {
+        const f = fields.find((field) => field.path === reqKey);
+        return f !== undefined && f.flatSafe && f.assignmentTemplate !== undefined;
+    });
+    const flatSupported = hasFlatFields && allRequiredFlatSafe;
+    return {
+        flatSupported,
+        hasFlatFields,
+        fields,
+        requiredTemplates,
+        optionalTemplates,
+        notes,
+    };
+}
+export { formatActionDetail } from "./describe.js";