局限与约束

不支持二进制文件

Verdent 的文件工具仅支持基于文本的格式。以下文件无法编辑：

变通方法： 二进制文件可以在代码中被引用或进行概念性讨论，但修改需要借助外部工具。

file_read 行数限制

局限：

• 大文件（>10,000 行）应分段读取
• 完整读取大文件可能导致上下文耗尽

解决方案： 使用行范围：file_read("file.js", start_line=100, max_lines=50)

bash 命令超时

局限：

• 最大超时时间：120 秒（2 分钟）
• 长时间运行的操作会被自动终止

解决方案： 将操作拆分为可在 2 分钟内完成的较小命令

搜索性能

局限：

• 宽泛的 glob 模式（**/*）可能返回数千条结果
• 正则搜索比字面字符串更慢

解决方案： 使用具体的模式并排除不必要的目录

上下文耗尽

问题： 在长会话或复杂操作中，AI 的上下文窗口可能被填满，限制了引用更早对话内容的能力。

缓解策略：

• 使用子智能体进行探索性研究（结果只消耗主上下文）
• 通过行范围有策略地读取文件
• 在读取完整内容前先使用 grep_file
• 将后台任务委派给 Explorer 子智能体

无法直接进行系统管理

无法：

• 以编程方式修改 VS Code 设置
• 自动安装 VS Code 扩展
• 更改系统级配置
• 重启 VS Code 或系统服务

范围： Verdent 在 VS Code 工作区内运行，而非系统管理层级。

无法自主执行

手动接受模式的控制：

• 用户必须在手动接受模式下批准工具执行
• 未经批准不会有自动化的后台操作
• 无法在 VS Code 关闭时运行命令

目的： 保证安全性以及用户对所有操作的控制。

无法实时监控

无法：

• 持续监控运行中的进程
• 实时跟踪文件系统变化
• 对系统事件发出告警
• 持续流式读取日志文件

替代方案： 使用 MCP 集成对接外部监控工具。

没有 MCP 无法进行网络操作

内置局限：

• 无法发起任意 HTTP 请求（针对特定页面请使用 web_fetch）
• 无法直接连接数据库（需要 MCP）
• 无法直接访问云服务（需要 MCP）
• 没有实时 API 集成（需要 MCP）

解决方案： 配置 MCP 服务器以访问外部系统。

二进制文件修改

局限： 无法编辑图片、PDF 或编译后的二进制文件

变通方法：

• 在 bash 命令中引用外部工具：bash("convert input.png -resize 50% output.png")
• 生成可供外部工具执行的脚本
• 记录二进制文件操作的手动步骤

示例：

# Image conversion
bash("convert input.png -resize 50% output.png")

# PDF to text
bash("pdftotext document.pdf output.txt")

大文件处理

局限： 超过 10,000 行的文件会给上下文窗口带来压力

变通方法：

• 使用行范围：file_read("large.log", start_line=1000, max_lines=100)
• 先搜索：grep_content("ERROR", glob="large.log") 以查找相关部分
• 将文件拆分为更小的模块以便管理

上下文窗口耗尽

局限： 长对话会填满上下文窗口

变通方法：

• 委派给 Explorer 子智能体进行代码库研究
• 使用 Verifier 子智能体执行隔离的验证任务
• 为不同的任务开启新对话
• 使用 todo_update 在多个会话间跟踪进度

最佳实践： 将后台研究委派给子智能体，以保留主上下文用于活跃的开发工作。

平台命令差异

局限： bash 命令在 Windows 和 Unix 之间存在差异

变通方法：

• 使用跨平台工具：用 npm 脚本代替原始 bash
• 条件命令：bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
• 在项目专属的 AGENTS.md 中加入平台说明

示例：

# Cross-platform
bash("npm run build")

# Platform-specific conditional
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then make; else nmake; fi")