本地 AI 代理中的文件访问：工具

本地AI代理的文件访问：工具与bug修复

我们的本地AI代理Doka现已支持文件访问功能，但在此之前，我们修复了llama.cpp中的一个关键KV缓存bug。系统提示以Session started: ${new Date().toISOString()}开头，每次迭代都会变化。这导致整个缓存失效：模型在10次迭代中从头重新计算2000个提示词标记，额外浪费了20,000个标记。

将时间戳移到提示末尾或用户回合末尾，即可恢复缓存。多步任务在8次以上迭代的循环中，速度提升2–3倍。这种模式类似于Anthropic对Claude的推荐，但对本地模型同样至关重要。

通过权限关卡实现安全文件访问

文件读取工具很简单，但写入操作需要防护措施。工具箱中的每个工具都有dangerous标志：

const fileTools: Tool[] = [
  {
    name: 'read_file',
    dangerous: false,
  },
  {
    name: 'write_file',
    dangerous: true,
  },
  {
    name: 'edit_file',
    dangerous: true,
  },
  {
    name: 'delete_file',
    dangerous: true,
  },
];

调用危险工具时，会弹出对话框显示参数：路径和内容（前500字符）。“允许”按钮不是默认选项。拒绝时，向代理返回错误：

{
  "error": "用户拒绝write_file权限",
  "canRetry": false,
  "suggestion": "请用户确认目标文件路径"
}

完整文件工具套件

我们实现了六种工具：

• read_file(path: string): string
• write_file(path: string, content: string): void (危险)
• edit_file(path: string, instruction: string): void (危险)
• list_dir(path: string): FileEntry[]
• move_file(from: string, to: string): void (危险)
• delete_file(path: string): void (危险)

edit_file根据指令应用补丁（读取→补丁→写入→验证），避免通过上下文传递大文件。

修复路径相关错误

代理因相对路径混淆了不同目录下同名文件。修复方案：

• 系统提示中指定默认工作目录。
• 路径验证：超出范围触发错误。
• 指令：路径模糊时询问用户。

该bug在测试3–4中显现：代理选择了根目录的notes.md，而非目标文件夹。

write_file或edit_file后，我们添加自动验证：自动read_file检查。这多一步，但防止静默失败（权限、磁盘问题）。MAX_TOOL_STEPS提升至12，支持计划+读取+写入+验证。

代理时间线提升透明度

用户抱怨“黑盒子”：等待三分钟不知步骤。我们添加侧边栏日志：

• 工具调用及参数。
• 结果。
• 时间戳。

事件流（tool_call_start / tool_call_end）在React中实时渲染。文件访问必备：用户看到确切路径和操作。

结构化错误与重试逻辑

以前，错误会输出Node.js堆栈跟踪，导致无限重试或幻觉。现在结构化：

{
  "error": "文件未找到: /path/to/file.md",
  "canRetry": false,
  "suggestion": "先用list_dir检查路径是否正确"
}

canRetry减少无谓循环。网络超时为true，不存在文件为false。

重构系统提示

系统提示现分节：

• 角色与边界：能力与限制。
• 优先规则：安全>准确>速度。
• 响应格式：不同类型结构。
• 少样本示例：边缘案例推理。

此结构减少长链幻觉，尤其规则拒绝。

规划阶段：思考→规划→行动

工具前指令：

使用工具前，写简短计划：
THINK: [需要什么信息？]
PLAN: [步骤1 → 步骤2 → 步骤3]
ACT: [执行计划]

减少冗余工具调用。强制行动前设定目标。

关键要点

• 将动态数据（时间戳）移至提示末尾，通过KV缓存加速循环2–3倍。
• 权限关卡+对话框+结构化错误最小化写入风险。
• 自动验证+路径校验消除静默文件操作失败。
• 代理时间线通过步骤透明构建文件访问信任。
• 带规划的结构化提示提升多步任务可靠性。

— Editorial Team