安装过程遇到「Tool call - Error: unknown tool "“ 问题」

[NullPointer8023]

DSH Web 工具问题完整排查总结

排查时间：2026-08-18
环境：macOS, Node.js v22.23.2, DSH v0.1.0-rc.7
最终状态：✅ 问题已解决

---

📑 目录

• 问题概述
• 第一阶段：启动失败
• 第二阶段：工具不可见
• 第三阶段：工具调用失败
• 第四阶段：问题解决
• 技术架构分析
• 关键文件位置
• 经验教训

---

问题概述

初始问题

npx @deepseek-ai/dsh web 命令无法正常启动，启动后工具不可见，工具调用时报错。

最终解决

通过切换模型解决了工具调用失败的问题。

---

第一阶段：启动失败

🚨 问题现象

npx @deepseek-ai/dsh web
# 命令无响应，没有任何输出

🔍 排查过程

1. 环境检查

node -v  # v22.23.2 ✅
npm -v   # 10.9.8 ✅
which dsh # /Users/ice/.nvm/versions/node/v22.23.2/bin/dsh ✅

2. 包安装检查

npm list -g @deepseek-ai/dsh
# 输出：@deepseek-ai/dsh@0.1.0-rc.7 ✅

3. Profile 配置检查

ls -la ~/.dsh/profiles/web/
# 发现 profile 目录存在但配置不完整

查看 ~/.dsh/profiles/web/package.json：

{
  "name": "web-profile",
  "version": "1.0.0",
  "private": true,
  "dependencies": {}
  // ❌ 缺少 dsh.profile.bundles 配置
}

🎯 根本原因

Web profile 的 package.json 缺少必要的 dsh.profile.bundles 配置，导致无法加载工具 bundle。

✅ 解决方案

删除损坏的 profile，让系统从模板重新初始化：

# 备份并删除旧的 profile
mv ~/.dsh/profiles/web ~/.dsh/profiles/web.backup

# 重新启动，系统会自动从模板初始化
dsh web --port 8080

重新启动后生成的正确配置：

{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {},
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app"
      ]
    }
  }
}

---

第二阶段：工具不可见

🚨 问题现象

DSH Web 启动成功，但在 Web UI 中找不到任何工具。

🔍 排查过程

1. 检查配置

dsh --profile web --dump-config | grep -E "^- id: tool-" -A 3

发现所有工具都被禁用：

- id: tool-bash
  name: '@deepseek-ai/dsh-tool-bash'
  disabled: true  # ❌
- id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'
  disabled: true  # ❌

2. 查看默认配置

检查 dsh-web-app 的 cordis.patch.yml：

cat ~/.nvm/versions/node/v22.23.2/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-web-app/cordis.patch.yml

发现 Web 模式默认禁用了大部分工具：

• tool-bash
• tool-pwsh
• tool-fs
• tool-fs-search
• tool-str-replace-editor
• tool-skill
• tool-subagent
• tool-workflow
• 等等...

🎯 根本原因

Web 模式出于安全考虑，默认禁用了大部分工具插件。这是设计决策，不是 bug。

✅ 解决方案

编辑 ~/.dsh/profiles/web/cordis.patch.yml，启用需要的工具：

# Your patch layer for this dsh profile
# 启用核心工具

- id: tool-bash
  disabled: false

- id: tool-fs
  disabled: false

- id: tool-fs-search
  disabled: false

- id: tool-str-replace-editor
  disabled: false

- id: tool-todo
  disabled: false

重启服务使配置生效：

pkill -f "dsh.*web"
dsh web --port 8080

---

第三阶段：工具调用失败

🚨 问题现象

工具已启用，但在 Web UI 中调用工具时报错：

Error: unknown tool ""

🔍 排查过程

1. 验证工具注册

dsh --profile web --dump-config | grep -E "^- id: tool-bash" -A 3

输出：

- id: tool-bash
  name: '@deepseek-ai/dsh-tool-bash'
  disabled: false  # ✅ 已启用

2. 深入分析会话日志

DSH 会将每个会话的记录保存到 ~/.dsh/sessions/ 目录：

# 找到最新的会话日志
ls -la ~/.dsh/sessions/--Users-ice-Documents-workspace-hy-cclient--/

# 解压并查看日志
zstd -d session.jsonl.zstd -o /tmp/session.jsonl
tail -100 /tmp/session.jsonl

3. 分析日志内容

从日志中发现问题：

第 32 行 - 模型正确生成工具调用：

{
  "type": "tool-call-delta",
  "index": 1,
  "id": "call_89f8cc603f8347d4987e5be4",
  "name": "run_code",  // ✅ name 正确
  "argumentsDelta": ""
}

第 33 行 - 后续 delta 中 name 丢失：

{
  "type": "tool-call-delta",
  "index": 1,
  "id": "",
  "name": "",  // ❌ name 为空
  "argumentsDelta": "{"
}

第 70 行 - 最终组装的工具调用：

{
  "type": "tool-call",
  "id": "",
  "name": "",  // ❌ name 为空
  "arguments": "{...}"
}

第 75 行 - 导致错误：

{
  "type": "tool-result",
  "content": [
    {
      "type": "text",
      "text": "Error: unknown tool \"\""
    }
  ],
  "isError": true
}

🎯 根本原因

DSH 流式工具调用组装 bug

模型（DeepSeek v4-pro）正确地在第一个 delta 中提供了 name:"run_code"，但 DSH 的 ConversationNodeAssembler 在处理后续 delta 时没有正确保留 name 字段，导致最终组装的工具调用 name 为空字符串。

这是一个代码层面的 bug，位于 DSH 的流式组装逻辑中。

---

第四阶段：问题解决

✅ 解决方案

切换模型。

编辑 ~/.dsh/settings.yaml：

agent-default-model:
  provider: deepseek-official
  model: deepseek-v3  # 切换到其他模型
  reasoningEffort: high

重启 DSH Web 服务后，工具调用正常工作！

💡 为什么有效

不同模型的流式输出格式可能略有差异。其他模型的工具调用格式能被 DSH 正确解析，不会触发组装 bug。

---

技术架构分析

DSH 工具系统架构

┌─────────────────────────────────────────────────────────┐
│                    用户配置层                            │
│  ~/.dsh/profiles/web/cordis.patch.yml                  │
│  (启用/禁用工具)                                        │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│              Cordis 插件加载器                           │
│  - 读取 cordis.patch.yml                               │
│  - 识别需要加载的插件                                    │
│  - 按顺序加载插件                                        │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│              插件动态注册                                │
│  每个工具插件导出:                                       │
│  - name: "tool-bash"                                   │
│  - inject: ["tools", "shell", ...]                     │
│  - apply(ctx, config):                                 │
│      ctx.tools.register(defineTool({                   │
│        name: "bash",                                   │
│        description: "...",                             │
│        parameters: {...},                              │
│        execute: async (args, exec) => {...}            │
│      }))                                               │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│              ToolRuntime (工具注册表)                    │
│  - 维护所有已注册的工具                                   │
│  - 提供工具查找: get(name, scope)                       │
│  - 提供工具执行: execute(exec)                          │
│  - 提供工具模式: schemas(scope)                         │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│              模型调用工具                                │
│  1. 模型生成工具调用 (流式 delta)                        │
│  2. ConversationNodeAssembler 组装完整调用               │
│  3. ToolRuntime.execute() 执行工具                       │
│  4. 返回结果给模型                                       │
└─────────────────────────────────────────────────────────┘

两层名称系统

1. 插件 ID："tool-bash" - 用于配置文件中的 id 字段
2. 工具名称："bash" - 模型实际调用时使用的名称

流式工具调用组装流程

模型输出 delta 流
    │
    ├─ delta 1: name="run_code", arguments=""
    ├─ delta 2: name="", arguments="{"
    ├─ delta 3: name="", arguments=""code": "..."
    └─ ...
    │
    ▼
ConversationNodeAssembler
    │
    ├─ 合并所有 delta
    ├─ 保留第一个 delta 的 name
    └─ 拼接所有 arguments
    │
    ▼
完整的 tool-call
    │
    └─ {name: "run_code", arguments: "{...}"}

---

关键文件位置

配置文件

~/.dsh/
├── profiles/
│   ├── web/
│   │   ├── package.json              # Profile 配置（包含 bundles）
│   │   ├── cordis.patch.yml          # 用户工具配置（启用/禁用）
│   │   ├── cordis.yml                # 自动生成的根配置
│   │   └── pnpm-workspace.yaml       # pnpm 工作区配置
│   └── node_modules/                 # 共享依赖
├── settings.yaml                     # 全局设置（模型配置）
├── .credentials.yaml                 # API 密钥
└── sessions/                         # 会话日志
    └── <workspace-path>/
        └── session-<id>/
            └── session.jsonl.zstd    # 压缩的会话日志

DSH 安装位置

/Users/ice/.nvm/versions/node/v22.23.2/lib/node_modules/@deepseek-ai/
└── dsh/
    ├── lib/
    │   ├── bin.js                    # 主入口
    │   ├── profile-boot-*.js         # Profile 启动逻辑
    │   └── dump-config-*.js          # 配置导出
    └── node_modules/@deepseek-ai/
        ├── dsh-base/                 # 基础 bundle
        ├── dsh-web-app/              # Web 应用 bundle
        ├── dsh-tool-bash/            # Bash 工具
        ├── dsh-tool-fs/              # 文件系统工具
        └── ...                       # 其他工具

常用命令

# 查看配置
dsh --profile web --dump-config

# 查看帮助
dsh --help
dsh web --help

# 启动服务
dsh web --port 8080

# 查看会话日志
ls ~/.dsh/sessions/
zstd -d ~/.dsh/sessions/<path>/session.jsonl.zstd -o /tmp/session.jsonl
cat /tmp/session.jsonl | jq .

---

经验教训

1. 配置问题排查

• ✅ 检查 profile 是否正确初始化
• ✅ 查看 package.json 中的 dsh.profile.bundles
• ✅ 必要时删除 profile 让系统重新初始化

2. 工具可见性问题

• ✅ 检查 cordis.patch.yml 中的 disabled 设置
• ✅ 理解 Web 模式的安全设计（默认禁用工具）
• ✅ 使用 dsh --dump-config 验证配置

3. 工具调用失败问题

• ✅ 查看会话日志 session.jsonl.zstd
• ✅ 分析流式 delta 的组装过程
• ✅ 检查模型输出格式是否与 DSH 兼容
• ✅ 尝试切换模型排除兼容性问题

4. 调试技巧

• ✅ 使用 dsh --dump-config 查看完整配置
• ✅ 解压并分析会话日志
• ✅ 使用 grep 快速定位问题
• ✅ 强制刷新浏览器（Cmd+Shift+R）清除缓存

5. 架构理解

• ✅ DSH 使用 Cordis 插件系统
• ✅ 工具是动态注册的，不是静态配置
• ✅ 流式组装可能有 bug，需要检查日志
• ✅ 不同模型可能有不同的输出格式

---

相关资源

官方资源

• GitHub: https://github.com/deepseek-ai/deepseek-harness
• NPM: https://www.npmjs.com/package/@deepseek-ai/dsh

配置文件参考

• Profile 配置: ~/.dsh/profiles/web/package.json
• 工具配置: ~/.dsh/profiles/web/cordis.patch.yml
• 全局设置: ~/.dsh/settings.yaml

日志分析

• 会话日志: ~/.dsh/sessions/*/session.jsonl.zstd
• 解压工具: zstd -d file.zstd -o file.jsonl
• JSON 格式化: cat file.jsonl | jq .

---

附录：常见问题

Q1: 如何查看所有可用的工具？

dsh --profile web --dump-config | grep "^- id: tool-"

Q2: 如何启用/禁用特定工具？

编辑 ~/.dsh/profiles/web/cordis.patch.yml：

- id: tool-bash
  disabled: false  # 启用
- id: tool-pwsh
  disabled: true   # 禁用

Q3: 如何查看会话日志？

# 找到最新的会话
ls -lt ~/.dsh/sessions/*/session-*/session.jsonl.zstd | head -1

# 解压并查看
zstd -d session.jsonl.zstd -c | jq .

Q4: 如何切换模型？

编辑 ~/.dsh/settings.yaml：

agent-default-model:
  provider: deepseek-official
  model: deepseek-v3  # 或其他模型

Q5: 工具调用失败如何排查？

1. 检查工具是否启用：dsh --dump-config | grep tool-bash
2. 查看会话日志：分析 session.jsonl.zstd
3. 检查模型输出：查看 delta 流是否正确
4. 尝试切换模型：排除兼容性问题

---

总结

通过系统性的排查，我们解决了 DSH Web 的三个层次的问题：

1. 启动失败 → 重新初始化 profile
2. 工具不可见 → 修改配置启用工具
3. 工具调用失败 → 切换模型解决流式组装 bug

整个过程深入理解了 DSH 的架构设计，包括 Cordis 插件系统、工具动态注册机制、流式工具调用组装等核心技术。

最终状态：✅ DSH Web 正常运行，所有工具可用！🎊

---

文档生成时间：2026-08-18
环境：macOS, Node.js v22.23.2, DSH v0.1.0-rc.7

[clwu1994]

补充一个代码层面的定位：切换模型可以绕过这个问题，但根因是 DeepSeek 流式 tool-call delta 的兼容性处理。

我在当前源码中复现了：第一个 delta 带有 function.name: "run_code"，后续 delta 带有 function.name: ""。packages/llm/llm-deepseek/src/translate.ts 原来的逻辑会用空字符串覆盖已保存的工具名，最后组装成 name: ""，触发 Error: unknown tool ""。

修复方式是仅在工具名非空时更新：

if (call.function?.name) block.name = call.function.name

我还补充了回归测试，验证后续空名称不会清除首次收到的有效工具名。相关 llm-deepseek 测试、TypeScript 编译和 lint 均已通过。也就是说，切换模型是 workaround，保留首次有效工具名才是代码层面的修复。