@tomflow/proflow-platform-cli 0.1.33 → 0.1.35

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.35
+
+### Patch Changes
+
+- Render retryable package-manager warnings as warnings instead of failed subprocess events.
+
+## 0.1.34
+
+### Patch Changes
+
+- Upgrade the ProFlow terminal experience, stream Registry and package-manager progress, publish structured Chinese Module documentation, and provide numbered package-owned Setup assistants.
+
 ## 0.1.33
 
 ### Patch Changes

package/DOCS.md

@@ -1,11 +1,39 @@
-# platform-cli
+# platform-cli — ProFlow 管理命令行
 
-Platform CLI（平台命令行）是 ProFlow 的统一管理入口，负责发现模块、安装依赖、汇总状态和按依赖顺序启动或停止模块。
+## 模块定位与作用
 
-## 推荐流程
+ProFlow 的薄管理面，负责从 Registry 发现 Module、同步 npm 包、解析依赖顺序，并转发和聚合七标准命令。
 
-`platform install` → `platform status` → `platform docs` → `platform setup` → `platform start`
+## 主要能力
 
-## 边界
+- 安装、卸载并验证完整 Module 包集合。
+- 聚合 status、docs 和 setup，不解释 Module 私有业务。
+- 按依赖顺序启动、按逆依赖顺序停止，并支持幂等重试。
 
-Platform CLI 只负责调用和汇总，不读取模块私有配置，也不替模块解释外部服务。具体配置由对应模块的 Setup（配置向导）完成。
+## 提供的 API 与 Public Contract
+
+- 不提供领域业务 Contract。
+- 提供 `platform` CLI；`runCli()` 返回强类型 `CliOutcome`，终端层负责中文渲染。
+
+## 依赖的 Module、Contract 和外部资源
+
+- 依赖 npm Registry、当前 Workspace package manager 和所有 discovered Module 的公开 adapter。
+- 不 deep import Module 私有代码，不读取 Module 私有配置。
+
+## 运行形态与生命周期
+
+类型为 CLI，命令执行结束后退出；不是业务 Runtime 或长期守护进程。
+
+## 使用方式
+
+推荐顺序为 `platform install`、`status`、`docs`、`setup`、`start`、`stop`、`uninstall`。
+
+## 职责边界与限制
+
+不代理业务 API、不保存 Module setup 输入、不建立 preflight/doctor 第二真源，也不提供 JSON 输出选项。
+
+## 术语
+
+- Discovery（发现）：从 Registry 与 Workspace 识别 governed Module。
+- Aggregation（聚合）：保留各 Module 结果并以统一终端形式展示。
+- Dependency Order（依赖顺序）：Provider 先于 Consumer 的生命周期顺序。

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.33";
+            readonly moduleVersion: "0.1.35";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.33";
+            readonly moduleVersion: "0.1.35";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.33";
+            moduleVersion: "0.1.35";
             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.33";
+            readonly moduleVersion: "0.1.35";
         };
         observedEffects: never[];
     }>;
@@ -50,7 +50,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.33";
+            moduleVersion: "0.1.35";
             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.33";
+            readonly moduleVersion: "0.1.35";
         };
         observedEffects: never[];
     }>;
@@ -73,7 +73,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.33";
+            readonly moduleVersion: "0.1.35";
         };
         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.33";
+    readonly moduleVersion: "0.1.35";
     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.33",
+    moduleVersion: "0.1.35",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.d.ts

@@ -21,4 +21,8 @@ export interface CliRuntimeOptions {
     onProgress?: PlatformProgressReporter;
 }
 export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<CliOutcome>;
-export declare function renderHumanResult(result: CliOutcome): string;
+export interface HumanRenderOptions {
+    color?: boolean;
+    width?: number;
+}
+export declare function renderHumanResult(result: CliOutcome, options?: HumanRenderOptions): string;

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 #!/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";
@@ -230,21 +231,50 @@ async function validateInstalledPackageSet(root, candidates, previousManaged) {
     }
 }
 async function handleInstall(root, runtime) {
+    const startedAt = Date.now();
     reportProgress(runtime.onProgress, {
         command: "install",
         phase: "workspace",
+        kind: "phase",
         status: "STARTED",
         message: "正在校验 Workspace",
     });
     const metadata = await ensureWorkspaceMetadata(root);
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "workspace",
+        kind: "phase",
+        status: "SUCCEEDED",
+        message: "Workspace 校验完成",
+        elapsedMs: Date.now() - startedAt,
+    });
     reportProgress(runtime.onProgress, {
         command: "install",
         phase: "registry",
+        kind: "phase",
         status: "STARTED",
-        message: "正在发现 Registry 模块",
+        message: "正在连接 Registry",
     });
     const discovered = await discoverRegistryModules({
         workspaceRoot: root,
+        onSearchComplete: (total) => reportProgress(runtime.onProgress, {
+            command: "install",
+            phase: "registry",
+            kind: "detail",
+            status: "STARTED",
+            total,
+            message: `Registry 返回 ${total} 个候选模块，正在核验`,
+        }),
+        onPackageChecked: ({ current, total, packageName }) => reportProgress(runtime.onProgress, {
+            command: "install",
+            phase: "registry",
+            kind: "detail",
+            status: "SUCCEEDED",
+            current,
+            total,
+            moduleRef: packageName.replace(PRO_FLOW_PACKAGE_PREFIX, ""),
+            message: `核验 ${packageName.replace(PRO_FLOW_PACKAGE_PREFIX, "")}`,
+        }),
         ...(runtime.registryRunner === undefined
             ? {}
             : { runner: runtime.registryRunner }),
@@ -252,6 +282,7 @@ async function handleInstall(root, runtime) {
     reportProgress(runtime.onProgress, {
         command: "install",
         phase: "registry",
+        kind: "phase",
         status: "SUCCEEDED",
         message: `已发现 ${discovered.candidates.length} 个注册模块`,
     });
@@ -264,6 +295,7 @@ async function handleInstall(root, runtime) {
     reportProgress(runtime.onProgress, {
         command: "install",
         phase: "packages",
+        kind: "phase",
         status: "STARTED",
         message: "正在同步依赖",
     });
@@ -273,6 +305,7 @@ async function handleInstall(root, runtime) {
             packageName: item.packageName,
             version: item.moduleVersion,
         })),
+        onOutput: (line) => reportPackageManagerOutput(runtime, "install", line),
         ...(runtime.packageRunner === undefined
             ? {}
             : { runner: runtime.packageRunner }),
@@ -283,12 +316,20 @@ async function handleInstall(root, runtime) {
     reportProgress(runtime.onProgress, {
         command: "install",
         phase: "packages",
+        kind: "phase",
         status: "SUCCEEDED",
         message: "依赖同步完成",
     });
     await recordPnpmPolicyOwnership(root, pnpmPolicyBefore);
     await validateInstalledPackageSet(root, discovered.candidates, previousManaged);
     const { catalog, modules } = await buildContext(root);
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "validation",
+        kind: "phase",
+        status: "SUCCEEDED",
+        message: `已验证 ${modules.length} 个已安装模块`,
+    });
     const moduleInstall = await installModulesThin(catalog, modules, root, runtime.onProgress);
     return outcome("install", batchStatus(moduleInstall), root, {
         registry: discovered.registry,
@@ -302,6 +343,22 @@ async function handleInstall(root, runtime) {
         next: "platform status",
     });
 }
+const usefulPackageOutput = /(?:resolved|downloaded|reused|linked|added|removed|packages:|progress:|warn|warning|error|ERR_|done|completed|audited|changed)/i;
+function reportPackageManagerOutput(runtime, command, output) {
+    if (!usefulPackageOutput.test(output.line))
+        return;
+    reportProgress(runtime.onProgress, {
+        command,
+        phase: "packages",
+        kind: "subprocess",
+        status: /\b(?:warn|warning)\b/i.test(output.line)
+            ? "WARNING"
+            : /(?:error|ERR_)/i.test(output.line)
+                ? "FAILED"
+                : "STARTED",
+        message: output.line,
+    });
+}
 async function workspaceProFlowDependencies(root) {
     try {
         const parsed = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
@@ -339,6 +396,7 @@ async function handleUninstall(root, runtime) {
     const mutation = await removeWorkspacePackages({
         workspaceRoot: root,
         packageNames,
+        onOutput: (line) => reportPackageManagerOutput(runtime, "uninstall", line),
         ...(runtime.packageRunner === undefined
             ? {}
             : { runner: runtime.packageRunner }),
@@ -447,7 +505,32 @@ function errorOutcome(command, error) {
     };
 }
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-function renderStatus(data) {
+const ansi = {
+    reset: "\u001b[0m",
+    bold: "\u001b[1m",
+    dim: "\u001b[2m",
+    cyan: "\u001b[36m",
+    blue: "\u001b[34m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+    red: "\u001b[31m",
+};
+function humanTheme(options = {}) {
+    const enabled = options.color === true;
+    const paint = (tone, value) => enabled ? `${ansi[tone]}${value}${ansi.reset}` : value;
+    return {
+        width: Math.max(60, options.width ?? 100),
+        paint,
+        title: (value) => paint("bold", paint("cyan", value)),
+        section: (value) => paint("bold", value),
+        command: (value) => paint("blue", value),
+        muted: (value) => paint("dim", value),
+        success: (value) => paint("green", value),
+        warning: (value) => paint("yellow", value),
+        failure: (value) => paint("red", value),
+    };
+}
+function renderStatus(data, theme) {
     if (!isRecord(data) || !Array.isArray(data.modules))
         return "未发现模块。";
     const setupLabels = {
@@ -462,8 +545,15 @@ function renderStatus(data) {
         NOT_APPLICABLE: "无独立进程",
     };
     const modules = data.modules.filter(isRecord);
-    const lines = ["ProFlow 状态", ""];
-    for (const raw of modules) {
+    const unhealthy = modules.filter((item) => item.setupStatus !== "READY" || 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);
@@ -478,43 +568,69 @@ function renderStatus(data) {
                     : runtimeStatus === "NOT_APPLICABLE"
                         ? "○"
                         : "✓";
-        lines.push(`${icon} ${moduleRef.padEnd(30)} ${String(raw.version).padEnd(9)} ${setupLabels[setupStatus] ?? "未知"} · ${runtimeLabels[runtimeStatus] ?? "未知"}`);
+        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" ? "模块配置检查失败" : "模块运行状态异常"}`, `  下一步：platform setup --module ${moduleRef}`);
+            lines.push(`  原因：${setupStatus === "FAILED" ? "模块配置检查失败" : "模块运行状态异常"}`, `  下一步：${theme.command(`platform setup --module ${moduleRef}`)}`);
         }
         else if (actionRequired) {
-            lines.push("  原因：模块尚未完成配置", `  下一步：platform setup --module ${moduleRef}`);
+            lines.push("  原因：模块尚未完成配置", `  下一步：${theme.command(`platform setup --module ${moduleRef}`)}`);
         }
+        lines.push("");
     }
+    const compact = (title, entries, symbol) => {
+        if (entries.length === 0)
+            return;
+        lines.push(theme.section(title), "");
+        for (const item of entries) {
+            const runtime = runtimeLabels[String(item.runtimeStatus)] ?? "未知";
+            lines.push(`${theme.success(symbol)} ${String(item.moduleRef).padEnd(32)} ${theme.muted(String(item.version).padEnd(9))} ${runtime}`);
+        }
+        lines.push("");
+    };
+    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("", `汇总：${ready} 已就绪 · ${action} 需要操作 · ${failed} 失败`);
+    lines.push(theme.section("汇总"), `${theme.success(`${ready} 已就绪`)} · ${theme.warning(`${action} 需要操作`)} · ${failed > 0 ? theme.failure(`${failed} 失败`) : `${failed} 失败`}`);
     return lines.join("\n");
 }
-function renderTerminalMarkdown(source) {
+function renderTerminalMarkdown(source, theme) {
+    let inCode = false;
     return source
         .split(/\r?\n/)
         .map((line) => {
-        const heading = line.match(/^#{1,6}\s+(.+)$/);
-        if (heading?.[1])
-            return heading[1].replaceAll("`", "");
-        const bullet = line.match(/^\s*-\s+(.+)$/);
+        if (line.trim().startsWith("```")) {
+            inCode = !inCode;
+            return "";
+        }
+        if (inCode)
+            return `  ${theme.command(line)}`;
+        const heading = line.match(/^(#{1,6})\s+(.+)$/);
+        if (heading?.[2])
+            return heading[1]?.length === 1
+                ? theme.title(heading[2].replaceAll("`", ""))
+                : theme.section(heading[2].replaceAll("`", ""));
+        const bullet = line.match(/^\s*[-*]\s+(.+)$/);
         if (bullet?.[1])
-            return `  • ${bullet[1].replaceAll("`", "")}`;
-        return line.replaceAll("`", "");
+            return `  ${theme.paint("cyan", "•")} ${bullet[1]}`;
+        if (/^\|.*\|$/.test(line))
+            return theme.muted(line);
+        return line.replace(/`([^`]+)`/g, (_match, code) => theme.command(code));
     })
         .join("\n")
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
-function renderDocs(data) {
+function renderDocs(data, theme) {
     if (!isRecord(data) || !Array.isArray(data.modules))
         return "未发现模块文档。";
-    const lines = ["ProFlow 模块文档"];
+    const lines = [theme.title("ProFlow 模块文档")];
     for (const raw of data.modules)
         if (isRecord(raw))
-            lines.push("", "─".repeat(72), `${String(raw.moduleRef)}  ${String(raw.version)}`, "", renderTerminalMarkdown(String(raw.docs ?? "")));
+            lines.push("", theme.muted("─".repeat(Math.min(theme.width, 96))), `${theme.section(String(raw.moduleRef))}  ${theme.muted(String(raw.version))}`, "", renderTerminalMarkdown(String(raw.docs ?? ""), theme));
     if (Array.isArray(data.errors) && data.errors.length > 0)
         lines.push("", "文档读取失败：", ...data.errors
             .filter(isRecord)
@@ -555,10 +671,10 @@ const setupCommands = {
         inputs: "Custom GPT URL",
     },
 };
-function renderSetup(data) {
+function renderSetup(data, theme) {
     if (!isRecord(data) || !Array.isArray(data.results))
         return "没有需要执行的配置步骤。";
-    const lines = ["ProFlow 配置", ""];
+    const lines = [theme.title("ProFlow 配置"), ""];
     const skipped = Array.isArray(data.skipped) ? data.skipped : [];
     let ready = skipped.filter((item) => isRecord(item) && item.reason === "READY").length;
     let needsAction = 0;
@@ -576,19 +692,31 @@ function renderSetup(data) {
             blocked += 1;
         else
             needsAction += 1;
-        lines.push(`${status === "FAILED" ? "✕" : "◆"} ${moduleRef}`);
+        lines.push(`${status === "FAILED" ? theme.failure("✕") : theme.warning("◆")} ${theme.section(moduleRef)}`);
         const plan = moduleSetupPlanDataSchema.safeParse(raw.result.data);
         if (plan.success) {
             for (const [index, step] of plan.data.steps.entries()) {
-                lines.push(`  ${index + 1}. ${step.title}`);
-                lines.push(`     运行：${step.execution.interactive}`);
-                lines.push(`     自动执行：${step.execution.nonInteractive}`);
+                const marker = step.state === "DONE"
+                    ? theme.success("✓")
+                    : step.state === "BLOCKED"
+                        ? theme.failure("✕")
+                        : index ===
+                            plan.data.steps.findIndex((item) => item.state === "TODO")
+                            ? theme.warning("→")
+                            : theme.muted("○");
+                lines.push(`  ${marker} ${String(index + 1).padStart(2, "0")}  ${step.title}`);
+                if (step.description)
+                    lines.push(`       ${step.description}`);
+                lines.push(`       运行：${theme.command(step.execution.interactive)}`);
+                lines.push(`       AI：${theme.command(step.execution.nonInteractive)}`);
                 if (step.requiredInputs.length > 0)
-                    lines.push(`     需要：${step.requiredInputs.map((item) => item.description).join("、")}`);
-                lines.push(`     验证：${step.verify}`);
-                lines.push(`     完成：${step.successCondition}`);
+                    lines.push(`       需要：${step.requiredInputs.map((item) => item.description).join("、")}`);
+                if (step.humanAction)
+                    lines.push(`       人工操作：${step.humanAction}`);
+                lines.push(`       验证：${theme.command(step.verify)}`);
+                lines.push(`       完成：${step.successCondition}`);
                 if (step.blockedReason)
-                    lines.push(`     原因：${step.blockedReason}`);
+                    lines.push(`       原因：${theme.failure(step.blockedReason)}`);
             }
             lines.push("");
             continue;
@@ -619,34 +747,49 @@ function renderSetup(data) {
     }
     if (needsAction === 0 && blocked === 0)
         lines.push("全部模块均已就绪。");
-    lines.push(`汇总：${ready} 个已就绪，${needsAction} 个需要操作，${blocked} 个系统阻塞`);
+    lines.push(theme.section("汇总"), `汇总：${theme.success(`${ready} 个已就绪`)}，${theme.warning(`${needsAction} 个需要操作`)}，${blocked > 0 ? theme.failure(`${blocked} 个系统阻塞`) : `${blocked} 个系统阻塞`}`);
     return lines.join("\n").trimEnd();
 }
-export function renderHumanResult(result) {
+export function renderHumanResult(result, options = {}) {
+    const theme = humanTheme(options);
     if (result.command === "setup" &&
         isRecord(result.data) &&
         Array.isArray(result.data.results))
-        return renderSetup(result.data);
+        return renderSetup(result.data, theme);
     if (result.command === "start" && isRecord(result.data)) {
         const blockers = Array.isArray(result.data.blockers)
             ? result.data.blockers.filter(isRecord)
             : [];
         if (blockers.length > 0)
             return [
-                "平台未启动：存在未就绪模块",
+                theme.failure("平台未启动：存在未就绪模块"),
                 "",
-                ...blockers.map((item) => `${String(item.moduleRef).padEnd(28)} ${String(item.setupStatus) === "FAILED" ? "失败" : "需要操作"}  配置尚未完成`),
+                ...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)}`)}`,
+                ]),
                 "",
-                `处理方式：platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`,
+                `处理方式：${theme.command(`platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`)}`,
             ].join("\n");
     }
     if (result.status === "FAILED" && result.error)
-        return `${result.command} 失败：${result.error.message}`;
+        return [
+            theme.failure(`╭─ ${result.command} 执行失败`),
+            `${theme.failure("│")} ${theme.section(result.error.code)}`,
+            `${theme.failure("│")} ${result.error.message}`,
+            theme.failure("╰─ 请根据提示修复后重试"),
+        ].join("\n");
     if (result.command === "help")
         return [
-            "ProFlow 平台命令行",
+            theme.title("ProFlow 平台命令行"),
+            "管理 ProFlow 模块的安装、配置、文档和运行生命周期。",
             "",
-            "platform install     安装并初始化全部 ProFlow 模块",
+            theme.section("用法"),
+            `  ${theme.command("platform <command> [--workspace <路径>]")}`,
+            "",
+            theme.section("命令"),
+            `${theme.command("platform install")}     安装并初始化全部 ProFlow 模块`,
             "platform uninstall   卸载模块包，保留 Workspace 数据",
             "platform status      查看模块配置与运行状态",
             "platform setup       自动配置并列出全部剩余步骤",
@@ -654,20 +797,32 @@ export function renderHumanResult(result) {
             "platform start       完成全量检查后启动平台",
             "platform stop        按逆依赖顺序停止平台",
             "",
-            "常用参数：--workspace <路径>；setup 还支持 --module <模块名>",
-            "推荐流程：install → status → docs → setup → start → status → stop",
-            "人工配置示例：pnpm exec -- proflow-chatgpt-carrier setup",
-            "AI 配置示例：pnpm exec -- proflow-chatgpt-carrier setup --carrier-url <url>",
-            "状态图例：已就绪＝配置完成；需要操作＝需运行 setup；失败＝存在系统阻塞；无独立进程＝无需启动",
+            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");
     if (result.command === "version" && isRecord(result.data))
         return String(result.data.version ?? platformCliDescriptor.moduleVersion);
     if (result.command === "status")
-        return renderStatus(result.data);
+        return renderStatus(result.data, theme);
     if (result.command === "setup")
-        return renderSetup(result.data);
+        return renderSetup(result.data, theme);
     if (result.command === "docs")
-        return renderDocs(result.data);
+        return renderDocs(result.data, theme);
     if ((result.command === "start" || result.command === "stop") &&
         isRecord(result.data)) {
         const skippedItems = Array.isArray(result.data.skipped)
@@ -684,8 +839,10 @@ export function renderHumanResult(result) {
             !skippedRefs.has(String(item.moduleRef))).length;
         const failed = operations.find((item) => isRecord(item.result) && item.result.status !== "SUCCEEDED");
         return [
-            `平台${result.command === "start" ? "启动" : "停止"}${failed ? "未完成" : "完成"}`,
-            `成功：${succeeded}，跳过：${skipped}${failed ? `，失败：${String(failed.moduleRef)}` : "，失败：0"}`,
+            failed
+                ? theme.failure(`平台${result.command === "start" ? "启动" : "停止"}未完成`)
+                : theme.success(`✓ 平台${result.command === "start" ? "启动" : "停止"}完成`),
+            `${theme.success(`成功：${succeeded}`)}  ${theme.muted(`跳过：${skipped}`)}  ${failed ? theme.failure(`失败：${String(failed.moduleRef)}`) : theme.muted("失败：0")}`,
         ].join("\n");
     }
     const labels = {
@@ -694,14 +851,40 @@ export function renderHumanResult(result) {
         start: "启动",
         stop: "停止",
     };
-    return `${labels[result.command] ?? result.command}${result.status === "SUCCEEDED" ? "成功" : "未完成"}${result.workspaceRoot ? `\nWorkspace：${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) {
     const argv = process.argv.slice(2);
     const reporter = createTerminalProgressReporter();
     const result = await runCli(argv, { onProgress: reporter });
     reporter.close();
-    process.stdout.write(`${renderHumanResult(result)}\n`);
+    const color = process.stdout.isTTY === true &&
+        process.env.NO_COLOR === undefined &&
+        process.env.TERM !== "dumb";
+    const rendered = `${renderHumanResult(result, {
+        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);
     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/install/package-manager.d.ts

@@ -6,7 +6,11 @@ export interface WorkspacePackageManagerSelection {
     declared?: string;
 }
 export interface PackageCommandRunner {
-    run(command: string, args: readonly string[], cwd: string): Promise<string>;
+    run(command: string, args: readonly string[], cwd: string, onOutput?: (line: PackageCommandOutput) => void): Promise<string>;
+}
+export interface PackageCommandOutput {
+    stream: "stdout" | "stderr";
+    line: string;
 }
 export declare function systemPackageCommandRunner(): PackageCommandRunner;
 export declare function readWorkspacePackageManagerSelection(workspaceRoot: string): Promise<WorkspacePackageManagerSelection>;
@@ -24,11 +28,13 @@ export declare function syncWorkspacePackages(options: {
     packages: readonly WorkspacePackageTarget[];
     runner?: PackageCommandRunner;
     executableAvailable?: (command: string) => boolean;
+    onOutput?: (line: PackageCommandOutput) => void;
 }): Promise<WorkspacePackageMutationResult>;
 export declare function removeWorkspacePackages(options: {
     workspaceRoot: string;
     packageNames: readonly string[];
     runner?: PackageCommandRunner;
     executableAvailable?: (command: string) => boolean;
+    onOutput?: (line: PackageCommandOutput) => void;
 }): Promise<WorkspacePackageMutationResult>;
 export declare function observeWorkspaceInstalledVersion(workspaceRoot: string, packageName: string): Promise<string | undefined>;

package/dist/src/install/package-manager.js

@@ -1,20 +1,58 @@
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { delimiter, join } from "node:path";
-import { promisify } from "node:util";
 import { PlatformError } from "../errors.js";
 import { atomicWrite } from "../paths.js";
-const execFileAsync = promisify(execFile);
 export function systemPackageCommandRunner() {
     return {
-        async run(command, args, cwd) {
-            const result = await execFileAsync(command, [...args], {
-                cwd,
-                encoding: "utf8",
-                maxBuffer: 4 * 1024 * 1024,
+        async run(command, args, cwd, onOutput) {
+            return new Promise((resolvePromise, rejectPromise) => {
+                const child = spawn(command, [...args], {
+                    cwd,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                let stdout = "";
+                let stderr = "";
+                const pending = {
+                    stdout: "",
+                    stderr: "",
+                };
+                const consume = (stream, chunk) => {
+                    const text = chunk.toString("utf8");
+                    if (stream === "stdout")
+                        stdout += text;
+                    else
+                        stderr += text;
+                    const parts = `${pending[stream]}${text}`.split(/\r?\n|\r/);
+                    pending[stream] = parts.pop() ?? "";
+                    for (const line of parts) {
+                        const normalized = line.trim();
+                        if (normalized)
+                            onOutput?.({ stream, line: normalized });
+                    }
+                };
+                const flush = () => {
+                    for (const stream of ["stdout", "stderr"]) {
+                        const line = pending[stream].trim();
+                        if (line)
+                            onOutput?.({ stream, line });
+                        pending[stream] = "";
+                    }
+                };
+                child.stdout.on("data", (chunk) => consume("stdout", chunk));
+                child.stderr.on("data", (chunk) => consume("stderr", chunk));
+                child.once("error", rejectPromise);
+                child.once("close", (code, signal) => {
+                    flush();
+                    if (code === 0)
+                        resolvePromise(stdout);
+                    else {
+                        const detail = stderr.trim() || stdout.trim();
+                        rejectPromise(new Error(`${command} exited with ${code ?? signal ?? "unknown"}${detail ? `: ${detail}` : ""}`));
+                    }
+                });
             });
-            return result.stdout;
         },
     };
 }
@@ -125,7 +163,7 @@ export async function syncWorkspacePackages(options) {
     await writeManagedPackageSet(options.workspaceRoot, targets);
     const args = await packageManagerInstallArgs(runner, manager, options.workspaceRoot);
     try {
-        await runner.run(manager.name, args, options.workspaceRoot);
+        await runner.run(manager.name, args, options.workspaceRoot, options.onOutput);
     }
     catch (error) {
         throw new PlatformError("COMMAND_FAILED", `${manager.name} install failed: ${packageMutationError(error)}`);
@@ -177,7 +215,7 @@ export async function removeWorkspacePackages(options) {
     const manager = await requireWorkspacePackageManager(options.workspaceRoot, options.executableAvailable ?? findExecutable);
     const args = await batchPackageManagerArgs(runner, manager, options.workspaceRoot, "remove", packageNames);
     try {
-        await runner.run(manager.name, args, options.workspaceRoot);
+        await runner.run(manager.name, args, options.workspaceRoot, options.onOutput);
     }
     catch (error) {
         throw new PlatformError("UNINSTALL_FAILED", `${manager.name} remove failed: ${packageMutationError(error)}`);

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

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

package/dist/src/lifecycle/thin.js

@@ -250,7 +250,11 @@ export async function startModulesThin(catalog, modules, workspaceRoot, reporter
             message: `${module.moduleRef}`,
         });
         if (!succeeded(status.result)) {
-            blockers.push({ moduleRef: module.moduleRef, setupStatus: "FAILED" });
+            blockers.push({
+                moduleRef: module.moduleRef,
+                setupStatus: "FAILED",
+                reason: status.result.error?.message ?? "模块状态检查失败",
+            });
             continue;
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);

package/dist/src/progress.d.ts

@@ -1,10 +1,13 @@
-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 interface PlatformProgressEvent {
     command: string;
     phase: string;
+    kind?: PlatformProgressKind;
     current?: number;
     total?: number;
     moduleRef?: string;
+    elapsedMs?: number;
     status: PlatformProgressStatus;
     message: string;
 }

package/dist/src/registry/npm-registry.d.ts

@@ -34,4 +34,10 @@ export declare function discoverRegistryModules(options: {
     packageName?: string;
     runner?: NpmCommandRunner;
     nodeVersion?: string;
+    onSearchComplete?: (total: number) => void;
+    onPackageChecked?: (input: {
+        current: number;
+        total: number;
+        packageName: string;
+    }) => void;
 }): Promise<RegistryDiscoveryResult>;

package/dist/src/registry/npm-registry.js

@@ -42,16 +42,32 @@ export async function discoverRegistryModules(options) {
     const names = options.packageName === undefined
         ? await searchPackageNames(options.workspaceRoot, registry, runner)
         : [validateRequestedPackageName(options.packageName)];
+    options.onSearchComplete?.(names.length);
     const candidates = [];
     const rejected = [];
-    for (const packageName of names) {
-        const manifest = await viewManifest(options.workspaceRoot, registry, packageName, runner);
-        const assessed = assessManifest(manifest, registry, options.nodeVersion ?? process.versions.node);
-        if ("candidate" in assessed)
-            candidates.push(assessed.candidate);
-        else
-            rejected.push(assessed.rejected);
-    }
+    let nextIndex = 0;
+    let completed = 0;
+    const worker = async () => {
+        while (nextIndex < names.length) {
+            const index = nextIndex++;
+            const packageName = names[index];
+            if (packageName === undefined)
+                return;
+            const manifest = await viewManifest(options.workspaceRoot, registry, packageName, runner);
+            const assessed = assessManifest(manifest, registry, options.nodeVersion ?? process.versions.node);
+            if ("candidate" in assessed)
+                candidates.push(assessed.candidate);
+            else
+                rejected.push(assessed.rejected);
+            completed += 1;
+            options.onPackageChecked?.({
+                current: completed,
+                total: names.length,
+                packageName,
+            });
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(4, names.length) }, () => worker()));
     candidates.sort((left, right) => left.packageName.localeCompare(right.packageName));
     rejected.sort((left, right) => left.packageName.localeCompare(right.packageName));
     return { registry, candidates, rejected };

package/dist/src/terminal.js

@@ -1,40 +1,58 @@
 import { clearLine, cursorTo } from "node:readline";
 const colors = {
+    cyan: "\u001b[36m",
+    blue: "\u001b[34m",
     green: "\u001b[32m",
     red: "\u001b[31m",
     yellow: "\u001b[33m",
+    bold: "\u001b[1m",
     dim: "\u001b[2m",
     reset: "\u001b[0m",
 };
 const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 function progressLine(event, color, spinner = "") {
-    const prefix = event.current && event.total ? `${event.current}/${event.total} · ` : "";
+    const prefix = event.current && event.total
+        ? `[${String(event.current).padStart(String(event.total).length, "0")}/${event.total}] `
+        : "";
+    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 symbol = event.status === "STARTED"
-        ? spinner
-        : event.status === "SUCCEEDED"
-            ? "✓"
-            : event.status === "FAILED"
-                ? "✕"
-                : event.status === "ACTION_REQUIRED"
-                    ? "◆"
-                    : "○";
+        : 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 === "WARNING"
+                    ? "!"
+                    : event.status === "FAILED"
+                        ? "✕"
+                        : event.status === "ACTION_REQUIRED"
+                            ? "◆"
+                            : "○";
     if (!color)
-        return `${symbol ? `${symbol} ` : ""}${prefix}${event.message}${suffix ? ` · ${suffix}` : ""}`;
+        return `${symbol ? `${symbol} ` : ""}${prefix}${event.message}${suffix ? ` · ${suffix}` : ""}${elapsed}`;
     const tone = event.status === "SUCCEEDED"
         ? colors.green
-        : event.status === "FAILED"
-            ? colors.red
-            : colors.yellow;
-    return `${tone}${symbol}${colors.reset} ${colors.dim}${prefix}${colors.reset}${event.message}${suffix ? ` · ${tone}${suffix}${colors.reset}` : ""}`;
+        : 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) {
     const interactive = stream.isTTY === true;
@@ -58,7 +76,10 @@ export function createTerminalProgressReporter(stream = process.stderr) {
     };
     const reporter = ((event) => {
         clearSpinner();
-        active = event.status === "STARTED" ? event : undefined;
+        const previousActive = active;
+        if (event.kind !== "subprocess") {
+            active = event.status === "STARTED" ? event : undefined;
+        }
         const line = progressLine(event, color, interactive ? spinnerFrames[frame++ % spinnerFrames.length] : "›");
         if (!interactive) {
             stream.write(`${line}\n`);
@@ -67,18 +88,22 @@ export function createTerminalProgressReporter(stream = process.stderr) {
         cursorTo(stream, 0);
         clearLine(stream, 0);
         stream.write(line);
+        if (event.kind === "subprocess") {
+            stream.write("\n");
+            active = previousActive;
+            if (active) {
+                paint();
+                timer = setInterval(paint, 80);
+                timer.unref();
+            }
+            return;
+        }
         if (event.status === "STARTED") {
             timer = setInterval(paint, 80);
             timer.unref();
             return;
         }
-        const compactModuleProgress = event.current !== undefined &&
-            event.total !== undefined &&
-            event.current < event.total &&
-            event.status !== "FAILED" &&
-            event.status !== "ACTION_REQUIRED";
-        if (!compactModuleProgress)
-            stream.write("\n");
+        stream.write("\n");
     });
     reporter.close = () => {
         clearSpinner();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,11 +24,11 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.10"
+    "@tomflow/proflow-module-contract": "^0.1.11"
   },
   "devDependencies": {
-    "@tomflow/proflow-module-template": "^0.1.8",
-    "@tomflow/proflow-deployment-conformance": "^0.1.8"
+    "@tomflow/proflow-deployment-conformance": "^0.1.9",
+    "@tomflow/proflow-module-template": "^0.1.9"
   },
   "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.33",
+	"moduleVersion": "0.1.35",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",