fix(web): include the HMR receiver in the initial client graph

2026-08-10 19:58:40 +08:00
parent 37ee7b0f24
commit a4d8c0da9b
19 changed files with 125 additions and 48 deletions
--- a/packages/boot/cmdline/README.i18n.yaml
+++ b/packages/boot/cmdline/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/cmdline/README.md
-README.md: dc267080d32d492e132df4592ddf742454a95ad2
-README.zh.md: e183156ab4a7907f8ae1e3259b2e09d458cec47d
+README.md: 571ea7acf9f7be1ee2bdadafae2fc71b99d4536a
+README.zh.md: 271acd6be4d58bf12d41bc02dd3ccabc7359a269
--- a/packages/boot/cmdline/README.md
+++ b/packages/boot/cmdline/README.md
@@ -56,7 +56,7 @@ Every row the app configures from flags then reads what the startup row resolved

 Loader defers a row's `!!js` interpolation until that row's declared injections are active, then evaluates against the row's plugin context. The example above can therefore read `ctx.webStartup` directly: Cordis has already populated that injected service before Loader asks for `webserver`'s config. Include trees preserve nested expression nodes until each target row reaches this point. Provider replacement and live patch reload repeat interpolation against the current injected services, so a launch flag cannot be silently reset.

-`enableRow(ctx, id)` turns on a row a bundle ships disabled because only some invocations want it (`dsh web --dev` and its client-plugin reload chain). Loader applies the enabled row's ordinary injection ordering.
+`enableRow(ctx, id)` turns on a row a bundle ships disabled because only some invocations want it (`dsh web --dev` and its client-plugin reload chain). The activation is an in-memory override: it does not rewrite the row's configured `disabled` value and survives config reapplication for that mounted entry. Loader applies the enabled row's ordinary injection ordering.

 ### One command line, one owner

--- a/packages/boot/cmdline/README.zh.md
+++ b/packages/boot/cmdline/README.zh.md
@@ -56,7 +56,7 @@ Loader 行的注入同时也是发现声明，因此无需组合包 manifest 字

 Loader 会把一行的 `!!js` 插值推迟到该行声明的注入全部激活之后，再基于该行的插件上下文求值。所以上例可以直接读取 `ctx.webStartup`：Loader 索取 `webserver` 的配置之前，Cordis 已经填入了这个注入服务。Include 树会保留嵌套表达式节点，直到各个目标行到达这一时点。提供方替换与活动 patch 重载都会针对当前注入服务重新插值，因此启动 flag 不会被悄悄重置。

-`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。Loader 会对启用后的行应用普通的注入顺序。
+`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。该激活是内存中的覆盖：它不会改写行所配置的 `disabled` 值，并会在已挂载条目的配置重新应用后继续生效。Loader 会对启用后的行应用普通的注入顺序。

 ### 一条命令行，一个所有者

--- a/packages/boot/cmdline/src/index.ts
+++ b/packages/boot/cmdline/src/index.ts
@@ -221,6 +221,8 @@ export function runStartup<T>(
 * A row cannot be inserted from inside a mounting plugin — the Loader returns a
 * prefixed id it then fails to resolve — so a conditional row ships disabled
 * and a row mounted beside it enables it after startup resolves the invocation.
+ * The Loader keeps that activation in memory, separate from serialized options,
+ * so reapplying the composition cannot restore the invocation's row to disabled.
 * @param ctx - plugin context whose Loader tree carries the row.
 * @param id - the row id.
 * @returns nothing once the row has started or is waiting for its dependencies.
@@ -231,7 +233,7 @@ export async function enableRow(ctx: Context, id: string): Promise<void> {
  if (loader === undefined) throw new Error('dsh-cmdline: enabling a row requires the Loader service')
  const entry = [...loader.entries()].find(candidate => candidate.options.id === id)
  if (entry === undefined) throw new Error(`dsh-cmdline: the composition has no ${JSON.stringify(id)} row to enable`)
-  await entry.update({ disabled: false })
+  await entry.enableRuntime()
 }

 /**
--- a/packages/boot/cmdline/tests/cmdline.spec.ts
+++ b/packages/boot/cmdline/tests/cmdline.spec.ts
@@ -234,17 +234,63 @@ describe('enableRow', () => {
    await expect(enableRow(withoutLoader, 'client-hmr')).rejects.toThrow('requires the Loader service')

    const ctx = new Context()
-    let update: unknown
+    let enabled = false
    ctx.provide('loader', {
      entries: () => [{
        options: { id: 'client-hmr' },
-        update: async (options: unknown) => { update = options },
+        enableRuntime: async () => { enabled = true },
      }],
    } as never)
    await enableRow(ctx, 'client-hmr')
-    expect(update).toEqual({ disabled: false })
+    expect(enabled).toBe(true)
    await expect(enableRow(ctx, 'absent')).rejects.toThrow('no "absent" row to enable')
  })
+
+  it('keeps invocation-only activation through config reapplication', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-runtime-enable-'))
+    const observed = { starts: 0, stops: 0 }
+    ;(globalThis as unknown as { __runtimeEnableObserved: typeof observed }).__runtimeEnableObserved = observed
+    writeFileSync(join(dir, 'conditional.mjs'), `
+export function apply(ctx) {
+  globalThis.__runtimeEnableObserved.starts += 1
+  ctx.effect(() => () => { globalThis.__runtimeEnableObserved.stops += 1 })
+}
+`)
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: conditional',
+      `  name: ${pathToFileURL(join(dir, 'conditional.mjs')).href}`,
+      '  disabled: true',
+      '',
+    ].join('\n'))
+
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    await ctx.loader.create({
+      name: 'cordis:include',
+      config: { path: pathToFileURL(join(dir, 'cordis.yml')).href },
+    })
+    await ctx.loader.await()
+    const conditional = [...ctx.loader.entries()].find(entry => entry.options.id === 'conditional')
+    const include = [...ctx.loader.entries()].find(entry => entry.options.name === 'cordis:include')
+    expect(conditional).toBeDefined()
+    expect(include?.fiber).toBeDefined()
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 0, stops: 0 })
+
+    await enableRow(ctx, 'conditional')
+    await ctx.loader.await()
+    expect(conditional?.disabled).toBe(false)
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 1, stops: 0 })
+
+    await include!.fiber!.update(include!.options.config, true)
+    await ctx.loader.await()
+    expect(conditional?.disabled).toBe(false)
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 1, stops: 0 })
+    disposers.push(async () => { await ctx.fiber.dispose() })
+  })
 })

 describe('provideCmdline', () => {
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
-README.md: fb6a1a3ee5293c7e90afae11a76fe5a8598f3ee8
-README.zh.md: d8276514d94e658788371034795a073abefbf6ac
+README.md: 47b582225e768ac035d12947939c7a7eb700458c
+README.zh.md: 61e134f90e7ae57cb6220e92880c001f0d06bae2
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. This bundle also owns the app command line: the `web-startup` row ([`src/startup.ts`](src/startup.ts)) parses `--host`, `--port`, `--dev`, and repeatable `--trusted-host` from `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)) and prints the app's `--help`. Every row it configures injects `webStartup`, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. `mode` and `lanAddresses` resolve on every boot because they describe the invocation. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, enables the optional HMR row before client-module discovery so the first development graph contains its reload receiver, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. This bundle also owns the app command line: the `web-startup` row ([`src/startup.ts`](src/startup.ts)) parses `--host`, `--port`, `--dev`, and repeatable `--trusted-host` from `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)) and prints the app's `--help`. Every row it configures injects `webStartup`, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. `mode` and `lanAddresses` resolve on every boot because they describe the invocation. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.

 ## Model Experience

--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。本组合包还持有应用命令行：`web-startup` 行（[`src/startup.ts`](src/startup.ts)）从 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)）解析 `--host`、`--port`、`--dev` 以及可重复的 `--trusted-host`，并打印应用自己的 `--help`。它所配置的每一行都注入 `webStartup`，因此在参数解析完成之前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。`mode` 与 `lanAddresses` 在每次 boot 时解析，因为它们描述的是本次调用。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，在客户端模块发现前启用可选的 HMR 行，确保首份开发模式图中包含它的重载接收端，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。本组合包还持有应用命令行：`web-startup` 行（[`src/startup.ts`](src/startup.ts)）从 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)）解析 `--host`、`--port`、`--dev` 以及可重复的 `--trusted-host`，并打印应用自己的 `--help`。它所配置的每一行都注入 `webStartup`，因此在参数解析完成之前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。`mode` 与 `lanAddresses` 在每次 boot 时解析，因为它们描述的是本次调用。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。

 ## 模型体验

--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -116,8 +116,8 @@
        lanAddresses: !!js ctx.get('webStartup')?.lanAddresses ?? []

    # The client-plugin reload chain: a dev-only row this bundle ships off,
-    # which the runtime row turns on for `--dev`. It is a row rather than a
-    # child of web-runtime because its node half is a client-side package,
+    # which the runtime row turns on before client discovery. It is a row rather
+    # than a child of web-runtime because its node half is a client-side package,
    # which a host-side bundle cannot import.
    - id: client-hmr
      name: '@deepseek-ai/dsh-client-hmr'
@@ -126,12 +126,14 @@

    # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──

-    # Dual-face: node half scans this very tree for dsh.client rows, composes
-    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
-    # module table the shell kernel constructs before cordis exists (adopted
-    # as a plugin entry by the kernel, never fetched).
+    # Dual-face: this waits for the runtime row to decide whether HMR belongs
+    # in the first graph. The node half then scans this tree, composes
+    # window.__DSH_BOOT__, and serves /plugins/<id>/client.js; the browser half
+    # is the module table the shell kernel constructs before cordis exists
+    # (adopted as a plugin entry by the kernel, never fetched).
    - id: modules
      name: '@deepseek-ai/dsh-client-modules'
+      inject: [webClientRoster]

    # Owns both ends of the web transport: node half binds the gateway to the
    # webserver under /api; browser half is the fetch/SSE client.
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -25,11 +25,10 @@ import type {} from '@deepseek-ai/dsh-bash-env'
 /** Stable Cordis plugin name. */
 export const name = 'web-app'

-/** The client-plugin reload chain row this bundle ships disabled, for `--dev`. */
-const HMR_ROW_ID = 'client-hmr'
-
 /** This dsh installation's root, from either this package's source or built entry. */
 const SOURCE_ROOT = fileURLToPath(new URL('../../../..', import.meta.url))
+const HMR_ROW_ID = 'client-hmr'
+const CLIENT_ROSTER_SERVICE = 'webClientRoster'

 /** Services required before the web runtime can mount. */
 export const inject = ['httpServer']
@@ -118,14 +117,16 @@ export const internals: { resolveDistIndex: () => string } = { resolveDistIndex
 * variables, and the URL line.
 * @param ctx - plugin context carrying the httpServer service.
 * @param config - validated {@link Config}.
- * @returns nothing once optional development rows are active and runtime contributions are registered.
+ * @returns nothing once the invocation's client roster and runtime contributions are registered.
 */
 export async function apply(ctx: Context, config: Config): Promise<void> {
-  ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() })
-  // The client-plugin reload chain is a row this bundle ships off, because it
-  // exists only in development. Turning it on belongs here rather than in the
-  // startup row: it needs host services that also activate after webStartup.
+  // Client discovery must start after the optional HMR row has a pending
+  // fiber. Otherwise its first browser graph omits the reload receiver, which
+  // cannot use that receiver to discover itself later.
  if (config.mode === 'development') await enableRow(ctx, HMR_ROW_ID)
+  // Release client discovery only after the optional row has a pending fiber.
+  ctx.provide(CLIENT_ROSTER_SERVICE, true)
+  ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() })
  if (config.surfaceContext) {
    ctx.inject(['systemPrompt'], (promptCtx) => {
      addHarnessSourceSection(promptCtx, SOURCE_ROOT)
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -49,6 +49,19 @@ function fakeHttpServer(): { server: HttpServerService; seat: () => unknown } {
  return { server, seat: () => fallback }
 }

+/** Install the optional HMR row the runtime sequences before client discovery. */
+function provideHmrRow(ctx: Context, settle: () => Promise<void> = async () => {}): string[] {
+  const updates: string[] = []
+  ctx.provide('loader', {
+    entries: () => [{
+      options: { id: 'client-hmr' },
+      enableRuntime: async () => { updates.push('client-hmr') },
+    }],
+    await: settle,
+  } as never)
+  return updates
+}
+
 interface BashContribution {
  name: string
  variables: Record<string, { description: string }>
@@ -68,14 +81,7 @@ describe('web-app runtime glue', () => {
        return () => {}
      },
    } as never)
-    const hmrUpdates: unknown[] = []
-    ctx.provide('loader', {
-      entries: () => [{
-        options: { id: 'client-hmr' },
-        update: async (options: unknown) => { hmrUpdates.push(options) },
-      }],
-      await: async () => {},
-    } as never)
+    const enabledRows = provideHmrRow(ctx)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    await apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, lanAddresses: ['192.168.1.5'] }))
    await ctx.plugin(SystemPrompt, { persona: '' })
@@ -83,7 +89,8 @@ describe('web-app runtime glue', () => {
    await new Promise(resolve => setTimeout(resolve, 0))

    expect(seat()).toBeDefined() // frontend-static claimed the fallback
-    expect(hmrUpdates).toEqual([{ disabled: false }])
+    expect(enabledRows).toEqual(['client-hmr'])
+    expect(ctx.get('webClientRoster')).toBe(true)
    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567 (LAN: http://192.168.1.5:4567)')
    const assembly = await ctx.systemPrompt.assemble()
    expect(assembly.sections.find(entry => entry.name === 'harness:source')?.text).toContain('DeepSeek Harness implementation checkout')
@@ -148,7 +155,7 @@ describe('web-app runtime glue', () => {
    // this row itself has activated.
    const ready = new Context()
    ready.provide('httpServer', fakeHttpServer().server)
-    ready.provide('loader', { await: () => Promise.resolve() } as never)
+    provideHmrRow(ready)
    let announce: () => void
    ready.provide('appReady', new Promise<void>((resolve) => { announce = resolve }))
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
@@ -182,7 +189,7 @@ describe('web-app runtime glue', () => {
    settled.provide('httpServer', fakeHttpServer().server)
    let release: () => void
    const settlement = new Promise<void>((resolve) => { release = resolve })
-    settled.provide('loader', { await: () => settlement } as never)
+    provideHmrRow(settled, () => settlement)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    await apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
    await new Promise(resolve => setTimeout(resolve, 0))
@@ -202,7 +209,7 @@ describe('web-app runtime glue', () => {
    await child
    let releaseTorn: () => void
    const tornSettlement = new Promise<void>((resolve) => { releaseTorn = resolve })
-    torn.provide('loader', { await: () => tornSettlement } as never)
+    provideHmrRow(torn, () => tornSettlement)
    await apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
    await child.dispose() // the httpServer service goes away
    releaseTorn!()