fix: address ds-review-bot v6/v7 findings on the image-input assembly

- resolveLlmRoute: reuse the yml pi-ai row for providers it already routes (DUPLICATE_ADAPTER boot failure) and detect an unset model by origin, not by comparison against one deployment default; covered by a new spec. - LlmService.resolveModelInfoFor preserves (and validates) modality metadata, arming the host image preflight for exact-route resolution. - session.selectModel refuses a text-only target once the session log carries an image on any replayed route; an accepted switch would strand every later turn with no in-product recovery. - The composer no longer gates image intake on the handshake activeModel snapshot (wrong authority for a per-session decision); the host preflight plus the error strip own capability, deployment limits stay client-side. - InputHub shell teardown releases the scope's draft images (File objects and object URLs leaked for the page lifetime). - session.prompt image parts carry optional alt into the durable block; ImageBlock documents assistant-side rendering as forward compatibility. - Assembled built-client lane apps/web/tests/image-display.snapshot.ts pins the history galleries over the authorized attachment route, the lightbox, and the composer paste rail; the attachment rail is an accessible group. - Docs: validateImage on the seam page, fixture byte metadata matches its PNG, and the Agent Note claims now match the shipped coverage.
2026-07-29 18:56:40 +08:00
parent 22e48c1953
commit adce3b833d
21 changed files with 526 additions and 36 deletions
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -61,6 +61,61 @@ export function resolveLanTrust(
  return { lanAddresses, trustedHosts: [...lanAddresses, ...extra] }
 }

+/** One provider/model source layer for {@link resolveLlmRoute}, in override order. */
+export interface LlmRouteInput {
+  /** CLI flag values (highest precedence). */
+  cli: { provider?: string | undefined; model?: string | undefined }
+  /** Profile-json values (parsed JSON — validated here, the config boundary). */
+  profile: { provider?: unknown; model?: unknown }
+  /** The api-gateway yml row's config values (deployment defaults). */
+  gateway: { provider?: unknown; model?: unknown }
+  /** Providers the shipped yml already routes through its static pi-ai row. */
+  ymlPiAiProviders: readonly string[]
+}
+
+/** The boot's resolved LLM routing decision. */
+export interface LlmRoute {
+  /** Effective api-gateway provider. */
+  provider: string
+  /** Pi-ai provider to mount dynamically; undefined when DeepSeek or a yml-routed provider serves the request. */
+  dynamicPiAiProvider: string | undefined
+}
+
+/**
+ * Resolve the boot's LLM route from the layered provider/model sources.
+ * A non-DeepSeek provider requires a model set at least as explicitly as the
+ * provider itself (flag/profile) — origin decides, never a comparison against
+ * any deployment's default model value, so editing the yml default cannot
+ * silently disarm the guard. Providers the shipped yml pi-ai row already
+ * routes are NOT mounted again: `LlmService.registerAdapter` rejects
+ * duplicate routes, so the gateway provider/model patch alone selects them.
+ * @param input - the layered provider/model sources and the yml pi-ai roster.
+ * @returns the effective provider and the dynamic pi-ai mount decision.
+ */
+export function resolveLlmRoute(input: LlmRouteInput): LlmRoute {
+  const provider = input.cli.provider ?? input.profile.provider ?? input.gateway.provider
+  if (typeof provider !== 'string' || provider === '') {
+    throw new Error('dsh: api-gateway provider must be a non-empty string')
+  }
+  if (provider !== 'deepseek') {
+    const providerFromYml = input.cli.provider === undefined && input.profile.provider === undefined
+    // A yml-set provider trusts its own row pairing; an override must bring
+    // its model along instead of inheriting the yml default's.
+    const model = providerFromYml
+      ? input.gateway.model
+      : input.cli.model ?? input.profile.model
+    if (typeof model !== 'string' || model === '') {
+      throw new Error(`dsh: provider ${provider} requires an explicit model`)
+    }
+  }
+  return {
+    provider,
+    dynamicPiAiProvider: provider === 'deepseek' || input.ymlPiAiProviders.includes(provider)
+      ? undefined
+      : provider,
+  }
+}
+
 /** One profile-json key mapped onto a yml row's config field. */
 interface ProfileMapping {
  jsonPath: string
@@ -207,15 +262,16 @@ export class AppCLIEntry {
    if (this.options.model !== undefined) put('api-gateway', 'model', this.options.model)

    const gatewayConfig = rows.get('api-gateway')?.config as Record<string, unknown> | undefined
-    const provider = this.options.provider ?? profile.provider ?? gatewayConfig?.provider
-    const model = this.options.model ?? profile.model ?? gatewayConfig?.model
-    if (typeof provider !== 'string' || provider === '') {
-      throw new Error('dsh: api-gateway provider must be a non-empty string')
-    }
-    if (provider !== 'deepseek' && (typeof model !== 'string' || model === '' || model === 'deepseek-v4-flash')) {
-      throw new Error(`dsh: provider ${provider} requires an explicit model`)
-    }
-    this.piAiProvider = provider === 'deepseek' ? undefined : provider
+    const piAiRow = rows.get('llm-pi-ai')?.config as { providers?: { provider?: unknown }[] } | undefined
+    const route = resolveLlmRoute({
+      cli: { provider: this.options.provider, model: this.options.model },
+      profile: { provider: profile.provider, model: profile.model },
+      gateway: { provider: gatewayConfig?.provider, model: gatewayConfig?.model },
+      ymlPiAiProviders: (piAiRow?.providers ?? [])
+        .map(p => p.provider)
+        .filter((value): value is string => typeof value === 'string'),
+    })
+    this.piAiProvider = route.dynamicPiAiProvider

    // Source 2b: authorities for the /api browser-trust fence (rationale on
    // resolveLanTrust).
--- a/apps/cli/tests/llm-route.spec.ts
+++ b/apps/cli/tests/llm-route.spec.ts
@@ -0,0 +1,61 @@
+/** resolveLlmRoute: layered provider/model resolution and the dynamic pi-ai mount decision. */
+import { describe, expect, it } from 'vitest'
+import { resolveLlmRoute } from '../src/app-cli-entry.ts'
+
+/** The shipped yml shape: DeepSeek gateway default plus a pi-ai row routing openai/anthropic. */
+const SHIPPED = {
+  gateway: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+  ymlPiAiProviders: ['openai', 'anthropic'],
+}
+
+describe('resolveLlmRoute', () => {
+  it('keeps the DeepSeek default without any dynamic mount', () => {
+    expect(resolveLlmRoute({ cli: {}, profile: {}, ...SHIPPED }))
+      .toEqual({ provider: 'deepseek', dynamicPiAiProvider: undefined })
+  })
+
+  it('reuses the yml pi-ai row for providers it already routes (no duplicate adapter)', () => {
+    expect(resolveLlmRoute({
+      cli: { provider: 'anthropic', model: 'claude-opus-4-8' }, profile: {}, ...SHIPPED,
+    })).toEqual({ provider: 'anthropic', dynamicPiAiProvider: undefined })
+  })
+
+  it('mounts pi-ai dynamically only for providers absent from the yml row', () => {
+    expect(resolveLlmRoute({
+      cli: { provider: 'google', model: 'gemini-3-pro' }, profile: {}, ...SHIPPED,
+    })).toEqual({ provider: 'google', dynamicPiAiProvider: 'google' })
+  })
+
+  it('requires an explicit model wherever the provider override came from, by origin', () => {
+    // CLI provider with no CLI/profile model: the yml DeepSeek default must not leak in.
+    expect(() => resolveLlmRoute({ cli: { provider: 'anthropic' }, profile: {}, ...SHIPPED }))
+      .toThrow(/provider anthropic requires an explicit model/)
+    // Profile provider paired with a profile model is explicit enough.
+    expect(resolveLlmRoute({
+      cli: {}, profile: { provider: 'openai', model: 'gpt-5' }, ...SHIPPED,
+    })).toEqual({ provider: 'openai', dynamicPiAiProvider: undefined })
+    // Profile provider with only the yml default model: same gap, same refusal.
+    expect(() => resolveLlmRoute({ cli: {}, profile: { provider: 'openai' }, ...SHIPPED }))
+      .toThrow(/provider openai requires an explicit model/)
+  })
+
+  it('trusts a yml-set non-DeepSeek provider only when its own row carries the model', () => {
+    expect(resolveLlmRoute({
+      cli: {}, profile: {},
+      gateway: { provider: 'anthropic', model: 'claude-opus-4-8' },
+      ymlPiAiProviders: ['openai', 'anthropic'],
+    })).toEqual({ provider: 'anthropic', dynamicPiAiProvider: undefined })
+    expect(() => resolveLlmRoute({
+      cli: {}, profile: {},
+      gateway: { provider: 'anthropic' },
+      ymlPiAiProviders: ['openai', 'anthropic'],
+    })).toThrow(/provider anthropic requires an explicit model/)
+  })
+
+  it('fails loud on a missing or empty provider', () => {
+    expect(() => resolveLlmRoute({ cli: {}, profile: {}, gateway: {}, ymlPiAiProviders: [] }))
+      .toThrow(/provider must be a non-empty string/)
+    expect(() => resolveLlmRoute({ cli: { provider: '' }, profile: {}, ...SHIPPED }))
+      .toThrow(/provider must be a non-empty string/)
+  })
+})
--- a/apps/web/tests/image-display.snapshot.ts
+++ b/apps/web/tests/image-display.snapshot.ts
@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+// Multimodal image surfaces over the BUILT client graph (the code-mode-fixture
+// idiom: real bundles via AppWebEntry, keyless FixtureApiClient transport).
+// Opens the fixture history session whose turn 65 carries an image in BOTH a
+// user message and an assistant message, and pins the product surfaces: the
+// history ImageGallery loading real fixture bytes through the authorized
+// sessions.attachment route, the double-click ImageLightbox, and the composer
+// intake chain (paste → thumbnail rail → image-only send enablement → remove).
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
+import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
+
+const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
+  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  {
+    id: '@deepseek-ai/dsh-client-ui-workspace',
+    dir: 'ui-workspace',
+    url: '/plugins/ui-workspace.js',
+    rev: 'fx',
+    inject: [
+      '@deepseek-ai/dsh-client-runtime',
+      '@deepseek-ai/dsh-client-ui-conversation',
+      '@deepseek-ai/dsh-client-ui-sidebar',
+    ],
+  },
+]
+
+const bundles = new Map(PLUGINS.map(plugin => [
+  plugin.url,
+  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
+]))
+
+interface FixtureWindow extends Window {
+  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
+  __ModuleLoader__?: unknown
+}
+
+class ResizeObserverStub {
+  observe(): void {}
+  disconnect(): void {}
+  unobserve(): void {}
+}
+
+const win = window as FixtureWindow
+let unmount: (() => void) | undefined
+
+beforeEach(() => {
+  localStorage.clear()
+  document.title = 'DeepSeek Harness'
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+    setTimeout(() => { callback(0) }, 0) as unknown as number)
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
+})
+
+afterEach(() => {
+  act(() => { unmount?.() })
+  unmount = undefined
+  cleanup()
+  delete win.__DSH_BOOT__
+  delete win.__ModuleLoader__
+  document.body.innerHTML = ''
+  document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
+  document.title = ''
+  history.replaceState(null, '', '/')
+  vi.unstubAllGlobals()
+})
+
+/** Boot the complete built client graph against the populated fixture branch. */
+function boot(): void {
+  history.replaceState(null, '', '/?fixture')
+  const root = document.createElement('div')
+  root.id = 'root'
+  document.body.appendChild(root)
+  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
+  act(() => {
+    const entry = new AppWebEntry(root, {
+      fetchBundle: (url) => {
+        const code = bundles.get(url)
+        return code === undefined ? Promise.reject(new Error(`missing built bundle ${url}`)) : Promise.resolve(code)
+      },
+      executeBundle: (code) => { (0, eval)(code) },
+    })
+    void entry.run()
+    unmount = () => { entry.dispose() }
+  })
+}
+
+/** Open the fixture history session (the alpha log carrying the turn-65 image pair) and wait for its gallery. */
+async function openFixtureSession(): Promise<void> {
+  const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
+  const group = (await within(tree).findAllByText('fixture'))
+    .map(el => el.closest<HTMLElement>('[role="treeitem"]'))
+    .find(el => el?.getAttribute('aria-expanded') !== null)
+  if (group === null || group === undefined) throw new Error('fixture Workspace group missing')
+  if (group.getAttribute('aria-expanded') === 'false') {
+    fireEvent.click(within(group).getByText('fixture'))
+    await waitFor(() => {
+      expect(group.getAttribute('aria-expanded')).toBe('true')
+    })
+  }
+  const session = await within(tree).findByText('Fixture 历史会话')
+  fireEvent.click(session)
+  await waitFor(() => {
+    expect(document.querySelectorAll('[data-align] img').length).toBeGreaterThan(0)
+  }, { timeout: 10_000 })
+}
+
+it('renders the history image pair through the authorized attachment route and opens the lightbox', async () => {
+  boot()
+  await openFixtureSession()
+
+  // Both the user-side (align=end) and assistant-side (align=start) galleries
+  // load real fixture bytes over sessions.attachment (data: fallback in jsdom).
+  await waitFor(() => {
+    const user = document.querySelector('[data-align="end"] img')
+    const assistant = document.querySelector('[data-align="start"] img')
+    if (user === null || assistant === null) throw new Error('history image galleries missing')
+    // jsdom serves object URLs; environments without createObjectURL fall back to data:.
+    expect(user.getAttribute('src')).toMatch(/^(blob:|data:image\/png;base64,)/)
+    expect(assistant.getAttribute('src')).toMatch(/^(blob:|data:image\/png;base64,)/)
+  }, { timeout: 10_000 })
+  const userImage = document.querySelector<HTMLElement>('[data-align="end"] img')!
+  expect(userImage.getAttribute('alt')).toBe('fixture-image.png')
+
+  // Double-click opens the original-size lightbox; Escape/close dismisses it.
+  const frame = userImage.closest('button')
+  if (frame === null) throw new Error('image frame button missing')
+  fireEvent.doubleClick(frame)
+  const lightbox = await screen.findByRole('dialog')
+  expect(within(lightbox).getByRole('img').getAttribute('src')).toMatch(/^(blob:|data:image\/png;base64,)/)
+  fireEvent.click(within(lightbox).getByRole('button', { name: /关闭/ }))
+  await waitFor(() => {
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+})
+
+it('accepts a pasted image into the composer rail and removes it', async () => {
+  boot()
+  await openFixtureSession()
+
+  // Image-only send arming is pinned at package level (input-bar.spec.tsx);
+  // this assembled lane pins the intake chain over the built graph.
+  const textarea = await screen.findByPlaceholderText('Message the agent', {}, { timeout: 10_000 })
+  const image = new File([new Uint8Array([137, 80, 78, 71])], 'pasted.png', { type: 'image/png' })
+  fireEvent.paste(textarea, {
+    clipboardData: {
+      items: [{ kind: 'file', type: 'image/png', getAsFile: () => image }],
+      getData: () => '',
+    },
+  })
+
+  // The rail is an accessible group holding the draft thumbnail (queried via
+  // DOM: jsdom's a11y-visibility computation hides the composer subtree).
+  const rail = await waitFor(() => {
+    const el = document.querySelector('[role="group"][aria-label="待发送图片"]')
+    if (el === null) throw new Error('attachment rail missing')
+    return el
+  }, { timeout: 5_000 })
+  expect(rail.querySelector('img')?.getAttribute('src')).toMatch(/^(blob:|data:)/)
+
+  const remove = rail.querySelector('button[aria-label^="移除图片"]')
+  if (remove === null) throw new Error('remove button missing')
+  fireEvent.click(remove)
+  await waitFor(() => {
+    expect(document.querySelector('[role="group"][aria-label="待发送图片"]')).toBeNull()
+  })
+})