@actiondock/core 2.6.0 → 2.7.0

package/dist/errors.d.ts

@@ -152,6 +152,26 @@ export declare const QUEUE_FULL = "QUEUE_FULL";
 export declare const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
 /** 输入通道已关闭拒绝继续写入 */
 export declare const INPUT_CLOSED = "INPUT_CLOSED";
+/** 扁平入参赋值表达式格式非法 */
+export declare const INVALID_FLAT_ARGUMENT = "INVALID_FLAT_ARGUMENT";
+/** 完整 JSON 文档解析失败 */
+export declare const INVALID_JSON = "INVALID_JSON";
+/** JSON 字面量解析失败或包含非有限数值 */
+export declare const INVALID_JSON_LITERAL = "INVALID_JSON_LITERAL";
+/** 扁平入参路径冲突 */
+export declare const INPUT_PATH_CONFLICT = "INPUT_PATH_CONFLICT";
+/** 扁平入参超出安全阈值上限 */
+export declare const FLAT_INPUT_LIMIT_EXCEEDED = "FLAT_INPUT_LIMIT_EXCEEDED";
+/** 输入数据超出上限（字节大小、嵌套深度等） */
+export declare const INPUT_LIMIT_EXCEEDED = "INPUT_LIMIT_EXCEEDED";
+/** 输入违反 ActionDock 安全策略（如包含全局禁止属性） */
+export declare const INPUT_POLICY_VIOLATION = "INPUT_POLICY_VIOLATION";
+/** 输入源互斥冲突 */
+export declare const INPUT_CONFLICT = "INPUT_CONFLICT";
+/** 输入文件不存在 */
+export declare const INPUT_FILE_NOT_FOUND = "INPUT_FILE_NOT_FOUND";
+/** 输入文件或流读取失败 */
+export declare const INPUT_FILE_READ_FAILED = "INPUT_FILE_READ_FAILED";
 /**
  * 进程领域结构化异常类。
  */

package/dist/errors.js

@@ -153,6 +153,26 @@ export const QUEUE_FULL = "QUEUE_FULL";
 export const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
 /** 输入通道已关闭拒绝继续写入 */
 export const INPUT_CLOSED = "INPUT_CLOSED";
+/** 扁平入参赋值表达式格式非法 */
+export const INVALID_FLAT_ARGUMENT = "INVALID_FLAT_ARGUMENT";
+/** 完整 JSON 文档解析失败 */
+export const INVALID_JSON = "INVALID_JSON";
+/** JSON 字面量解析失败或包含非有限数值 */
+export const INVALID_JSON_LITERAL = "INVALID_JSON_LITERAL";
+/** 扁平入参路径冲突 */
+export const INPUT_PATH_CONFLICT = "INPUT_PATH_CONFLICT";
+/** 扁平入参超出安全阈值上限 */
+export const FLAT_INPUT_LIMIT_EXCEEDED = "FLAT_INPUT_LIMIT_EXCEEDED";
+/** 输入数据超出上限（字节大小、嵌套深度等） */
+export const INPUT_LIMIT_EXCEEDED = "INPUT_LIMIT_EXCEEDED";
+/** 输入违反 ActionDock 安全策略（如包含全局禁止属性） */
+export const INPUT_POLICY_VIOLATION = "INPUT_POLICY_VIOLATION";
+/** 输入源互斥冲突 */
+export const INPUT_CONFLICT = "INPUT_CONFLICT";
+/** 输入文件不存在 */
+export const INPUT_FILE_NOT_FOUND = "INPUT_FILE_NOT_FOUND";
+/** 输入文件或流读取失败 */
+export const INPUT_FILE_READ_FAILED = "INPUT_FILE_READ_FAILED";
 /**
  * 进程领域结构化异常类。
  */

package/dist/export/templates.js

@@ -124,7 +124,7 @@ ad link "<skill_root>"
 
 ### 动作参数契约按需调阅
 
-在调用未知参数的 Action 前，可在终端执行命令按需查阅该 Action 的输入输出模式与详细说明：
+在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
 
 \`\`\`bash
 ad describe ${pkgId}/${firstAction}
@@ -134,29 +134,28 @@ ad describe ${pkgId}/${firstAction}
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
 
-推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
 \`\`\`bash
-# 写入参数到临时文件并通过 --input-file 传递
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-ad run ${pkgId}/${firstAction} --input-file /tmp/input.json
+# 调阅参数契约与建议赋值样例
+ad describe ${pkgId}/${firstAction}
 \`\`\`
 
-亦可通过内联参数进行简易命令调用：
+调用语法格式：
+ad run ${pkgId}/${firstAction} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ad describe ${pkgId}/${firstAction} 查阅的参数契约提供）
+
+将参数写入 JSON 文件并通过 --input-file 传递：
 
 \`\`\`bash
-ad run ${pkgId}/${firstAction} --input '{"param": "value"}'
+ad run ${pkgId}/${firstAction} --json --input-file input.json
 \`\`\`
 
-> **免注册本地执行**：
+> 免注册本地执行：
 > 若工作目录已位于本技能根目录，亦可直接免 link 执行：
 > \`\`\`bash
 > cd <skill_root>
-> ad run <action-id> --input-file /tmp/input.json
+> ad run ${firstAction} --json
 > \`\`\`
 
 ### 结构化响应解析
@@ -258,24 +257,31 @@ description: ${desc}
 ${desc}
 
 
+### 动作参数契约按需调阅
+
+在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
+
+\`\`\`bash
+${binaryRelPath} describe ${firstAction}
+\`\`\`
+
 ### 执行 Action
 
-推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
 \`\`\`bash
-# 写入参数到临时文件并通过 --input-file 传递
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-${binaryRelPath} run <action-id> --input-file /tmp/input.json
+# 调阅参数契约与建议赋值样例
+${binaryRelPath} describe ${firstAction}
 \`\`\`
 
-亦可通过内联参数进行简易命令调用：
+调用语法格式：
+${binaryRelPath} run ${firstAction} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ${binaryRelPath} describe ${firstAction} 查阅的参数契约提供）
+
+将参数写入 JSON 文件并通过 --input-file 传递：
 
 \`\`\`bash
-${binaryRelPath} run ${firstAction} --input '{"param": "value"}'
+${binaryRelPath} run ${firstAction} --json --input-file input.json
 \`\`\`
 
 ### 结构化响应解析
@@ -466,16 +472,22 @@ ${playbookEntries.join("\n")}
 ---`
         : "";
     const sInvoke = `## 标准调用命令
+ 
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
-推荐使用参数文件传递内容，杜绝终端引号转义问题：
+\`\`\`bash
+# 调阅参数契约与建议赋值样例
+ad describe ${sampleActionId}
+\`\`\`
 
+调用语法格式：
+ad run ${sampleActionId} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ad describe ${sampleActionId} 查阅的参数契约提供）
+ 
+将参数写入 JSON 文件并通过 --input-file 传递：
+ 
 \`\`\`bash
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-ad run ${sampleActionId} --input-file /tmp/input.json
+ad run ${sampleActionId} --json --input-file input.json
 \`\`\`
 
 ### 结构化响应解析

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from "./profile/index.js";
 export * from "./project/index.js";
 export * from "./registry/index.js";
 export * from "./runtime/index.js";
-export * from "./schema/validator.js";
+export * from "./schema/index.js";
 export * from "./server/index.js";
 export * from "./storage/index.js";
 export * from "./utils/index.js";
@@ -19,4 +19,6 @@ export * from "./host/index.js";
 export * from "./target/index.js";
 export * from "./ipc/index.js";
 export * from "./process/index.js";
+export * from "./input/index.js";
+export * from "./json/index.js";
 export type { ModuleLoader } from "./runtime/index.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export * from "./profile/index.js";
 export * from "./project/index.js";
 export * from "./registry/index.js";
 export * from "./runtime/index.js";
-export * from "./schema/validator.js";
+export * from "./schema/index.js";
 export * from "./server/index.js";
 export * from "./storage/index.js";
 export * from "./utils/index.js";
@@ -19,3 +19,5 @@ export * from "./host/index.js";
 export * from "./target/index.js";
 export * from "./ipc/index.js";
 export * from "./process/index.js";
+export * from "./input/index.js";
+export * from "./json/index.js";

package/dist/input/advice.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 单个字段的输入建议明细（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;
+export declare const FLAT_SAFE_KEY_REGEX: RegExp;
+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";