Cmd 命令执行工具

适用版本：4.0.8.1+

Cmd 提供“可控命令执行”，默认有两层安全边界。

1) 初始化

from agently.builtins.tools import Cmd

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

2) 安全机制

• 命令白名单：只允许 allowed_cmd_prefixes
• 目录白名单：workdir 必须位于 allowed_workdir_roots

若不满足，会返回：

• need_approval=True
• reason=cmd_not_allowed 或 reason=workdir_not_allowed

3) 直接调用

import asyncio
from agently.builtins.tools import Cmd

cmd = Cmd(allowed_cmd_prefixes=["ls", "pwd"], allowed_workdir_roots=["/workspace/project"])

async def main():
    result = await cmd.run("ls", workdir="/workspace/project")
    print(result)

asyncio.run(main())

4) 结果结构

成功时典型字段：

• ok
• returncode
• stdout
• stderr

拒绝时典型字段：

• ok=False
• need_approval=True
• reason

5) 与 Agent 集成建议

• 只暴露必要命令，不要给宽泛前缀
• 目录白名单精确到项目根
• 在提示词中约束用途（如“仅允许读取文件”）