如何让AI在真实设备上写代码跑命令:AgentDock文件与命令工具完全指南
如何让AI在真实设备上写代码跑命令:AgentDock文件与命令工具完全指南
AgentDock 是一个面向 AI Agent 的安全 MCP 运行时,它通过文件工具(File Tools)和命令工具(Command Tools)让 ChatGPT、Claude 等 AI 在本地电脑、服务器或容器上写代码、改配置、跑命令,并在明确的权限边界内返回结构化、可追溯的结果。本文带你快速看懂 AgentDock 的 7 个核心文件与命令工具,以及它们如何安全地落地到真实设备。
🚀 快速上手:3 步连接你的 AI 客户端
AgentDock 通过 MCP(Model Context Protocol)Streamable HTTP 协议对外暴露工具。连接只需要 3 步:
- 安装 AgentDock:从官方安装包按操作系统安装即可,无需 Go 环境;
- 获取接入信息:安装后从控制台或终端拿到 MCP 地址与 Bearer Token(默认地址形如
http://127.0.0.1:8765/mcp,以实际部署为准); - 配置客户端:把地址和 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 就是入口:
session_observe(status)随时查看进程是否还活着、最新输出是什么;session_act(write)向 TTY 会话继续输入,回答交互式提示;- 不需要了就用
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
- 文件工具参数契约:internal/tool/file/contract.go
- 命令工具参数契约:internal/tool/command/contract.go
- 工具注册入口:internal/app/specs_file.go 与 internal/app/specs_command.go
- 补丁预览与解析:internal/tool/file/patch_preview.go
- 原子写入实现:internal/fs/atomicfile/write.go
- 内置用户指南 Skill:core-skills/agentdock-user-guide/SKILL.md
总结
AgentDock 的文件与命令工具解决了一个核心问题:让 AI 在真实设备上干活,但不失控。只读工具自由探索,写入工具全部带边界、可预览、可追溯,长命令可以观察、交互、终止。把它接进你的 AI 客户端,"写代码 + 跑命令"就从聊天框里的空谈变成了真刀真枪的交付。
