@tomflow/proflow-platform-cli 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.37
+
+### Patch Changes
+
+- Ship the Phase 3 browser, tunnel, model automation, platform readiness, and documentation closure as one verifiable platform snapshot.
+
+## 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

package/README.md

@@ -32,7 +32,7 @@ Platform does not interpret Module-private configuration or recreate a cross-Mod
 
 ## Install / Uninstall
 
-`platform install` validates or creates the minimal Workspace metadata, discovers the complete governed package set from the Registry, synchronizes that set, validates the installed descriptors, then invokes `Module.install` in dependency order. It does not perform human setup work.
+`platform install` validates or creates the minimal Workspace metadata, discovers the complete governed package set from the Registry, synchronizes that set, validates the installed descriptors, then invokes `Module.install` in the frozen Deployment Install Order. This product deployment order is distinct from Runtime dependency topology: Chrome is first, followed by Browser Extension, Agent packages, Gateway/Tunnel, runtime/data foundations and governance packages. It does not perform human setup work.
 
 `platform uninstall` invokes `Module.uninstall` in reverse dependency order before package removal. `.proflow` is Workspace/user data and is preserved unless an owning Module explicitly removes its own artifacts.
 
@@ -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.35";
+            readonly moduleVersion: "0.1.37";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.35";
+            readonly moduleVersion: "0.1.37";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.35";
+            moduleVersion: "0.1.37";
             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.35";
+            readonly moduleVersion: "0.1.37";
         };
         observedEffects: never[];
     }>;
@@ -50,7 +50,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.35";
+            moduleVersion: "0.1.37";
             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.35";
+            readonly moduleVersion: "0.1.37";
         };
         observedEffects: never[];
     }>;
@@ -73,7 +73,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.35";
+            readonly moduleVersion: "0.1.37";
         };
         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.35";
+    readonly moduleVersion: "0.1.37";
     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.35",
+    moduleVersion: "0.1.37",
     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, {
@@ -457,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")
@@ -488,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,
@@ -501,6 +511,7 @@ function errorOutcome(command, error) {
         error: {
             code: "COMMAND_FAILED",
             message: error instanceof Error ? error.message : String(error),
+            category,
         },
     };
 }
@@ -524,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),
@@ -536,6 +548,7 @@ function renderStatus(data, theme) {
     const setupLabels = {
         READY: "已就绪",
         ACTION_REQUIRED: "需要操作",
+        BLOCKED: "等待依赖",
         FAILED: "失败",
     };
     const runtimeLabels = {
@@ -545,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;
@@ -591,10 +604,11 @@ function renderStatus(data, theme) {
     };
     compact("运行中", running, "●");
     compact("已就绪", healthy, "○");
-    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 ready = healthy.length + running.length;
+    const action = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED" && item.runtimeStatus !== "FAILED").length;
+    const failed = failedModules.length;
+    const blocked = modules.filter((item) => item.setupStatus === "BLOCKED" && item.runtimeStatus !== "FAILED").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) {
@@ -639,36 +653,36 @@ function renderDocs(data, theme) {
 }
 const setupCommands = {
     "chatgpt-carrier": {
-        ai: "pnpm exec -- proflow-chatgpt-carrier setup --carrier-url <url>",
-        inputs: "Custom GPT URL",
+        ai: "pnpm exec -- proflow-chatgpt-carrier setup",
+        inputs: "无",
     },
     "dev-tunnel": {
-        ai: "pnpm exec -- proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>",
-        inputs: "Tunnel ID、公开 HTTPS URL",
+        ai: "pnpm exec -- proflow-dev-tunnel setup",
+        inputs: "无",
     },
     "model-provider-api": {
-        ai: "pnpm exec -- proflow-model-provider-api setup --provider-base-url <url>",
-        inputs: "模型服务 Base URL",
+        ai: "pnpm exec -- proflow-model-provider-api setup",
+        inputs: "无（等待 Deployment resolver 提供 endpoint）",
     },
     "model-runtime": {
-        ai: "pnpm exec -- proflow-model-runtime setup --fast-model <id> --reason-model <id>",
-        inputs: "FAST 模型 ID、REASON 模型 ID",
+        ai: "pnpm exec -- proflow-model-runtime setup",
+        inputs: "无（仅等价合格候选歧义时选择）",
     },
     "execution-browser-extension": {
-        ai: "pnpm exec -- proflow-execution-browser-extension setup --extension-id <id>",
-        inputs: "Chrome Extension ID",
+        ai: "pnpm exec -- proflow-execution-browser-extension setup",
+        inputs: "无",
     },
     "agent-controller-dev": {
-        ai: "pnpm exec -- proflow-agent-controller-dev setup --carrier-url <url>",
-        inputs: "Custom GPT URL",
+        ai: "pnpm exec -- proflow-agent-controller-dev setup",
+        inputs: "无",
     },
     "agent-product": {
-        ai: "pnpm exec -- proflow-agent-product setup --carrier-url <url>",
-        inputs: "Custom GPT URL",
+        ai: "pnpm exec -- proflow-agent-product setup",
+        inputs: "无",
     },
     "agent-test-ops": {
-        ai: "pnpm exec -- proflow-agent-test-ops setup --carrier-url <url>",
-        inputs: "Custom GPT URL",
+        ai: "pnpm exec -- proflow-agent-test-ops setup",
+        inputs: "无",
     },
 };
 function renderSetup(data, theme) {
@@ -679,10 +693,12 @@ function renderSetup(data, theme) {
     let ready = skipped.filter((item) => isRecord(item) && item.reason === "READY").length;
     let needsAction = 0;
     let blocked = 0;
+    const renderedModuleRefs = new Set();
     for (const raw of data.results) {
         if (!isRecord(raw) || !isRecord(raw.result))
             continue;
         const moduleRef = String(raw.moduleRef ?? raw.result.moduleRef ?? "unknown");
+        renderedModuleRefs.add(moduleRef);
         const status = String(raw.result.status ?? "UNKNOWN");
         if (status === "SUCCEEDED") {
             ready += 1;
@@ -745,11 +761,100 @@ function renderSetup(data, theme) {
         }
         lines.push("");
     }
+    const dependencyBlockers = Array.isArray(data.blockers)
+        ? data.blockers.filter(isRecord)
+        : [];
+    for (const item of dependencyBlockers) {
+        const moduleRef = String(item.moduleRef ?? "unknown");
+        if (renderedModuleRefs.has(moduleRef))
+            continue;
+        blocked += 1;
+        lines.push(`${theme.info("◇")} ${theme.section(moduleRef)}`, `  原因：${typeof item.reason === "string" ? item.reason : "等待上游 Module 就绪"}`, `  下一步：${theme.command(typeof item.nextCommand === "string" ? item.nextCommand : `platform setup --module ${moduleRef}`)}`, "");
+    }
     if (needsAction === 0 && blocked === 0)
         lines.push("全部模块均已就绪。");
     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.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" &&
@@ -760,18 +865,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 [
@@ -779,42 +901,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")
@@ -851,6 +943,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) {
@@ -865,26 +959,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/deployment-order.d.ts

@@ -0,0 +1,2 @@
+export declare const FROZEN_DEPLOYMENT_INSTALL_ORDER: readonly ["chrome-runtime", "execution-browser-extension", "agent-controller-dev", "agent-product", "agent-test-ops", "agent-gateway", "dev-tunnel", "agent-runtime", "platform-host", "execution-runtime", "execution-local", "model-provider-api", "model-runtime", "task-orchestration", "task-store-sqlite", "task-migration-runner", "execution-contracts", "model-contracts", "module-contract", "module-skill", "module-template", "deployment-conformance", "platform-cli", "chatgpt-carrier"];
+export declare function orderModuleRefsForInstall(moduleRefs: readonly string[]): string[];

package/dist/src/deployment-order.js

@@ -0,0 +1,40 @@
+export const FROZEN_DEPLOYMENT_INSTALL_ORDER = [
+    "chrome-runtime",
+    "execution-browser-extension",
+    "agent-controller-dev",
+    "agent-product",
+    "agent-test-ops",
+    "agent-gateway",
+    "dev-tunnel",
+    "agent-runtime",
+    "platform-host",
+    "execution-runtime",
+    "execution-local",
+    "model-provider-api",
+    "model-runtime",
+    "task-orchestration",
+    "task-store-sqlite",
+    "task-migration-runner",
+    "execution-contracts",
+    "model-contracts",
+    "module-contract",
+    "module-skill",
+    "module-template",
+    "deployment-conformance",
+    "platform-cli",
+    "chatgpt-carrier",
+];
+const installRank = new Map(FROZEN_DEPLOYMENT_INSTALL_ORDER.map((moduleRef, index) => [moduleRef, index]));
+export function orderModuleRefsForInstall(moduleRefs) {
+    return [...moduleRefs].sort((left, right) => {
+        const leftRank = installRank.get(left);
+        const rightRank = installRank.get(right);
+        if (leftRank !== undefined && rightRank !== undefined)
+            return leftRank - rightRank;
+        if (leftRank !== undefined)
+            return -1;
+        if (rightRank !== undefined)
+            return 1;
+        return left.localeCompare(right);
+    });
+}

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

@@ -1,4 +1,5 @@
 import { moduleStatusObservationSchema, } from "@tomflow/proflow-module-contract";
+import { orderModuleRefsForInstall } from "../deployment-order.js";
 import { PlatformError } from "../errors.js";
 import { buildDependencyGraph } from "../graph/graph.js";
 import { reportProgress } from "../progress.js";
@@ -13,6 +14,16 @@ function ordered(modules, reverse = false) {
         .map((ref) => byRef.get(ref))
         .filter((item) => item !== undefined);
 }
+function orderedForInstall(modules) {
+    // Keep dependency validation, but do not let dependency depth/alphabetical order
+    // dictate the user-facing package installation trajectory.
+    buildDependencyGraph(modules);
+    const refs = orderModuleRefsForInstall(modules.map((module) => module.moduleRef));
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    return refs
+        .map((ref) => byRef.get(ref))
+        .filter((item) => item !== undefined);
+}
 export async function observeStatuses(catalog, modules, workspaceRoot, reporter) {
     const results = [];
     const modulesInOrder = [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef));
@@ -69,7 +80,9 @@ export async function observeDocs(catalog, modules, workspaceRoot, reporter) {
 }
 async function runOrdered(catalog, modules, workspaceRoot, command, reverse, reporter) {
     const results = [];
-    const modulesInOrder = ordered(modules, reverse);
+    const modulesInOrder = command === "install"
+        ? orderedForInstall(modules)
+        : ordered(modules, reverse);
     for (const [index, module] of modulesInOrder.entries()) {
         reportProgress(reporter, {
             command,
@@ -78,7 +91,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);
@@ -160,12 +175,37 @@ export async function stopModulesThin(catalog, modules, workspaceRoot, reporter)
 export async function setupModulesThin(catalog, modules, workspaceRoot, target, reporter) {
     const results = [];
     const skipped = [];
-    let matched = target === undefined;
+    const blockers = [];
+    const graph = buildDependencyGraph(modules);
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const dependenciesByRef = new Map();
+    for (const edge of graph.edges) {
+        const dependencies = dependenciesByRef.get(edge.from) ?? [];
+        dependencies.push(edge.to);
+        dependenciesByRef.set(edge.from, dependencies);
+    }
+    if (target !== undefined && !byRef.has(target.moduleRef))
+        throw new PlatformError("INVALID_REQUEST", `setup target module ${target.moduleRef} was not discovered`);
+    const visitedRefs = new Set();
+    const includeWithDependencies = (moduleRef) => {
+        if (visitedRefs.has(moduleRef))
+            return;
+        visitedRefs.add(moduleRef);
+        for (const dependency of dependenciesByRef.get(moduleRef) ?? [])
+            includeWithDependencies(dependency);
+    };
+    if (target !== undefined)
+        includeWithDependencies(target.moduleRef);
+    else
+        for (const moduleRef of graph.order)
+            visitedRefs.add(moduleRef);
+    const modulesInOrder = graph.order
+        .filter((moduleRef) => visitedRefs.has(moduleRef))
+        .map((moduleRef) => byRef.get(moduleRef))
+        .filter((module) => module !== undefined);
+    const setupStatusByRef = new Map();
     let completed = true;
-    const modulesInOrder = ordered(modules);
     for (const [index, module] of modulesInOrder.entries()) {
-        if (target !== undefined && module.moduleRef !== target.moduleRef)
-            continue;
         reportProgress(reporter, {
             command: "setup",
             phase: "setup",
@@ -175,17 +215,20 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
             status: "STARTED",
             message: module.moduleRef,
         });
-        matched = true;
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
         if (!succeeded(status.result)) {
             results.push(status);
+            setupStatusByRef.set(module.moduleRef, "FAILED");
             completed = false;
-            if (target !== undefined)
+            if (target?.moduleRef === module.moduleRef)
                 break;
             continue;
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
-        if (observed.setupStatus === "READY" && target?.input === undefined) {
+        setupStatusByRef.set(module.moduleRef, observed.setupStatus);
+        if (target !== undefined && module.moduleRef !== target.moduleRef)
+            continue;
+        if (observed.setupStatus === "READY" && target === undefined) {
             skipped.push({ moduleRef: module.moduleRef, reason: "READY" });
             reportProgress(reporter, {
                 command: "setup",
@@ -198,6 +241,29 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
             });
             continue;
         }
+        const unavailableDependencies = (dependenciesByRef.get(module.moduleRef) ?? []).filter((moduleRef) => setupStatusByRef.get(moduleRef) !== "READY");
+        if (unavailableDependencies.length > 0) {
+            const first = unavailableDependencies[0];
+            blockers.push({
+                moduleRef: module.moduleRef,
+                setupStatus: "BLOCKED",
+                reason: `等待依赖模块就绪：${unavailableDependencies.join(", ")}`,
+                nextCommand: `platform setup --module ${first}`,
+            });
+            completed = false;
+            reportProgress(reporter, {
+                command: "setup",
+                phase: "setup",
+                current: index + 1,
+                total: modulesInOrder.length,
+                moduleRef: module.moduleRef,
+                status: "SKIPPED",
+                message: `${module.moduleRef} 等待 ${unavailableDependencies.join(", ")}`,
+            });
+            if (target !== undefined)
+                break;
+            continue;
+        }
         const setup = await dispatchModuleCommand(catalog, module, "setup", context(workspaceRoot, target?.input));
         results.push(setup);
         reportProgress(reporter, {
@@ -215,13 +281,25 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
         });
         if (!succeeded(setup.result)) {
             completed = false;
-            if (target !== undefined)
-                break;
         }
+        const reconciled = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
+        if (succeeded(reconciled.result))
+            setupStatusByRef.set(module.moduleRef, moduleStatusObservationSchema.parse(reconciled.result.data).setupStatus);
+        else {
+            results.push(reconciled);
+            setupStatusByRef.set(module.moduleRef, "FAILED");
+            completed = false;
+        }
+        if (target !== undefined && !succeeded(setup.result))
+            break;
     }
-    if (!matched)
-        throw new PlatformError("INVALID_REQUEST", `setup target module ${target?.moduleRef ?? ""} was not discovered`);
-    return { phase: "setup", results, completed, skipped };
+    return {
+        phase: "setup",
+        results,
+        completed,
+        ...(blockers[0] ? { blockedBy: blockers[0], blockers } : {}),
+        skipped,
+    };
 }
 export async function startModulesThin(catalog, modules, workspaceRoot, reporter) {
     const results = [];
@@ -232,22 +310,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 +341,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" | "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,17 +17,19 @@ function progressLine(event, color, spinner = "") {
     const elapsed = event.elapsedMs !== undefined
         ? ` · ${(event.elapsedMs / 1000).toFixed(1)}s`
         : "";
-    const suffix = event.status === "SUCCEEDED"
-        ? "完成"
-        : event.status === "WARNING"
-            ? "警告"
-            : 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"
@@ -85,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.35",
+  "version": "0.1.37",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,11 +24,11 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.11"
+    "@tomflow/proflow-module-contract": "^0.1.13"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.9",
-    "@tomflow/proflow-module-template": "^0.1.9"
+    "@tomflow/proflow-module-template": "^0.1.10",
+    "@tomflow/proflow-deployment-conformance": "^0.1.11"
   },
   "description": "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",
   "keywords": [

package/proflow.module.json

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