如何让AI在真实设备上写代码跑命令:AgentDock文件与命令工具完全指南

原创2026-10-14 04:44:001,720 阅读

如何让AI在真实设备上写代码跑命令:AgentDock文件与命令工具完全指南

AgentDock 是一个面向 AI Agent 的安全 MCP 运行时,它通过文件工具(File Tools)和命令工具(Command Tools)让 ChatGPT、Claude 等 AI 在本地电脑、服务器或容器上写代码、改配置、跑命令,并在明确的权限边界内返回结构化、可追溯的结果。本文带你快速看懂 AgentDock 的 7 个核心文件与命令工具,以及它们如何安全地落地到真实设备。

AgentDock 多设备连接示意:AI 通过 MCP 调用文件与命令工具操作多台真实设备

🚀 快速上手:3 步连接你的 AI 客户端

AgentDock 通过 MCP(Model Context Protocol)Streamable HTTP 协议对外暴露工具。连接只需要 3 步:

  1. 安装 AgentDock:从官方安装包按操作系统安装即可,无需 Go 环境;
  2. 获取接入信息:安装后从控制台或终端拿到 MCP 地址与 Bearer Token(默认地址形如 http://127.0.0.1:8765/mcp,以实际部署为准);
  3. 配置客户端:把地址和 Token 填入 ChatGPT、Claude 等客户端的 MCP 设置:
{
  "mcpServers": {
    "agentdock": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <AGENTDOCK_AUTH_TOKEN>"
      }
    }
  }
}

💡 公网访问必须保留认证并使用 HTTPS,不要把 Token 发到公开聊天、截图或 Issue 中。

📁 文件工具:让 AI 安全地读、搜、改代码

文件工具由 4 个核心工具组成,源码入口见 specs_file.go,参数契约定义在 contract.go:

工具 作用 类型 关键限制
read_file 按行读取 UTF-8 文本片段 只读 默认最多 256KB,上限 4MB
list_dir 列出目录条目,支持 glob 过滤 只读 深度上限 20 层,条目上限 5000
search_text 全文或正则搜索 只读 结果上限 1000 条,上下文 20 行
file_edit 编辑文件(5 种动作) 写入 支持 dry-run 预览 diff

路径规则很重要:相对路径默认从 ~/AgentDock 目录解析;绝对路径和 ~/ 路径则遵循宿主安全规则。

🔍 只读三件套:读懂一个陌生项目

让 AI"先看再动手"是最稳的工作方式:

  • list_dir 支持 max_depth 控制遍历深度,** 可跨目录匹配;
  • search_text 优先使用 ripgrep 引擎,没有 rg 时自动回退到内置 Go 实现(rg / go_fallback),并支持 include_globs、exclude_globs 精确控制搜索范围;
  • read_file 支持 start_line / end_line 分段读取,超长文件会被截断并告知 next_start_line,AI 可以自动继续读。

✏️ file_edit 五种编辑动作

file_edit 用一个工具统一了所有文件修改(参数见 contract.go):

action 说明
replace 精确文本替换,支持 replace_all
patch 应用结构化补丁(Add / Update / Move 文件)
add 新建文件并写入内容
delete 删除文件或目录
move 移动/重命名文件

两个值得点赞的安全设计:

  • dry_run 预览:只校验并返回 diff,不真正写盘;
  • diff_preview + insertions/deletions:每次修改都给出变更摘要,AI 和人都能核对改了什么。

写入层由 atomicfile 模块 保证原子写入,配合 securepath 模块 的路径边界与私有目录保护,AI 无法越界写坏系统文件。

⚡ 命令工具:让 AI 跑命令、看输出、管长任务

命令工具由 3 个工具组成,契约定义在 contract.go,注册见 specs_command.go:

工具 作用 类型
exec_command 执行命令,返回结果或会话 写入
session_observe list / status 查看会话 只读
session_act write / kill / kill_all 操作会话 写入

🔢 exec_command 的三种执行模式

execution_mode 决定了命令如何返回(详见 参数定义):

  • auto(默认):先同步等待 yield_time_ms(默认 5 秒),命令没跑完就转为后台会话,返回 session_id;
  • sync:一直等到命令退出才返回;
  • async:立即返回会话句柄。

关键安全参数:

  • timeout_ms:超时时间,上限 24 小时,防止失控进程;
  • max_output_bytes:输出上限(默认 64KB,上限 4MB),超长输出自动截断,避免撑爆对话上下文。

返回结果中 stdout、stderr、exit_code 严格分离,还有 elapsed_ms、timed_out 等字段——AI 能像资深运维一样判断命令到底成功没有,而不是只看"有没有输出"。

🕹️ 长命令会话:像人一样观察和交互

命令跑得久?exec_command 返回的 session_id 就是入口:

  1. session_observe(status)随时查看进程是否还活着、最新输出是什么;
  2. session_act(write)向 TTY 会话继续输入,回答交互式提示;
  3. 不需要了就用 kill / kill_all 优雅终止。

这让 AI 能处理 ssh 交互式登录、长时构建任务等场景,而不会傻等超时。

🧭 典型工作流:一次完整的多步任务

对 AI 说"帮我给这个项目加一个健康检查接口",背后通常是这样一条工具链:

list_dir      → 摸清项目结构
search_text   → 找到路由注册位置
read_file     → 精读相关代码段
file_edit     → replace 修改代码(可先 dry_run 预览)
exec_command  → 跑构建和测试,验证改动
session_act   → 测试没通过?继续排查并终止残留进程

多设备场景下,同一会话可连接多台设备的 AgentDock(Mac mini、VPS、Windows PC),AI 先确认当前连到哪台实例,再在正确设备上执行文件与命令操作。

🛡️ 安全速查表:AI 到底能碰什么

机制 保护什么
路径边界 + 私有目录保护 AI 无法随意读写系统敏感路径
原子写入(atomicfile) 文件不会写一半变成损坏状态
输出截断 + 敏感值脱敏 防止泄露和上下文爆炸
只读/写入工具分离 读取类工具天然无法修改系统
超时与输出上限 防止失控命令与超长输出

🔎 延伸阅读:在源码里看实现

想深入这些工具的实现,可以直接阅读源码(仓库为只读镜像,查看前可先克隆):

git clone https://gitcode.com/gh_mirrors/age/agentdock

总结

AgentDock 的文件与命令工具解决了一个核心问题:让 AI 在真实设备上干活,但不失控。只读工具自由探索,写入工具全部带边界、可预览、可追溯,长命令可以观察、交互、终止。把它接进你的 AI 客户端,"写代码 + 跑命令"就从聊天框里的空谈变成了真刀真枪的交付。

登录后查看全文
agentdock