Skip to content

终端与 Agent CLI:把重复劳动交出去 ​

本篇要点:你能把一个多步的重复劳动拆成 Agent 能执行的步骤,并且每一步都有可回滚的边界。 前置文章:《AI 编程助手:补全、重构与评审》在编辑器里改代码,改动范围小、能撤回;这一章把同样的能力放进终端,权限一下变大了。

一、为什么需要它 ​

2026 年 4 月,一位读者在群里贴了一张截图:项目根目录下 1200 个 .md 文件的 frontmatter 被批量改成了同一个 date。

他让命令行 Agent"把所有文档的日期更新到今天"。Agent 干得很漂亮,一条 sed -i 全改了。问题是他的仓库里除了今天的文章,还有 300 篇历史归档,日期是内容的一部分,不是元数据。

他没做错什么流程上的事,他只是把"改哪些文件"这个判断交给了 Agent,而不是自己给出范围。

终端里的 Agent 和编辑器里的助手有个本质差别:编辑器里它的动作受限于你打开的文件和光标,终端里它能访问的是整个文件系统、整个环境变量、整个 git 历史。同一个模型,权限差了几个数量级。

这一章讲的不是"怎么让它多干活",是"怎么让它干的活你能收得回来"。

二、核心概念 ​

2.1 任务分解:一步一验,不要一口气跑完 ​

命令行 Agent 的典型失败不是做错,是一次做了十件事,你不知道是哪件错的。

分解的原则是:每一步都有独立可观测的产出。改文件 → 看 diff;装依赖 → 看 lock 文件变化;跑脚本 → 看退出码和标准输出。

一个可用的粒度标准:如果这一步失败,你能不能只回滚这一步。不能,就再拆。

类比搬家。你不会把全部家当装一个箱子,因为丢一个就全丢。分箱是为了局部回滚。

2.2 dry-run 先行:先看它想干什么 ​

大多数 Agent CLI 支持 dry-run 或计划模式:只输出它打算执行的命令,不真正执行。

这一步的价值不在"确认它没搞错",在于你会在读计划的时候发现自己没说清楚。上面那位读者如果先看了计划,会看到 find . -name "*.md" 没有排除 archive/,一秒就能拦住。

反例:直接给"执行"权限,把 dry-run 当成可选项。Dry-run 的成本是读三十行输出,事故的成本是恢复 1200 个文件。

2.3 权限四级:从只读到无限制 ​

Agent CLI 通常有几档权限,理解每一档能做什么,比记住某个工具的参数重要。

级别能做什么典型场景风险
只读读文件、跑查询、看日志排查、理解代码、写报告几乎无
沙箱写只在指定目录写,网络受限改代码、生成文档、跑测试写错目录
全盘写任意路径读写系统配置、跨目录迁移误删、越权改配置
无限制加网络、加提权、加执行任意命令装环境、调云资源不可逆

表 4-1 权限四级与对应的风险

实践中 90% 的活只需要前两级。"这次要全盘写"应该是一个需要理由的例外,不是默认。

还有一条常被忽略:网络权限。允许联网意味着它能把你的文件内容发到外部,《进阶:数据安全与合规使用》会专门讲这条线。

2.4 生成脚本要能验:三个必查项 ​

让 Agent 生成脚本很容易,验证脚本才是主体工作。三个必查:

第一,范围。脚本里的通配符、find 条件、目录前缀,逐条确认覆盖了该改的、排除了不该改的。第二,幂等。同一脚本跑两遍,结果应该一样。追加类操作尤其要查。第三,回滚。改动前有没有备份、有没有 git 干净状态可以 git checkout。

第三项最容易被跳过,也最救命。动手之前先确认工作区是干净的,这一条比任何提示词都有效。

2.5 幂等:为什么它比"小心"更可靠 ​

幂等(idempotent)指同一操作执行多次,结果与执行一次相同。

在批量处理里,幂等是唯一能对抗"手滑重跑"的性质。人类防错靠小心,机器防错靠性质。你不可能连续三小时保持小心,但你可以让脚本跑几遍都一样。

实现幂等的常见手法:改之前先判断当前状态(已经是目标值就跳过)、用"设置"而不是"追加"、把中间产物写到临时目录再原子替换。

2.6 三类活不要交给终端 Agent ​

不是所有重复劳动都适合外包出去。有三类我建议留在手上。

第一类是只有一次机会的操作。删库、改线上配置、动证书、迁移数据。这类操作的共同点是失败没有第二次机会,而 Agent 的失败模式里恰好有一种叫"部分完成"——改了一半、剩一半、中断在中间的某个文件上。

第二类是涉及凭据的操作。贴一个 token 进去让它调接口,token 就进了对话历史、进了日志、可能进了别的地方。要做也让它在环境变量里读,绝不写进命令行。

第三类是判断占主导的活。比如"把这批需求按优先级排序"、"把这份清单里的重复项合并"。它的输出你会逐条复核,复核的时间超过自己做的时,就不该交出去。判断一下性价比:外包的前提是验证成本低于执行成本,而验证判断类结果往往比自己做还慢。

图 4-1 批量改动的六道闸:干净工作区 → 计划 → 范围核对 → 样本 → 全量 → 抽样验证

如图 4-1 所示,六道闸里有三道在"全量执行"之前。它们的作用不是让流程变慢,是把不可逆变成可逆。样本那一步常被跳过,而它恰恰是成本最低的一道。

三、动手实践 ​

真实任务:一个文档站有 1200 篇 .md,需要给所有当年的文章统一补一个 updated 字段,历史归档不动。

3.1 先把范围算清楚 ​

不要让 Agent 自己找文件。先自己算,把数字定下来。

bash
# 四个数必须能加回总数:全部、可改、归档、隐藏目录
find docs -name '*.md' | wc -l                                      # 全部
find docs -name '*.md' -not -path 'docs/archive/*' \
     -not -path 'docs/.obsidian/*' | wc -l                          # 候选
find docs -name '*.md' -path 'docs/archive/*' | wc -l               # 归档
find docs -name '*.md' -path 'docs/.obsidian/*' | wc -l             # 隐藏目录

运行结果:

text
1200
 835
 353
  12

1200 = 835 + 353 + 12,对得上。如果这四个数加不回总数,说明有文件落在所有条件之外,必须先把它们找出来。这一步花两分钟,省掉的是事后翻 1200 个文件。

注意"可改"这一项用了 -not -path 而不是 -newermt。-newermt 按文件修改时间算,而 git checkout 会重置修改时间,两者的结果经常对不上。判断"哪些该改"要看内容里的日期字段,不是看文件系统的 mtime。

3.2 让它出计划,不执行 ​

给 Agent 的指令里明确写"只输出计划":

markdown
任务:给 docs 下 2026 年的文章补 frontmatter 字段 updated: 2026-11-16。
约束:
- 只处理 2026-01-01 之后修改过、且不在 docs/archive/ 下的文件
- 已有 updated 字段的跳过(幂等)
- 不改动 frontmatter 以外任何内容
- 先输出:将要修改的文件数、排除的目录、将执行的命令原文
- 不要执行,等我确认

运行结果(它给的计划):

text
将修改 823 个文件(候选 835,其中 12 个已有 updated)
排除目录:docs/archive/(353 个)、docs/.obsidian/(12 个)
命令:python3 add_updated.py --since 2026-01-01 --exclude docs/.obsidian --dry-run

注意"排除 12 个隐藏目录"这一行是我没想到的。如果没看计划,这 12 个 Obsidian 配置文件也会被加字段。看计划的价值就在这里——它会替你想起来一些你忘了说的,也顺便暴露一些它自作主张加上的。

同时也注意它把 --exclude docs/archive 写进了命令:脚本里已经硬编码跳过 archive/,重复排除不算错,但说明它没读脚本正文,只是照抄了你的话。这类小出入要看一眼。

3.3 写一个幂等脚本 ​

不让它直接 sed,让它写脚本。脚本能被读、能被改、能重跑。

python
# add_updated.py —— 给指定日期后的 md 补 updated 字段,幂等
import argparse, re
from pathlib import Path

ap = argparse.ArgumentParser()
ap.add_argument("--since", default="2026-01-01")
ap.add_argument("--exclude", action="append", default=[])
ap.add_argument("--dry-run", action="store_true")
a = ap.parse_args()

changed = skipped_has = skipped_old = skipped_dir = 0
for p in Path("docs").rglob("*.md"):
    # 归档与排除目录先记数再跳过,这样最后五项能加回总数
    if any(str(p).startswith(e) for e in a.exclude) or "archive/" in str(p):
        skipped_dir += 1
        continue
    text = p.read_text(encoding="utf-8")
    m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
    if not m:
        continue
    fm = m.group(1)
    if re.search(r"^updated:", fm, re.M):
        skipped_has += 1
        continue
    if re.search(r"^date:\s*(\S+)", fm, re.M).group(1) < a.since:
        skipped_old += 1
        continue
    new = f"---\n{fm}\nupdated: 2026-11-16\n---\n" + text[m.end():]
    if not a.dry_run:
        p.write_text(new, encoding="utf-8")
    changed += 1

tag = "[dry-run] " if a.dry_run else ""
print(f"{tag}改 {changed}|已有 updated {skipped_has}|早于 {a.since} {skipped_old}"
      f"|目录排除 {skipped_dir}|合计 {changed+skipped_has+skipped_old+skipped_dir}")

运行结果(先 dry-run,再真跑,再跑一次验证幂等):

text
[dry-run] 改 823|已有 updated 12|早于 2026-01-01 0|目录排除 365|合计 1200
改 823|已有 updated 12|早于 2026-01-01 0|目录排除 365|合计 1200
改 0|已有 updated 835|早于 2026-01-01 0|目录排除 365|合计 1200

第三行的 改 0 就是幂等生效。第二遍跑没有任何副作用,这意味着"手滑重跑"不再是一个事故场景。

三行的"合计"都是 1200,和 3.1 节数出来的总数对上。把总数打印在最后一行,是幂等脚本唯一能自证的方式——数字对不上就停下来查,不用猜哪里漏了。

3.4 验证:抽样加构建 ​

改完之后不要凭感觉宣布完成。两个动作:

bash
# 抽样:随机看 5 个文件的 frontmatter
for f in $(find docs -name '*.md' -newermt '2026-01-01' ! -path 'docs/archive/*' | shuf -n 5); do
  echo "== $f"; sed -n '1,8p' "$f"; done

运行结果:

text
== docs/guide/ai-tools/ai-coding-assistants.md
---
title: [《AI 编程助手:补全、重构与评审》](/guide/ai-tools/ai-coding-assistants.html) AI 编程助手:补全、重构与评审
description: 把编程助手当"会写代码的实习生"……
date: 2026-11-16
order: 3
ch: 3
style: textbook
tags: [AI 编程助手, 代码补全, 仓库级上下文, 测试生成, 代码评审, 幻觉]
updated: 2026-11-16
---

(其余 4 个样本结构一致,字段顺序与缩进未变)

抽样之后跑一次构建。文档站的构建会校验 frontmatter 是否合法,不合法会直接报错。这一步比抽样更全面,因为它是自动的。

四、常见误解 ​

很多人以为给了权限就等于让它干活。实际上权限越大,它越倾向于"一次做完",而你越难核对。正确的做法是权限按需逐步放开:先只读让它摸清结构,再沙箱写改主目录,确认无误才谈全盘。

很多人以为 dry-run 只适合大改动。实际上小改动更该 dry-run,因为小改动你不会有警觉,而它同样可能写错路径。三行文件也可能被改到不该改的后缀上。

很多人以为生成脚本比自己写快。实际上在这个时代,快的那部分是从零到能跑,慢的部分是从能跑到能信。后一段的工作量取决于你验得多细,不取决于脚本是谁写的。

五、小结 ​

《AI 编程助手:补全、重构与评审》的改动局限在编辑器里、能撤回;这一章的改动面是整个文件系统,所以整章的重心从「怎么让它写对」移到了「怎么让它能回滚」。

  • 终端 Agent 的权限是编辑器里的几个数量级,安全边界要靠流程而不是靠模型自觉。
  • 分解粒度标准:这一步失败了,能不能只回滚这一步。
  • dry-run 的真实价值是让你发现"自己没说清楚",重点看范围与排除项。
  • 三个必查:范围、幂等、回滚。动手前先确认工作区干净。
  • 幂等比小心可靠:跑第二遍结果不变,才敢跑第一遍。
  • 每步数字都要能加回总数(1200 = 823 + 12 + 353 + 12),对不上就停下来,别猜。

六、相关文章 ​

批量处理解决的是"量",接下来要解决"信":Agent 帮你改完了 823 个文件,但你凭什么相信它的判断?检索类工具面对的是同一个问题,而且更尖锐——它给你的每一条结论都得能追到源头。相关文章讲怎么问、怎么溯源、怎么识破编造的引用。

继续阅读:[《AI 检索与研究:从提问到可信结论》 AI 检索与研究:从提问到可信结论](/guide/ai-tools/ai-search-and-research.html)