qlogicagent 2.13.3 → 2.13.5

package/dist/cli/pet-runtime.js

@@ -0,0 +1,220 @@
+import { resolveActiveOwnerUserId } from "../runtime/infra/agent-paths.js";
+import { PetGrowthEngine } from "../runtime/pet/pet-growth-engine.js";
+import { PetSoulService, } from "../runtime/pet/index.js";
+import { petReactionEngine } from "../runtime/pet/pet-reaction-engine.js";
+import { forgePetdexAsset } from "../runtime/pet/petdex-forge-service.js";
+import { generateMedia, getMediaRuntimeContext, isMediaAvailable, isMediaOperationDeclaredAvailable } from "./media-runtime-facade.js";
+export function createPetRuntime(deps) {
+    const ownerUserId = () => deps.resolveOwnerUserId?.() ?? resolveActiveOwnerUserId();
+    const streamText = async (client, request) => {
+        let text = "";
+        for await (const chunk of client.transport.stream(request, client.apiKey)) {
+            if (chunk.type === "delta")
+                text += chunk.text;
+        }
+        return text.trim();
+    };
+    return {
+        createPetSoulGenerator() {
+            const client = deps.resolveClientForPurpose("smallModel");
+            if (!client)
+                return undefined;
+            return async (rarity) => {
+                const prompt = "你是桌面宠物灵魂生成器。严格输出 JSON，包含 name、personality、catchphrase。 " +
+                    `稀有度: ${rarity}。名字 2-4 个中文字符，性格 15 字内，口头禅 6 字内。`;
+                try {
+                    const text = await streamText(client, {
+                        model: client.model,
+                        messages: [{ role: "user", content: prompt }],
+                        maxTokens: 100,
+                    });
+                    const match = text.match(/\{[\s\S]*\}/);
+                    if (match) {
+                        const parsed = JSON.parse(match[0]);
+                        if (parsed.name && parsed.personality && parsed.catchphrase) {
+                            return {
+                                name: String(parsed.name).slice(0, 8),
+                                personality: String(parsed.personality).slice(0, 30),
+                                catchphrase: String(parsed.catchphrase).slice(0, 12),
+                            };
+                        }
+                    }
+                }
+                catch {
+                    // PetSoulService will fall back to deterministic local defaults.
+                }
+                throw new Error("LLM_GENERATION_FAILED");
+            };
+        },
+        createSmallLLMCall() {
+            const client = deps.resolveClientForPurpose("smallModel") ?? deps.resolveClientForPurpose("textGeneration");
+            if (!client)
+                return undefined;
+            return async (prompt, maxTokens) => {
+                try {
+                    return await streamText(client, {
+                        model: client.model,
+                        messages: [{ role: "user", content: prompt }],
+                        maxTokens,
+                    }) || null;
+                }
+                catch {
+                    return null;
+                }
+            };
+        },
+        async forgeAnalyzeImage(imageBase64, hint) {
+            const client = deps.resolveClientForPurpose("imageUnderstanding");
+            if (!client)
+                throw new Error("No vision model available for image analysis");
+            const prompt = [
+                "Analyze this character image for an 8 by 9 Petdex desktop pet sprite atlas.",
+                "Return a concise plain-text character description covering species, colors, body shape, key features, eyes, pose language, and style.",
+                hint ? `User hint: ${hint}` : "",
+            ].filter(Boolean).join("\n");
+            const text = await streamText(client, {
+                model: client.model,
+                messages: [{
+                        role: "user",
+                        content: prompt,
+                        imageUrls: [`data:image/png;base64,${imageBase64}`],
+                    }],
+                maxTokens: 200,
+            });
+            return text || hint || "A cute rounded desktop pet character";
+        },
+        isImageGenerationAvailable() {
+            return isMediaAvailable("image");
+        },
+        isPetdexForgeAvailable() {
+            return isMediaOperationDeclaredAvailable("image", "img2img");
+        },
+        async forgeGeneratePetdexAtlas(input) {
+            // Codex vision-QA: when a vision model is configured, let the forge reject
+            // and regenerate drifting/dirty rows by inspecting generated strips and the
+            // final contact sheet. Absent a vision model, the forge degrades cleanly.
+            const visionClient = deps.resolveClientForPurpose("imageUnderstanding");
+            const inspectImage = visionClient
+                ? async ({ prompt, imageUrls }) => {
+                    try {
+                        return await streamText(visionClient, {
+                            model: visionClient.model,
+                            messages: [{ role: "user", content: prompt, imageUrls }],
+                            maxTokens: 200,
+                        });
+                    }
+                    catch {
+                        return "PASS"; // a vision-call failure must not block generation
+                    }
+                }
+                : undefined;
+            return forgePetdexAsset(input, async (request) => {
+                const context = getMediaRuntimeContext();
+                const result = await generateMedia({
+                    mediaType: "image",
+                    model: "",
+                    prompt: request.prompt,
+                    purpose: request.purpose,
+                    style: request.style,
+                    size: request.size,
+                    imageUrl: request.imageUrl,
+                    referenceImages: request.referenceImages?.map((image) => image.imageUrl),
+                    n: request.n,
+                    quality: request.quality,
+                });
+                return {
+                    mediaUrls: result.mediaUrls,
+                    model: result.model,
+                    size: result.size,
+                    durationMs: result.durationMs,
+                    provider: result.provider ?? context.mediaProviders.image?.provider,
+                    billingUnit: result.billingUnit,
+                    billingQuantity: result.billingQuantity,
+                };
+            }, { inspectImage });
+        },
+        async awardXp(event) {
+            try {
+                const soulService = new PetSoulService(deps.getActiveProjectRoot(), ownerUserId());
+                const soul = soulService.load();
+                if (!soul)
+                    return;
+                const xpGain = PetGrowthEngine.xpForEvent(event);
+                const { newLevel, newXp, events, statBoosts } = PetGrowthEngine.processXpGain(soul, xpGain);
+                soul.level = newLevel;
+                soul.experience = newXp;
+                for (const [key, value] of Object.entries(statBoosts)) {
+                    const statKey = key;
+                    soul.stats[statKey] = Math.min(10, soul.stats[statKey] + (value ?? 0));
+                }
+                soulService.updateSoul(soul);
+                deps.sendNotification("pet.growth", {
+                    level: newLevel,
+                    experience: newXp,
+                    xpNeeded: PetGrowthEngine.xpForLevel(newLevel),
+                    displayTraits: PetGrowthEngine.getUnlockedDisplayTraits(newLevel).map((trait) => ({
+                        id: trait.id,
+                        level: trait.unlockedAtLevel,
+                    })),
+                });
+                for (const growthEvent of events) {
+                    if (growthEvent.type === "molt") {
+                        deps.sendNotification("pet.reaction", {
+                            text: `宠物蜕变：第 ${growthEvent.moltStage} 阶段`,
+                            style: "excited",
+                        });
+                    }
+                    else if (growthEvent.type === "display_trait_unlock" && growthEvent.displayTrait) {
+                        deps.sendNotification("pet.reaction", {
+                            text: `Display trait unlocked: ${growthEvent.displayTrait.id}`,
+                            style: "excited",
+                        });
+                    }
+                }
+            }
+            catch {
+                // Pet growth is a non-critical side effect.
+            }
+        },
+        async reactAfterTurn(messages) {
+            try {
+                const soulService = new PetSoulService(deps.getActiveProjectRoot(), ownerUserId());
+                const soul = soulService.load();
+                const smallModel = deps.resolveClientForPurpose("smallModel");
+                if (soul && smallModel) {
+                    const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+                    const turnSummary = typeof lastAssistant?.content === "string"
+                        ? lastAssistant.content.slice(0, 100)
+                        : "Task completed.";
+                    const llmReaction = await petReactionEngine.generateLLM({ turnSummary, soul }, async (prompt, maxTokens) => await streamText(smallModel, {
+                        model: smallModel.model,
+                        messages: [{ role: "user", content: prompt }],
+                        maxTokens,
+                    }) || null);
+                    if (llmReaction) {
+                        deps.sendNotification("pet.reaction", {
+                            text: llmReaction.text,
+                            style: llmReaction.style,
+                            duration: 10000,
+                        });
+                        return;
+                    }
+                }
+                const reaction = petReactionEngine.maybeGenerate("turn.end");
+                if (reaction) {
+                    deps.sendNotification("pet.reaction", {
+                        text: reaction.text,
+                        style: reaction.style,
+                        duration: 10000,
+                    });
+                }
+            }
+            catch {
+                // Pet reactions are best-effort.
+            }
+        },
+        isActive() {
+            return new PetSoulService(deps.getActiveProjectRoot(), ownerUserId()).load() !== null;
+        },
+    };
+}

package/dist/cli/pet-runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/pet-runtime.test.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PetSoulService } from "../runtime/pet/pet-soul-service.js";
+import { createPetRuntime } from "./pet-runtime.js";
+const tmpDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tmpDirs.push(dir);
+    return dir;
+}
+function makeRuntime(workspace) {
+    return createPetRuntime({
+        getActiveProjectRoot: () => workspace,
+        resolveOwnerUserId: () => "user/alice",
+        resolveClientForPurpose: () => null,
+        sendNotification: () => undefined,
+    });
+}
+afterEach(() => {
+    vi.unstubAllEnvs();
+    for (const dir of tmpDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("pet runtime profile boundary", () => {
+    it("detects active pet identity from the current owner profile", async () => {
+        const home = makeTempDir("pet-runtime-home-");
+        const workspace = makeTempDir("pet-runtime-workspace-");
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        vi.stubEnv("QLOGIC_LLMROUTER_USER_ID", "user/alice");
+        await new PetSoulService(workspace).ensureSoul("user/alice");
+        expect(makeRuntime(workspace).isActive()).toBe(true);
+    });
+    it("awards turn XP to the explicit owner profile instead of the implicit active owner", async () => {
+        const home = makeTempDir("pet-runtime-home-");
+        const workspace = makeTempDir("pet-runtime-workspace-");
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        vi.stubEnv("QLOGIC_LLMROUTER_USER_ID", "user/bob");
+        await new PetSoulService(workspace, "user/alice").ensureSoul("user/alice");
+        await makeRuntime(workspace).awardXp("turn.end");
+        expect(new PetSoulService(workspace, "user/alice").load()?.experience).toBe(10);
+        expect(new PetSoulService(workspace, "user/bob").load()).toBeNull();
+    });
+});

package/dist/cli/plugin-bootstrap.d.ts

@@ -0,0 +1,15 @@
+import type { HookRegistry } from "../contracts/hooks.js";
+import type { RuntimeLogger } from "../runtime/hooks/hook-registry.js";
+import type { PathService, ToolCatalog } from "../runtime/ports/index.js";
+import { PluginLoader } from "../skills/plugins/plugin-loader.js";
+export interface PluginBootstrapDeps {
+    config: Record<string, unknown>;
+    hooks: HookRegistry;
+    log: RuntimeLogger;
+    pathService: PathService;
+    toolCatalog: ToolCatalog;
+    setPluginLoader(loader: PluginLoader): void;
+}
+export declare const pluginToolRegistrationModule: import("../runtime/ports/tool-contracts.js").ToolRegistrationModule<PluginBootstrapDeps>;
+export declare function configurePluginBootstrap(deps: PluginBootstrapDeps): void;
+export declare function resolvePluginDirsFromConfig(config: Record<string, unknown>, pathService: PathService): string[];

package/dist/cli/plugin-bootstrap.js

@@ -0,0 +1,63 @@
+import * as fs from "node:fs";
+import { defineToolRegistrationModule } from "../runtime/ports/index.js";
+import { PluginLoader } from "../skills/plugins/plugin-loader.js";
+import { resolveAllPluginDirs } from "../skills/plugins/plugin-marketplace.js";
+export const pluginToolRegistrationModule = defineToolRegistrationModule({
+    id: "plugin-tools",
+    kind: "plugin",
+    register: configurePluginBootstrapInternal,
+});
+export function configurePluginBootstrap(deps) {
+    pluginToolRegistrationModule.register(deps);
+}
+function configurePluginBootstrapInternal(deps) {
+    const pluginDirs = resolvePluginDirsFromConfig(deps.config, deps.pathService);
+    resolveAllPluginDirs(pluginDirs, deps.log).then((resolvedPluginDirs) => {
+        if (resolvedPluginDirs.length === 0)
+            return;
+        const loader = new PluginLoader({
+            pluginDirs: resolvedPluginDirs,
+            hookRegistry: deps.hooks,
+            log: deps.log,
+            toolCatalog: deps.toolCatalog,
+        });
+        deps.setPluginLoader(loader);
+        loader.loadAll().then((loaded) => {
+            deps.log.info(`[plugins] ${loaded.length} loaded, ${loader.getPluginSkills().length} skills`);
+        }).catch((err) => {
+            deps.log.warn(`[plugins] load error: ${err instanceof Error ? err.message : err}`);
+        });
+        deps.hooks.register({
+            point: "turn.submitted",
+            handler: async () => {
+                await loader.discoverNew();
+                await loader.refreshActivations();
+                return { action: "continue" };
+            },
+            label: "plugin-activation-refresh",
+            priority: 50,
+        });
+    }).catch((err) => {
+        deps.log.warn(`[plugins] marketplace resolve error: ${err instanceof Error ? err.message : err}`);
+    });
+}
+export function resolvePluginDirsFromConfig(config, pathService) {
+    const pluginDirs = [];
+    const addPluginDir = (candidate) => {
+        if (!candidate || !fs.existsSync(candidate))
+            return;
+        if (!pluginDirs.includes(candidate))
+            pluginDirs.push(candidate);
+    };
+    const userPluginDir = pathService.getUserPluginsDir();
+    addPluginDir(userPluginDir);
+    addPluginDir(pathService.getProjectPluginsDir(pathService.getActiveProjectRoot()));
+    const injectedPluginPaths = config.pluginPaths;
+    if (Array.isArray(injectedPluginPaths)) {
+        for (const candidate of injectedPluginPaths) {
+            if (typeof candidate === "string")
+                addPluginDir(candidate);
+        }
+    }
+    return pluginDirs;
+}

package/dist/cli/product-coordinator.d.ts

@@ -0,0 +1,34 @@
+import { ProductOrchestrator } from "../orchestration/agent-instance.js";
+import { ProductPlanner } from "../orchestration/product-planner.js";
+import { AgentProcessManager } from "../runtime/infra/agent-process.js";
+import type { AgentConfigStore } from "../runtime/infra/agent-config-store.js";
+import type { AcpDetector } from "../runtime/infra/acp-detector.js";
+export interface ProductCoordinatorHost {
+    acpDetector: AcpDetector;
+    agentConfigStore: AgentConfigStore | null;
+    productOrchestrator: ProductOrchestrator | null;
+    productPlanner: ProductPlanner | null;
+    productProcessManager: AgentProcessManager | null;
+    emitAgentStatus(agentId: string, state: string, extra?: {
+        missedBeats?: number;
+        lastActivityAt?: number;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+        };
+    }): void;
+    handleMcpToolCall(memberId: string, tool: string, args: Record<string, unknown>): Promise<unknown>;
+    sendNotification(method: string, params: Record<string, unknown>): void;
+}
+/** productId → 容器项目 id(R2 容器优先,与 solo-handler.soloProjectMap 对称)。终态回写用。
+ *  定义在此(callbacks 所在文件)与 solo 对称;product-handler 再导出供 ACP 入口/测试引用。 */
+export declare const productProjectMap: Map<string, string>;
+/**
+ * 终态回写 product 容器项目的 planStatus(比照 R1 solo onTerminal),并 re-push 项目使 历史方案
+ * 刷新后留存。**仅当项目仍 "running" 时迁移**——避免"完成晚到覆盖取消"或反向覆盖(R1 cancel-clobber
+ * 教训)。完成(含部分失败,planStatus 枚举无 "failed")→ "completed";取消 → "cancelled"。
+ */
+export declare function writeProductTerminalPlanStatus(host: ProductCoordinatorHost, productId: string, status: "completed" | "cancelled"): void;
+export declare function ensureProductOrchestrator(host: ProductCoordinatorHost): ProductOrchestrator;
+export declare function ensureProductPlanner(host: ProductCoordinatorHost): ProductPlanner;

package/dist/cli/product-coordinator.js

@@ -0,0 +1,124 @@
+import * as path from "node:path";
+import { ProductOrchestrator } from "../orchestration/agent-instance.js";
+import { ProductPlanner } from "../orchestration/product-planner.js";
+import { AgentProcessManager } from "../runtime/infra/agent-process.js";
+import { getDefaultPathService } from "../runtime/infra/default-path-service.js";
+import * as projectStore from "../runtime/infra/project-store.js";
+/** productId → 容器项目 id(R2 容器优先,与 solo-handler.soloProjectMap 对称)。终态回写用。
+ *  定义在此(callbacks 所在文件)与 solo 对称;product-handler 再导出供 ACP 入口/测试引用。 */
+export const productProjectMap = new Map();
+/**
+ * 终态回写 product 容器项目的 planStatus(比照 R1 solo onTerminal),并 re-push 项目使 历史方案
+ * 刷新后留存。**仅当项目仍 "running" 时迁移**——避免"完成晚到覆盖取消"或反向覆盖(R1 cancel-clobber
+ * 教训)。完成(含部分失败,planStatus 枚举无 "failed")→ "completed";取消 → "cancelled"。
+ */
+export function writeProductTerminalPlanStatus(host, productId, status) {
+    const projectId = productProjectMap.get(productId);
+    if (!projectId)
+        return;
+    const cur = projectStore.getProjectById(projectId);
+    if (!cur || cur.planStatus !== "running")
+        return; // 已终态,勿覆盖
+    projectStore.updateProject(projectId, { planStatus: status });
+    const full = projectStore.getProjectById(projectId);
+    if (full)
+        host.sendNotification("project.created", full);
+}
+export function ensureProductOrchestrator(host) {
+    if (!host.productOrchestrator) {
+        const pm = new AgentProcessManager({
+            log: {
+                info: (msg) => process.stderr.write(`[product:pm] ${msg}\n`),
+                warn: (msg) => process.stderr.write(`[product:pm] WARN ${msg}\n`),
+            },
+            onNotification: (memberId, method, params) => {
+                if (method === "agents.error" || method === "agents.status") {
+                    host.sendNotification(method, params);
+                }
+                host.sendNotification("team.member.notification", {
+                    memberId,
+                    method,
+                    params,
+                });
+            },
+            onStateChange: (memberId, state) => {
+                const handle = pm.getHandle(memberId);
+                const tracker = pm.getUsageTracker(memberId);
+                const usage = tracker?.getUsage();
+                host.emitAgentStatus(memberId, state, {
+                    missedBeats: pm.getMissedBeats(memberId),
+                    lastActivityAt: handle?.lastActivityAt,
+                    usage: usage && usage.totalTokens > 0 ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, totalTokens: usage.totalTokens } : undefined,
+                });
+            },
+            onMcpToolCall: (memberId, tool, args) => host.handleMcpToolCall(memberId, tool, args),
+            sessionDir: path.join(getDefaultPathService().getUserAgentHome(), "agent-logs"),
+        });
+        host.productOrchestrator = new ProductOrchestrator(pm, host.acpDetector, host.agentConfigStore, createProductCallbacks(host));
+        if (host.productPlanner) {
+            host.productOrchestrator.setLeaderCoordinator(host.productPlanner);
+        }
+        host.productProcessManager = pm;
+    }
+    return host.productOrchestrator;
+}
+export function ensureProductPlanner(host) {
+    if (!host.productPlanner) {
+        ensureProductOrchestrator(host);
+        host.productPlanner = new ProductPlanner(host.productProcessManager, host.acpDetector, host.agentConfigStore, {
+            log: {
+                info: (msg) => process.stderr.write(`${msg}\n`),
+                warn: (msg) => process.stderr.write(`${msg}\n`),
+            },
+            onPlanReady: (productId, plan) => {
+                host.sendNotification("product.planReady", { productId, plan });
+            },
+            onPlanFailed: (productId, error) => {
+                host.sendNotification("product.planFailed", { productId, error });
+            },
+            onPlanningDelta: (productId, text) => {
+                host.sendNotification("product.planningDelta", { productId, text });
+            },
+        });
+        host.productOrchestrator?.setLeaderCoordinator(host.productPlanner);
+    }
+    return host.productPlanner;
+}
+function createProductCallbacks(host) {
+    return {
+        log: {
+            info: (msg) => process.stderr.write(`${msg}\n`),
+            warn: (msg) => process.stderr.write(`${msg}\n`),
+        },
+        onTaskStarted: (productId, taskId, assignee) => {
+            host.sendNotification("product.taskStarted", { productId, taskId, assignee });
+        },
+        onTaskCompleted: (productId, taskId, result) => {
+            host.sendNotification("product.taskCompleted", { productId, taskId, result });
+        },
+        onTaskFailed: (productId, taskId, error) => {
+            host.sendNotification("product.taskFailed", { productId, taskId, error });
+        },
+        onCheckpointed: (productId, timestamp) => {
+            host.sendNotification("product.checkpointed", { productId, timestamp });
+        },
+        onBudgetWarning: (productId, usedTokens, maxTotalTokens, percentage) => {
+            host.sendNotification("product.budgetWarning", { productId, usedTokens, maxTotalTokens, percentage });
+        },
+        onCompleted: (productId, summary) => {
+            host.sendNotification("product.completed", { productId, summary });
+            // R2 终态回写:product 跑完(含部分失败=terminal)→ 容器项目 planStatus="completed",历史方案
+            // 显示"已完成"且刷新后留存(比照 solo onTerminal)。guard 防取消被晚到的完成覆盖。
+            writeProductTerminalPlanStatus(host, productId, "completed");
+        },
+        onDagTopology: (productId, nodes, edges) => {
+            host.sendNotification("product.dagTopology", { productId, nodes, edges });
+        },
+        onBudgetUpdate: (productId, inputTokens, outputTokens, elapsed, maxTotalTokens) => {
+            host.sendNotification("product.budgetUpdate", { productId, inputTokens, outputTokens, elapsed, maxTotalTokens });
+        },
+        onTaskOutputDelta: (productId, taskId, text) => {
+            host.sendNotification("product.taskOutput", { productId, taskId, text });
+        },
+    };
+}

package/dist/cli/product-coordinator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/product-coordinator.test.js

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+// R2 终态回写 helper(product 跑完/取消 → 容器项目 planStatus)。比照 solo onTerminal。
+// 只 mock projectStore;用真实 productProjectMap(同模块导出)。
+const { projectStoreMock } = vi.hoisted(() => ({
+    projectStoreMock: {
+        getProjectById: vi.fn(),
+        updateProject: vi.fn(),
+    },
+}));
+vi.mock("../runtime/infra/project-store.js", () => projectStoreMock);
+import { productProjectMap, writeProductTerminalPlanStatus } from "./product-coordinator.js";
+function fakeHost() {
+    return { sendNotification: vi.fn() };
+}
+describe("writeProductTerminalPlanStatus — R2 终态回写(guard 防 clobber)", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        productProjectMap.clear();
+    });
+    it("running 项目 → 写 planStatus + re-push project.created", () => {
+        productProjectMap.set("prod-1", "proj-1");
+        projectStoreMock.getProjectById.mockReturnValue({ id: "proj-1", name: "P", planStatus: "running" });
+        const host = fakeHost();
+        writeProductTerminalPlanStatus(host, "prod-1", "completed");
+        expect(projectStoreMock.updateProject).toHaveBeenCalledWith("proj-1", { planStatus: "completed" });
+        expect(host.sendNotification).toHaveBeenCalledWith("project.created", expect.objectContaining({ id: "proj-1" }));
+    });
+    it("取消同理写 cancelled", () => {
+        productProjectMap.set("prod-2", "proj-2");
+        projectStoreMock.getProjectById.mockReturnValue({ id: "proj-2", planStatus: "running" });
+        writeProductTerminalPlanStatus(fakeHost(), "prod-2", "cancelled");
+        expect(projectStoreMock.updateProject).toHaveBeenCalledWith("proj-2", { planStatus: "cancelled" });
+    });
+    it("非 running(已终态)→ 不覆盖(防完成晚到盖掉取消,反之亦然)", () => {
+        productProjectMap.set("prod-3", "proj-3");
+        projectStoreMock.getProjectById.mockReturnValue({ id: "proj-3", planStatus: "cancelled" });
+        writeProductTerminalPlanStatus(fakeHost(), "prod-3", "completed");
+        expect(projectStoreMock.updateProject).not.toHaveBeenCalled();
+    });
+    it("无 productProjectMap 绑定 → 跳过", () => {
+        writeProductTerminalPlanStatus(fakeHost(), "unbound", "completed");
+        expect(projectStoreMock.getProjectById).not.toHaveBeenCalled();
+        expect(projectStoreMock.updateProject).not.toHaveBeenCalled();
+    });
+    it("项目已不存在 → 跳过", () => {
+        productProjectMap.set("prod-4", "proj-gone");
+        projectStoreMock.getProjectById.mockReturnValue(undefined);
+        writeProductTerminalPlanStatus(fakeHost(), "prod-4", "completed");
+        expect(projectStoreMock.updateProject).not.toHaveBeenCalled();
+    });
+});

package/dist/cli/project-command-service.d.ts

@@ -0,0 +1,28 @@
+import type { ProjectInfo } from "../protocol/methods.js";
+import type { ProjectMemoryStore, ProjectMemoryStoreFactory } from "../runtime/ports/index.js";
+export interface ProjectCommandHost {
+    memdir: ProjectMemoryStore | null;
+    projectMemoryStoreFactory: ProjectMemoryStoreFactory;
+    mediaPersistence: {
+        setProjectDir(projectDir: string): void;
+    };
+    setActiveWorkdir(dir: string): void;
+}
+export interface ProjectCreateCommand {
+    name: string;
+    workspaceDir?: string;
+    type?: string;
+    groupId?: string;
+}
+export interface ProjectCreateResult {
+    project: ProjectInfo;
+    nameDuplicate?: ProjectInfo;
+    isAgentTeamProject: boolean;
+    /** True when creation switched the active project (container types never switch). */
+    autoSwitched: boolean;
+    deduplicated?: boolean;
+}
+type ProjectPlanStatus = NonNullable<ProjectInfo["planStatus"]>;
+export declare function isProjectPlanStatus(value: unknown): value is ProjectPlanStatus;
+export declare function createProject(host: ProjectCommandHost, command: ProjectCreateCommand): Promise<ProjectCreateResult>;
+export {};