L08 · 起步：安装与 Web UI

一、两种启动方式Two Ways to Start

方式 A：免安装体验（推荐第一次用）

npx @deepseek-ai/dsh web

npx = 临时下载、运行、不常驻安装，像试驾：车开走试试，不用先买。启动后自动打开 http://127.0.0.1:3080。

方式 B：从源码运行（后续开发插件必须用这个）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build
pnpm dsh web

场景	用哪个
只是想用、想体验	方式 A
开发插件 / 读源码 / 改代码	方式 B（本课程后续练习都基于 B）
SSH 服务器上跑，不想自动开浏览器	加 `--no-open`

二、配置模型（第一次必做）Configure a Model

打开 Settings → Models（设置 → 模型），在 DeepSeek 卡片填入 API key（去 platform.deepseek.com 申请），保存。
立即生效，不用重启——模型改动下一次请求就生效。

密钥安全设计：key 是只写的——保存后界面只显示打码的描述符，永不回显原文。密钥本体存 $DSH_HOME/.credentials.yaml（DSH_HOME 是 dsh 的主目录），设置里只保留对它的"引用"。

配置后模型选择器出现可用模型，选中的自动成为新会话默认；已发过请求的会话则记住自己日志里记录的模型，不被全局默认影响——又是"日志即事实"。

三、选择工作区Choose a Workspace

workspace（工作区）= 授权给智能体操作的目录。dsh 进程默认用启动时的目录，但 Web UI 必须先添加并选中一个 workspace 才能新建会话（安全默认：不点头，不让碰）。点 Choose workspace → 添加你启动 dsh 的项目目录 → 选中它。

四、第一个任务First Task

总结这个仓库，并指出它的主要包。

发出后观察 Web UI：流式输出（每个片段是一条 assistant/chunk 入账事件，见 L07）、工具活动卡片（读文件等）、敏感操作的审批弹窗。智能体在工作区能读写文件、运行命令、委派子任务、维护计划，每一步都在日志里，随时可回看。

五、接其他模型（进阶）Other Providers

目录里的现成提供商

Add provider → 选 Anthropic / OpenAI 等目录提供商 → 填 API key。目录自带端点、协议和模型清单，像应用商店的"官方应用"，信息都配好了。

自定义提供商（公司网关 / 自建服务 / OpenAI 兼容端点）

Add a custom provider，提供：小写 Provider ID（永久的，改名=新建+删旧）、base URL、API 协议、凭据、至少一个模型；可点 Fetch available models 从端点拉取清单。

网关不兼容时的两个"兼容开关"

常见坑：很多 OpenAI 兼容网关"地址通、key 对，但每个请求都被拒"。两个原因占大头，改 $DSH_HOME/settings.yaml 里路由的 compat 即可：

llm-pi-ai:
  providers:
    my-gateway:
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false   # 推理模型的系统提示别用 developer 角色发
        maxTokensField: max_tokens     # 输出上限字段用 max_tokens 而非 max_completion_tokens

让模型收图片

手动添加的模型默认纯文本；视觉模型要在 settings.yaml 给它声明 input: [text, image]。报错"图片被拒"先查这里。

六、排错速查Troubleshooting

症状	解法
`MISSING_CREDENTIAL`	在 Models 页存好 key，或配置所引用的环境变量
`UNKNOWN_MODEL`	选一个已配置的模型，或往自定义提供商里补这个模型
拉模型清单 401	key 不对；或该端点没有 `GET /models` 接口——改为手动填模型
key 和 URL 都对但请求全被拒	网关请求形状与 OpenAI 不同 → 上文的 compat 两开关
只有推理模型失败	系统提示被发成 developer 角色被网关拒 → `supportsDeveloperRole: false`

workspace 工作区

授权智能体操作的目录，不选中不让干活。

DSH_HOME

dsh 主目录：密钥、设置、profile 都住这。

catalog provider

目录内置的提供商，端点协议全配好。

compat 开关

修正网关与 OpenAI 请求形状差异的配置。

✏️ 动手练习

按方式 B 跑起来，配好 DeepSeek key，选中工作区。
发送"总结这个仓库，并指出它的主要包"，观察流式输出、工具卡片、（若触发）审批弹窗。
进阶：公司有 OpenAI 兼容网关的话，加一个 custom provider 并用 compat 开关调通它。

预期结果：能独立完成"启动 → 配 key → 选工作区 → 跑任务"全流程，并理解每步的安全设计。

📝 自测（点击展开答案）

1. 改了模型配置要重启吗？已发过消息的会话会跟着换模型吗？

不用重启，下一次请求即生效。已发过请求的会话保留自己日志里记录的模型——会话级模型选择也是"日志即事实"。

2. 为什么保存后的 API key 界面上看不到原文？

key 只写：界面只显示打码描述符，本体存 $DSH_HOME/.credentials.yaml，设置里只留引用——防界面/截图泄漏。

3. 新装的 Web UI 为什么必须先选 workspace？

安全默认：不给智能体指定可操作的目录就不允许开会话。启动目录只是默认位置，界面上仍要显式选中。

4. 网关 key、URL 全对但请求全挂，第一个该试什么？

compat 两开关：supportsDeveloperRole: false（多数网关拒 developer 角色系统提示）+ maxTokensField: max_tokens（很多服务器只认老字段名）。

权威出处：user/guide/index.zh.md · user/guide/providers.zh.md（本课主要依据） · README.zh.md