Paseo 接入 renat3u/dsh-paseo

dsh-paseo

将 dsh（DeepSeek Harness）作为 Paseo 的 ACP provider：在 Paseo 界面里并行运行和管理多个 dsh agent，并稳定地拉起 dsh。

特性

- Paseo：dsh 注册为 Paseo 的 ACP provider（Agent Client Protocol over stdio JSON-RPC），在 Paseo 的桌面 / Web / 手机客户端里直接选择 "DSH (DeepSeek Harness)" 创建会话。
- 并行 agent：每个 dsh 会话是一个独立 dsh 进程（独立会话日志、独立 workspace、独立取消路径），Paseo 的 attach / logs / send / stop / delete 全部可用。
- 稳定拉起：launcher 自动解析 dsh 安装、自愈初始化 paseo profile、转发信号、保持 stdout 协议纯净；Paseo 杀进程 / 断连都能干净收尾。
- 不改 dsh 源码：dsh 侧通过官方 profile bundle 机制注入一个 ACP 桥插件，只消费公开接缝（ctx.agents / ctx.sessions / ctx.approval）。
- 模型可组合：默认继承所连接 dsh 服务的默认模型；通过派生 provider + 环境变量可显式覆盖出任意模型 / 端点配置（flash、pro、自定义 baseURL 等）。
- 权限可控：默认 workspace-write 沙箱 + 一次性权限询问（Paseo 界面 allow-once / reject），可选 danger-full-access。

架构

Paseo daemon（桌面 / Web / 手机 / CLI 客户端） │ 每个 dsh 会话 spawn 一个进程，ACP over stdio（JSON-RPC 2.0） ▼ bin/dsh-paseo-launch.mjs ← 稳定拉起：解析 dsh → 自愈 profile → 信号转发（位于 bundle 包内：packages/dsh-paseo/bin/） ▼
dsh --profile paseo ← bundles: [@deepseek-ai/dsh-base, @deepseek-ai/dsh-paseo]
└─ paseo-acp 桥插件 ← initialize / session/new / prompt / cancel / request_permission

环境要求

| 依赖 | 版本 | 说明 |
| Node.js | ≥ 22.19 | launcher 与构建脚本 |
| pnpm | 11.x | dsh plugin 内部转发（profile 安装）；dsh 源码仓库根运行 pnpm dsh web 启动 Web 界面 |
| dsh | 当前 rc | 源码快照（仓库根 pnpm dsh web 启动 Web 界面）；launcher 解析 dsh 可执行：PATH → ~/.dsh/source/current |
| Paseo | ≥ 0.3 | @getpaseo/cli（npm install -g @getpaseo/cli）或桌面版 |
| DeepSeek API Key | — | 走 dsh 侧凭据：环境变量 / ~/.dsh/.env / ~/.dsh/.credentials.yaml |

安装

1) 构建 bundle（把 vendored @deepseek-ai/cordis / dsh seam / ACP SDK 链接进 node_modules） cd
node scripts/build.mjs

2) 注册 Paseo provider（幂等，带备份；写入 $PASEO_HOME/config.json，默认 ~/.paseo）
node packages/dsh-paseo/scripts/install-paseo-provider.mjs

3) 安装 dsh 侧 profile（launcher 首次拉起时会自动做，也可手动；在 dsh 源码仓库根执行）
pnpm dsh plugin --profile paseo add /packages/dsh-paseo
pnpm dsh --profile paseo --dump-config | grep -A5 paseo-acp # 验证组合配置

4) 启动 / 重启 Paseo daemon paseo start --relay --listen 0.0.0.0:6767 --hostnames true

注意：paseo restart 不会保留 --listen 等启动参数（会退回 127.0.0.1，手机将无法直连）。重启请使用完整参数：paseo restart --relay --listen 0.0.0.0:6767 --hostnames true。

手机连接（可选）

1. 手机安装 Paseo app（App Store / Google Play 搜索 "Paseo"）。
2. 在 daemon 机器上生成配对码：paseo daemon pair（输出 QR / 配对链接）。
3. 手机打开配对链接（或扫码）完成配对，即可在手机上看到这台 host 并操作 dsh agent。

--relay 开启后手机与 daemon 无需同一网络（端到端加密走 relay.paseo.sh）；--listen 0.0.0.0:6767 供局域网直连。

快速开始

在 Paseo 里跑一个 dsh agent paseo run --provider dsh "实现用户认证"

或：GUI / 手机 app 里新建会话 → provider 选 "DSH (DeepSeek Harness)" → 输入任务

首次拉起时 launcher 会自动完成 dsh 侧 profile 安装，无需手工步骤。

使用

并行运行每开一个 dsh 会话 = 一个独立 dsh 进程。paseo ls 查看所有 agent，paseo attach 流式查看输出，paseo send "任务" 跟进，paseo stop 中断（实测：工具调用被 ABORTED，turn 以 aborted/user 收尾）。

模型选择

模型路由由 dsh 侧配置决定（单一事实源），与所连接的 dsh 服务保持一致：未显式覆盖时，Paseo agent 继承 dsh 服务的默认模型选择（agent-default-model 行 → $DSH_HOME/settings.yaml / Web Models 页，默认 deepseek-v4-flash）。
需要单独选模型时，Paseo 侧用派生 provider + 环境变量显式覆盖：

// ~/.paseo/config.json —— command 由 node packages/dsh-paseo/scripts/install-paseo-provider.mjs // 自动写入 launcher 绝对路径（Windows 为 [node, launcher]）；以下为示意 {
"agents": { "providers": {
"dsh": { "extends": "acp", "label": "DSH (DeepSeek Harness)",
"command": ["/absolute/path/to/dsh-paseo/packages/dsh-paseo/bin/dsh-paseo-launch.mjs"],
"params": { "supportsMcpServers": false } },
"dsh-pro": { "extends": "acp", "label": "DSH Pro",
"command": ["/absolute/path/to/dsh-paseo/packages/dsh-paseo/bin/dsh-paseo-launch.mjs"],
"params": { "supportsMcpServers": false },
"env": { "DSH_PASEO_MODEL": "deepseek-v4-pro" } }
} }
}

改完配置后重启 daemon（带完整参数）。实测：默认 dsh provider 的 agent 自报 deepseek-v4-flash（跟随服务默认）；env.DSH_PASEO_MODEL 显式覆盖后自报对应模型。

权限模式

| 模式 | 行为 |
| workspace-write（默认） | bash / 文件工具被沙箱围栏在工作区内；越界触发一次性权限询问（Paseo 界面 allow-once / reject，可开 Auto Accept） |
| danger-full-access | 完全访问（仅可信机器）；在 provider 的 env 里设 DSH_PERMISSION_MODE=danger-full-access |

会话与日志

- dsh 会话日志落在 $DSH_HOME/sessions/，可被 dsh 其他界面查询 / 回放。
- ACP 桥为 fresh-sessions-only（不支持 resume / load / list，与官方 dsh-acp 一致）。
- 桥只输出已提交的助手文本（agent_message_chunk），不逐 token 流式；reasoning / 工具活动留在 dsh 会话日志。

配置参考

Paseo provider 字段（~/.paseo/config.json → agents.providers.dsh）

| 字段 | 值 | 说明 |
| extends | "acp" | 泛型 ACP provider |
| command | launcher 绝对路径 | Paseo 每 agent spawn 一次 |
| params.supportsMcpServers | false | 必须为 false：dsh 桥拒绝非空 mcpServers（Paseo 默认会注入内部工具 MCP） |
| env | 任意 | 透传给 dsh 进程的环境变量（模型 / 权限选择等） |
| label / description | 字符串 | 界面显示名 |

环境变量（dsh 进程侧）

| 变量 | 默认 | 说明 |
| DSH_PASEO_MODEL | 继承 dsh 服务默认 | 显式覆盖桥创建的 agent 的模型（每进程求值）；未设置时跟随 dsh 服务默认（settings.yaml / Models 页） |
| DSH_PASEO_PROVIDER | 继承 dsh 服务默认 | 显式覆盖 llm 路由；可改 openai / anthropic 等（llm-pi-ai） |
| DSH_PERMISSION_MODE | workspace-write | 沙箱模式（同时决定 approval ask/never） |
| DSH_PASEO_DSH | 自动解析 | 显式指定 dsh 可执行文件路径 |
| DSH_HOME | ~/.dsh | dsh 主目录（profile / 会话 / 凭据） |
| DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL | 环境 / .env | 密钥与 API 端点（也可在 settings.yaml 配置）。当前版本 DEEPSEEK_BASE_URL 只从进程环境读取，.env 不再允许覆盖 |

dsh settings.yaml（热重载，无需重启）

$DSH_HOME/settings.yaml 的 llm-deepseek: 段可覆盖模型目录、默认模型、API 地址（baseURL）、思考级别等：

llm-deepseek:
baseURL: https://your-gateway.example/v1
reasoningEffort: max
models:
- id: deepseek-v4-flash
- id: deepseek-v4-pro

验证（端到端测试）

不经过 Paseo，直接验证 dsh 的 ACP 服务（隔离问题用）
node tools/acp-smoke-client.mjs # 走 launcher
node tools/acp-smoke-client.mjs --direct # 直接 spawn dsh（不走 launcher）

经过 Paseo 验证 paseo run --provider dsh "Reply with exactly: PONG" paseo logs # 应看到 [User] 提问 + PONG paseo ls # agent 状态 idle/completed

单测
node scripts/test.mjs

预期输出（实测）：smoke 打印 PASS: full ACP round-trip succeeded；paseo logs 显示 PONG。

目录结构

packages/dsh-paseo/ dsh 侧 Cordis bundle src/index.ts ACP 桥插件（改编自 @deepseek-ai/dsh-acp，BSD-3-Clause） src/codec.ts prompt 展平 / turn 结束 → stop reason 映射 bin/dsh-paseo-launch.mjs Paseo 的 spawn 入口（稳定拉起 dsh） cordis.patch.yml 注入层：paseo-acp 行 + persona 覆盖 packages/dsh-paseo/scripts/install-paseo-provider.mjs 注册 provider 到 Paseo config.json scripts/build.mjs 构建（链接依赖 + snapshot tsc + 产物校验） scripts/test.mjs 单测入口 paseo/provider.dsh.json provider 配置模板 tools/acp-smoke-client.mjs ACP 端到端冒烟客户端 docs/ 架构细节与排障文档

已知限制

- 每个 dsh agent 是一个完整 harness 进程（boot ~2-4s，内存 ~150-250MB）——进程级并行的固有成本，与 Paseo 对其他 agent 的处理一致。
- 不支持会话 resume / load / list（fresh sessions only）。
- 桥只输出已提交文本（不逐 token 流式）。
- Paseo UI 内模型选择器为 cosmetic：实际路由由 dsh 侧配置 / DSH_PASEO_MODEL 决定。
- 构建期依赖 dsh 快照（~/.dsh/source/current 或 DSH_MONOREPO）；换快照后需重跑 node scripts/build.mjs。

故障排查

见 docs/troubleshooting.md（症状速查表：provider 不显示、unavailable、MCP 报错、密钥缺失、模型不对、端口监听丢失等）。

License

MIT（ACP 桥改编自 @deepseek-ai/dsh-acp，BSD-3-Clause，见文件头与 LICENSE）。