@tomflow/proflow-platform-cli 0.1.34 → 0.1.36

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.36
+
+### Patch Changes
+
+- Distinguish dependency blocking from verified failure, expose Module-owned status diagnostics, remove automatic docs paging, consolidate start checks, add contextual help, and clarify uninstall output.
+
+## 0.1.35
+
+### Patch Changes
+
+- Render retryable package-manager warnings as warnings instead of failed subprocess events.
+
 ## 0.1.34
 
 ### Patch Changes

package/README.md

@@ -41,7 +41,7 @@ Platform does not interpret Module-private configuration or recreate a cross-Mod
 `platform status` validates and aggregates only Module-owned observations:
 
 ```text
-setupStatus: READY | ACTION_REQUIRED | FAILED
+setupStatus: READY | ACTION_REQUIRED | BLOCKED | FAILED
 runtimeStatus: RUNNING | STOPPED | FAILED | NOT_APPLICABLE
 ```
 

package/dist/deployment/adapter.d.ts

@@ -6,7 +6,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.34";
+            readonly moduleVersion: "0.1.36";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.34";
+            readonly moduleVersion: "0.1.36";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.34";
+            moduleVersion: "0.1.36";
             data: {
                 readonly setupStatus: "READY";
                 readonly runtimeStatus: "NOT_APPLICABLE";
@@ -40,7 +40,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.34";
+            readonly moduleVersion: "0.1.36";
         };
         observedEffects: never[];
     }>;
@@ -50,7 +50,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.34";
+            moduleVersion: "0.1.36";
             data: {
                 docs: string;
             };
@@ -63,7 +63,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.34";
+            readonly moduleVersion: "0.1.36";
         };
         observedEffects: never[];
     }>;
@@ -73,7 +73,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.34";
+            readonly moduleVersion: "0.1.36";
         };
         observedEffects: never[];
     }>;

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-cli";
     readonly packageName: "@tomflow/proflow-platform-cli";
-    readonly moduleVersion: "0.1.34";
+    readonly moduleVersion: "0.1.36";
     readonly kind: "cli";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-cli",
     packageName: "@tomflow/proflow-platform-cli",
-    moduleVersion: "0.1.34",
+    moduleVersion: "0.1.36",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.d.ts

@@ -2,6 +2,8 @@
 import { type PackageCommandRunner } from "./install/package-manager.ts";
 import { type PlatformProgressReporter } from "./progress.ts";
 import { type NpmCommandRunner } from "./registry/index.ts";
+declare const COMMANDS: readonly ["install", "uninstall", "status", "setup", "docs", "start", "stop"];
+type Command = (typeof COMMANDS)[number];
 export type CliStatus = "SUCCEEDED" | "ACTION_REQUIRED" | "BLOCKED" | "FAILED";
 export interface CliOutcome {
     command: string;
@@ -11,6 +13,8 @@ export interface CliOutcome {
     error?: {
         code: string;
         message: string;
+        category?: "USAGE" | "OPERATION";
+        helpCommand?: Command;
     };
 }
 export interface CliRuntimeOptions {
@@ -26,3 +30,4 @@ export interface HumanRenderOptions {
     width?: number;
 }
 export declare function renderHumanResult(result: CliOutcome, options?: HumanRenderOptions): string;
+export {};

package/dist/src/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { moduleDocsDataSchema, moduleSetupPlanDataSchema, moduleStatusObservationSchema, } from "@tomflow/proflow-module-contract";
@@ -120,7 +119,9 @@ function batchStatus(result) {
     if (result.blockedBy)
         return result.blockedBy.setupStatus === "ACTION_REQUIRED"
             ? "ACTION_REQUIRED"
-            : "FAILED";
+            : result.blockedBy.setupStatus === "BLOCKED"
+                ? "BLOCKED"
+                : "FAILED";
     const statuses = result.results.map((item) => statusFromModule(item.result.status));
     if (statuses.includes("FAILED"))
         return "FAILED";
@@ -154,6 +155,9 @@ async function handleStatus(root, runtime) {
             version: module.moduleVersion,
             setupStatus: parsed.data.setupStatus,
             runtimeStatus: parsed.data.runtimeStatus,
+            ...(parsed.data.issues === undefined
+                ? {}
+                : { issues: parsed.data.issues }),
         };
     });
     reportProgress(runtime.onProgress, {
@@ -351,7 +355,11 @@ function reportPackageManagerOutput(runtime, command, output) {
         command,
         phase: "packages",
         kind: "subprocess",
-        status: /(?:error|ERR_)/i.test(output.line) ? "FAILED" : "STARTED",
+        status: /\b(?:warn|warning)\b/i.test(output.line)
+            ? "WARNING"
+            : /(?:error|ERR_)/i.test(output.line)
+                ? "FAILED"
+                : "STARTED",
         message: output.line,
     });
 }
@@ -453,7 +461,8 @@ export async function runCli(argv, runtime = {}) {
         parsed = parseArgs(argv);
     }
     catch (error) {
-        return errorOutcome("unknown", error);
+        const helpCommand = argv.find((value) => COMMANDS.includes(value));
+        return errorOutcome("unknown", error, "USAGE", helpCommand);
     }
     try {
         if (parsed.command === "help")
@@ -484,12 +493,17 @@ export async function runCli(argv, runtime = {}) {
         return errorOutcome(parsed.command, error);
     }
 }
-function errorOutcome(command, error) {
+function errorOutcome(command, error, category = "OPERATION", helpCommand) {
     if (error instanceof PlatformError)
         return {
             command,
             status: "FAILED",
-            error: { code: error.code, message: error.message },
+            error: {
+                code: error.code,
+                message: error.message,
+                category,
+                ...(helpCommand === undefined ? {} : { helpCommand }),
+            },
         };
     return {
         command,
@@ -497,6 +511,7 @@ function errorOutcome(command, error) {
         error: {
             code: "COMMAND_FAILED",
             message: error instanceof Error ? error.message : String(error),
+            category,
         },
     };
 }
@@ -520,6 +535,7 @@ function humanTheme(options = {}) {
         title: (value) => paint("bold", paint("cyan", value)),
         section: (value) => paint("bold", value),
         command: (value) => paint("blue", value),
+        info: (value) => paint("blue", value),
         muted: (value) => paint("dim", value),
         success: (value) => paint("green", value),
         warning: (value) => paint("yellow", value),
@@ -532,6 +548,7 @@ function renderStatus(data, theme) {
     const setupLabels = {
         READY: "已就绪",
         ACTION_REQUIRED: "需要操作",
+        BLOCKED: "等待依赖",
         FAILED: "失败",
     };
     const runtimeLabels = {
@@ -541,40 +558,40 @@ function renderStatus(data, theme) {
         NOT_APPLICABLE: "无独立进程",
     };
     const modules = data.modules.filter(isRecord);
-    const unhealthy = modules.filter((item) => item.setupStatus !== "READY" || item.runtimeStatus === "FAILED");
+    const failedModules = modules.filter((item) => item.setupStatus === "FAILED" || item.runtimeStatus === "FAILED");
+    const actionModules = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED" && item.runtimeStatus !== "FAILED");
+    const blockedModules = modules.filter((item) => item.setupStatus === "BLOCKED" && item.runtimeStatus !== "FAILED");
     const running = modules.filter((item) => item.setupStatus === "READY" && item.runtimeStatus === "RUNNING");
     const healthy = modules.filter((item) => item.setupStatus === "READY" &&
         item.runtimeStatus !== "RUNNING" &&
         item.runtimeStatus !== "FAILED");
     const lines = [theme.title("ProFlow 状态"), ""];
-    if (unhealthy.length > 0)
-        lines.push(theme.section("需要处理"), "");
-    for (const raw of unhealthy) {
-        const moduleRef = String(raw.moduleRef);
-        const setupStatus = String(raw.setupStatus);
-        const runtimeStatus = String(raw.runtimeStatus);
-        const failed = setupStatus === "FAILED" || runtimeStatus === "FAILED";
-        const actionRequired = setupStatus === "ACTION_REQUIRED";
-        const icon = failed
-            ? "✕"
-            : actionRequired
-                ? "◆"
-                : runtimeStatus === "RUNNING"
-                    ? "●"
-                    : runtimeStatus === "NOT_APPLICABLE"
-                        ? "○"
-                        : "✓";
-        const tone = failed ? theme.failure : theme.warning;
-        lines.push(`${tone(icon)} ${theme.section(moduleRef)}  ${theme.muted(String(raw.version))}`);
-        lines.push(`  ${tone(setupLabels[setupStatus] ?? "未知")} · ${runtimeLabels[runtimeStatus] ?? "未知"}`);
-        if (failed) {
-            lines.push(`  原因：${setupStatus === "FAILED" ? "模块配置检查失败" : "模块运行状态异常"}`, `  下一步：${theme.command(`platform setup --module ${moduleRef}`)}`);
-        }
-        else if (actionRequired) {
-            lines.push("  原因：模块尚未完成配置", `  下一步：${theme.command(`platform setup --module ${moduleRef}`)}`);
+    const renderProblems = (title, entries, tone, icon) => {
+        if (entries.length === 0)
+            return;
+        lines.push(theme.section(title), "");
+        for (const raw of entries) {
+            const moduleRef = String(raw.moduleRef);
+            const setupStatus = String(raw.setupStatus);
+            const runtimeStatus = String(raw.runtimeStatus);
+            lines.push(`${tone(icon)} ${theme.section(moduleRef)}  ${theme.muted(String(raw.version))}`);
+            lines.push(`  ${tone(setupLabels[setupStatus] ?? "未知")} · ${runtimeLabels[runtimeStatus] ?? "未知"}`);
+            const issues = Array.isArray(raw.issues)
+                ? raw.issues.filter(isRecord)
+                : [];
+            for (const issue of issues) {
+                lines.push(`  原因：${String(issue.message)}`);
+                if (Array.isArray(issue.relatedModuleRefs) &&
+                    issue.relatedModuleRefs.length > 0)
+                    lines.push(`  依赖：${issue.relatedModuleRefs.map(String).join("、")}`);
+                lines.push(`  下一步：${theme.command(String(issue.nextCommand))}`);
+            }
+            lines.push("");
         }
-        lines.push("");
-    }
+    };
+    renderProblems("失败", failedModules, theme.failure, "✕");
+    renderProblems("需要操作", actionModules, theme.warning, "◆");
+    renderProblems("等待依赖", blockedModules, theme.info, "◇");
     const compact = (title, entries, symbol) => {
         if (entries.length === 0)
             return;
@@ -590,7 +607,8 @@ function renderStatus(data, theme) {
     const ready = modules.filter((item) => item.setupStatus === "READY").length;
     const action = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED").length;
     const failed = modules.filter((item) => item.setupStatus === "FAILED").length;
-    lines.push(theme.section("汇总"), `${theme.success(`${ready} 已就绪`)} · ${theme.warning(`${action} 需要操作`)} · ${failed > 0 ? theme.failure(`${failed} 失败`) : `${failed} 失败`}`);
+    const blocked = modules.filter((item) => item.setupStatus === "BLOCKED").length;
+    lines.push(theme.section("汇总"), `${theme.success(`${ready} 已就绪`)} · ${theme.warning(`${action} 需要操作`)} · ${theme.info(`${blocked} 等待依赖`)} · ${failed > 0 ? theme.failure(`${failed} 失败`) : `${failed} 失败`}`);
     return lines.join("\n");
 }
 function renderTerminalMarkdown(source, theme) {
@@ -746,6 +764,86 @@ function renderSetup(data, theme) {
     lines.push(theme.section("汇总"), `汇总：${theme.success(`${ready} 个已就绪`)}，${theme.warning(`${needsAction} 个需要操作`)}，${blocked > 0 ? theme.failure(`${blocked} 个系统阻塞`) : `${blocked} 个系统阻塞`}`);
     return lines.join("\n").trimEnd();
 }
+function renderHelp(theme, command) {
+    const commandHelp = {
+        install: {
+            usage: "platform install [--workspace <路径>]",
+            description: "安装并初始化全部 ProFlow 模块",
+        },
+        uninstall: {
+            usage: "platform uninstall [--workspace <路径>]",
+            description: "卸载模块包，保留 Workspace 数据",
+        },
+        status: {
+            usage: "platform status [--workspace <路径>]",
+            description: "查看模块配置与运行状态",
+        },
+        setup: {
+            usage: "platform setup [--workspace <路径>] [--module <模块名>]",
+            description: "自动配置并列出全部剩余步骤",
+        },
+        docs: {
+            usage: "platform docs [--workspace <路径>]",
+            description: "阅读全部模块能力文档",
+        },
+        start: {
+            usage: "platform start [--workspace <路径>]",
+            description: "完成全量检查后启动平台",
+        },
+        stop: {
+            usage: "platform stop [--workspace <路径>]",
+            description: "按逆依赖顺序停止平台",
+        },
+    };
+    if (command) {
+        const item = commandHelp[command];
+        return [
+            theme.title(`platform ${command}`),
+            item.description,
+            "",
+            theme.section("用法"),
+            `  ${theme.command(item.usage)}`,
+            "",
+            theme.section("帮助"),
+            `  ${theme.command(`platform ${command} --help`)}`,
+        ].join("\n");
+    }
+    return [
+        theme.title("ProFlow 平台命令行"),
+        "管理 ProFlow 模块的安装、配置、文档和运行生命周期。",
+        "",
+        theme.section("用法"),
+        `  ${theme.command("platform <command> [--workspace <路径>]")}`,
+        "",
+        theme.section("命令"),
+        ...Object.entries(commandHelp).map(([name, item]) => `  ${theme.command(`platform ${name}`.padEnd(21))}${item.description}`),
+        "",
+        theme.section("公共参数"),
+        "  --workspace <路径>       指定 ProFlow Workspace",
+        "  setup --module <模块名>  只查看指定模块的配置步骤",
+        "  -h, --help               显示帮助",
+        "  -v, --version            显示版本",
+        "",
+        theme.section("推荐流程"),
+        `  ${theme.command("install → status → docs → setup → start → status → stop")}`,
+        "",
+        theme.section("人工配置示例"),
+        `  人工：${theme.command("pnpm exec -- proflow-chatgpt-carrier setup")}`,
+        `  AI：  ${theme.command("pnpm exec -- proflow-chatgpt-carrier setup")}`,
+        `        ${theme.command("--carrier-url <url>")}`,
+        "",
+        theme.section("状态图例"),
+        `  ${theme.success("已就绪")}    配置与验证完成`,
+        `  ${theme.warning("需要操作")}  需要执行 setup 步骤`,
+        `  ${theme.info("等待依赖")}  等待上游 Module 或外部服务`,
+        `  ${theme.failure("失败")}      已确认配置或运行故障`,
+        "  运行中    服务进程正在运行",
+        "  无独立进程 该模块无需启动",
+        "",
+        theme.section("遇到问题"),
+        `  先运行 ${theme.command("platform status")}；配置问题运行 ${theme.command("platform setup")}。`,
+    ].join("\n");
+}
 export function renderHumanResult(result, options = {}) {
     const theme = humanTheme(options);
     if (result.command === "setup" &&
@@ -756,18 +854,35 @@ export function renderHumanResult(result, options = {}) {
         const blockers = Array.isArray(result.data.blockers)
             ? result.data.blockers.filter(isRecord)
             : [];
-        if (blockers.length > 0)
-            return [
-                theme.failure("平台未启动：存在未就绪模块"),
-                "",
-                ...blockers.flatMap((item) => [
-                    `${String(item.setupStatus) === "FAILED" ? theme.failure("✕") : theme.warning("◆")} ${theme.section(String(item.moduleRef))}  ${String(item.setupStatus) === "FAILED" ? theme.failure("失败") : theme.warning("需要操作")}`,
-                    `  原因：${typeof item.reason === "string" ? item.reason : "模块配置尚未完成"}`,
-                    `  下一步：${theme.command(`platform setup --module ${String(item.moduleRef)}`)}`,
-                ]),
-                "",
-                `处理方式：${theme.command(`platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`)}`,
-            ].join("\n");
+        if (blockers.length > 0) {
+            const groups = [
+                { status: "FAILED", title: "失败", icon: "✕", tone: theme.failure },
+                {
+                    status: "ACTION_REQUIRED",
+                    title: "需要操作",
+                    icon: "◆",
+                    tone: theme.warning,
+                },
+                { status: "BLOCKED", title: "等待依赖", icon: "◇", tone: theme.info },
+            ];
+            const lines = [theme.failure("平台未启动：存在未就绪模块"), ""];
+            for (const group of groups) {
+                const entries = blockers.filter((item) => item.setupStatus === group.status);
+                if (entries.length === 0)
+                    continue;
+                lines.push(theme.section(group.title));
+                for (const item of entries)
+                    lines.push(`${group.tone(group.icon)} ${theme.section(String(item.moduleRef))}`, `  原因：${typeof item.reason === "string" ? item.reason : "模块尚未就绪"}`, `  下一步：${theme.command(typeof item.nextCommand === "string" ? item.nextCommand : `platform setup --module ${String(item.moduleRef)}`)}`);
+                lines.push("");
+            }
+            const readyCount = Array.isArray(result.data.results)
+                ? result.data.results.filter((item) => isRecord(item) &&
+                    isRecord(item.result) &&
+                    item.result.status === "SUCCEEDED").length - blockers.length
+                : 0;
+            lines.push(theme.section("检查汇总"), `${Math.max(0, readyCount)} 已就绪 · ${blockers.length} 未就绪 · 0 个模块已启动`, `处理方式：${theme.command(`platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`)}`);
+            return lines.join("\n");
+        }
     }
     if (result.status === "FAILED" && result.error)
         return [
@@ -775,42 +890,12 @@ export function renderHumanResult(result, options = {}) {
             `${theme.failure("│")} ${theme.section(result.error.code)}`,
             `${theme.failure("│")} ${result.error.message}`,
             theme.failure("╰─ 请根据提示修复后重试"),
+            ...(result.error.category === "USAGE"
+                ? ["", renderHelp(theme, result.error.helpCommand)]
+                : []),
         ].join("\n");
     if (result.command === "help")
-        return [
-            theme.title("ProFlow 平台命令行"),
-            "管理 ProFlow 模块的安装、配置、文档和运行生命周期。",
-            "",
-            theme.section("用法"),
-            `  ${theme.command("platform <command> [--workspace <路径>]")}`,
-            "",
-            theme.section("命令"),
-            `${theme.command("platform install")}     安装并初始化全部 ProFlow 模块`,
-            "platform uninstall   卸载模块包，保留 Workspace 数据",
-            "platform status      查看模块配置与运行状态",
-            "platform setup       自动配置并列出全部剩余步骤",
-            "platform docs        阅读模块能力文档",
-            "platform start       完成全量检查后启动平台",
-            "platform stop        按逆依赖顺序停止平台",
-            "",
-            theme.section("公共参数"),
-            "  --workspace <路径>       指定 ProFlow Workspace",
-            "  setup --module <模块名>  只查看指定模块的配置步骤",
-            "",
-            theme.section("推荐流程"),
-            `  ${theme.command("install → status → docs → setup → start → status → stop")}`,
-            "",
-            theme.section("人工配置示例"),
-            `  人工：${theme.command("pnpm exec -- proflow-chatgpt-carrier setup")}`,
-            `  AI：  ${theme.command("pnpm exec -- proflow-chatgpt-carrier setup --carrier-url <url>")}`,
-            "",
-            theme.section("状态图例"),
-            `  ${theme.success("已就绪")}  配置完成    ${theme.warning("需要操作")}  运行 setup`,
-            `  ${theme.failure("失败")}    存在阻塞    无独立进程  无需启动`,
-            "",
-            theme.section("遇到问题"),
-            `  先运行 ${theme.command("platform status")}；配置问题运行 ${theme.command("platform setup")}。`,
-        ].join("\n");
+        return renderHelp(theme);
     if (result.command === "version" && isRecord(result.data))
         return String(result.data.version ?? platformCliDescriptor.moduleVersion);
     if (result.command === "status")
@@ -847,6 +932,8 @@ export function renderHumanResult(result, options = {}) {
         start: "启动",
         stop: "停止",
     };
+    if (result.command === "uninstall" && result.status === "SUCCEEDED")
+        return `${theme.success("✓ 已经卸载")}${result.workspaceRoot ? `\n${theme.muted("Workspace")}  ${result.workspaceRoot}` : ""}`;
     return `${result.status === "SUCCEEDED" ? theme.success("✓") : theme.failure("✕")} ${labels[result.command] ?? result.command}${result.status === "SUCCEEDED" ? "成功" : "未完成"}${result.workspaceRoot ? `\n${theme.muted("Workspace")}  ${result.workspaceRoot}` : ""}`;
 }
 if (import.meta.main) {
@@ -861,26 +948,7 @@ if (import.meta.main) {
         color,
         width: process.stdout.columns,
     })}\n`;
-    if (result.command === "docs" &&
-        process.stdout.isTTY === true &&
-        rendered.split("\n").length > (process.stdout.rows ?? 24)) {
-        await writeThroughPager(rendered);
-    }
-    else
-        process.stdout.write(rendered);
+    process.stdout.write(rendered);
     if (result.status !== "SUCCEEDED")
         process.exitCode = 1;
 }
-async function writeThroughPager(content) {
-    await new Promise((resolvePromise) => {
-        const pager = spawn("less", ["-FIRX"], {
-            stdio: ["pipe", "inherit", "inherit"],
-        });
-        pager.once("error", () => {
-            process.stdout.write(content);
-            resolvePromise();
-        });
-        pager.once("close", () => resolvePromise());
-        pager.stdin.end(content);
-    });
-}

package/dist/src/lifecycle/thin.d.ts

@@ -15,6 +15,7 @@ export interface ModuleBatchResult {
         moduleRef: string;
         setupStatus: ModuleSetupStatus;
         reason?: string;
+        nextCommand?: string;
     }>;
     skipped?: Array<{
         moduleRef: string;

package/dist/src/lifecycle/thin.js

@@ -78,7 +78,9 @@ async function runOrdered(catalog, modules, workspaceRoot, command, reverse, rep
             total: modulesInOrder.length,
             moduleRef: module.moduleRef,
             status: "STARTED",
-            message: `${module.moduleRef}`,
+            message: command === "uninstall"
+                ? `正在卸载 ${module.moduleRef}`
+                : `${module.moduleRef}`,
         });
         const result = await dispatchModuleCommand(catalog, module, command, context(workspaceRoot));
         results.push(result);
@@ -232,22 +234,26 @@ export async function startModulesThin(catalog, modules, workspaceRoot, reporter
         reportProgress(reporter, {
             command: "start",
             phase: "status",
+            kind: "detail",
+            retention: "REPLACE",
             current: index + 1,
             total: modulesInOrder.length,
             moduleRef: module.moduleRef,
             status: "STARTED",
-            message: `${module.moduleRef}`,
+            message: `正在检查模块状态 · ${module.moduleRef}`,
         });
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
         results.push(status);
         reportProgress(reporter, {
             command: "start",
             phase: "status",
+            kind: "detail",
+            retention: "REPLACE",
             current: index + 1,
             total: modulesInOrder.length,
             moduleRef: module.moduleRef,
             status: succeeded(status.result) ? "SUCCEEDED" : "FAILED",
-            message: `${module.moduleRef}`,
+            message: `正在检查模块状态 · ${module.moduleRef}`,
         });
         if (!succeeded(status.result)) {
             blockers.push({
@@ -259,11 +265,19 @@ export async function startModulesThin(catalog, modules, workspaceRoot, reporter
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
         runtimeByRef.set(module.moduleRef, observed.runtimeStatus);
-        if (observed.setupStatus !== "READY")
+        if (observed.setupStatus !== "READY") {
+            const issue = observed.issues?.find((item) => item.scope === "SETUP");
             blockers.push({
                 moduleRef: module.moduleRef,
                 setupStatus: observed.setupStatus,
+                ...(issue
+                    ? {
+                        reason: issue.message,
+                        nextCommand: issue.nextCommand,
+                    }
+                    : {}),
             });
+        }
     }
     if (results.some((item) => !succeeded(item.result)) || blockers.length > 0)
         return {

package/dist/src/progress.d.ts

@@ -1,9 +1,11 @@
-export type PlatformProgressStatus = "STARTED" | "SUCCEEDED" | "ACTION_REQUIRED" | "FAILED" | "SKIPPED";
+export type PlatformProgressStatus = "STARTED" | "SUCCEEDED" | "WARNING" | "ACTION_REQUIRED" | "FAILED" | "SKIPPED";
 export type PlatformProgressKind = "phase" | "detail" | "subprocess";
+export type PlatformProgressRetention = "KEEP" | "REPLACE";
 export interface PlatformProgressEvent {
     command: string;
     phase: string;
     kind?: PlatformProgressKind;
+    retention?: PlatformProgressRetention;
     current?: number;
     total?: number;
     moduleRef?: string;

package/dist/src/terminal.js

@@ -17,35 +17,43 @@ function progressLine(event, color, spinner = "") {
     const elapsed = event.elapsedMs !== undefined
         ? ` · ${(event.elapsedMs / 1000).toFixed(1)}s`
         : "";
-    const suffix = event.status === "SUCCEEDED"
-        ? "完成"
-        : event.status === "ACTION_REQUIRED"
-            ? "待处理"
-            : event.status === "FAILED"
-                ? "失败"
-                : event.status === "SKIPPED"
-                    ? "跳过"
-                    : "";
+    const suffix = event.command === "uninstall" && event.status === "SUCCEEDED"
+        ? "已经卸载"
+        : event.status === "SUCCEEDED"
+            ? "完成"
+            : event.status === "WARNING"
+                ? "警告"
+                : event.status === "ACTION_REQUIRED"
+                    ? "待处理"
+                    : event.status === "FAILED"
+                        ? "失败"
+                        : event.status === "SKIPPED"
+                            ? "跳过"
+                            : "";
     const symbol = event.kind === "subprocess"
         ? "│"
         : event.status === "STARTED"
             ? spinner
             : event.status === "SUCCEEDED"
                 ? "✓"
-                : event.status === "FAILED"
-                    ? "✕"
-                    : event.status === "ACTION_REQUIRED"
-                        ? "◆"
-                        : "○";
+                : event.status === "WARNING"
+                    ? "!"
+                    : event.status === "FAILED"
+                        ? "✕"
+                        : event.status === "ACTION_REQUIRED"
+                            ? "◆"
+                            : "○";
     if (!color)
         return `${symbol ? `${symbol} ` : ""}${prefix}${event.message}${suffix ? ` · ${suffix}` : ""}${elapsed}`;
     const tone = event.status === "SUCCEEDED"
         ? colors.green
-        : event.status === "FAILED"
-            ? colors.red
-            : event.kind === "subprocess"
-                ? colors.blue
-                : colors.yellow;
+        : event.status === "WARNING"
+            ? colors.yellow
+            : event.status === "FAILED"
+                ? colors.red
+                : event.kind === "subprocess"
+                    ? colors.blue
+                    : colors.yellow;
     return `${tone}${symbol}${colors.reset} ${colors.dim}${prefix}${colors.reset}${event.message}${suffix ? ` · ${tone}${suffix}${colors.reset}` : ""}${event.elapsedMs === undefined ? "" : `${colors.dim}${elapsed}${colors.reset}`}`;
 }
 export function createTerminalProgressReporter(stream = process.stderr) {
@@ -79,6 +87,12 @@ export function createTerminalProgressReporter(stream = process.stderr) {
             stream.write(`${line}\n`);
             return;
         }
+        if (event.retention === "REPLACE" && event.status !== "STARTED") {
+            cursorTo(stream, 0);
+            clearLine(stream, 0);
+            active = undefined;
+            return;
+        }
         cursorTo(stream, 0);
         clearLine(stream, 0);
         stream.write(line);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,10 +24,10 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.11"
+    "@tomflow/proflow-module-contract": "^0.1.12"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.9",
+    "@tomflow/proflow-deployment-conformance": "^0.1.10",
     "@tomflow/proflow-module-template": "^0.1.9"
   },
   "description": "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-cli",
 	"packageName": "@tomflow/proflow-platform-cli",
-	"moduleVersion": "0.1.34",
+	"moduleVersion": "0.1.36",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",