故障排查

“Service is experiencing high traffic. Please try again later!”

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

何时出现：

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

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

安装与设置问题

系统要求：

• 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”）

全新重装流程：

查看日志：

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

无法登录 Verdent for VS Code

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

解决方法：

未收到免费试用积分

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

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

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

注册失败

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

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

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

缺少模型（Claude、GPT、Gemini）

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

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

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

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

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

性能问题

症状：

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

常见原因与修复方法：

图片相关错误信息

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

file_edit 失败

错误： “Failed to find exact match”

原因：

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

解决方法：

# 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)

bash 命令失败

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

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

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

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

命令未找到：

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

权限错误：

• 命令以用户权限执行
• 仅在必要时并在手动接受模式下使用 sudo
• 检查文件/目录权限

搜索返回无结果

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

检查模式语法：

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

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

检查排除项：

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

大小写敏感性：

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

子智能体未触发

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

检查清单：

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

手动测试：

@subagent-name perform task

内置子智能体行为

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

常见原因：

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

解决方法：

• 使用显式 @ 提及来强制指定子智能体
• 重新表述请求以匹配子智能体的专长
• 如果是上下文问题，开启新对话

AGENTS.md 未生效

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

诊断：

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

优先级检查：

# 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)

MCP 连接失败

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

诊断步骤：

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

常见修复：

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

二进制文件限制

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

应对方法：

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

大文件处理

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

应对方法：

# 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")

跨平台命令差异

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

应对方法：

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

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

最佳实践： 使用 npm 脚本以实现跨平台兼容性。