Cmd 命令执行工具

适用版本：v4.0.8.2

Cmd 的设计目标不是“任意执行 shell”，而是“带 allowlist 的受控命令执行”。

1. 命令执行边界图

如何阅读这张图

• Cmd 真正承担的是“受控执行器”角色，而不是默认给模型一把 shell。
• 命令白名单和工作目录白名单是两层独立边界，任何一层不通过都应该中止。

2. 初始化

from agently.builtins.tools import Cmd

cmd = Cmd(
    allowed_cmd_prefixes=["ls", "rg", "cat", "pwd"],
    allowed_workdir_roots=["/workspace/project"],
    timeout=20,
    env=None,
)

默认允许的命令前缀很保守：

• ls
• rg
• cat
• pwd
• whoami
• date
• head
• tail

3. 两层安全边界

命令白名单

命令首项必须在 allowed_cmd_prefixes 中，否则返回：

{
    "ok": False,
    "need_approval": True,
    "reason": "cmd_not_allowed",
}

工作目录白名单

workdir 必须位于 allowed_workdir_roots 内，否则返回：

{
    "ok": False,
    "need_approval": True,
    "reason": "workdir_not_allowed",
}

4. 公开方法

result = await cmd.run(
    cmd="rg TriggerFlow .",
    workdir="/workspace/project",
    allow_unsafe=False,
)

其中：

• cmd 可为字符串或 list[str]
• allow_unsafe=True 会跳过命令前缀检查，但不会跳过工作目录检查

5. 成功返回

{
    "ok": True,
    "returncode": 0,
    "stdout": "...",
    "stderr": "",
}

6. 架构思路

Cmd 更适合被放进“只读诊断”或“审批后执行”的链路里：

• 模型只负责提出命令意图
• Cmd 负责硬边界检查
• 上层系统再决定是否把结果写回 Tool Loop

这也是为什么高风险写操作不应该直接暴露给默认工具回路。

7. 使用建议

• 只开放读取类命令给模型
• workdir 精确到项目根目录
• 把真正危险的写操作放到人工批准流程，而不是直接暴露给 Tool Loop