@yadsh/dsh-qa-browser
面向 DeepSeek Harness 和 QA Surface 的会话级 Playwright 浏览器运行时
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @yadsh/dsh-qa-browser@0.4.2Qa Browser 以 @yadsh/dsh-qa-browser 发布，当前版本为 0.4.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Session-scoped Chromium runtime for DeepSeek Harness. It is the Browser-side
implementation described by SPEC-DSH-QA-BROWSER.md; QA Surface remains an
independent layout host.
The implemented foundation provides:
ctx.qaBrowser;BrowserContext per DSH session;browser_screenshot result backed by durable DSH attachments;⋯ menu, bounded on-demand PNG frames,
error states and non-focus-stealing activity reveal;No Browser code or Playwright dependency is added to dsh-qa-surface.
>=0.1.7-rc.2 <0.2.0^22.19.0 || >=24.0.0The plugin never downloads a browser in postinstall. Install a managed
Playwright Chromium explicitly in the deployment image, set an absolute
runtime.executablePath, or run runtime.mode: attach against a Chromium that
is already up with its DevTools endpoint open.
- id: dsh-qa-browser
config:
enabled: true
runtime:
provider: playwright
mode: launch
executablePath: null
browserChannel: chromium
cdpEndpoint: null
allowRemoteCdpEndpoint: false
headless: true
chromiumSandbox: true
actionTimeoutMs: 15000
navigationTimeoutMs: 30000
idleTimeoutMinutes: 30
session:
contextScope: session
maxTabs: 12
viewport:
width: 1440
height: 900
deviceScaleFactor: 1
ui:
autoRevealOnAgentActivity: true
focusOnAutoReveal: false
humanControl:
enabled: true
leaseSeconds: 30
security:
network:
allowedSchemes: [http, https]
allowLoopback: true
allowPrivateNetworks: false
allowHosts: []
denyHosts: []
denyMetadataEndpoints: true
denyDshOrigin: true
# Add the public reverse-proxy origin when it differs from Host listen.
dshOrigins: [https://qa.example.com]
allowHosts and denyHosts accept exact hostnames or a leading wildcard such
as *.internal.example. Explicitly allowed hosts may resolve to private
addresses, but cannot bypass the metadata-endpoint deny. denyHosts always
wins.
Every destination the context dials passes this gate: the document, its
redirects and subresources, and the WebSockets a page opens. A socket is not a
request the HTTP route ever sees, so it is asked about at its handshake — and
because the default allowedSchemes lists only http and https, a socket is
refused until ws or wss is added there. Service workers are blocked in a
Browser context for the same reason: a worker dials from outside every page, so
its traffic would leave past the gate with no tab to attribute it to.
A refusal is the operator's message, not only the model's. When the policy
blocks a destination, the Browser panel lists it — whether the page itself or a
request the page made, the host, how many requests were refused, and the
refusal text, which names the class of address and the setting that lifts the
block — and the Host logs browser.policy-refused with the same facts. The two
kinds read differently on purpose: a refused navigation means nothing opened,
while a refused request means the page opened without an asset or an API
answer, which is a page that looks broken rather than one that was blocked. The
panel names both ways out — an allowHosts entry for one host, or
allowPrivateNetworks for the whole deployment — because they are not
equivalent: the first opens one intranet service, the second opens every
private range to whatever the model asks for.
The notice belongs to a tab, because that is the page the operator is looking at: the banner explains the selected tab, the strip marks the other tabs the policy refused something for, and a refusal with no page behind it — a WebSocket handshake, whose route carries no frame — is shown beside the selected tab's own entries. One entry per destination, at most eight of them, counted rather than repeated, and the next navigation of that tab starts it empty.
denyDshOrigin automatically covers the active Harness listener on localhost,
the machine hostname and its network interfaces. Add reverse-proxy/public
origins explicitly through dshOrigins; Browser rechecks every redirect and
subrequest on the Host.
The QA panel uses the existing DSH Remote transport and QA bearer credential. It never embeds the target page in an iframe, persists the credential, or opens a second server. Frames are rejected above 5 MiB.
Human control is explicit and temporary. While the panel owns the lease,
mutating agent Browser tools fail with BROWSER_HUMAN_CONTROL_ACTIVE, while
snapshots and screenshots remain readable. Hiding or closing the panel releases
the lease; a lost client expires automatically.
The panel is a browser the operator can use, not just watch. A panel that does
not hold the lease renders its chrome disabled — tabs as a roster, the address
read-only — and can still copy the address or refresh the image. Taking the
lease on a chat whose browser has not started yet starts it, because every
control needs the lease and the lease needs a session. The device row resizes
the emulated viewport under the same deployment bounds the agent's
browser_viewport tool uses; clicks and context menus additionally require
capabilities.coordinateInput, and the panel says so when a deployment has
turned it off.
Back and forward are drawn from the history the Host has watched this tab visit — every navigation it performed and every one it saw committed — because Chromium exposes no "is there an entry behind this page" question. The arrows are therefore honest about what the runtime knows, and a page that arrived through a redirect is recorded as a fresh entry rather than guessed at.
The panel's own design — what each control calls, how the lease and the coordinate-input switch divide the chrome, how history depth is kept — is in the panel chrome note.
For a containerized Harness, see the Docker deployment guide. Chromium and its OS libraries must be installed inside the Harness image.
runtime.mode decides where the Chromium comes from. launch — the default —
owns one process: the plugin starts it for the first session and closes it when
the runtime shuts down. attach joins a browser that is already running, through
its DevTools endpoint:
runtime:
mode: attach
cdpEndpoint: http://127.0.0.1:9222
The endpoint is an http/https URL for the browser's DevTools server —
Playwright reads its webSocketDebuggerUrl itself — or that ws/wss URL
directly. By default it has to name this machine, and the list is read exactly:
localhost, 127.0.0.1, ::1, plus the forms the URL parser itself resolves to
those (http://127.1, http://2130706433). A *.localhost name is not on it
although it is meant to be local, and neither is localhost. with a trailing dot
— that dot turns the literal into a DNS query. This plugin never resolves the
endpoint, Playwright dials it through the system resolver, and a resolver with a
search domain can answer chrome.localhost with a machine somewhere else. For an
http or https endpoint the gate bounds the address written down, which is the
first hop: the server there replies with the ws URL to dial, and wrapping that
first request in TLS does not move the answer to the second one, so a deployment
that needs the dialled address pinned writes a ws/wss URL. Holding a CDP
endpoint means holding the browser, its every tab included and past this plugin's
own policy, so an endpoint beyond loopback — including one that merely looks like
it — needs allowRemoteCdpEndpoint: true written next to it: a decision someone
made on purpose, not a default.
The gate is this plugin's half of the answer, and the browser keeps its own:
Chromium checks the Host header of a DevTools request and answers an IP address
or localhost, on both hops — the /json/version question an http endpoint
asks and the ws upgrade that answer names. A container's service name clears
the gate once the switch is written and is then refused by the browser, before a
page ever opens, so write the address rather than the name — and not
--remote-allow-origins, which guards the Origin of an upgrade instead: the
opt-in run puts both questions to a live browser, and the name comes back refused
with that flag set just as it is without it.
The keys that choose and shape a process are refused under attach rather than
ignored: executablePath, a browserChannel other than chromium, and
chromiumSandbox: false all describe a Chromium this plugin starts, and a
deployment that wrote them would not be getting what it wrote. The refusals run
both ways: under launch, cdpEndpoint and
allowRemoteCdpEndpoint: true describe a browser this mode does not join, so
they are refused as well.
What attach mode changes, and what it deliberately does not:
Browser handle reaches the context
it came with through one method, contexts(), and this runtime never calls it —
so it drives no page inside that context and closes nothing it did not build.
SPEC §5 keeps existing user tabs a non-goal, and this is the mode that could
have broken it. What the CDP connection itself attaches to is Playwright's
business, which is why the promise is checked against a real browser: the
person's own tab is still listed by that browser after this plugin's teardown,
and a page a second driver opens in that same context neither lends its cookies
and storage to this plugin's session nor takes the session's.attach changes is
where those two halves run: the gate resolves and classifies the name in this
process, while the browser dials from wherever the deployment started it. On
one machine that is the same answer; a browser in another container has its own
resolver and its own /etc/hosts, so
an allow-list written for the Host is a judgment about a name the browser may
read differently. The gates stop at this runtime's request path, too: a
destination refused for a session of this plugin is served to a page this
plugin never built, which the same run reads off the borrowed browser.headless: false promises a window a
person can watch and click in; attach mode owns no window, so that
combination is refused when the config resolves. Whether the browser behind
the endpoint has a visible window is that browser's business — and if a person
can reach it, they can act in the pages the agent is driving. That is a
property of the endpoint you chose, not something this plugin can promise
either way.BROWSER_CONNECTION_LOST and the panel says the connection to the browser was
lost; a browser this plugin started keeps reporting BROWSER_CRASHED. Either
way the next agent action rebuilds the session instead of pretending the old
tabs are still there.pnpm --filter @yadsh/dsh-qa-browser check
The real Chromium integration tests are opt-in so a project that has nothing to
do with a browser never downloads or spawns one. This project's own CI job is
not such a project: ci.yml sets the variable below for
@yadsh/dsh-qa-browser, so what only a real browser can answer is checked on a
pull request and on main rather than left to whoever remembers to run it. Both
runtime modes are covered there: the launch case starts its own Chromium, and
the attach case starts one outside the plugin, points runtime.cdpEndpoint at
it, drives a session through the network gates on that borrowed browser in both
directions — the destination refused and the one let through to its server — and
checks that the plugin's teardown left it running. The endpoint is dialled in
both forms the mode accepts — an http one, which asks that server where to
connect next, and the ws one a deployment writes when it must pin the address
itself. The run also
puts a second driver on that endpoint, the shape the Harness's own browser tool
makes of a shared Chromium: the cookies and storage of a page it opened in the
browser's own context stay out of this plugin's session and the session's stay out
of it, while a destination that session's policy refuses is served to it. The
suite looks for a browser the way the launch path looks for one — Playwright's own
build, then an installed Chrome, Chromium or Edge — so one variable is enough
wherever any of them exists:
DSH_QA_BROWSER_E2E=1 pnpm --filter @yadsh/dsh-qa-browser test:browser
On Windows PowerShell:
$env:DSH_QA_BROWSER_E2E = "1"
pnpm --filter @yadsh/dsh-qa-browser test:browser
DSH_QA_BROWSER_EXECUTABLE names the binary instead of leaving it to that
search — the switch to use when the machine has several, or none findable. A run
that was asked for and could not find a browser fails rather than skipping: a
named binary that is not there says so, and a search that came up empty says so
too.
MIT