@tomflow/proflow-platform-cli 0.1.21 → 0.1.23

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.23
+
+### Patch Changes
+
+- Resolve DOCS.md from both source and built deployment adapters, prove all 24 built adapters return the published body, and announce package synchronization before the package manager blocks.
+
+## 0.1.22
+
+### Patch Changes
+
+- Replace JSON terminal protocols with typed CLI outcomes, add real-time Chinese progress and lifecycle summaries, publish DOCS content, standardize executable setup plans and package-owned setup commands, and preserve only user-owned pnpm policy during uninstall.
+
 ## 0.1.21
 
 ### Patch Changes

package/README.md

@@ -51,7 +51,7 @@ There is no Platform-derived configuration status, missing-input list, overall r
 
 `platform setup` scans all discovered Modules in dependency order. It skips `READY` Modules, invokes `Module.setup` for every non-ready Module, continues after `ACTION_REQUIRED` or `FAILED`, and returns one complete aggregate.
 
-Targeted `platform setup --module <moduleRef> --input '<json>'` forwards opaque input to the owning Module. Platform neither interprets that input nor creates Module-specific instructions.
+Targeted `platform setup --module <moduleRef>` re-observes one Module. Human or AI input is collected by the package-owned setup command shown by `platform setup`; Platform does not accept raw JSON input.
 
 ## Docs
 

package/SETUP.md

@@ -1,27 +1,10 @@
 # @tomflow/proflow-platform-cli — Module Setup
 
-The Platform CLI owns orchestration only. It never interprets another Module's setup details. Global `platform setup` traverses every discovered Module, skips `READY` Modules, lets each non-ready Module run its own package-owned setup workflow, and aggregates every remaining `ACTION_REQUIRED` or `FAILED` result in one response.
-
-## Step 1 — Verify the Platform CLI Module
-
-**Executable:**
-
-```bash
-platform setup --module platform-cli
-```
-
-**Success condition:**
-
-`platform status` reports `platform-cli setup=READY`. No user/private path, token, loopback endpoint, or cross-Module fact is requested.
-
-## Step 2 — Run the full workspace setup guide
-
-**Executable:**
-
-```bash
-platform setup
-```
-
-**Success condition:**
-
-All automatically solvable Module setup work is completed in the same run, and every remaining human/external action is listed together. Re-running the command re-observes reality and continues until all required Modules report `setupStatus=READY`.
+## STEP-PLATFORM-CLI-01 — 完成模块自动配置
+
+Responsible: AI
+Interactive executable: `platform setup --module platform-cli`
+Non-interactive executable: `platform setup --module platform-cli`
+Required inputs: none
+Verify: `platform status`
+Success condition: `platform-cli.setupStatus=READY`.

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.21";
+            readonly moduleVersion: "0.1.23";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.21";
+            readonly moduleVersion: "0.1.23";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.21";
+            moduleVersion: "0.1.23";
             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.21";
+            readonly moduleVersion: "0.1.23";
         };
         observedEffects: never[];
     }>;
@@ -50,10 +50,9 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.21";
+            moduleVersion: "0.1.23";
             data: {
                 docs: string;
-                setup: string;
             };
         };
         observedEffects: never[];
@@ -64,7 +63,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.21";
+            readonly moduleVersion: "0.1.23";
         };
         observedEffects: never[];
     }>;
@@ -74,7 +73,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.21";
+            readonly moduleVersion: "0.1.23";
         };
         observedEffects: never[];
     }>;

package/dist/deployment/adapter.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
@@ -28,7 +29,12 @@ export const behaviorAdapter = {
         observedEffects: [],
     }),
     docs: async (_context) => ({
-        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        result: {
+            ...base,
+            data: {
+                docs: readFileSync(new URL(import.meta.url.includes("/dist/") ? "../../DOCS.md" : "../DOCS.md", import.meta.url), "utf8"),
+            },
+        },
         observedEffects: [],
     }),
     start: async (_context) => ({

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.21";
+    readonly moduleVersion: "0.1.23";
     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.21",
+    moduleVersion: "0.1.23",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type PackageCommandRunner } from "./install/package-manager.ts";
+import { type PlatformProgressReporter } from "./progress.ts";
 import { type NpmCommandRunner } from "./registry/index.ts";
 export type CliStatus = "SUCCEEDED" | "ACTION_REQUIRED" | "BLOCKED" | "FAILED";
 export interface CliOutcome {
@@ -17,6 +18,7 @@ export interface CliRuntimeOptions {
     registryRunner?: NpmCommandRunner;
     packageRunner?: PackageCommandRunner;
     executableAvailable?: (command: string) => boolean;
+    onProgress?: PlatformProgressReporter;
 }
-export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<string>;
+export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<CliOutcome>;
 export declare function renderHumanResult(result: CliOutcome): string;

package/dist/src/cli.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve } from "node:path";
-import { moduleStatusObservationSchema } from "@tomflow/proflow-module-contract";
+import { moduleDocsDataSchema, moduleSetupPlanDataSchema, moduleStatusObservationSchema, } from "@tomflow/proflow-module-contract";
 import { descriptor as platformCliDescriptor } from "../deployment/descriptor.js";
 import { AutoModuleCatalog, discoverModules } from "./discovery/discover.js";
 import { InstalledModuleCatalog } from "./discovery/installed.js";
 import { PlatformError } from "./errors.js";
 import { observeWorkspaceInstalledVersion, removeWorkspacePackages, syncWorkspacePackages, } from "./install/package-manager.js";
+import { cleanOwnedPnpmPolicy, observeMinimumReleaseAgeExclude, recordPnpmPolicyOwnership, } from "./install/pnpm-policy.js";
 import { installModulesThin, observeDocs, observeStatuses, setupModulesThin, startModulesThin, stopModulesThin, uninstallModulesThin, } from "./lifecycle/index.js";
 import { ensureWorkspaceMetadata } from "./persistence/workspace-metadata.js";
+import { reportProgress } from "./progress.js";
 import { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, } from "./registry/index.js";
+import { createTerminalProgressReporter } from "./terminal.js";
 const COMMANDS = [
     "install",
     "uninstall",
@@ -20,36 +23,23 @@ const COMMANDS = [
     "stop",
 ];
 function parseArgs(argv) {
-    let json = false, workspace, moduleRef, input, inputSeen = false;
+    let workspace, moduleRef;
     let special;
     const positional = [];
     for (let index = 0; index < argv.length; index += 1) {
         const value = argv[index];
         if (value === undefined)
             continue;
-        if (value === "--json") {
-            json = true;
-            continue;
-        }
-        if (value === "--workspace" ||
-            value === "--module" ||
-            value === "--input") {
+        if (value === "--json")
+            throw new PlatformError("INVALID_REQUEST", "不支持的选项 --json");
+        if (value === "--workspace" || value === "--module") {
             const next = argv[index + 1];
-            if (!next || (value !== "--input" && next.startsWith("-")))
+            if (!next || next.startsWith("-"))
                 throw new PlatformError("INVALID_REQUEST", `${value} requires a value`);
             if (value === "--workspace")
                 workspace = next;
             else if (value === "--module")
                 moduleRef = next;
-            else {
-                try {
-                    input = JSON.parse(next);
-                    inputSeen = true;
-                }
-                catch (error) {
-                    throw new PlatformError("INVALID_REQUEST", `--input must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-                }
-            }
             index += 1;
             continue;
         }
@@ -68,29 +58,24 @@ function parseArgs(argv) {
     if (special !== undefined) {
         if (workspace !== undefined ||
             moduleRef !== undefined ||
-            inputSeen ||
             positional.length > 0)
             throw new PlatformError("INVALID_REQUEST", `${special} flag cannot be combined with command options`);
-        return { command: special, json };
+        return { command: special };
     }
     if (positional.length === 0)
-        return { command: "help", json };
+        return { command: "help" };
     if (positional.length !== 1)
         throw new PlatformError("INVALID_REQUEST", "commands accept no positional arguments");
     const raw = positional[0] ?? "";
     if (!COMMANDS.includes(raw))
         throw new PlatformError("INVALID_REQUEST", `unknown command ${raw}`);
     const command = raw;
-    if ((moduleRef !== undefined || inputSeen) && command !== "setup")
-        throw new PlatformError("INVALID_REQUEST", "--module/--input are only valid with setup");
-    if (inputSeen && moduleRef === undefined)
-        throw new PlatformError("INVALID_REQUEST", "--input requires --module");
+    if (moduleRef !== undefined && command !== "setup")
+        throw new PlatformError("INVALID_REQUEST", "--module is only valid with setup");
     return {
         command,
-        json,
         ...(workspace === undefined ? {} : { workspace }),
         ...(moduleRef === undefined ? {} : { moduleRef }),
-        ...(inputSeen ? { input } : {}),
     };
 }
 function outcome(command, status, workspaceRoot, data) {
@@ -144,9 +129,9 @@ function batchStatus(result) {
         return "ACTION_REQUIRED";
     return "FAILED";
 }
-async function handleStatus(root) {
+async function handleStatus(root, runtime) {
     const { catalog, modules } = await buildContext(root);
-    const observed = await observeStatuses(catalog, modules, root);
+    const observed = await observeStatuses(catalog, modules, root, runtime.onProgress);
     const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
     const output = observed.map((item) => {
         if (item.result.status !== "SUCCEEDED")
@@ -166,16 +151,32 @@ async function handleStatus(root) {
     });
     return outcome("status", "SUCCEEDED", root, { modules: output });
 }
-async function handleDocs(root) {
-    const { catalog, modules } = await buildContext(root);
-    const docs = await observeDocs(catalog, modules, root);
-    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
-    return outcome("docs", "SUCCEEDED", root, {
-        modules: docs.map((item) => ({
+async function handleDocs(root, runtime) {
+    const { catalog, modules: resolvedModules } = await buildContext(root);
+    const docs = await observeDocs(catalog, resolvedModules, root, runtime.onProgress);
+    const byRef = new Map(resolvedModules.map((module) => [module.moduleRef, module]));
+    const modules = [];
+    const errors = [];
+    for (const item of docs) {
+        const parsed = moduleDocsDataSchema.safeParse(item.result.data);
+        if (item.result.status !== "SUCCEEDED" || !parsed.success) {
+            errors.push({
+                moduleRef: item.moduleRef,
+                reason: item.result.status !== "SUCCEEDED"
+                    ? (item.result.error?.message ?? "文档读取失败")
+                    : "Module.docs 返回格式无效",
+            });
+            continue;
+        }
+        modules.push({
             moduleRef: item.moduleRef,
             version: byRef.get(item.moduleRef)?.moduleVersion,
-            docs: item.result.data,
-        })),
+            docs: parsed.data.docs,
+        });
+    }
+    return outcome("docs", errors.length === 0 ? "SUCCEEDED" : "FAILED", root, {
+        modules,
+        errors,
     });
 }
 async function validateInstalledPackageSet(root, candidates, previousManaged) {
@@ -203,7 +204,19 @@ async function validateInstalledPackageSet(root, candidates, previousManaged) {
     }
 }
 async function handleInstall(root, runtime) {
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "workspace",
+        status: "STARTED",
+        message: "正在校验 Workspace",
+    });
     const metadata = await ensureWorkspaceMetadata(root);
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "registry",
+        status: "STARTED",
+        message: "正在发现 Registry 模块",
+    });
     const discovered = await discoverRegistryModules({
         workspaceRoot: root,
         ...(runtime.registryRunner === undefined
@@ -215,6 +228,13 @@ async function handleInstall(root, runtime) {
     if (discovered.candidates.length === 0)
         throw new PlatformError("PACKAGE_NOT_FOUND", "no ProFlow packages were discovered in the configured scope");
     const previousManaged = await workspaceProFlowDependencies(root);
+    const pnpmPolicyBefore = await observeMinimumReleaseAgeExclude(root);
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "packages",
+        status: "STARTED",
+        message: "正在同步依赖",
+    });
     const mutation = await syncWorkspacePackages({
         workspaceRoot: root,
         packages: discovered.candidates.map((item) => ({
@@ -228,9 +248,16 @@ async function handleInstall(root, runtime) {
             ? {}
             : { executableAvailable: runtime.executableAvailable }),
     });
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "packages",
+        status: "SUCCEEDED",
+        message: "依赖同步完成",
+    });
+    await recordPnpmPolicyOwnership(root, pnpmPolicyBefore);
     await validateInstalledPackageSet(root, discovered.candidates, previousManaged);
     const { catalog, modules } = await buildContext(root);
-    const moduleInstall = await installModulesThin(catalog, modules, root);
+    const moduleInstall = await installModulesThin(catalog, modules, root, runtime.onProgress);
     return outcome("install", batchStatus(moduleInstall), root, {
         registry: discovered.registry,
         packageManager: mutation.packageManager,
@@ -271,7 +298,7 @@ async function workspaceProFlowDependencies(root) {
 async function handleUninstall(root, runtime) {
     const packageNames = await workspaceProFlowDependencies(root);
     const { catalog, modules } = await buildContext(root);
-    const moduleUninstall = await uninstallModulesThin(catalog, modules, root);
+    const moduleUninstall = await uninstallModulesThin(catalog, modules, root, runtime.onProgress);
     if (!moduleUninstall.completed)
         return outcome("uninstall", batchStatus(moduleUninstall), root, {
             modules: moduleUninstall,
@@ -287,40 +314,39 @@ async function handleUninstall(root, runtime) {
             ? {}
             : { executableAvailable: runtime.executableAvailable }),
     });
+    const cleanedPnpmPolicy = await cleanOwnedPnpmPolicy(root);
     return outcome("uninstall", "SUCCEEDED", root, {
         modules: moduleUninstall,
         packageManager: mutation.packageManager,
         removed: packageNames,
+        cleanedPnpmPolicy,
         preserved: [".proflow"],
     });
 }
-async function handleSetup(root, parsed) {
+async function handleSetup(root, parsed, runtime) {
     const { catalog, modules } = await buildContext(root);
     const target = parsed.moduleRef === undefined
         ? undefined
-        : {
-            moduleRef: parsed.moduleRef,
-            ...(Object.hasOwn(parsed, "input") ? { input: parsed.input } : {}),
-        };
-    const result = await setupModulesThin(catalog, modules, root, target);
+        : { moduleRef: parsed.moduleRef };
+    const result = await setupModulesThin(catalog, modules, root, target, runtime.onProgress);
     return outcome("setup", batchStatus(result), root, result);
 }
-async function handleStart(root) {
+async function handleStart(root, runtime) {
     const { catalog, modules } = await buildContext(root);
-    const result = await startModulesThin(catalog, modules, root);
+    const result = await startModulesThin(catalog, modules, root, runtime.onProgress);
     return outcome("start", batchStatus(result), root, result);
 }
-async function handleStop(root) {
+async function handleStop(root, runtime) {
     const { catalog, modules } = await buildContext(root);
-    const result = await stopModulesThin(catalog, modules, root);
+    const result = await stopModulesThin(catalog, modules, root, runtime.onProgress);
     return outcome("stop", batchStatus(result), root, result);
 }
 function helpOutcome() {
     return outcome("help", "SUCCEEDED", undefined, {
-        usage: "platform <install|uninstall|status|setup|docs|start|stop> [--workspace <path>] [--json]",
+        usage: "platform <install|uninstall|status|setup|docs|start|stop> [--workspace <path>]",
         commands: [...COMMANDS],
         install: "platform install [--workspace <path>]",
-        setup: "platform setup [--workspace <path>] [--module <moduleRef> --input '<json>']",
+        setup: "platform setup [--workspace <path>] [--module <moduleRef>]",
     });
 }
 export async function runCli(argv, runtime = {}) {
@@ -329,35 +355,35 @@ export async function runCli(argv, runtime = {}) {
         parsed = parseArgs(argv);
     }
     catch (error) {
-        return JSON.stringify(errorOutcome("unknown", error));
+        return errorOutcome("unknown", error);
     }
     try {
         if (parsed.command === "help")
-            return JSON.stringify(helpOutcome());
+            return helpOutcome();
         if (parsed.command === "version")
-            return JSON.stringify(outcome("version", "SUCCEEDED", undefined, {
+            return outcome("version", "SUCCEEDED", undefined, {
                 version: platformCliDescriptor.moduleVersion,
-            }));
+            });
         const root = await canonicalWorkspace(runtime.cwd ?? process.cwd(), parsed.workspace);
         switch (parsed.command) {
             case "install":
-                return JSON.stringify(await handleInstall(root, runtime));
+                return await handleInstall(root, runtime);
             case "uninstall":
-                return JSON.stringify(await handleUninstall(root, runtime));
+                return await handleUninstall(root, runtime);
             case "status":
-                return JSON.stringify(await handleStatus(root));
+                return await handleStatus(root, runtime);
             case "setup":
-                return JSON.stringify(await handleSetup(root, parsed));
+                return await handleSetup(root, parsed, runtime);
             case "docs":
-                return JSON.stringify(await handleDocs(root));
+                return await handleDocs(root, runtime);
             case "start":
-                return JSON.stringify(await handleStart(root));
+                return await handleStart(root, runtime);
             case "stop":
-                return JSON.stringify(await handleStop(root));
+                return await handleStop(root, runtime);
         }
     }
     catch (error) {
-        return JSON.stringify(errorOutcome(parsed.command, error));
+        return errorOutcome(parsed.command, error);
     }
 }
 function errorOutcome(command, error) {
@@ -379,28 +405,81 @@ function errorOutcome(command, error) {
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function renderStatus(data) {
     if (!isRecord(data) || !Array.isArray(data.modules))
-        return "No modules.";
+        return "未发现模块。";
+    const setupLabels = {
+        READY: "已就绪",
+        ACTION_REQUIRED: "需要操作",
+        FAILED: "失败",
+    };
+    const runtimeLabels = {
+        RUNNING: "运行中",
+        STOPPED: "已停止",
+        FAILED: "运行失败",
+        NOT_APPLICABLE: "无独立进程",
+    };
     return [
-        "ProFlow Modules",
+        "ProFlow 模块状态",
         "",
+        "模块                         版本       配置状态   运行状态",
         ...data.modules
             .filter(isRecord)
-            .map((raw) => `${String(raw.moduleRef)}  ${String(raw.version)}  setup=${String(raw.setupStatus)}  runtime=${String(raw.runtimeStatus)}`),
+            .map((raw) => `${String(raw.moduleRef).padEnd(28)} ${String(raw.version).padEnd(10)} ${(setupLabels[String(raw.setupStatus)] ?? "未知").padEnd(10)} ${runtimeLabels[String(raw.runtimeStatus)] ?? "未知"}`),
+        "",
+        "需要操作：运行 platform setup",
+        "失败：运行 platform setup 查看原因和修复步骤",
     ].join("\n");
 }
 function renderDocs(data) {
     if (!isRecord(data) || !Array.isArray(data.modules))
-        return "No module docs.";
-    const lines = ["ProFlow Docs"];
+        return "未发现模块文档。";
+    const lines = ["ProFlow 模块文档"];
     for (const raw of data.modules)
         if (isRecord(raw))
-            lines.push("", `## ${String(raw.moduleRef)} @ ${String(raw.version)}`, JSON.stringify(raw.docs ?? {}, null, 2));
+            lines.push("", `## ${String(raw.moduleRef)} @ ${String(raw.version)}`, String(raw.docs ?? ""));
+    if (Array.isArray(data.errors) && data.errors.length > 0)
+        lines.push("", "文档读取失败：", ...data.errors
+            .filter(isRecord)
+            .map((item) => `- ${String(item.moduleRef)}：${String(item.reason)}`));
     return lines.join("\n");
 }
+const setupCommands = {
+    "chatgpt-carrier": {
+        ai: "proflow-chatgpt-carrier setup --carrier-url <url>",
+        inputs: "Custom GPT URL",
+    },
+    "dev-tunnel": {
+        ai: "proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>",
+        inputs: "Tunnel ID、公开 HTTPS URL",
+    },
+    "model-provider-api": {
+        ai: "proflow-model-provider-api setup --provider-base-url <url>",
+        inputs: "模型服务 Base URL",
+    },
+    "model-runtime": {
+        ai: "proflow-model-runtime setup --fast-model <id> --reason-model <id>",
+        inputs: "FAST 模型 ID、REASON 模型 ID",
+    },
+    "execution-browser-extension": {
+        ai: "proflow-execution-browser-extension setup --extension-id <id>",
+        inputs: "Chrome Extension ID",
+    },
+    "agent-controller-dev": {
+        ai: "proflow-agent-controller-dev setup --carrier-url <url>",
+        inputs: "Custom GPT URL",
+    },
+    "agent-product": {
+        ai: "proflow-agent-product setup --carrier-url <url>",
+        inputs: "Custom GPT URL",
+    },
+    "agent-test-ops": {
+        ai: "proflow-agent-test-ops setup --carrier-url <url>",
+        inputs: "Custom GPT URL",
+    },
+};
 function renderSetup(data) {
     if (!isRecord(data) || !Array.isArray(data.results))
-        return "No setup actions are required.";
-    const lines = ["ProFlow Setup", ""];
+        return "没有需要执行的配置步骤。";
+    const lines = ["ProFlow 配置", ""];
     let automatic = 0;
     let pending = 0;
     for (const raw of data.results) {
@@ -413,31 +492,52 @@ function renderSetup(data) {
             continue;
         }
         pending += 1;
-        lines.push(`## ${moduleRef} — ${status}`);
-        const actionRequired = raw.result.actionRequired;
+        lines.push(moduleRef);
+        const plan = moduleSetupPlanDataSchema.safeParse(raw.result.data);
+        if (plan.success) {
+            for (const [index, step] of plan.data.steps.entries()) {
+                lines.push(`  [${step.state} ${index + 1}/${plan.data.steps.length}] ${step.title}`);
+                lines.push(`  人工执行：${step.execution.interactive}`);
+                lines.push(`  AI 执行：${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}`);
+                if (step.blockedReason)
+                    lines.push(`  原因：${step.blockedReason}`);
+            }
+            lines.push("");
+            continue;
+        }
+        lines.push(`  [${status === "FAILED" ? "BLOCKED" : "TODO"} 1/1] ${status === "FAILED" ? "等待上游服务信息" : "完成模块配置"}`);
         const error = raw.result.error;
-        if (isRecord(actionRequired)) {
-            if (actionRequired.action !== undefined)
-                lines.push(`Action: ${String(actionRequired.action)}`);
-            if (actionRequired.description !== undefined)
-                lines.push(String(actionRequired.description));
+        if (status !== "FAILED") {
+            const commands = setupCommands[moduleRef] ?? {
+                ai: `proflow-${moduleRef} setup`,
+                inputs: "按命令提示提供",
+            };
+            lines.push(`  人工执行：proflow-${moduleRef} setup`);
+            lines.push(`  AI 执行：${commands.ai}`);
+            lines.push(`  需要输入：${commands.inputs}`);
+            lines.push(`  验证：proflow-${moduleRef} verify`);
+            lines.push("  完成条件：配置状态变为“已就绪”");
         }
         else if (isRecord(error)) {
             const code = error.code === undefined ? "FAILED" : String(error.code);
             const message = error.message === undefined
                 ? "Module setup failed."
                 : String(error.message);
-            lines.push(`Error: ${code} — ${message}`);
-        }
-        else if (raw.result.data !== undefined) {
-            lines.push(JSON.stringify(raw.result.data, null, 2));
+            lines.push(`  原因：${code} — ${message}`);
+            lines.push(`  执行：platform setup --module ${moduleRef}`);
+            lines.push("  完成条件：配置状态变为“已就绪”");
         }
         lines.push("");
     }
     if (pending === 0)
-        lines.push("All discovered Modules are setup-ready.");
+        lines.push("全部模块均已就绪。 ");
     if (automatic > 0)
-        lines.push(`Automatically completed in this run: ${automatic}`);
+        lines.push(`本次自动完成：${automatic} 个模块`);
+    lines.push(`汇总：${automatic} 个已就绪，${pending} 个待处理`);
     return lines.join("\n").trimEnd();
 }
 export function renderHumanResult(result) {
@@ -445,17 +545,38 @@ export function renderHumanResult(result) {
         isRecord(result.data) &&
         Array.isArray(result.data.results))
         return renderSetup(result.data);
-    if (result.status === "FAILED")
-        return `${result.command.toUpperCase()} FAILED${result.error ? ` [${result.error.code}] ${result.error.message}` : ""}`;
+    if (result.command === "start" && isRecord(result.data)) {
+        const blockers = Array.isArray(result.data.blockers)
+            ? result.data.blockers.filter(isRecord)
+            : [];
+        if (blockers.length > 0)
+            return [
+                "平台未启动：存在未就绪模块",
+                "",
+                ...blockers.map((item) => `${String(item.moduleRef).padEnd(28)} ${String(item.setupStatus) === "FAILED" ? "失败" : "需要操作"}  配置尚未完成`),
+                "",
+                `处理方式：platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`,
+            ].join("\n");
+    }
+    if (result.status === "FAILED" && result.error)
+        return `${result.command} 失败：${result.error.message}`;
     if (result.command === "help")
         return [
-            "ProFlow Platform CLI",
+            "ProFlow 平台命令行",
             "",
-            ...COMMANDS.map((command) => `platform ${command}`),
+            "platform install     安装并初始化全部 ProFlow 模块",
+            "platform uninstall   卸载模块包，保留 Workspace 数据",
+            "platform status      查看模块配置与运行状态",
+            "platform setup       自动配置并列出全部剩余步骤",
+            "platform docs        阅读模块能力文档",
+            "platform start       完成全量检查后启动平台",
+            "platform stop        按逆依赖顺序停止平台",
             "",
-            "platform install --workspace <path>",
-            "platform setup --module <moduleRef> --input '<json>'",
-            "append --json for machine-readable output",
+            "常用参数：--workspace <路径>；setup 还支持 --module <模块名>",
+            "推荐流程：install → status → docs → setup → start → status → stop",
+            "人工配置示例：proflow-chatgpt-carrier setup",
+            "AI 配置示例：proflow-chatgpt-carrier setup --carrier-url <url>",
+            "状态图例：已就绪＝配置完成；需要操作＝需运行 setup；失败＝存在系统阻塞；无独立进程＝无需启动",
         ].join("\n");
     if (result.command === "version" && isRecord(result.data))
         return String(result.data.version ?? platformCliDescriptor.moduleVersion);
@@ -465,19 +586,36 @@ export function renderHumanResult(result) {
         return renderSetup(result.data);
     if (result.command === "docs")
         return renderDocs(result.data);
-    return [
-        `${result.command.toUpperCase()} ${result.status}`,
-        ...(result.workspaceRoot ? [`Workspace: ${result.workspaceRoot}`] : []),
-        ...(result.data === undefined
-            ? []
-            : [JSON.stringify(result.data, null, 2)]),
-    ].join("\n");
+    if ((result.command === "start" || result.command === "stop") &&
+        isRecord(result.data)) {
+        const skipped = Array.isArray(result.data.skipped)
+            ? result.data.skipped.length
+            : 0;
+        const results = Array.isArray(result.data.results)
+            ? result.data.results.filter(isRecord)
+            : [];
+        const operations = results.filter((item) => item.command === result.command);
+        const succeeded = operations.filter((item) => isRecord(item.result) && item.result.status === "SUCCEEDED").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"}`,
+        ].join("\n");
+    }
+    const labels = {
+        install: "安装",
+        uninstall: "卸载",
+        start: "启动",
+        stop: "停止",
+    };
+    return `${labels[result.command] ?? result.command}${result.status === "SUCCEEDED" ? "成功" : "未完成"}${result.workspaceRoot ? `\nWorkspace：${result.workspaceRoot}` : ""}`;
 }
 if (import.meta.main) {
     const argv = process.argv.slice(2);
-    const output = await runCli(argv);
-    const result = JSON.parse(output);
-    process.stdout.write(`${argv.includes("--json") ? output : renderHumanResult(result)}\n`);
+    const result = await runCli(argv, {
+        onProgress: createTerminalProgressReporter(),
+    });
+    process.stdout.write(`${renderHumanResult(result)}\n`);
     if (result.status !== "SUCCEEDED")
         process.exitCode = 1;
 }

package/dist/src/command.d.ts

@@ -0,0 +1 @@
+export { type CliOutcome, type CliRuntimeOptions, type CliStatus, runCli, } from "./cli.ts";

package/dist/src/command.js

@@ -0,0 +1,3 @@
+// Stable programmatic command surface. Terminal entrypoints must consume this
+// typed outcome instead of parsing serialized stdout.
+export { runCli, } from "./cli.js";

package/dist/src/install/pnpm-policy.d.ts

@@ -0,0 +1,3 @@
+export declare function observeMinimumReleaseAgeExclude(root: string): Promise<string[]>;
+export declare function recordPnpmPolicyOwnership(root: string, before: readonly string[]): Promise<void>;
+export declare function cleanOwnedPnpmPolicy(root: string): Promise<string[]>;

package/dist/src/install/pnpm-policy.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWrite } from "../paths.js";
+const policyFileName = "pnpm-workspace.yaml";
+const ownershipFile = (root) => join(root, ".proflow", "deployment", "pnpm-policy-ownership.json");
+async function text(root) {
+    try {
+        return await readFile(join(root, policyFileName), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function observeMinimumReleaseAgeExclude(root) {
+    const source = await text(root);
+    if (!source)
+        return [];
+    const lines = source.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^minimumReleaseAgeExclude:\s*$/.test(line));
+    if (start < 0)
+        return [];
+    const values = [];
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (/^\S/.test(line) && line.trim() !== "")
+            break;
+        const match = line.match(/^\s+-\s+['"]?([^'"]+)['"]?\s*$/);
+        if (match?.[1])
+            values.push(match[1]);
+    }
+    return values;
+}
+export async function recordPnpmPolicyOwnership(root, before) {
+    const after = await observeMinimumReleaseAgeExclude(root);
+    const introduced = after.filter((value) => !before.includes(value));
+    if (introduced.length === 0)
+        return;
+    await mkdir(join(root, ".proflow", "deployment"), { recursive: true });
+    await atomicWrite(ownershipFile(root), `${JSON.stringify({ contract: "proflow.pnpm-policy-ownership.v1", introduced }, null, 2)}\n`);
+}
+export async function cleanOwnedPnpmPolicy(root) {
+    let introduced;
+    try {
+        const parsed = JSON.parse(await readFile(ownershipFile(root), "utf8"));
+        introduced =
+            typeof parsed === "object" &&
+                parsed !== null &&
+                Array.isArray(Reflect.get(parsed, "introduced"))
+                ? Reflect.get(parsed, "introduced").filter((value) => typeof value === "string")
+                : [];
+    }
+    catch {
+        return [];
+    }
+    if (introduced.length === 0)
+        return [];
+    const source = await text(root);
+    if (!source)
+        return [];
+    const owned = new Set(introduced);
+    const lines = source.split(/\r?\n/);
+    const next = lines.filter((line) => {
+        const match = line.match(/^\s+-\s+['"]?([^'"]+)['"]?\s*$/);
+        return !match?.[1] || !owned.has(match[1]);
+    });
+    await atomicWrite(join(root, policyFileName), next.join("\n"));
+    return introduced;
+}

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

@@ -1,6 +1,7 @@
 import { type ModuleSetupStatus } from "@tomflow/proflow-module-contract";
 import type { ResolvedModule } from "../contracts.ts";
 import type { ModuleCatalog } from "../modules.ts";
+import { type PlatformProgressReporter } from "../progress.ts";
 import { type ModuleDispatchResult } from "./dispatch.ts";
 export interface ModuleBatchResult {
     phase: "install" | "uninstall" | "setup" | "start" | "stop";
@@ -10,14 +11,22 @@ export interface ModuleBatchResult {
         moduleRef: string;
         setupStatus: ModuleSetupStatus;
     };
+    blockers?: Array<{
+        moduleRef: string;
+        setupStatus: ModuleSetupStatus;
+    }>;
+    skipped?: Array<{
+        moduleRef: string;
+        reason: "RUNNING" | "STOPPED" | "NOT_APPLICABLE";
+    }>;
 }
-export declare function observeStatuses(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string): Promise<ModuleDispatchResult[]>;
-export declare function observeDocs(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string): Promise<ModuleDispatchResult[]>;
-export declare const installModulesThin: (catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string) => Promise<ModuleBatchResult>;
-export declare const uninstallModulesThin: (catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string) => Promise<ModuleBatchResult>;
-export declare const stopModulesThin: (catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string) => Promise<ModuleBatchResult>;
+export declare function observeStatuses(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter): Promise<ModuleDispatchResult[]>;
+export declare function observeDocs(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter): Promise<ModuleDispatchResult[]>;
+export declare const installModulesThin: (catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter) => Promise<ModuleBatchResult>;
+export declare const uninstallModulesThin: (catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter) => Promise<ModuleBatchResult>;
+export declare function stopModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter): Promise<ModuleBatchResult>;
 export declare function setupModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, target?: {
     moduleRef: string;
     input?: unknown;
-}): Promise<ModuleBatchResult>;
-export declare function startModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string): Promise<ModuleBatchResult>;
+}, reporter?: PlatformProgressReporter): Promise<ModuleBatchResult>;
+export declare function startModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter): Promise<ModuleBatchResult>;

package/dist/src/lifecycle/thin.js

@@ -1,6 +1,7 @@
 import { moduleStatusObservationSchema, } from "@tomflow/proflow-module-contract";
 import { PlatformError } from "../errors.js";
 import { buildDependencyGraph } from "../graph/graph.js";
+import { reportProgress } from "../progress.js";
 import { dispatchModuleCommand, } from "./dispatch.js";
 const succeeded = (result) => result.status === "SUCCEEDED";
 const context = (workspaceRoot, input) => input === undefined ? { workspaceRoot } : { workspaceRoot, input };
@@ -12,38 +13,160 @@ function ordered(modules, reverse = false) {
         .map((ref) => byRef.get(ref))
         .filter((item) => item !== undefined);
 }
-export async function observeStatuses(catalog, modules, workspaceRoot) {
+export async function observeStatuses(catalog, modules, workspaceRoot, reporter) {
     const results = [];
-    for (const module of [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef)))
-        results.push(await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot)));
+    const modulesInOrder = [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef));
+    for (const [index, module] of modulesInOrder.entries()) {
+        reportProgress(reporter, {
+            command: "status",
+            phase: "status",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: module.moduleRef,
+        });
+        const result = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
+        results.push(result);
+        reportProgress(reporter, {
+            command: "status",
+            phase: "status",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(result.result) ? "SUCCEEDED" : "FAILED",
+            message: module.moduleRef,
+        });
+    }
     return results;
 }
-export async function observeDocs(catalog, modules, workspaceRoot) {
+export async function observeDocs(catalog, modules, workspaceRoot, reporter) {
     const results = [];
-    for (const module of [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef)))
-        results.push(await dispatchModuleCommand(catalog, module, "docs", context(workspaceRoot)));
+    const modulesInOrder = [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef));
+    for (const [index, module] of modulesInOrder.entries()) {
+        reportProgress(reporter, {
+            command: "docs",
+            phase: "docs",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: module.moduleRef,
+        });
+        const result = await dispatchModuleCommand(catalog, module, "docs", context(workspaceRoot));
+        results.push(result);
+        reportProgress(reporter, {
+            command: "docs",
+            phase: "docs",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(result.result) ? "SUCCEEDED" : "FAILED",
+            message: module.moduleRef,
+        });
+    }
     return results;
 }
-async function runOrdered(catalog, modules, workspaceRoot, command, reverse) {
+async function runOrdered(catalog, modules, workspaceRoot, command, reverse, reporter) {
     const results = [];
-    for (const module of ordered(modules, reverse)) {
+    const modulesInOrder = ordered(modules, reverse);
+    for (const [index, module] of modulesInOrder.entries()) {
+        reportProgress(reporter, {
+            command,
+            phase: command,
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: `${module.moduleRef}`,
+        });
         const result = await dispatchModuleCommand(catalog, module, command, context(workspaceRoot));
         results.push(result);
+        reportProgress(reporter, {
+            command,
+            phase: command,
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(result.result) ? "SUCCEEDED" : "FAILED",
+            message: `${module.moduleRef}`,
+        });
         if (!succeeded(result.result))
             return { phase: command, results, completed: false };
     }
     return { phase: command, results, completed: true };
 }
-export const installModulesThin = (catalog, modules, workspaceRoot) => runOrdered(catalog, modules, workspaceRoot, "install", false);
-export const uninstallModulesThin = (catalog, modules, workspaceRoot) => runOrdered(catalog, modules, workspaceRoot, "uninstall", true);
-export const stopModulesThin = (catalog, modules, workspaceRoot) => runOrdered(catalog, modules, workspaceRoot, "stop", true);
-export async function setupModulesThin(catalog, modules, workspaceRoot, target) {
+export const installModulesThin = (catalog, modules, workspaceRoot, reporter) => runOrdered(catalog, modules, workspaceRoot, "install", false, reporter);
+export const uninstallModulesThin = (catalog, modules, workspaceRoot, reporter) => runOrdered(catalog, modules, workspaceRoot, "uninstall", true, reporter);
+export async function stopModulesThin(catalog, modules, workspaceRoot, reporter) {
+    const results = [];
+    const skipped = [];
+    const modulesInOrder = ordered(modules, true);
+    for (const [index, module] of modulesInOrder.entries()) {
+        reportProgress(reporter, {
+            command: "stop",
+            phase: "status",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: `${module.moduleRef}`,
+        });
+        const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
+        results.push(status);
+        if (!succeeded(status.result))
+            return { phase: "stop", results, completed: false, skipped };
+        const observed = moduleStatusObservationSchema.parse(status.result.data);
+        if (observed.runtimeStatus === "STOPPED" ||
+            observed.runtimeStatus === "NOT_APPLICABLE") {
+            skipped.push({
+                moduleRef: module.moduleRef,
+                reason: observed.runtimeStatus,
+            });
+            reportProgress(reporter, {
+                command: "stop",
+                phase: "stop",
+                current: index + 1,
+                total: modulesInOrder.length,
+                moduleRef: module.moduleRef,
+                status: "SKIPPED",
+                message: `${module.moduleRef}`,
+            });
+            continue;
+        }
+        const stopped = await dispatchModuleCommand(catalog, module, "stop", context(workspaceRoot));
+        results.push(stopped);
+        reportProgress(reporter, {
+            command: "stop",
+            phase: "stop",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(stopped.result) ? "SUCCEEDED" : "FAILED",
+            message: `${module.moduleRef}`,
+        });
+        if (!succeeded(stopped.result))
+            return { phase: "stop", results, completed: false, skipped };
+    }
+    return { phase: "stop", results, completed: true, skipped };
+}
+export async function setupModulesThin(catalog, modules, workspaceRoot, target, reporter) {
     const results = [];
     let matched = target === undefined;
     let completed = true;
-    for (const module of ordered(modules)) {
+    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",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: module.moduleRef,
+        });
         matched = true;
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
         if (!succeeded(status.result)) {
@@ -54,10 +177,33 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target)
             continue;
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
-        if (observed.setupStatus === "READY" && target?.input === undefined)
+        if (observed.setupStatus === "READY" && target?.input === undefined) {
+            reportProgress(reporter, {
+                command: "setup",
+                phase: "setup",
+                current: index + 1,
+                total: modulesInOrder.length,
+                moduleRef: module.moduleRef,
+                status: "SKIPPED",
+                message: module.moduleRef,
+            });
             continue;
+        }
         const setup = await dispatchModuleCommand(catalog, module, "setup", context(workspaceRoot, target?.input));
         results.push(setup);
+        reportProgress(reporter, {
+            command: "setup",
+            phase: "setup",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(setup.result)
+                ? "SUCCEEDED"
+                : setup.result.status === "ACTION_REQUIRED"
+                    ? "SKIPPED"
+                    : "FAILED",
+            message: module.moduleRef,
+        });
         if (!succeeded(setup.result)) {
             completed = false;
             if (target !== undefined)
@@ -68,34 +214,71 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target)
         throw new PlatformError("INVALID_REQUEST", `setup target module ${target?.moduleRef ?? ""} was not discovered`);
     return { phase: "setup", results, completed };
 }
-export async function startModulesThin(catalog, modules, workspaceRoot) {
+export async function startModulesThin(catalog, modules, workspaceRoot, reporter) {
     const results = [];
     const modulesInOrder = ordered(modules);
-    for (const module of modulesInOrder) {
+    const blockers = [];
+    const runtimeByRef = new Map();
+    for (const [index, module] of modulesInOrder.entries()) {
+        reportProgress(reporter, {
+            command: "start",
+            phase: "status",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: "STARTED",
+            message: `${module.moduleRef}`,
+        });
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
-        if (!succeeded(status.result))
-            return {
-                phase: "start",
-                results: [...results, status],
-                completed: false,
-            };
+        results.push(status);
+        if (!succeeded(status.result)) {
+            blockers.push({ moduleRef: module.moduleRef, setupStatus: "FAILED" });
+            continue;
+        }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
+        runtimeByRef.set(module.moduleRef, observed.runtimeStatus);
         if (observed.setupStatus !== "READY")
-            return {
-                phase: "start",
-                results: [...results, status],
-                completed: false,
-                blockedBy: {
-                    moduleRef: module.moduleRef,
-                    setupStatus: observed.setupStatus,
-                },
-            };
+            blockers.push({
+                moduleRef: module.moduleRef,
+                setupStatus: observed.setupStatus,
+            });
     }
-    for (const module of modulesInOrder) {
+    if (results.some((item) => !succeeded(item.result)) || blockers.length > 0)
+        return {
+            phase: "start",
+            results,
+            completed: false,
+            ...(blockers[0] ? { blockedBy: blockers[0], blockers } : {}),
+        };
+    const skipped = [];
+    for (const [index, module] of modulesInOrder.entries()) {
+        const runtimeStatus = runtimeByRef.get(module.moduleRef);
+        if (runtimeStatus === "RUNNING" || runtimeStatus === "NOT_APPLICABLE") {
+            skipped.push({ moduleRef: module.moduleRef, reason: runtimeStatus });
+            reportProgress(reporter, {
+                command: "start",
+                phase: "start",
+                current: index + 1,
+                total: modulesInOrder.length,
+                moduleRef: module.moduleRef,
+                status: "SKIPPED",
+                message: `${module.moduleRef}`,
+            });
+            continue;
+        }
         const started = await dispatchModuleCommand(catalog, module, "start", context(workspaceRoot));
         results.push(started);
+        reportProgress(reporter, {
+            command: "start",
+            phase: "start",
+            current: index + 1,
+            total: modulesInOrder.length,
+            moduleRef: module.moduleRef,
+            status: succeeded(started.result) ? "SUCCEEDED" : "FAILED",
+            message: `${module.moduleRef}`,
+        });
         if (!succeeded(started.result))
-            return { phase: "start", results, completed: false };
+            return { phase: "start", results, completed: false, skipped };
     }
-    return { phase: "start", results, completed: true };
+    return { phase: "start", results, completed: true, skipped };
 }

package/dist/src/progress.d.ts

@@ -0,0 +1,12 @@
+export type PlatformProgressStatus = "STARTED" | "SUCCEEDED" | "ACTION_REQUIRED" | "FAILED" | "SKIPPED";
+export interface PlatformProgressEvent {
+    command: string;
+    phase: string;
+    current?: number;
+    total?: number;
+    moduleRef?: string;
+    status: PlatformProgressStatus;
+    message: string;
+}
+export type PlatformProgressReporter = (event: PlatformProgressEvent) => void;
+export declare const reportProgress: (reporter: PlatformProgressReporter | undefined, event: PlatformProgressEvent) => void | undefined;

package/dist/src/progress.js

@@ -0,0 +1 @@
+export const reportProgress = (reporter, event) => reporter?.(event);

package/dist/src/terminal.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformProgressReporter } from "./progress.ts";
+export declare function createTerminalProgressReporter(stream?: NodeJS.WriteStream): PlatformProgressReporter;

package/dist/src/terminal.js

@@ -0,0 +1,44 @@
+import { clearLine, cursorTo } from "node:readline";
+const colors = {
+    green: "\u001b[32m",
+    red: "\u001b[31m",
+    yellow: "\u001b[33m",
+    dim: "\u001b[2m",
+    reset: "\u001b[0m",
+};
+function progressLine(event, color) {
+    const prefix = event.current && event.total
+        ? `[${String(event.current).padStart(2, "0")}/${event.total}] `
+        : "";
+    const suffix = event.status === "SUCCEEDED"
+        ? "完成"
+        : event.status === "FAILED"
+            ? "失败"
+            : event.status === "SKIPPED"
+                ? "跳过"
+                : "";
+    if (!color || suffix === "")
+        return `${prefix}${event.message}${suffix ? `… ${suffix}` : "…"}`;
+    const tone = event.status === "SUCCEEDED"
+        ? colors.green
+        : event.status === "FAILED"
+            ? colors.red
+            : colors.yellow;
+    return `${colors.dim}${prefix}${colors.reset}${event.message}… ${tone}${suffix}${colors.reset}`;
+}
+export function createTerminalProgressReporter(stream = process.stderr) {
+    const interactive = stream.isTTY === true;
+    const color = interactive && !("NO_COLOR" in process.env);
+    return (event) => {
+        const line = progressLine(event, color);
+        if (!interactive) {
+            stream.write(`${line}\n`);
+            return;
+        }
+        cursorTo(stream, 0);
+        clearLine(stream, 0);
+        stream.write(line);
+        if (event.status !== "STARTED")
+            stream.write("\n");
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./dist/src/index.js",
     "./cli": "./dist/src/cli.js",
+    "./command": "./dist/src/command.js",
     "./deployment/adapter": "./dist/deployment/adapter.js",
     "./deployment/descriptor": "./dist/deployment/descriptor.js"
   },
@@ -23,11 +24,11 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.7"
+    "@tomflow/proflow-module-contract": "^0.1.9"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.5",
-    "@tomflow/proflow-module-template": "^0.1.5"
+    "@tomflow/proflow-deployment-conformance": "^0.1.7",
+    "@tomflow/proflow-module-template": "^0.1.7"
   },
   "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.21",
+	"moduleVersion": "0.1.23",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",