DeepSeek Harness 常见问题 FAQ

按使用阶段整理的高频问题。每个问题给“一句话结论 + 展开”，找不到答案时跳到排错指南。

安装与启动

Q："npx @deepseek-ai/dsh web" 下载很慢或失败？
网络问题。换 npm 镜像源重试；或改用源码安装（git clone → pnpm install → build），详见安装与首次启动。

Q：端口 3080 被占了？
启动命令带应用参数换端口：dsh --profile web --port 8080（flag 顺序规则见 CLI 命令参考）。

Q：Web UI 打开了但输入框是灰的？
没选工作区。点“选择工作区”选中目录，输入框才可用（机制见第一个任务）。

Q：需要什么环境？
Web UI 只需 Node.js；Python SDK 需 Python 3.10+ 与 Git（清单见环境要求）。

Q：保存 API 密钥后为什么看不到了？
刻意设计——密钥只写，界面只显示脱敏描述符。明文在 ~/.dsh/.credentials.yaml（见模型与凭据）。

Q：报 MISSING_CREDENTIAL？
密钥没配好：到模型页保存，或确认被引用的环境变量存在。

Q：能接公司的 OpenAI 兼容网关吗？
能。添加自定义提供方，填 Provider ID、基础 URL、协议、凭据、模型。

Q：能传图片给模型吗？
自定义模型的图片能力要显式声明（input: [text, image]）；DeepSeek 官方 chat 路由是纯文本。

Q：agent 做到一半停下了？
大概率是某步触发了审批弹窗等你确认，或权限不够被拒（见沙箱与安全）。

Q：关掉页面任务会丢吗？
不会。会话持久化在 ~/.dsh/sessions，可恢复继续（见会话与记忆）。

Q：怎么让 agent 每次都遵守我的规则？
写进 AGENTS.md（项目级或全局），自动注入每个会话（见 AGENTS.md）。

Q：agent 改了不该改的文件？
先用隔离测试目录练手；重要项目在 AGENTS.md 写禁止规则；用权限模式限制写入范围。

Q：任务太多 agent 上下文爆了？
会话自动压缩早期内容；大批量任务用工作流扇出子代理。

Q：改了配置为什么不生效？
DSH 配置是分层叠加的——确认改对了文件与层级，用 dsh --dump-config 验证（见配置层与 patch）。

Q：只改一个字段，别的字段回默认了？
patch 是替换整行不是合并——重述该行全部字段。

Q：想限制 agent 只读不写/只读不跑命令？
用自定义 Agent Preset 控制工具集（见创建 Agent Preset）。

Q：能给 agent 加新能力吗？
三种方式：写 Skill（零代码）、写插件（带代码）、接 MCP 服务器（现成生态），分别见编写 Skill、插件开发、MCP 集成。

Q：DSH 会突然不兼容吗？
会。当前是开发者预览期，官方明示未来有破坏性变更——关注 GitHub Release 再升级（见什么是 DSH）。