@actiondock/cli 2.3.0 → 2.4.0

package/dist/commands/action/create.d.ts

@@ -1,7 +1,14 @@
 import type { Command } from "commander";
 import type { CliContext } from "../../types.js";
 /**
- * 注册 action 命令组（action create, action new）。
+ * 解析用户通过命令行传入的字段定义字符串（如 name:string, count?:number）。
+ */
+export declare function parseSchemaFields(rawFields?: string[] | string): {
+    properties: Record<string, any>;
+    required: string[];
+} | null;
+/**
+ * 注册 action 命令组（action create, action list, action describe, action run, action validate）。
  *
  * @param program Commander 根程序对象
  * @param context 命令行上下文

package/dist/commands/action/create.js

@@ -1,10 +1,68 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
-import { assertPathWithinRoot, checkGeneratedTypes, findProjectRoot, getPackageSlug, loadManifest, loadProjectConfig, saveManifest, writeActionTypes, } from "@actiondock/core";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { assertPathWithinRoot, findProjectRoot, getPackageSlug, loadManifest, loadProjectConfig, saveManifest, writeActionTypes, } from "@actiondock/core";
 import { ExecutionError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
+import { attachDescribeCommand } from "../describe.js";
+import { attachListCommand } from "../list.js";
+import { attachRunCommand } from "../run.js";
+import { attachValidateCommand } from "../validate.js";
 /**
- * 注册 action 命令组（action create, action new）。
+ * 解析用户通过命令行传入的字段定义字符串（如 name:string, count?:number）。
+ */
+export function parseSchemaFields(rawFields) {
+    if (!rawFields)
+        return null;
+    const items = Array.isArray(rawFields) ? rawFields : [rawFields];
+    const tokens = items
+        .flatMap((item) => item.split(/[, ]+/))
+        .map((t) => t.trim())
+        .filter(Boolean);
+    if (tokens.length === 0)
+        return null;
+    const properties = {};
+    const required = [];
+    for (const token of tokens) {
+        const colonIdx = token.indexOf(":");
+        let rawKey = colonIdx > -1 ? token.slice(0, colonIdx).trim() : token.trim();
+        const rawType = colonIdx > -1 ? token.slice(colonIdx + 1).trim().toLowerCase() : "string";
+        let isOptional = false;
+        if (rawKey.endsWith("?")) {
+            isOptional = true;
+            rawKey = rawKey.slice(0, -1).trim();
+        }
+        if (!rawKey)
+            continue;
+        let schemaType = "string";
+        const extraProps = {};
+        if (rawType === "number" || rawType === "int" || rawType === "integer") {
+            schemaType = "number";
+        }
+        else if (rawType === "boolean" || rawType === "bool") {
+            schemaType = "boolean";
+        }
+        else if (rawType === "array" || rawType === "list") {
+            schemaType = "array";
+            extraProps.items = { type: "string" };
+        }
+        else if (rawType === "object" || rawType === "json") {
+            schemaType = "object";
+        }
+        else {
+            schemaType = "string";
+        }
+        properties[rawKey] = {
+            type: schemaType,
+            ...extraProps,
+        };
+        if (!isOptional) {
+            required.push(rawKey);
+        }
+    }
+    return { properties, required };
+}
+/**
+ * 注册 action 命令组（action create, action list, action describe, action run, action validate）。
  *
  * @param program Commander 根程序对象
  * @param context 命令行上下文
@@ -12,16 +70,21 @@ import { writeStdout } from "../../renderer.js";
 export function registerActionCommands(program, context) {
     const actionCmd = program
         .command("action")
-        .description("Manage Action definitions (create, scaffold)");
+        .description("Manage Action definitions and lifecycle (create, list, describe, run, validate)");
     actionCmd
         .command("create <id>")
-        .alias("new")
         .description("Scaffold a new Action definition file")
         .option("-d, --desc <description>", "Action description")
         .option("-f, --file <filePath>", "Target file path relative to actions dir")
+        .option("-i, --input <fields...>", "Input schema fields (e.g. name:string, count?:number)")
+        .option("-o, --output <fields...>", "Output schema fields (e.g. message:string, success:boolean)")
         .action(async (id, options) => {
         await handleActionCreate(id, options, context);
     });
+    attachListCommand(actionCmd, context);
+    attachDescribeCommand(actionCmd, context);
+    attachRunCommand(actionCmd, context);
+    attachValidateCommand(actionCmd, context);
 }
 export async function handleActionCreate(id, options, context) {
     const root = findProjectRoot();
@@ -44,29 +107,79 @@ export async function handleActionCreate(id, options, context) {
         if (existsSync(targetFullFile)) {
             throw new ExecutionError(`Target action file already exists at ${targetFullFile}`);
         }
+        const targetDir = dirname(targetFullFile);
+        if (!existsSync(targetDir)) {
+            mkdirSync(targetDir, { recursive: true });
+        }
+        const generatedTypesTarget = resolve(root, ".actiondock", "generated", "actions");
+        let typesImportPath = relative(targetDir, generatedTypesTarget).replace(/\\/g, "/");
+        if (!typesImportPath.startsWith("./") && !typesImportPath.startsWith("../")) {
+            typesImportPath = `./${typesImportPath}`;
+        }
+        const parsedInput = parseSchemaFields(options.input);
+        const parsedOutput = parseSchemaFields(options.output);
+        const inputSchema = parsedInput
+            ? {
+                type: "object",
+                properties: parsedInput.properties,
+                required: parsedInput.required,
+            }
+            : {
+                type: "object",
+                properties: {
+                    exampleParam: {
+                        type: "string",
+                        description: "Example parameter description",
+                    },
+                },
+                required: [],
+            };
+        const outputSchema = parsedOutput
+            ? {
+                type: "object",
+                properties: parsedOutput.properties,
+                required: parsedOutput.required,
+            }
+            : {
+                type: "object",
+                properties: {
+                    success: { type: "boolean" },
+                },
+                required: ["success"],
+            };
+        // 纯粹根据 outputSchema 的字段类型生成中性占位值，杜绝业务语义假设与虚假字段访问
+        const propEntries = Object.entries(outputSchema.properties || {});
+        let returnBody;
+        if (propEntries.length === 0) {
+            returnBody = "  return {};";
+        }
+        else {
+            const returnLines = propEntries.map(([k, prop]) => {
+                const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+                let defaultVal = '"done"';
+                if (prop.type === "number" || prop.type === "integer")
+                    defaultVal = "0";
+                else if (prop.type === "boolean")
+                    defaultVal = "true";
+                else if (prop.type === "array")
+                    defaultVal = "[]";
+                else if (prop.type === "object")
+                    defaultVal = "{}";
+                return `    ${safeKey}: ${defaultVal},`;
+            });
+            returnBody = `  return {\n${returnLines.join("\n")}\n  };`;
+        }
         const desc = options.desc || `Action ${id}`;
         const template = `import { defineAction } from "@actiondock/sdk";
+import type { ActionInput, ActionOutput } from "${typesImportPath}";
 
-export interface Input {
-  exampleParam?: string;
-}
-
-export interface Output {
-  success: boolean;
-  result?: unknown;
-}
+export type Input = ActionInput<"${id}">;
+export type Output = ActionOutput<"${id}">;
 
 export default defineAction<Input, Output>(async (input, ctx) => {
   ctx.log.info("Running ${id}", input);
 
-  // Access config: ctx.config.get("MY_CONFIG")
-  // Access state:  await ctx.state.get("my_key") / await ctx.state.set("my_key", val)
-  // Call action:   await ctx.actions.invoke(otherAction, input)
-
-  return {
-    success: true,
-    result: input.exampleParam || "done",
-  };
+${returnBody}
 });
 `;
         writeFileSync(targetFullFile, template, "utf-8");
@@ -81,36 +194,35 @@ export default defineAction<Input, Output>(async (input, ctx) => {
         manifest.actions[id] = {
             entry: join(config.actionsDir || "actions", targetRelFile).replace(/\\/g, "/"),
             description: desc,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    exampleParam: {
-                        type: "string",
-                        description: "Example parameter description",
-                    },
-                },
-                required: [],
-            },
-            outputSchema: {
-                type: "object",
-                properties: {
-                    success: { type: "boolean" },
-                    result: {},
-                },
-                required: ["success"],
-            },
+            inputSchema,
+            outputSchema,
             uses: [],
             tags: [],
         };
         saveManifest(root, manifest);
-        // 若当前项目已存在类型生成文件，则同步自动刷新类型声明
-        const typeCheck = checkGeneratedTypes(root, manifest);
-        if (typeCheck.exists) {
-            writeActionTypes(root, manifest);
+        // 始终自动生成或更新类型声明文件，确保单一事实源即时生效
+        writeActionTypes(root, manifest);
+        let sampleInputStr = "{}";
+        const inputEntries = Object.entries(inputSchema.properties || {});
+        if (inputEntries.length > 0) {
+            const sampleObj = {};
+            for (const [k, prop] of inputEntries) {
+                if (prop.type === "number" || prop.type === "integer")
+                    sampleObj[k] = 42;
+                else if (prop.type === "boolean")
+                    sampleObj[k] = true;
+                else if (prop.type === "array")
+                    sampleObj[k] = ["item"];
+                else if (prop.type === "object")
+                    sampleObj[k] = {};
+                else
+                    sampleObj[k] = "hello";
+            }
+            sampleInputStr = JSON.stringify(sampleObj);
         }
         writeStdout(`[OK] Created Action '${id}' at ${targetFullFile}`, context);
         writeStdout(`\nTo run this action:`, context);
-        writeStdout(`  ad run ${id} --input '{"exampleParam": "hello"}'`, context);
+        writeStdout(`  ad run ${id} --input '${sampleInputStr}'`, context);
     }
     catch (err) {
         if (err instanceof ExecutionError)

package/dist/commands/action/index.d.ts

@@ -0,0 +1 @@
+export * from "./create.js";

package/dist/commands/action/index.js

@@ -0,0 +1 @@
+export * from "./create.js";

package/dist/commands/describe.d.ts

@@ -1,5 +1,12 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+/**
+ * 挂载 describe 子命令至指定 Commander 节点。
+ *
+ * @param parent 目标 Commander 命令节点
+ * @param context 命令行上下文
+ */
+export declare function attachDescribeCommand(parent: Command, context?: CliContext): Command;
 /**
  * 注册顶层统一 describe 命令：查询指定 Action 的规范结构与模式定义。
  *

package/dist/commands/describe.js

@@ -2,13 +2,13 @@ import { ArgumentError, ExecutionError } from "../errors.js";
 import { renderActionDetail, renderResult } from "../renderer.js";
 import { getEffectiveOptions, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
 /**
- * 注册顶层统一 describe 命令：查询指定 Action 的规范结构与模式定义。
+ * 挂载 describe 子命令至指定 Commander 节点。
  *
- * @param program Commander 根程序对象
+ * @param parent 目标 Commander 命令节点
  * @param context 命令行上下文
  */
-export function registerDescribeCommand(program, context) {
-    program
+export function attachDescribeCommand(parent, context) {
+    return parent
         .command("describe <id>")
         .alias("show")
         .description("Show action definition, schema, and description")
@@ -66,3 +66,12 @@ export function registerDescribeCommand(program, context) {
         }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });
     });
 }
+/**
+ * 注册顶层统一 describe 命令：查询指定 Action 的规范结构与模式定义。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerDescribeCommand(program, context) {
+    attachDescribeCommand(program, context);
+}

package/dist/commands/index.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
-import { registerActionCommands } from "./action/create.js";
+import { registerActionCommands } from "./action/index.js";
 import { registerAddCommand } from "./add.js";
 import { registerBuildCommand } from "./build.js";
 import { registerConfigCommands } from "./config/index.js";
@@ -13,7 +13,6 @@ import { registerInitCommand } from "./init.js";
 import { registerLinkCommands } from "./link.js";
 import { registerListCommand } from "./list.js";
 import { registerMcpCommands } from "./mcp.js";
-import { registerNewCommands } from "./new.js";
 import { registerPackCommand } from "./pack.js";
 import { registerPlaybookCommands } from "./playbook.js";
 import { registerProfileCommands } from "./profile.js";
@@ -29,4 +28,4 @@ import { registerValidateCommand } from "./validate.js";
  */
 export declare const CLI_VERSION: string;
 export declare function createCliProgram(context?: CliContext): Command;
-export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerNewCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };
+export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };

package/dist/commands/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
-import { registerActionCommands } from "./action/create.js";
+import { registerActionCommands } from "./action/index.js";
 import { registerAddCommand } from "./add.js";
 import { registerBuildCommand } from "./build.js";
 import { registerConfigCommands } from "./config/index.js";
@@ -14,7 +14,6 @@ import { registerInitCommand } from "./init.js";
 import { registerLinkCommands } from "./link.js";
 import { registerListCommand } from "./list.js";
 import { registerMcpCommands } from "./mcp.js";
-import { registerNewCommands } from "./new.js";
 import { registerPackCommand } from "./pack.js";
 import { registerPlaybookCommands } from "./playbook.js";
 import { registerProfileCommands } from "./profile.js";
@@ -84,7 +83,6 @@ export function createCliProgram(context) {
     registerInitCommand(program);
     registerAddCommand(program, context);
     registerRemoveCommand(program, context);
-    registerNewCommands(program, context);
     registerActionCommands(program, context);
     registerInfoCommand(program, context);
     registerDoctorCommand(program, context);
@@ -108,4 +106,4 @@ export function createCliProgram(context) {
     applyCommonOptions(program);
     return program;
 }
-export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerNewCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };
+export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };

package/dist/commands/list.d.ts

@@ -1,5 +1,12 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+/**
+ * 挂载 list 子命令至指定 Commander 节点。
+ *
+ * @param parent 目标 Commander 命令节点
+ * @param context 命令行上下文
+ */
+export declare function attachListCommand(parent: Command, context?: CliContext): Command;
 /**
  * 注册顶层统一 list 命令：列出当前工程、已链接包或远端服务中的可用 Action。
  *

package/dist/commands/list.js

@@ -3,13 +3,13 @@ import { ArgumentError } from "../errors.js";
 import { renderActionList, renderResult } from "../renderer.js";
 import { getEffectiveOptions, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, withTarget } from "../utils/index.js";
 /**
- * 注册顶层统一 list 命令：列出当前工程、已链接包或远端服务中的可用 Action。
+ * 挂载 list 子命令至指定 Commander 节点。
  *
- * @param program Commander 根程序对象
+ * @param parent 目标 Commander 命令节点
  * @param context 命令行上下文
  */
-export function registerListCommand(program, context) {
-    program
+export function attachListCommand(parent, context) {
+    return parent
         .command("list [patterns...]")
         .description("List actions in current project, linked packages, or remote profile")
         .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
@@ -75,3 +75,12 @@ export function registerListCommand(program, context) {
         }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });
     });
 }
+/**
+ * 注册顶层统一 list 命令：列出当前工程、已链接包或远端服务中的可用 Action。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerListCommand(program, context) {
+    attachListCommand(program, context);
+}

package/dist/commands/playbook.js

@@ -361,10 +361,9 @@ export function registerPlaybookCommands(program, context) {
             return;
         }
     });
-    // playbook create / new
+    // playbook create
     pbCmd
         .command("create <id>")
-        .alias("new")
         .description("Scaffold a new Playbook markdown file")
         .option("-d, --desc <description>", "Playbook description")
         .option("-a, --actions <actions...>", "Referenced action IDs")

package/dist/commands/run.d.ts

@@ -4,6 +4,13 @@ import type { CliContext } from "../types.js";
  * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
  */
 export declare function executeAction(id: string, options: any, context?: CliContext): Promise<void>;
+/**
+ * 挂载 run 子命令至指定 Commander 节点。
+ *
+ * @param parent 目标 Commander 命令节点
+ * @param context 命令行上下文
+ */
+export declare function attachRunCommand(parent: Command, context?: CliContext): Command;
 /**
  * 注册顶层统一 run 命令：执行指定 Action。
  *

package/dist/commands/run.js

@@ -117,13 +117,13 @@ export async function executeAction(id, options, context) {
     }
 }
 /**
- * 注册顶层统一 run 命令：执行指定 Action。
+ * 挂载 run 子命令至指定 Commander 节点。
  *
- * @param program Commander 根程序对象
+ * @param parent 目标 Commander 命令节点
  * @param context 命令行上下文
  */
-export function registerRunCommand(program, context) {
-    program
+export function attachRunCommand(parent, context) {
+    return parent
         .command("run <id>")
         .description("Execute an action (from current project, linked packages, or remote profile)")
         .option("-P, --package <id>", "Target package ID or path")
@@ -144,3 +144,12 @@ export function registerRunCommand(program, context) {
         await executeAction(id, options, context);
     });
 }
+/**
+ * 注册顶层统一 run 命令：执行指定 Action。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerRunCommand(program, context) {
+    attachRunCommand(program, context);
+}

package/dist/commands/validate.d.ts

@@ -1,5 +1,12 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+/**
+ * 挂载 validate 子命令至指定 Commander 节点。
+ *
+ * @param parent 目标 Commander 命令节点
+ * @param context 命令行上下文
+ */
+export declare function attachValidateCommand(parent: Command, context?: CliContext): Command;
 /**
  * 注册顶层统一 validate 命令：校验 Action 的 Schema 与方法定义完整性。
  *

package/dist/commands/validate.js

@@ -3,13 +3,13 @@ import { ArgumentError, ExecutionError } from "../errors.js";
 import { renderActionValidation, renderResult } from "../renderer.js";
 import { getEffectiveOptions } from "../utils/index.js";
 /**
- * 注册顶层统一 validate 命令：校验 Action 的 Schema 与方法定义完整性。
+ * 挂载 validate 子命令至指定 Commander 节点。
  *
- * @param program Commander 根程序对象
+ * @param parent 目标 Commander 命令节点
  * @param context 命令行上下文
  */
-export function registerValidateCommand(program, context) {
-    program
+export function attachValidateCommand(parent, context) {
+    return parent
         .command("validate [id]")
         .description("Validate action schemas and definitions")
         .option("-P, --package <id>", "Target package ID or path")
@@ -104,3 +104,12 @@ export function registerValidateCommand(program, context) {
         }
     });
 }
+/**
+ * 注册顶层统一 validate 命令：校验 Action 的 Schema 与方法定义完整性。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerValidateCommand(program, context) {
+    attachValidateCommand(program, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,11 +34,11 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.3.0",
-    "@actiondock/core": "^2.3.0",
-    "@actiondock/mcp": "^2.3.0",
-    "@actiondock/runtime-node": "^2.3.0",
-    "@actiondock/sdk": "^2.3.0",
+    "@actiondock/builder": "^2.4.0",
+    "@actiondock/core": "^2.4.0",
+    "@actiondock/mcp": "^2.4.0",
+    "@actiondock/runtime-node": "^2.4.0",
+    "@actiondock/sdk": "^2.4.0",
     "commander": "^13.1.0"
   },
   "devDependencies": {

package/dist/commands/new.d.ts

@@ -1,9 +0,0 @@
-import type { Command } from "commander";
-import type { CliContext } from "../types.js";
-/**
- * 注册顶层 new 脚手架命令（new action, new playbook）。
- *
- * @param program Commander 根程序对象
- * @param context 命令行上下文
- */
-export declare function registerNewCommands(program: Command, context?: CliContext): void;

package/dist/commands/new.js

@@ -1,33 +0,0 @@
-import { handleActionCreate } from "./action/create.js";
-import { handlePlaybookCreate } from "./playbook.js";
-/**
- * 注册顶层 new 脚手架命令（new action, new playbook）。
- *
- * @param program Commander 根程序对象
- * @param context 命令行上下文
- */
-export function registerNewCommands(program, context) {
-    const newCmd = program
-        .command("new")
-        .description("Scaffold a new Action or Playbook in current project");
-    // new action <id>
-    newCmd
-        .command("action <id>")
-        .alias("create")
-        .description("Scaffold a new Action definition file")
-        .option("-d, --desc <description>", "Action description")
-        .option("-f, --file <filePath>", "Target file path relative to actions dir")
-        .action(async (id, options) => {
-        await handleActionCreate(id, options, context);
-    });
-    // new playbook <id>
-    newCmd
-        .command("playbook <id>")
-        .description("Scaffold a new Playbook markdown file")
-        .option("-d, --desc <description>", "Playbook description")
-        .option("-a, --actions <actions...>", "Referenced action IDs")
-        .option("-f, --file <filePath>", "Target file path relative to playbooks dir")
-        .action((id, options) => {
-        handlePlaybookCreate(id, options, context);
-    });
-}