deepseek-harness/docs/subsystems/boot.zh.md

Profile 管理

English | 中文

boot 包组负责 launcher 提供的 profile 访问与插件管理器。插件管理器文档说明持久化、重载与包操作行为。

管理记录

PluginEntryId 标识一个 Loader 条目；调用方从 listPlugins 获取，不自行拼接 patch id。

PluginInfo 包含模块标识、实际启停状态和 fiber 阶段，以及唯一的 patchId 或 readOnlyReason。

BundleInfo 包含包名、可选的安装版本、标题与描述、profile 自身依赖是否持有该包、组合层选择状态、删除可用性、可选的解析错误、其 patch 声明的行（BundleRowInfo：行 id、模块，以及组合包生效期间的存活条目 id），以及其 patch 覆盖的已有行 id。

InstallBundleOptions.enabled 默认为 true。False 表示安装但不选择该组合包层。requestId（PluginInstallRequestId，调用方生成的 UUID）标识这次安装，用于其日志与状态事件以及 cancelInstall，后者答复 PluginInstallCancellation：cancelled、too-late 或 not-running。

PluginSpecInspection 是 inspect 在安装前的答复：被接受的 spec 的形式、名称、版本、描述、标题与组合包声明，或拒绝的问题与原因。

PluginInstallLogChunk 是 pnpm 运行输出的一块，归于其 request id 与 job id 之下，带命令行、目录、流，以及运行最后一块上的退出码；PluginInstallProgress 是一次安装的 request id 与 Host 阶段；PluginChange 给出 plugin-manager/changed 事件背后的操作，管理器之外应用的一代 patch 记为 reload。

ChangeResult.changed 独立报告磁盘修改，application 为 applied、restart-required、overridden、failed 或 cancelled。message 描述结果。可选的 packageResult 记录 pnpm 退出码、有界输出、截断标记、完整诊断日志路径，以及失败运行的失败类别；可选的 bundle 给出安装新增的包。

Cordis API

Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.

ctx.hmr — Hmr

Hot reload service with Cordis-compatible module configuration and events.

/** Serialize a caller-owned mutation with all automatic reload paths.
 * @param operation Work that must not overlap module or configuration replacement.
 * @returns The operation result after its asynchronous work completes.
 */
runExclusive<T>(operation: () => Promise<T>): Promise<T>

/** Watch a configuration path through the same queue as module replacement.
 * @param filename Absolute path, which may not exist yet.
 * @param refresh Rebuilds configuration from its current files and awaits Loader completion.
 * @returns Disposer closing this registration and waiting for its pending refresh.
 */
async watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>

/** Read direct module dependency URLs from the active Node loader.
 * @param url Module URL.
 * @returns Linked module URLs, or an empty list for an uncached module.
 */
async getLinked(url: string): Promise<string[]>

Source: packages/boot/hmr/src/index.ts

ctx.pluginManager — PluginManager

Manage profile files and apply their declared reload lifecycle.

/** Read current plugins, including why a row cannot be changed through the profile patch.
 * @returns Current runtime entries with persistent patch targets.
 */
@Remote async listPlugins(): Promise<PluginInfo[]>

/** Read installed bundles and bundles supplied by this dsh installation.
 * @returns Package versions, titles, rows, activation selections and removal availability.
 */
@Remote listBundles(): Promise<BundleInfo[]>

/** Read what a spec names before installing it.
 * @param spec One package spec: a registry name, an absolute path, a git address, or a tarball.
 * @param signal Ends a registry lookup early.
 * @returns The package the spec names, or why it is refused.
 */
@Remote async inspect(spec: string, signal?: AbortSignal): Promise<PluginSpecInspection>

/** Persist a plugin entry's desired enablement and apply it on live profiles.
 * @param id Loader entry identity returned by listPlugins.
 * @param enabled Whether the plugin should run.
 * @returns Saved and runtime outcomes, including higher-priority overrides.
 */
@Remote setPluginEnabled(id: PluginEntryId, enabled: boolean): Promise<ChangeResult>

/** Select or remove a bundle layer while retaining installed dependencies.
 * @param name Bundle package name.
 * @param enabled Whether the bundle contributes its patch layer.
 * @returns Persisted and runtime outcomes.
 */
@Remote setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>

/**
 * Install a package using the same pnpm implementation as dsh plugin. A run
 * that fails, is cancelled, or adds a package without a bundle patch restores
 * `package.json` and `pnpm-lock.yaml` as they were; downloaded files can stay.
 * @param spec One package spec, including local paths relative to the invocation directory.
 * @param options Whether to activate the installed bundle (defaults to true) and the request id a cancellation names.
 * @returns Package-manager diagnostics and observed activation outcome.
 */
@Remote installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>

/** Stop an installation this manager owns and wait until its files are back.
 * @param requestId The id the installation was started with.
 * @returns `cancelled` once pnpm exited and the files are restored, `too-late` once the bundle is being
 * applied, `not-running` for any other id.
 */
@Remote async cancelInstall(requestId: PluginInstallRequestId): Promise<PluginInstallCancellation>

/** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path.
 * @param name Installed dependency name.
 * @returns Removal diagnostics and the remaining profile state.
 */
@Remote removeBundle(name: string): Promise<ChangeResult>

Source: packages/boot/plugin-manager/src/index.ts

ctx.profileContext — ProfileContext

Current profile facts; scheduling and mutation belong to their callers.

Source: packages/boot/app-boot/src/profile-context.ts

hmr/* events

hmr/change — emit

A watched file has no module or configuration handler.

/** A watched file has no module or configuration handler.
 * @mode emit
 * @param url Canonical file URL.
 */
'hmr/change'(url: string): void

Source: packages/boot/hmr/src/index.ts

hmr/reload — emit

Module replacements have finished loading.

/** Module replacements have finished loading.
 * @mode emit
 * @param reloads Replaced plugins and their module locations.
 */
'hmr/reload'(reloads: Map<Plugin, Reload>): void

Source: packages/boot/hmr/src/index.ts

plugin-manager/* events

plugin-manager/changed — emit

The profile's plugins, bundles, or composition changed: a manager operation completed, or a patch generation was applied.

/**
 * The profile's plugins, bundles, or composition changed: a manager
 * operation completed, or a patch generation was applied.
 * @mode emit
 * @param change - what changed.
 */
'plugin-manager/changed'(change: PluginChange): void

Source: packages/boot/plugin-manager/src/types.ts

plugin-manager/install-log — emit

One chunk of a pnpm run's output, streamed as the run produces it.

/**
 * One chunk of a pnpm run's output, streamed as the run produces it.
 * @mode emit
 * @param chunk - the chunk and the run it belongs to.
 */
'plugin-manager/install-log'(chunk: PluginInstallLogChunk): void

Source: packages/boot/plugin-manager/src/types.ts

plugin-manager/install-state — emit

An installation moved between its Host phases.

/**
 * An installation moved between its Host phases.
 * @mode emit
 * @param progress - the installation's request id and phase.
 */
'plugin-manager/install-state'(progress: PluginInstallProgress): void

Source: packages/boot/plugin-manager/src/types.ts

profile/* events

profile/reconciled — emit

A complete patch generation was applied to the root Include and the Loader settled, whether or not every row activated.

/**
 * A complete patch generation was applied to the root Include and the
 * Loader settled, whether or not every row activated.
 * @mode emit
 * @param patches - the ordered patch list that was applied.
 */
'profile/reconciled'(patches: readonly PatchOptions[]): void

Source: packages/boot/app-boot/src/index.ts