@actiondock/cli 2.9.1 → 2.10.0

package/README.md

@@ -170,7 +170,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--json` 输出标准信封） |
 | `ad validate [id]` | 校验 Action 规范与模式规范 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
-| `ad action create <id>` | 创建新 Action 源码（别名 `ad action new`） |
+| `ad action create <id>` | 创建新 Action 源码 |
 | `ad playbook list` / `show` | 查看智能体操作规程 Playbook |
 | `ad config list` / `get` / `set` | 管理包运行时配置与环境变量绑定 |
 | `ad state list` / `get` / `set` / `delete` / `clear` | 查看与维护 SQLite 持久化状态 |

package/dist/commands/config/schema.js

@@ -1,6 +1,6 @@
 import { isSecretConfigKey, } from "@actiondock/core/project";
 import { notInProjectError } from "../../errors.js";
-import { renderConfigSchema, renderResult, writeStdout } from "../../renderer.js";
+import { renderConfigSchema, renderResult } from "../../renderer.js";
 import { buildMergedConfigEntries } from "../../services/config-merge.js";
 import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, withService } from "../../utils/index.js";
 /**
@@ -78,17 +78,23 @@ export function registerConfigSchemaCommand(configCmd, context) {
                 ok,
                 missingCount: missingRequired.length,
                 configs: items,
+                ...(!ok
+                    ? {
+                        hints: [
+                            "Tip: Run 'ad config set <KEY> <val>' to configure required settings.",
+                        ],
+                    }
+                    : {}),
             };
-            if (options.json) {
-                renderResult(result, {
-                    json: options.json,
-                    context,
-                });
-            }
-            else {
-                writeStdout(renderConfigSchema(items, projConfig.id, root) + "\n", context);
-            }
+            renderResult(result, {
+                json: options.json,
+                humanFormatter: () => renderConfigSchema(items, projConfig.id, root) + "\n",
+                context,
+            });
             if (!ok) {
+                if (context) {
+                    context.exitCode = 1;
+                }
                 process.exitCode = 1;
             }
         }, { localRoot: root });

package/dist/commands/describe.js

@@ -38,7 +38,10 @@ export function attachDescribeCommand(parent, context) {
             catch (err) {
                 const code = err?.code;
                 if (code === ACTION_NOT_FOUND || code === NOT_FOUND || code === PACKAGE_NOT_FOUND) {
-                    throw new ArgumentError(err?.message || String(err), err?.details, code);
+                    const hint = (code === ACTION_NOT_FOUND || code === NOT_FOUND)
+                        ? "Tip: Run 'ad list' to discover available actions."
+                        : (err?.hint || err?.details?.hint);
+                    throw new ArgumentError(err?.message || String(err), err?.details, code, hint);
                 }
                 throw new ExecutionError(err?.message || String(err), err?.details, code);
             }

package/dist/commands/index.js

@@ -77,6 +77,26 @@ export function createCliProgram(context) {
     program.exitOverride((err) => {
         throw err;
     });
+    if (context?.stdout || context?.stderr) {
+        program.configureOutput({
+            writeOut: (str) => {
+                if (context.stdout)
+                    context.stdout(str);
+                else
+                    process.stdout.write(str);
+            },
+            writeErr: (str) => {
+                if (context.stderr)
+                    context.stderr(str);
+                else
+                    process.stderr.write(str);
+            },
+        });
+    }
+    program.addHelpText("after", `
+Workflow Guidance:
+  For multi-step workflows, run 'ad playbook list' before invoking atomic actions.
+  Run 'ad info [intent]' to discover packages and playbooks by keyword.`);
     registerInitCommand(program);
     registerAddCommand(program, context);
     registerRemoveCommand(program, context);

package/dist/commands/info.js

@@ -9,6 +9,26 @@ import { applyTargetOptions, getEffectiveOptions, resolveFallbackStrategy, resol
  * 将远端信息响应归一为本地工程详情视图。
  */
 function remoteInfoToDetail(remoteInfo) {
+    const actionsMap = new Map();
+    const rawActions = remoteInfo.actionsDetail || remoteInfo.actions || [];
+    for (const a of rawActions) {
+        if (typeof a === "string") {
+            actionsMap.set(a, { id: a });
+        }
+        else if (a && typeof a === "object") {
+            actionsMap.set(a.id, { id: a.id, description: a.description });
+        }
+    }
+    const playbooksMap = new Map();
+    const rawPlaybooks = remoteInfo.playbooksDetail || remoteInfo.playbooks || [];
+    for (const pb of rawPlaybooks) {
+        if (typeof pb === "string") {
+            playbooksMap.set(pb, { id: pb });
+        }
+        else if (pb && typeof pb === "object") {
+            playbooksMap.set(pb.id, { id: pb.id, description: pb.description });
+        }
+    }
     return {
         id: remoteInfo.id,
         name: remoteInfo.name || remoteInfo.id,
@@ -17,12 +37,14 @@ function remoteInfoToDetail(remoteInfo) {
         projectRoot: remoteInfo.path || remoteInfo.projectRoot || "",
         actionsDir: "remote",
         playbooksDir: "remote",
-        actionsCount: remoteInfo.actionsCount || (remoteInfo.actions ? remoteInfo.actions.length : 0),
-        playbooksCount: remoteInfo.playbooksCount || (remoteInfo.playbooks ? remoteInfo.playbooks.length : 0),
-        actions: (remoteInfo.actionsDetail || remoteInfo.actions || []).map((a) => typeof a === "string" ? a : a.id),
-        playbooks: (remoteInfo.playbooksDetail || remoteInfo.playbooks || []).map((pb) => typeof pb === "string" ? pb : pb.id),
+        actionsCount: actionsMap.size,
+        playbooksCount: playbooksMap.size,
+        actions: Array.from(actionsMap.keys()),
+        playbooks: Array.from(playbooksMap.keys()),
         configDeclared: Object.keys(remoteInfo.configDeclared || {}),
         configDef: remoteInfo.configDeclared,
+        actionsMap,
+        playbooksMap,
     };
 }
 /**
@@ -116,6 +138,9 @@ export function registerInfoCommand(program, context) {
         }
         // 扫描本地候选包（当前工程根目录 + 全局已链接包）
         const { currentRoot, aggregated } = scanLocalAggregatedPackages(context);
+        const infoHints = [
+            "Tip: Run 'ad info <package-id>' to view detailed package configuration and schema.",
+        ];
         // 无关键字过滤场景
         if (!effectiveIntent) {
             if (currentRoot) {
@@ -130,7 +155,7 @@ export function registerInfoCommand(program, context) {
                 });
                 return;
             }
-            renderResult({ linkedPackages: aggregated }, {
+            renderResult({ linkedPackages: aggregated, hints: infoHints }, {
                 ...outOpts,
                 humanFormatter: () => renderAggregatedPackages(aggregated),
             });
@@ -147,7 +172,7 @@ export function registerInfoCommand(program, context) {
         }
         if (aggregated.length === 0) {
             if (isMachine) {
-                renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false }, outOpts);
+                renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false, hints: infoHints }, outOpts);
                 return;
             }
             throw new ExecutionError(`No ActionDock project or linked packages available to match '${effectiveIntent}'`);
@@ -164,14 +189,14 @@ export function registerInfoCommand(program, context) {
         if (filterRes.matchedCount === 0) {
             if (!filterRes.isFallback) {
                 if (isMachine) {
-                    renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false }, outOpts);
+                    renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false, hints: infoHints }, outOpts);
                     return;
                 }
                 throw new ExecutionError(`No packages matched intent '${effectiveIntent}'`);
             }
             // 回退模式：展示全部包并附带提示
             if (isMachine) {
-                renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0 }, outOpts);
+                renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0, hints: infoHints }, outOpts);
                 return;
             }
             renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0 }, {
@@ -183,7 +208,7 @@ export function registerInfoCommand(program, context) {
         }
         // 机器模式下搜索：稳定返回列表结构，不因为 matchedCount === 1 突变为详情
         if (isMachine) {
-            renderResult({ linkedPackages: filterRes.items, matchedCount: filterRes.matchedCount, isFallback: false }, outOpts);
+            renderResult({ linkedPackages: filterRes.items, matchedCount: filterRes.matchedCount, isFallback: false, hints: infoHints }, outOpts);
             return;
         }
         // 人类终端交互：精确匹配单个包展开详情

package/dist/commands/list.js

@@ -63,8 +63,19 @@ export function attachListCommand(parent, context) {
                 };
             });
             const filterRes = filterWithFallbackInfo(rawList, effectiveIntent, [(a) => a.id, (a) => a.description], shouldFallback);
-            if (filterRes.isFallback && isMachine) {
-                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+            const hints = [
+                "Tip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.",
+            ];
+            if (isMachine) {
+                if (filterRes.isFallback) {
+                    renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0, hints }, { json: options.json, context });
+                    return;
+                }
+                renderResult({
+                    items: filterRes.items,
+                    ...(filterRes.matchedCount !== undefined ? { matchedCount: filterRes.matchedCount } : {}),
+                    hints,
+                }, { json: options.json, context });
                 return;
             }
             const title = resolved.type === "remote"

package/dist/commands/playbook.js

@@ -31,6 +31,9 @@ export function registerPlaybookCommands(program, context) {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const { shouldFallback, isMachine } = resolveFallbackStrategy(options);
+        const hints = [
+            "Tip: Run 'ad playbook show <id>' to inspect procedure steps before execution.",
+        ];
         // 1. 远端服务分支
         const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
@@ -40,6 +43,10 @@ export function registerPlaybookCommands(program, context) {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
                 insecure: target.insecure,
             });
+            if (isMachine) {
+                renderResult({ items: remotePbs, hints }, { json: options.json, context });
+                return;
+            }
             renderResult(remotePbs, {
                 json: options.json,
                 humanFormatter: () => renderPlaybookList(remotePbs, `Playbooks ${remoteTargetSuffix(target)}`, false, effectiveIntent),
@@ -67,8 +74,16 @@ export function registerPlaybookCommands(program, context) {
                 packageId: config.id,
             }));
             const filterRes = filterWithFallbackInfo(rawList, effectiveIntent, [(p) => p.id, (p) => p.description], shouldFallback);
-            if (filterRes.isFallback && isMachine) {
-                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+            if (isMachine) {
+                if (filterRes.isFallback) {
+                    renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0, hints }, { json: options.json, context });
+                    return;
+                }
+                renderResult({
+                    items: filterRes.items,
+                    ...(filterRes.matchedCount !== undefined ? { matchedCount: filterRes.matchedCount } : {}),
+                    hints,
+                }, { json: options.json, context });
                 return;
             }
             renderResult(filterRes.items, {
@@ -81,6 +96,10 @@ export function registerPlaybookCommands(program, context) {
         // 3. 扫描所有已链接的外部包
         const linkedList = listLinkedPackages(context?.customHome);
         if (linkedList.length === 0) {
+            if (isMachine) {
+                renderResult({ packages: [], hints }, { json: options.json, context });
+                return;
+            }
             renderResult([], {
                 json: options.json,
                 humanFormatter: () => NO_PROJECT_NO_LINKED_MESSAGE,
@@ -136,8 +155,12 @@ export function registerPlaybookCommands(program, context) {
                 isFallback = true;
             }
         }
-        if (isFallback && isMachine) {
-            renderResult({ packages: filteredPackages, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+        if (isMachine) {
+            if (isFallback) {
+                renderResult({ packages: filteredPackages, isFallback: true, matchedCount: 0, hints }, { json: options.json, context });
+                return;
+            }
+            renderResult({ packages: filteredPackages, hints }, { json: options.json, context });
             return;
         }
         renderResult(filteredPackages, {
@@ -150,6 +173,7 @@ export function registerPlaybookCommands(program, context) {
                         lines.push(`    - ${pb.id.padEnd(26)} ${pb.description || ""}`);
                     }
                 }
+                lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
                 return lines.join("\n");
             },
             context,
@@ -169,16 +193,22 @@ export function registerPlaybookCommands(program, context) {
         // 1. 远端服务分支
         const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
-            const detail = await fetchRemotePlaybookShow(target.serverUrl, id, target.token, {
-                allowInsecureHttp: Boolean(options.allowInsecureHttp),
-                insecure: target.insecure,
-            });
-            renderResult(detail, {
-                json: options.json,
-                humanFormatter: () => renderPlaybookDetail(detail),
-                context,
-            });
-            return;
+            try {
+                const detail = await fetchRemotePlaybookShow(target.serverUrl, id, target.token, {
+                    allowInsecureHttp: Boolean(options.allowInsecureHttp),
+                    insecure: target.insecure,
+                });
+                renderResult(detail, {
+                    json: options.json,
+                    humanFormatter: () => renderPlaybookDetail(detail),
+                    context,
+                });
+                return;
+            }
+            catch (err) {
+                const hint = "Tip: Run 'ad playbook list' to discover available playbooks.";
+                throw new ArgumentError(`${err.message}\n${hint}`, err?.details, err?.code, hint);
+            }
         }
         // 2. 本地项目模式
         let showTarget = id;
@@ -199,9 +229,13 @@ export function registerPlaybookCommands(program, context) {
             resolved = resolvePlaybook(showTarget, { graph });
         }
         catch (err) {
-            throw new ArgumentError(err.message);
+            const hint = "Tip: Run 'ad playbook list' to discover available playbooks.";
+            throw new ArgumentError(`${err.message}\n${hint}`, err?.details, err?.code, hint);
         }
         const pb = resolved.playbook;
+        const hints = [
+            "Tip: Follow steps sequentially. Invoke constituent actions using 'ad run <action> [options] -- <assignments...>'.",
+        ];
         const detail = {
             id: pb.id,
             packageId: resolved.packageId,
@@ -209,6 +243,7 @@ export function registerPlaybookCommands(program, context) {
             actions: pb.actions,
             filePath: pb.filePath,
             content: pb.content,
+            hints,
         };
         renderResult(detail, {
             json: options.json,
@@ -317,14 +352,14 @@ export function registerPlaybookCommands(program, context) {
                                 resolveAction(actRef, { graph, catalog, caller: target.packageId });
                             }
                             catch (e) {
-                                errors.push(`Referenced cross-package action '${actRef}' not resolvable: ${e.message}`);
+                                errors.push(`Referenced cross-package action '${actRef}' not resolvable: ${e.message}. Hint: Action '${actRef}' not found. Run 'ad action create ${actRef}' to create local action, or 'ad add <pkg>' to install external dependency.`);
                             }
                         }
                         else {
                             const foundInActions = actions.has(actRef);
                             const foundInManifest = Boolean(manifest?.actions?.[actRef]);
                             if (!foundInActions && !foundInManifest) {
-                                errors.push(`Referenced action '${actRef}' not found in project actions`);
+                                errors.push(`Referenced action '${actRef}' not found in project actions. Hint: Action '${actRef}' not found. Run 'ad action create ${actRef}' to create local action, or 'ad add <pkg>' to install external dependency.`);
                             }
                         }
                     }

package/dist/commands/run.js

@@ -1,5 +1,6 @@
 import { validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core/project";
 import { resolveTarget, } from "@actiondock/core/profile";
+import { resolveExecutionHint, } from "@actiondock/core";
 import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
 import { writeStderr, writeStdout } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, resolveTimeoutMs, withService, } from "../utils/index.js";
@@ -87,6 +88,10 @@ export function renderRawExecutionResult(targetRef, result, context) {
                 ? result.error.details
                 : JSON.stringify(result.error.details, null, 2), context);
         }
+        const hint = resolveExecutionHint(targetRef, result.error);
+        if (hint) {
+            writeStderr(hint, context);
+        }
         if (context) {
             context.exitCode = 1;
         }
@@ -189,7 +194,14 @@ export async function executeAction(id, options, context, flatArgs, control) {
                     throw new SigintError();
                 }
                 if (isMachine) {
-                    writeStdout(JSON.stringify(result, null, 2), context);
+                    if (!result.ok) {
+                        const hint = resolveExecutionHint(targetRef, result.error);
+                        const machineOutput = hint !== undefined ? { ...result, hint } : result;
+                        writeStdout(JSON.stringify(machineOutput, null, 2), context);
+                    }
+                    else {
+                        writeStdout(JSON.stringify(result, null, 2), context);
+                    }
                 }
                 else {
                     renderRawExecutionResult(targetRef, result, context);
@@ -260,6 +272,9 @@ export function attachRunCommand(parent, context) {
         .option("-i, --input <json>", "Action input as inline JSON")
         .option("-f, --input-file <path>", "Action input from JSON file, or '-' for stdin")
         .option("-c, --config <key=value...>", "Temporary config override (repeatable)");
+    cmd.unknownOption = function (flag) {
+        this.error(`unknown option '${flag}'\nHint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>.`, { code: "commander.unknownOption" });
+    };
     return applyTargetOptions(cmd)
         .option("--timeout <duration>", "Execution timeout (e.g. 30s, 5m, 500ms)")
         .option("--request-id <id>", "Idempotency request ID for deduplication")

package/dist/errors.d.ts

@@ -6,19 +6,20 @@ export declare class CliError extends Error {
     readonly exitCode: ExitCodeValue;
     readonly code: string;
     readonly details?: unknown;
-    constructor(message: string, exitCode?: ExitCodeValue, code?: string, details?: unknown);
+    readonly hint?: string;
+    constructor(message: string, exitCode?: ExitCodeValue, code?: string, details?: unknown, hint?: string);
 }
 /**
  * 命令行参数与选项校验错误（退出码为 2）。
  */
 export declare class ArgumentError extends CliError {
-    constructor(message: string, details?: unknown, code?: string);
+    constructor(message: string, details?: unknown, code?: string, hint?: string);
 }
 /**
  * 业务逻辑或框架执行失败错误（退出码为 1）。
  */
 export declare class ExecutionError extends CliError {
-    constructor(message: string, details?: unknown, code?: string);
+    constructor(message: string, details?: unknown, code?: string, hint?: string);
 }
 /**
  * 将任意异常统一包裹为 CLI 执行错误（错误码保留辅助）。
@@ -48,6 +49,7 @@ export interface FormattedError {
     message: string;
     exitCode: ExitCodeValue;
     details?: unknown;
+    hint?: string;
 }
 /**
  * 目标包寻址失败错误（-P 指定的包不在链接注册表也无法按路径寻址）。

package/dist/errors.js

@@ -30,20 +30,22 @@ export class CliError extends Error {
     exitCode;
     code;
     details;
-    constructor(message, exitCode = ExitCode.FAILURE, code = "CLI_ERROR", details) {
+    hint;
+    constructor(message, exitCode = ExitCode.FAILURE, code = "CLI_ERROR", details, hint) {
         super(message);
         this.name = "CliError";
         this.exitCode = exitCode;
         this.code = code;
         this.details = details;
+        this.hint = hint;
     }
 }
 /**
  * 命令行参数与选项校验错误（退出码为 2）。
  */
 export class ArgumentError extends CliError {
-    constructor(message, details, code = "INVALID_ARGUMENT") {
-        super(message, ExitCode.INVALID_ARGUMENT, code, details);
+    constructor(message, details, code = "INVALID_ARGUMENT", hint) {
+        super(message, ExitCode.INVALID_ARGUMENT, code, details, hint);
         this.name = "ArgumentError";
     }
 }
@@ -51,8 +53,8 @@ export class ArgumentError extends CliError {
  * 业务逻辑或框架执行失败错误（退出码为 1）。
  */
 export class ExecutionError extends CliError {
-    constructor(message, details, code = "EXECUTION_FAILURE") {
-        super(message, ExitCode.FAILURE, code, details);
+    constructor(message, details, code = "EXECUTION_FAILURE", hint) {
+        super(message, ExitCode.FAILURE, code, details, hint);
         this.name = "ExecutionError";
     }
 }
@@ -96,7 +98,9 @@ export class SigintError extends CliError {
  * 目标包寻址失败错误（-P 指定的包不在链接注册表也无法按路径寻址）。
  */
 export function packageNotFoundError(pkg) {
-    return new ArgumentError(`Package '${pkg}' not found in linked packages or path`);
+    const base = `Package '${pkg}' not found in linked packages or path`;
+    const hint = `Hint: Package '${pkg}' not found. Run 'ad add ${pkg}' to install project dependency, or 'ad link <path>' for local development.`;
+    return new ArgumentError(base, undefined, "INVALID_ARGUMENT", hint);
 }
 /**
  * 当前目录不在 ActionDock 工程内错误。
@@ -104,7 +108,9 @@ export function packageNotFoundError(pkg) {
  */
 export function notInProjectError(hint) {
     const base = "Not in an ActionDock project (actiondock.json not found)";
-    return new ArgumentError(hint ? `${base}.\n${hint}` : base);
+    const effectiveHint = hint ??
+        "Hint: Run 'ad init' to start a new project, specify '-P <id|path>' for an existing package, or run 'ad link <path>' to register it.";
+    return new ArgumentError(base, undefined, "INVALID_ARGUMENT", effectiveHint);
 }
 /**
  * 当前目录无工程且全局注册表无任何链接包提示文案（非错误场景使用）。
@@ -122,6 +128,7 @@ export function formatError(err) {
             message: err.message,
             exitCode: err.exitCode,
             details: err.details,
+            hint: err.hint,
         };
     }
     if (err instanceof InputError) {
@@ -130,6 +137,7 @@ export function formatError(err) {
             message: err.message,
             exitCode: ExitCode.INVALID_ARGUMENT,
             details: err.details,
+            hint: err.hint || err.details?.hint,
         };
     }
     if (err instanceof ActionDockError) {
@@ -145,6 +153,7 @@ export function formatError(err) {
             message: err.message,
             exitCode: isArgument ? ExitCode.INVALID_ARGUMENT : ExitCode.FAILURE,
             details: err.details,
+            hint: err.hint || err.details?.hint,
         };
     }
     // Commander.js 原生错误处理
@@ -156,6 +165,7 @@ export function formatError(err) {
                 message: err.message || String(err),
                 exitCode: ExitCode.INVALID_ARGUMENT,
                 details: err.details,
+                hint: err.hint,
             };
         }
         const commanderErr = err;
@@ -166,10 +176,15 @@ export function formatError(err) {
             code.startsWith("commander.optionMissingArgument") ||
             code.startsWith("commander.invalidArgument") ||
             code.startsWith("commander.excessArguments")) {
+            const hint = commanderErr.hint ||
+                (code.startsWith("commander.unknownOption")
+                    ? "Hint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>."
+                    : undefined);
             return {
                 code: CLI_CODE_INVALID_ARGUMENT,
                 message: commanderErr.message,
                 exitCode: ExitCode.INVALID_ARGUMENT,
+                hint,
             };
         }
         // 正常退出（如 --help 或 --version）
@@ -187,6 +202,7 @@ export function formatError(err) {
             message: err.message,
             exitCode: ExitCode.FAILURE,
             details: err.details,
+            hint: err.hint || err.details?.hint,
         };
     }
     return {

package/dist/renderer.d.ts

@@ -1,6 +1,6 @@
 import type { RunRecord } from "@actiondock/sdk";
 import { type RegistryStatusReport } from "@actiondock/core/registry";
-import type { Envelope, ProjectDetailInfo, AggregatedPackage, EnvCheckItem, CliContext } from "./types.js";
+import type { Envelope, ProjectDetailInfo, ProjectDetailJson, AggregatedPackage, EnvCheckItem, CliContext } from "./types.js";
 /**
  * 构造标准成功结果信封。
  *
@@ -16,7 +16,7 @@ export declare function createSuccessEnvelope<T>(data: T, meta?: Record<string,
  * @param details 附加错误细节
  * @param meta 附加元数据
  */
-export declare function createErrorEnvelope(code: string, message: string, details?: unknown, meta?: Record<string, unknown>): Envelope<never>;
+export declare function createErrorEnvelope(code: string, message: string, details?: unknown, meta?: Record<string, unknown>, hint?: string): Envelope<never>;
 /**
  * 序列化数据为格式化 JSON 字符串。
  *
@@ -48,22 +48,9 @@ export declare function renderError(err: unknown, options: {
     context?: CliContext;
 }): void;
 /**
- * 将工程详情信息转换为机器输出视图（剔除 Map 明细与定义字典）。
+ * 将工程详情信息转换为机器输出视图（结构化配置契约、规程与动作索引）。
  */
-export declare function projectDetailToJson(info: ProjectDetailInfo): {
-    id: string;
-    name: string;
-    version: string;
-    description: string | undefined;
-    projectRoot: string;
-    actionsDir: string;
-    playbooksDir: string;
-    actionsCount: number;
-    playbooksCount: number;
-    actions: string[];
-    playbooks: string[];
-    configDeclared: string[];
-};
+export declare function projectDetailToJson(info: ProjectDetailInfo): ProjectDetailJson;
 /**
  * 格式化渲染单个项目的元数据与详情信息。
  */

package/dist/renderer.js

@@ -24,7 +24,11 @@ export function createSuccessEnvelope(data, meta) {
  * @param details 附加错误细节
  * @param meta 附加元数据
  */
-export function createErrorEnvelope(code, message, details, meta) {
+export function createErrorEnvelope(code, message, details, meta, hint) {
+    const effectiveHint = hint ??
+        (details && typeof details === "object" && typeof details.hint === "string"
+            ? details.hint
+            : undefined);
     const result = {
         ok: false,
         error: {
@@ -33,6 +37,9 @@ export function createErrorEnvelope(code, message, details, meta) {
             ...(details !== undefined ? { details } : {}),
         },
     };
+    if (effectiveHint !== undefined) {
+        result.hint = effectiveHint;
+    }
     if (meta && Object.keys(meta).length > 0) {
         result.meta = meta;
     }
@@ -93,31 +100,79 @@ export function renderError(err, options) {
     const formatted = formatError(err);
     const isMachine = Boolean(options.json);
     if (isMachine) {
-        const errorEnv = createErrorEnvelope(formatted.code, formatted.message, formatted.details);
+        const errorEnv = createErrorEnvelope(formatted.code, formatted.message, formatted.details, undefined, formatted.hint);
         writeStdout(formatJson(errorEnv), options.context);
     }
     else {
         writeStderr(`Error: ${formatted.message}`, options.context);
+        if (formatted.hint) {
+            writeStderr(formatted.hint, options.context);
+        }
     }
 }
 /**
- * 将工程详情信息转换为机器输出视图（剔除 Map 明细与定义字典）。
+ * 将工程详情信息转换为机器输出视图（结构化配置契约、规程与动作索引）。
  */
 export function projectDetailToJson(info) {
-    return {
+    const config = {};
+    if (info.configDeclared && info.configDeclared.length > 0) {
+        for (const key of info.configDeclared) {
+            const item = info.configDef?.[key];
+            config[key] = {
+                ...(item?.description !== undefined ? { description: item.description } : {}),
+                ...(item?.default !== undefined ? { default: item.default } : {}),
+                secret: Boolean(item?.secret),
+            };
+        }
+    }
+    const playbooks = [];
+    if (info.playbooksMap && info.playbooksMap.size > 0) {
+        for (const [id, pb] of info.playbooksMap.entries()) {
+            playbooks.push({
+                id,
+                ...(pb?.description ? { description: pb.description } : {}),
+            });
+        }
+    }
+    else if (info.playbooks && info.playbooks.length > 0) {
+        for (const pbId of info.playbooks) {
+            playbooks.push({ id: pbId });
+        }
+    }
+    const actions = [];
+    if (info.actionsMap && info.actionsMap.size > 0) {
+        for (const [id, act] of info.actionsMap.entries()) {
+            actions.push({
+                id,
+                ...(act?.description ? { description: act.description } : {}),
+            });
+        }
+    }
+    else if (info.actions && info.actions.length > 0) {
+        for (const actId of info.actions) {
+            actions.push({ id: actId });
+        }
+    }
+    const hints = [
+        "Tip: Run 'ad playbook show <id>' to inspect procedure steps before execution.",
+    ];
+    if (info.configDeclared && info.configDeclared.length > 0) {
+        hints.push("Tip: Run 'ad config set <KEY> <val>' to configure required settings.");
+    }
+    const result = {
         id: info.id,
         name: info.name || info.id,
         version: info.version || "0.0.0",
-        description: info.description,
-        projectRoot: info.projectRoot,
-        actionsDir: info.actionsDir,
-        playbooksDir: info.playbooksDir,
-        actionsCount: info.actionsCount,
-        playbooksCount: info.playbooksCount,
-        actions: info.actions,
-        playbooks: info.playbooks,
-        configDeclared: info.configDeclared,
+        root: info.projectRoot,
+        config,
+        playbooks,
+        actions,
+        hints,
     };
+    if (info.description) {
+        result.description = info.description;
+    }
+    return result;
 }
 /**
  * 格式化渲染单个项目的元数据与详情信息。
@@ -130,36 +185,52 @@ export function renderProjectDetail(info) {
         lines.push(`Description: ${info.description}`);
     }
     lines.push(`Root:        ${info.projectRoot}`);
+    if (info.configDeclared.length > 0) {
+        lines.push(`\nDeclared Config Keys (${info.configDeclared.length}):`);
+        for (const k of info.configDeclared) {
+            const item = info.configDef?.[k];
+            const isSec = item?.secret ? " [secret]" : "";
+            const def = item?.default !== undefined ? ` (default: ${JSON.stringify(item.default)})` : "";
+            lines.push(`  - ${k.padEnd(24)} ${item?.description || ""}${def}${isSec}`);
+        }
+    }
+    lines.push(`\nPlaybooks (${info.playbooksCount}):`);
+    if (info.playbooksMap && info.playbooksMap.size > 0) {
+        for (const [id, pb] of info.playbooksMap.entries()) {
+            lines.push(`  - ${id.padEnd(28)} ${pb.description || ""}`);
+        }
+    }
+    else if (info.playbooks && info.playbooks.length > 0) {
+        for (const pbId of info.playbooks) {
+            lines.push(`  - ${pbId}`);
+        }
+    }
+    else {
+        lines.push("  (no playbooks declared)");
+    }
     lines.push(`\nActions (${info.actionsCount}):`);
+    const actionList = [];
     if (info.actionsMap) {
         for (const [id, act] of info.actionsMap.entries()) {
-            lines.push(`  - ${id.padEnd(28)} ${act.description || ""}`);
+            actionList.push({ id, description: act.description || "" });
         }
     }
-    else {
+    else if (info.actions) {
         for (const actId of info.actions) {
-            lines.push(`  - ${actId}`);
+            actionList.push({ id: actId, description: "" });
         }
     }
-    lines.push(`\nPlaybooks (${info.playbooksCount}):`);
-    if (info.playbooksMap) {
-        for (const [id, pb] of info.playbooksMap.entries()) {
-            lines.push(`  - ${id.padEnd(28)} ${pb.description || ""}`);
-        }
+    if (actionList.length === 0) {
+        lines.push("  (no actions declared)");
     }
     else {
-        for (const pbId of info.playbooks) {
-            lines.push(`  - ${pbId}`);
+        for (const a of actionList) {
+            lines.push(`  - ${a.id.padEnd(28)} ${a.description}`);
         }
     }
+    lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
     if (info.configDeclared.length > 0) {
-        lines.push(`\nDeclared Config Keys:`);
-        for (const k of info.configDeclared) {
-            const item = info.configDef?.[k];
-            const isSec = item?.secret ? " [secret]" : "";
-            const def = item?.default !== undefined ? ` (default: ${JSON.stringify(item.default)})` : "";
-            lines.push(`  - ${k.padEnd(24)} ${item?.description || ""}${def}${isSec}`);
-        }
+        lines.push("Tip: Run 'ad config set <KEY> <val>' to configure required settings.");
     }
     return lines.join("\n");
 }
@@ -252,6 +323,7 @@ export function renderActionList(items, title = "Actions", isFallback = false, i
             lines.push(`  - ${a.id.padEnd(28)} ${a.description}`);
         }
     }
+    lines.push("\nTip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.");
     return lines.join("\n");
 }
 /**
@@ -294,6 +366,7 @@ export function renderPlaybookList(items, title = "Playbooks", isFallback = fals
             lines.push(`  - ${p.id.padEnd(26)} ${p.description}${pkgDesc}`);
         }
     }
+    lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
     return lines.join("\n");
 }
 /**
@@ -314,6 +387,7 @@ export function renderPlaybookDetail(pb) {
         lines.push("--- Content ---");
         lines.push(pb.content);
     }
+    lines.push("\nTip: Follow steps sequentially. Invoke constituent actions using 'ad run <action> [options] -- <assignments...>'.");
     return lines.join("\n");
 }
 /**

package/dist/types.d.ts

@@ -27,6 +27,7 @@ export interface Envelope<T = unknown> {
         message: string;
         details?: unknown;
     };
+    hint?: string;
     meta?: Record<string, unknown>;
 }
 /**
@@ -108,6 +109,42 @@ export interface ProjectDetailInfo {
     }>;
     playbooksMap?: Map<string, any>;
 }
+/**
+ * 机器视图工程配置声明条目。
+ */
+export interface ProjectDetailConfigItem {
+    description?: string;
+    default?: unknown;
+    secret: boolean;
+}
+/**
+ * 机器视图规程条目。
+ */
+export interface ProjectDetailPlaybookItem {
+    id: string;
+    description?: string;
+}
+/**
+ * 机器视图动作条目。
+ */
+export interface ProjectDetailActionItem {
+    id: string;
+    description?: string;
+}
+/**
+ * 机器模式工程详情输出结构。
+ */
+export interface ProjectDetailJson {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    root: string;
+    config: Record<string, ProjectDetailConfigItem>;
+    playbooks: ProjectDetailPlaybookItem[];
+    actions: ProjectDetailActionItem[];
+    hints?: string[];
+}
 /**
  * 聚合 Package 信息结构。
  */

package/dist/utils/utils.d.ts

@@ -3,7 +3,7 @@ import { type ActionDockManifest, type ProjectTransaction } from "@actiondock/co
 /**
  * 「未显式指定包且当前目录无工程」的统一补救提示（单一事实源）。
  */
-export declare const PACKAGE_HINT_MESSAGE = "Please specify -P, --package <id> or cd into a project directory.";
+export declare const PACKAGE_HINT_MESSAGE = "Hint: Run 'ad init' to start a new project, specify '-P <id|path>' for an existing package, or run 'ad link <path>' to register it.";
 /**
  * 远端目标拓扑的最小字段视图（与 core 的 ResolvedTarget 远端分支兼容）。
  */

package/dist/utils/utils.js

@@ -6,7 +6,7 @@ import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError,
 /**
  * 「未显式指定包且当前目录无工程」的统一补救提示（单一事实源）。
  */
-export const PACKAGE_HINT_MESSAGE = "Please specify -P, --package <id> or cd into a project directory.";
+export const PACKAGE_HINT_MESSAGE = "Hint: Run 'ad init' to start a new project, specify '-P <id|path>' for an existing package, or run 'ad link <path>' to register it.";
 /**
  * 拼接远端目标标题后缀（单一事实源）。
  *

package/package.json

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