dsh-plugin-dev-kb 1.0.9 → 1.1.0

package/kb/meta/site-pages.txt

@@ -1,182 +1,184 @@
-develop\basic\config.md
-develop\basic\index.md
-develop\basic\publish.md
-develop\basic\tool.md
-develop\cordis-tutorial\01-first-plugin.md
-develop\cordis-tutorial\02-lifecycle-and-effects.md
-develop\cordis-tutorial\03-services.md
-develop\cordis-tutorial\04-events.md
-develop\cordis-tutorial\05-config.md
-develop\cordis-tutorial\06-composition-and-hmr.md
-develop\cordis-tutorial\07-into-the-harness.md
-develop\cordis-tutorial\index.md
-develop\framework\events.md
-develop\framework\index.md
-develop\framework\service.md
-develop\practice\dynamic-cordis.md
-develop\practice\index.md
-develop\practice\llm-adapter.md
-en\develop\basic\config.md
-en\develop\basic\index.md
-en\develop\basic\publish.md
-en\develop\basic\tool.md
-en\develop\cordis-tutorial\01-first-plugin.md
-en\develop\cordis-tutorial\02-lifecycle-and-effects.md
-en\develop\cordis-tutorial\03-services.md
-en\develop\cordis-tutorial\04-events.md
-en\develop\cordis-tutorial\05-config.md
-en\develop\cordis-tutorial\06-composition-and-hmr.md
-en\develop\cordis-tutorial\07-into-the-harness.md
-en\develop\cordis-tutorial\index.md
-en\develop\framework\events.md
-en\develop\framework\index.md
-en\develop\framework\service.md
-en\develop\practice\dynamic-cordis.md
-en\develop\practice\index.md
-en\develop\practice\llm-adapter.md
-en\guide\github-review.md
-en\guide\mcp-memory.md
-en\guide\providers.md
-en\guide\python-sdk.md
-en\guide\quickstart.md
-en\guide\schedule.md
-en\index.md
-en\reference\agent-lifecycle.md
-en\reference\api-gateway.md
-en\reference\capability-seams.md
-en\reference\config-catalog.md
-en\reference\cookbook\adding-a-package.md
-en\reference\cookbook\adding-a-settings-card.md
-en\reference\cookbook\adding-a-tool.md
-en\reference\cookbook\adding-an-llm-adapter.md
-en\reference\cookbook\extension-cookbook.md
-en\reference\cordis-api\context.md
-en\reference\cordis-api\events.md
-en\reference\cordis-api\fiber.md
-en\reference\cordis-api\inherited.md
-en\reference\cordis-api\registry.md
-en\reference\cordis-api\service.md
-en\reference\cordis-primer.md
-en\reference\index.md
-en\reference\persistence-catalog.md
-en\reference\subsystems\approval.md
-en\reference\subsystems\client-modules.md
-en\reference\subsystems\code-runtime.md
-en\reference\subsystems\commands.md
-en\reference\subsystems\compaction.md
-en\reference\subsystems\conversation.md
-en\reference\subsystems\core.md
-en\reference\subsystems\credentials.md
-en\reference\subsystems\filesystem.md
-en\reference\subsystems\goal.md
-en\reference\subsystems\index.md
-en\reference\subsystems\invariants.md
-en\reference\subsystems\jobs.md
-en\reference\subsystems\llm-streaming.md
-en\reference\subsystems\lsp.md
-en\reference\subsystems\permission-presets.md
-en\reference\subsystems\persistence.md
-en\reference\subsystems\plan.md
-en\reference\subsystems\sandbox.md
-en\reference\subsystems\schedule.md
-en\reference\subsystems\scope.md
-en\reference\subsystems\session-projection.md
-en\reference\subsystems\session-query.md
-en\reference\subsystems\session-reference.md
-en\reference\subsystems\session-telemetry.md
-en\reference\subsystems\session-title.md
-en\reference\subsystems\session.md
-en\reference\subsystems\settings.md
-en\reference\subsystems\shell.md
-en\reference\subsystems\skills.md
-en\reference\subsystems\slots.md
-en\reference\subsystems\spill.md
-en\reference\subsystems\storage.md
-en\reference\subsystems\subagent.md
-en\reference\subsystems\subprocess.md
-en\reference\subsystems\system-prompt.md
-en\reference\subsystems\terminal.md
-en\reference\subsystems\token-meter.md
-en\reference\subsystems\tools.md
-en\reference\subsystems\typert.md
-en\reference\subsystems\user-questions.md
-en\reference\subsystems\web-client.md
-en\reference\subsystems\web-server.md
-en\reference\subsystems\web.md
-en\reference\subsystems\workflow.md
-en\reference\subsystems\workspace.md
-en\reference\tool-catalog.md
-en\reference\tool-execution-pipeline.md
-guide\github-review.md
-guide\mcp-memory.md
-guide\providers.md
-guide\python-sdk.md
-guide\quickstart.md
-guide\schedule.md
-index.md
-reference\agent-lifecycle.md
-reference\api-gateway.md
-reference\capability-seams.md
-reference\config-catalog.md
-reference\cookbook\adding-a-package.md
-reference\cookbook\adding-a-settings-card.md
-reference\cookbook\adding-a-tool.md
-reference\cookbook\adding-an-llm-adapter.md
-reference\cookbook\extension-cookbook.md
-reference\cordis-api\context.md
-reference\cordis-api\events.md
-reference\cordis-api\fiber.md
-reference\cordis-api\inherited.md
-reference\cordis-api\registry.md
-reference\cordis-api\service.md
-reference\cordis-primer.md
-reference\index.md
-reference\persistence-catalog.md
-reference\subsystems\approval.md
-reference\subsystems\client-modules.md
-reference\subsystems\code-runtime.md
-reference\subsystems\commands.md
-reference\subsystems\compaction.md
-reference\subsystems\conversation.md
-reference\subsystems\core.md
-reference\subsystems\credentials.md
-reference\subsystems\filesystem.md
-reference\subsystems\goal.md
-reference\subsystems\index.md
-reference\subsystems\invariants.md
-reference\subsystems\jobs.md
-reference\subsystems\llm-streaming.md
-reference\subsystems\lsp.md
-reference\subsystems\permission-presets.md
-reference\subsystems\persistence.md
-reference\subsystems\plan.md
-reference\subsystems\sandbox.md
-reference\subsystems\schedule.md
-reference\subsystems\scope.md
-reference\subsystems\session-projection.md
-reference\subsystems\session-query.md
-reference\subsystems\session-reference.md
-reference\subsystems\session-telemetry.md
-reference\subsystems\session-title.md
-reference\subsystems\session.md
-reference\subsystems\settings.md
-reference\subsystems\shell.md
-reference\subsystems\skills.md
-reference\subsystems\slots.md
-reference\subsystems\spill.md
-reference\subsystems\storage.md
-reference\subsystems\subagent.md
-reference\subsystems\subprocess.md
-reference\subsystems\system-prompt.md
-reference\subsystems\terminal.md
-reference\subsystems\token-meter.md
-reference\subsystems\tools.md
-reference\subsystems\typert.md
-reference\subsystems\user-questions.md
-reference\subsystems\web-client.md
-reference\subsystems\web-server.md
-reference\subsystems\web.md
-reference\subsystems\workflow.md
-reference\subsystems\workspace.md
-reference\tool-catalog.md
-reference\tool-execution-pipeline.md
+develop\basic\config.md
+develop\basic\index.md
+develop\basic\publish.md
+develop\basic\tool.md
+develop\cordis-tutorial\01-first-plugin.md
+develop\cordis-tutorial\02-lifecycle-and-effects.md
+develop\cordis-tutorial\03-services.md
+develop\cordis-tutorial\04-events.md
+develop\cordis-tutorial\05-config.md
+develop\cordis-tutorial\06-composition-and-hmr.md
+develop\cordis-tutorial\07-into-the-harness.md
+develop\cordis-tutorial\index.md
+develop\framework\events.md
+develop\framework\index.md
+develop\framework\service.md
+develop\practice\dynamic-cordis.md
+develop\practice\index.md
+develop\practice\llm-adapter.md
+en\develop\basic\config.md
+en\develop\basic\index.md
+en\develop\basic\publish.md
+en\develop\basic\tool.md
+en\develop\cordis-tutorial\01-first-plugin.md
+en\develop\cordis-tutorial\02-lifecycle-and-effects.md
+en\develop\cordis-tutorial\03-services.md
+en\develop\cordis-tutorial\04-events.md
+en\develop\cordis-tutorial\05-config.md
+en\develop\cordis-tutorial\06-composition-and-hmr.md
+en\develop\cordis-tutorial\07-into-the-harness.md
+en\develop\cordis-tutorial\index.md
+en\develop\framework\events.md
+en\develop\framework\index.md
+en\develop\framework\service.md
+en\develop\practice\dynamic-cordis.md
+en\develop\practice\index.md
+en\develop\practice\llm-adapter.md
+en\guide\github-review.md
+en\guide\mcp-memory.md
+en\guide\network-proxy.md
+en\guide\providers.md
+en\guide\python-sdk.md
+en\guide\quickstart.md
+en\guide\schedule.md
+en\index.md
+en\reference\agent-lifecycle.md
+en\reference\api-gateway.md
+en\reference\capability-seams.md
+en\reference\config-catalog.md
+en\reference\cookbook\adding-an-llm-adapter.md
+en\reference\cookbook\adding-a-package.md
+en\reference\cookbook\adding-a-settings-card.md
+en\reference\cookbook\adding-a-tool.md
+en\reference\cookbook\extension-cookbook.md
+en\reference\cordis-api\context.md
+en\reference\cordis-api\events.md
+en\reference\cordis-api\fiber.md
+en\reference\cordis-api\inherited.md
+en\reference\cordis-api\registry.md
+en\reference\cordis-api\service.md
+en\reference\cordis-primer.md
+en\reference\index.md
+en\reference\persistence-catalog.md
+en\reference\subsystems\approval.md
+en\reference\subsystems\client-modules.md
+en\reference\subsystems\code-runtime.md
+en\reference\subsystems\commands.md
+en\reference\subsystems\compaction.md
+en\reference\subsystems\conversation.md
+en\reference\subsystems\core.md
+en\reference\subsystems\credentials.md
+en\reference\subsystems\filesystem.md
+en\reference\subsystems\goal.md
+en\reference\subsystems\index.md
+en\reference\subsystems\invariants.md
+en\reference\subsystems\jobs.md
+en\reference\subsystems\llm-streaming.md
+en\reference\subsystems\lsp.md
+en\reference\subsystems\permission-presets.md
+en\reference\subsystems\persistence.md
+en\reference\subsystems\plan.md
+en\reference\subsystems\sandbox.md
+en\reference\subsystems\schedule.md
+en\reference\subsystems\scope.md
+en\reference\subsystems\session.md
+en\reference\subsystems\session-projection.md
+en\reference\subsystems\session-query.md
+en\reference\subsystems\session-reference.md
+en\reference\subsystems\session-telemetry.md
+en\reference\subsystems\session-title.md
+en\reference\subsystems\settings.md
+en\reference\subsystems\shell.md
+en\reference\subsystems\skills.md
+en\reference\subsystems\slots.md
+en\reference\subsystems\spill.md
+en\reference\subsystems\storage.md
+en\reference\subsystems\subagent.md
+en\reference\subsystems\subprocess.md
+en\reference\subsystems\system-prompt.md
+en\reference\subsystems\terminal.md
+en\reference\subsystems\token-meter.md
+en\reference\subsystems\tools.md
+en\reference\subsystems\typert.md
+en\reference\subsystems\user-questions.md
+en\reference\subsystems\web.md
+en\reference\subsystems\web-client.md
+en\reference\subsystems\web-server.md
+en\reference\subsystems\workflow.md
+en\reference\subsystems\workspace.md
+en\reference\tool-catalog.md
+en\reference\tool-execution-pipeline.md
+guide\github-review.md
+guide\mcp-memory.md
+guide\network-proxy.md
+guide\providers.md
+guide\python-sdk.md
+guide\quickstart.md
+guide\schedule.md
+index.md
+reference\agent-lifecycle.md
+reference\api-gateway.md
+reference\capability-seams.md
+reference\config-catalog.md
+reference\cookbook\adding-an-llm-adapter.md
+reference\cookbook\adding-a-package.md
+reference\cookbook\adding-a-settings-card.md
+reference\cookbook\adding-a-tool.md
+reference\cookbook\extension-cookbook.md
+reference\cordis-api\context.md
+reference\cordis-api\events.md
+reference\cordis-api\fiber.md
+reference\cordis-api\inherited.md
+reference\cordis-api\registry.md
+reference\cordis-api\service.md
+reference\cordis-primer.md
+reference\index.md
+reference\persistence-catalog.md
+reference\subsystems\approval.md
+reference\subsystems\client-modules.md
+reference\subsystems\code-runtime.md
+reference\subsystems\commands.md
+reference\subsystems\compaction.md
+reference\subsystems\conversation.md
+reference\subsystems\core.md
+reference\subsystems\credentials.md
+reference\subsystems\filesystem.md
+reference\subsystems\goal.md
+reference\subsystems\index.md
+reference\subsystems\invariants.md
+reference\subsystems\jobs.md
+reference\subsystems\llm-streaming.md
+reference\subsystems\lsp.md
+reference\subsystems\permission-presets.md
+reference\subsystems\persistence.md
+reference\subsystems\plan.md
+reference\subsystems\sandbox.md
+reference\subsystems\schedule.md
+reference\subsystems\scope.md
+reference\subsystems\session.md
+reference\subsystems\session-projection.md
+reference\subsystems\session-query.md
+reference\subsystems\session-reference.md
+reference\subsystems\session-telemetry.md
+reference\subsystems\session-title.md
+reference\subsystems\settings.md
+reference\subsystems\shell.md
+reference\subsystems\skills.md
+reference\subsystems\slots.md
+reference\subsystems\spill.md
+reference\subsystems\storage.md
+reference\subsystems\subagent.md
+reference\subsystems\subprocess.md
+reference\subsystems\system-prompt.md
+reference\subsystems\terminal.md
+reference\subsystems\token-meter.md
+reference\subsystems\tools.md
+reference\subsystems\typert.md
+reference\subsystems\user-questions.md
+reference\subsystems\web.md
+reference\subsystems\web-client.md
+reference\subsystems\web-server.md
+reference\subsystems\workflow.md
+reference\subsystems\workspace.md
+reference\tool-catalog.md
+reference\tool-execution-pipeline.md

package/kb/meta/source.json

@@ -3,11 +3,11 @@
   "source": "官方文档站点 https://deepseek-harness.github.io/deepseek-harness/ （VitePress）",
   "repository": "https://github.com/deepseek-ai/deepseek-harness",
   "branch": "master",
-  "commit": "cd5ef8148158c3a752a658978873241fdf8e2bbc",
-  "fetchedAt": "2026-08-30T10:00:08.912Z",
+  "commit": "d347e703908d0406b7a7ef80e3a0e594d86b2215",
+  "fetchedAt": "2026-09-05T10:10:32.663Z",
   "siteBase": "https://deepseek-harness.github.io/deepseek-harness",
-  "publishedMarkdownPages": 182,
-  "siteFiles": 186,
+  "publishedMarkdownPages": 184,
+  "siteFiles": 188,
   "images": 4,
-  "extraFiles": 56
+  "extraFiles": 58
 }

package/kb/meta/topics.md

@@ -59,7 +59,7 @@
 
 ## 12b. API Gateway 与服务接入
 - 核心：`site/reference/api-gateway.md`（Typert API Gateway：Remote 方法声明、Host/Client 约定、RPC 与 `/api` 路由复用）
-- 扩展：`extra/subsystems/webhook.md`（webhook 接入，仓库文档）、`site/reference/subsystems/typert.md`
+- 扩展：`extra/cookbook/adding-a-remote-api.md`（新增 Remote API 五步操作，中英各一）、`extra/subsystems/webhook.md`（webhook 接入，仓库文档）、`site/reference/subsystems/typert.md`
 
 ## 13. 系统提示词 / Token / 上下文压缩
 - `site/reference/subsystems/system-prompt.md`、`token-meter.md`、`compaction.md`
@@ -73,11 +73,11 @@
 ## 16. 中英对照
 - 英文站：`site/en/`（结构与中文站一致：`guide/`、`develop/`、`reference/`）；`INDEX.md` 有全部 URL ↔ 文件对照
 
-## 17. 使用指南进阶（GitHub Review / 定时任务 / MCP 记忆）
-- `site/guide/github-review.md`（用 dsh 做 GitHub 代码评审）、`site/guide/schedule.md`（定时任务）、`site/guide/mcp-memory.md`（MCP 与长期记忆）
+## 17. 使用指南进阶（GitHub Review / 定时任务 / MCP 记忆 / 网络代理）
+- `site/guide/github-review.md`（用 dsh 做 GitHub 代码评审）、`site/guide/schedule.md`（定时任务）、`site/guide/mcp-memory.md`（MCP 与长期记忆）、`site/guide/network-proxy.md`（代理后运行：HTTPS_PROXY 等环境变量、哪些路径保持直连）
 - 扩展：`site/reference/subsystems/schedule.md`、`extra/subsystems/todo.md`（仓库文档）
 
 ## 检索技巧
-- 全量索引：`meta/search-index.json`（241 个文件的 path/url/title/字符数）
+- 全量索引：`meta/search-index.json`（245 个文件的 path/url/title/字符数）
 - 大文件（config-catalog / tool-catalog / module-graph / subsystems/session 等 ≥100KB）先用 grep 定位关键行，再 read 局部，不要整读
 - 常用检索关键词：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`

package/kb/site/develop/cordis-tutorial/07-into-the-harness.md

@@ -12,8 +12,9 @@ editSource: "docs/cordis-tutorial/07-into-the-harness.zh.md"
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
+import { brandString } from '@deepseek-ai/dsh-brand'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { ToolCallId } from '@deepseek-ai/dsh-llm'
 
 export const name = 'greet-tool'
 export const inject = ['tools']
@@ -38,7 +39,7 @@ export function apply(ctx: Context) {
   // the model. ToolCallId brands the correlation id a provider would issue.
   void (async () => {
     const result = await ctx.tools.execute({
-      callId: ToolCallId('demo-1'),
+      callId: brandString<ToolCallId>('demo-1'),
       name: 'greet',
       arguments: { name: 'Cordis' },
       signal: new AbortController().signal,

package/kb/site/develop/practice/llm-adapter.md

@@ -56,7 +56,8 @@ export function apply(ctx: Context, config: Config) {
 `stream()` 必须按以下协议生成分片：
 
 ```ts
-import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
 
 async function* exampleChunks(): AsyncIterable<StreamChunk> {
   // 1. Start each content block with block-start.
@@ -78,7 +79,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
   yield {
     type: 'tool-call-delta',
     index: 1,
-    id: ToolCallId('call-123'),
+    id: brandString<ToolCallId>('call-123'),
     name: 'bash',
     argumentsDelta: '{"command":"ls"}',
   }
@@ -87,7 +88,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
     index: 1,
     block: {
       type: 'tool-call',
-      id: ToolCallId('call-123'),
+      id: brandString<ToolCallId>('call-123'),
       name: 'bash',
       arguments: '{"command":"ls"}',
     },

package/kb/site/en/develop/cordis-tutorial/07-into-the-harness.md

@@ -12,8 +12,9 @@ Create `greet-tool.ts` in `tmp/cordis-tutorial`:
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
+import { brandString } from '@deepseek-ai/dsh-brand'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { ToolCallId } from '@deepseek-ai/dsh-llm'
 
 export const name = 'greet-tool'
 export const inject = ['tools']
@@ -38,7 +39,7 @@ export function apply(ctx: Context) {
   // the model. ToolCallId brands the correlation id a provider would issue.
   void (async () => {
     const result = await ctx.tools.execute({
-      callId: ToolCallId('demo-1'),
+      callId: brandString<ToolCallId>('demo-1'),
       name: 'greet',
       arguments: { name: 'Cordis' },
       signal: new AbortController().signal,

package/kb/site/en/develop/practice/llm-adapter.md

@@ -56,7 +56,8 @@ export function apply(ctx: Context, config: Config) {
 `stream()` yields chunks using this protocol:
 
 ```ts
-import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
 
 async function* exampleChunks(): AsyncIterable<StreamChunk> {
   // 1. Start each content block with block-start.
@@ -78,7 +79,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
   yield {
     type: 'tool-call-delta',
     index: 1,
-    id: ToolCallId('call-123'),
+    id: brandString<ToolCallId>('call-123'),
     name: 'bash',
     argumentsDelta: '{"command":"ls"}',
   }
@@ -87,7 +88,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
     index: 1,
     block: {
       type: 'tool-call',
-      id: ToolCallId('call-123'),
+      id: brandString<ToolCallId>('call-123'),
       name: 'bash',
       arguments: '{"command":"ls"}',
     },

package/kb/site/en/guide/network-proxy.md

@@ -0,0 +1,87 @@
+---
+editSource: "docs/user/guide/network-proxy.md"
+---
+
+# Run DSH behind a network proxy
+
+DSH routes its outbound requests — model calls, web search, page fetches, and MCP servers over HTTP — through the proxy named by the standard proxy environment variables. It reads them at launch; nothing else needs configuring. A few paths stay direct by design or by runtime limit, listed under "What stays direct" below.
+
+## Export the variables
+
+```sh
+export HTTPS_PROXY=http://127.0.0.1:7890
+export HTTP_PROXY=http://127.0.0.1:7890
+```
+
+Put both lines in your shell profile so every `dsh` invocation inherits them, or in `$DSH_HOME/.env` (`~/.dsh/.env` by default) next to your API key; an exported variable always wins over that file. A project's own `.env` cannot set them: it arrives with `git clone`, and DSH refuses to start rather than let a repository decide where your traffic goes.
+
+A proxy that needs credentials takes them in the URL: `http://user:password@proxy.example:8080`. DSH never prints the URL back: a diagnostic names the variable it rejected, so neither the username nor the password appears anywhere.
+
+## Why your browser is proxied but your terminal is not
+
+This is the most common surprise, and it is not specific to DSH. There is no single "system proxy" that all software obeys — there are three unrelated mechanisms:
+
+| Mechanism | Who follows it |
+|---|---|
+| The operating system's proxy settings | Safari, most native macOS apps, Chrome and Edge |
+| The `HTTP_PROXY` / `HTTPS_PROXY` environment variables | `curl`, `git`, `npm`, `pip`, and DSH |
+| TUN mode (a virtual network interface) | Everything, transparently |
+
+The "system proxy" switch in a proxy application such as Clash writes only the first one. Browsers pick it up; command-line tools never see it. That is why exporting the variables is a separate step, and why turning on TUN mode makes both work without any variables at all.
+
+DSH does not read the operating system's proxy settings. Export the variables, or use TUN mode.
+
+## Choose what stays direct
+
+`NO_PROXY` lists hosts to reach directly:
+
+```sh
+export NO_PROXY=internal.example.com,.corp.example.com,registry.local
+```
+
+An entry names a host and matches it together with every subdomain under it: `NO_PROXY=example.com` also sends `api.example.com` direct. A leading `.` or `*.` is accepted and means the same thing. An entry may carry a `:port`, and `*` bypasses everything.
+
+**CIDR ranges do not work.** An operating system bypass list often contains entries like `10.0.0.0/8` or `192.168.0.0/16`; copying those into `NO_PROXY` has no effect. Use host names or domain suffixes instead.
+
+You do not need to list `localhost` or `127.0.0.1`. DSH always bypasses loopback, because its own Web UI and local servers would otherwise route through the proxy and loop.
+
+## Limits worth knowing
+
+**SOCKS proxies are not supported.** A `socks5://` value is reported at startup and skipped, and DSH connects directly for the scheme that named it — setting `HTTPS_PROXY=socks5://…` alongside a usable `HTTP_PROXY` leaves `https:` direct rather than borrowing the HTTP proxy. Point the variables at your proxy application's HTTP port instead — most expose both, and the HTTP one is usually a neighbouring port number.
+
+**`ALL_PROXY` alone is enough.** DSH falls back to it for both schemes, even though Node and curl differ on this. Setting `HTTPS_PROXY` explicitly is still clearer.
+
+**A TLS-intercepting corporate proxy needs its certificate.** If requests fail with a certificate error once the proxy is reachable, point Node at your organisation's CA bundle before launching:
+
+```sh
+export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
+```
+
+Node reads that variable only at process start, so export it before running `dsh`.
+
+**Tools DSH runs for you follow the same proxy.** Commands in the bash tool, `git`, `gh`, and MCP servers started as child processes all inherit these variables. A child that is itself a Node program honors them only on Node 22.21 or later; an older Node connects directly. If one of your proxy variables holds a value DSH rejected — a SOCKS URL, say — Node-based tools also connect directly rather than fail to start, while `curl` and `git` still read that value.
+
+**A password in the proxy URL reaches those tools too.** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` is a normal environment variable, so every command DSH runs — including the ones the model writes — can read it, and a command that prints its environment puts the password in output that is kept. This is how the variable already behaves for everything else in your shell. If that matters, give the proxy a credential-free entry point, or authenticate it some other way than in the URL.
+
+## What stays direct
+
+Not every request DSH makes goes through the proxy:
+
+- **Anything on this machine.** Loopback is always direct: `localhost`, the whole `127.0.0.0/8` range, `::1`, and `0.0.0.0`. A proxy cannot usefully reach a service that only listens locally.
+- **Code the model writes.** The workflow and code-runtime workers never receive the proxy settings, so a script the model authors cannot read a proxy URL that may carry a password. Such a script reaches the network only if it configures that itself.
+- **Usage telemetry.** The OTLP exporter uses Node's own HTTP client rather than the one a proxy configures, so telemetry connects directly and simply fails where direct egress is blocked. Nothing you do in DSH depends on it. Set `DSH_TELEMETRY_MODE=DISABLED` to turn it off entirely.
+- **`web_fetch` to a literal private address.** A URL naming an address like `http://10.0.0.5/` is refused rather than handed to the proxy, the same refusal it gets with no proxy configured.
+
+## Check that it worked
+
+Ask the agent to fetch a page and watch your proxy application's connection log:
+
+```sh
+dsh --profile headless "fetch https://example.com and tell me the page title"
+```
+
+If the request does not appear there, confirm the variables survive into DSH's own environment:
+
+```sh
+env | grep -i proxy
+```