CaiZongyuan/dsh-ag-ui ↗★ 5

dsh-ag-ui

提供已认证的AG-UI HTTP与SSE网关服务 适合需要通过HTTP和SSE网关接入并管理AG-UI及浏览器工具的用户。

包名
dsh-ag-ui
兼容性
待验证
Harness 依赖范围
0.1.5-rc.2
Cordis 依赖范围
4.0.2
版本
0.1.0
许可证
MIT
最近更新
2026年9月15日

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:CaiZongyuan/dsh-ag-ui

Profile configuration

Environment variables are the shortest setup path. A Profile can instead override the bundle row in its own cordis.patch.yml:

- id: ag-ui
  disabled: false
  config:
    provider: openai
    model: gpt-5.6-sol
    sharedSecret: !!js process.env.DSH_AG_UI_SHARED_SECRET
    path: /ag-ui
    maxThreads: 100
    frontendToolTimeoutMs: 300000

A later Profile patch replaces the bundle row's complete config; include every value that deployment needs.

Configuration

provider, model, and sharedSecret are required. sharedSecret must contain at least 16 UTF-8 bytes.

FieldDefaultPurpose
path/ag-uiBase Host HTTP route for runs and files
providerrequiredRegistered DSH model provider route
modelrequiredModel ID owned by the provider
workspaceRoot/workspacesRoot for per-thread workspace directories, named by durable session id
agentPresetnoneDeployment-default agent preset id composed into every thread
tenantPresets{}Per-tenant preset ids taking precedence over agentPreset
selectableAgentPresets{}Canonical preset ids each authenticated tenant may select for a blank thread
sharedSecretrequiredBearer secret shared only with the trusted BFF
tenantHeaderx-dsh-tenant-idTrusted tenant identity header
userHeaderx-dsh-user-idTrusted user identity header
allowNonLoopbackfalsePermit a non-loopback Host bind explicitly
maxRequestBytes262144Maximum request body bytes
maxFileBytes104857600Maximum bytes per uploaded file or deliverable download
maxIdentityBytes256Maximum bytes per protocol or identity ID
maxMessages256Maximum message count per request
maxMessageBytes524288Maximum combined message JSON bytes
maxFilesPerMessage8Maximum non-text parts in one user message
maxContexts32Maximum context entry count
maxContextBytes131072Maximum combined context JSON bytes
maxTools32Maximum browser Tool count
maxToolBytes131072Maximum browser Tool JSON bytes
maxToolSchemaDepth16Maximum browser Tool schema depth
maxForwardedPropsBytes65536Maximum forwardedProps JSON bytes
maxStateBytes65536Maximum state JSON bytes
maxThreads100Maximum process-local live threads
threadIdleMs1800000Idle thread lifetime
frontendToolTimeoutMs300000Maximum browser Tool result wait
humanInteractionTimeoutMs300000Maximum wait for each native human request; integer from 1 to 2147483647 ms
maxPendingInterrupts16Maximum live human requests per thread
maxRunEvents4096Maximum events retained per run
maxRunEventBytes2097152Maximum retained event bytes per run
maxRunsPerThread32Maximum retained run ledger entries and, separately, waiting requests per thread

agentPreset composes each thread's agent from the host's agent-presets roster (mount the roster plugin before this Gateway); an unresolvable id fails Gateway activation loudly, a per-tenant entry overrides the deployment default for that tenant's threads, and a resumed thread keeps the composition its own durable session recorded. Without agentPreset, threads keep the host composition unchanged.

Each thread uses / as its DSH working directory. The directory is named by the durable session id, so client thread ids stay off disk. When the Host provides workspaceRegistry, the Gateway registers new workspaces for DSH Web.

File routes require the official fileUploads and attachments services, already mounted by @deepseek-ai/dsh-web-app. POST /threads//files streams the raw body with content-length, optional content-type, and percent-encoded x-file-name. Harness owns streamed storage, content hashes, temporary-file cleanup, and staged receipts. The response retains its AG-UI URL source and filename/size/sha256 metadata.

Clients must preserve the returned URL query when changing a proxy prefix. The gateway signs the native file reference and receipt for the authenticated session. GET verifies the signature and principal/thread mapping before calling the official streamed reader. Same-name uploads keep their display name and receive distinct receipt URLs. Downloads remain authorized after cold resume; rotating the shared secret invalidates old URLs. Pre-native unsigned upload URLs require a fresh upload.

User messages accept ordered text and signed thread-file URL parts. Images use official image admission; other files become native file content parts. Harness owns receipt binding, successful admission retirement, and rollback when queue delivery fails. Rejected admission can retry its still-staged receipt. A consumed, explicitly retired, or cold unsent receipt returns FILE_NOT_STAGED and requires re-upload; the gateway never restores expired authority. MESSAGES_SNAPSHOT preserves the exact accepted AG-UI parts. Shared-state and frontend Tool admission are revalidated after asynchronous file processing, before publishing those parts. Inline data parts are not accepted.

For multiple presets within one tenant, the host can grant selection with selectableAgentPresets: { "tenant-1": ["alpha", "beta"] }. A run may then request forwardedProps: { agentPreset: "beta" }. The Gateway validates grants against the roster at activation and calls native agentPresets.select under the thread's run reservation before its first turn. The roster alone grants no authority, and the BFF must still authenticate the tenant and authorize access to its application features.

Selection is optional. Omitting it preserves the current composition; repeating the effective canonical id is a no-op, including after restart. A different ungranted id fails with HTTP 403 PRESET_NOT_ALLOWED; a granted change after the first turn fails with HTTP 409 PRESET_LOCKED. A history-only request never selects a preset, so a session created by a history read can still choose one on its first work run. The native session log owns the selected composition and restores it after restart. Tool names are validated against the selected composition before SSE starts. A successful selection remains recorded if that validation rejects the run or its client disconnects; no user turn is started, and the blank session can select again.

maxRunEvents must retain at least the mandatory opening and terminal events. maxRunEventBytes bounds the complete retained Run record, including RUN_STARTED and its terminal event, and must be large enough for the configured maximum identity length. A non-loopback DSH WebServer requires allowNonLoopback: true. Prefer a loopback Gateway behind a same-host authenticated BFF.

Opening and final durable history snapshots both count toward this bound. Buffer overflow ends the HTTP run and cancels only its currently claimed native turn. An overflowing history-only read does not cancel another active turn. Completed duplicate requests still replay the exact retained events.