@tomflow/proflow-platform-cli 0.1.38 → 0.1.39

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.39
+
+### Patch Changes
+
+- Add professional setup orchestration, Provider FAST/THINK input, recoverable managed Dev Tunnel provisioning, Browser installation guidance, and precise status diagnostics.
+
 ## 0.1.38
 
 ### Patch Changes

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

package/dist/src/cli.d.ts

@@ -2,6 +2,7 @@
 import { type PackageCommandRunner } from "./install/package-manager.ts";
 import { type PlatformProgressReporter } from "./progress.ts";
 import { type NpmCommandRunner } from "./registry/index.ts";
+import { type SetupInteraction } from "./setup/interaction.ts";
 declare const COMMANDS: readonly ["install", "uninstall", "status", "setup", "docs", "start", "stop"];
 type Command = (typeof COMMANDS)[number];
 export type CliStatus = "SUCCEEDED" | "ACTION_REQUIRED" | "BLOCKED" | "FAILED";
@@ -23,6 +24,7 @@ export interface CliRuntimeOptions {
     packageRunner?: PackageCommandRunner;
     executableAvailable?: (command: string) => boolean;
     onProgress?: PlatformProgressReporter;
+    setupInteraction?: SetupInteraction;
 }
 export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<CliOutcome>;
 export interface HumanRenderOptions {

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve } from "node:path";
-import { moduleDocsDataSchema, moduleSetupPlanDataSchema, moduleStatusObservationSchema, } from "@tomflow/proflow-module-contract";
+import { moduleDocsDataSchema, moduleSetupPlanDataSchema, moduleStatusObservationSchema, readModuleSharedFacts, } 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";
@@ -12,6 +12,7 @@ import { installModulesThin, observeDocs, observeStatuses, setupModulesThin, sta
 import { ensureWorkspaceMetadata } from "./persistence/workspace-metadata.js";
 import { reportProgress } from "./progress.js";
 import { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, } from "./registry/index.js";
+import { createClackSetupInteraction, } from "./setup/interaction.js";
 import { createTerminalProgressReporter } from "./terminal.js";
 const COMMANDS = [
     "install",
@@ -70,8 +71,8 @@ function parseArgs(argv) {
     if (!COMMANDS.includes(raw))
         throw new PlatformError("INVALID_REQUEST", `unknown command ${raw}`);
     const command = raw;
-    if (moduleRef !== undefined && command !== "setup")
-        throw new PlatformError("INVALID_REQUEST", "--module is only valid with setup");
+    if (moduleRef !== undefined && command !== "setup" && command !== "docs")
+        throw new PlatformError("INVALID_REQUEST", "--module is only valid with setup or docs");
     return {
         command,
         ...(workspace === undefined ? {} : { workspace }),
@@ -171,7 +172,7 @@ async function handleStatus(root, runtime) {
     });
     return outcome("status", "SUCCEEDED", root, { modules: output });
 }
-async function handleDocs(root, runtime) {
+async function handleDocs(root, parsed, runtime) {
     reportProgress(runtime.onProgress, {
         command: "docs",
         phase: "docs",
@@ -179,7 +180,28 @@ async function handleDocs(root, runtime) {
         message: "正在整理模块文档",
     });
     const { catalog, modules: resolvedModules } = await buildContext(root);
-    const docs = await observeDocs(catalog, resolvedModules, root);
+    const selectedModules = parsed.moduleRef === undefined
+        ? resolvedModules
+        : resolvedModules.filter((item) => item.moduleRef === parsed.moduleRef);
+    if (parsed.moduleRef !== undefined && selectedModules.length === 0)
+        throw new PlatformError("INVALID_REQUEST", `docs target module ${parsed.moduleRef} was not discovered`);
+    if (parsed.moduleRef === undefined) {
+        reportProgress(runtime.onProgress, {
+            command: "docs",
+            phase: "docs",
+            status: "SUCCEEDED",
+            message: `已整理 ${selectedModules.length} 个模块的文档索引`,
+        });
+        return outcome("docs", "SUCCEEDED", root, {
+            indexOnly: true,
+            modules: selectedModules.map((module) => ({
+                moduleRef: module.moduleRef,
+                version: module.moduleVersion,
+            })),
+            errors: [],
+        });
+    }
+    const docs = await observeDocs(catalog, selectedModules, root);
     const byRef = new Map(resolvedModules.map((module) => [module.moduleRef, module]));
     const modules = [];
     const errors = [];
@@ -270,7 +292,7 @@ async function handleInstall(root, runtime) {
             kind: "detail",
             status: "STARTED",
             total,
-            message: `Registry 返回 ${total} 个候选模块，正在核验`,
+            message: `Registry 返回 ${total} 个候选模块，正在做安装前核验`,
         }),
         onPackageChecked: ({ current, total, packageName }) => reportProgress(runtime.onProgress, {
             command: "install",
@@ -280,7 +302,7 @@ async function handleInstall(root, runtime) {
             current,
             total,
             moduleRef: packageName.replace(PRO_FLOW_PACKAGE_PREFIX, ""),
-            message: `核验 ${packageName.replace(PRO_FLOW_PACKAGE_PREFIX, "")}`,
+            message: `安装前核验 ${packageName.replace(PRO_FLOW_PACKAGE_PREFIX, "")}`,
         }),
         ...(runtime.registryRunner === undefined
             ? {}
@@ -335,7 +357,7 @@ async function handleInstall(root, runtime) {
         phase: "validation",
         kind: "phase",
         status: "SUCCEEDED",
-        message: `已验证 ${modules.length} 个已安装模块`,
+        message: `安装完成，${modules.length} 个模块已从本地安装物验证`,
     });
     const moduleInstall = await installModulesThin(catalog, modules, root, runtime.onProgress);
     return outcome("install", batchStatus(moduleInstall), root, {
@@ -428,17 +450,78 @@ async function handleSetup(root, parsed, runtime) {
         message: "正在分析模块配置",
     });
     const { catalog, modules } = await buildContext(root);
-    const target = parsed.moduleRef === undefined
+    const interaction = runtime.setupInteraction;
+    const inputByModule = new Map();
+    const approvedSteps = new Set();
+    const confirmSetupStep = interaction?.confirmStep
+        ? async (moduleRef) => {
+            if (approvedSteps.has(moduleRef))
+                return;
+            if (!(await interaction.confirmStep?.(moduleRef)))
+                throw new PlatformError("INVALID_REQUEST", "配置已取消");
+            approvedSteps.add(moduleRef);
+        }
+        : undefined;
+    if (interaction)
+        interaction.begin();
+    let target = parsed.moduleRef === undefined
         ? undefined
         : { moduleRef: parsed.moduleRef };
-    const result = await setupModulesThin(catalog, modules, root, target, undefined);
+    let result = await setupModulesThin(catalog, modules, root, target, runtime.onProgress, confirmSetupStep);
+    for (let attempt = 0; interaction && !result.completed && attempt < 8; attempt += 1) {
+        const actionable = [...result.results]
+            .reverse()
+            .find((item) => item.result.status === "ACTION_REQUIRED");
+        const action = actionable?.result.actionRequired;
+        if (!actionable || !action)
+            break;
+        let modelIds;
+        if (actionable.moduleRef === "model-runtime") {
+            const facts = await readModuleSharedFacts({ workspaceRoot: root }, "model-provider-api");
+            const inventory = facts?.models;
+            if (Array.isArray(inventory))
+                modelIds = inventory.flatMap((item) => {
+                    if (typeof item === "string")
+                        return [item];
+                    if (isRecord(item) && typeof item.id === "string")
+                        return [item.id];
+                    return [];
+                });
+        }
+        const collected = await interaction.collect({
+            moduleRef: actionable.moduleRef,
+            action: action.action,
+            description: action.description,
+            ...(modelIds?.length ? { modelIds } : {}),
+        });
+        if (!collected)
+            break;
+        const previous = inputByModule.get(actionable.moduleRef) ?? {};
+        const input = { ...previous, ...collected };
+        inputByModule.set(actionable.moduleRef, input);
+        const targeted = await setupModulesThin(catalog, modules, root, { moduleRef: actionable.moduleRef, input }, runtime.onProgress, confirmSetupStep);
+        if (parsed.moduleRef !== undefined || !targeted.completed) {
+            result = targeted;
+            target = { moduleRef: actionable.moduleRef, input };
+            continue;
+        }
+        target = undefined;
+        result = await setupModulesThin(catalog, modules, root, undefined, runtime.onProgress, confirmSetupStep);
+    }
+    if (interaction && result.completed)
+        interaction.finish("配置已完成");
     reportProgress(runtime.onProgress, {
         command: "setup",
         phase: "setup",
         status: result.completed ? "SUCCEEDED" : "ACTION_REQUIRED",
         message: result.completed ? "模块配置已就绪" : "配置清单已生成",
     });
-    return outcome("setup", batchStatus(result), root, result);
+    return outcome("setup", batchStatus(result), root, {
+        ...result,
+        ...(parsed.moduleRef === undefined
+            ? {}
+            : { targetModuleRef: parsed.moduleRef }),
+    });
 }
 async function handleStart(root, runtime) {
     const { catalog, modules } = await buildContext(root);
@@ -485,7 +568,7 @@ export async function runCli(argv, runtime = {}) {
             case "setup":
                 return await handleSetup(root, parsed, runtime);
             case "docs":
-                return await handleDocs(root, runtime);
+                return await handleDocs(root, parsed, runtime);
             case "start":
                 return await handleStart(root, runtime);
             case "stop":
@@ -658,6 +741,18 @@ function renderTerminalMarkdown(source, theme) {
 function renderDocs(data, theme) {
     if (!isRecord(data) || !Array.isArray(data.modules))
         return "未发现模块文档。";
+    if (data.indexOnly === true) {
+        const modules = data.modules.filter(isRecord);
+        return [
+            theme.title("ProFlow 帮助"),
+            "",
+            "先运行 platform status 查看当前状态；需要某项详细说明时使用：",
+            `  ${theme.command("platform docs --module <模块名>")}`,
+            "",
+            theme.section(`可用文档（${modules.length}）`),
+            ...modules.map((item) => `  ${String(item.moduleRef).padEnd(34)} ${theme.muted(String(item.version ?? ""))}`),
+        ].join("\n");
+    }
     const lines = [theme.title("ProFlow 模块文档")];
     for (const raw of data.modules)
         if (isRecord(raw))
@@ -668,36 +763,13 @@ function renderDocs(data, theme) {
             .map((item) => `- ${String(item.moduleRef)}：${String(item.reason)}`));
     return lines.join("\n");
 }
-const setupCommands = {
-    "dev-tunnel": {
-        ai: "platform setup --module dev-tunnel",
-        inputs: "无",
-    },
-    "model-provider-api": {
-        ai: "platform setup --module model-provider-api",
-        inputs: "无（等待 Deployment resolver 提供 endpoint）",
-    },
-    "model-runtime": {
-        ai: "platform setup --module model-runtime",
-        inputs: "无（仅等价合格候选歧义时选择）",
-    },
-    "execution-browser-extension": {
-        ai: "platform setup --module execution-browser-extension",
-        inputs: "无",
-    },
-    "agent-controller-dev": {
-        ai: "platform setup --module agent-controller-dev",
-        inputs: "无",
-    },
-    "agent-product": {
-        ai: "platform setup --module agent-product",
-        inputs: "无",
-    },
-    "agent-test-ops": {
-        ai: "platform setup --module agent-test-ops",
-        inputs: "无",
-    },
+const setupModuleLabels = {
+    "execution-browser-extension": "浏览器扩展",
+    "dev-tunnel": "远程连接",
+    "model-provider-api": "模型服务",
+    "model-runtime": "FAST / THINK 模型",
 };
+const setupModuleLabel = (moduleRef) => setupModuleLabels[moduleRef] ?? moduleRef;
 function renderSetup(data, theme) {
     if (!isRecord(data) || !Array.isArray(data.results))
         return "没有需要执行的配置步骤。";
@@ -721,10 +793,14 @@ function renderSetup(data, theme) {
             blocked += 1;
         else
             needsAction += 1;
-        lines.push(`${status === "FAILED" ? theme.failure("✕") : theme.warning("◆")} ${theme.section(moduleRef)}`);
+        lines.push(`${status === "FAILED" ? theme.failure("✕") : theme.warning("◆")} ${theme.section(setupModuleLabel(moduleRef))}`);
         const plan = moduleSetupPlanDataSchema.safeParse(raw.result.data);
         if (plan.success) {
+            const currentStep = plan.data.steps.find((step) => step.state === "BLOCKED") ??
+                plan.data.steps.find((step) => step.state === "TODO");
             for (const [index, step] of plan.data.steps.entries()) {
+                if (step !== currentStep && step.state !== "DONE")
+                    continue;
                 const marker = step.state === "DONE"
                     ? theme.success("✓")
                     : step.state === "BLOCKED"
@@ -736,13 +812,10 @@ function renderSetup(data, theme) {
                 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("、")}`);
                 if (step.humanAction)
                     lines.push(`       人工操作：${step.humanAction}`);
-                lines.push(`       验证：${theme.command(step.verify)}`);
                 lines.push(`       完成：${step.successCondition}`);
                 if (step.blockedReason)
                     lines.push(`       原因：${theme.failure(step.blockedReason)}`);
@@ -753,15 +826,7 @@ function renderSetup(data, theme) {
         lines.push(`  1. ${status === "FAILED" ? "等待上游服务信息" : "完成模块配置"}`);
         const error = raw.result.error;
         if (status !== "FAILED") {
-            const commands = setupCommands[moduleRef] ?? {
-                ai: `platform setup --module ${moduleRef}`,
-                inputs: "按命令提示提供",
-            };
-            lines.push(`  人工执行：${commands.ai}`);
-            lines.push(`  AI 执行：${commands.ai}`);
-            lines.push(`  需要输入：${commands.inputs}`);
-            lines.push("  验证：platform status");
-            lines.push("  完成条件：配置状态变为“已就绪”");
+            lines.push("  请在当前 Platform 向导中完成这一项。完成后会自动验证。");
         }
         else if (isRecord(error)) {
             const code = error.code === undefined ? "FAILED" : String(error.code);
@@ -769,8 +834,7 @@ function renderSetup(data, theme) {
                 ? "Module setup failed."
                 : String(error.message);
             lines.push(`  原因：${code} — ${message}`);
-            lines.push(`  执行：platform setup --module ${moduleRef}`);
-            lines.push("  完成条件：配置状态变为“已就绪”");
+            lines.push("  修复当前问题后重新运行 platform setup。");
         }
         lines.push("");
     }
@@ -784,8 +848,11 @@ function renderSetup(data, theme) {
         blocked += 1;
         lines.push(`${theme.info("◇")} ${theme.section(moduleRef)}`, `  原因：${typeof item.reason === "string" ? item.reason : "等待上游 Module 就绪"}`, `  下一步：${theme.command(typeof item.nextCommand === "string" ? item.nextCommand : `platform setup --module ${moduleRef}`)}`, "");
     }
+    const targetModuleRef = typeof data.targetModuleRef === "string" ? data.targetModuleRef : undefined;
     if (needsAction === 0 && blocked === 0)
-        lines.push("全部模块均已就绪。");
+        lines.push(targetModuleRef
+            ? `${setupModuleLabel(targetModuleRef)}配置已就绪。`
+            : "全部模块均已就绪。");
     lines.push(theme.section("汇总"), `汇总：${theme.success(`${ready} 个已就绪`)}，${theme.warning(`${needsAction} 个需要操作`)}，${blocked > 0 ? theme.failure(`${blocked} 个系统阻塞`) : `${blocked} 个系统阻塞`}`);
     return lines.join("\n").trimEnd();
 }
@@ -808,8 +875,8 @@ function renderHelp(theme, command) {
             description: "自动配置并列出全部剩余步骤",
         },
         docs: {
-            usage: "platform docs [--workspace <路径>]",
-            description: "阅读全部模块能力文档",
+            usage: "platform docs [--workspace <路径>] [--module <模块名>]",
+            description: "查看文档索引，或阅读一个模块的详细文档",
         },
         start: {
             usage: "platform start [--workspace <路径>]",
@@ -974,7 +1041,12 @@ export function renderHumanResult(result, options = {}) {
 if (import.meta.main) {
     const argv = process.argv.slice(2);
     const reporter = createTerminalProgressReporter();
-    const result = await runCli(argv, { onProgress: reporter });
+    const result = await runCli(argv, {
+        onProgress: reporter,
+        ...(process.stdin.isTTY && process.stdout.isTTY
+            ? { setupInteraction: createClackSetupInteraction() }
+            : {}),
+    });
     reporter.close();
     const color = process.stdout.isTTY === true &&
         process.env.NO_COLOR === undefined &&

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

@@ -71,7 +71,7 @@ export async function readWorkspacePackageManagerSelection(workspaceRoot) {
         return { name, source: "declared", declared };
     }
     if (lockManagers.size > 1) {
-        throw new PlatformError("PACKAGE_MANAGER_CONFLICT", `multiple package-manager lockfiles are present: ${[...lockManagers].sort().join(", ")}`);
+        throw new PlatformError("PACKAGE_MANAGER_CONFLICT", `检测到多个包管理器的 lockfile（${[...lockManagers].sort().join(", ")}）。Platform 不会自动删除或替你选择；请先保留现场并明确工作区应使用的唯一包管理器。`);
     }
     const [fromLockfile] = lockManagers;
     if (fromLockfile !== undefined) {

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

@@ -30,5 +30,5 @@ export declare function stopModulesThin(catalog: ModuleCatalog, modules: readonl
 export declare function setupModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, target?: {
     moduleRef: string;
     input?: unknown;
-}, reporter?: PlatformProgressReporter): Promise<ModuleBatchResult>;
+}, reporter?: PlatformProgressReporter, beforeSetup?: (moduleRef: string) => Promise<void>): Promise<ModuleBatchResult>;
 export declare function startModulesThin(catalog: ModuleCatalog, modules: readonly ResolvedModule[], workspaceRoot: string, reporter?: PlatformProgressReporter): Promise<ModuleBatchResult>;

package/dist/src/lifecycle/thin.js

@@ -172,7 +172,7 @@ export async function stopModulesThin(catalog, modules, workspaceRoot, reporter)
     }
     return { phase: "stop", results, completed: true, skipped };
 }
-export async function setupModulesThin(catalog, modules, workspaceRoot, target, reporter) {
+export async function setupModulesThin(catalog, modules, workspaceRoot, target, reporter, beforeSetup) {
     const results = [];
     const skipped = [];
     const blockers = [];
@@ -180,8 +180,40 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
     const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
     if (target !== undefined && !byRef.has(target.moduleRef))
         throw new PlatformError("INVALID_REQUEST", `setup target module ${target.moduleRef} was not discovered`);
-    const selectedRefs = new Set(target === undefined ? graph.order : [target.moduleRef]);
-    const modulesInOrder = graph.order
+    const setupPriority = [
+        "execution-browser-extension",
+        "dev-tunnel",
+        "model-provider-api",
+        "model-runtime",
+    ];
+    const dependenciesByRef = new Map();
+    for (const edge of graph.edges) {
+        const dependencies = dependenciesByRef.get(edge.from) ?? [];
+        dependencies.push(edge.to);
+        dependenciesByRef.set(edge.from, dependencies);
+    }
+    const userOrder = [];
+    const included = new Set();
+    const appendWithDependencies = (moduleRef) => {
+        if (included.has(moduleRef) || !byRef.has(moduleRef))
+            return;
+        for (const dependency of graph.order)
+            if (dependenciesByRef.get(moduleRef)?.includes(dependency))
+                appendWithDependencies(dependency);
+        included.add(moduleRef);
+        userOrder.push(moduleRef);
+    };
+    if (target === undefined) {
+        for (const moduleRef of setupPriority)
+            appendWithDependencies(moduleRef);
+        for (const moduleRef of graph.order)
+            appendWithDependencies(moduleRef);
+    }
+    else {
+        appendWithDependencies(target.moduleRef);
+    }
+    const selectedRefs = new Set(target === undefined ? userOrder : [target.moduleRef]);
+    const modulesInOrder = userOrder
         .filter((moduleRef) => selectedRefs.has(moduleRef))
         .map((moduleRef) => byRef.get(moduleRef))
         .filter((module) => module !== undefined);
@@ -200,9 +232,7 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
         if (!succeeded(status.result)) {
             results.push(status);
             completed = false;
-            if (target?.moduleRef === module.moduleRef)
-                break;
-            continue;
+            break;
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
         if (observed.setupStatus === "READY" && target === undefined) {
@@ -218,6 +248,7 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
             });
             continue;
         }
+        await beforeSetup?.(module.moduleRef);
         const setup = await dispatchModuleCommand(catalog, module, "setup", context(workspaceRoot, target?.input));
         results.push(setup);
         reportProgress(reporter, {
@@ -243,8 +274,7 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
         }
         else {
             const reconciledStatus = moduleStatusObservationSchema.parse(reconciled.result.data);
-            if (reconciledStatus.setupStatus === "BLOCKED" ||
-                reconciledStatus.setupStatus === "FAILED") {
+            if (reconciledStatus.setupStatus !== "READY") {
                 const issue = reconciledStatus.issues?.find((item) => item.scope === "SETUP");
                 blockers.push({
                     moduleRef: module.moduleRef,
@@ -256,8 +286,7 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
                 completed = false;
             }
         }
-        if (target !== undefined &&
-            (!succeeded(setup.result) || blockers.length > 0))
+        if (!succeeded(setup.result) || blockers.length > 0)
             break;
     }
     return {

package/dist/src/setup/interaction.d.ts

@@ -0,0 +1,14 @@
+export type SetupActionRequest = {
+    moduleRef: string;
+    action: string;
+    description: string;
+    modelIds?: readonly string[];
+};
+export interface SetupInteraction {
+    begin(): void;
+    finish(message: string): void;
+    confirmStep?(moduleRef: string): Promise<boolean>;
+    collect(request: SetupActionRequest): Promise<Record<string, unknown> | undefined>;
+}
+export declare function validateProviderBaseUrl(value: string): string | undefined;
+export declare function createClackSetupInteraction(): SetupInteraction;

package/dist/src/setup/interaction.js

@@ -0,0 +1,126 @@
+import { autocomplete, cancel, confirm, intro, isCancel, outro, password, text, } from "@clack/prompts";
+const stepPrompts = {
+    "execution-browser-extension": "下一步将打开 Chrome，并引导你加载浏览器扩展。按 Enter 继续。",
+    "dev-tunnel": "下一步将检查远程连接；如需登录，会打开 GitHub 授权。按 Enter 继续。",
+    "model-provider-api": "下一步配置 OpenAI-compatible 模型服务地址。按 Enter 继续。",
+    "model-runtime": "下一步从真实模型列表选择 FAST 与 THINK。按 Enter 继续。",
+};
+function cancelled(value) {
+    if (!isCancel(value))
+        return false;
+    cancel("已取消配置，没有继续执行后续步骤。");
+    return true;
+}
+function privateIpv4(hostname) {
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part)))
+        return false;
+    const [first = -1, second = -1] = parts;
+    return (first === 10 ||
+        first === 127 ||
+        (first === 192 && second === 168) ||
+        (first === 172 && second >= 16 && second <= 31));
+}
+export function validateProviderBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return "请输入包含 http:// 或 https:// 的完整 API Base URL。";
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return "只支持 HTTP(S) OpenAI-compatible 服务。";
+    if (/\/chat\/completions\/?$/i.test(url.pathname))
+        return "请填写服务 Base URL，不要包含 /chat/completions。";
+    const local = url.hostname === "localhost" ||
+        url.hostname.endsWith(".local") ||
+        privateIpv4(url.hostname);
+    if (!local && url.protocol !== "https:")
+        return "公网模型服务必须使用 https://。";
+    return undefined;
+}
+async function providerEndpoint() {
+    const value = await text({
+        message: "OpenAI-compatible 服务 Base URL",
+        placeholder: "例如 https://api.deepseek.com 或 http://192.168.0.108:8080/v1",
+        validate: (candidate) => candidate === undefined || candidate.trim().length === 0
+            ? "API Base URL 不能为空。"
+            : validateProviderBaseUrl(candidate),
+    });
+    if (cancelled(value))
+        return undefined;
+    const providerBaseUrl = String(value).trim().replace(/\/$/, "");
+    const approved = await confirm({
+        message: `使用 ${providerBaseUrl} 连接整个模型服务？`,
+        initialValue: true,
+    });
+    if (cancelled(approved) || approved !== true)
+        return undefined;
+    return { providerBaseUrl };
+}
+async function providerCredential() {
+    const value = await password({
+        message: "模型服务 API Key（输入不会显示）",
+        mask: "•",
+        validate: (candidate) => candidate === undefined || candidate.trim().length === 0
+            ? "API Key 不能为空。"
+            : undefined,
+    });
+    if (cancelled(value))
+        return undefined;
+    return { providerCredential: String(value) };
+}
+async function modelRoles(modelIds) {
+    const options = modelIds.map((id) => ({ value: id, label: id }));
+    const fastModel = await autocomplete({
+        message: "选择 FAST 模型（快速、低延迟）",
+        placeholder: "输入关键字搜索模型",
+        options,
+    });
+    if (cancelled(fastModel))
+        return undefined;
+    const reasonModel = await autocomplete({
+        message: "选择 THINK 模型（复杂分析与推理）",
+        placeholder: "输入关键字搜索模型",
+        options,
+    });
+    if (cancelled(reasonModel))
+        return undefined;
+    const approved = await confirm({
+        message: `确认 FAST=${String(fastModel)}，THINK=${String(reasonModel)}？`,
+        initialValue: true,
+    });
+    if (cancelled(approved) || approved !== true)
+        return undefined;
+    return { fastModel: String(fastModel), reasonModel: String(reasonModel) };
+}
+export function createClackSetupInteraction() {
+    return {
+        begin() {
+            intro("ProFlow 配置向导");
+        },
+        finish(message) {
+            outro(message);
+        },
+        async confirmStep(moduleRef) {
+            const message = stepPrompts[moduleRef];
+            if (!message)
+                return true;
+            const approved = await confirm({ message, initialValue: true });
+            return !cancelled(approved) && approved === true;
+        },
+        async collect(request) {
+            if (request.action === "provide-provider-endpoint") {
+                return providerEndpoint();
+            }
+            if (request.action === "provide-provider-credential") {
+                return providerCredential();
+            }
+            if (request.action.startsWith("select-") && request.modelIds?.length) {
+                return modelRoles(request.modelIds);
+            }
+            return undefined;
+        },
+    };
+}

package/package.json

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

package/proflow.module.json

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