Yugoo Design

Package: [email protected].

Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts. It combines domain methods, Design Projects, versioned Design Files and shared Panels. The Companion provides those Panels for hosts outside the native DSH UI; it uses the host's own models and conversation.

Native installation, tools, Panel saving, KAG and GRA must be verified for the actual host version and platform. A successful package installation or runtime-load check does not establish all of those capabilities.

Use Node.js >=22.19.0 and a durable npm or pnpm installation directory. Older package versions retain their own engines.node requirements. The current payload uses the packaged native Git library for normal Design versioning without system Git. Its supported targets are Windows x64 MSVC, Linux x64 GNU and macOS arm64; host acceptance remains version-specific. System Git is separate and needed only for the explicit CLI diagnostic backend and development fixtures. Missing native support is reported rather than silently spawning system Git. For published packages, resolve the required release to its exact version and integrity before acquisition; keep the previous installed version available during updates. Stop if that exact release is missing; do not substitute another package, channel or arbitrary version. If a retained installation already matches that exact release and provides the required host adapter and runtime, reuse it after checking its help and runtime receipt. A stale catalog or old host session is not a reason to download the same runtime again. A different required release gets a new retained directory; do not overwrite an installed runtime or copy only part of its dependency tree.

Node is a shared prerequisite, separate from the retained product package. Reuse an existing user/system Node installation or a Node version manager; installing another host adapter does not download another Node. New installer plans select --node-executable or YUGOO_NODE_EXECUTABLE first, then inspect PATH and standard Node installation locations. They verify the real executable, version, platform, architecture and SHA-256, and bind the same absolute path to the owned MCP/Hook configuration. An invalid explicit choice fails rather than silently switching to another Node. Preview directories, plugin caches, application resources and temporary runtimes cannot become shared prerequisites.

If the acquired release lists resolve-node in its help, inspect the selection without registering a host or changing configuration:

npx --no-install yugoo-design resolve-node

If no compatible Node exists, prepare it once through the system's Node installer or a version manager and rerun the installer. This route does not download Node, change global PATH, or own/delete an external Node during plugin removal. It does not implement a product-managed Node download or garbage collector. DSH Desktop continues to use its official pinned Electron/Loader entry; do not replace that host-internal executable with the Companion's standalone Node selection. Windows desktop preparation validates an existing Node on Windows. Preparation from another operating system requires an explicit Windows path and reports that locator as unverified; it does not establish target runtime acceptance.

In a dedicated retained version directory, use normal pnpm installation:

pnpm add --save-exact [email protected] --registry=https://registry.npmjs.org
pnpm exec yugoo-design --help

The prebuilt package carries the upstream Transformers.js Node entry, ONNX CPU runtime and sharp JavaScript. npm installs only the selected platform's sharp binary and the remaining runtime dependencies. No source build, approve-builds, allowBuilds, ignore-scripts flag or hand-written workspace configuration is needed for these bundled runtime packages. Default pnpm dependency links are supported; retain the complete installation layout. The same pnpm store serves initial acquisition and the native DSH package operation, so shared dependencies can be reused. Existing npm installation remains supported with npm install --save-exact [email protected].

Run acquisition in its own retained version directory, outside the Design Project or host profile. Keep one package manager per directory. The prebuilt CPU targets are Linux x64 GNU, Windows x64 and macOS arm64; actual installed-host and model readiness still require their own checks.

An explicitly selected HTTPS npm mirror is supported, for example --registry=https://registry.npmmirror.com. Use it both when acquiring this package and when invoking yugoo-design install --host dsh --registry=<url> with the required host inputs. The latter controls the official DSH CLI's package download registry; it does not replace that CLI with npm or pnpm. The exact aggregate version still comes from release-hosts.json, whose registry remains the canonical release origin/default. The plan and receipt separately record the effective mirror and bind it through apply and owned updates. There is no automatic registry fallback or global registry edit. Verify the exact mirror version and integrity against the selected release before installation; missing or stale mirror packages are not permission to change version or source. Registry selection does not redirect separate embedding-model or upstream installation-script downloads to that mirror.

Local embedding runs on CPU. The prebuilt release does not run ONNX's extra CUDA acquisition script. Model files are prepared separately through the embedding-model preparation step; package installation alone does not establish semantic indexing. GPU provisioning and configurable or user-local model selection remain future work.

Older published archives, including 0.2.8, keep their original installation behavior. Their included guide may require ONNXRUNTIME_NODE_INSTALL_CUDA=skip and a native pnpm build-policy repair. New release assembly does not change those immutable archives. Check the acquired release's bundledDependencies and its own instructions rather than applying new packaging assumptions to an old version.

Local embedding model preparation

The current provider pins Xenova/multilingual-e5-small at revision 761b726dd34fb83930e26aab4e9ac3899aa1fa78, with quantized q8 weights and CPU inference. Its default cache is .cache/design-system/embeddings under the home directory of the user running the runtime, not the npm installation or Design Project. Windows Node uses that Windows user's home; WSL uses its Linux user. An offline installation needs the complete model cache in the library's expected 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:

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 fetching the pinned model files if absent. Apply it only to that exact owned Panel startup with its existing host/session/project arguments. It is a runtime serve option, not a yugoo-design install or check-runtime option. Conversely, --disable-embedding on that runtime entry keeps structure/evidence without 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 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.

yugoo-design check-runtime verifies the declared runtime dependencies and its isolated native-load/Git checks. It does not fetch or validate the complete embedding model, run semantic inference or prove that KAG is current. After cache preparation, verify the real project's semantic status separately. Preserve the reported model/runtime failure and existing Design Files rather than clearing the database or reinstalling the host to make the status appear successful.

While embedding is unavailable, use design_knowledge_context and preserve its project, checkpoint, graph revision and coverage.basis (as query basis) for design_query_knowledge. This keeps the view stable when a later publication becomes available. If source projection has completed and still matches the pinned sources, context remains available with coverage.basis: source-projection: records, explicit references and literal-text queries work without semantic inference. Its coverage excludes embedding candidates and other non-file interpretations. The returned status still shows the semantic maintenance failure and any older latest-complete publication; basic context availability does not mean semantic KAG is current. These reads do not retry maintenance. An unprojected, incomplete or stale source view remains unavailable; use bounded reads of the Design Files in that case. Legacy queries without a basis retain their historical-snapshot behavior when a publication exists; their returned coverage does not assert semantic completeness or compatibility with the current projection policy.

Install in the current native host

Ask the Agent in your current host to install or update Yugoo Design as one product. It should identify the host from its actual execution context or your explicit choice, not from which CLIs happen to be installed. If identity is unclear, ask only for the missing host choice. Follow this acquired version's CLI parameters and host requirements; a newer source guide does not add commands to an already published package. Users do not install DSH and Companion separately:

| Host | Native installation route | | --- | --- | | Codex | install --host codex: run the existing plan, runtime check and apply transaction, retaining each receipt. | | Codex Desktop | install --host codex-desktop: prepare a small npm-backed local source and owned personal catalog; install or update it through the native plugin UI. | | Claude Code | install --host claude-code: native user-scope registration. | | Qoder CLI | install --host qoder: native user-scope registration and independent readback. | | QwenWork | install --host qwenwork: prepare the expert suite and its MCP configuration; import and enable through the host. | | WorkBuddy | install --host workbuddy: prepare the stable marketplace and plugin; import or update and enable through the host. | | DSH | install --host dsh: run the existing plan/apply transaction with the bound aggregate, official CLI/Loader and an explicitly selected existing profile. |

For a fresh WorkBuddy preparation, the native suite example is 0.3.30 (--suite-version 0.3.30), with the verified Node executable and a persistent external preparation destination. Import the returned nativeImport.market directory and enable its yugoo-design plugin. The fresh market is also named yugoo-design; no previous test market or preparation receipt is required. An owned update with --previous-receipt retains its original market name and directory, including historical test markets, rather than migrating a registered installation.

The QwenWork native suite example is 0.1.5 (--suite-version 0.1.5). These numeric versions were used with the recorded local Companion beta.18 candidate; they are separate from the published Companion npm version. Use the selected package's guide and an explicitly chosen suite version. An owned update must advance beyond its previous receipt's suite version, even when an example here uses the old value. Desktop preparation writes that explicit version into the import; it does not prove the host loaded it.

Supply the required host inputs shown by yugoo-design --help. Without a host, the entry returns host-selection-required; missing inputs return inputs-required, both with exit code 2 and no installation attempted. The Agent should obtain supported native facts itself and ask only for missing choices. Explicit saved-plan and prepare-desktop routes remain available.

For Codex Desktop, choose a new --destination inside the intended user's home with an existing parent, an external --receipt-dir, and optionally an existing public --node-executable. Keep the exact npm installation at its acquired path: the small prepared source points to its shared runtime. An owned update uses a new npm directory and source destination with the old --previous-receipt, retaining the old inputs. --dry-run saves a source-bound plan; apply that exact --plan from the same package without choosing a new Node or destination. The returned catalog preparation still reports the plugin as not installed or loaded. Complete the native UI action, and return to the current conversation after a normal user-controlled restart if the host requires one.

The Agent completes executable steps and reports only the required human authorization, import, enable, restart or new-session action. Report acquisition, registration/import, activation and verified use separately; do not report an untested phase as complete. DSH uses its native integration, not a second Companion runtime inside the host.

Desktop preparation alone does not register or activate a plugin. Native suite versions are separate from npm versions. Preserve unrelated registrations, models, credentials and Design Projects; do not overwrite an owned previous installation path or automatically repeat an uncertain operation. Same-version retries and updates must follow the owning adapter's receipt rules; this entry does not introduce a universal replacement or rollback mechanism.

Start the host normally, then confirm the loaded Yugoo Design entry and tools in the intended conversation. Offer a first-project request; let the user start that design task. During the first design cycle, edit and save a Panel, reopen it and check that the original host conversation receives the saved result. Report unsupported Workers, GRA or other host capabilities explicitly. Follow the owning host's supported diagnostics, update, recovery and uninstall routes and retain their receipts; availability differs by host. Read only the relevant host section below; fetching the full online guide is not required for ordinary setup.

CLI registration and activation

Run commands from the retained npm installation's consumer directory. Use pnpm exec yugoo-design install --host HOST with an external --receipt-dir and the actual native executable: --codex-executable for codex, --claude-executable for claude-code, or --qoder-executable for qoder. The Agent discovers these paths from the active host. Codex CLI and Claude Code's direct entries run the existing runtime check and registration transaction; users do not assemble those stages manually. Follow the acquired version's help if it requires a saved plan. Qoder performs native registration and readback; use its separate check-runtime --host qoder diagnostic for runtime readiness.

After registration, use the host's normal reload/new-session step when necessary and check the loaded Skill and tools. Codex CLI uses $yugoo; Claude Code and Qoder use /yugoo-design:yugoo. Qoder's same-version owned registration is a no-op; a different version uses its native uninstall/re-registration procedure. Preserve existing settings, the previous runtime and the owning receipt on an update.

DSH inputs and native activation

The Agent prepares --dsh-config from the existing official DSH installation; the user does not need to guess its fields. Save an absolute JSON file with the following eight required keys. Replace every example path, version and hash with values read from that installation:

{
  "dshHome": "/absolute/existing/dsh-home",
  "node": {
    "path": "/absolute/official-runtime/node",
    "sha256": "<sha256-of-runtime-executable>"
  },
  "cli": {
    "path": "/absolute/official-dsh/<bin.dsh-entry>",
    "sha256": "<sha256-of-cli-file>"
  },
  "hostManifest": {
    "path": "/absolute/official-dsh/package.json",
    "sha256": "<sha256-of-host-package-json>"
  },
  "loader": {
    "path": "/absolute/official-dsh-app-boot/<main-entry>",
    "sha256": "<sha256-of-loader-file>"
  },
  "loaderManifest": {
    "path": "/absolute/official-dsh-app-boot/package.json",
    "sha256": "<sha256-of-loader-package-json>"
  },
  "hostVersion": "<hostManifest.version>",
  "loaderVersion": "<loaderManifest.version>"
}

Use absolute file paths and each file's actual SHA-256: 64 lowercase hexadecimal characters, computed from its resolved bytes. Each file pin accepts only path and sha256. Locate the installed packages through the host's existing entry point or native installation information; do not use a source checkout, a shell shim or a separately downloaded replacement.

| Field | Value to read from the installed host | | --- | --- | | dshHome | The existing DSH configuration root for the intended host, resolved to its real directory. It contains profiles/; it is not the profile directory itself. | | node | For Web, the compatible Node executable used to run the official CLI. For Desktop, the official Electron executable, as described below. | | hostManifest | package.json for @deepseek-ai/dsh; check its package name and read version into hostVersion. | | cli | For Web, resolve hostManifest's bin.dsh relative to that package directory. Desktop has a different entry below. | | loaderManifest | package.json for the installed @deepseek-ai/dsh-app-boot; read version into loaderVersion. | | loader | Resolve loaderManifest's main relative to its package directory. |

These version strings identify DSH and its Loader, not the Yugoo npm product.

For Desktop, also add desktopHostManifest as a { "path": "...", "sha256": "..." } pin for the installed @deepseek-ai/dsh-desktop-host/package.json. Its version, hostVersion and loaderVersion must match. Set cli to that Desktop package's lib/cli.js, with the DSH and Loader packages from the same installed tree. Set node to the official Electron executable; the installer uses its existing Electron Node bridge to read ASAR resources and run the official CLI. Keep the installed tree intact rather than extracting it or substituting ordinary Node. Read and hash any files inside ASAR through Electron's filesystem; the archive location depends on the actual installation. Use the existing desktop profile.

Pass the existing profile's name separately with --profile; the installer does not create a profile. Do not add nodeExecutable, cliExecutable, scope or runner overrides to the JSON. DSH does not accept --node-executable, --disable-embedding or Codex's --runtime-receipt; model settings remain owned by the host.

Choose an absolute, private --receipt-dir outside the retained product package, DSH home, every pinned input directory and any previous product installation. It must not contain or overlap those roots or the config file. Keep the config file outside the receipt directory. For example, use separate user-owned install-config/ and install-receipts/ directories outside those roots, with a new receipt directory for this operation. On Windows, an existing receipt directory must already have the required private permissions; the installer does not repair unsafe shared directories.

Use these inputs with the acquired yugoo-design install --host dsh route. An explicit --dry-run writes <planSha256>.dsh-plan.json in the receipt directory and returns its planFile; --apply --plan <absolute-planFile> consumes that saved file with the same config and profile. The direct route without either flag orchestrates these stages and uses a fresh receipt subdirectory. Use the returned planFile, not a copy of the CLI's display object. Ordinary Host-managed registry updates inspect the current profile and need no historical Yugoo receipt. When supplying optional successful history with --previous-receipt, use the same receipt in both stages. Older acquired versions retain their own receipt requirements; use their actual help. Keep the returned plan and result paths. Before native apply, the installer retains <id>.dsh-prepared.json; a completed result is stored as <id>.dsh-result.json, with command logs alongside it. A prepared record or failed result does not establish a successful installation. Inspect the retained partial state before retrying; this adapter does not automatically roll back an interrupted native package operation.

After the official CLI operation, check the selected profile's Plugins page and enable @yugoo-design/dsh-design-system-dsh if it is installed but disabled. Use normal host restart/reload only when needed, then verify /yugoo and the embedded Design Panel. The adapter acquires its exact native module dependencies; users do not manually install each internal package or modify host sources.

QwenWork import and MCP activation

Use pnpm exec yugoo-design install --host qwenwork with the real public --node-executable, verified --qwenwork-runtime JSON, an external --destination and a numeric --suite-version. The runtime JSON contains executable, worker, nodeExecutable, executableSha256 and workerSha256 from the intended native installation; the Agent discovers and verifies them. An owned update uses its --previous-receipt and a greater native suite version. The returned suite and connector paths identify the materials for activation.

First use the installation capabilities advertised by the current QwenWork conversation. Its bundled qwenwork-guidance/guide-mcp.md describes discovering the actual settings keys with qw_query({key: "qwenwork"}). When the returned plugin entry advertises install_from_path, follow its schema with the prepared suite. When the connector entry advertises add, use the generated design-system-mcp.json connector's command, args and env as its config. Reuse an existing working connector. Query the returned detail key to confirm connection and tools, then make a real tool call. These are native Host actions, not another Yugoo CLI or desktop-control endpoint.

If the Agent cannot complete a required action through those native tools, give the user these UI steps and the corresponding generated files/configuration:

1. Open Extensions → Expert Kits → Add → Upload suite, select the generated yugoo-design.zip, install it and enable the suite.
2. Check its design-system connector. If tools are not connected and no working connector already exists, open Extensions → Connectors → Add → Paste JSON configuration. Paste the contents of the generated design-system-mcp.json, import it and enable it. With --separate-mcp, this separate step is required. Keep one active connector rather than importing it twice.
3. After adding/enabling the connector, verify a real tool call in the current task. If the tools are not exposed there, start a new QwenWork task, select the yugoo skill and continue verification. A ZIP or successful Skill import alone does not establish readiness.

Native connector actions can reload the tool pool. If the current conversation already exposes and successfully calls the new tools, continue there; otherwise use the host's new-task activation step above. A connected pool alone does not prove that this Agent can call its tools.

These native UI steps follow QwenWork's suite import guide and connector guide. The Agent adapts prerequisites, paths and shell commands to the actual environment; historical test-machine paths are not additional installation requirements. An acquired adapter's concrete unsupported-platform error still needs a product fix; do not manufacture another machine's paths or claim success from preparation.

WorkBuddy market activation

Use pnpm exec yugoo-design install --host workbuddy with the real public --node-executable, an external persistent --destination and a numeric --suite-version. Import the returned nativeImport.market directory through the native marketplace importer and enable yugoo-design and its MCP connection. In the inspected desktop, the path was Skills → Skill Market → Suites → + (Add Marketplace); use the equivalent control advertised by the current host. A full plugin belongs in the marketplace importer, not the standalone Skill ZIP importer. On update, keep the same owned market directory, supply its --previous-receipt and a greater suite version, then use the market's Refresh and Update controls in that order. Verify the loaded yugoo Skill and tools in the original host after any required normal reload or new-session action.