常见问题与诊断清单

先记录当前版本与运行方式，再处理症状。不要在排障信息里粘贴 API Key、完整 .credentials.yaml 或 .env。

基础诊断命令

dsh --version
dsh web --help
dsh --profile web --dump-default-config
dsh --profile web --dump-config

源码环境再检查：

node --version
pnpm --version
pnpm run build

高频症状

症状	原因与修复
Web 输入框不可用	尚未选中工作区；点击「选择工作区」并选中目录。
默认端口冲突	改用 dsh web --port 3081。
缺少模块或前端产物	在仓库根运行 pnpm run build 后重试。
修改源码后仍显示旧界面	启动器不检查构建产物是否过期；重新 build。
MISSING_CREDENTIAL	在模型设置保存凭据，或提供配置所引用的环境变量。
INVALID_CREDENTIAL	修正保存值；错误本身不会显示密钥内容。
UNKNOWN_MODEL	选择已配置模型，或给自定义 Provider 添加该模型。
获取模型返回 401	检查凭据；不支持 GET /models 时改为手动录入。
凭据文件权限错误	运行 chmod 600 ~/.dsh/.credentials.yaml。
--host 0.0.0.0 被拒绝	当前 CLI 有意禁止全接口监听；使用 127.0.0.1。
Headless 立即报用法错误	必须提供非空任务。
Patch 后配置字段消失	Patch 替换目标条目的整个 config，不是深合并。

发布日志前的检查

--dump-config 不应输出明文 API Key，但仍可能包含本机路径、Provider ID 和环境结构。提交到公开 Issue 前先人工检查。

不要通过反向代理或修改源码来绕过 0.0.0.0 限制。当前 Web 载体没有认证层，公开监听会放大远程代码执行风险。