dsh-acp-enhanced 0.2.1 → 0.3.1

package/README-zh.md

@@ -0,0 +1,210 @@
+**[English](README.md) | 中文**
+
+# dsh-acp-enhanced
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的增强版
+[Agent Client Protocol](https://agentclientprotocol.com)（ACP）服务器，为 **Zed** 等 ACP
+编辑器设计。它是官方 `@deepseek-ai/dsh-acp` 桥接器的即插即用替代品：官方桥只做纯文本
+输出，本桥把 Web GUI 的能力（流式、遥测、模型/权限控制、会话管理、MCP）全部暴露到
+ACP 线上。
+
+## 特性
+
+### 输出与遥测
+
+- **块级流式 + 推理流式**：文本块与思考过程实时到达（`agent_message_chunk` /
+  `agent_thought_chunk`），取消/重试不留半截输出
+- **完整遥测**：上下文用量环 + 缓存命中率 / TPS / 输入-输出-推理 token / 工具耗时 /
+  轮次计数（`usage_update._meta` 携带全量明细）
+
+### 模型与权限
+
+- **模型切换**：实时 `provider/model` 目录下拉（按 ACP 规范分组线格式）
+- **推理强度**：`reasoning_effort` 下拉——仅当当前路由暴露可选 efforts 时出现
+- **权限预设**：read-only / workspace-write / full-access 三种会话模式
+- **审批**：工具调用弹出原生 allow-once / reject-once 审批
+
+### Zed 深度集成
+
+- **工具卡片**：展开可见每次调用的完整参数与结果预览（`rawInput` / `rawOutput`），
+  按工具类型渲染图标
+- **Zed 文件与终端**：`zed_read_text_file` / `zed_write_text_file` / `zed_terminal` 把
+  文件编辑放进 Zed 的"编辑文件"区（diff + 接受/拒绝）、命令跑在 Zed 真实终端
+- **原生表单提问**：`ask_user_question` → `elicitation/create` 表单，选项即点即答
+- **Plan 面板**：plan mode 开关 → Zed 底部"规划中"状态条
+
+### 会话
+
+- **恢复与归档**：`session/load` 恢复历史线程（完整回放）；`session/list` /
+  `session/delete` 管理线程归档（带标题、按更新时间排序）；标题实时推送
+
+### 命令
+
+- **Slash 命令**：输入 `/` 即可见命令列表（`available_commands_update`）：`/status`
+  查看路由与遥测、`/model` 列出或切换模型（列表以等宽代码块排版，一眼全见），其余
+  （`/compact` `/goal` `/permission` `/plan`…）直通 harness 命令注册表，全部**不经过
+  模型 turn** 即时执行；未解析的 slash 放行给模型（`/skill-name` 技能手势）
+
+### MCP
+
+- **MCP servers**：`session/new` 的 `mcpServers` 挂载任意 MCP server（stdio +
+  streamable HTTP），工具以 `mcp__<server>__<tool>` 注入；失败的 server 不会拖垮会话
+
+## 效果预览
+
+在 Zed 的 AI Agent 面板中选择 **dsh-acp-enhanced** 后：
+
+<img src="assets/screenshots/approval-config-context.png" width="560">
+
+<img src="assets/screenshots/tool-cards-elicitation.png" width="560">
+
+## 快速开始
+
+本包遵循 dsh 官方插件规范（声明了 `dsh.bundle`），安装与官方组合包一致：**一条命令**
+完成，自动初始化 profile、安装包、追加 bundle 层，全程无需手写 profile YAML。
+
+### 安装（2 步）
+
+**第 1 步：安装**（从 npm registry，无需下载源码）
+
+```sh
+dsh plugin --profile acp-enhanced add dsh-acp-enhanced
+```
+
+> 开发/改源码时用 `link:` 指向本地 checkout（改动实时生效）：
+> `dsh plugin --profile acp-enhanced add "link:/absolute/path/to/dsh-acp-enhanced"`
+
+**第 2 步：注册进 Zed**（在 `~/.config/zed/settings.json` 的 `agent_servers` 里注册；
+Zed 会用极简 PATH 拉起 agent，因此用随附启动器 `scripts/dsh-acp-zed.sh` 定位
+`node`/`dsh`）
+
+> **启动器随包发布**，绝对路径取决于第 1 步的安装方式：
+> - **npm 安装（默认）**：`$HOME/.dsh/profiles/acp-enhanced/node_modules/dsh-acp-enhanced/scripts/dsh-acp-zed.sh`。Zed 不会展开 `~` 或环境变量，请把 `$HOME` 换成你的用户目录（如 `/Users/you`）后写全绝对路径。
+> - **`link:` 开发安装**：`<你的 checkout 路径>/scripts/dsh-acp-zed.sh`。
+
+#### 最常见：DeepSeek 官方 API（默认路由）
+
+```jsonc
+{
+  // ...你已有的设置...
+  "agent_servers": {
+    "dsh-acp-enhanced": {
+      "type": "custom",
+      "command": "/bin/bash",
+      "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
+      "env": {
+        "DSH_ACP_PROVIDER": "deepseek-official",  // 官方 provider id
+        "DSH_ACP_MODEL": "deepseek-v4-flash"      // 官方模型 id
+      }
+    }
+  }
+}
+```
+
+> 这两项 env 与包自带 patch 的缺省值一致，**省略也能工作**——显式写上只是让路由意图
+> 一目了然。API key 不必写进 Zed：存入 `~/.dsh/.credentials.yaml`
+> （`DEEPSEEK_API_KEY`）由 dsh 凭据服务解析即可；启动脚本还会兜底继承正在运行的
+> `dsh web` 进程的 key。
+
+可选：固定面板默认项（都可随时在面板里改）：
+
+```jsonc
+"dsh-acp-enhanced": {
+  // ...上面的 type/command/args/env...
+  "default_config_options": {
+    "model": "deepseek-official/deepseek-v4-flash",
+    "plan_mode": false,
+    "reasoning_effort": "high"
+  },
+  "favorite_config_option_values": {
+    "model": ["deepseek-official/deepseek-v4-flash", "deepseek-official/deepseek-v4-pro"]
+  }
+}
+```
+
+#### 扩展：走 OpenAI-Responses 网关（如公司内部模型网关）
+
+同一安装路径，只是 env 换成网关暴露的 provider/model 与它要求的 key 环境变量名：
+
+```jsonc
+"dsh-acp-enhanced": {
+  "type": "custom",
+  "command": "/bin/bash",
+  "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
+  "env": {
+    "DSH_ACP_PROVIDER": "<gateway-provider-id>",  // 网关暴露的 provider id
+    "DSH_ACP_MODEL": "<gateway-model-id>",         // 网关暴露的 model id
+    "<KEY_ENV_NAME>": "<key>"                      // 网关声明读取的 key 环境变量名
+  }
+}
+```
+
+> `<KEY_ENV_NAME>` 也可以省掉，把 key 存进 `~/.dsh/.credentials.yaml` 统一管理。
+
+Zed 会热重载设置。打开 **AI Agent 面板**（`Cmd+Shift+A`）→ agent 选择器选
+**dsh-acp-enhanced** → 输入第一条消息即可：回复实时流式返回，状态栏显示上下文用量，
+面板顶部有 Model / Permission preset / Plan mode 配置项与三种模式，线程归档可恢复
+历史会话。
+
+本地验证（无需 Zed）：
+
+```sh
+node scripts/acp-client.mjs                    # 官方默认路由，无需 env；期望 ALL CHECKS PASSED
+DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # 自定义路由时再传
+```
+
+### 可选：web_search 走同一个网关
+
+若网关实现 OpenAI Responses 的 `web_search` 服务端工具，可把搜索也路由到网关（复用
+同一凭据）。装子包并给 profile 的 `cordis.patch.yml` 追加两段：
+
+```sh
+dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
+```
+
+```yaml
+- id: web
+  config:
+    searchProvider: openai-responses   # 子包注册在 ctx.web 上的搜索 provider id（固定值）
+
+- insert:
+    - id: web-search-openrouter
+      name: 'dsh-web-search-openrouter'
+      config:
+        enabled: true
+        baseURL: http://<gateway-host>:<port>/v1
+        model: <your-model-id>
+        apiKeyEnv: <KEY_ENV_NAME>
+```
+
+> ⚠️ `searchProvider` 必须**精确等于** `openai-responses`——这是
+> `dsh-web-search-openrouter` 注册在 `ctx.web` 上的搜索 provider id，**不是**网关的
+> LLM provider id（即上面 `DSH_ACP_PROVIDER` 填的那个）。web 插件按 id 精确匹配，
+> 填错时配置期不会报错，直到首次搜索才抛 `WEB_PROVIDER_CONFIGURED_MISSING`。
+
+## 故障排查
+
+| 症状 | 处理 |
+|---|---|
+| `exec: dsh: not found`（status 127） | 用随附 `dsh-acp-zed.sh` 启动器（自定位 node/dsh） |
+| `no API key for provider route "xxx"` | 写入 `~/.dsh/.credentials.yaml`，或在 agent_servers 里设 `env.DEEPSEEK_API_KEY` |
+| 无法切换模型 / 上下文用量不显示 | 选到了不可路由的"幽灵 provider"；本桥默认过滤（只广播 `config.provider` 的模型），确认 profile 的 provider 指向真实路由 |
+| 需要详细诊断 | `ACP_DEBUG=1 dsh --profile acp-enhanced`（stderr 生命周期 trace） |
+
+## 开发
+
+```sh
+node scripts/acp-client.mjs           # 端到端冒烟（需要 API key）
+node scripts/acp-client-tools.mjs     # 客户端工具测试（模拟 Zed 的 fs/terminal/elicitation/plan）
+node scripts/acp-mcp-test.mjs         # MCP 挂载测试（无模型调用）
+node scripts/acp-smoke-keyless.mjs    # keyless 冒烟（CI 用）
+node scripts/acp-resume-test.mjs      # 会话恢复测试
+```
+
+## 已知限制
+
+仅 baseline prompt（无图片/音频附件）、不支持 `additionalDirectories`、文本按块粒度
+流式、每会话同时一个 in-flight prompt。MCP 支持 stdio 与 streamable HTTP（不声明
+legacy SSE / `acp` 传输）。`session/close` / `session/fork` / `session/resume` 未实现
+（不声明能力，合规客户端不会调用）；`session/delete` 因 dsh 持久化无官方删除 API，
+采用直接删除后端目录的方式。

package/README.md

@@ -1,111 +1,127 @@
-**[English](README-en.md) | 中文**
+**[中文](README-zh.md) | English**
 
 # dsh-acp-enhanced
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的增强版
-[Agent Client Protocol](https://agentclientprotocol.com)（ACP）服务器，为 **Zed** 等 ACP
-编辑器设计。它是官方 `@deepseek-ai/dsh-acp` 桥接器的即插即用替代品：官方桥只做纯文本
-输出，本桥把 Web GUI 的能力（流式、遥测、模型/权限控制、会话管理、MCP）全部暴露到
-ACP 线上。
+An enhanced [Agent Client Protocol](https://agentclientprotocol.com) (ACP) server for
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), built for ACP
+editors like **Zed**. It is a drop-in replacement for the official `@deepseek-ai/dsh-acp`
+bridge: the official bridge only streams plain text, this one exposes the Web GUI's
+capabilities — streaming, telemetry, model/permission control, session management, MCP —
+over the ACP wire.
 
-## 特性
+## Features
 
-### 输出与遥测
+### Output & telemetry
 
-- **块级流式 + 推理流式**：文本块与思考过程实时到达（`agent_message_chunk` /
-  `agent_thought_chunk`），取消/重试不留半截输出
-- **完整遥测**：上下文用量环 + 缓存命中率 / TPS / 输入-输出-推理 token / 工具耗时 /
-  轮次计数（`usage_update._meta` 携带全量明细）
+- **Block + reasoning streaming**: text blocks and the model's thinking arrive live
+  (`agent_message_chunk` / `agent_thought_chunk`); cancelled/retried attempts never leak
+  torn output
+- **Full telemetry**: context usage ring plus cache hit rate / TPS / input-output-reasoning
+  tokens / tool timing / turn counts (`usage_update._meta` carries the full breakdown)
 
-### 模型与权限
+### Model & permissions
 
-- **模型切换**：实时 `provider/model` 目录下拉（按 ACP 规范分组线格式）
-- **推理强度**：`reasoning_effort` 下拉——仅当当前路由暴露可选 efforts 时出现
-- **权限预设**：read-only / workspace-write / full-access 三种会话模式
-- **审批**：工具调用弹出原生 allow-once / reject-once 审批
+- **Model switching**: live `provider/model` catalog dropdown (ACP grouped-select wire shape)
+- **Reasoning effort**: `reasoning_effort` dropdown — only when the routed model exposes
+  selectable efforts
+- **Permission presets**: read-only / workspace-write / full-access session modes
+- **Approval**: native allow-once / reject-once prompts per tool call
 
-### Zed 深度集成
+### Zed deep integration
 
-- **工具卡片**：展开可见每次调用的完整参数与结果预览（`rawInput` / `rawOutput`），
-  按工具类型渲染图标
-- **Zed 文件与终端**：`zed_read_text_file` / `zed_write_text_file` / `zed_terminal` 把
-  文件编辑放进 Zed 的"编辑文件"区（diff + 接受/拒绝）、命令跑在 Zed 真实终端
-- **原生表单提问**：`ask_user_question` → `elicitation/create` 表单，选项即点即答
-- **Plan 面板**：plan mode 开关 → Zed 底部"规划中"状态条
+- **Tool cards**: expand to see each call's full arguments and result preview
+  (`rawInput` / `rawOutput`), with per-kind icons
+- **Zed files & terminal**: `zed_read_text_file` / `zed_write_text_file` / `zed_terminal`
+  put file edits into Zed's "edited files" area (diff + accept/reject) and commands into a
+  real Zed terminal
+- **Native form questions**: `ask_user_question` → `elicitation/create` form, click an
+  option, no typing
+- **Plan panel**: plan mode toggle → "planning" status bar in Zed
 
-### 会话
+### Sessions
 
-- **恢复与归档**：`session/load` 恢复历史线程（完整回放）；`session/list` /
-  `session/delete` 管理线程归档（带标题、按更新时间排序）；标题实时推送
+- **Resume & archive**: `session/load` restores past threads (full replay);
+  `session/list` / `session/delete` manage the thread archive (titled, sorted by last
+  activity); live title updates
 
-### MCP
+### Commands
 
-- **MCP servers**：`session/new` 的 `mcpServers` 挂载任意 MCP server（stdio +
-  streamable HTTP），工具以 `mcp__<server>__<tool>` 注入；失败的 server 不会拖垮会话
+- **Slash commands**: typing `/` reveals the command list (`available_commands_update`):
+  `/status` shows the route and telemetry, `/model` lists or switches the model (listings
+  render as monospace code blocks — readable at a glance), everything
+  else (`/compact` `/goal` `/permission` `/plan`…) runs straight through the harness
+  command registry — all executed **without a model turn**; unresolved slashes fall
+  through to the model (the `/skill-name` skill gesture)
 
-## 效果预览
+### MCP
 
-在 Zed 的 AI Agent 面板中选择 **dsh-acp-enhanced** 后：
+- **MCP servers**: `session/new` `mcpServers` mount any MCP server (stdio + streamable
+  HTTP); tools join as `mcp__<server>__<tool>`; a failing server never takes the session
+  down
 
-<img src="assets/screenshots/approval-config-context.png" alt="审批弹窗与模型/推理强度切换、上下文环" width="560">
+## Preview
 
-- 工具调用需要许可时弹出**原生审批弹窗**；输入框下方是模型、推理强度、权限预设、
-  Plan mode 配置项与上下文用量环。
+After picking **dsh-acp-enhanced** in Zed's AI Agent panel:
 
-<img src="assets/screenshots/tool-cards-elicitation.png" alt="工具调用入参与输出、Zed 原生提问表单" width="320">
+<img src="assets/screenshots/approval-config-context.png" width="560">
 
-- **工具卡片**可展开查看完整入参与结果预览；DSH 需要确认/选择时以 **Zed 原生表单**
-  弹出，选项即点即答。
+<img src="assets/screenshots/tool-cards-elicitation.png" width="560">
 
-## 快速开始
+## Quick start
 
-本包遵循 dsh 官方插件规范（声明了 `dsh.bundle`），安装与官方组合包一致：**一条命令**
-完成，自动初始化 profile、安装包、追加 bundle 层，全程无需手写 profile YAML。
+This package follows the official dsh plugin conventions (it declares `dsh.bundle`), so
+installation matches any official bundle: **one command** — auto-initializes the profile,
+installs the package, appends the bundle layer; no profile YAML to write.
 
-### 安装（2 步）
+### Install (2 steps)
 
-**第 1 步：安装**（从 npm registry，无需下载源码）
+**Step 1 — install** (from the npm registry; no source checkout needed):
 
 ```sh
 dsh plugin --profile acp-enhanced add dsh-acp-enhanced
 ```
 
-> 开发/改源码时用 `link:` 指向本地 checkout（改动实时生效）：
+> When hacking on the code, use `link:` to a local checkout instead (live edits):
 > `dsh plugin --profile acp-enhanced add "link:/absolute/path/to/dsh-acp-enhanced"`
 
-**第 2 步：注册进 Zed**（在 `~/.config/zed/settings.json` 的 `agent_servers` 里注册；
-Zed 会用极简 PATH 拉起 agent，因此用随附启动器 `scripts/dsh-acp-zed.sh` 定位
-`node`/`dsh`）
+**Step 2 — register in Zed** (under `agent_servers` in `~/.config/zed/settings.json`;
+Zed spawns agents with a minimal PATH, so use the shipped launcher
+`scripts/dsh-acp-zed.sh`, which locates `node`/`dsh` itself)
 
-#### 最常见：DeepSeek 官方 API（默认路由）
+> **The launcher ships with the package.** Its absolute path depends on how you
+> installed in Step 1:
+> - **npm install (default)**: `$HOME/.dsh/profiles/acp-enhanced/node_modules/dsh-acp-enhanced/scripts/dsh-acp-zed.sh` — replace `$HOME` with your home directory (e.g. `/Users/you`); Zed does not expand `~` or env vars, so write the full literal path.
+> - **`link:` dev install**: `<your checkout>/scripts/dsh-acp-zed.sh`.
+
+#### Most common: DeepSeek official API (the default route)
 
 ```jsonc
 {
-  // ...你已有的设置...
+  // ...your existing settings...
   "agent_servers": {
     "dsh-acp-enhanced": {
       "type": "custom",
       "command": "/bin/bash",
       "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
       "env": {
-        "DSH_ACP_PROVIDER": "deepseek-official",  // 官方 provider id
-        "DSH_ACP_MODEL": "deepseek-v4-flash"      // 官方模型 id
+        "DSH_ACP_PROVIDER": "deepseek-official",  // the official provider id
+        "DSH_ACP_MODEL": "deepseek-v4-flash"      // the official model id
       }
     }
   }
 }
 ```
 
-> 这两项 env 与包自带 patch 的缺省值一致，**省略也能工作**——显式写上只是让路由意图
-> 一目了然。API key 不必写进 Zed：存入 `~/.dsh/.credentials.yaml`
-> （`DEEPSEEK_API_KEY`）由 dsh 凭据服务解析即可；启动脚本还会兜底继承正在运行的
-> `dsh web` 进程的 key。
+> Both env vars match the shipped patch's defaults, so **they can be omitted entirely** —
+> writing them out just makes the route explicit. The API key does not have to live in Zed:
+> store it in `~/.dsh/.credentials.yaml` (`DEEPSEEK_API_KEY`) and the dsh credentials
+> service resolves it; the launcher also falls back to a running `dsh web` process's key.
 
-可选：固定面板默认项（都可随时在面板里改）：
+Optional: pin the panel's default config options (all still changeable in the panel):
 
 ```jsonc
 "dsh-acp-enhanced": {
-  // ...上面的 type/command/args/env...
+  // ...the type/command/args/env above...
   "default_config_options": {
     "model": "deepseek-official/deepseek-v4-flash",
     "plan_mode": false,
@@ -117,9 +133,10 @@ Zed 会用极简 PATH 拉起 agent，因此用随附启动器 `scripts/dsh-acp-z
 }
 ```
 
-#### 扩展：走 OpenAI-Responses 网关（如公司内部模型网关）
+#### Extended: route through an OpenAI-Responses gateway (e.g. a company model gateway)
 
-同一安装路径，只是 env 换成网关暴露的 provider/model 与它要求的 key 环境变量名：
+Same install path; only the env values change to the provider/model the gateway exposes
+plus the key env var it requires:
 
 ```jsonc
 "dsh-acp-enhanced": {
@@ -127,31 +144,34 @@ Zed 会用极简 PATH 拉起 agent，因此用随附启动器 `scripts/dsh-acp-z
   "command": "/bin/bash",
   "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
   "env": {
-    "DSH_ACP_PROVIDER": "<gateway-provider-id>",  // 网关暴露的 provider id
-    "DSH_ACP_MODEL": "<gateway-model-id>",         // 网关暴露的 model id
-    "<KEY_ENV_NAME>": "<key>"                      // 网关声明读取的 key 环境变量名
+    "DSH_ACP_PROVIDER": "<gateway-provider-id>",  // provider id exposed by the gateway
+    "DSH_ACP_MODEL": "<gateway-model-id>",         // model id exposed by the gateway
+    "<KEY_ENV_NAME>": "<key>"                      // the key env var the gateway reads
   }
 }
 ```
 
-> `<KEY_ENV_NAME>` 也可以省掉，把 key 存进 `~/.dsh/.credentials.yaml` 统一管理。
+> `<KEY_ENV_NAME>` can also be omitted and the key stored in
+> `~/.dsh/.credentials.yaml` instead.
 
-Zed 会热重载设置。打开 **AI Agent 面板**（`Cmd+Shift+A`）→ agent 选择器选
-**dsh-acp-enhanced** → 输入第一条消息即可：回复实时流式返回，状态栏显示上下文用量，
-面板顶部有 Model / Permission preset / Plan mode 配置项与三种模式，线程归档可恢复
-历史会话。
+Zed hot-reloads settings. Open the **AI Agent panel** (`Cmd+Shift+A`) → pick
+**dsh-acp-enhanced** in the agent selector → send your first message: replies stream in
+real time, the status bar shows context usage, the panel exposes Model / Permission preset
+/ Plan mode options plus three modes, and the thread archive lists and resumes past
+sessions.
 
-本地验证（无需 Zed）：
+Verify locally (no Zed needed):
 
 ```sh
-node scripts/acp-client.mjs                    # 官方默认路由，无需 env；期望 ALL CHECKS PASSED
-DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # 自定义路由时再传
+node scripts/acp-client.mjs                    # official default route, no env; expect ALL CHECKS PASSED
+DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # only for a custom route
 ```
 
-### 可选：web_search 走同一个网关
+### Optional: route web_search through the same gateway
 
-若网关实现 OpenAI Responses 的 `web_search` 服务端工具，可把搜索也路由到网关（复用
-同一凭据）。装子包并给 profile 的 `cordis.patch.yml` 追加两段：
+If the gateway implements the OpenAI Responses `web_search` server tool, you can route
+search through it too (reusing the same credential). Install the sub-package and append
+two blocks to the profile's `cordis.patch.yml`:
 
 ```sh
 dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
@@ -160,7 +180,7 @@ dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
 ```yaml
 - id: web
   config:
-    searchProvider: <provider>
+    searchProvider: openai-responses   # the search provider id this sub-package registers on ctx.web (fixed value)
 
 - insert:
     - id: web-search-openrouter
@@ -172,29 +192,36 @@ dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
         apiKeyEnv: <KEY_ENV_NAME>
 ```
 
-## 故障排查
+> ⚠️ `searchProvider` must be **exactly** `openai-responses` — the search provider id
+> `dsh-web-search-openrouter` registers on `ctx.web`. It is **not** your gateway's LLM
+> provider id (the one you put in `DSH_ACP_PROVIDER` above). The `web` plugin matches it
+> exactly, so a wrong value produces no error at config time and only fails at the first
+> search with `WEB_PROVIDER_CONFIGURED_MISSING`.
+
+## Troubleshooting
 
-| 症状 | 处理 |
+| Symptom | Fix |
 |---|---|
-| `exec: dsh: not found`（status 127） | 用随附 `dsh-acp-zed.sh` 启动器（自定位 node/dsh） |
-| `no API key for provider route "xxx"` | 写入 `~/.dsh/.credentials.yaml`，或在 agent_servers 里设 `env.DEEPSEEK_API_KEY` |
-| 无法切换模型 / 上下文用量不显示 | 选到了不可路由的"幽灵 provider"；本桥默认过滤（只广播 `config.provider` 的模型），确认 profile 的 provider 指向真实路由 |
-| 需要详细诊断 | `ACP_DEBUG=1 dsh --profile acp-enhanced`（stderr 生命周期 trace） |
+| `exec: dsh: not found` (status 127) | Use the shipped `dsh-acp-zed.sh` launcher (locates node/dsh itself) |
+| `no API key for provider route "xxx"` | Write `~/.dsh/.credentials.yaml`, or set `env.DEEPSEEK_API_KEY` on the agent_servers entry |
+| Cannot switch models / context usage missing | A "phantom provider" route was picked; this bridge filters them by default (only `config.provider`'s models are advertised) — point the profile's provider at a real route |
+| Need detailed diagnostics | `ACP_DEBUG=1 dsh --profile acp-enhanced` (stderr lifecycle trace) |
 
-## 开发
+## Development
 
 ```sh
-node scripts/acp-client.mjs           # 端到端冒烟（需要 API key）
-node scripts/acp-client-tools.mjs     # 客户端工具测试（模拟 Zed 的 fs/terminal/elicitation/plan）
-node scripts/acp-mcp-test.mjs         # MCP 挂载测试（无模型调用）
-node scripts/acp-smoke-keyless.mjs    # keyless 冒烟（CI 用）
-node scripts/acp-resume-test.mjs      # 会话恢复测试
+node scripts/acp-client.mjs           # end-to-end smoke (needs an API key)
+node scripts/acp-client-tools.mjs     # client-tool tests (mocks Zed fs/terminal/elicitation/plan)
+node scripts/acp-mcp-test.mjs         # MCP mount test (no model calls)
+node scripts/acp-smoke-keyless.mjs    # keyless boot smoke (CI)
+node scripts/acp-resume-test.mjs      # session resume test
 ```
 
-## 已知限制
+## Known limitations
 
-仅 baseline prompt（无图片/音频附件）、不支持 `additionalDirectories`、文本按块粒度
-流式、每会话同时一个 in-flight prompt。MCP 支持 stdio 与 streamable HTTP（不声明
-legacy SSE / `acp` 传输）。`session/close` / `session/fork` / `session/resume` 未实现
-（不声明能力，合规客户端不会调用）；`session/delete` 因 dsh 持久化无官方删除 API，
-采用直接删除后端目录的方式。
+Baseline prompts only (no image/audio attachments), no `additionalDirectories`, text
+streams at block granularity, one in-flight prompt per session. MCP supports stdio and
+streamable HTTP (legacy SSE / `acp` transports are not advertised).
+`session/close` / `session/fork` / `session/resume` are not implemented (capabilities
+undeclared, compliant clients will not call them); `session/delete` removes the persisted
+directory directly because dsh persistence has no official delete API.

package/lib/codec.js

@@ -57,6 +57,40 @@ export function promptHasUnsupportedContent(prompt) {
   return prompt.some((block) => block.type !== 'text' && block.type !== 'resource_link')
 }
 
+/** Kramdown attribute-style inline markup (SiYuan exports), including
+ *  truncation-damaged tails — titles are byte-budgeted upstream, so a cut
+ *  can land mid-attribute (unterminated `"` or no closing `]`):
+ *  `[resource_link name="..." url="..."]`, `[file_link ...]`, `[ref ...]`. */
+const KRAMDOWN_ATTR_MARKUP = /\[[^\]]*="[^\]]*\]|\[[^\]]*="[^\]]*$/g
+
+/** Tight markdown link `[label](url)` — kept as the label only. */
+const MARKDOWN_LINK = /\[([^\]]+)\]\(([^)\s]+)\)/g
+
+/** Human-facing attribute kept when stripping kramdown markup; the closing
+ *  quote is optional so a value truncated at the byte budget still survives. */
+const ATTR_NAME_OR_TEXT = /(?:name|text)="([^"]*)"?/i
+
+/**
+ * Sanitize a session title for display on the ACP wire. Titles derive from
+ * raw first-prompt text, which often carries pasted markup — SiYuan's
+ * kramdown `[resource_link ...]` / `[file_link ...]` / `[ref ...]` inline
+ * syntax (possibly truncated mid-markup), or plain markdown links. Keeps the
+ * human-facing name/text (or the markdown label) and collapses whitespace
+ * to a single line.
+ * @param input - untrusted title text (raw or upstream-normalized).
+ * @returns the cleaned title; `''` when nothing visible remains.
+ */
+export function sanitizeWireTitle(input) {
+  return String(input ?? '')
+    .replace(MARKDOWN_LINK, '$1')
+    .replace(KRAMDOWN_ATTR_MARKUP, (match) => {
+      const keep = ATTR_NAME_OR_TEXT.exec(match)
+      return keep === null ? '' : keep[1]
+    })
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 /**
  * Compute the usage telemetry snapshot for one provider-reported usage sample.
  * @param usage - TokenUsage { inputTokens, outputTokens, cacheReadTokens?, cacheWriteTokens?, reasoningTokens? }.

package/lib/index.js

@@ -31,6 +31,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { rm } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { isAbsolute, dirname } from 'node:path'
 import { Readable, Writable } from 'node:stream'
 import Schema from '@deepseek-ai/schemastery'
@@ -39,11 +40,15 @@ import { createUserMessage, errorChain, ReasoningEffortId } from '@deepseek-ai/d
 import { installModelSelection } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason, usageTelemetry } from './codec.js'
+import { acpPromptToText, promptHasUnsupportedContent, sanitizeWireTitle, turnEndToStopReason, usageTelemetry } from './codec.js'
+
+/** Agent version advertised on the ACP wire — read from package.json so the
+ *  handshake can never drift from the released package version. */
+const AGENT_VERSION = createRequire(import.meta.url)('../package.json').version
 
 export const name = 'acp-enhanced'
 /** The bridge creates and owns agents; every other concern is carried by the composition. */
-export const inject = ['agents', 'llm', 'approval', 'tools']
+export const inject = ['agents', 'llm', 'approval', 'tools', 'commands']
 
 export const Config = Schema.object({
   /** Initial provider route for every created agent. */
@@ -121,6 +126,7 @@ export function apply(ctx, config) {
   const llm = ctx.llm
   const approval = ctx.approval
   const tools = ctx.tools
+  const commands = ctx.commands
   const logger = ctx.logger
   /** The user-questions service (mounted by dsh-base); absent in minimal deployments. */
   const userQuestions = ctx.get('userQuestions')
@@ -281,7 +287,10 @@ export function apply(ctx, config) {
           if (event.data.contextWindow !== undefined) record.contextWindow = event.data.contextWindow
           break
         case 'session/title': {
-          const title = event.data.title
+          // Titles derive from raw first-prompt text; sanitize before the wire
+          // so pasted markup (e.g. SiYuan `[resource_link ...]`) can't leak
+          // into Zed's thread title.
+          const title = sanitizeWireTitle(event.data.title)
           if (typeof title === 'string' && title.length > 0) {
             record.title = title
             publishSessionInfo(record, {
@@ -1001,6 +1010,111 @@ export function apply(ctx, config) {
     }
   }
 
+  // ── slash commands (adapter built-ins + harness command registry) ────────
+
+  /** Adapter-level commands, always first in the advertised list. */
+  const BUILTIN_COMMANDS = [
+    { name: 'status', description: 'Show session status: model route, context usage, telemetry.' },
+    { name: 'model', description: 'List the model catalog, or switch with /model <provider/model | substring>.' },
+  ]
+
+  /**
+   * Advertise the full command surface for a session as ACP
+   * `available_commands_update`: adapter built-ins plus whatever the harness
+   * command registry (compact/goal/permission/plan/…) serves for the agent.
+   */
+  async function publishCommands(record) {
+    const list = [...BUILTIN_COMMANDS]
+    const seen = new Set(list.map((command) => command.name))
+    try {
+      for (const descriptor of commands.list(record.agent)) {
+        if (seen.has(descriptor.name)) continue
+        seen.add(descriptor.name)
+        list.push({
+          name: descriptor.name,
+          description: descriptor.description,
+          ...descriptor.input === undefined ? {} : { input: descriptor.input },
+        })
+      }
+    } catch (error) {
+      logger.warn(`acp-enhanced: command listing failed: ${String(error)}`)
+    }
+    notify({
+      sessionId: record.agent.session.id,
+      update: { sessionUpdate: 'available_commands_update', availableCommands: list },
+    })
+  }
+
+  /**
+   * Advertise the command surface *after* the current request response is
+   * written. A fresh `session/new` id is generated server-side, so the client
+   * cannot route session notifications for it until the response arrives; an
+   * `available_commands_update` queued before that response is dropped and
+   * the slash menu stays empty ("Available commands: none").
+   */
+  function publishCommandsAfterResponse(record) {
+    setImmediate(() => {
+      publishCommands(record).catch((error) => {
+        logger.warn(`acp-enhanced: command broadcast failed: ${String(error)}`)
+      })
+    })
+  }
+
+  /** Text summary of one session: route, turns, last usage telemetry. */
+  async function statusText(record) {
+    const selection = record.selection.current
+    const last = record.lastUsage
+    const lines = [
+      `route      ${selection.provider ?? '?'}/${selection.model ?? '?'}`,
+      `turns      ${record.turnCount}`,
+      ...last === undefined ? [] : [
+        `context    ${last.used}/${last.size}`,
+        `last usage ${last.meta.inputTokens ?? '?'}/${last.meta.outputTokens ?? '?'} in/out, ${last.meta.reasoningTokens ?? '?'} reasoning, cache hit ${last.meta.cacheHitRate ?? '?'}%, ${last.meta.tps ?? '?'} tps`,
+      ],
+    ]
+    // Monospace code block: aligned columns at a glance, no interaction needed.
+    return ['```', ...lines, '```'].join('\n')
+  }
+
+  /** The /model command: list the live catalog or switch by exact id/substring. */
+  async function modelCommandText(record, query) {
+    const catalog = await modelCatalog()
+    const current = record.selection.current
+    if (query.trim().length === 0) {
+      const lines = catalog.flatMap((group) => group.models.map((model) => {
+        const mark = `${group.id}/${model.id}` === `${current.provider}/${current.model}` ? '* ' : '  '
+        return `${mark}${group.id}/${model.id}`
+      }))
+      // Monospace code block: aligned catalog, no interaction needed.
+      return lines.length > 0 ? ['```', ...lines, '```'].join('\n') : 'no models available'
+    }
+    const needle = query.trim().toLowerCase()
+    const matches = catalog.flatMap((group) => group.models.map((model) => ({ provider: group.id, model: model.id })))
+      .filter((candidate) => `${candidate.provider}/${candidate.model}`.toLowerCase().includes(needle) || candidate.model.toLowerCase().includes(needle))
+    if (matches.length === 0) return `no model matches "${query}"`
+    if (matches.length > 1) return `ambiguous: ${matches.map((m) => `${m.provider}/${m.model}`).join(', ')}`
+    await applySelection(record, { provider: matches[0].provider, model: matches[0].model })
+    return `switched to ${matches[0].provider}/${matches[0].model}`
+  }
+
+  /** Refresh every client-visible surface a command may have mutated. */
+  function refreshAfterCommand(record) {
+    const permission = permissionPresets()
+    if (permission !== undefined) {
+      notify({
+        sessionId: record.agent.session.id,
+        update: {
+          sessionUpdate: 'current_mode_update',
+          currentModeId: permission.current(record.agent.session.events),
+        },
+      })
+    }
+    broadcastConfig(record).catch((error) => {
+      logger.warn(`acp-enhanced: config rebroadcast after command failed: ${String(error)}`)
+    })
+    publishCommands(record)
+  }
+
   // ── session records + history replay ─────────────────────────────────────
 
   /** Build the bridge-owned protocol record for a fresh or resumed agent. */
@@ -1066,7 +1180,9 @@ export function apply(ctx, config) {
           // Malformed line — skip; titles live on well-formed rows.
         }
       }
-      return last
+      // Stored titles are the raw upstream text (the sanitizer runs on the
+      // live path only); clean them here so replay shows the same wire shape.
+      return last === undefined ? undefined : sanitizeWireTitle(last)
     } catch {
       return undefined
     }
@@ -1202,7 +1318,7 @@ export function apply(ctx, config) {
         syncClientTools()
         return Promise.resolve({
           protocolVersion: PROTOCOL_VERSION,
-          agentInfo: { name: 'deepseek-harness-acp-enhanced', version: '0.2.0' },
+          agentInfo: { name: 'deepseek-harness-acp-enhanced', version: AGENT_VERSION },
           agentCapabilities: {
             loadSession: true,
             sessionCapabilities: { list: {}, delete: {} },
@@ -1238,6 +1354,7 @@ export function apply(ctx, config) {
         const record = makeRecord(handle)
         sessions.set(sessionId, record)
         await syncMcpServers(params.mcpServers, params.cwd)
+        publishCommandsAfterResponse(record)
         const permission = permissionPresets()
         return {
           sessionId,
@@ -1299,6 +1416,7 @@ export function apply(ctx, config) {
         // Zed inserts the thread before the load RPC completes; replay the
         // conversation history as notifications so the thread renders.
         await replayHistory(record)
+        publishCommandsAfterResponse(record)
         const permission = permissionPresets()
         return {
           ...permission === undefined ? {} : {
@@ -1329,6 +1447,49 @@ export function apply(ctx, config) {
         }
         const text = acpPromptToText(params.prompt)
         if (text.trim().length === 0) throw invalidParams('empty prompt')
+
+        // Insurance: by the first prompt the client is guaranteed to know the
+        // session, so re-advertise the command surface (idempotent) — covers
+        // any client that missed the post-session/new broadcast.
+        publishCommands(record)
+
+        // Adapter-level slash commands never reach the model: /status and
+        // /model are built in, any other registered slash (compact/goal/
+        // permission/plan/…) runs through the harness command registry
+        // without a model turn. An unresolved slash falls through — the
+        // /skill-name gesture is claimed inside the agent's next step.
+        const trimmed = text.trim()
+        const commandMatch = trimmed.match(/^\/(\w[\w-]*)\b/)
+        const respond = (reply) => {
+          notify({
+            sessionId: record.agent.session.id,
+            update: {
+              sessionUpdate: 'agent_message_chunk',
+              messageId: randomUUID(),
+              content: { type: 'text', text: reply },
+            },
+          })
+          return { stopReason: 'end_turn' }
+        }
+        if (commandMatch?.[1] === 'status') return respond(await statusText(record))
+        if (commandMatch?.[1] === 'model') {
+          return respond(await modelCommandText(record, trimmed.slice(commandMatch[0].length).trim()))
+        }
+        if (commandMatch !== null && commandMatch[1] !== undefined) {
+          let execution
+          try {
+            execution = await commands.execute(record.agent, trimmed, new AbortController().signal)
+          } catch (error) {
+            return respond(`⚠ /${commandMatch[1]} failed: ${error.message ?? String(error)}`)
+          }
+          if (execution !== undefined) {
+            const { result } = execution
+            const reply = result.text ?? (result.kind === 'success' ? `/${commandMatch[1]} ✓` : `/${commandMatch[1]} failed`)
+            refreshAfterCommand(record)
+            return respond(result.kind === 'error' ? `⚠ ${reply}` : reply)
+          }
+        }
+
         if (ctx.agents.get(record.agent.id) !== record.agent) {
           throw internalError('prompt was not queued: the agent was disposed outside the bridge')
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-acp-enhanced",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Enhanced ACP server for DeepSeek Harness: block-level streaming, usage/stat telemetry (cache hit rate, token speed, input/output tokens, context length, turns, tool timing), model & reasoning-effort switching, and permission-preset control over the ACP wire (Zed-friendly)",
   "keywords": [
     "dsh",
@@ -23,9 +23,10 @@
   "files": [
     "lib",
     "profile",
+    "scripts/dsh-acp-zed.sh",
     "cordis.patch.yml",
     "README.md",
-    "README-en.md",
+    "README-zh.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/dsh-acp-zed.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Zed launcher for dsh-acp-enhanced.
+#
+# Zed (a GUI app) spawns agent processes with a minimal PATH that usually does
+# NOT include node or dsh, so this wrapper locates both itself:
+#   - node: PATH, /opt/homebrew/bin, /usr/local/bin, ~/.nvm/versions/node/*
+#   - dsh:  PATH, the npx cache (~/.npm/_npx/*/node_modules/.bin), the global
+#           npm prefix bin dir, /opt/homebrew/bin, /usr/local/bin
+# and prepends the node dir to PATH so dsh's `#!/usr/bin/env node` shebang
+# resolves.
+#
+# The profile resolves DEEPSEEK_API_KEY through the dsh credentials service
+# (~/.dsh/.credentials.yaml), so no environment plumbing is required; an
+# explicit DEEPSEEK_API_KEY from Zed's agent_servers.env wins, and a running
+# `dsh web` process is a final fallback source.
+#
+# stdout stays the ACP JSON-RPC wire; diagnostics go to stderr.
+set -u
+
+NODE_BIN="$(command -v node 2>/dev/null || true)"
+if [ -z "${NODE_BIN}" ]; then
+  for candidate in \
+    /opt/homebrew/bin/node \
+    /usr/local/bin/node \
+    "$HOME"/.nvm/versions/node/*/bin/node; do
+    if [ -x "${candidate}" ]; then
+      NODE_BIN="${candidate}"
+      break
+    fi
+  done
+fi
+if [ -n "${NODE_BIN}" ]; then
+  export PATH="$(dirname "${NODE_BIN}"):${PATH}"
+fi
+
+DASH_BIN="$(command -v dsh 2>/dev/null || true)"
+if [ -z "${DASH_BIN}" ]; then
+  for candidate in \
+    "$HOME"/.npm/_npx/*/node_modules/.bin/dsh \
+    "$(npm prefix -g 2>/dev/null)/bin/dsh" \
+    /opt/homebrew/bin/dsh \
+    /usr/local/bin/dsh; do
+    if [ -x "${candidate}" ]; then
+      DASH_BIN="${candidate}"
+      break
+    fi
+  done
+fi
+if [ -z "${NODE_BIN}" ] || [ -z "${DASH_BIN}" ]; then
+  echo "dsh-acp-zed: cannot locate node and/or dsh (node='${NODE_BIN}' dsh='${DASH_BIN}'); install them or set PATH" >&2
+  exit 127
+fi
+
+if [ -z "${DEEPSEEK_API_KEY:-}" ]; then
+  WEB_PID="$(pgrep -f 'dsh web' | head -n 1)"
+  if [ -n "${WEB_PID}" ]; then
+    KEY="$(ps eww "${WEB_PID}" 2>/dev/null | tr ' ' '\n' | grep '^DEEPSEEK_API_KEY=' | cut -d= -f2-)"
+    if [ -n "${KEY}" ]; then
+      export DEEPSEEK_API_KEY="${KEY}"
+    fi
+  fi
+fi
+
+exec "${DASH_BIN}" --profile acp-enhanced "$@"

package/README-en.md

@@ -1,215 +0,0 @@
-**[中文](README.md) | English**
-
-# dsh-acp-enhanced
-
-An enhanced [Agent Client Protocol](https://agentclientprotocol.com) (ACP) server for
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), built for ACP
-editors like **Zed**. It is a drop-in replacement for the official `@deepseek-ai/dsh-acp`
-bridge: the official bridge only streams plain text, this one exposes the Web GUI's
-capabilities — streaming, telemetry, model/permission control, session management, MCP —
-over the ACP wire.
-
-## Features
-
-### Output & telemetry
-
-- **Block + reasoning streaming**: text blocks and the model's thinking arrive live
-  (`agent_message_chunk` / `agent_thought_chunk`); cancelled/retried attempts never leak
-  torn output
-- **Full telemetry**: context usage ring plus cache hit rate / TPS / input-output-reasoning
-  tokens / tool timing / turn counts (`usage_update._meta` carries the full breakdown)
-
-### Model & permissions
-
-- **Model switching**: live `provider/model` catalog dropdown (ACP grouped-select wire shape)
-- **Reasoning effort**: `reasoning_effort` dropdown — only when the routed model exposes
-  selectable efforts
-- **Permission presets**: read-only / workspace-write / full-access session modes
-- **Approval**: native allow-once / reject-once prompts per tool call
-
-### Zed deep integration
-
-- **Tool cards**: expand to see each call's full arguments and result preview
-  (`rawInput` / `rawOutput`), with per-kind icons
-- **Zed files & terminal**: `zed_read_text_file` / `zed_write_text_file` / `zed_terminal`
-  put file edits into Zed's "edited files" area (diff + accept/reject) and commands into a
-  real Zed terminal
-- **Native form questions**: `ask_user_question` → `elicitation/create` form, click an
-  option, no typing
-- **Plan panel**: plan mode toggle → "planning" status bar in Zed
-
-### Sessions
-
-- **Resume & archive**: `session/load` restores past threads (full replay);
-  `session/list` / `session/delete` manage the thread archive (titled, sorted by last
-  activity); live title updates
-
-### MCP
-
-- **MCP servers**: `session/new` `mcpServers` mount any MCP server (stdio + streamable
-  HTTP); tools join as `mcp__<server>__<tool>`; a failing server never takes the session
-  down
-
-## Preview
-
-After picking **dsh-acp-enhanced** in Zed's AI Agent panel:
-
-<img src="assets/screenshots/approval-config-context.png" alt="Approval popup, model/reasoning-effort switches, context ring" width="560">
-
-- Tool calls that need permission pop a **native approval prompt**; below the input box sit
-  the model, reasoning effort, permission preset, plan mode options and the context usage
-  ring.
-
-<img src="assets/screenshots/tool-cards-elicitation.png" alt="Tool call inputs and outputs, native Zed question form" width="320">
-
-- **Tool cards** expand to show full arguments and result previews; when dsh needs your
-  confirmation or a choice, the question arrives as a **native Zed form** — click an
-  option, no typing.
-
-## Quick start
-
-This package follows the official dsh plugin conventions (it declares `dsh.bundle`), so
-installation matches any official bundle: **one command** — auto-initializes the profile,
-installs the package, appends the bundle layer; no profile YAML to write.
-
-### Install (2 steps)
-
-**Step 1 — install** (from the npm registry; no source checkout needed):
-
-```sh
-dsh plugin --profile acp-enhanced add dsh-acp-enhanced
-```
-
-> When hacking on the code, use `link:` to a local checkout instead (live edits):
-> `dsh plugin --profile acp-enhanced add "link:/absolute/path/to/dsh-acp-enhanced"`
-
-**Step 2 — register in Zed** (under `agent_servers` in `~/.config/zed/settings.json`;
-Zed spawns agents with a minimal PATH, so use the shipped launcher
-`scripts/dsh-acp-zed.sh`, which locates `node`/`dsh` itself)
-
-#### Most common: DeepSeek official API (the default route)
-
-```jsonc
-{
-  // ...your existing settings...
-  "agent_servers": {
-    "dsh-acp-enhanced": {
-      "type": "custom",
-      "command": "/bin/bash",
-      "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
-      "env": {
-        "DSH_ACP_PROVIDER": "deepseek-official",  // the official provider id
-        "DSH_ACP_MODEL": "deepseek-v4-flash"      // the official model id
-      }
-    }
-  }
-}
-```
-
-> Both env vars match the shipped patch's defaults, so **they can be omitted entirely** —
-> writing them out just makes the route explicit. The API key does not have to live in Zed:
-> store it in `~/.dsh/.credentials.yaml` (`DEEPSEEK_API_KEY`) and the dsh credentials
-> service resolves it; the launcher also falls back to a running `dsh web` process's key.
-
-Optional: pin the panel's default config options (all still changeable in the panel):
-
-```jsonc
-"dsh-acp-enhanced": {
-  // ...the type/command/args/env above...
-  "default_config_options": {
-    "model": "deepseek-official/deepseek-v4-flash",
-    "plan_mode": false,
-    "reasoning_effort": "high"
-  },
-  "favorite_config_option_values": {
-    "model": ["deepseek-official/deepseek-v4-flash", "deepseek-official/deepseek-v4-pro"]
-  }
-}
-```
-
-#### Extended: route through an OpenAI-Responses gateway (e.g. a company model gateway)
-
-Same install path; only the env values change to the provider/model the gateway exposes
-plus the key env var it requires:
-
-```jsonc
-"dsh-acp-enhanced": {
-  "type": "custom",
-  "command": "/bin/bash",
-  "args": ["/absolute/path/to/dsh-acp-enhanced/scripts/dsh-acp-zed.sh"],
-  "env": {
-    "DSH_ACP_PROVIDER": "<gateway-provider-id>",  // provider id exposed by the gateway
-    "DSH_ACP_MODEL": "<gateway-model-id>",         // model id exposed by the gateway
-    "<KEY_ENV_NAME>": "<key>"                      // the key env var the gateway reads
-  }
-}
-```
-
-> `<KEY_ENV_NAME>` can also be omitted and the key stored in
-> `~/.dsh/.credentials.yaml` instead.
-
-Zed hot-reloads settings. Open the **AI Agent panel** (`Cmd+Shift+A`) → pick
-**dsh-acp-enhanced** in the agent selector → send your first message: replies stream in
-real time, the status bar shows context usage, the panel exposes Model / Permission preset
-/ Plan mode options plus three modes, and the thread archive lists and resumes past
-sessions.
-
-Verify locally (no Zed needed):
-
-```sh
-node scripts/acp-client.mjs                    # official default route, no env; expect ALL CHECKS PASSED
-DSH_ACP_PROVIDER=... DSH_ACP_MODEL=... node scripts/acp-client.mjs   # only for a custom route
-```
-
-### Optional: route web_search through the same gateway
-
-If the gateway implements the OpenAI Responses `web_search` server tool, you can route
-search through it too (reusing the same credential). Install the sub-package and append
-two blocks to the profile's `cordis.patch.yml`:
-
-```sh
-dsh plugin --profile acp-enhanced add dsh-web-search-openrouter
-```
-
-```yaml
-- id: web
-  config:
-    searchProvider: <provider>
-
-- insert:
-    - id: web-search-openrouter
-      name: 'dsh-web-search-openrouter'
-      config:
-        enabled: true
-        baseURL: http://<gateway-host>:<port>/v1
-        model: <your-model-id>
-        apiKeyEnv: <KEY_ENV_NAME>
-```
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| `exec: dsh: not found` (status 127) | Use the shipped `dsh-acp-zed.sh` launcher (locates node/dsh itself) |
-| `no API key for provider route "xxx"` | Write `~/.dsh/.credentials.yaml`, or set `env.DEEPSEEK_API_KEY` on the agent_servers entry |
-| Cannot switch models / context usage missing | A "phantom provider" route was picked; this bridge filters them by default (only `config.provider`'s models are advertised) — point the profile's provider at a real route |
-| Need detailed diagnostics | `ACP_DEBUG=1 dsh --profile acp-enhanced` (stderr lifecycle trace) |
-
-## Development
-
-```sh
-node scripts/acp-client.mjs           # end-to-end smoke (needs an API key)
-node scripts/acp-client-tools.mjs     # client-tool tests (mocks Zed fs/terminal/elicitation/plan)
-node scripts/acp-mcp-test.mjs         # MCP mount test (no model calls)
-node scripts/acp-smoke-keyless.mjs    # keyless boot smoke (CI)
-node scripts/acp-resume-test.mjs      # session resume test
-```
-
-## Known limitations
-
-Baseline prompts only (no image/audio attachments), no `additionalDirectories`, text
-streams at block granularity, one in-flight prompt per session. MCP supports stdio and
-streamable HTTP (legacy SSE / `acp` transports are not advertised).
-`session/close` / `session/fork` / `session/resume` are not implemented (capabilities
-undeclared, compliant clients will not call them); `session/delete` removes the persisted
-directory directly because dsh persistence has no official delete API.