yugoo-design 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Yugoo Design
 
-Package: `yugoo-design@0.1.0`.
+Package: `yugoo-design@0.1.2`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -55,7 +55,7 @@ from another operating system requires an explicit Windows path and reports that
 locator as unverified; it does not establish target runtime acceptance.
 
 ```sh
-ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact yugoo-design@0.1.0 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact yugoo-design@0.1.2 --registry=https://registry.npmjs.org
 npx --no-install yugoo-design --help
 ```
 
@@ -72,7 +72,7 @@ allowBuilds:
 ```
 
 ```sh
-ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact yugoo-design@0.1.0 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact yugoo-design@0.1.2 --registry=https://registry.npmjs.org
 pnpm exec yugoo-design --help
 ```
 
@@ -121,7 +121,7 @@ process value:
 $previousOrtCuda = [Environment]::GetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', 'Process')
 try {
   $env:ONNXRUNTIME_NODE_INSTALL_CUDA = 'skip'
-  npm install --ignore-scripts=false --save-exact yugoo-design@0.1.0 --registry=https://registry.npmjs.org
+  npm install --ignore-scripts=false --save-exact yugoo-design@0.1.2 --registry=https://registry.npmjs.org
 } finally {
   [Environment]::SetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', $previousOrtCuda, 'Process')
 }
@@ -139,6 +139,34 @@ layout. A tokenizer or one weight file alone does not establish a usable cache.
 Use the acquired version's model identity; changing the model/revision or copying
 an arbitrary cache is not a supported repair.
 
+When the acquired `yugoo-design --help` lists `prepare-embedding`, run it from
+that installation directory under the actual runtime user and OS:
+
+```sh
+npx --no-install yugoo-design prepare-embedding
+# Only when downloading the fixed model has been allowed:
+npx --no-install yugoo-design prepare-embedding --allow-download --probe
+```
+
+The default command is an offline size/hash inspection: it creates no cache,
+lock or network request. `--allow-download` prepares the four pinned files
+(about 135 MB total), reusing verified files and resumable downloads. `--probe`
+performs real local CPU inference with fixed synthetic text; use it without
+`--allow-download` to test an existing cache. An explicitly selected cache can
+be passed as `--embedding-cache /absolute/cache`; use that same cache for the
+runtime. No Design Project or host registration is needed for preparation.
+
+`assets-ready` means the files passed integrity checks and CPU inference has not
+been tested; `ready` means the CPU probe also passed. `unavailable` reports the
+resource or inference failure and exits unsuccessfully. None of these results
+proves semantic KAG is current for a real project. Respect an explicitly disabled
+embedding configuration. Preparation does not change DSH's provider or model
+settings; it is relevant only when DSH uses this same default local model/cache.
+
+Published `0.1.0` does not include this command. Follow that package's existing
+runtime route below, or update to a published version whose help includes it;
+do not pass the new command to an older installation.
+
 For the shared runtime's `scripts/design.mjs serve` entry used by Codex, Claude
 Code, Qoder and QwenWork, the default is **local-only** model loading. Its runtime
 help documents `--allow-embedding-download`: when explicitly allowed, this permits
@@ -150,11 +178,12 @@ semantic embeddings. Neither option changes host model credentials. Model-file
 download and CPU inference do not upload Design text.
 
 WorkBuddy's `yugoo_workbuddy_open_panel` service currently fixes `localOnly: true`
-and exposes no model-download parameter. It requires the existing complete cache
-for its Windows runtime user; the CLI flag above does not add a WorkBuddy download
-route. If the cache is missing, report that limitation and the semantic-index
-diagnostic. Do not invent an installer flag, change host identity or start another
-host's service to bypass it. Authorized design work can continue from Design Files
+and exposes no model-download parameter. It requires a complete cache
+for its Windows runtime user. A package with `prepare-embedding` can prepare that
+cache before the service starts; the older runtime `serve` flag does not add a
+WorkBuddy download route. If preparation is unavailable or fails, report the
+semantic-index diagnostic. Do not change host identity or start another host's
+service to bypass it. Authorized design work can continue from Design Files
 and structural evidence; do not report semantic KAG as ready. DSH follows its own
 provider configuration rather than these Companion `serve` flags.
 

package/bin/installer.mjs

@@ -14,6 +14,7 @@ import { codexAdapter, assertCodexAdmission, createCodexNativeAdapter } from './
 import { createClaudeNativeAdapter, planClaudeInstallation, applyClaudeInstallation, recoverClaudeInstallation } from './npm-installer-claude.mjs'
 import { installQoderPlugin } from './npm-installer-qoder.mjs'
 import { checkRuntime, inspectRuntime, assertInstalledRuntimeReceipt } from './npm-runtime-check.mjs'
+import { embeddingPreparationMain } from './npm-embedding-preparation.mjs'
 import { runDesktopDshInstaller } from './npm-installer-dsh-desktop.mjs'
 import { desktopPreparationMain, desktopPreparationReuseMain } from './npm-desktop-preparation.mjs'
 import { agentInstallation, AGENT_INSTALL_HOSTS, DESKTOP_INSTALL_OPTIONS } from './npm-agent-installation.mjs'
@@ -774,6 +775,7 @@ export async function nativePluginDirectory({npmRoot,host}) {
 
 export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=codexAdapter,dshAdapterFactory=createDshInstallerAdapter,claudeAdapterFactory=createClaudeNativeAdapter,qoderInstaller=installQoderPlugin,agentDispatch=true,signal,dshInstallTimeoutMs}={}) {
   if(args[0]==='prepare-desktop')return desktopPreparationMain(args.slice(1),{npmRoot})
+  if(args[0]==='prepare-embedding')return embeddingPreparationMain(args.slice(1),{npmRoot,signal})
   const {values,positionals}=parseArgs({args,allowPositionals:true,options:{host:{type:'string'},'dry-run':{type:'boolean'},
     help:{type:'boolean',short:'h'},apply:{type:'boolean'},plan:{type:'string'},'receipt-dir':{type:'string'},receipt:{type:'string'},'runtime-receipt':{type:'string'},'codex-executable':{type:'string'},'claude-executable':{type:'string'},'user-root':{type:'string'},'disable-embedding':{type:'boolean'},
     'qoder-executable':{type:'string'},'qoder-config-dir':{type:'string'},
@@ -785,6 +787,7 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
     commands:{
       'resolve-node':'Discover and verify an existing compatible Node without a host, npm package or configuration writes.',
       'prepare-desktop':'Prepare a small QwenWork suite or stable WorkBuddy market from this exact acquired npm package. Uses --target, --package-name/--package-version, --suite-version, --node-executable and an external --destination; does not register a host. Updates use the previous preparation receipt.',
+      'prepare-embedding':'Check the fixed local model cache; --allow-download explicitly prepares resources and --probe verifies actual offline CPU inference. No host or project required.',
       install:'The current Agent selects --host from trusted context or one user choice. Direct install orchestrates existing native routes or Codex Desktop/QwenWork/WorkBuddy preparation. Missing inputs and pending activation are explicit. Existing --dry-run / --apply remain available.',
       'plugin-directory':'Inspect the optional Claude/Qoder session-only --plugin-dir entry; this is not persistent installation.',
       'check-runtime':'Check runtime prerequisites and write an external runtime receipt; does not install.',

package/bin/npm-agent-installation.mjs

@@ -30,32 +30,35 @@ function pending(host, status, missing, message) {
     installation: { host: host ?? null, acquisition: 'unverified', registration: 'not-performed',
       activation: 'not-performed', usability: 'unverified', nextActions: [{ action: 'supply-inputs', automatic: false, message }] } }
 }
-function activationActions(host, result) {
+function activationActions(host, result, disableEmbedding) {
+  const embedding = disableEmbedding ? [] : [{ action: 'prepare-local-embedding', automatic: true,
+    command: ['prepare-embedding'],
+    message: 'Use this acquired product\'s prepare-embedding to check the fixed model cache under the actual runtime user and operating system. Match the runtime\'s --embedding-cache and selected Node; a WSL cache is not a Windows runtime cache. Reuse complete files. If resources are missing or invalid, explain the model download and use --allow-download only when permitted; use --probe to verify CPU inference. DSH custom provider/model settings remain owned by DSH and must not be replaced with defaults. Report resource integrity, CPU inference and the real project\'s semantic status separately. Missing embeddings do not block basic design or available source-projection context.' }]
   const verify = { action: 'verify-native-session', automatic: true,
     message: 'In the intended native conversation, verify the actually loaded Yugoo Design version and tools; then open a project and verify Panel save/reopen and original-conversation receipt. Registration alone is not usability.' }
   if (host === 'codex-desktop') return [
     { action: 'activate-native-plugin', automatic: false, path: result.marketplacePath,
-      message: 'Install or update this exact prepared local Yugoo Design source through Codex Desktop. If a normal restart is required, keep and return to the current conversation. Retain the exact npm version and previous owned source until the loaded version is verified.' }, verify]
+      message: 'Install or update this exact prepared local Yugoo Design source through Codex Desktop. If a normal restart is required, keep and return to the current conversation. Retain the exact npm version and previous owned source until the loaded version is verified.' }, ...embedding, verify]
   if (host === 'qwenwork') return [
     { action: 'import-expert-suite', automatic: false, path: result.nativeImport?.archive,
       message: 'Import this exact expert-suite ZIP through QwenWork. If bundled MCP is disabled by organization policy, use the emitted connector configuration and retain exactly one Yugoo Design connector.' },
     { action: 'activate-native-suite', automatic: false,
-      message: 'Enable the imported suite; start a new native conversation if QwenWork requires it. Retain the acquired npm runtime and confirm the actually loaded suite version.' }, verify]
+      message: 'Enable the imported suite; start a new native conversation if QwenWork requires it. Retain the acquired npm runtime and confirm the actually loaded suite version.' }, ...embedding, verify]
   if (host === 'workbuddy') return [
     { action: 'import-or-update-market', automatic: false, path: result.nativeImport?.market,
       message: 'Import this stable marketplace through WorkBuddy, or refresh the same market and update its existing Yugoo Design plugin. Preparation has not registered or activated it.' },
     { action: 'activate-native-plugin', automatic: false,
-      message: 'Enable the plugin and start a new native conversation if WorkBuddy requires it; confirm the actually loaded suite version.' }, verify]
+      message: 'Enable the plugin and start a new native conversation if WorkBuddy requires it; confirm the actually loaded suite version.' }, ...embedding, verify]
   return [{ action: 'activate-native-session', automatic: false,
     message: host === 'dsh'
       ? 'Use the selected existing DSH profile and the host-supported plugin activation/restart flow; verify runtime loading in a new native session.'
       : host === 'codex'
         ? 'Start a new Codex conversation normally in the intended workspace and invoke the installed yugoo Skill through the native Skill entry. Retain the registered npm runtime.'
-        : 'Start a new native host conversation normally in the intended workspace and invoke /yugoo-design:yugoo. Retain the registered npm runtime; no --plugin-dir is needed.' }, verify]
+        : 'Start a new native host conversation normally in the intended workspace and invoke /yugoo-design:yugoo. Retain the registered npm runtime; no --plugin-dir is needed.' }, ...embedding, verify]
 }
 
 /** Project only verified facts from the owning native/preparation receipt. */
-export function installationResult(host, result, packageIdentity) {
+export function installationResult(host, result, packageIdentity, { disableEmbedding = false } = {}) {
   const failed = result.status === 'failed-partial-state-retained'
   const desktop = host === 'qwenwork' || host === 'workbuddy' || host === 'codex-desktop'
   const registered = !desktop && !failed && (result.hostRegistered === true
@@ -68,9 +71,10 @@ export function installationResult(host, result, packageIdentity) {
       registryAcquisitionVerified: false,
       registration: failed ? 'failed-partial-state-retained' : registered ? 'verified' : 'not-performed',
       activation: failed ? 'not-performed' : 'required', usability: 'unverified',
+      embedding: { status: disableEmbedding ? 'disabled' : 'unverified', blocksBasicDesign: false },
       nextActions: failed ? [{ action: 'inspect-retained-state', automatic: false, path: result.receiptFile,
         message: 'Inspect the owning receipt and retained DSH state before another operation. No automatic rollback or retry was attempted.' }]
-        : activationActions(host, result) } }
+        : activationActions(host, result, disableEmbedding) } }
 }
 
 export async function agentInstallation(values, { npmRoot, invoke, desktopPrepare, desktopReuse, codexDesktopPrepare,
@@ -116,7 +120,7 @@ export async function agentInstallation(values, { npmRoot, invoke, desktopPrepar
       return installationResult(host, reused || await desktopPrepare(args))
     }
     if (host === 'claude-code' || host === 'qoder')
-      return installationResult(host, await invoke(argv('install', values, allowed)))
+      return installationResult(host, await invoke(argv('install', values, allowed)), undefined, { disableEmbedding: values['disable-embedding'] === true })
     // DSH's exclusive plan files are never overwritten. Each direct operation gets
     // its own receipt subdirectory; Codex keeps the stable directory needed by upgrades.
     const nativeValues = host === 'dsh' ? { ...values, 'receipt-dir': join(values['receipt-dir'], randomUUID()) } : values
@@ -135,7 +139,7 @@ export async function agentInstallation(values, { npmRoot, invoke, desktopPrepar
       assert.ok(runtime.receiptFile, 'The owning runtime checker did not retain its receipt')
       const applyArgs = argv('install', values, allowed.filter(key => !['receipt-dir', 'disable-embedding', 'node-executable'].includes(key)))
       applyArgs.push('--apply', '--plan', plan.planFile, '--runtime-receipt', runtime.receiptFile)
-      return installationResult(host, await invoke(applyArgs), plan.package)
+      return installationResult(host, await invoke(applyArgs), plan.package, { disableEmbedding: values['disable-embedding'] === true })
     }
     const applyArgs = argv('install', nativeValues, allowed)
     applyArgs.push('--apply', '--plan', plan.planFile)

package/bin/npm-embedding-preparation.mjs

@@ -0,0 +1,32 @@
+import { parseArgs } from 'node:util'
+import { isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** Installed product entry. Resolves only the acquired package's existing Knowledge runtime. */
+export async function embeddingPreparationMain(args, { npmRoot, signal } = {}) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    help: { type: 'boolean', short: 'h' }, 'embedding-cache': { type: 'string' },
+    'allow-download': { type: 'boolean' }, probe: { type: 'boolean' },
+  } })
+  if (positionals.length) throw new Error('prepare-embedding does not accept a host or project.')
+  if (values.help) return { schemaVersion: 1, kind: 'embedding-preparation-help', status: 'not-applicable',
+    usage: 'yugoo-design prepare-embedding [--embedding-cache /absolute/cache] [--allow-download] [--probe]',
+    options: { '--embedding-cache': 'Use the same absolute model cache as the target runtime; omission keeps the existing per-user default.',
+      '--allow-download': 'Explicitly permit the existing pinned model downloader to prepare missing or invalid resources; default only checks.',
+      '--probe': 'After verified resources, run one fixed text through the existing local CPU worker, offline. No project or host is required.' },
+    results: { 'assets-ready': 'All fixed resources verified; CPU inference has not been checked.', ready: 'Fixed resources verified and actual CPU inference passed.', unavailable: 'Resources or inference unavailable; see reasonCode. Basic design and source facts are unchanged.' } }
+  if (values['embedding-cache'] !== undefined && !isAbsolute(values['embedding-cache'])) throw new Error('--embedding-cache must be an absolute path.')
+  try {
+    const runtimeUrl = pathToFileURL(join(npmRoot, 'payload/shared/knowledge/runtime.mjs'))
+    const { runStandaloneKnowledgeOperation } = await import(pathToFileURL(join(npmRoot, 'payload/shared/knowledge/cli-lifecycle.mjs')).href)
+    return await runStandaloneKnowledgeOperation({ runtimeUrl, loadRuntime: () => import(runtimeUrl.href), run: runtime => {
+      if (typeof runtime.prepareLocalEmbedding !== 'function') throw new Error('Missing embedding preparation entry')
+      return runtime.prepareLocalEmbedding({ cacheDir: values['embedding-cache'], allowDownload: values['allow-download'] === true,
+        probe: values.probe === true, signal })
+    } })
+  } catch {
+    return { schemaVersion: 1, kind: 'embedding-preparation', status: 'unavailable', reasonCode: signal?.aborted ? 'cancelled' : 'runtime-unavailable',
+      resources: { state: 'unavailable' }, inference: { state: 'not-run' }, semanticKagVerified: false,
+      message: 'The installed Knowledge runtime could not run the embedding check. Check this package and its current-platform dependencies. Basic design and source facts are unchanged.' }
+  }
+}

package/bin/yugoo-design.mjs

@@ -5,10 +5,12 @@ const args=process.argv.slice(2)
 const dshInstall=args[0]==='install'&&args.some((arg,index)=>arg==='--host=dsh'||arg==='--host'&&args[index+1]==='dsh')
 const cancellation=new AbortController()
 const cancel=()=>cancellation.abort()
-if(dshInstall) { process.on('SIGINT',cancel);process.on('SIGTERM',cancel) }
+const cancellable=dshInstall||args[0]==='prepare-embedding'
+if(cancellable) { process.on('SIGINT',cancel);process.on('SIGTERM',cancel) }
 try {
-  const result=await installerMain(args,{npmRoot:fileURLToPath(new URL('../',import.meta.url)),signal:dshInstall?cancellation.signal:undefined})
+  const result=await installerMain(args,{npmRoot:fileURLToPath(new URL('../',import.meta.url)),signal:cancellable?cancellation.signal:undefined})
   console.log(JSON.stringify(result))
+  if(args[0]==='prepare-embedding'&&!['assets-ready','ready','not-applicable'].includes(result.status))process.exitCode=1
   if(process.argv[2]==='check-runtime'&&!['load-verified','disabled','not-applicable'].includes(result.status))process.exitCode=1
   if(result.status==='failed-partial-state-retained')process.exitCode=1
   if(['runtime-not-ready','unsupported-host'].includes(result.status))process.exitCode=1
@@ -17,5 +19,5 @@ try {
   console.error(error.installation ? JSON.stringify({error:error.message,installation:error.installation}) : error.message)
   process.exitCode=1
 } finally {
-  if(dshInstall) { process.off('SIGINT',cancel);process.off('SIGTERM',cancel) }
+  if(cancellable) { process.off('SIGINT',cancel);process.off('SIGTERM',cancel) }
 }

package/package.json

@@ -60,5 +60,5 @@
     }
   },
   "name": "yugoo-design",
-  "version": "0.1.0"
+  "version": "0.1.2"
 }

package/payload/overlays/claude-code/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "yugoo-design",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Yugoo Design: interactive Design Panels with Claude Code native agents and background design reviews."
 }

package/payload/overlays/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "yugoo-design",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Yugoo Design: local Design Project Panels for an explicitly bound Codex conversation (development preview).",
   "author": {
     "name": "yugoo-design contributors"

package/payload/overlays/qoder/.qoder-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "yugoo-design",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Yugoo Design: interactive Design Panels with Qoder-native Producers, Workers and background reviews."
 }

package/payload/shared/knowledge/cli-lifecycle.mjs

@@ -30,6 +30,17 @@ function ownKnowledgeSignals(runtimeUrl) {
 	});
 	for (const [name, listener] of owned) process.removeListener(name, listener);
 }
+/** Finite CLI diagnostics use the same verified signal ownership and public terminal shutdown. */
+async function runStandaloneKnowledgeOperation({ runtimeUrl, loadRuntime, run }) {
+	ownKnowledgeSignals(runtimeUrl);
+	let runtime;
+	try {
+		runtime = await loadRuntime();
+		return await run(runtime);
+	} finally {
+		await runtime?.shutdownLadybugKnowledgeRuntime();
+	}
+}
 async function startStandaloneCompanion({ runtimeUrl, loadRuntime, start }) {
 	ownKnowledgeSignals(runtimeUrl);
 	let server, loading, closing;
@@ -76,4 +87,4 @@ async function startStandaloneCompanion({ runtimeUrl, loadRuntime, start }) {
 	}
 }
 //#endregion
-export { startStandaloneCompanion };
+export { runStandaloneKnowledgeOperation, startStandaloneCompanion };

package/payload/shared/knowledge/runtime-manifest.json

@@ -8,11 +8,11 @@
     "undici": "8.10.2"
   },
   "assets": {
-    "cli-lifecycle.mjs": "6951c54bf30bb90d4fd8ff4addfb46f6358b084059440213643b1aff03ae903a",
+    "cli-lifecycle.mjs": "039c7705557b58c435c0a96a6540b2a233a3583ebab36c5d100bad0771a15d88",
     "embedding-worker.js": "1dc5f99a02fc8bd58ab318991a2145665c95bc65f4a025b63be524dffdb66f00",
     "embedding-worker.mjs": "1dc5f99a02fc8bd58ab318991a2145665c95bc65f4a025b63be524dffdb66f00",
     "package.json": "a3e820bf1715afda0b535dd848a22362dbdc28296fbbbe6ffd6b7712d06194b6",
-    "runtime.mjs": "7366e74ca57996e534c69c1e31bb7b8ca7deb2f85d40a1d8c6bef9349bf370d6"
+    "runtime.mjs": "08e99eae9738441b5a1a588a5a1a16a986e0dd8a8a41199fc88d19ab0956940e"
   },
   "officialInputs": {
     "repository": "https://github.com/deepseek-ai/deepseek-harness",

package/payload/shared/knowledge/runtime.mjs

@@ -35181,19 +35181,58 @@ async function size(path) {
 		throw error;
 	}
 }
-async function valid(path, asset) {
+async function valid(path, asset, signal) {
 	if (await size(path) !== asset.bytes) return false;
 	const hash = createHash(asset.kind === "git-blob-sha1" ? "sha1" : "sha256");
 	if (asset.kind === "git-blob-sha1") hash.update(`blob ${asset.bytes}\0`);
-	for await (const bytes of createReadStream(path)) hash.update(bytes);
+	for await (const bytes of createReadStream(path)) {
+		signal?.throwIfAborted();
+		hash.update(bytes);
+	}
 	return hash.digest("hex") === asset.hash;
 }
+function validateAssets(files) {
+	if (files.some((file) => !/^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/.test(file.path) || file.path.split("/").some((p) => p === "..") || !Number.isSafeInteger(file.bytes) || file.bytes < 1 || !["sha256", "git-blob-sha1"].includes(file.kind))) throw new EmbeddingAssetError("integrity");
+}
+/** Read-only inspection: never creates a cache, lock, staging file or network dispatcher. */
+async function inspectEmbeddingAssetSet(root, files, signal) {
+	validateAssets(files);
+	const results = [];
+	for (const asset of files) {
+		signal.throwIfAborted();
+		const path = join(root, asset.path);
+		try {
+			const length = await size(path);
+			results.push({
+				path: asset.path,
+				bytes: asset.bytes,
+				state: length === void 0 ? "missing" : length !== asset.bytes ? "incomplete" : await valid(path, asset, signal) ? "ready" : "integrity"
+			});
+		} catch (error) {
+			if (!(error instanceof EmbeddingAssetError)) throw error;
+			results.push({
+				path: asset.path,
+				bytes: asset.bytes,
+				state: "integrity"
+			});
+		}
+	}
+	signal.throwIfAborted();
+	return {
+		state: results.every((file) => file.state === "ready") ? "ready" : "unavailable",
+		bytes: files.reduce((total, file) => total + file.bytes, 0),
+		files: results
+	};
+}
+function inspectDefaultEmbeddingAssets(cacheDir, signal) {
+	return inspectEmbeddingAssetSet(join(cacheDir, DEFAULT_EMBEDDING_ASSETS.model, DEFAULT_EMBEDDING_ASSETS.revision), DEFAULT_EMBEDDING_ASSETS.files, signal);
+}
 /** Private resource preparation. No model/native session or Design text enters this path.
 * Download has its own bounded lifetime; the existing 180s inference budget is unchanged.
 * A failed pass keeps resumable staging bytes and never publishes a partial canonical file.
 */
 async function prepareEmbeddingAssetSet(root, files, localOnly, options) {
-	if (files.some((file) => !/^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/.test(file.path) || file.path.split("/").some((p) => p === "..") || !Number.isSafeInteger(file.bytes) || file.bytes < 1 || !["sha256", "git-blob-sha1"].includes(file.kind))) throw new EmbeddingAssetError("integrity");
+	validateAssets(files);
 	options.signal.throwIfAborted();
 	await mkdir(root, { recursive: true });
 	const compromised = new AbortController();
@@ -35218,7 +35257,7 @@ async function prepareEmbeddingAssetSet(root, files, localOnly, options) {
 		for (const asset of files) {
 			signal.throwIfAborted();
 			const target = join(root, asset.path);
-			if (await valid(target, asset)) continue;
+			if (await valid(target, asset, signal)) continue;
 			if (localOnly) throw new EmbeddingAssetError("missing");
 			await mkdir(dirname(target), { recursive: true });
 			const staged = target + ".yugoo-download.part";
@@ -35258,7 +35297,7 @@ async function prepareEmbeddingAssetSet(root, files, localOnly, options) {
 			} finally {
 				await output.close();
 			}
-			if (!await valid(staged, asset)) throw new EmbeddingAssetError("integrity");
+			if (!await valid(staged, asset, signal)) throw new EmbeddingAssetError("integrity");
 			signal.throwIfAborted();
 			if (await size(target) !== void 0) await copyFile(target, target + ".rejected-" + randomUUID(), constants.COPYFILE_EXCL);
 			await rename(staged, target);
@@ -35661,4 +35700,114 @@ var DesignSemanticIndex = class {
 	}
 };
 //#endregion
-export { DesignSemanticIndex, LadybugDesignKnowledgeProvider, shutdownLadybugKnowledgeRuntime };
+//#region packages/knowledge-ladybug/src/embedding-preparation.ts
+const reasons = {
+	missing: "固定版本模型资源缺失；允许下载后可显式准备。",
+	incomplete: "固定版本模型资源不完整；允许下载后可显式续传。",
+	integrity: "固定版本模型资源完整性校验失败；请显式重新准备。",
+	download: "模型资源下载未完成；请检查网络及代理后显式重试。",
+	busy: "另一进程正在准备模型资源；请在其完成后重试。",
+	cancelled: "模型准备或推理检查已取消。",
+	runtime: "模型缓存无法读取或运行依赖不可用。"
+};
+/** Installation diagnostic only: no project, provider database, publication or host configuration. */
+async function prepareLocalEmbedding(options = {}) {
+	if (options.cacheDir !== void 0 && !isAbsolute(options.cacheDir)) throw new Error("Embedding cache must be an absolute path");
+	const index = new DesignSemanticIndex({
+		localOnly: true,
+		...options.cacheDir ? { cacheDir: options.cacheDir } : {}
+	});
+	const signal = options.signal ?? new AbortController().signal;
+	const { cacheDir, model, revision } = index.config;
+	let resources = { state: "unavailable" };
+	const base = {
+		schemaVersion: 1,
+		kind: "embedding-preparation",
+		cacheDir,
+		model,
+		revision,
+		downloadAllowed: options.allowDownload === true,
+		semanticKagVerified: false,
+		note: "仅检查本地语义索引资源与可选 CPU 推理；不更改基础设计、源事实投影或项目语义发布状态。"
+	};
+	try {
+		resources = await inspectDefaultEmbeddingAssets(cacheDir, signal);
+		if (options.allowDownload === true && resources.state !== "ready") {
+			await prepareDefaultEmbeddingAssets({
+				...index.config,
+				localOnly: false
+			}, signal);
+			resources = await inspectDefaultEmbeddingAssets(cacheDir, signal);
+		}
+		if (resources.state !== "ready") {
+			const code = resources.files.find((file) => file.state !== "ready").state;
+			return {
+				...base,
+				status: "unavailable",
+				resources,
+				inference: { state: "not-run" },
+				reasonCode: code,
+				message: reasons[code]
+			};
+		}
+		if (!options.probe) return {
+			...base,
+			status: "assets-ready",
+			resources,
+			inference: { state: "not-checked" },
+			message: "固定模型资源完整；尚未验证实际 CPU 推理。使用 --probe 检查。"
+		};
+		try {
+			await index.compute("installation-probe", {
+				checkpoint: "installation-probe",
+				nodes: [],
+				edges: [],
+				warnings: [],
+				semanticUnits: [{
+					id: "installation-probe:0",
+					nodeId: "installation-probe",
+					file: "installation-probe.json",
+					pointer: "",
+					text: "Local embedding readiness check.",
+					digest: "installation-probe-v1"
+				}]
+			}, void 0, signal);
+			return {
+				...base,
+				status: "ready",
+				resources,
+				inference: {
+					state: "ready",
+					device: "cpu"
+				},
+				message: "固定模型资源完整，实际本地 CPU 推理通过。"
+			};
+		} catch {
+			return {
+				...base,
+				status: "unavailable",
+				resources,
+				inference: {
+					state: "unavailable",
+					device: "cpu"
+				},
+				reasonCode: signal.aborted ? "cancelled" : "inference-unavailable",
+				message: signal.aborted ? reasons.cancelled : "模型资源完整，但实际 CPU 推理未通过。请检查当前平台运行依赖、CPU 和内存。"
+			};
+		}
+	} catch (error) {
+		const code = signal.aborted ? "cancelled" : error instanceof EmbeddingAssetError ? error.code : "runtime";
+		return {
+			...base,
+			status: "unavailable",
+			resources,
+			inference: { state: "not-run" },
+			reasonCode: code,
+			message: reasons[code]
+		};
+	} finally {
+		await index.close();
+	}
+}
+//#endregion
+export { DesignSemanticIndex, LadybugDesignKnowledgeProvider, prepareLocalEmbedding, shutdownLadybugKnowledgeRuntime };

package/release-hosts.json

@@ -4,7 +4,7 @@
     "dsh": {
       "aggregatePackage": "@yugoo-design/dsh-design-system-dsh",
       "registry": "https://registry.npmjs.org",
-      "aggregateVersion": "0.1.0"
+      "aggregateVersion": "0.1.2"
     }
   }
 }

package/release-manifest.json

@@ -3,21 +3,22 @@
   "fixture": false,
   "distribution": "stable",
   "publishReady": false,
-  "version": "0.1.0",
+  "version": "0.1.2",
   "readmeSource": {
     "path": "packages/companion/README.md",
-    "sourceSha256": "e9caa13476599a62cf08b7bf04bf11fee8ba32f003fd1d8de1ebaf09c479fd41",
-    "sectionSha256": "858538e4c8436757cba9a0f17679bcde6f243fe52bd0d8d0a40e98da6c4ff65d"
+    "sourceSha256": "0b4fdabb12018f52718b8d278a47ebf5818460b36d86d6be96da60cb98b52aa5",
+    "sectionSha256": "97c43b5e19f7b1d64a85534b15bb242cf0daccf60fd86ef578c4037a310f2f0c"
   },
   "assets": {
     "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
     "NOTICE": "6119b21e1fa5d37ec3ab337ad43685970310aa5c97a0e90ecf6603d17091f371",
-    "README.md": "b0c23e78d56febe16f7962a9b2fb7a5462b083ea8121a96b040ed7bc62ae0df2",
+    "README.md": "598ac20a2019438aadbfd66a1cc5bd94e6cefb004733bb6c773f4ab9b87046d9",
     "THIRD_PARTY_NOTICES.md": "bfcab921c6c15ccc47f9b1a6cc5941675c95962de5ea5b0edc50fbfa2aef136a",
-    "bin/installer.mjs": "a28f62a92fbc14c3964452c8b61d3f4486d92b1771a65db253ff55f926e7897d",
-    "bin/npm-agent-installation.mjs": "c5f8f845ea339c21834ac9f313458e63a9f0c299d6ed68feb8c689a1f060a0f5",
+    "bin/installer.mjs": "169f367c8c66d5066b51e305dbdbe692888b96dec4ae671dda1cd216b4baa8b4",
+    "bin/npm-agent-installation.mjs": "0b64248e789b4d3a3ee1752f5235744c27d37bb302e0e538d34a7905a59a5a6a",
     "bin/npm-codex-desktop-source.mjs": "a4990fe747ff8da2d884a795a255aa691c848b4a9d8ebbdb28f3929bcda8359d",
     "bin/npm-desktop-preparation.mjs": "43f7a972a44bea90291e113f206e3c3bc4a91a02e4b82eea85293c1cebb15237",
+    "bin/npm-embedding-preparation.mjs": "bd787ea9404e97e07adba68c700f61b1f25a70a1a475506cd91c258f2dc10afd",
     "bin/npm-installer-claude.mjs": "e34a681b3fa9d7f40518103fb4230e083077347e3d6aaa14dceeba609d5fd310",
     "bin/npm-installer-codex-desktop.mjs": "dcd8e75f5e47531843c5842cb3068a55f968fe20ed8ea3f5b3d0d7b155c0c5eb",
     "bin/npm-installer-codex.mjs": "5789195b889a78fa298395fb5e3b6f72539e473f816132c4762e0ee77ac4a9c8",
@@ -30,7 +31,7 @@
     "bin/npm-runtime-check.mjs": "31880b9b79fdceeef070f8d304cde66ce335bc34d173b16e603abf0a6a5d60ad",
     "bin/windows-native-platform.mjs": "57ac50c9a8cc0371597d6d40e3efe4cbe2a470e98f75f0229721c7d5a48e7e98",
     "bin/windows-private-storage.mjs": "27c3eb052278f0cb2850326e1d0864cfd2f3f6d2b1975ec7c24535ef6251ac94",
-    "bin/yugoo-design.mjs": "2b9a0a610953dac800a7ee8d46fb05c193550bc57297985f42d076cec757a80f",
+    "bin/yugoo-design.mjs": "3a390aca541f6a7c6a987a54037d58926e3a5dc7971f9d540476e329ceeb027a",
     "licenses/DSH-LICENSE": "ebb4f09972aee8608be255debaf78451a68e95c290f55c240dec2ecfa16ea6be",
     "licenses/bundled-js/3d-force-graph@1.80.0/LICENSE": "7262e566e874d1ce8cfadace01d4f635f8d704b6bdf7b4345cc028e5faeafded",
     "licenses/bundled-js/@babel/runtime@7.29.7/LICENSE": "117da2af0d4ce0fe1c8e19b5cff9dcd806adf973d328d27b11d4448c4ff24f76",
@@ -427,7 +428,7 @@
     "licenses/third-party/whiteboard-fonts/licenses/JetBrainsMono-OFL.txt": "30f0c136e3c88e422d0791acd97238870f9054a9729bc34cf2ff0d4ed8cac4ad",
     "licenses/third-party/whiteboard-fonts/licenses/source-han-sans-LICENSE.txt": "fcac737e761ec63dbfbdce11030a1780161920d80315edba9c8beff1c2bac5a2",
     "licenses/third-party/whiteboard-fonts/manifest.json": "c164438115a40cdead905085e95298f28a4ffa2a3947512b9a98509f33c26972",
-    "package.json": "47af5cb65de70871de72bb9722f70bfbe83f3b5252246b8874485051afb56508",
+    "package.json": "f812f334f59b81b251d26098fc659f3bcfe7a11b9d367fbac778a0b12ab43ebd",
     "payload/desktop-preparation/LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
     "payload/desktop-preparation/NOTICE": "6b4eec391144fcbd96ec7b45a28764ab1932722a96325248377c3e28aac2c62d",
     "payload/desktop-preparation/THIRD_PARTY_NOTICES.md": "bfcab921c6c15ccc47f9b1a6cc5941675c95962de5ea5b0edc50fbfa2aef136a",
@@ -465,7 +466,7 @@
     "payload/desktop-preparation/src/workbuddy-relay-service.mjs": "44d60d6956250417507fb76c71c3030a01bc38e565e4572a761b46f255f8e669",
     "payload/desktop-preparation/src/workbuddy-ui-probes.mjs": "a91d4651248125769254755bdf66a44bbc9e5a793dad0a137c35acbb10a89a88",
     "payload/desktop-preparation/workbuddy-package.mjs": "f39407b3fd2406c73079b4067e9eb93d181a35ac53ad548b45e8599f486ca976",
-    "payload/overlays/claude-code/.claude-plugin/plugin.json": "a0498213223ffd0a911e75b523a8bd2bfe6cab5eda9bc21b5c024df58f3b16ce",
+    "payload/overlays/claude-code/.claude-plugin/plugin.json": "e7f83d7c8e13b19fbaf437097b2df9d925ab98a5051ebdc4df095df884760247",
     "payload/overlays/claude-code/.mcp.json": "1108847d27abd953a52cd7c3ea4cd416898d67dcfdb80a92255d889186b12b66",
     "payload/overlays/claude-code/hooks/hooks.json": "e8bea6fdf13dce4023a2112dd4a31fd1a77e0f4ca2d4c506882ea80ef86b6482",
     "payload/overlays/claude-code/scripts/claude-connection.mjs": "83a6a2de1b28d1b5dd230b1447abac6f2209a80d6681f08766a53e7b6f63200f",
@@ -479,7 +480,7 @@
     "payload/overlays/claude-code/skills/design-component/SKILL.md": "85a1f2a016174787226eaa9e9e6675e86057212d322a65014edd71f3e4861b34",
     "payload/overlays/claude-code/skills/yugoo/SKILL.md": "045d81c10b0d18ebe1644180149f42059b114874bcf8daca805c6fd91e343c81",
     "payload/overlays/claude-code/skills/yugoo/native-execution.md": "2e66dc2811ce6552ab43547af3020337e9de60576ad3c8de4422f120dbd6d5a7",
-    "payload/overlays/codex/.codex-plugin/plugin.json": "1dac83b8c20e668b97a3551002782d212a0da34f7831c12abb1305afa4c1933d",
+    "payload/overlays/codex/.codex-plugin/plugin.json": "c4dc58fe7b547e14369f072c3aa61f7e939b4792c0a4887e4bfd4f819b32ab62",
     "payload/overlays/codex/.mcp.json": "ee6450b4f9a5239ae9c173d07198d37041fad65f9f65ecf4ff88ccf8528a609a",
     "payload/overlays/codex/README.md": "614c04455a8b88941d62861bc9e6ab0ae96f7aefb4a04a31085a2d86ccbf363b",
     "payload/overlays/codex/scripts/design.mjs": "c116e3a9f60830923692a9f8785640d9a13a97320771bf9201de0e5089618a74",
@@ -489,7 +490,7 @@
     "payload/overlays/codex/skills/design-panel/native-execution.md": "2e66dc2811ce6552ab43547af3020337e9de60576ad3c8de4422f120dbd6d5a7",
     "payload/overlays/codex/skills/yugoo/SKILL.md": "d2c512b979178c9be0dd5cf2b855ad1d39af00f40728aa3031b87e12693a8600",
     "payload/overlays/qoder/.mcp.json": "7f86b52fffd552312441b9bd99dd39a3b80b2893dc4a85519614d906bdc6884e",
-    "payload/overlays/qoder/.qoder-plugin/plugin.json": "5692a38ad807bc1721e7c1279b3f503f14a804e475c81a654f338e7ab6bb67e1",
+    "payload/overlays/qoder/.qoder-plugin/plugin.json": "75fdbe896e82f21077b7bb7a5ab0d106fed5cdd62598970e80360aa3cb20a4be",
     "payload/overlays/qoder/commands/yugoo.md": "1461cf9bd13ae18bf0ad204222dfd8c558552471628c31b2dc936f3329ac26cf",
     "payload/overlays/qoder/hooks/hooks.json": "6452852583af61a7b4f0ed501a41d02a212a8487e5d920bcb0b2ee7e7e643d7d",
     "payload/overlays/qoder/scripts/design.mjs": "c116e3a9f60830923692a9f8785640d9a13a97320771bf9201de0e5089618a74",
@@ -1161,12 +1162,12 @@
     "payload/shared/kits/web_app/THIRD_PARTY_NOTICES.md": "1d358b1a367efd6f4e0fb04436df7f814531cd6a01a0b2b752d7b8268a461c79",
     "payload/shared/kits/web_app/kit.yaml": "f66f6510d621933e2e45164c214bb3dc59c2a79bbe6521d93b37d5ba4419ca28",
     "payload/shared/kits/web_app/mindset.md": "dea0d63d0ae4795c1737d50d4564d3ddb934d80daee082a91afed4ea3be5cc08",
-    "payload/shared/knowledge/cli-lifecycle.mjs": "6951c54bf30bb90d4fd8ff4addfb46f6358b084059440213643b1aff03ae903a",
+    "payload/shared/knowledge/cli-lifecycle.mjs": "039c7705557b58c435c0a96a6540b2a233a3583ebab36c5d100bad0771a15d88",
     "payload/shared/knowledge/embedding-worker.js": "1dc5f99a02fc8bd58ab318991a2145665c95bc65f4a025b63be524dffdb66f00",
     "payload/shared/knowledge/embedding-worker.mjs": "1dc5f99a02fc8bd58ab318991a2145665c95bc65f4a025b63be524dffdb66f00",
     "payload/shared/knowledge/package.json": "a3e820bf1715afda0b535dd848a22362dbdc28296fbbbe6ffd6b7712d06194b6",
-    "payload/shared/knowledge/runtime-manifest.json": "07094bc42a1ec010c7f1800b65e9737537233c9be149a901f48354590f9ea581",
-    "payload/shared/knowledge/runtime.mjs": "7366e74ca57996e534c69c1e31bb7b8ca7deb2f85d40a1d8c6bef9349bf370d6",
+    "payload/shared/knowledge/runtime-manifest.json": "3320b95239598fd9a9fb424ec4fb1d3037441464f46543260c20084543e9b709",
+    "payload/shared/knowledge/runtime.mjs": "08e99eae9738441b5a1a588a5a1a16a986e0dd8a8a41199fc88d19ab0956940e",
     "payload/shared/scripts/codex-connection-DuV2wtkn.mjs": "953b36e1a0a9892a126008ebdc2c29d2eb1036b279fa138fe881b5fd314cbf5e",
     "payload/shared/scripts/codex-desktop-bridge.mjs": "dc9eb9b8f35bc076758e520668cef19f853b797e798a6027f55bf0e230d33ed5",
     "payload/shared/scripts/codex-desktop-marketplace.mjs": "96974611780bffaf2b69b0fea143b6760cdaf7f8d38236931086bb3ad94f3892",
@@ -1368,7 +1369,7 @@
     "payload/shared/web/zh-CN-LNUGB5OW-B8jdxL1j.js": "009e897b8dce75b294018536f2c7d08f17d5174497d13cd0b5b46e17660e54ed",
     "payload/shared/web/zh-HK-E62DVLB3-C01JMzt_.js": "421281ca20c481adb4d774fdea5c907cc74241f6a745908b72dee694ed3f4112",
     "payload/shared/web/zh-TW-RAJ6MFWO-Cdn1Kb1q.js": "a48825086867a6b48a5e9a0fcdf91eb4d6752def51bf7b6dfa9bad12aed33624",
-    "release-hosts.json": "af227e2f3e03039e195f80e34e6d7cddf1d2369114dc307440361e494cb9d3e0"
+    "release-hosts.json": "72c4cbb93852b7c3d856dc21cf7d2350336ab1acb55538bab3779ec7151569b2"
   },
   "dependencies": {
     "@ladybugdb/wasm-core": "0.21.1",
@@ -1383,7 +1384,7 @@
     "product": {
       "schemaVersion": 1,
       "name": "yugoo-design",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "bin": "yugoo-design"
     }
   },