7.4 常见问题
本节目标
把全书出现过的问题汇总成一张速查表，遇到坑先来这里翻。
安装与启动
问：npx 下载很慢或失败？
检查网络和代理。可以临时换 npm 国内镜像：
npm config set registry https://registry.npmmirror.com问：端口被占用怎么办？
换端口启动：
npx @deepseek-ai/dsh web --port 8080然后访问 http://127.0.0.1:8080/。
问：node -v 版本太老？
dsh 需要 Node.js 22 及以上。去官网下载最新 LTS 覆盖安装即可。
问：浏览器打不开界面？
以终端打印的地址为准。确认端口一致，终端没报错，再刷新一次。
配置模型
问：保存后模型不可用，提示密钥无效？
密钥可能没复制全（sk- 开头一整串），或刚创建还没生效。到 DeepSeek 平台重新创建一个试试。
问：提示余额不足？
DeepSeek 按量付费，新账号可能需要充值。到平台费用页查看。
问：想用别的模型？
设置 → 模型 → 添加提供方（内置 20 多家），或添加自定义提供方接 OpenAI 兼容服务（1.2 节）。
问：API 密钥泄露了怎么办？
到 DeepSeek 平台吊销重建，旧密钥立即失效。别把密钥截图发群里、提交到 git。
工作区与会话
问：添加了工作区但侧边栏没有？
确认选的是文件夹不是文件。同一目录只能添加一次。
问：删了工作区文件会丢吗？
不会。删除只是移除分组记录，文件与会话都保留。
问：会话太多找不到？
用侧边栏搜索框，按标题或内容搜。不用的会话归档（5.1 节）。
问：想回到昨天的对话继续干？
点侧边栏会话行，历史完整加载，直接续聊。
运行与结果
问：agent 跑偏了？
先设目标（4.5 节）再发任务，跑偏了直接说"停，回到目标上"。也可以用计划模式先审方案（4.6 节）。
问：agent 运行太久？
看工具调用树它卡在哪一步。长任务让它放后台（4.8 节），或者指令里限定范围。
问：agent 的回答不满意？
先换更强的模型（4.1 节）或调高推理等级，再检查指令是否足够具体。指令含糊，结果必然含糊。
问：agent 老是弹审批？
说明它想动工作区以外的东西。看清操作内容再决定：该放行的放行，不该放行的拒绝（4.4 节）。
界面与视图
问：对话视图和轨迹视图什么区别？
对话视图是人话版，轨迹视图是原始轮次记录（USER/CONTEXT/ASSISTANT/TOOL），排查细节用轨迹（4.10 节）。
问：界面是英文，想换中文？
设置 → 通用设置 → 语言 → 中文。
问：界面太亮/太暗？
设置 → 通用设置 → 外观，选浅色/深色/跟随系统（6.4 节）。
进阶
问：怎么在无人值守时跑任务？
用 headless 模式（7.1 节）：
export DEEPSEEK_API_KEY="你的密钥"
dsh --profile headless "任务"问：想限制 agent 的权限更严一点？
切 Read Only 模式（只读），或保持 Workspace Write 并在审批时拒绝超范围操作（7.2 节）。
问：想给 dsh 加新能力？
装插件或技能。插件在设置 → 插件查看，技能在会话里用 / 调用（4.3、6.2 节）。写自己的插件属于开发进阶，官方文档有专门教程。
结语
到这里，这本入门教程就全部讲完了。回顾一下你走过的路：
- Part 0：认识 dsh，装好环境，看懂界面
- Part 1-2：配好模型，圈好工作区
- Part 3：发出第一条指令，看懂工具调用
- Part 4：点亮会话里的全部进阶功能
- Part 5-6：管好会话，调成自己的形状
- Part 7：了解 CLI、安全机制，完成实战
从"dsh 是什么"到"用 dsh 完成真实任务"，你已经完成了从零到一的跨越。接下来，去你的项目里让 agent 帮你干活吧。遇到问题，回来翻这本教程。