零基础复现Claude Code：终端篇——赋予输入命令的超能力

从"能改"到"能验证"

第4篇的成就我们给Agent装上了"双手"——它能真正读写文件了不再是纸上谈兵。不过，

但现在有个问题：Agent改完代码后它不知道改对了没有。话说回来，

这一篇是能力的关键跃升——从"盲改"到"验证式修改"。

本节目标

读完这篇文章，你将：

• 理解命令执行的风险与边界为什么这是Agent最危险的能力
• 实现安全的终端工具用白名单+黑名单双重过滤
• 掌握输出截断策略避免命令输出撑爆Token预算
• 看到Agent的完整工作流读文件→改文件→跑测试→看结果→调整

原理深潜的观点是。命令执行的双刃剑

📍 回到第一篇的公式

还记得我们在第一篇建立的公式吗？老实说，

循环 t = 0,1,2,...：
Thought_t。Action_t = LLM
Observation_t = Execute ← 本篇增加run_cmd工具
S_{t+1} = S_t + 

第4篇我们实现了read_file和write_fileAgent能读写文件了。

这一篇我们要实现run_cmd让Agent能输入命令验证自己的修改。

为什么命令执行是最危险的能力？

对比三种工具的风险等级：

工具	风险等级	最坏情况	可逆性
read_file	🟢 低	⚠️ 读取敏感文件⚠️	✅ 完全可逆✅
write_file`	🟡 中	☢️ 误改关键文件	🔄 部分可逆
run_cmd `	🔴 高	☠️ 删除整个项目	✘ 不可逆

为什么 run_cmd ` 最危险？

 # read_file 最多泄露信息
read_file # 读到密码。但文件还在
# write_file 可以备份恢复
write_file # 改坏了但有.backup
# run_cmd 可能造成灾难
run_cmd # 整个程序被删除，无法恢复 

所以我们必须 极其谨慎 地设计这个工具。

subprocess.run 的三个关键参数

Python 的 subprocess.run ` 是输入命令的标准方式：

 import subprocess
result = subprocess.run (
# 命令和参数
capture_output = True,# 捕获stdout和stderr
text = True。# 返回字符串而不是bytes
timeout =30 # 30秒超时防止卡死
)
print # 命令的标准输出
print # 命令的错误输出
print # 退出码 

关键洞察 ：

• capture_output=True ` ：让我们能拿到命令输出，反馈给模型
• text=True ` ：直接得到字符串，不需要decode
• timeout ` ：防止命令卡死

输出截断策略

假设Agent执行了 cat large_file.log `，文件有10MB。如果全部返回给模型：

10MB 文本 ≈ 250万Token ≈ $50 

而且会超出模型的。

方法：截断输出

 MAX_OUTPUT_LENGTH =2000 # 约400个Token
if len > MAX_OUTPUT_LENGTH :
return f "{output}
... }字符)"
else :
return output
by shlex.split
if not cmd_parts:
return "错误：空命令"
base_cmd = cmd_parts
if base_cmd not in SAFE_COMMANDS:
return f"⛔ 拒绝执行：'{base_cmd}' 不在安全命令列表中"
# 🔑 输入命令
result = subprocess.run(
cmd_parts,capture_output=True,text=True。timeout=30,# 🔒 30秒超时防止卡死
cwd=os.getcwd
)
# 🔑 合并stdout和stderr
output = result.stdout
if result.stderr:
output += f"
: {result.stderr}"
# 🔑 输出长度检查
if len> MAX_OUTPUT_LENGTH:
return f"{output}
... }字符)"
return output if output else ""
except subprocess.TimeoutExpired:
return "错误：命令执行超时"
except Exception as e:
return f"错误：{str}"

⚠️ 安全警告

⚠️ 命令执行是Agent最危险的能力，必须极其谨慎。

建议的安全措施：

1. 在隔离环境中测试
   • 用Docker容器：

     docker run -it python:3.9 bash

   • 从用虚拟机来看，

     VirtualBox、VMware等虚拟机软件。创建快照，方便回滚，

在真实的Claude Code实现中，这部分对应的是：

我们的实现 真实代码位置 关键差异

run_cmd

crates/runtime/src/bash.rs 中的 execute_bash

再看真实版支持。沙箱模式 流式输出

crates/runtime/src/permissions.rs 中的权限检查逻辑更复杂

支持多级权限控制

输出截断

execute_bash内部逻辑支持分页显示

智能截断

如果都能回答，恭喜你，Agent 的 "终端" 部分你已经掌握了。

下一篇见！说起来，``

新手容易踩的坑

说到坑1，用 shell=True 输入命令 后果这方面，容易被注入攻击 再看正确做法，始终使用列表形式传参

说到坑2。忘记设置timeout 至于后果，可能导致程序卡死 说到正确做法，始终设置合理的timeout

说到接下来，把所有拼图组装起来

现在你已经学会了如何实现安全的终端功能，而且看到了 Agent 的完整工作流。其实，

但还有一个关键问题没解决： 我们的 Agent 目前还是 “散装” 的 —— 多个独立文件。没有统一入口，

下一篇。我们将组装完整的 Mini Claude Code，实现真正的可用程序！

系列进度

✅ 第2篇：地基篇 — 让模型开口说话 ✅ 第3篇：灵魂篇 — ReAct循环的骨架 ✅ 第4篇：双手篇 — Agent 能读写文件了！说起来，✅ 第5篇：终端篇 — Agent 能执行安全命令！⏭️ 第6 篇 ： 组 装 篇 — Mini Claude Code 最 后 一 公里！

---