---
title: "故障排查"
description: "常见问题、诊断与解决方案"
---

### 你将学到什么

Verdent for VS Code 的常见故障排查流程、诊断步骤以及已知问题的应对方法。

<Info>
  针对用户反馈最多的问题的详细排查指南，正在根据支持数据进行整理。本页提供通用诊断流程。如遇此处未涵盖的具体问题，请联系 [support@verdent.ai](mailto:support@verdent.ai)。
</Info>

---

## 快速诊断

<Tabs>
  <Tab title="服务错误（最常见）">
    ### “Service is experiencing high traffic. Please try again later!”

    **这是用户遇到的第一大常见错误**，表示 Verdent 服务暂时过载。

    **何时出现：**

    - 在使用高峰期
    - 后端服务承受高负载时
    - 临时性的服务降级

    **恢复步骤（按顺序执行）：**

    <Steps>
      <Step title="回滚消息" stepNumber={1}>
        如果错误持续存在，回滚最近的一条消息：

        - 点击聊天界面中的回滚/撤销按钮
        - 稍等片刻后重新提交你的请求
      </Step>
      <Step title="开启新会话" stepNumber={2}>
        如果错误仍然出现，开启一个全新的会话：

        - 点击顶部栏中的 “+”（新建会话）按钮
        - 这会清除上下文和工具授权
        - 在干净的会话中重新提交你的请求
      </Step>
      <Step title="等待并重试" stepNumber={3}>
        等待 30-60 秒后再次尝试你的请求。大多数服务问题会很快恢复。
      </Step>
    </Steps>
    <Warning>
      如果该问题在多个会话中持续超过 5-10 分钟，请查看 [Verdent 状态页面](https://verdent.ai/status) 或联系 [support@verdent.ai](mailto:support@verdent.ai)。
    </Warning>
  </Tab>
  <Tab title="安装与设置">
    ### 安装与设置问题

    **系统要求：**

    - **VS Code 版本：** 1.90.0 或更高（必需）
    - **网络连接：** 需要有效的网络连接
    - **订阅：** 有效的 Verdent 订阅

    **基本诊断清单：**

    1. **确认 VS Code 版本：** Help → About（必须为 1.90.0+）
    2. **检查网络连接：** Verdent 需要有效的网络连接
    3. **确认订阅：** 确保 Verdent 订阅处于有效状态
    4. **重启 VS Code：** 在安装或配置更改后
    5. **检查扩展状态：** View → Extensions → Verdent（应显示 “Enabled”）

    **全新重装流程：**

    <Steps>
      <Step title="卸载 Verdent">
        View → Extensions → Verdent → Uninstall
      </Step>
      <Step title="重启 VS Code">
        完全关闭并重新打开 VS Code
      </Step>
      <Step title="重新安装 Verdent">
        View → Extensions → 搜索 “Verdent” → Install
      </Step>
    </Steps>
    **查看日志：**

    - 打开输出面板：View → Output
    - 从下拉菜单中选择 “Verdent”
    - 查找错误信息或堆栈跟踪

    <Info>
      大多数安装问题通过简单地重新加载 VS Code 或全新重装即可解决。如果问题仍然存在，请检查日志并将日志详情提供给支持团队。
    </Info>
  </Tab>
  <Tab title="认证与账户">
    ### 无法登录 Verdent for VS Code

    **最常见的原因：** 代理配置问题

    **解决方法：**

    <Steps>
      <Step title="打开 VS Code 设置">
        按 `Cmd+,`（macOS）或 `Ctrl+,`（Windows/Linux）
      </Step>
      <Step title="搜索代理设置">
        在设置搜索栏中搜索 “useProxy” 或 “verdent.enableProxy”
      </Step>
      <Step title="切换代理状态">
        切换代理设置的开/关（与当前状态相反）
      </Step>
      <Step title="重试登录">
        再次尝试登录 Verdent
      </Step>
    </Steps>
    <Info>
      如果你处于企业防火墙之后，可能需要启用代理设置。如果你使用的是家庭网络，请尝试关闭它。
    </Info>
    ---

    ### 未收到免费试用积分

    **错误：** 未收到免费试用积分或免费试用访问被拒绝

    **原因：** 注册时检测到违反服务条款的行为

    **解决方法：** 请联系 [support@verdent.ai](mailto:support@verdent.ai) 以获取关于免费试用访问的帮助。支持团队将审查你的账户并协助解决问题。

    ---

    ### 注册失败

    **错误：** 账户注册被拒绝或受到限制

    **原因：** 注册违反了 Verdent 的服务条款，导致访问受限

    **解决方法：** 请联系 [support@verdent.ai](mailto:support@verdent.ai) 寻求帮助。支持团队可以审查你的注册并提供解决问题的指导。

    ---

    ### 缺少模型（Claude、GPT、Gemini）

    **问题：** 在模型选择中找不到 Claude、GPT 或 Gemini 模型

    **原因：** 模型提供商基于地区的限制

    **说明：** 一些 AI 模型提供商设有地区限制，导致某些模型在特定地理位置无法使用。出现这种情况时：

    - 受限模型不会出现在你的模型选择菜单中
    - 你仍可不受影响地使用所有其他可用模型
    - 对你的订阅或积分没有影响

    **查看可用模型：** 访问 https://www.verdent.ai/regions 查看你所在地区可用的模型

    <Note>
      地区限制由 AI 模型提供商（Anthropic、OpenAI、Google）设定，而非 Verdent。Verdent 无法绕过这些限制。
    </Note>
  </Tab>
  <Tab title="性能">
    ### 性能问题

    **症状：**

    - 响应缓慢
    - 上下文窗口已满错误
    - 工具执行超时

    **常见原因与修复方法：**

    | 问题             | 原因                        | 解决方法                                                              |
    | ----------------- | ---------------------------- | --------------------------------------------------------------------- |
    | 响应缓慢    | 读取大文件       | 使用行范围：`file_read("file.js", start_line=100, max_lines=50)` |
    | 上下文已满      | 对话历史过长    | 委派给子智能体或开启新对话                       |
    | 工具超时     | bash 命令运行时间过长   | 设置明确的超时或拆分为更小的命令                   |
    | 内存占用高 | 并行操作过多 | 限制并发工具执行数量                                      |

    <Tip>
      将探索性任务委派给 @Explorer 子智能体，以保留主上下文。
    </Tip>
  </Tab>
  <Tab title="图片错误">
    ### 图片相关错误信息

    **常见图片处理错误的快速参考：**

    | 错误信息                  | 原因                                                                    | 解决方法                                                      |
    | ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
    | **Unsupported Image Type**     | 仅支持 JPEG、PNG、GIF 或 WebP 图片                        | 回滚并将图片类型更改为受支持的格式     |
    | **Image Dimensions Too Large** | 图片宽度或高度不能超过 8000 像素                          | 回滚并将图片尺寸调整为 8000×8000 或更小 |
    | **Input Too Long**             | 输入超出了模型允许的最大长度                     | 简化你的输入或缩小图片尺寸                       |
    | **File Too Large**             | 图片大小不能超过 5 MB                                            | 回滚并发送压缩后的图片（最大 5 MB）              |
    | **Unreadable Image**           | 无法处理该图片，文件可能已损坏或格式不受支持 | 回滚并替换为有效的图片文件                     |
  </Tab>
</Tabs>

---

## 工具相关问题

<Tabs>
  <Tab title="file_edit 失败">
    ### file_edit 失败

    **错误：** “Failed to find exact match”

    **原因：**

    - 自上次 file_read 后文本已更改
    - 空白字符差异（制表符与空格）
    - 字符串在文件中不唯一

    **解决方法：**

    ```bash
    # 1. Read file again to get current state
    file_read("file.js")

    # 2. Use larger context string for uniqueness
    file_edit("file.js",
      old_string="function foo() {\n  return 42;\n}",
      new_string="...")

    # 3. For multiple identical strings, use replace_all
    file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
    ```

    <Warning>
      始终在编辑前立即读取文件，以确保你掌握的是当前状态。
    </Warning>
  </Tab>
  <Tab title="bash 失败">
    ### bash 命令失败

    **错误：** 命令超时或执行失败

    **最大超时：** 120 秒（2 分钟，硬性限制）

    **解决方法：** 将长命令拆分为更小的操作：

    ```bash
    # Instead of one long command, break into steps
    bash("step1")  # Completes in < 2min
    bash("step2")  # Completes in < 2min
    ```

    **命令未找到：**

    - 检查命令是否存在：`bash("which command-name")`
    - 确保路径正确或先激活环境
    - 对可执行文件使用完整路径

    **权限错误：**

    - 命令以用户权限执行
    - 仅在必要时并在手动接受模式下使用 `sudo`
    - 检查文件/目录权限
  </Tab>
  <Tab title="搜索问题">
    ### 搜索返回无结果

    **问题：** grep_file 或 glob 找不到预期的文件

    **检查模式语法：**

    ```bash
    # Wrong
    grep_file("*.ts")  # Missing ** for recursive

    # Correct
    grep_file("**/*.ts")  # Recursive search
    ```

    **检查排除项：**

    ```bash
    # Ensure not accidentally excluding target files
    glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
    ```

    **大小写敏感性：**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

---

## 子智能体与配置问题

<Tabs>
  <Tab title="子智能体未触发">
    ### 子智能体未触发

    **问题：** 自定义子智能体未自动激活

    **检查清单：**

    - 文件位置：`~/.verdent/subagents/[name].md`
    - 包含 `name` 和 `description` 的有效 YAML frontmatter
    - 调用策略与使用方式匹配（strict 要求 @ 提及）
    - “何时使用” 准则与请求模式匹配
    - markdown 文件中无语法错误

    **手动测试：**

    ```
    @subagent-name perform task
    ```

    <Tip>
      在排查自动调用之前，先使用显式 @ 提及来验证子智能体是否正常工作。
    </Tip>
  </Tab>
  <Tab title="内置子智能体">
    ### 内置子智能体行为

    **问题：** @Explorer、@Verifier 或 @Code-reviewer 行为不符合预期

    **常见原因：**

    - 请求与子智能体的专长不匹配
    - 子智能体上下文已满（罕见）
    - 主对话上下文影响了路由

    **解决方法：**

    - 使用显式 @ 提及来强制指定子智能体
    - 重新表述请求以匹配子智能体的专长
    - 如果是上下文问题，开启新对话
  </Tab>
  <Tab title="AGENTS.md 规则">
    ### AGENTS.md 未生效

    **问题：** 项目规则未影响 Verdent 行为

    **诊断：**

    1. **位置：** 文件必须位于项目根目录
    2. **语法：** 有效的 Markdown（检查语法错误）
    3. **明确性：** 规则必须是指令式的：“Always use X” 而非 “Try to use X”
    4. **测试：** 开启新对话以测试全新应用效果

    **优先级检查：**

    ```markdown
    # In AGENTS.md (highest priority)
    - Use 4-space indentation

    # In VERDENT.md (lower priority)
    - Use 2-space indentation

    # Result: 4-space indentation (AGENTS.md wins)
    ```
  </Tab>
  <Tab title="MCP 连接">
    ### MCP 连接失败

    **错误：** 无法连接到 MCP 服务器

    **诊断步骤：**

    1. **检查 mcp.json：** `~/.verdent/mcp.json` 中有效的 JSON 语法
    2. **服务器运行中：** 确保 MCP 服务器进程处于活动状态
    3. **网络：** 验证与服务器端点的连通性
    4. **认证：** 确认凭据正确
    5. **日志：** 检查 MCP 服务器日志以获取错误详情

    **常见修复：**

    - 重启 MCP 服务器
    - 验证连接字符串格式
    - 检查防火墙规则是否允许 MCP 流量
    - 验证 API 密钥或令牌
  </Tab>
</Tabs>

---

## 已知问题与应对方法

<Tabs>
  <Tab title="二进制文件">
    ### 二进制文件限制

    **问题：** 无法编辑图片、PDF、已编译的二进制文件

    **应对方法：**

    ```bash
    # Use bash to call external tools
    bash("convert input.png -resize 50% output.png")
    bash("pdftotext document.pdf output.txt")
    ```

    <Info>
      修改二进制文件需要通过 bash 命令调用外部工具。
    </Info>
  </Tab>
  <Tab title="大文件">
    ### 大文件处理

    **问题：** 超过 10,000 行的文件会导致上下文问题

    **应对方法：**

    ```bash
    # Always use line ranges for large files
    file_read("large.log", start_line=1000, max_lines=100)

    # Search first to find relevant sections
    grep_content("ERROR", glob="large.log")
    ```

    <Tip>
      先用 grep_content 搜索以定位相关行号，然后只读取那些特定范围。
    </Tip>
  </Tab>
  <Tab title="平台差异">
    ### 跨平台命令差异

    **问题：** bash 命令在 Windows 和 Unix 之间存在差异

    **应对方法：**

    ```bash
    # Use cross-platform tools when possible
    bash("npm run build")  # Works everywhere

    # Or conditional execution
    bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
    ```

    **最佳实践：** 使用 npm 脚本以实现跨平台兼容性。
  </Tab>
</Tabs>

---

## 获取更多帮助

### 支持渠道

**对于此处未涵盖的具体问题：**

- **邮箱：** [support@verdent.ai](mailto:support@verdent.ai)
- **Discord：** [加入 Verdent 社区](https://discord.com/invite/NGjXEZcbJq) 获取实时支持
- **GitHub Issues：** 报告 bug 或请求功能

**报告问题时，请包含：**

1. Verdent 版本（来自扩展面板）
2. VS Code 版本
3. 操作系统
4. 错误信息（确切文本）
5. 重现步骤
6. 预期行为与实际行为

---

### 诊断信息收集

**帮助支持团队进行诊断：**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

---

## 另请参阅

<CardGroup cols={2}>
  <Card title="常见问题" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    常见问题解答
  </Card>
  <Card title="限制" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    已知限制与约束
  </Card>
</CardGroup>