@world-engines/project-host 0.1.0-alpha.0

package/dist/cli-command.js

@@ -0,0 +1,613 @@
+import { lstat, open, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sha256Hex } from "@world-engines/project-format";
+import { AuthoringBridgeError, authoringToolDescriptor } from "@world-engines/authoring-bridge";
+import { LocalProjectHost } from "./project-host.js";
+import { runProjectHostMcpStdio } from "./mcp.js";
+import { LocalPreviewRuntime, PreviewRuntimeError } from "./preview-runtime.js";
+import { ProjectTransferCoordinator } from "./transfer.js";
+import { RemoteDownloadCoordinator } from "./transfer/download.js";
+import { parseDownloadInvocation, toDownloadRemoteRequest } from "./cli/download.js";
+import { parseUploadInvocation } from "./cli/upload.js";
+import { RemoteUploadCoordinator } from "./transfer/upload.js";
+import { toPublicError } from "./public-error.js";
+import { ingestProjectDocument } from "./authoring-ingestion.js";
+import { loadProjectDocumentSource, parseProjectDocumentIngestInvocation, parseProjectDocumentOperationInvocation, resolvePathOnlyProjectDocumentIngest, stageProjectDocumentBytes } from "./cli/ingest.js";
+import { parseDocumentDumpInvocation, writeDocumentPlainTextDump } from "./cli/dump.js";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+import { answerDocumentQuestion, retrieveDocumentEvidenceBundle } from "./document-query.js";
+import { ingestLosslessDocument, readLosslessDocumentStatus, resumeLosslessDocument } from "./document-ingestion.js";
+import { prepareHarnessDocumentIngestion, nextHarnessDocumentIngestion, acceptHarnessDocumentIngestion, commitHarnessDocumentIngestion, } from "./harness-document-ingestion.js";
+import { FrozenReviewCoordinator } from "./frozen-review.js";
+import { parseReviewInvocation } from "./cli/review.js";
+import { startLocalGuiServer } from "./local-gui-server.js";
+import { prepareLocalRecallSnapshot } from "./prepared-embedding-cache.js";
+export async function verifyLocalGuiAssets(overrides = {}) {
+    const roots = {
+        source: overrides.source ?? fileURLToPath(new URL("../assets/gui/", import.meta.url)),
+        generated: overrides.generated ?? fileURLToPath(new URL("./gui/", import.meta.url)),
+    };
+    for (const [area, path] of [
+        ["source", "index.html"],
+        ["source", "app.js"],
+        ["source", "local-preview-bridge.js"],
+        ["source", "local-preview-asset-urls.js"],
+        ["source", "styles.css"],
+        ["source", "WELogo-title.svg"],
+        ["generated", "graph.js"],
+        ["generated", "graph.css"],
+        ["generated", "score.js"],
+        ["generated", "score.css"],
+        ["generated", "trigger.js"],
+        ["generated", "trigger.css"],
+        ["generated", "graph-layout-worker.js"],
+        ["generated", "graph-layout.wasm"],
+    ]) {
+        try {
+            const info = await lstat(join(roots[area], path));
+            if (!info.isFile() || info.isSymbolicLink())
+                throw new Error("not a regular file");
+        }
+        catch {
+            const error = new Error(`GUI asset 缺失：${path}`);
+            error.code = "E_GUI_UNAVAILABLE";
+            throw error;
+        }
+    }
+}
+function authoringModelConnection(runtime) {
+    return runtime.modelConnection ?? runtime.losslessIngestion?.modelConnection ?? runtime.ingestion?.modelConnection;
+}
+/** 已持久化的恢复 identity 立即写入 stderr JSONL；stdout 仍只有最终 receipt。 */
+function cliLosslessCapability(capability, io) {
+    return {
+        ...capability,
+        async onProgress(progress) {
+            io.stderr(`${JSON.stringify(progress)}\n`);
+            await capability.onProgress?.(progress);
+        },
+    };
+}
+function authoringHostOptions(runtime) {
+    const embedding = runtime.embedding ?? authoringModelConnection(runtime)?.embedding;
+    const capabilities = runtime.desktopAuthoringCapabilities;
+    return embedding === undefined && runtime.resolveEmbedding === undefined && capabilities === undefined ? {} : {
+        desktop_authoring_capabilities: {
+            ...capabilities,
+            ...(runtime.resolveEmbedding === undefined ? {} : { resolve_ladybug_embedding_port: runtime.resolveEmbedding }),
+            ...(embedding === undefined ? {} : {
+                ladybug_embedding_port: embedding,
+            }),
+        },
+    };
+}
+function writeJson(io, value) {
+    io.stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+function requiredCliValue(value, message) {
+    if (value === undefined)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", message);
+    return value;
+}
+async function readSnapshotOperation(root, operationId) {
+    const ledgerKey = await sha256Hex(new TextEncoder().encode(operationId));
+    const path = join(root, ".worldengine", "operations", `snapshot-${ledgerKey}.json`);
+    return JSON.parse(await readFile(path, "utf8"));
+}
+/**
+ * 根脚本 `worldengine snapshot` 没有可由调用方持久化的 effect identity。
+ * 因此把项目 authority 中已经 readback 的 identity 和本命令固定请求一起哈希；
+ * 同一 project/revision 的崩溃重试会回到同一 durable ledger，而不会盲目生成新 ID。
+ */
+async function deriveImplicitSnapshotOperation(projectId, expectedProjectRevision) {
+    const canonicalRequest = JSON.stringify({
+        command: "worldengine.snapshot.v1",
+        project_id: projectId,
+        expected_project_revision: expectedProjectRevision,
+    });
+    const digest = await sha256Hex(new TextEncoder().encode(canonicalRequest));
+    return `snapshot_${digest}`;
+}
+function parseToolCall(name, input, identityArgs) {
+    if (name === undefined) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool 需要 name 与 input JSON");
+    }
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input 必须是 JSON object");
+    }
+    const descriptor = authoringToolDescriptor(name);
+    if (!descriptor.project_effect) {
+        if (identityArgs.length !== 0)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "只读 tool 不接受 effect identity");
+        return { name: name, input: input };
+    }
+    const [operationId, expectedProjectRevision] = identityArgs;
+    if (operationId === undefined || expectedProjectRevision === undefined || identityArgs.length !== 2 || !/^\d+$/.test(expectedProjectRevision)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "effect tool 需要稳定 operation_id 与 expected_project_revision");
+    }
+    return {
+        name: name,
+        input: input,
+        effect_identity: { operation_id: operationId, expected_project_revision: Number(expectedProjectRevision) },
+    };
+}
+async function readProjectToolInputJson(projectRoot, inputPath) {
+    const path = await assertSafeExistingProjectPath(projectRoot, resolve(projectRoot, inputPath));
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 8 * 1024 * 1024) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input JSON 文件无效或过大");
+    }
+    const handle = await open(path, "r");
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > 8 * 1024 * 1024 || before.dev !== info.dev || before.ino !== info.ino) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input JSON 文件无效或过大");
+        }
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || bytes.byteLength !== after.size)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input JSON 文件读取期间发生变化");
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input JSON 文件必须是 JSON");
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function parseProjectToolCall(projectRoot, args) {
+    const [name, input, ...rest] = args;
+    if (input === "--input-json-file") {
+        const [inputPath, ...identityArgs] = rest;
+        if (inputPath === undefined)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool --input-json-file 需要项目相对 JSON 文件");
+        return parseToolCall(name, await readProjectToolInputJson(projectRoot, inputPath), identityArgs);
+    }
+    if (input === undefined)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool 需要 name 与 input JSON");
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tool input 必须是 JSON object");
+    }
+    return parseToolCall(name, parsed, rest);
+}
+export async function runWorldengineCli(args, cwd, io, previewRuntime = new LocalPreviewRuntime(), downloadRuntime = {}, uploadRuntime = {}, authoringRuntime = {}, reviewRuntime = {}, guiRuntime = {}) {
+    try {
+        const [command, subcommand, operand] = args;
+        if (command === undefined || command === "help" || command === "--help") {
+            io.stdout("worldengine doctor | snapshot [operation_id expected_project_revision] | tool <registered-tool-name> <input-json>|--input-json-file <project-relative-json> [operation_id expected_project_revision] | ingest <path> <scope-id> <source-id> <source-revision> | ingest status|next|resume|commit <operation-id> | ingest accept <operation-id> <request-id> <candidate-json-file> | status|resume <operation-id> | ask <scope-id> <query> | dump <document-id> <output-relative-dir> | recall prepare [scope-id] | recall <query> [limit] | read <entity-id> | review prepare|submit|status | sync status | operation <id> | upload plan|confirm|operation|reconcile|retry|undo|bind-review-target | download plan|confirm|operation|reconcile|restore | preview | gui | mcp\n");
+            return 0;
+        }
+        if (command === "mcp") {
+            if (args.length === 1)
+                return await runProjectHostMcpStdio(cwd, undefined, authoringHostOptions(authoringRuntime));
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "mcp 参数无效");
+        }
+        const host = await LocalProjectHost.open(cwd, authoringHostOptions(authoringRuntime));
+        try {
+            if (command === "doctor") {
+                const report = await host.doctor();
+                writeJson(io, report);
+                return report.ok ? 0 : 1;
+            }
+            if (command === "snapshot") {
+                let operationId;
+                let expectedProjectRevision;
+                if (args.length === 1) {
+                    const status = await host.inspect();
+                    expectedProjectRevision = status.project_revision;
+                    operationId = await deriveImplicitSnapshotOperation(status.project_id, expectedProjectRevision);
+                }
+                else if (subcommand !== undefined && operand !== undefined && args.length === 3 && /^\d+$/.test(operand)) {
+                    operationId = subcommand;
+                    expectedProjectRevision = Number(operand);
+                }
+                else {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "snapshot 需要稳定 operation_id 与 expected_project_revision");
+                }
+                writeJson(io, await host.snapshot({
+                    operation_id: operationId,
+                    expected_project_revision: expectedProjectRevision,
+                }));
+                return 0;
+            }
+            if (command === "sync" && subcommand === "status") {
+                try {
+                    const status = await host.inspect();
+                    const transfer = await ProjectTransferCoordinator.open(host.root);
+                    writeJson(io, {
+                        ...(await transfer.status()),
+                        snapshot_id: status.snapshot_id,
+                        snapshot_digest: status.snapshot_digest,
+                    });
+                    return 0;
+                }
+                catch (error) {
+                    io.stderr(`${toPublicError(error, "E_VALIDATION_FAILED").code}: 请求失败\n`);
+                    return 1;
+                }
+            }
+            if (command === "operation" && subcommand !== undefined) {
+                writeJson(io, await readSnapshotOperation(host.root, subcommand));
+                return 0;
+            }
+            if (command === "download") {
+                const invocation = parseDownloadInvocation(args.slice(1));
+                const status = await host.inspect();
+                const coordinator = await RemoteDownloadCoordinator.open(host.root, status.project_id, downloadRuntime.transport, downloadRuntime.dependencies);
+                if (invocation.kind === "plan") {
+                    writeJson(io, await coordinator.plan(toDownloadRemoteRequest(status.project_id, invocation)));
+                    return 0;
+                }
+                if (invocation.kind === "confirm") {
+                    const plan = requiredCliValue(invocation.plan, "download confirm 缺少 plan");
+                    const planDigest = requiredCliValue(invocation.plan_digest, "download confirm 缺少 plan digest");
+                    const operation = await coordinator.confirm(plan, planDigest);
+                    writeJson(io, { operation, receipt: await coordinator.apply(plan, operation) });
+                    return 0;
+                }
+                if (invocation.kind === "restore") {
+                    const operationId = requiredCliValue(invocation.operation_id, "download restore 缺少 operation_id");
+                    await coordinator.restore(operationId);
+                    writeJson(io, { operation_id: invocation.operation_id, restored: true });
+                    return 0;
+                }
+                writeJson(io, await coordinator.operation(requiredCliValue(invocation.operation_id, "download operation 缺少 operation_id"), invocation.kind === "reconcile"));
+                return 0;
+            }
+            if (command === "upload") {
+                const invocation = parseUploadInvocation(args.slice(1));
+                const status = await host.inspect();
+                const coordinator = await RemoteUploadCoordinator.open(host.root, status.project_id, uploadRuntime.transport ?? downloadRuntime.transport);
+                if (invocation.kind === "plan") {
+                    // upload 只能消费已经由同一稳定 operation identity 冻结的 Project Snapshot。
+                    const operationId = requiredCliValue(invocation.operation_id, "upload plan 缺少 operation_id");
+                    const expectedProjectRevision = requiredCliValue(invocation.expected_project_revision, "upload plan 缺少 expected_project_revision");
+                    const expiresAtMs = requiredCliValue(invocation.expires_at_ms, "upload plan 缺少 expires_at_ms");
+                    const targets = requiredCliValue(invocation.targets, "upload plan 缺少 targets");
+                    await host.snapshot({ operation_id: operationId, expected_project_revision: expectedProjectRevision });
+                    writeJson(io, await coordinator.plan({ operation_id: operationId, expires_at_ms: expiresAtMs, targets }));
+                    return 0;
+                }
+                if (invocation.kind === "confirm") {
+                    const plan = invocation.plan;
+                    if (invocation.plan_digest === undefined) {
+                        if (io.confirmUploadTarget === undefined)
+                            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "非交互 upload 必须提供 --confirm-plan <digest>");
+                        for (const target of plan.targets) {
+                            if (!(await io.confirmUploadTarget(target)))
+                                throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "upload 未获得逐目标明确确认");
+                        }
+                    }
+                    writeJson(io, await coordinator.confirm(plan, invocation.plan_digest ?? plan.plan_digest));
+                    return 0;
+                }
+                if (invocation.kind === "retry") {
+                    writeJson(io, await coordinator.retry(requiredCliValue(invocation.operation_id, "upload retry 缺少 operation_id")));
+                    return 0;
+                }
+                if (invocation.kind === "undo") {
+                    writeJson(io, await coordinator.undo(requiredCliValue(invocation.operation_id, "upload undo 缺少 operation_id")));
+                    return 0;
+                }
+                if (invocation.kind === "bind-review-target") {
+                    writeJson(io, await coordinator.bindFrozenReviewTarget(requiredCliValue(invocation.operation_id, "upload bind-review-target 缺少 operation_id"), invocation.client_target_key === undefined ? {} : { client_target_key: invocation.client_target_key }));
+                    return 0;
+                }
+                writeJson(io, await coordinator.operation(requiredCliValue(invocation.operation_id, "upload operation 缺少 operation_id"), invocation.kind === "reconcile"));
+                return 0;
+            }
+            if (command === "review") {
+                const invocation = parseReviewInvocation(args.slice(1));
+                const status = await host.inspect();
+                const coordinator = await FrozenReviewCoordinator.open(host.root, status.project_id, {
+                    ...(reviewRuntime.pipeline === undefined ? {} : { pipeline: reviewRuntime.pipeline }),
+                    ...(reviewRuntime.transport ?? uploadRuntime.transport ?? downloadRuntime.transport) === undefined
+                        ? {}
+                        : { transport: reviewRuntime.transport ?? uploadRuntime.transport ?? downloadRuntime.transport },
+                    ...(reviewRuntime.recovery === undefined ? {} : { recovery: reviewRuntime.recovery }),
+                });
+                if (invocation.kind === "status") {
+                    writeJson(io, await coordinator.status(invocation.operation_key));
+                }
+                else if (invocation.kind === "prepare") {
+                    writeJson(io, await coordinator.prepare(invocation));
+                }
+                else {
+                    writeJson(io, await coordinator.submit(invocation));
+                }
+                return 0;
+            }
+            if (command === "tool") {
+                writeJson(io, await host.dispatchTool(await parseProjectToolCall(host.root, args.slice(1))));
+                return 0;
+            }
+            if (command === "dump") {
+                writeJson(io, await writeDocumentPlainTextDump(host, parseDocumentDumpInvocation(args.slice(1))));
+                return 0;
+            }
+            if (command === "ingest" && ["next", "accept", "commit"].includes(subcommand ?? "")) {
+                if (operand === undefined)
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ingest 需要 operation-id");
+                if (subcommand === "accept") {
+                    const requestId = args[3];
+                    const candidatePath = args[4];
+                    if (args.length !== 5 || requestId === undefined || candidatePath === undefined) {
+                        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ingest accept 需要 operation-id/request-id/candidate-json-file");
+                    }
+                    const safePath = await assertSafeExistingProjectPath(host.root, resolve(host.root, candidatePath));
+                    const info = await lstat(safePath);
+                    if (!info.isFile() || info.isSymbolicLink() || info.size > 8 * 1024 * 1024)
+                        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "抽取结果文件无效或过大");
+                    let candidate;
+                    const candidateHandle = await open(safePath, "r");
+                    try {
+                        const before = await candidateHandle.stat();
+                        if (!before.isFile() || before.size > 8 * 1024 * 1024 || before.dev !== info.dev || before.ino !== info.ino) {
+                            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "抽取结果文件无效或过大");
+                        }
+                        const bytes = await candidateHandle.readFile();
+                        const after = await candidateHandle.stat();
+                        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+                            || bytes.byteLength !== after.size)
+                            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "抽取结果文件读取期间发生变化");
+                        candidate = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+                    }
+                    catch {
+                        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "抽取结果必须是 JSON");
+                    }
+                    finally {
+                        await candidateHandle.close();
+                    }
+                    writeJson(io, await acceptHarnessDocumentIngestion(host.root, operand, requestId, candidate));
+                }
+                else {
+                    if (args.length !== 3)
+                        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ingest next/commit 参数无效");
+                    writeJson(io, subcommand === "next"
+                        ? await nextHarnessDocumentIngestion(host.root, operand)
+                        : await commitHarnessDocumentIngestion(host, host.root, operand));
+                }
+                return 0;
+            }
+            if (command === "status" || command === "resume" || (command === "ingest" && (subcommand === "status" || subcommand === "resume"))) {
+                let invocation;
+                try {
+                    invocation = parseProjectDocumentOperationInvocation(command === "ingest" ? args.slice(1) : args);
+                }
+                catch {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "status/resume 需要稳定 operation-id");
+                }
+                const status = await readLosslessDocumentStatus(host.root, invocation.operationId);
+                if (invocation.kind === "status") {
+                    writeJson(io, status);
+                }
+                else if (status.method?.version === "harness-v1") {
+                    const next = await nextHarnessDocumentIngestion(host.root, invocation.operationId);
+                    writeJson(io, next.state === "ready_to_commit" || next.state === "committed"
+                        ? await commitHarnessDocumentIngestion(host, host.root, invocation.operationId)
+                        : next);
+                }
+                else {
+                    if (authoringRuntime.losslessIngestion === undefined)
+                        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "旧 operation 需要原执行适配器，不能静默改成 harness 方法", { failure: "E_CAPABILITY_UNAVAILABLE" });
+                    writeJson(io, await resumeLosslessDocument(host, invocation.operationId, cliLosslessCapability(authoringRuntime.losslessIngestion, io)));
+                }
+                return 0;
+            }
+            if (command === "ingest") {
+                if (args.length === 2) {
+                    let resolved;
+                    try {
+                        resolved = await resolvePathOnlyProjectDocumentIngest(host.root, requiredCliValue(args[1], "ingest 需要原文路径"));
+                    }
+                    catch {
+                        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ingest 单路径参数或项目原文无效");
+                    }
+                    // 单路径模式只准备 harness 请求。只有用户的 harness 可在稍后经 ingest accept 提交候选。
+                    const prepared = await prepareHarnessDocumentIngestion(host, {
+                        bytes: resolved.source.bytes,
+                        scopeId: resolved.source.scopeId,
+                        sourceId: resolved.source.sourceId,
+                        sourceRevision: resolved.source.sourceRevision,
+                        sourcePath: resolved.source.sourcePath,
+                        ...(resolved.source.sourceStoragePath === undefined ? {} : { sourceStoragePath: resolved.source.sourceStoragePath }),
+                    }, { projectRoot: host.root });
+                    writeJson(io, {
+                        mode: "path-only-harness-prepare-v1",
+                        resolved_source: {
+                            scope_id: resolved.invocation.scopeId,
+                            source_id: resolved.invocation.sourceId,
+                            source_revision: resolved.invocation.sourceRevision,
+                            source_path: resolved.source.sourcePath,
+                            ...(resolved.source.sourceStoragePath === undefined ? {} : { source_storage_path: resolved.source.sourceStoragePath }),
+                        },
+                        preparation: prepared,
+                    });
+                    return 0;
+                }
+                let invocation;
+                try {
+                    invocation = parseProjectDocumentIngestInvocation(args.slice(1));
+                }
+                catch {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ingest 参数无效");
+                }
+                if (authoringRuntime.losslessIngestion === undefined && authoringRuntime.ingestion === undefined) {
+                    const source = await stageProjectDocumentBytes(host.root, invocation);
+                    writeJson(io, await prepareHarnessDocumentIngestion(host, {
+                        bytes: source.bytes, scopeId: source.scopeId, sourceId: source.sourceId,
+                        sourceRevision: source.sourceRevision, sourcePath: source.sourcePath,
+                        ...(source.sourceStoragePath === undefined ? {} : { sourceStoragePath: source.sourceStoragePath }),
+                    }, { projectRoot: host.root }));
+                }
+                else if (authoringRuntime.losslessIngestion !== undefined) {
+                    const source = await stageProjectDocumentBytes(host.root, invocation);
+                    writeJson(io, await ingestLosslessDocument(host, {
+                        bytes: source.bytes,
+                        scopeId: source.scopeId,
+                        sourceId: source.sourceId,
+                        sourceRevision: source.sourceRevision,
+                        sourcePath: source.sourcePath,
+                        ...(source.sourceStoragePath === undefined ? {} : { sourceStoragePath: source.sourceStoragePath }),
+                    }, cliLosslessCapability(authoringRuntime.losslessIngestion, io)));
+                }
+                else {
+                    writeJson(io, await ingestProjectDocument(host, await loadProjectDocumentSource(host.root, invocation), authoringRuntime.ingestion));
+                }
+                return 0;
+            }
+            if (command === "recall" && subcommand === "prepare") {
+                if (args.length > 3)
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "recall prepare 仅接受可选 scope-id");
+                const embedding = await authoringRuntime.resolveEmbedding?.() ?? authoringRuntime.embedding ?? authoringModelConnection(authoringRuntime)?.embedding;
+                if (embedding?.origin === undefined)
+                    throw new AuthoringBridgeError("E_AUTH_REQUIRED", "请先在本地 GUI 登录并启动账户模型代理");
+                const prepared = await prepareLocalRecallSnapshot(host, { ...embedding, origin: embedding.origin }, operand === undefined ? {} : { scopeId: operand });
+                writeJson(io, {
+                    status: "prepared", project_id: prepared.project_id, project_revision: prepared.project_revision,
+                    source_sha256: prepared.source_sha256, scope_id: prepared.scope_id,
+                    entity_count: prepared.snapshot.batch.entries.length,
+                    descriptor: prepared.snapshot.batch.descriptor,
+                    readback_verified: true,
+                });
+                return 0;
+            }
+            if (command === "recall") {
+                if (subcommand === undefined || args.length > 3 || (operand !== undefined && !/^\d+$/.test(operand))) {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "recall 需要 query 与可选 limit");
+                }
+                writeJson(io, await host.dispatchTool({
+                    name: "world_search",
+                    input: { query: subcommand, mode: "semantic", ...(operand === undefined ? {} : { limit: Number(operand) }) },
+                }));
+                return 0;
+            }
+            if (command === "ask") {
+                const modelConnection = authoringModelConnection(authoringRuntime);
+                if (subcommand === undefined || operand === undefined || args.length !== 3) {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ask 需要 scope-id 与 query");
+                }
+                // npm 作者路径只返回可验证证据，由当前 harness 推理；保留显式内部 adapter 的历史验收。
+                writeJson(io, modelConnection === undefined
+                    ? await retrieveDocumentEvidenceBundle(host, { scopeId: subcommand, query: operand })
+                    : await answerDocumentQuestion(host, { scopeId: subcommand, query: operand }, { modelConnection }));
+                return 0;
+            }
+            if (command === "read") {
+                if (subcommand === undefined || args.length !== 2) {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "read 需要 entity-id");
+                }
+                writeJson(io, await host.dispatchTool({ name: "world_get", input: { ids: [subcommand], include_relations: true } }));
+                return 0;
+            }
+            if (command === "preview") {
+                try {
+                    writeJson(io, await previewRuntime.start(host.root));
+                    return 0;
+                }
+                catch (error) {
+                    if (error instanceof PreviewRuntimeError) {
+                        io.stderr(`${toPublicError(error).code}: 请求失败\n`);
+                        return 1;
+                    }
+                    throw error;
+                }
+            }
+            if (command === "gui") {
+                const guiArgs = args.slice(1);
+                if (guiArgs.length > 1 || (guiArgs[0] !== undefined && !["--no-open", "--check"].includes(guiArgs[0]))) {
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "gui 只接受 --no-open 或 --check");
+                }
+                if (guiArgs[0] === "--check") {
+                    await verifyLocalGuiAssets();
+                    return 0;
+                }
+                const commandOutputLimit = 1024 * 1024;
+                const runCommand = async (commandArgs, context) => {
+                    let stdout = "";
+                    let stderr = "";
+                    const append = (current, text) => {
+                        if (Buffer.byteLength(current, "utf8") + Buffer.byteLength(text, "utf8") > commandOutputLimit) {
+                            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "GUI command 输出超过上限");
+                        }
+                        return current + text;
+                    };
+                    const commandRuntimes = context.auth === undefined || guiRuntime.runtimesForTransport === undefined
+                        ? { download: downloadRuntime, upload: uploadRuntime, review: reviewRuntime }
+                        : guiRuntime.runtimesForTransport(context.auth.transport);
+                    const exitCode = await runWorldengineCli(commandArgs, host.root, {
+                        stdout: (text) => { stdout = append(stdout, text); },
+                        stderr: (text) => { stderr = append(stderr, text); },
+                    }, previewRuntime, commandRuntimes.download, commandRuntimes.upload, authoringRuntime, commandRuntimes.review, guiRuntime);
+                    if (exitCode !== 0) {
+                        const reportedCode = /^(E_[A-Z0-9_]+): 请求失败$/m.exec(stderr)?.[1];
+                        const candidate = Object.assign(new Error("GUI command failed"), { code: reportedCode ?? "E_VALIDATION_FAILED" });
+                        const error = Object.assign(new Error(`GUI command 退出码 ${exitCode}`), { code: toPublicError(candidate, "E_VALIDATION_FAILED").code });
+                        throw error;
+                    }
+                    return { exitCode, stdout, stderr };
+                };
+                const options = {
+                    hostOptions: authoringHostOptions(authoringRuntime),
+                    runCommand,
+                    previewRuntime,
+                    authOptions: {},
+                };
+                const server = await (guiRuntime.startServer ?? startLocalGuiServer)(host.root, options);
+                let modelProxy;
+                let closed = false;
+                const managedServer = {
+                    ...server,
+                    async close() {
+                        if (closed)
+                            return;
+                        closed = true;
+                        try {
+                            await modelProxy?.close();
+                        }
+                        finally {
+                            await server.close();
+                        }
+                    },
+                };
+                try {
+                    modelProxy = await guiRuntime.startModelProxy?.(server, {
+                        root: host.root,
+                        project_id: (await host.inspect()).project_id,
+                    });
+                    guiRuntime.onServerStarted?.(managedServer);
+                    if (guiArgs[0] !== "--no-open")
+                        await guiRuntime.openBrowser?.(server.url);
+                    writeJson(io, { status: "listening", url: server.url });
+                }
+                catch (error) {
+                    await managedServer.close();
+                    throw error;
+                }
+                return 0;
+            }
+            if (command === "operation" && operand !== undefined) {
+                writeJson(io, await readSnapshotOperation(host.root, operand));
+                return 0;
+            }
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "未知命令");
+        }
+        finally {
+            await host.close();
+        }
+    }
+    catch (error) {
+        const publicError = toPublicError(error);
+        io.stderr(`${publicError.code}: 请求失败\n`);
+        return publicError.code === "E_SCHEMA_INVALID" ? 2 : 1;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};