dsh web 启动成功,页面也能打开,但一发请求就不通。 这类问题中,「启动」和「可用」是两件事,中间至少隔着四个独立判断。
先把最容易混淆的一点说清楚:
Profile 是一组有名称的插件配置,不是模型名称,也不是权限预设。
官方参考说明 profile 保存的是组合包列表和用户补丁;CLI 参考说明内置启动方式和输入通道。因此,「我选了 web,为什么模型不能用」这个问题把两件事混在了一起:选择 profile 决定的是使用哪套插件组合、走哪个接口,模型和凭据则需要另外配置。
一、按接口选择五个内置 profile
| 需求 | Profile | 接口和边界 |
|---|---|---|
| 在浏览器里交互 | web |
Web 应用与浏览器客户端 |
| 脚本执行一次任务 | headless |
位置参数传任务,标准输出给最终文本 |
| SDK 客户端集成 | sdk |
标准输入输出承载 JSON-RPC |
| ACP 客户端集成 | acp |
标准输入输出承载 ACP |
| 更小的 SDK 组合 | sdk-minimal |
同为 JSON-RPC,能力和权限不同 |
选择时看由谁发起交互:是人通过浏览器操作、脚本执行一次任务,还是协议客户端发起调用。
sdk-minimal 不是 sdk 的别名
表中这一项需要特别留意。CLI 参考说明,sdk-minimal 使用独立的组合包,并且:
- 省略文本文件系统工具;
- 省略指令发现;
- 省略 SQLite;
- 配置树固定为
danger-full-access; - 不挂载审批或权限设置服务。
也就是说,它「同为 JSON-RPC,但能力和权限都不同」。名字里的 minimal 容易让人以为它只是「更轻量的同一个东西」,实际上少掉的是能力,多出来的是权限,选择前需要把这两点都核对清楚。
二、dsh web 是简写,不是另一套配置
简写的规则
dsh web就是dsh --profile web,两种写法选择的是同一个名称;- 简写名称必须紧跟
dsh; plugin在这个位置表示插件管理命令,所以名为plugin的 profile 只能用--profile选择;- 简写之后再给一个
--profile会被拒绝。
参数怎么分流
启动器先处理自己的参数;遇到第一个不认识的参数后,会把剩余参数原样交给应用。
例如 dsh --profile web --port 8080:--port 8080 会交给 Web 应用。因此,使用 --patch 这类启动器参数时,要放在应用参数之前。
下面两种查帮助的写法也要区分:
dsh --help——查看启动器帮助;dsh --profile web --help——查看 Web 应用帮助,且不会启动应用。
两种写法不会产生两套配置
这一点能省去不少排查:自定义 profile 即使包含 Web 组合包,也可能因为组合包列表和补丁不同而表现不同。所以,不能只凭名称判断 profile 里到底有什么。同名不等于同内容。
三、首次启动创建了什么
首次使用时,web、headless、sdk、sdk-minimal 和 acp 会根据随包模板自动初始化。
- 选中的 profile 位于
$DSH_HOME/profiles/<name>; - manifest 记录组合包层;
- profile 自己的
cordis.patch.yml保存用户覆盖; - 随包组合包从当前 dsh 安装解析,启动器不会为运行时解析创建回退链接。
两个容易踩的边界
- 普通启动时,如果自定义 profile 不存在,会报错并提示插件管理途径,不会自动把它当作
web。因此,输入--profile foo后不会静默进入 web;如果看到报错,就说明没有 fallback。 --from-default-profile会用新模板替换自定义目标;成功替换时,旧依赖和用户补丁也会被删除。
第 2 条是这里唯一有破坏性的操作。普通首次启动不需要使用这个选项;如果确实要用,请先阅读参考并保存必要内容。
四、五步判断「到底通不通」
- 确认交互方:是人、单次脚本,还是协议客户端。
- 按对应语法启动:浏览器场景用
dsh web;单次任务可用dsh --profile headless "run the tests"。 - 为该环境配置模型和凭据。选择 profile 不会验证密钥,这是「启动了但不通」最常见的原因。模型相关配置见配置模型与提供商。
- 用小任务验证接口。SDK 和 ACP 需要通过相应的协议客户端连接,不要把普通任务文本直接写进协议流。
- 结果异常时,记录 profile 和启动目录。基于 base 的 profile 默认以运行命令的目录作为工作区根目录。
第 5 条可以结合启动前先选工作区理解:工作区根目录由启动位置决定,而不是由「安装了哪个插件」决定。
五、配置变更什么时候才会生效
配置层级顺序如下:
profile 所列组合包
→ profile 补丁
→ home 补丁
→ 命令行补丁
后面的层可以替换整行配置。
这里有一个模板级的差异:
- Web 模板包含实时补丁能力;
- 随包的 headless、SDK 和 ACP 模板在启动时应用补丁。
而组合包成员发生变化需要重启。完整的顺序和替换语义见配置层优先级。
三个「不一定」要记住
- 不同 profile 可以挂载不同插件,某个界面里的设置不一定存在于另一个 profile;
- profile 补丁不是所有 profile 共用的 home 补丁;
- 但 home 偏好可能影响多个 profile。
插件设置可能要到下一个请求或重启时才生效,具体以对应文档为准。
六、团队交接时该记录什么
只记录 profile 名称不够,还要说明由谁使用哪个接口:
- 浏览器流程:Web UI 运行在哪台主机、谁可以访问;
- headless 流程:工作目录是什么、输出由谁接收;
- SDK / ACP 集成:哪个客户端负责协议流。
例如,开发者可以先在本机仓库中选择 web、配置好模型,再通过浏览器观察结果;CI 中的有限任务可以选择 headless,并把退出状态和文本分别保存。
两种选择都不会替对方决定模型提供商——它们各自仍需要有效的路由和凭据。
如果程序需要持续的多轮协议交互,应评估 SDK 接口,不要把单次任务输出硬当成协议服务。
七、别被「同名 profile」骗了
profile 首次从模板初始化后,可能积累本地修改。排查时要分清三件事:
- 随包模板;
- 磁盘上现有的 profile;
- 某次启动最终组合出来的配置树。
升级应用并不意味着已有 profile 一定恢复成原始模板。 正确的排查顺序是:先确认选中的名称,再检查组合包列表与补丁,最后再决定是否修改;不要为了查看模板内容而直接覆盖已有目录。
两台机器即使使用同名 profile,也可能安装了不同插件,或存在本机覆盖。比较问题时,先固定版本和配置来源,避免把「名称相同」误认为「运行内容相同」。
交接时还可以说明:进程如何停止、日志由谁保管、分享前需要删除哪些信息。新维护者据此更容易区分浏览器连接问题、模型请求失败和权限问题。这三类现象看起来都是「用不了」,但对应的排查位置完全不同。
八、一份可复用的验收记录
记录以下五项即可:
- 启动命令;
- 所在目录;
- 选择的模型;
- 测试输入;
- 观察到的结果。
分别验证三条路径:
- Web:先确认页面连接的是预期服务,再发起一次小型模型请求。只看到页面不代表模型可用。
- headless:确认调用方分别收到最终文本与退出状态。
- 协议客户端:确认客户端能识别所选传输,并能处理连接错误。
启动成功只能证明这次组合启动了,不能证明每个模型、工具或外部集成都已准备好。
九、端口和帮助这两个常见收尾
- 改监听地址与端口见设置 Web 监听地址和端口;
- 不想在启动时自动打开浏览器,见启动 Web UI 但不打开浏览器;
- 单次任务的完整写法见headless 跑一次任务;
- 从 SDK 起步见用 Python SDK 跑第一个任务。
这些都是确定要用哪种方式之后再处理的事项。先确定交互方式,再调整参数;否则可能会在本来就不合适的 profile 上花很多时间。
十、边界说明
- Profile 不是模型名,也不是权限预设;选择 profile 不会验证密钥。
sdk-minimal不是sdk的别名:能力更少,权限固定为danger-full-access且不挂载审批服务。- 同名 profile 不代表同内容,两台机器、两个环境都可能不同。
--from-default-profile会删除旧依赖和用户补丁,不是无害的查看操作。- 升级应用不会把已有 profile 恢复成模板。
- 以上为操作建议,不是额外的 CLI 承诺;具体行为仍以安装版本和实际组合的插件文档为准。
十一、相关术语
- Profile:一组有名称的插件配置,保存组合包列表与用户补丁。
- 组合包(bundle):由 profile 声明、从当前 dsh 安装解析的插件层。
- 补丁(patch):覆盖组合配置的层,按 profile → home → 命令行顺序应用。
- 启动器:处理自己的参数后,把剩余参数交给应用的那一层。
相关阅读
本文依据 DeepSeek Harness 官方参考总览与 CLI 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog