@actiondock/core 2.6.0 → 2.8.0

package/dist/input/advice.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 单个字段的输入建议明细（v1 机器契约）。
+ */
+export interface CliInputFieldAdviceV1 {
+    /** 字段路径（属性名） */
+    path: string;
+    /** 是否允许作为输入传入 */
+    inputAllowed: boolean;
+    /** 是否可通过扁平语法安全赋值 */
+    flatSafe: boolean;
+    /** 是否为必填字段 */
+    required?: boolean;
+    /** 字段模式类型 */
+    type?: string;
+    /** 赋值操作符（"=" 或 ":="） */
+    operator?: "=" | ":=";
+    /** 编码类型标识 */
+    encoding?: "string" | "json-number" | "json-boolean" | "json-null" | "json-array" | "json-object" | "json" | string;
+    /** 赋值模板样例 */
+    assignmentTemplate?: string;
+    /** 无法通过扁平赋值或被禁止的原因代码 */
+    reason?: "FORBIDDEN_PROPERTY" | "UNSAFE_FLAT_PROPERTY" | "PROPERTY_SCHEMA_FALSE" | string;
+    /** 推荐的降级输入通道 */
+    fallback?: "stdin-json" | null;
+    /** 字段描述信息 */
+    description?: string;
+    /** 人类提示信息 */
+    hint?: string;
+}
+/**
+ * Action 输入模式编码顾问分析报告（v1 机器契约）。
+ */
+export interface CliInputAdviceV1 {
+    version: 1;
+    analysisMode: "declared-properties-only";
+    analysisStatus: "ok" | "unsupported" | "malformed";
+    analysisCode?: "MALFORMED_SCHEMA" | "COMPLEX_SCHEMA" | "UNSUPPORTED_SCHEMA_SHAPE";
+    analysisMessage?: string;
+    schemaState: "absent" | "reject-all" | "any" | "object" | "json-only" | "complex";
+    inputFeasibility: "known-impossible" | "possible-or-unknown";
+    flatAvailable: boolean;
+    requiredSatisfiable: boolean | null;
+    flatCandidate: boolean;
+    schemaRecommendedMode: "none" | "flat" | "full-json";
+    feasibilityCode?: "SCHEMA_REJECTS_ALL" | "REQUIRED_FIELD_FORBIDDEN" | "REQUIRED_FIELD_REJECTS_ALL" | "REQUIRED_FIELD_DISALLOWED_BY_ADDITIONAL_PROPERTIES";
+    fields: CliInputFieldAdviceV1[];
+}
+/**
+ * 依据 inputSchema 构造 v1 版本的 Action 输入编码顾问报告（机器契约）。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 遵循技术设计文档规范的结构化输入建议
+ */
+export declare function buildCliInputAdviceV1(schema: unknown): CliInputAdviceV1;
+/**
+ * 扁平编码通用指引文案。
+ * 属性名安全判定统一引用 flat-predicates 的单一事实源（含禁止属性排除），
+ * 禁止在本文件另建独立正则分叉。
+ */
+export declare const FLAT_ENCODING_GUIDELINES: readonly string[];
+/**
+ * 单个字段的输入建议明细。
+ */
+export interface ActionInputFieldAdvice {
+    /** 字段路径（属性名） */
+    path: string;
+    /** 字段类型字符串 */
+    type: string;
+    /** 是否为必填字段 */
+    required: boolean;
+    /** 字段名是否满足扁平编码安全规范 */
+    flatSafe: boolean;
+    /** 编码模板（如 "name=TEXT"、"age:=NUMBER"、"meta:=JSON"），非直接可执行 token */
+    assignmentTemplate?: string;
+    /** 人类说明文字，如 "大型结构建议使用 --input-file" */
+    hint?: string;
+    /** 字段描述信息 */
+    description?: string;
+}
+/**
+ * Action 输入模式整体编码顾问分析报告。
+ */
+export interface ActionInputAdvice {
+    /** 根模式是否支持扁平入参赋值（仅当根模式为对象且所有 required 字段均具备 flatSafe 赋值方案时为 true） */
+    flatSupported: boolean;
+    /** 是否存在至少一个可扁平化的字段 */
+    hasFlatFields: boolean;
+    /** 字段明细清单 */
+    fields: ActionInputFieldAdvice[];
+    /** 所有必填字段的编码模板数组 */
+    requiredTemplates: string[];
+    /** 可选字段的编码模板数组 */
+    optionalTemplates: string[];
+    /** 结构化提示与降级说明清单 */
+    notes: string[];
+}
+/**
+ * 依据 inputSchema 构造统一的 Action 输入编码建议。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 结构化编码建议报告
+ */
+export declare function buildActionInputAdvice(schema: unknown): ActionInputAdvice;
+export { formatActionDetail } from "./describe.js";