@jingyi0605/codingns 0.3.5 → 0.4.0

package/dist/server/modules/debug-target/debug-target-service.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import { AppError } from "../../shared/errors/app-error.js";
 import { createId } from "../../shared/utils/id.js";
 import { nowIso } from "../../shared/utils/time.js";
+import { DEFAULT_DEBUG_PORT_POOLS } from "../preferences/profile-service.js";
 import { buildTemplateCommandLine, getShellEnterSequence } from "../terminal/terminal-shell.js";
+import { discoverTemplateRuntimeStatuses } from "../terminal/template-port-runtime.js";
 import { createTaskManager } from "../tasks/task-manager.js";
 import { HOST_TASK_TYPES } from "../tasks/task-types.js";
 import { FRAMEWORK_COMPATIBILITY_MATRIX, FRAMEWORK_COMPATIBILITY_MATRIX_VERSION, getFrameworkCompatibilityItem } from "./framework-compatibility-matrix.js";
@@ -21,10 +23,11 @@ export class DebugTargetService {
     runtimeBindingRepository;
     aiFallbackEditRepository;
     terminalCommandTemplateRepository;
+    preferenceProfileService;
     terminalService;
     terminalInstanceRepository;
     taskManager;
-    constructor(db, workspaceService, workspaceWorktreeRepository, debugTargetRepository, debugServiceRepository, frameworkAnalysisResultRepository, debugRuntimeSessionRepository, portLeaseRepository, runtimeBindingRepository, aiFallbackEditRepository, terminalCommandTemplateRepository, terminalService, terminalInstanceRepository, taskManager = createTaskManager()) {
+    constructor(db, workspaceService, workspaceWorktreeRepository, debugTargetRepository, debugServiceRepository, frameworkAnalysisResultRepository, debugRuntimeSessionRepository, portLeaseRepository, runtimeBindingRepository, aiFallbackEditRepository, terminalCommandTemplateRepository, preferenceProfileService, terminalService, terminalInstanceRepository, taskManager = createTaskManager()) {
         this.db = db;
         this.workspaceService = workspaceService;
         this.workspaceWorktreeRepository = workspaceWorktreeRepository;
@@ -36,6 +39,7 @@ export class DebugTargetService {
         this.runtimeBindingRepository = runtimeBindingRepository;
         this.aiFallbackEditRepository = aiFallbackEditRepository;
         this.terminalCommandTemplateRepository = terminalCommandTemplateRepository;
+        this.preferenceProfileService = preferenceProfileService;
         this.terminalService = terminalService;
         this.terminalInstanceRepository = terminalInstanceRepository;
         this.taskManager = taskManager;
@@ -134,7 +138,94 @@ export class DebugTargetService {
             items: FRAMEWORK_COMPATIBILITY_MATRIX
         };
     }
-    async createLaunchPlan(targetId) {
+    async createLaunchPlan(targetId, portRequests = [], userId = null) {
+        return await this.createRegisteredTemplatePreviewPlan(targetId, portRequests, userId);
+    }
+    async run(input) {
+        const launchPlan = await this.createManagedRuntimeLaunchPlan(input.targetId, input.portRequests ?? [], input.userId);
+        if (!launchPlan.autoStartAllowed) {
+            const aiFallbackItem = launchPlan.services.find((item) => item.aiFallback?.eligible);
+            if (aiFallbackItem) {
+                await this.failRuntimePlan(launchPlan.runtimeSession.id, aiFallbackItem.failureStage ?? "ai_fallback_required", "当前服务需要进入受限 AI 兜底流程，自动运行已阻止", 409, "DEBUG_TARGET_AI_FALLBACK_REQUIRED");
+            }
+            await this.failRuntimePlan(launchPlan.runtimeSession.id, launchPlan.services.find((item) => item.failureStage)?.failureStage ?? "launch_requirements", "当前启动计划缺少必要的服务发现、HMR 或 callback 处理，暂不允许自动启动", 409, "DEBUG_TARGET_RUN_NOT_ALLOWED");
+        }
+        const startedServices = [];
+        try {
+            for (const item of launchPlan.services) {
+                const service = this.getServiceOrThrow(item.serviceId, input.targetId);
+                const analysis = this.frameworkAnalysisResultRepository
+                    .listByTargetId(input.targetId)
+                    .find((candidate) => candidate.id === item.frameworkAnalysisId) ?? null;
+                const terminal = await this.terminalService.createTerminal({
+                    workspaceId: this.getTargetOrThrow(input.targetId).workspaceId,
+                    name: `${service.name} 运行`,
+                    cwd: service.cwd,
+                    shell: input.shell,
+                    runtimeType: input.runtimeType,
+                    createdByUserId: input.userId,
+                    env: {
+                        ...service.env,
+                        ...item.envPatch
+                    },
+                    debugRuntimeSessionId: launchPlan.runtimeSession.id,
+                    debugTargetId: input.targetId,
+                    debugServiceId: service.id,
+                    frameworkAnalysisId: analysis?.id ?? null,
+                    launcherSourceType: "debug_service",
+                    launchStage: "command_dispatched",
+                    failureStage: null,
+                    adapterKind: item.adapterKind ?? null,
+                    envPatchSummary: item.envPatch,
+                    artifactRef: item.artifactRef
+                });
+                const commandLine = buildTemplateCommandLine(buildEphemeralTemplate(service, item, input.runtimeType ?? terminal.runtimeType), terminal.shell);
+                await this.terminalService.writeInput(terminal.id, `${commandLine}${getShellEnterSequence(terminal.shell)}`);
+                this.runtimeBindingRepository.update({
+                    id: item.runtimeBindingId,
+                    runtimeId: launchPlan.runtimeSession.id,
+                    serviceId: service.id,
+                    processInstanceId: terminal.id,
+                    expectedPort: item.expectedPort,
+                    leasedPort: item.leasedPort,
+                    observedPort: null,
+                    proxyPath: null,
+                    status: "ALLOCATED",
+                    updatedAt: nowIso()
+                });
+                startedServices.push({
+                    serviceId: service.id,
+                    processInstanceId: terminal.id,
+                    terminalId: terminal.id,
+                    leasedPort: item.leasedPort,
+                    runtimeBindingId: item.runtimeBindingId
+                });
+            }
+        }
+        catch (error) {
+            for (const service of startedServices) {
+                try {
+                    await this.terminalService.closeTerminal(service.terminalId);
+                }
+                catch {
+                    // 失败回滚阶段只做尽力而为，避免覆盖原始错误。
+                }
+            }
+            await this.failRuntimePlan(launchPlan.runtimeSession.id, "command_execution", error instanceof Error ? error.message : "调试目标启动失败", 500, "DEBUG_TARGET_RUN_FAILED");
+        }
+        const updatedRuntimeSession = this.debugRuntimeSessionRepository.update({
+            ...launchPlan.runtimeSession,
+            status: "RUNNING",
+            failureStage: null,
+            startedAt: nowIso(),
+            updatedAt: nowIso()
+        });
+        return {
+            runtimeSession: updatedRuntimeSession ?? launchPlan.runtimeSession,
+            services: startedServices
+        };
+    }
+    async createManagedRuntimeLaunchPlan(targetId, portRequests, userId) {
         const target = this.getTargetOrThrow(targetId);
         const services = this.debugServiceRepository.listByTargetId(targetId);
         const analyses = this.frameworkAnalysisResultRepository.listByTargetId(targetId);
@@ -160,6 +251,13 @@ export class DebugTargetService {
             updatedAt: timestamp
         });
         const planItems = [];
+        const requestedPorts = await resolveRequestedPorts({
+            targetRootPath: target.rootPath,
+            services,
+            portRequests,
+            portLeaseRepository: this.portLeaseRepository
+        });
+        const portPoolConfig = this.resolvePortPoolConfig(userId);
         for (const service of services) {
             const analysis = analysisByServiceId.get(service.id) ?? analyses[0] ?? null;
             if (!analysis) {
@@ -169,7 +267,8 @@ export class DebugTargetService {
                     detail: "调试服务缺少框架分析结果，无法生成启动计划"
                 });
             }
-            const allocatedPort = await allocateManagedPort(service.role, this.portLeaseRepository);
+            const allocatedPort = requestedPorts.get(service.id)
+                ?? await allocateManagedPort(service.role, this.portLeaseRepository, portPoolConfig);
             const injectionPlan = resolveLaunchPlan({
                 targetRootPath: target.rootPath,
                 service,
@@ -262,90 +361,60 @@ export class DebugTargetService {
             services: planItems
         };
     }
-    async run(input) {
-        const launchPlan = await this.createLaunchPlan(input.targetId);
-        if (!launchPlan.autoStartAllowed) {
-            const aiFallbackItem = launchPlan.services.find((item) => item.aiFallback?.eligible);
-            if (aiFallbackItem) {
-                await this.failRuntimePlan(launchPlan.runtimeSession.id, aiFallbackItem.failureStage ?? "ai_fallback_required", "当前服务需要进入受限 AI 兜底流程，自动运行已阻止", 409, "DEBUG_TARGET_AI_FALLBACK_REQUIRED");
-            }
-            await this.failRuntimePlan(launchPlan.runtimeSession.id, launchPlan.services.find((item) => item.failureStage)?.failureStage ?? "launch_requirements", "当前启动计划缺少必要的服务发现、HMR 或 callback 处理，暂不允许自动启动", 409, "DEBUG_TARGET_RUN_NOT_ALLOWED");
-        }
-        const startedServices = [];
-        try {
-            for (const item of launchPlan.services) {
-                const service = this.getServiceOrThrow(item.serviceId, input.targetId);
-                const analysis = this.frameworkAnalysisResultRepository
-                    .listByTargetId(input.targetId)
-                    .find((candidate) => candidate.id === item.frameworkAnalysisId) ?? null;
-                const terminal = await this.terminalService.createTerminal({
-                    workspaceId: this.getTargetOrThrow(input.targetId).workspaceId,
-                    name: `${service.name} 运行`,
-                    cwd: service.cwd,
-                    shell: input.shell,
-                    runtimeType: input.runtimeType,
-                    createdByUserId: input.userId,
-                    env: {
-                        ...service.env,
-                        ...item.envPatch
-                    },
-                    debugRuntimeSessionId: launchPlan.runtimeSession.id,
-                    debugTargetId: input.targetId,
-                    debugServiceId: service.id,
-                    frameworkAnalysisId: analysis?.id ?? null,
-                    launcherSourceType: "debug_service",
-                    launchStage: "command_dispatched",
-                    failureStage: null,
-                    adapterKind: item.adapterKind ?? null,
-                    envPatchSummary: item.envPatch,
-                    artifactRef: item.artifactRef
-                });
-                const commandLine = buildTemplateCommandLine(buildEphemeralTemplate(service, item, input.runtimeType ?? terminal.runtimeType), terminal.shell);
-                await this.terminalService.writeInput(terminal.id, `${commandLine}${getShellEnterSequence(terminal.shell)}`);
-                this.runtimeBindingRepository.update({
-                    id: item.runtimeBindingId,
-                    runtimeId: launchPlan.runtimeSession.id,
-                    serviceId: service.id,
-                    processInstanceId: terminal.id,
-                    expectedPort: item.expectedPort,
-                    leasedPort: item.leasedPort,
-                    observedPort: null,
-                    proxyPath: null,
-                    status: "ALLOCATED",
-                    updatedAt: nowIso()
-                });
-                startedServices.push({
-                    serviceId: service.id,
-                    processInstanceId: terminal.id,
-                    terminalId: terminal.id,
-                    leasedPort: item.leasedPort,
-                    runtimeBindingId: item.runtimeBindingId
-                });
-            }
+    async createRegisteredTemplatePreviewPlan(targetId, portRequests, userId) {
+        const target = this.getTargetOrThrow(targetId);
+        const analyses = this.frameworkAnalysisResultRepository.listByTargetId(targetId);
+        if (analyses.length === 0) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_ANALYSIS_REQUIRED",
+                detail: "当前调试目标还没有可用的框架分析结果，请先执行分析"
+            });
         }
-        catch (error) {
-            for (const service of startedServices) {
-                try {
-                    await this.terminalService.closeTerminal(service.terminalId);
-                }
-                catch {
-                    // 失败回滚阶段只做尽力而为，避免覆盖原始错误。
-                }
-            }
-            await this.failRuntimePlan(launchPlan.runtimeSession.id, "command_execution", error instanceof Error ? error.message : "调试目标启动失败", 500, "DEBUG_TARGET_RUN_FAILED");
+        const timestamp = nowIso();
+        const runtimeSession = buildPreviewRuntimeSession(target.id, timestamp);
+        const templates = listRegisteredTemplatesForTarget(this.terminalCommandTemplateRepository.listByWorkspace(target.workspaceId), target.rootPath);
+        if (templates.length === 0) {
+            return await this.createManagedRuntimeLaunchPlan(targetId, portRequests, userId);
         }
-        const updatedRuntimeSession = this.debugRuntimeSessionRepository.update({
-            ...launchPlan.runtimeSession,
-            status: "RUNNING",
-            failureStage: null,
-            startedAt: nowIso(),
-            updatedAt: nowIso()
+        const services = this.debugServiceRepository.listByTargetId(targetId);
+        const runtimeStatuses = await discoverTemplateRuntimeStatuses(templates
+            .filter((template) => template.port !== null)
+            .map((template) => ({
+            templateId: template.id,
+            port: template.port
+        })));
+        const runtimeStatusByTemplateId = new Map(runtimeStatuses.map((item) => [item.templateId, item]));
+        const portPoolConfig = this.resolvePortPoolConfig(userId);
+        const requestedPorts = await resolveTemplateRequestedPorts({
+            targetRootPath: target.rootPath,
+            templates,
+            portRequests,
+            portLeaseRepository: this.portLeaseRepository
+        });
+        const templatePlans = await buildRegisteredTemplatePlanItems({
+            target,
+            templates,
+            services,
+            analyses,
+            runtimeStatusByTemplateId,
+            requestedPorts,
+            portPoolConfig,
+            portLeaseRepository: this.portLeaseRepository
         });
         return {
-            runtimeSession: updatedRuntimeSession ?? launchPlan.runtimeSession,
-            services: startedServices
+            runtimeSession,
+            targetId: target.id,
+            autoStartAllowed: templatePlans.length > 0 && templatePlans.every((item) => item.autoStartAllowed),
+            services: templatePlans
         };
     }
+    resolvePortPoolConfig(userId) {
+        if (!userId) {
+            return clonePortPoolConfig(DEFAULT_DEBUG_PORT_POOLS);
+        }
+        return clonePortPoolConfig(this.preferenceProfileService.getProfile(userId).debugPortPools);
+    }
     async handleTerminalExit(event) {
         const runtimeId = event.terminal.debugRuntimeSessionId ?? null;
         if (!runtimeId) {
@@ -1551,10 +1620,447 @@ function resolveMissingRequirements(analysis) {
 function isFrameworkEligible(level) {
     return level === "supported" || level === "conditional";
 }
-async function allocateManagedPort(role, portLeaseRepository) {
-    const startPort = resolvePortRangeStart(role);
-    for (let offset = 0; offset < 200; offset += 1) {
-        const port = startPort + offset;
+async function buildRegisteredTemplatePlanItems(input) {
+    const matchedContexts = input.templates.map((template) => matchTemplateAnalysisContext(template, input.services, input.analyses));
+    const configuredPortCount = new Map();
+    const plannedPortByTemplateId = new Map();
+    const usedPorts = new Set();
+    for (const template of input.templates) {
+        if (template.port !== null) {
+            configuredPortCount.set(template.port, (configuredPortCount.get(template.port) ?? 0) + 1);
+        }
+    }
+    for (const context of matchedContexts) {
+        const requestedPort = input.requestedPorts.get(context.template.id);
+        if (requestedPort !== undefined) {
+            plannedPortByTemplateId.set(context.template.id, requestedPort);
+            usedPorts.add(requestedPort);
+            continue;
+        }
+        if (context.template.port === null) {
+            plannedPortByTemplateId.set(context.template.id, null);
+            continue;
+        }
+        const runtimeStatus = input.runtimeStatusByTemplateId.get(context.template.id) ?? null;
+        const needsOrchestration = input.target.sourceType === "worktree"
+            || (configuredPortCount.get(context.template.port) ?? 0) > 1
+            || runtimeStatus?.occupied === true
+            || input.portLeaseRepository.findActiveByPort(context.template.port, "tcp") !== null
+            || usedPorts.has(context.template.port);
+        if (!needsOrchestration) {
+            plannedPortByTemplateId.set(context.template.id, context.template.port);
+            usedPorts.add(context.template.port);
+            continue;
+        }
+        const allocatedPort = await allocateManagedPort(context.role, input.portLeaseRepository, input.portPoolConfig, usedPorts);
+        plannedPortByTemplateId.set(context.template.id, allocatedPort);
+        usedPorts.add(allocatedPort);
+    }
+    const backendEndpoint = resolveRegisteredTemplateBackendEndpoint(matchedContexts, plannedPortByTemplateId);
+    return matchedContexts.map((context) => {
+        const plannedPort = plannedPortByTemplateId.get(context.template.id) ?? null;
+        const runtimeBindingId = createId();
+        const analysis = context.analysis;
+        if (!analysis) {
+            return {
+                serviceId: context.template.id,
+                role: context.role,
+                frameworkAnalysisId: null,
+                primaryFramework: null,
+                compatibilityLevel: "unknown",
+                adapterKind: context.template.adapterKind ?? null,
+                injectionMode: context.template.injectionMode ?? null,
+                command: context.template.command,
+                args: context.template.args,
+                envPatch: {},
+                expectedPort: context.template.port,
+                leasedPort: plannedPort,
+                artifactRef: context.template.generatedArtifactRef ?? null,
+                runtimeBindingId,
+                portLeaseId: null,
+                requiresServiceDiscoveryHandling: false,
+                requiresHmrHandling: false,
+                requiresCallbackHandling: false,
+                failureStage: "framework_analysis_missing",
+                adapterAttempts: [],
+                aiFallback: null,
+                missingRequirements: ["analysis"],
+                autoStartAllowed: false
+            };
+        }
+        if (plannedPort === null) {
+            return {
+                serviceId: context.template.id,
+                role: context.role,
+                frameworkAnalysisId: analysis.id,
+                primaryFramework: analysis.primaryFramework ?? null,
+                compatibilityLevel: analysis.compatibilityLevel,
+                adapterKind: context.template.adapterKind ?? null,
+                injectionMode: context.template.injectionMode ?? null,
+                command: context.template.command,
+                args: context.template.args,
+                envPatch: {},
+                expectedPort: context.template.port,
+                leasedPort: null,
+                artifactRef: context.template.generatedArtifactRef ?? null,
+                runtimeBindingId,
+                portLeaseId: null,
+                requiresServiceDiscoveryHandling: analysis.requiresServiceDiscoveryHandling,
+                requiresHmrHandling: analysis.requiresHmrHandling,
+                requiresCallbackHandling: analysis.requiresCallbackHandling,
+                failureStage: "port_unconfigured",
+                adapterAttempts: [],
+                aiFallback: null,
+                missingRequirements: ["port"],
+                autoStartAllowed: false
+            };
+        }
+        const injectionPlan = resolveLaunchPlan({
+            targetRootPath: input.target.rootPath,
+            service: buildTemplateBackedDebugService(context.template, context.role, analysis.id),
+            analysis,
+            leasedPort: plannedPort
+        });
+        const serviceDiscoveryEnvPatch = buildServiceDiscoveryEnvPatch({
+            role: context.role,
+            analysis,
+            backendEndpoint
+        });
+        const missingRequirements = resolveRegisteredTemplateMissingRequirements(analysis, {
+            role: context.role,
+            backendEndpoint
+        });
+        const envPatch = {
+            ...injectionPlan.envPatch,
+            ...serviceDiscoveryEnvPatch
+        };
+        const autoStartAllowed = isFrameworkEligible(analysis.compatibilityLevel)
+            && missingRequirements.length === 0
+            && injectionPlan.adapterKind !== "ai_fallback"
+            && injectionPlan.adapterKind !== null;
+        return {
+            serviceId: context.template.id,
+            role: context.role,
+            frameworkAnalysisId: analysis.id,
+            primaryFramework: analysis.primaryFramework ?? null,
+            compatibilityLevel: analysis.compatibilityLevel,
+            adapterKind: injectionPlan.adapterKind ?? null,
+            injectionMode: injectionPlan.injectionMode ?? null,
+            command: context.template.command,
+            args: injectionPlan.args,
+            envPatch,
+            expectedPort: context.template.port,
+            leasedPort: plannedPort,
+            artifactRef: injectionPlan.artifactRef ?? context.template.generatedArtifactRef ?? null,
+            runtimeBindingId,
+            portLeaseId: null,
+            requiresServiceDiscoveryHandling: analysis.requiresServiceDiscoveryHandling,
+            requiresHmrHandling: analysis.requiresHmrHandling,
+            requiresCallbackHandling: analysis.requiresCallbackHandling,
+            failureStage: injectionPlan.failureStage,
+            adapterAttempts: injectionPlan.adapterAttempts,
+            aiFallback: injectionPlan.aiFallback,
+            missingRequirements,
+            autoStartAllowed
+        };
+    });
+}
+function buildPreviewRuntimeSession(targetId, timestamp) {
+    return {
+        id: `preview-${createId()}`,
+        targetId,
+        status: "PREPARING",
+        failureStage: null,
+        startedAt: null,
+        stoppedAt: null,
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+function listRegisteredTemplatesForTarget(templates, rootPath) {
+    return templates
+        .filter((template) => template.managedBySystem !== true)
+        .filter((template) => isTemplateRelevantToRootPath(template, rootPath))
+        .sort((left, right) => compareTemplatePriority(left, right, rootPath));
+}
+function matchTemplateAnalysisContext(template, services, analyses) {
+    const analysisByServiceId = new Map(analyses
+        .filter((analysis) => analysis.serviceId)
+        .map((analysis) => [analysis.serviceId, analysis]));
+    const normalizedTemplateCwd = path.resolve(template.cwd);
+    const templateRole = inferTemplateRole(template);
+    const matchedService = [...services]
+        .sort((left, right) => compareServiceMatchPriority(left, right, normalizedTemplateCwd, templateRole))
+        .find((service) => {
+        const serviceCwd = path.resolve(service.cwd);
+        return serviceCwd === normalizedTemplateCwd
+            || isPathWithin(normalizedTemplateCwd, serviceCwd)
+            || isPathWithin(serviceCwd, normalizedTemplateCwd);
+    }) ?? null;
+    const analysis = matchedService ? analysisByServiceId.get(matchedService.id) ?? null : null;
+    return {
+        template,
+        role: matchedService?.role ?? templateRole,
+        service: matchedService,
+        analysis
+    };
+}
+function compareServiceMatchPriority(left, right, templateCwd, templateRole) {
+    const leftExact = Number(path.resolve(left.cwd) === templateCwd);
+    const rightExact = Number(path.resolve(right.cwd) === templateCwd);
+    if (rightExact !== leftExact) {
+        return rightExact - leftExact;
+    }
+    const leftRoleMatch = Number(left.role === templateRole);
+    const rightRoleMatch = Number(right.role === templateRole);
+    if (rightRoleMatch !== leftRoleMatch) {
+        return rightRoleMatch - leftRoleMatch;
+    }
+    const leftDistance = resolveRelativePathDistance(templateCwd, left.cwd);
+    const rightDistance = resolveRelativePathDistance(templateCwd, right.cwd);
+    if (leftDistance !== rightDistance) {
+        return leftDistance - rightDistance;
+    }
+    return left.name.localeCompare(right.name);
+}
+function resolveRelativePathDistance(leftPath, rightPath) {
+    const normalizedLeft = withTrailingSeparator(path.resolve(leftPath));
+    const normalizedRight = withTrailingSeparator(path.resolve(rightPath));
+    if (normalizedLeft === normalizedRight) {
+        return 0;
+    }
+    if (normalizedLeft.startsWith(normalizedRight) || normalizedRight.startsWith(normalizedLeft)) {
+        return 1;
+    }
+    return 2;
+}
+function inferTemplateRole(template) {
+    const signal = [
+        template.name,
+        template.cwd,
+        template.command,
+        ...template.args
+    ].join(" ").toLowerCase();
+    if (signal.includes("frontend")
+        || signal.includes("web")
+        || signal.includes("ui")
+        || signal.includes("vite")
+        || signal.includes("next")
+        || signal.includes("astro")
+        || signal.includes("nuxt")
+        || signal.includes("vue")
+        || signal.includes("remix")) {
+        return "frontend";
+    }
+    if (signal.includes("worker")) {
+        return "worker";
+    }
+    if (signal.includes("mock")) {
+        return "mock";
+    }
+    if (signal.includes("backend")
+        || signal.includes("server")
+        || signal.includes("api")
+        || signal.includes("host")
+        || signal.includes("express")
+        || signal.includes("nestjs")
+        || signal.includes("koa")
+        || signal.includes("hono")
+        || signal.includes("uvicorn")
+        || signal.includes("flask")
+        || signal.includes("django")
+        || signal.includes("spring")
+        || signal.includes("rails")
+        || signal.includes("dotnet")) {
+        return "backend";
+    }
+    return "custom";
+}
+function buildTemplateBackedDebugService(template, role, frameworkAnalysisId) {
+    return {
+        id: template.id,
+        targetId: template.debugTargetId ?? "",
+        role,
+        name: template.name,
+        cwd: template.cwd,
+        command: template.command,
+        args: template.args,
+        env: template.env,
+        defaultPortHint: template.port,
+        protocol: "http",
+        healthPath: null,
+        adapterKind: template.adapterKind ?? null,
+        frameworkAnalysisId,
+        createdAt: template.createdAt,
+        updatedAt: template.updatedAt
+    };
+}
+function resolveRegisteredTemplateBackendEndpoint(contexts, plannedPortByTemplateId) {
+    const candidate = contexts.find((context) => context.role === "backend" && plannedPortByTemplateId.get(context.template.id) !== null);
+    if (!candidate) {
+        return null;
+    }
+    return `http://127.0.0.1:${plannedPortByTemplateId.get(candidate.template.id)}`;
+}
+function buildServiceDiscoveryEnvPatch(input) {
+    if (input.role === "backend" || !input.analysis.requiresServiceDiscoveryHandling || !input.backendEndpoint) {
+        return {};
+    }
+    switch (input.analysis.primaryFramework) {
+        case "vite":
+            return {
+                VITE_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "nextjs":
+            return {
+                NEXT_PUBLIC_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "cra":
+            return {
+                REACT_APP_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "astro":
+            return {
+                PUBLIC_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "nuxt":
+            return {
+                NUXT_PUBLIC_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "vue-cli":
+            return {
+                VUE_APP_API_BASE_URL: input.backendEndpoint,
+                API_BASE_URL: input.backendEndpoint
+            };
+        case "remix":
+            return {
+                API_BASE_URL: input.backendEndpoint,
+                PUBLIC_API_BASE_URL: input.backendEndpoint
+            };
+        default:
+            return {
+                API_BASE_URL: input.backendEndpoint,
+                BACKEND_BASE_URL: input.backendEndpoint
+            };
+    }
+}
+function resolveRegisteredTemplateMissingRequirements(analysis, input) {
+    const missing = [];
+    if (analysis.requiresServiceDiscoveryHandling
+        && input.role !== "backend"
+        && !input.backendEndpoint) {
+        missing.push("service_discovery");
+    }
+    if (analysis.requiresCallbackHandling) {
+        missing.push("callback");
+    }
+    return missing;
+}
+async function resolveTemplateRequestedPorts(input) {
+    const requestedPorts = new Map();
+    const usedPorts = new Map();
+    for (const request of input.portRequests) {
+        validatePortRequestShape(request);
+        const matches = input.templates.filter((template) => matchesTemplatePortRequest(template, input.targetRootPath, request));
+        if (matches.length === 0) {
+            throw new AppError({
+                statusCode: 400,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_UNMATCHED",
+                detail: `显式端口请求没有匹配到任何启动项：${describePortRequest(request)}`,
+                field: "portRequests"
+            });
+        }
+        if (matches.length > 1) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_AMBIGUOUS",
+                detail: `显式端口请求匹配到了多个启动项：${describePortRequest(request)}`,
+                field: "portRequests"
+            });
+        }
+        const matchedTemplate = matches[0];
+        const previousPort = requestedPorts.get(matchedTemplate.id);
+        if (previousPort !== undefined && previousPort !== request.port) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_CONFLICT",
+                detail: `同一个启动项收到了多个不同的显式端口请求：${matchedTemplate.name}`,
+                field: "portRequests"
+            });
+        }
+        const occupiedBy = usedPorts.get(request.port);
+        if (occupiedBy && occupiedBy !== matchedTemplate.id) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_CONFLICT",
+                detail: `多个启动项请求了同一个端口：${request.port}`,
+                field: "portRequests"
+            });
+        }
+        await ensureRequestedPortAvailable(request.port, inferTemplateRole(matchedTemplate), input.portLeaseRepository);
+        requestedPorts.set(matchedTemplate.id, request.port);
+        usedPorts.set(request.port, matchedTemplate.id);
+    }
+    return requestedPorts;
+}
+async function resolveRequestedPorts(input) {
+    const requestedPorts = new Map();
+    const usedPorts = new Map();
+    for (const request of input.portRequests) {
+        validatePortRequestShape(request);
+        const matches = input.services.filter((service) => matchesPortRequest(service, input.targetRootPath, request));
+        if (matches.length === 0) {
+            throw new AppError({
+                statusCode: 400,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_UNMATCHED",
+                detail: `显式端口请求没有匹配到任何服务：${describePortRequest(request)}`,
+                field: "portRequests"
+            });
+        }
+        if (matches.length > 1) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_AMBIGUOUS",
+                detail: `显式端口请求匹配到了多个服务：${describePortRequest(request)}`,
+                field: "portRequests"
+            });
+        }
+        const matchedService = matches[0];
+        const previousPort = requestedPorts.get(matchedService.id);
+        if (previousPort !== undefined && previousPort !== request.port) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_CONFLICT",
+                detail: `同一个服务收到了多个不同的显式端口请求：${matchedService.name}`,
+                field: "portRequests"
+            });
+        }
+        const occupiedBy = usedPorts.get(request.port);
+        if (occupiedBy && occupiedBy !== matchedService.id) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "DEBUG_TARGET_PORT_REQUEST_CONFLICT",
+                detail: `多个服务请求了同一个端口：${request.port}`,
+                field: "portRequests"
+            });
+        }
+        await ensureRequestedPortAvailable(request.port, matchedService.role, input.portLeaseRepository);
+        requestedPorts.set(matchedService.id, request.port);
+        usedPorts.set(request.port, matchedService.id);
+    }
+    return requestedPorts;
+}
+async function allocateManagedPort(role, portLeaseRepository, portPoolConfig, usedPorts = new Set()) {
+    const range = portPoolConfig;
+    for (let port = range.start; port <= range.end; port += 1) {
+        if (usedPorts.has(port)) {
+            continue;
+        }
         if (portLeaseRepository.findActiveByPort(port, "tcp")) {
             continue;
         }
@@ -1566,21 +2072,25 @@ async function allocateManagedPort(role, portLeaseRepository) {
     throw new AppError({
         statusCode: 409,
         errorCode: "PORT_LEASE_EXHAUSTED",
-        detail: `当前服务角色没有可分配的空闲端口：${role}`
+        detail: `当前服务角色没有可分配的空闲端口：${role}（范围 ${range.start}-${range.end}）`
     });
 }
-function resolvePortRangeStart(role) {
-    switch (role) {
-        case "frontend":
-            return 43000;
-        case "backend":
-            return 44000;
-        case "worker":
-            return 45000;
-        case "mock":
-            return 46000;
-        default:
-            return 47000;
+async function ensureRequestedPortAvailable(port, role, portLeaseRepository) {
+    if (portLeaseRepository.findActiveByPort(port, "tcp")) {
+        throw new AppError({
+            statusCode: 409,
+            errorCode: "DEBUG_TARGET_PORT_NOT_AVAILABLE",
+            detail: `显式请求的端口已被平台中的其他运行时占用：${port}`,
+            field: "portRequests"
+        });
+    }
+    if (!(await isPortAvailable(port))) {
+        throw new AppError({
+            statusCode: 409,
+            errorCode: "DEBUG_TARGET_PORT_NOT_AVAILABLE",
+            detail: `显式请求的端口当前不可用：${port}（服务角色：${role}）`,
+            field: "portRequests"
+        });
     }
 }
 async function isPortAvailable(port) {
@@ -1629,6 +2139,94 @@ function resolveProcessInstance(processInstanceId, terminalInstanceRepository) {
     }
     return terminalInstanceRepository.findById(processInstanceId);
 }
+function validatePortRequestShape(request) {
+    if (!Number.isInteger(request.port) || request.port < 1 || request.port > 65535) {
+        throw new AppError({
+            statusCode: 400,
+            errorCode: "INVALID_INPUT",
+            detail: `显式端口请求非法，port 必须是 1 到 65535 之间的整数：${request.port}`,
+            field: "portRequests"
+        });
+    }
+    const hasSelector = Boolean(request.serviceId?.trim()
+        || request.role?.trim()
+        || request.cwd?.trim()
+        || request.name?.trim()
+        || request.command?.trim());
+    if (!hasSelector) {
+        throw new AppError({
+            statusCode: 400,
+            errorCode: "INVALID_INPUT",
+            detail: "显式端口请求至少要提供 serviceId、role、cwd、name、command 中的一个选择条件",
+            field: "portRequests"
+        });
+    }
+}
+function matchesPortRequest(service, targetRootPath, request) {
+    if (request.serviceId?.trim() && request.serviceId.trim() !== service.id) {
+        return false;
+    }
+    if (request.role?.trim() && request.role.trim() !== service.role) {
+        return false;
+    }
+    if (request.name?.trim() && request.name.trim() !== service.name) {
+        return false;
+    }
+    if (request.command?.trim() && request.command.trim() !== service.command) {
+        return false;
+    }
+    if (request.cwd?.trim()) {
+        const selectorPath = normalizePortRequestCwd(request.cwd, targetRootPath);
+        const servicePath = path.resolve(service.cwd);
+        if (selectorPath !== servicePath) {
+            return false;
+        }
+    }
+    return true;
+}
+function matchesTemplatePortRequest(template, targetRootPath, request) {
+    if (request.serviceId?.trim() && request.serviceId.trim() !== template.id) {
+        return false;
+    }
+    if (request.role?.trim() && request.role.trim() !== inferTemplateRole(template)) {
+        return false;
+    }
+    if (request.name?.trim() && request.name.trim() !== template.name) {
+        return false;
+    }
+    if (request.command?.trim() && request.command.trim() !== template.command) {
+        return false;
+    }
+    if (request.cwd?.trim()) {
+        const selectorPath = normalizePortRequestCwd(request.cwd, targetRootPath);
+        const templatePath = path.resolve(template.cwd);
+        if (selectorPath !== templatePath) {
+            return false;
+        }
+    }
+    return true;
+}
+function clonePortPoolConfig(config) {
+    return { ...config };
+}
+function normalizePortRequestCwd(value, targetRootPath) {
+    const trimmed = value?.trim() || "";
+    if (!trimmed) {
+        return "";
+    }
+    return path.resolve(path.isAbsolute(trimmed) ? trimmed : path.join(targetRootPath, trimmed));
+}
+function describePortRequest(request) {
+    const parts = [
+        request.serviceId?.trim() ? `serviceId=${request.serviceId.trim()}` : null,
+        request.role?.trim() ? `role=${request.role.trim()}` : null,
+        request.cwd?.trim() ? `cwd=${request.cwd.trim()}` : null,
+        request.name?.trim() ? `name=${request.name.trim()}` : null,
+        request.command?.trim() ? `command=${request.command.trim()}` : null,
+        `port=${request.port}`
+    ].filter((item) => Boolean(item));
+    return parts.join(", ");
+}
 function resolveAiFallbackNextStatus(action) {
     switch (action) {
         case "apply":