参数

参数	类型	必填	说明
`command`	string	是	要执行的 shell 命令
`description`	string	是	向用户解释为什么执行此命令及预期效果
`working_directory`	string	否	命令执行的工作目录（绝对路径），不指定则使用当前目录

安全机制

交互模式（TTY）下，AI Agent 每次执行命令前都会弹出确认提示，由你决定是否授权：

⚠️  准备执行命令:
  └ 描述: 检查当前目录下 Rust 文件的编码格式
  └ 命令: file src/*.rs

? 是否确认执行？
  ▸ 1. 允许
    0. 拒绝

允许 — 按 Enter 或 1，命令将被执行
拒绝 — 按 0，命令被取消
Ctrl+C — 安全退出

非交互环境（管道、CI、重定向等）：默认拒绝所有命令执行，这是安全设计。

自动放行

对于绝对安全的只读命令（如查看系统信息、打印工作目录等），shell_exec 会自动放行，不会弹出确认提示。内置命令列表按操作系统划分：

适用于 Unix 系操作系统：

类别	命令	说明
通用	`pwd`	打印工作目录
	`whoami`	打印当前用户名
	`true` `false`	无操作，返回 0/1
	`echo`	输出文本（需带参数，裸 `echo` 不放行）
	`printf`	格式化输出（需带参数）
	`cd`	改变工作目录
系统信息	`uname`	系统信息
	`hostname`	主机名
	`uptime`	系统运行时间
	`arch`	硬件架构
	`which`	定位命令路径（需带参数）
	`id`	用户身份信息
	`logname`	登录用户名
	`tty`	终端设备名
	`cal`	显示日历
	`seq`	生成数字序列（需带参数）
	`getconf`	系统配置变量（需带参数）
	`pathchk`	路径名检查（需带参数）
路径操作	`basename`	从路径中提取文件名（需带参数）
	`dirname`	从路径中提取目录名（需带参数）
	`realpath`	解析为绝对路径（需带参数）
目录列表	`ls`	列出目录内容
日期时间	`date`	查看当前日期时间

适用于 Windows 操作系统：

类别	命令	说明
通用	`pwd`	打印工作目录
	`whoami`	打印当前用户名
	`true` `false`	无操作，返回 0/1
	`echo`	输出文本（需带参数，裸 `echo` 不放行）
	`printf`	格式化输出（需带参数）
	`cd`	改变工作目录
系统信息	`hostname`	主机名
	`which`	定位命令路径（需带参数）
	`id`	用户身份信息
	`ver`	显示 Windows 版本
	`systeminfo`	显示系统信息
目录列表	`dir`	列出目录
日期时间	`date /t`	显示日期（`/t` 表示只查看不设置）
	`time /t`	显示时间（`/t` 表示只查看不设置）
	`vol`	显示卷标

匹配规则：命令以列表中的某个条目开头即匹配（前缀匹配）。例如 ls 会放行 ls 和 ls -la，但不会误放 lsblk。

即使前缀匹配，包含 ; | > < ` $ & 等控制运算符的命令仍会要求确认，这是安全保护。

内置列表的設計原则是"宁可漏放（回到确认流程）也不错放"。如果内置列表未覆盖你常用的安全命令，可以通过 [permissions.commands] 配置自行扩展。

自定义权限配置

你可以在 ~/.zapmyco/settings.toml 中配置命令的自动放行（白名单）和自动拒绝（黑名单）：

[permissions.commands]
# 自动放行的命令前缀列表（白名单）
# 命令将以"开头匹配"的方式检查：
# - "git status" 会放行 "git status" 和 "git status -s"
# - 匹配的命令会跳过用户确认
allow = [
    "git status",
    "git diff",
    "git log",
    "cargo check",
    "cargo clippy",
    "cargo fmt --check",
]

# 自动拒绝的命令前缀列表（黑名单，优先于 allow）
# 如果一个命令同时匹配 allow 和 deny，deny 优先生效
deny = [
    "rm -rf",
    "sudo",
]

在配置自定义放行命令时请谨慎评估安全性。即使配置了放行列表，包含控制运算符的命令仍会要求确认。

约束与限制

限制项	值
执行超时	30 秒
输出最大长度	100,000 字符（stdout + stderr 合计）
Shell（Unix）	`sh -c`
Shell（Windows）	`cmd.exe /C`

错误场景

错误类型	说明
超时	命令执行超过 30 秒
命令未找到	Shell 无法找到指定的可执行文件
输出过大	stdout + stderr 超过 100K 字符限制
用户拒绝	用户在确认提示中选择了"拒绝"或 `Ctrl+C`

使用示例

zapmyco run '列出当前目录的文件'
zapmyco run '运行测试并显示结果'
zapmyco run --profile advanced '重构 src/cli.rs 中的重复代码，然后运行 cargo fmt'

shell_exec — 执行命令

参数