常见问题

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

解决方案：

1. 打开 VS Code 设置（macOS 上为 Cmd+,，Windows/Linux 上为 Ctrl+,）
2. 搜索 "useProxy" 或 "verdent.enableProxy"
3. 切换代理设置的开/关状态（与当前状态相反）
4. 再次尝试登录

说明： 如果你处于企业防火墙之后，可能需要启用代理设置。如果你使用的是家庭网络，请尝试禁用它。

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

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

解决方案： 请联系 support@verdent.ai 以获得免费试用访问方面的帮助。支持团队将审核你的账户并协助解决该问题。

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

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

解决方案： 请联系 support@verdent.ai 以获得帮助。支持团队可以审核你的注册并提供解决该问题的指导。

问题： 在模型选择菜单中找不到某些 AI 模型

原因： 模型提供商基于地理位置的限制

说明： 部分 AI 模型提供商（Anthropic、OpenAI、Google）设有区域限制，使某些模型无法在特定地理位置使用。出现这种情况时：

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

查看可用模型： 访问 https://www.verdent.ai/regions 查看你所在区域有哪些可用模型

注意： 区域限制由 AI 模型提供商设定，而非 Verdent。Verdent 无法覆盖这些限制。

Visual Studio Code 是由微软开发的免费开源代码编辑器。它是一个轻量但功能强大的开发环境，支持多种编程语言，并提供调试、语法高亮、智能代码补全和集成版本控制等功能。Verdent 作为扩展直接集成到 Visual Studio Code 中，为你现有的工作流添加 AI 驱动的编码能力。

Verdent 是一款用于 Visual Studio Code 的 AI 编码助手扩展，通过自然语言对话帮助你完成代码生成、重构、调试和项目导航。

核心能力：

• 通过文件工具进行代码生成和修改
• 借助专门的子智能体探索代码库
• 通过 bash 集成执行命令
• 通过规则和 MCP 服务器进行自定义扩展

最低要求：

• Visual Studio Code 1.90.0 或更高版本
• 有效的 Verdent 套餐
• 互联网连接

平台支持： macOS、Windows、Linux、WSL

1. 从 VS Code 应用市场安装 Verdent 扩展
2. 在提示时使用你的 Verdent 账户登录
3. 打开任意代码文件或项目
4. 打开聊天视图，开始与 Verdent 对话

首个任务建议： 让 Verdent 解释你的项目结构或审查某个特定文件。

打开 Visual Studio Code，转到 Help → About（在 macOS 上为 Code → About Visual Studio Code）。版本号会显示在对话框中。Verdent 需要 Visual Studio Code 1.90.0 或更高版本。

你也可以通过命令行查看：

code --version

请参阅 积分与套餐，了解 Verdent 各产品中积分、定价层级和使用基础的统一定义。

请参阅 积分用完后会发生什么，了解统一的账户政策和恢复选项。

通过剪贴板粘贴或通过文件路径引用的图片会在你的对话会话内处理。图片不会被永久存储，并在你开始新对话时清除。文件路径引用会在本地读取图片，不进行上传。

Plan Mode 是一种只读执行模式，Verdent 在其中分析代码、开展研究并创建详细的实现计划，但不会修改文件或执行命令。生成计划后，Verdent 会提供两个选项：Edit（请求修改并优化计划）或 Start Building（切换到 Agent Mode 并开始执行）。智能体可以提出澄清性问题，以在执行前消除不确定性。该模式非常适合复杂任务——你希望在做出更改前先审查方案，确保你的期望与 Verdent 提出的解决方案保持一致。

不会。 Plan Mode 严格只读：

• Verdent 可以读取文件、搜索代码并分析你的代码库
• 在 Plan Mode 期间不会发生任何文件写入、编辑或删除
• 计划仅显示在聊天视图中
• 只有在你明确批准并切换到 Agent Mode 后，才会开始执行代码

安全保证： Plan Mode 不会意外修改你的代码。它专为安全探索和策略制定而设计。

通过输入框即时切换：

进入 Plan Mode：

• 点击输入框中的 Switch Mode 按钮
• 从下拉菜单中选择 Plan Mode
• 或者说："Switch to Plan Mode"

退出 Plan Mode：

• 点击输入框中的 Switch Mode 按钮
• 从下拉菜单中选择 Agent Mode
• 或者在审查计划后选择 Start Building

模式持久性：

• 模式选择在当前会话内保持
• 新会话以默认的 Agent Mode 开始
• 你可以随时自由切换模式

典型工作流： Plan Mode → 审查 → Agent Mode → 执行 → 返回 Plan Mode 处理下一个复杂功能。

点击顶部栏中的 "New Session" 按钮。这会清除当前对话历史，并为你的下一个任务提供全新的上下文窗口。

可以，每个 VS Code 窗口独立运行。你可以在多个项目中打开 Verdent，每个窗口都维护各自独立的对话上下文。

可以。Verdent 使用标准 Git 命令，因此无论托管平台如何，它都能与任何 Git 仓库协作。对于创建拉取请求，Verdent 使用 gh CLI，该 CLI 需要 GitHub，但所有其他 Git 操作都通用。

支持： 所有基于文本的文件格式，包括：

• 源代码（JavaScript、Python、TypeScript、Java、Go 等）
• 配置文件（JSON、YAML、TOML、XML、ENV）
• 文档（Markdown、HTML、LaTeX）
• 构建文件（package.json、Makefile、requirements.txt）

不支持： 二进制文件（图片、视频、PDF、编译后的二进制文件、Office 文档）

变通方法： 可以在代码中引用二进制文件，但修改需要外部工具。

出色支持：

• JavaScript、TypeScript、Python、React、Vue、Angular
• Node.js、Go、Java/Spring、C#/.NET
• Swift、Kotlin、Flutter

非常好的支持： Rust、C/C++、Ruby、R

良好支持： PHP、Assembly、Julia

由于训练数据丰富，常见语言的支持更强。

三种文件操作工具：

• file_read： 读取完整文件或特定行范围
• file_edit： 替换特定文本模式（定向修改）
• file_write： 创建新文件或完整重写文件

最佳实践： 修改时使用 file_edit，仅在创建新文件时使用 file_write。

通过 Verdent 运行终端命令或 shell 脚本，包括运行测试、安装软件包或执行构建命令等操作。在大多数权限模式下，命令执行需要批准，以防止意外的系统更改。

可以，使用 bash 工具。Verdent 可以运行终端命令，具备：

• 最大超时：120 秒（2 分钟）
• 使用 && 进行命令链接
• 跨平台支持（Unix 上为 bash，Windows 上为 PowerShell）

安全性： 命令以你的用户权限执行。使用 Manual Accept Mode 在执行前进行审查。

最大超时： 120 秒（2 分钟）

超过 2 分钟的命令将被自动终止。对于更长的操作，可以考虑：

替代方案：

• 拆分为更小的命令：bash("task1") && bash("task2")
• 拆分为更小的操作
• 在后台运行并单独检查结果

一种迭代验证过程，代码经过生成、测试和修复，直到通过全面测试。Verdent 会自动运行测试、分析失败、修复问题并多次重新测试，直到代码正确运行。这交付的是可投入生产的代码，而不仅仅是建议。每个结果都包含详细摘要和代码差异，准确展示更改了什么。

子智能体是具有隔离上下文窗口、针对特定任务的专门 AI 智能体。

内置子智能体：

• @Explorer： 代码库搜索、架构问题
• @Verifier： 快速验证检查
• @Code-reviewer： 安全和质量审查

何时使用： 将研究、验证或审查任务委派出去，以节省主对话的上下文。

如何创建自定义子智能体：

在 ~/.verdent/subagents/ 中创建一个 markdown 文件：

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

使用场景： 领域专属专业知识（金融、医疗）、团队工作流、技术专家。

当上下文中先前的操作和信息形成了意料之外的行为模式，进而影响后续任务时，就发生了上下文污染。例如，如果你反复更新代码然后部署它，智能体可能开始把所有代码更新都与立即部署关联起来，即使你只是在做实验。子智能体通过在隔离的上下文窗口中运行来防止上下文污染，使每个专门任务都能以干净的上下文开始，避免不同类型工作之间的交叉污染。

查看 Verdent 面板底部的输入框。"Switch Permission" 按钮会显示你当前的模式（例如 "Manual"、"Auto"、"Plan"）。你可以点击它来切换模式。

Auto-Run Mode：

• 文件操作无需批准即自动执行
• 命令仍需权限
• 为可信代码库提供更快的工作流
• 最适合带版本控制的个人项目

Manual Accept Mode：

• 审查并批准每个受保护的操作
• 对于共享代码库或生产环境更安全
• 在执行前准确了解将运行什么

通过设置或命令面板切换模式。

仅读取数据而不做更改的操作：文件读取和网页搜索。这些操作在 Auto-Run Mode 中会自动批准，而文件编辑和命令执行出于安全考虑仍需批准。

不可以，权限模式互斥——你一次只能使用一种：

• Manual Accept —— 默认，最大控制
• Auto-Run —— 为可信项目简化流程
• Plan —— 只读规划模式
• Skip Permissions —— 完全自主

你可以通过输入框中的 Switch Permission 按钮即时切换模式。大多数用户会根据任务上下文在不同模式之间切换（例如，复杂功能用 Plan Mode，快速修复用 Auto-Run）。

对于发现和搜索任务，使用 Explorer 智能体可避免消耗主上下文。仅在需要修改文件时才用 @ 提及直接加载文件。Explorer 非常适合 "找出所有……的文件" 这类问题，而 @ 提及适合 "更新这个特定文件" 这类任务。

可以！在 ~/.verdent/subagents/ 中创建自定义子智能体：

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

使用场景： 领域专属专业知识（金融、医疗）、团队工作流、技术专家。

可以。你可以随时中断执行。Verdent 会完成它当前正在处理的步骤，然后停止。在此之前的进度会被保留。你可以审查已完成的工作，进行调整，然后选择继续或采取不同的方法。

查看待办事项列表。它实时显示状态，任何时候都有一项被标记为 "in progress"。活动项准确显示 Verdent 当前正在处理什么。已完成项被标记为完成，待处理项显示剩余内容。

不会。Verdent 仅在你明确要求时才创建提交。你对何时提交更改拥有完全控制权。准备好后，只需说 "暂存所有更改并创建提交" 即可。

不会。Verdent 仅在你明确要求时才推送到远程仓库。所有 Git 操作（commit、push、merge、rebase）出于安全考虑都需要你的明确指示。

三种自定义方法：

1. VERDENT.md： 个人全局偏好（~/.verdent/VERDENT.md）
2. AGENTS.md： 项目专属团队标准（项目根目录，纳入版本控制）
3. plan_rules.md： Plan Mode 输出格式（~/.verdent/plan_rules.md）

为保持团队一致性，AGENTS.md 会覆盖 VERDENT.md。

大多数 Verdent 设置会立即生效，无需重启：

• 权限模式： 通过输入框即时切换
• 模型预设： 在下一次请求时应用
• 规则文件： 应用于新对话（保存会触发重新加载）
• 子智能体： 创建后立即可用
• 键盘快捷键： 在 VS Code 中保存后应用

例外： VS Code 扩展设置（如 verdent.enableCheckpoints）会立即生效，但可能需要重新打开文件或会话才能完全应用。

Model Context Protocol（MCP）通过外部工具和服务扩展 Verdent：

配置： 通过 设置 → MCP Servers 进行 ~/.verdent/mcp.json

能力：

• 数据库连接（PostgreSQL、MySQL、MongoDB）
• 云服务（AWS、Azure、GCP）
• 项目管理工具（Jira、Linear）
• CI/CD 流水线（Jenkins、GitHub Actions）

状态： MCP 集成文档正在编写中。如需设置帮助，请联系 support@verdent.ai。

上下文窗口的计量单位。Token 代表 AI 模型处理的文本片段（单词、单词的一部分或字符）。上下文限制以 token 而非字符或单词来衡量，典型对话会消耗数千个 token。

你会话中的所有内容：对话中的全部消息、加载到上下文中的文件内容、工具输出（grep/搜索结果、文件读取）、系统提示词和指令，以及 MCP 服务器定义。这些都会消耗你总上下文容量中的 token。

标准模型（Claude 4.5 Sonnet、Haiku、GPT-5、GPT-5-Codex、MiniMax-M2）拥有 200K token 的上下文窗口，足以应对大多数任务。Claude Sonnet 4.5 提供扩展的 1M token 上下文（大 5 倍），适用于包含 1000+ 文件的大型代码库、复杂的多文件重构或长时间的开发会话。当输入超过 200K token 时，1M 上下文会自动激活，也可以显式选择。

没有固定的文件数量限制——这取决于文件大小和总 token 数。对于 200K 上下文，避免加载 20+ 个大文件（每个 >1000 行）。专注于与当前任务直接相关的文件。有选择地使用 @-mentions，并利用 AGENTS.md 文档而不是加载许多示例文件。使用 1M 上下文时，文件选择就不那么关键了。

迹象包括响应时间变慢、会话已运行数小时，或加载了许多大文件。监控你的会话长度和文件数量。当你注意到性能下降时，完成当前任务，提交进度，然后以干净的上下文开始一个新会话。

策略：

1. 策略性文件读取： 对大文件使用行范围
2. 委派给子智能体： 用 Explorer/Verifier 进行后台研究
3. 先搜索再读取： 使用 grep_file 识别相关文件
4. 拆分操作： 使用 todo_update 跟踪多步任务

经验法则： 超过 500 行的文件应使用行范围。

你必须手动开始一个新会话来重置上下文——Verdent 不会自动清除上下文。最佳实践：在完成一个原子工作单元、测试并提交到版本控制后重置。对于 1M token 上下文，重置的需求要少得多。

不会——重置上下文只会从内存中清除对话历史和已加载的文件。你实际的代码更改、提交和文件修改都会被保留。出于安全考虑，请始终在重置上下文前将工作提交到版本控制。重置 → 开始新会话 → 继续处理下一个任务。

要具体到足以消除歧义，但不要过度解释显而易见的细节。包括：确切的文件路径、实现方法、预期结果和约束。不好的示例："修复代码"——太含糊。好的示例："在 ContactForm.js 中为 email 字段添加输入验证，以拒绝无效的邮箱格式"——范围和目标清晰。拿不准时，宁可更具体一些。

Verdent 会自动加载提示词中按名称提及的文件以及同一目录中的相关文件。@-mentions（@filename.js）显式保证某个文件在上下文中，这在处理紧密耦合的文件、参考一个文件的模式应用到另一个文件，或自动检测可能在大型代码库中遗漏上下文时至关重要。当你要求 Verdent "遵循与……相同的模式" 时，请始终使用 @-mentions 以确保精确的代码引用。

不需要——Verdent 在会话内维护对话上下文，因此你无需重复已讨论过的架构细节或约定。不过，对于关键约束，或当会话变长时（100+ 条消息），请重申重要的上下文。更好的做法：使用项目规则（AGENTS.md）来记录持久的上下文，如技术栈、编码标准和模式——这样你就再也无需重复它们了。

使用迭代式优化：审查输出，找出哪里出了问题，然后在后续提示词中提供更正。示例："验证逻辑很好，但请使用 Joi 模式验证而不是手动检查。匹配 ProductController.js 中的验证模式。" 你也可以要求解释："你为什么使用 Redux 而不是 Context API？" 然后基于理解进行优化。不要重复相同的提示词——根据失败的原因进行调整。

在以下情况使用 Plan Mode：大型重构或架构更改、你希望在执行前审查范围的多文件修改、你对需求不确定的复杂任务，或你希望 Verdent 在实现前通过澄清性问题对你进行访谈。跳过 Plan Mode 的情况：简单、明确定义的任务、快速 bug 修复或日常操作。Plan Mode 会增加开销，但能在复杂工作中防止代价高昂的错误。

根据任务复杂度和预算匹配模型预设：

使用 Efficiency（效率比 Sonnet 高 3.2 倍）：

• 快速 bug 修复和简单代码生成
• 日常操作和高频任务
• 速度比深度更重要时

使用 Balance（1 倍基线）—— 默认：

• 通用开发和日常编码
• 功能实现和代码审查
• 大多数场景下的均衡性能

使用 Performance（效率 0.5 倍，成本 2 倍）：

• 复杂的架构决策
• 需要大量上下文（200k+ token）的大型代码库
• 复杂的调试和重构

专业提示： 大多数用户保持 Balance 为默认，仅在触及上下文限制或需要深度推理时切换到 Performance。

如果 Verdent 无法连接到 AI 服务，请检查以下常见问题：

测试基本连通性：

• 确认你有可用的互联网访问
• 尝试访问其他 HTTPS 服务，以确认出站连接正常工作

企业/团队环境：

• 联系你的网络管理员，将 Verdent 的 API 端点加入白名单
• 确保允许出站 HTTPS 流量通过你的防火墙
• 检查代理服务器是否已正确配置以放行 API 请求
• SSL/TLS 检查可能需要为 Verdent 端点设置例外

常见症状：

• 扩展似乎挂起或超时
• 凭据正确但身份验证失败

如果配置防火墙后问题仍然存在，请联系 Verdent 支持，以获取需要加入白名单的具体端点详情。

检查：

• 位置： 文件位于项目根目录
• 语法： 有效的 Markdown
• 明确性： 规则要有指令性（"始终使用……" 而不是 "尽量……"）
• 全新测试： 开始新对话以测试应用情况

优先级： 对于项目专属行为，AGENTS.md 会覆盖 VERDENT.md。

原因：

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

解决方案：

• 再次读取文件以获取当前内容
• 提供更长的上下文字符串以确保唯一性
• 对多个相同字符串使用 replace_all=true
• 确认 file_path 正确

检查：

• 位置： 文件位于 ~/.verdent/subagents/[name].md
• 调用策略： 严格策略需要显式 @ 提及
• YAML frontmatter： 语法有效
• "何时使用" 准则： 与你的请求模式匹配

测试： 使用显式 @ 提及来验证子智能体是否正常工作：@your-subagent do task