@tomflow/proflow-platform-cli 0.1.37 → 0.1.39

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- Retire the obsolete Carrier package and Browser standalone management CLI, make Platform setup/status preserve owner and dependency semantics, and enforce read-only status observation across the final Real-3 deployment closeout.
+
 ## 0.1.37
 
 ### 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.37";
+            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.37";
+            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.37";
+            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.37";
+            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.37";
+            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.37";
+            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.37";
+            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.37";
+    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.37",
+    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 }),
@@ -158,6 +159,9 @@ async function handleStatus(root, runtime) {
             ...(parsed.data.issues === undefined
                 ? {}
                 : { issues: parsed.data.issues }),
+            ...(item.externalAvailabilityClaim === undefined
+                ? {}
+                : { externalAvailabilityClaim: item.externalAvailabilityClaim }),
         };
     });
     reportProgress(runtime.onProgress, {
@@ -168,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",
@@ -176,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 = [];
@@ -267,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",
@@ -277,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
             ? {}
@@ -332,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, {
@@ -425,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);
@@ -482,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":
@@ -558,9 +644,17 @@ function renderStatus(data, theme) {
         NOT_APPLICABLE: "无独立进程",
     };
     const modules = data.modules.filter(isRecord);
+    const productOrder = new Map([
+        ["execution-browser-extension", 0],
+        ["dev-tunnel", 1],
+        ["model-provider-api", 2],
+    ]);
+    const orderedProblems = (entries) => [...entries].sort((a, b) => (productOrder.get(String(a.moduleRef)) ?? 100) -
+        (productOrder.get(String(b.moduleRef)) ?? 100));
     const failedModules = modules.filter((item) => item.setupStatus === "FAILED" || item.runtimeStatus === "FAILED");
-    const actionModules = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED" && item.runtimeStatus !== "FAILED");
-    const blockedModules = modules.filter((item) => item.setupStatus === "BLOCKED" && item.runtimeStatus !== "FAILED");
+    const actionModules = orderedProblems(modules.filter((item) => item.setupStatus === "ACTION_REQUIRED" &&
+        item.runtimeStatus !== "FAILED"));
+    const blockedModules = orderedProblems(modules.filter((item) => item.setupStatus === "BLOCKED" && item.runtimeStatus !== "FAILED"));
     const running = modules.filter((item) => item.setupStatus === "READY" && item.runtimeStatus === "RUNNING");
     const healthy = modules.filter((item) => item.setupStatus === "READY" &&
         item.runtimeStatus !== "RUNNING" &&
@@ -574,8 +668,11 @@ function renderStatus(data, theme) {
             const moduleRef = String(raw.moduleRef);
             const setupStatus = String(raw.setupStatus);
             const runtimeStatus = String(raw.runtimeStatus);
+            const runtimeLabel = raw.externalAvailabilityClaim === "AVAILABLE"
+                ? "外部资源可用"
+                : (runtimeLabels[runtimeStatus] ?? "未知");
             lines.push(`${tone(icon)} ${theme.section(moduleRef)}  ${theme.muted(String(raw.version))}`);
-            lines.push(`  ${tone(setupLabels[setupStatus] ?? "未知")} · ${runtimeLabels[runtimeStatus] ?? "未知"}`);
+            lines.push(`  ${tone(setupLabels[setupStatus] ?? "未知")} · ${runtimeLabel}`);
             const issues = Array.isArray(raw.issues)
                 ? raw.issues.filter(isRecord)
                 : [];
@@ -584,7 +681,8 @@ function renderStatus(data, theme) {
                 if (Array.isArray(issue.relatedModuleRefs) &&
                     issue.relatedModuleRefs.length > 0)
                     lines.push(`  依赖：${issue.relatedModuleRefs.map(String).join("、")}`);
-                lines.push(`  下一步：${theme.command(String(issue.nextCommand))}`);
+                if (setupStatus !== "BLOCKED")
+                    lines.push(`  下一步：${theme.command(String(issue.nextCommand))}`);
             }
             lines.push("");
         }
@@ -597,7 +695,9 @@ function renderStatus(data, theme) {
             return;
         lines.push(theme.section(title), "");
         for (const item of entries) {
-            const runtime = runtimeLabels[String(item.runtimeStatus)] ?? "未知";
+            const runtime = item.externalAvailabilityClaim === "AVAILABLE"
+                ? "外部资源可用"
+                : (runtimeLabels[String(item.runtimeStatus)] ?? "未知");
             lines.push(`${theme.success(symbol)} ${String(item.moduleRef).padEnd(32)} ${theme.muted(String(item.version).padEnd(9))} ${runtime}`);
         }
         lines.push("");
@@ -608,7 +708,7 @@ function renderStatus(data, theme) {
     const action = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED" && item.runtimeStatus !== "FAILED").length;
     const failed = failedModules.length;
     const blocked = modules.filter((item) => item.setupStatus === "BLOCKED" && item.runtimeStatus !== "FAILED").length;
-    lines.push(theme.section("汇总"), `${theme.success(`${ready} 已就绪`)} · ${theme.warning(`${action} 需要操作`)} · ${theme.info(`${blocked} 等待依赖`)} · ${failed > 0 ? theme.failure(`${failed} 失败`) : `${failed} 失败`}`);
+    lines.push(theme.section("汇总"), `${theme.success(`${ready} 配置已完成`)} · ${theme.warning(`${action} 根阻塞`)} · ${theme.info(`${blocked} 下游等待`)} · ${failed > 0 ? theme.failure(`${failed} 失败`) : `${failed} 失败`} · ${running.length} 个真实进程运行中`, `PLATFORM_READY=${action === 0 && blocked === 0 && failed === 0 ? "YES" : "NO"}`);
     return lines.join("\n");
 }
 function renderTerminalMarkdown(source, theme) {
@@ -641,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))
@@ -651,40 +763,13 @@ function renderDocs(data, theme) {
             .map((item) => `- ${String(item.moduleRef)}：${String(item.reason)}`));
     return lines.join("\n");
 }
-const setupCommands = {
-    "chatgpt-carrier": {
-        ai: "pnpm exec -- proflow-chatgpt-carrier setup",
-        inputs: "无",
-    },
-    "dev-tunnel": {
-        ai: "pnpm exec -- proflow-dev-tunnel setup",
-        inputs: "无",
-    },
-    "model-provider-api": {
-        ai: "pnpm exec -- proflow-model-provider-api setup",
-        inputs: "无（等待 Deployment resolver 提供 endpoint）",
-    },
-    "model-runtime": {
-        ai: "pnpm exec -- proflow-model-runtime setup",
-        inputs: "无（仅等价合格候选歧义时选择）",
-    },
-    "execution-browser-extension": {
-        ai: "pnpm exec -- proflow-execution-browser-extension setup",
-        inputs: "无",
-    },
-    "agent-controller-dev": {
-        ai: "pnpm exec -- proflow-agent-controller-dev setup",
-        inputs: "无",
-    },
-    "agent-product": {
-        ai: "pnpm exec -- proflow-agent-product setup",
-        inputs: "无",
-    },
-    "agent-test-ops": {
-        ai: "pnpm exec -- proflow-agent-test-ops setup",
-        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 "没有需要执行的配置步骤。";
@@ -708,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"
@@ -723,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)}`);
@@ -740,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: `proflow-${moduleRef} setup`,
-                inputs: "按命令提示提供",
-            };
-            lines.push(`  人工执行：pnpm exec -- proflow-${moduleRef} setup`);
-            lines.push(`  AI 执行：${commands.ai}`);
-            lines.push(`  需要输入：${commands.inputs}`);
-            lines.push(`  验证：proflow-${moduleRef} verify`);
-            lines.push("  完成条件：配置状态变为“已就绪”");
+            lines.push("  请在当前 Platform 向导中完成这一项。完成后会自动验证。");
         }
         else if (isRecord(error)) {
             const code = error.code === undefined ? "FAILED" : String(error.code);
@@ -756,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("");
     }
@@ -771,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();
 }
@@ -795,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 <路径>]",
@@ -839,17 +919,17 @@ function renderHelp(theme, command) {
         theme.section("推荐流程"),
         `  ${theme.command("install → status → docs → setup → start → status → stop")}`,
         "",
-        theme.section("人工配置示例"),
-        `  人工：${theme.command("pnpm exec -- proflow-chatgpt-carrier setup")}`,
-        `  AI：  ${theme.command("pnpm exec -- proflow-chatgpt-carrier setup")}`,
+        theme.section("配置入口"),
+        `  ${theme.command("platform setup")}`,
         "",
         theme.section("状态图例"),
         `  ${theme.success("已就绪")}    配置与验证完成`,
         `  ${theme.warning("需要操作")}  需要执行 setup 步骤`,
         `  ${theme.info("等待依赖")}  等待上游 Module 或外部服务`,
         `  ${theme.failure("失败")}      已确认配置或运行故障`,
-        "  运行中    服务进程正在运行",
-        "  无独立进程 该模块无需启动",
+        "  运行中      服务进程正在运行",
+        "  外部资源可用 Chrome 等外部资源已通过真实探测",
+        "  无独立进程  该模块无需启动",
         "",
         theme.section("遇到问题"),
         `  先运行 ${theme.command("platform status")}；配置问题运行 ${theme.command("platform setup")}。`,
@@ -866,24 +946,35 @@ export function renderHumanResult(result, options = {}) {
             ? result.data.blockers.filter(isRecord)
             : [];
         if (blockers.length > 0) {
+            const productOrder = new Map([
+                ["execution-browser-extension", 0],
+                ["dev-tunnel", 1],
+                ["model-provider-api", 2],
+            ]);
             const groups = [
                 { status: "FAILED", title: "失败", icon: "✕", tone: theme.failure },
                 {
                     status: "ACTION_REQUIRED",
-                    title: "需要操作",
+                    title: "当前根阻塞",
                     icon: "◆",
                     tone: theme.warning,
                 },
-                { status: "BLOCKED", title: "等待依赖", icon: "◇", tone: theme.info },
+                { status: "BLOCKED", title: "下游等待", icon: "◇", tone: theme.info },
             ];
             const lines = [theme.failure("平台未启动：存在未就绪模块"), ""];
             for (const group of groups) {
-                const entries = blockers.filter((item) => item.setupStatus === group.status);
+                const entries = blockers
+                    .filter((item) => item.setupStatus === group.status)
+                    .sort((a, b) => (productOrder.get(String(a.moduleRef)) ?? 100) -
+                    (productOrder.get(String(b.moduleRef)) ?? 100));
                 if (entries.length === 0)
                     continue;
                 lines.push(theme.section(group.title));
-                for (const item of entries)
-                    lines.push(`${group.tone(group.icon)} ${theme.section(String(item.moduleRef))}`, `  原因：${typeof item.reason === "string" ? item.reason : "模块尚未就绪"}`, `  下一步：${theme.command(typeof item.nextCommand === "string" ? item.nextCommand : `platform setup --module ${String(item.moduleRef)}`)}`);
+                for (const item of entries) {
+                    lines.push(`${group.tone(group.icon)} ${theme.section(String(item.moduleRef))}`, `  原因：${typeof item.reason === "string" ? item.reason : "模块尚未就绪"}`);
+                    if (group.status !== "BLOCKED")
+                        lines.push(`  下一步：${theme.command(typeof item.nextCommand === "string" ? item.nextCommand : `platform setup --module ${String(item.moduleRef)}`)}`);
+                }
                 lines.push("");
             }
             const readyCount = Array.isArray(result.data.results)
@@ -891,7 +982,7 @@ export function renderHumanResult(result, options = {}) {
                     isRecord(item.result) &&
                     item.result.status === "SUCCEEDED").length - blockers.length
                 : 0;
-            lines.push(theme.section("检查汇总"), `${Math.max(0, readyCount)} 已就绪 · ${blockers.length} 未就绪 · 0 个模块已启动`, `处理方式：${theme.command(`platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`)}`);
+            lines.push(theme.section("检查汇总"), `${Math.max(0, readyCount)} 配置已完成 · ${blockers.filter((item) => item.setupStatus === "ACTION_REQUIRED").length} 根阻塞 · ${blockers.filter((item) => item.setupStatus === "BLOCKED").length} 下游等待 · 0 个真实进程启动`, "PLATFORM_READY=NO", `处理方式：${theme.command(`platform setup${result.workspaceRoot ? ` --workspace "${result.workspaceRoot}"` : ""}`)}`);
             return lines.join("\n");
         }
     }
@@ -950,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/deployment-order.d.ts

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

package/dist/src/deployment-order.js

@@ -22,7 +22,6 @@ export const FROZEN_DEPLOYMENT_INSTALL_ORDER = [
     "module-template",
     "deployment-conformance",
     "platform-cli",
-    "chatgpt-carrier",
 ];
 const installRank = new Map(FROZEN_DEPLOYMENT_INSTALL_ORDER.map((moduleRef, index) => [moduleRef, index]));
 export function orderModuleRefsForInstall(moduleRefs) {

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/dispatch.d.ts

@@ -6,5 +6,6 @@ export interface ModuleDispatchResult {
     command: ModuleManagementCommand;
     result: ModuleOperationResult;
     observedEffects: string[];
+    externalAvailabilityClaim?: "AVAILABLE" | "UNAVAILABLE";
 }
 export declare function dispatchModuleCommand(catalog: ModuleCatalog, module: ResolvedModule, command: ModuleManagementCommand, context: ModuleCommandContext): Promise<ModuleDispatchResult>;

package/dist/src/lifecycle/dispatch.js

@@ -24,6 +24,10 @@ function normalizeInvocation(raw) {
         observedEffects: Array.isArray(raw.observedEffects)
             ? raw.observedEffects.filter((item) => typeof item === "string")
             : [],
+        ...(raw.externalAvailabilityClaim === "AVAILABLE" ||
+            raw.externalAvailabilityClaim === "UNAVAILABLE"
+            ? { externalAvailabilityClaim: raw.externalAvailabilityClaim }
+            : {}),
     };
 }
 export async function dispatchModuleCommand(catalog, module, command, context) {
@@ -32,7 +36,7 @@ export async function dispatchModuleCommand(catalog, module, command, context) {
     const invoke = adapter[command];
     if (!isCommandFn(invoke))
         throw new PlatformError("COMMAND_FAILED", `module ${module.moduleRef} does not implement standard command "${command}"`);
-    const { result, observedEffects } = normalizeInvocation(await invoke(context));
+    const { result, observedEffects, externalAvailabilityClaim } = normalizeInvocation(await invoke(context));
     const parsed = moduleOperationResultSchema.safeParse(result);
     if (!parsed.success)
         throw new PlatformError("COMMAND_FAILED", `module ${module.moduleRef} "${command}" returned an invalid result: ${parsed.error.message}`);
@@ -41,5 +45,8 @@ export async function dispatchModuleCommand(catalog, module, command, context) {
         command,
         result: parsed.data,
         observedEffects,
+        ...(externalAvailabilityClaim === undefined
+            ? {}
+            : { externalAvailabilityClaim }),
     };
 }

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,38 +172,51 @@ 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 = [];
     const graph = buildDependencyGraph(modules);
     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 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);
     }
-    if (target !== undefined && !byRef.has(target.moduleRef))
-        throw new PlatformError("INVALID_REQUEST", `setup target module ${target.moduleRef} was not discovered`);
-    const visitedRefs = new Set();
-    const includeWithDependencies = (moduleRef) => {
-        if (visitedRefs.has(moduleRef))
+    const userOrder = [];
+    const included = new Set();
+    const appendWithDependencies = (moduleRef) => {
+        if (included.has(moduleRef) || !byRef.has(moduleRef))
             return;
-        visitedRefs.add(moduleRef);
-        for (const dependency of dependenciesByRef.get(moduleRef) ?? [])
-            includeWithDependencies(dependency);
+        for (const dependency of graph.order)
+            if (dependenciesByRef.get(moduleRef)?.includes(dependency))
+                appendWithDependencies(dependency);
+        included.add(moduleRef);
+        userOrder.push(moduleRef);
     };
-    if (target !== undefined)
-        includeWithDependencies(target.moduleRef);
-    else
+    if (target === undefined) {
+        for (const moduleRef of setupPriority)
+            appendWithDependencies(moduleRef);
         for (const moduleRef of graph.order)
-            visitedRefs.add(moduleRef);
-    const modulesInOrder = graph.order
-        .filter((moduleRef) => visitedRefs.has(moduleRef))
+            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);
-    const setupStatusByRef = new Map();
     let completed = true;
     for (const [index, module] of modulesInOrder.entries()) {
         reportProgress(reporter, {
@@ -218,16 +231,10 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
         if (!succeeded(status.result)) {
             results.push(status);
-            setupStatusByRef.set(module.moduleRef, "FAILED");
             completed = false;
-            if (target?.moduleRef === module.moduleRef)
-                break;
-            continue;
+            break;
         }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
-        setupStatusByRef.set(module.moduleRef, observed.setupStatus);
-        if (target !== undefined && module.moduleRef !== target.moduleRef)
-            continue;
         if (observed.setupStatus === "READY" && target === undefined) {
             skipped.push({ moduleRef: module.moduleRef, reason: "READY" });
             reportProgress(reporter, {
@@ -241,29 +248,7 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
             });
             continue;
         }
-        const unavailableDependencies = (dependenciesByRef.get(module.moduleRef) ?? []).filter((moduleRef) => setupStatusByRef.get(moduleRef) !== "READY");
-        if (unavailableDependencies.length > 0) {
-            const first = unavailableDependencies[0];
-            blockers.push({
-                moduleRef: module.moduleRef,
-                setupStatus: "BLOCKED",
-                reason: `等待依赖模块就绪：${unavailableDependencies.join(", ")}`,
-                nextCommand: `platform setup --module ${first}`,
-            });
-            completed = false;
-            reportProgress(reporter, {
-                command: "setup",
-                phase: "setup",
-                current: index + 1,
-                total: modulesInOrder.length,
-                moduleRef: module.moduleRef,
-                status: "SKIPPED",
-                message: `${module.moduleRef} 等待 ${unavailableDependencies.join(", ")}`,
-            });
-            if (target !== undefined)
-                break;
-            continue;
-        }
+        await beforeSetup?.(module.moduleRef);
         const setup = await dispatchModuleCommand(catalog, module, "setup", context(workspaceRoot, target?.input));
         results.push(setup);
         reportProgress(reporter, {
@@ -283,14 +268,25 @@ export async function setupModulesThin(catalog, modules, workspaceRoot, target,
             completed = false;
         }
         const reconciled = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
-        if (succeeded(reconciled.result))
-            setupStatusByRef.set(module.moduleRef, moduleStatusObservationSchema.parse(reconciled.result.data).setupStatus);
-        else {
+        if (!succeeded(reconciled.result)) {
             results.push(reconciled);
-            setupStatusByRef.set(module.moduleRef, "FAILED");
             completed = false;
         }
-        if (target !== undefined && !succeeded(setup.result))
+        else {
+            const reconciledStatus = moduleStatusObservationSchema.parse(reconciled.result.data);
+            if (reconciledStatus.setupStatus !== "READY") {
+                const issue = reconciledStatus.issues?.find((item) => item.scope === "SETUP");
+                blockers.push({
+                    moduleRef: module.moduleRef,
+                    setupStatus: reconciledStatus.setupStatus,
+                    ...(issue === undefined
+                        ? {}
+                        : { reason: issue.message, nextCommand: issue.nextCommand }),
+                });
+                completed = false;
+            }
+        }
+        if (!succeeded(setup.result) || blockers.length > 0)
             break;
     }
     return {

package/dist/src/registry/index.d.ts

@@ -1,2 +1,2 @@
 export type { NpmCommandResult, NpmCommandRunner, RegistryDiscoveryResult, RegistryModuleCandidate, RegistryRejectedPackage, } from "./npm-registry.ts";
-export { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.ts";
+export { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, RETIRED_PRO_FLOW_PACKAGES, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.ts";

package/dist/src/registry/index.js

@@ -1 +1 @@
-export { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.js";
+export { discoverRegistryModules, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, RETIRED_PRO_FLOW_PACKAGES, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.js";

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

@@ -1,5 +1,6 @@
 export declare const PRO_FLOW_SCOPE = "@tomflow";
 export declare const PRO_FLOW_PACKAGE_PREFIX = "@tomflow/proflow-";
+export declare const RETIRED_PRO_FLOW_PACKAGES: Set<string>;
 export interface NpmCommandResult {
     stdout: string;
     stderr: string;
@@ -26,6 +27,7 @@ export interface RegistryDiscoveryResult {
     registry: string;
     candidates: RegistryModuleCandidate[];
     rejected: RegistryRejectedPackage[];
+    retired: string[];
 }
 export declare function systemNpmRunner(): NpmCommandRunner;
 export declare function resolveScopeRegistry(workspaceRoot: string, runner?: NpmCommandRunner): Promise<string>;

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

@@ -6,6 +6,9 @@ import { versionSatisfies } from "../modules.js";
 const execFileAsync = promisify(execFile);
 export const PRO_FLOW_SCOPE = "@tomflow";
 export const PRO_FLOW_PACKAGE_PREFIX = "@tomflow/proflow-";
+export const RETIRED_PRO_FLOW_PACKAGES = new Set([
+    "@tomflow/proflow-chatgpt-carrier",
+]);
 export function systemNpmRunner() {
     return {
         async run(args, cwd, timeoutMs) {
@@ -42,15 +45,17 @@ export async function discoverRegistryModules(options) {
     const names = options.packageName === undefined
         ? await searchPackageNames(options.workspaceRoot, registry, runner)
         : [validateRequestedPackageName(options.packageName)];
-    options.onSearchComplete?.(names.length);
+    const retired = names.filter((name) => RETIRED_PRO_FLOW_PACKAGES.has(name));
+    const activeNames = names.filter((name) => !RETIRED_PRO_FLOW_PACKAGES.has(name));
+    options.onSearchComplete?.(activeNames.length);
     const candidates = [];
     const rejected = [];
     let nextIndex = 0;
     let completed = 0;
     const worker = async () => {
-        while (nextIndex < names.length) {
+        while (nextIndex < activeNames.length) {
             const index = nextIndex++;
-            const packageName = names[index];
+            const packageName = activeNames[index];
             if (packageName === undefined)
                 return;
             const manifest = await viewManifest(options.workspaceRoot, registry, packageName, runner);
@@ -62,15 +67,15 @@ export async function discoverRegistryModules(options) {
             completed += 1;
             options.onPackageChecked?.({
                 current: completed,
-                total: names.length,
+                total: activeNames.length,
                 packageName,
             });
         }
     };
-    await Promise.all(Array.from({ length: Math.min(4, names.length) }, () => worker()));
+    await Promise.all(Array.from({ length: Math.min(4, activeNames.length) }, () => worker()));
     candidates.sort((left, right) => left.packageName.localeCompare(right.packageName));
     rejected.sort((left, right) => left.packageName.localeCompare(right.packageName));
-    return { registry, candidates, rejected };
+    return { registry, candidates, rejected, retired };
 }
 async function searchPackageNames(workspaceRoot, registry, runner) {
     const result = await runner.run([

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.37",
+  "version": "0.1.39",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,11 +24,12 @@
     "SETUP.md"
   ],
   "dependencies": {
+    "@clack/prompts": "1.7.0",
     "@tomflow/proflow-module-contract": "^0.1.13"
   },
   "devDependencies": {
-    "@tomflow/proflow-module-template": "^0.1.10",
-    "@tomflow/proflow-deployment-conformance": "^0.1.11"
+    "@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.",
   "keywords": [

package/proflow.module.json

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