DeepSeek Harness Web Agent 运行时上下文注入surfaceContext 设计、prompt 组装与源码实现解析【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文以仓库内 Agent Note 2026-07-28-web-agent-runtime-context.md 为核心骨架结合dsh-web-app组合包源码与 CLI 参考文档系统讲解 DeepSeek Harness 如何让 Web 端 Agent 明确感知自己正运行在 Web GUI 中包括app:web-surface与harness:source两个 prompt section 的注册机制、surfaceContext组合配置开关的语义与作用域、dsh web启动别名与 profile 组合栈的联动以及对应的单元测试与快照验证。读完本文你将理解 Web 会话系统提示词的前缀构成顺序掌握如何在无 headless 污染的前提下为浏览器内 Agent 提供稳定的产品定向信息并能定位相关源码与测试自行验证。问题背景Web Agent 不知道自己在哪共享的 CLI base 组合包将部署 personadeployment persona配置为空字符串而 Web overlay 并没有替换它同时 Web launcher 也没有向模型提示任何 source源码检出位置或交互界面interaction surface信息。session header 虽然为工具与持久化记录了工作目录但模型提示词中既不包含该目录也不包含 DeepSeek Harness Web GUI 的身份描述。由此产生一个典型的歧义场景用户对 Web Agent 说帮我改一下这个页面的主题change this pages themeAgent 会去用户选定的项目里寻找某个未指明的页面而用户真正想改的其实是正在运行该会话的 GUI 本身。根因不是模型能力不足而是模型输入缺少稳定的产品定向信息product orientation——它不知道this page指的是哪个页面也不知道自己运行在什么界面里。决策总览把表面事实交给 Web 表面自己修复的核心原则是**表面事实由拥有它的表面声明**the composing Web app owns this surface fact。具体决策如下Web profile 组合dsh-base与dsh-web-app两个 bundle。Web bundle 提供一段简洁的 coding-agent persona内含解析后的{{model}}与 session 的{{cwd}}。web-runtime插件在surfaceContext为true时注册app:web-surfaceprompt section。在挂载 profile 树之前dsh web别名读取同一个组合配置仅在 surface context 启用时安装已有的harness:sourcesection。headless bundle 以及拥有完整提示词complete prompt的 profile 将surfaceContext: false从而抑制 Web 提示词与受管 shell 事实managed shell factsWeb 别名也同时抑制 source section且不依赖 overlay 路径判断。所有已挂载的 prompt contribution 都会在 agent loop 发出 request header 之前激活。核心约束Web 提示词把未加限定的 this page、this GUI、this app 一律解释为 DeepSeek Harness Web GUI同时明确声明浏览器不提供隐式 DOM、路由或截图上下文让模型既能识别产品、又不会声称它并未收到的视觉状态。组装后的文本记录在request/header中维持模型可见内容即日志内容的不变式model-visible/logged invariant。关键实现两个 prompt section 与它们的注册顺序harness:source源码检出位置与工作目录的区分harness:sourcesection 由 packages/boot/app-boot/src/index.ts 中的addHarnessSourceSection(ctx, sourceRoot)注册。其完整文本为The DeepSeek Harness implementation checkout is atsourceRoot. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.该 section 的措辞与不得从一个路径推断另一个路径的警告由另一份决策笔记 source-checkout/workdir distinction 拥有避免此修复与后续 workdir 语义决策互相冲突。从源码看该 section 注册在systemPrompt服务的 fiber 上dev HMR 重载该插件后会被丢弃、直到下次 boot 重新注册若启动树中没有systemPrompt服务则直接返回undefinedno-op。app:web-surface浏览器界面定向段落app:web-surface的注册位于 packages/bundle/web-app/src/index.ts 的webSurfacePrompt(webUrl)函数其生成文本节选核心语义为You are interacting with the user through the DeepSeek Harness Web GUI atwebUrl. When the user refers to this page, this GUI, or this app without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. ... Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.DSH_BOOT. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL.其中 URL 通过localWebUrl(ctx)从webServer服务的端口解析为http://127.0.0.1:port。该段落还包含一段更新契约update contract只有同时运行pnpm run dev:web时客户端插件变更才能免刷新生效其余变更需要重建 Web 产物并验证现有 URL——这直接约束了模型在浏览器会话中承诺自动热更新的边界。段落排序FIRST_PARTY_SECTION_ORDER两个 section 的拼接顺序由 packages/core/system-prompt/src/index.ts 的FIRST_PARTY_SECTION_ORDER常量决定section 按order升序拼接同序按名字的 code-unit 顺序。与本主题相关的占位如下order常量section 语义-1000HARNESS_IDENTITYharness 身份开场-900HARNESS_SOURCE源码检出位置harness:source-800WEB_SURFACEWeb 界面定向app:web-surface0DEPLOYMENT_PERSONA部署 persona含 Web 的 coding-agent persona相邻取值至少相差 10使 first-party 分组保持稀疏、便于机械检测意外的顺序冲突外部插件可用任意 order。因此最终的 Web 系统提示词前缀顺序为harness identity → source checkout → Web orientation → coding-agent persona快照测试锁定的正是这个顺序。surfaceContext 开关配置、默认值与作用域surfaceContext是web-app插件的 schema 化配置项z.boolean().default(true)定义于 packages/bundle/web-app/src/index.ts。当它为true时插件在apply()中执行两件事注入systemPrompt服务注册harness:source通过addHarnessSourceSection(promptCtx, SOURCE_ROOT)与app:web-surface两个 section注入shellEnv服务注册 bash 变量DSH_WEB_URL描述为 Canonical local URL of the DeepSeek Harness Web GUI serving this session.值为当前会话的规范本地 URL。当surfaceContext为false时上述两段都不注册模型提示词与 shell 环境均不携带 Web 事实。Web 提示词与DSH_WEB_URL变量的注册位于 packages/bundle/web-app/src/index.ts值得注意一个拥有完整提示词的 agent preset persona 可以只抑制 prompt section而保留宿主拥有的 shell 变量。该配置的默认值在 Web bundle 的补丁层 packages/bundle/web-app/cordis.patch.yml 中显式写出web-runtime行config.surfaceContext: true与 schema 默认一致同时printUrl: true、openBrowser与trustedHosts来自ctx.webStartup的调用参数。headless bundle 以及持有完整提示词的 profile 则把该值置为false这样 headless/终端场景的 Agent 不会被错误告知你在浏览器里。dsh web 启动别名与 source section 的门控dsh web是--profile web的硬编码别名见 apps/cli/src/args.ts 与 apps/cli/reference/README.md。Web profile 的树由空根节点开始按顺序叠加dsh-base与dsh-web-app两个 bundle 的补丁层再叠加 profile 自身cordis.patch.yml、home 级$DSH_HOME/cordis.patch.yml与--patchoverlay。surfaceContext门控的要点在于同一事实、单一来源dsh web别名在挂载树之前读取组合后的surfaceContext值而不是维护一份独立的开关副本Web bundle 的补丁层与 launcher 读取到的是同一条组合配置行。默认开启、显式关闭普通 Web 请求默认获得 source Web orientation 段落headless 与完整 prompt 的 profile 显式置false后Web 别名也一并抑制 source section无需检查 overlay 路径避免 launcher 层重复推导表面事实。从 CLI 参考文档看dsh web后续 flag 属于 web 应用本身--host/--port覆盖组合行取值可重复的--trusted-host通过ctx.webRuntime.trustedHosts注入调用级 authority--no-open仅对本次调用禁用默认浏览器交接。dsh --profile web --dump-default-config可以打印 bundle 层的组合结果便于观察web-runtime行在叠加后的最终取值。验证方式单元测试与无密钥快照该修复的验证分三层对应 Agent Note 的 Verification 部分Web runtime 单元测试钉住surfaceContext开启与关闭两种行为确认 prompt section 与DSH_WEB_URL变量的注册/抑制符合预期见 packages/bundle/web-app/tests/web-app.spec.ts。Web alias 单元测试从组合行读取surfaceContext钉住默认开启与显式关闭两种 source-section 门控。无密钥 fresh-round-trip Web 场景启动随附的 base Web bundle通过 HTTP/SSE 应用跑真实会话将系统提示词前缀中的 source 与工作目录路径归一化后做快照。快照按 request 顺序锁定 harness 身份、源码检出、Web 定向与解析后的 coding-agent persona。Core Web 快照则应用 RL overlay钉住其完整系统提示词且不含 source 或 Web section。备选方案为何被否决该修复在决策阶段明确评估过四条替代路线Agent Note 的 Alternatives considered 一节理解这些取舍有助于把握设计的边界每个 prompt 附带 URL/DOM/截图当前根 URL 无法唯一标识所选组件且消息契约中没有视觉捕获引入动态页面状态需要单独设计日志化的模型输入超出本次修复范围。要求 session Workspace 必须是 harness 检出目录Workspace cwd 是用户的任务目标完全可能是空项目或另一个仓库将其与应用的源码位置混同会破坏这一边界还会让已安装或外部启动的会话语义变得含糊。把 Web 措辞放进全局 harness 身份dsh-system-prompt同时服务于 TUI、ACP、SDK 与自定义部署这些都不在浏览器中运行表面事实应由组合它的 Web 应用声明。为所有 CLI 表面修改现有 source-location sectionharness:source与 TUI 共享只陈述检出事实保持 Web 定向独立可复用该契约同时避免告诉 headless/终端 Agent你在浏览器里。影响与后果普通 Web 请求新增一段简短稳定的提示词前缀部署该变更时供应商前缀缓存provider prefix caches可能失效一次。Agent 现在能够区分GUI 源码检出与用户选定的 Workspace对当前应用这类未限定引用可直接消解省去一次澄清往返clarification round trip。对具体视觉状态的引用仍受无 DOM / 无路由 / 无截图显式声明的约束必要时仍需用户提供路径、描述或附件。拥有完整提示词的 profile 可通过 Web runtime 的组合设置直接退出无需 launcher 层做路径检查。延伸阅读路径决策笔记本体.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md含中文版 .zh.mdWeb bundle 运行时实现packages/bundle/web-app/src/index.tsWeb bundle 补丁层web-runtime行配置packages/bundle/web-app/cordis.patch.ymlPrompt section 排序常量packages/core/system-prompt/src/index.tssource section 注册实现packages/boot/app-boot/src/index.tsCLI 启动别名与 profile 组合说明apps/cli/src/args.ts 与 apps/cli/reference/README.mdworkdir 语义配套决策.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考