学完 Hello-Agents 教程之后，最后一个任务是毕业设计。用所学的知识自己手搓一个Agent应用，刚好那段时间 Code Agent 特别火，Cursor、Claude Code、Codex… 各家都在推自己的产品。心想既然要练手，不如复刻一个 Code Agent，自己手搓一遍，才能真正理解这些产品为什么好用，以及它们到底在工程上做对了什么。

于是就有了这个项目。
基于Hello-Agents框架的Code Agent代码仓库：https://github.com/datawhalechina/hello-agents/tree/main/Co-creation-projects/YYHDBL-HelloCodeAgentCli

重构后MyCodeAgent代码仓库：https://github.com/YYHDBL/MyCodeAgent.git

这篇文章不是教程，是我在做这个 Code Agent 项目过程中踩过的坑、走过的弯路、以及最后怎么解决的一些记录。

目录

• 第一章：看了太多最佳实践，反而踩进第一个大坑
• 第二章：一次管道命令事故——我第一次看见”不可诊断”有多致命
• 第三章：工具设计的 Goldilocks 区
• 第四章：提示词不是魔法咒语，而是 Agent 的控制面
• 第五章：上下文不是内存容量问题，而是注意力调度问题
• 第六章：可观测性把黑盒变玻璃盒
• 第七章：从一个项目抽出来的通用方法论

第一章：看了太多最佳实践，反而踩进第一个大坑

刚动手写代码时，我查阅了大量业界的 Agent 设计实践。比如 Manus 团队分享的《上下文工程经验教训》，还有 Anthropic 官方的《Building agents with the Claude Agent SDK》。看着这些顶流大厂毫无保留地分享”最佳实践”，我心想：反正现在有 Claude Code，让 AI 帮我把这些高级概念全实现一遍不就行了？

于是，我不假思索地堆砌了各种看似优雅的设计：多层记忆（Memory System）、复杂的上下文工程、多智能体系统（Multi-Agent）……不得不说，Claude Code 确实牛逼，很快就帮我生成了一大堆逻辑复杂的代码。

天崩开局

但当我满怀期待地跑起第一版测试时，现实狠狠打了我一巴掌：整个系统烂透了。

面对一个极其简单的修改需求，Agent 像发疯一样调用了七八种工具，进行了好几轮的”左右脑互搏”。最终，我只收获了一段根本跑不通的残缺代码，以及一张严重超支的 Token 欠费账单。

看着满屏的报错，我才意识到：Agent 开发和传统软件开发很不一样。

以前我们做传统后端开发，习惯先画好架构图，再写代码。图纸够优雅，系统就稳固。这是程序员的本能。

但 Agent 开发不一样。你是在跟一个大模型打交道，它本身就是概率性的——同样的输入，每次可能给你完全不同的输出。

我在这个不确定的地基上，强行叠加了一套自己都没验证过的复杂架构。多智能体、Plan-and-Execute……这些设计彼此交叉，让不确定性成倍放大。

结果是：复杂架构没能兜住底，反而因为状态流转太多、工具交叉太复杂，让模型错得更离谱。错误在各组件之间来回传，我连排查都无从下手。

那些大厂的”最佳实践”当然是好东西，但我忽略了一点：那些复杂架构是他们踩了无数坑、耗费了海量 token 之后演进出来的结果，不是新手上路的起点。

推倒重来

看着这堆连简单读取文件都会陷入死循环的代码，我做了一个违背祖宗的决定——删库，推倒重来。

奉行”Less is more”的原则，我直接复用了 Hello-Agent 最基础的主干，把最短的链路先跑通。核心组件被精简到只剩这几块：

代码层面，我没有搞任何花哨的设计模式，直接在 code_agent.py 里粗暴地把它们攒了起来：

1
2
3
4
5
6
7
8

self.terminal_tool = TerminalTool(
    workspace=str(self.paths.repo_root),
    timeout=60,
    confirm_dangerous=True,
    default_shell_mode=True,  
)
self.registry = ToolRegistry()
self.registry.register_tool(self.terminal_tool)

看着这个简陋的 V0 版本成功在终端里跑通了第一个极简任务，我长舒了一口气。

只要可以完成最基础的基础对话和工具调用，我们就能在真实任务环境中验证和迭代优化。

先跑起来，比一步更重要。

第二章：一次管道命令事故——我第一次看见”不可诊断”有多致命

V0 跑起来之后，我开始放松对工具的约束。既然架构已经精简了，让模型自由组合命令应该没问题吧？

于是我给 Terminal Tool 开了绿灯：default_shell_mode=True。这意味着模型不只能跑单条命令，还能写管道、重定向、子命令——就像人一样。

事故经过

那天我提了个简单需求：”帮我搜一下 process_data 函数的定义”。

模型很快给出了一条看起来挺专业的命令：

1

rg -n "def process_data" src/ | grep -v test | sed -n '1,50p'

老工程师常用的组合拳：先搜函数定义，过滤掉测试文件，再取前 50 行。没什么问题。

但执行结果是空的。Agent 看到这个空结果，愣了一下，然后开始补救：

第一轮重试：

1
2

Thought: 看起来没找到，可能是搜索范围太窄了。让我扩大搜索范围。
Action: rg -n "process_data" | head -100

还是空。

第二轮重试：

1
2

Thought: 可能函数名记错了，试试模糊匹配。
Action: rg -n "process.*data" src/ --type py | grep "def "

还是空。

第三轮重试：

1
2

Thought: 看来这个函数可能不存在，或者我搜错了目录。让我先列出目录结构。
Action: find src/ -name "*.py" | xargs grep -l "process_data"

结果依然是空。三轮尝试后，它放弃了，告诉我：”我在仓库里没有找到 process_data 函数的定义，可能函数名有误，或者它不在 Python 文件里。”

但我手动去仓库里看了，那个函数明明就在 src/utils/helpers.py 第 42 行。

排查过程

我复制那条命令到终端自己跑，发现 rg 报错了：

1
2

$ rg -n "def process_data" src/ | grep -v test | sed -n '1,50p'
Error: path 'src/' does not exist

原来我启动 Agent 时的工作目录不是项目根目录，而是项目下的一个子目录。src/ 相对当前目录不存在，rg 直接报错退出。

但在 Agent 那边，错误信息被管道吞掉了。因为命令用了 |，rg 的错误输出没有传到 stdout，而是被管道导向了下一个命令的输入。grep 收到的是空输入，自然输出空；sed 也是空。

错误在链路中被压扁了。 Agent 看到的只是一个空字符串，它根本不知道上游失败了。

最坑的是，模型基于这个错误信息做出了完全错误的判断。它以为”确实没找到”，于是开始各种补救：换搜索词、换目录、甚至怀疑我是不是记错了函数名。这些动作全都是基于一个错误的判断，白白消耗了大量 token。

当时的错误修复方向

我第一反应是：Bash 工具太危险了，得加限制。

于是我写了一大堆安全检查代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

SHELL_META_TOKENS = ["|", "||", "&&", ";", ">", ">>", "<", "$(", "`"]
DANGEROUS_BASE_COMMANDS = {"rm", "chmod", "mv", "dd"}

def validate_command(cmd):
    # 检查是否包含管道或重定向
    for token in SHELL_META_TOKENS:
        if token in cmd:
            return False, f"包含非法字符: {token}"
    
    # 检查基础命令是否在白名单
    base_cmd = cmd.split()[0]
    if base_cmd not in ALLOWED_COMMANDS:
        return False, f"命令 {base_cmd} 不在白名单"
    
    # 检查危险命令
    if base_cmd in DANGEROUS_BASE_COMMANDS:
        return False, "危险命令，禁止执行"
    
    return True, "OK"

但很快我发现，shell 太灵活了。你禁了 |，它可以用 $(...) 子命令替换；你禁了 >，它可以用 tee；你禁了 rm，它可以用 > file 来清空文件。

补丁越打越多，代码越写越长，但那个根本问题——“到底是哪一步失败了”——依然存在。

即使我封死了所有管道和重定向，只允许最简单的单条命令，问题还在：

1

rg "pattern" src/

如果返回空，我还是不知道是”仓库里真的没有”，还是”rg 因为路径错误没执行”。模型依然无法针对性地纠错。

根因定位

后来我才想明白，这件事的根因不是”命令太危险”，而是不可诊断。

具体来说有三个问题：

第一，多步骤被塞进一个 Action。 管道把好几步逻辑打包在一起，中间状态全丢了。Agent 只能看到最终结果，看不到执行过程。

第二，观察信号只有一个终态。 成功、失败、空结果，全都混在一起。模型分不清楚”真的没找到”和”查找过程中出错了”。

第三，模型无法针对性纠错。 它不知道 rg、grep、sed 谁出了问题，下一步只能瞎猜。重试不是基于”修正错误”，而是基于”赌运气”。

给模型更高自由度，不是在提升能力上限，而是在放大不确定性。它确实能写出更”聪明”的命令，但一旦出错，连你自己都排查不了它在哪一步”聪明反被聪明误”了。

现在的做法

后来我直接把 Bash 降级了——不是删掉，而是明确它的定位：只处理那些原子工具覆盖不到的边角需求，不走主链路。

高频操作全部拆成原子工具：

每个工具都有明确的状态码：

• success：任务完成，结果在 data 里
• partial：任务完成但内容被截断
• error：任务失败，error 里有具体错误码

比如 Glob 搜不到文件：

1
2
3
4
5

{
  "status": "success",
  "data": {"paths": []},
  "text": "No files matching '*.xyz' found"
}

路径不存在：

1
2
3
4

{
  "status": "error",
  "error": {"code": "NOT_FOUND", "message": "Path 'src/' does not exist"}
}

模型能清晰区分”确实没有”和”出错了”。

Bash 的硬约束也明确了：

• 禁止读/搜/列：ls/cat/head/grep/find/rg 这些有专门工具
• 禁止交互：vim、nano、top、ssh
• 禁止网络（默认）：curl/wget 被禁
• 黑名单：rm -rf /、sudo/su、mkfs/fdisk

这样做之后，调试变得简单很多。出了问题看日志就知道是哪一步：

• Glob 返回了空数组 → 确实没这个文件
• Glob 返回了 NOT_FOUND → 路径错了
• Grep 返回了 timeout → 搜索范围太大

模型也能根据具体的错误码决定下一步：路径错了就换路径，超时了就缩小范围，真的没找到就告诉用户。

本章结论

可诊断性是可恢复性的前提。

如果不知道哪坏了，就修不好。如果不知道失败发生在哪一步，就无法针对性纠正。

在 Agent 开发里，给模型自由组合命令的能力，听起来很美好，但实际上是在制造黑盒。看似高效的管道命令，把错误信息压扁成一个个无法区分的空结果，让模型在错误的道路上越跑越远。

原子工具虽然步骤繁琐，但每一步都有明确的输入、输出、状态。出了问题，你能定位；模型错了，你能纠正。

可控性比一次性完成任务重要得多。

第三章：工具设计的 Goldilocks 区——不是越自由越好，也不是越碎越好

第三章之后，我开始把工具拆开。Terminal Tool 那种什么都管的万能模式确实有问题，拆成原子工具后，调试变得清晰多了。

但我很快又踩了一个新坑：拆得太碎了。

两个极端我都踩过

极端 A：万能工具

第一个极端你已经见过了。一个 Terminal Tool 什么都能做：管道、重定向、子命令、环境变量——完全放开。

那时候我觉得，LLM 这么聪明，给它足够自由度，应该能像工程师一样操作。rg | grep | sed 这种组合命令效率很高。

结果你也知道了：错误被管道吞掉，模型瞎猜重试，token 哗哗流，问题还没解决。

极端 B：过度原子化

意识到万能工具有问题后，我走向了另一个极端：把每个功能点都拆成独立工具，追求极致的原子化。

那时候我的工具列表长这样：

• ListDir：列出目录内容
• ListDirRecursive：递归列出目录
• FindByName：按文件名查找
• FindByPattern：按通配符查找
• SearchExact：精确匹配搜索
• SearchRegex：正则匹配搜索
• SearchFuzzy：模糊匹配搜索
• ReadLines：读取指定行范围
• ReadOffset：读取指定字节偏移
• ReadFull：读取完整文件
• …

问题很快就来了。

第一，模型开始”选工具困难”。

都是找文件，FindByName、FindByPattern、Glob，用哪个？模型经常在第一步就卡住，它要花好几轮才能确定”哦，原来应该用 Glob”。

有一次我让它”找一下所有测试文件”，它先调了 ListDirRecursive 列出所有文件，然后想调 SearchRegex 来过滤，但发现 SearchRegex 是搜内容不是搜文件名，于是又调回 ListDirRecursive 拿更多上下文，最后才选对 Glob。

本来一步搞定的事，用了四步。

第二，Schema 噪声淹没上下文。

每个工具都有参数描述、类型定义、约束条件。十几个工具的 schema 加起来，几千 token 就出去了。

模型还没开始解决任务，就先消耗大量注意力在”读说明书”上。更糟糕的是，长 schema 容易让模型”选择性失明”——它可能只注意到部分工具，或者把参数搞混。

第三，维护成本爆炸。

每个工具都要单独写测试、单独调优、单独处理边界情况。FindByName 和 FindByPattern 有 80% 的逻辑是重复的，但因为是两个独立工具，我得维护两份代码。

这时候我才意识到，工具系统不是乐高颗粒越细越好。过度封装和过度拆分，本质上都会把系统推向不稳定，只是一个坏在执行期（万能工具），一个坏在决策期（过度原子化）。

转折点：找那个”刚刚好”的度

我后来给自己定了一个判断框架：频率 × 确定性。

• 高频、强确定动作：必须原子化，一步完成，不可再分
• 中频、带副作用动作：必须受控，关键操作加保险
• 低频、弱确定动作：保留弹性，但放到兜底层，明确禁止什么而非允许什么

按这个框架，我重新设计了工具体系，形成三层结构：

这套分层不是”架构美学”，是被真实故障逼出来的。它最大的价值是降低模型决策负担，让高频路径更短、更清晰。

高频原子层：必须稳定

这层工具是 Agent 的”主力武器”，使用频率最高，必须极致稳定。

Glob：找文件，一个工具就够了

最开始我想把”按名找文件”拆成多个工具：

• FindByName：精确匹配文件名
• FindByPattern：通配符匹配
• FindByRegex：正则匹配
• FindRecursive：递归查找

后来我发现这就是过度原子化。模型会纠结：”我是该用精确匹配还是通配符？要不要递归？”

最后合并成一个 Glob，只做一件事：给定模式，返回候选路径。

1
2
3
4
5

# Glob 的参数
{
  "pattern": "**/*.py",  # 通配符模式，** 表示递归
  "path": "src/"         # 起始路径，默认为当前目录
}

内部实现可以复杂（支持 ** 递归、自动处理大小写、结果排序），但对模型暴露的接口必须简单。模型不需要知道”递归还是不递归”，它只需要说”找所有 py 文件”。

Grep：复杂度留在实现层

Grep 是另一个例子。内部我做了很多优化：

• 优先用 rg（ripgrep），速度快
• rg 不可用时（比如编码问题、权限问题）自动回退到 Python 实现
• 结果按文件修改时间排序，最近修改的排前面

但对模型来说，它看到的就是：

1
2
3
4
5
6

# Grep 的参数
{
  "pattern": "def process_data",  # 搜索模式
  "path": "src/",                  # 搜索路径
  "file_pattern": "*.py"          # 可选：只搜特定类型文件
}

返回格式固定：

1
2
3
4
5
6
7
8
9

{
  "status": "success",
  "data": {
    "matches": [
      {"file": "src/utils.py", "line": 42, "text": "def process_data(...)"},
      {"file": "src/helpers.py", "line": 88, "text": "def process_data(...)"}
    ]
  }
}

模型看到的是一个稳定入口。内部实现可以复杂（比如自动回退），但对外接口要简单。

中频受控层：能改，但必须”读过才能改”

这层工具涉及文件修改，是”高危操作”，必须有严格的约束机制。

Read → Edit/Write 的强制顺序

我设计了一个硬性规则：不 Read 就不能改。

1
2
3
4
5
6
7
8
9
10
11
12

# 第一次 Read
result = Read({"path": "core/llm.py"})
# 返回包含 file_mtime_ms 和 file_size_bytes

# 后续 Edit 自动注入乐观锁参数
Edit({
  "path": "core/llm.py",
  "old_string": "...",
  "new_string": "...",
  "file_mtime_ms": 1733920000123,  # 自动注入
  "file_size_bytes": 4217          # 自动注入
})

ToolRegistry 会自动维护一个读缓存。如果某个文件没有被 Read 过，Edit/Write 会直接返回错误："File not read. You must read before editing."

这防止了模型”凭记忆”去改文件——它必须先把文件内容拿到上下文中，确认过，才能改。

乐观锁：防止并发修改

即使 Read 过了，文件也可能在 Read 之后被外部程序（比如 IDE 的自动保存）修改。

Edit/Write 会对比 file_mtime_ms 和 file_size_bytes，如果不匹配，返回 CONFLICT 错误：

1
2
3
4
5
6
7

{
  "status": "error",
  "error": {
    "code": "CONFLICT",
    "message": "File changed since last read."
  }
}

这时候模型必须重新 Read，获取最新内容，再尝试修改。

MultiEdit：原子性多点修改

有时候需要在同一个文件里改多个地方。如果拆成多个 Edit，中间可能出错，导致文件处于”半改”状态。

MultiEdit 支持一次性提交多个修改，要么全成功，要么全失败：

1
2
3
4
5
6
7

MultiEdit({
  "path": "core/llm.py",
  "edits": [
    {"old_string": "...", "new_string": "..."},
    {"old_string": "...", "new_string": "..."}
  ]
})

这保证了文件修改的原子性。

低频兜底层：Bash 不是不能用，但绝不能当默认入口

Bash 我没删，因为总有原子工具覆盖不到的低频场景。比如：

• 跑测试命令：pytest tests/
• 安装依赖：pip install -r requirements.txt
• 检查 git 状态：git status

但它的定位必须是”兜底”，不是”默认”。

明确禁区

Bash 的约束列表很长，但核心就一条：禁止做高频动作能做的事。

1
2
3
4
5
6
7
8
9
10
11
12

BASH_DISABLED_PATTERNS = [
    # 禁止读/搜/列（这些有专门工具）
    r'\bls\b', r'\bcat\b', r'\bhead\b', r'\btail\b',
    r'\bgrep\b', r'\bfind\b', r'\brg\b',
    # 禁止交互
    r'\bvim?\b', r'\bnano\b', r'\btop\b', r'\bssh\b',
    # 禁止网络（默认）
    r'\bcurl\b', r'\bwget\b',
    # 危险命令黑名单
    r'\brm\s+-rf\b', r'\bsudo\b', r'\bsu\b',
    r'\bmkfs\b', r'\bfdisk\b'
]

如果模型试图用 Bash 做 ls，它会收到错误："Use LS tool instead of Bash for listing directories."

这强制模型走原子工具的主链路，不让它”抄近道”。

为什么留着 Bash？

有人可能会问：既然限制这么多，为什么不干脆删掉 Bash？

因为完美原子化是不现实的。总有一些边缘需求：

• 跑一个自定义的 Python 脚本
• 检查系统环境变量
• 执行项目特定的构建命令

这些需求频率太低，不值得专门做成工具，但又确实需要。Bash 就是处理这些”长尾需求”的。

关键是：Bash 的存在不能影响主链路的稳定性。它必须是”最后手段”，不是”默认入口”。

关键机制设计

统一响应协议

所有工具，无论高频中频低频，都返回统一格式的 JSON：

以Glob工具的返回结果为例：

1
2
3
4
5
6
7
8
9
10

{
  "status": "partial",
  "data": {
    "paths": ["core/llm.py", "agents/codeAgent.py"],
    "truncated": true
  },
  "text": "Found 2 files matching '**/*.py' (Scanned 12000 items, timed out)",
  "stats": {"time_ms": 2010, "matched": 2},
  "context": {"cwd": ".", "params_input": {"pattern": "**/*.py"}}
}

这有几个好处：

• 模型不需要学习不同工具的不同返回格式
• 错误处理逻辑统一：看 status，如果是 error 看 error.code
• 调试方便：所有工具的输出结构一致，Trace 记录也统一

ToolRegistry

ToolRegistry 不只是工具注册表，它还干几件关键的事：

1. Schema 汇总

把每个工具的参数定义转成 JSON Schema，统一提供给模型：

1

registry.get_openai_tools()  # 返回所有工具的 schema 列表

2. 乐观锁自动注入

对于 Write/Edit/MultiEdit，自动注入 file_mtime_ms 和 file_size_bytes：

1
2
3
4
5
6

def _inject_optimistic_lock_params(self, tool_name, parameters):
    if tool_name in {"Write", "Edit", "MultiEdit"}:
        path = parameters.get("path")
        if path in self.read_cache:
            parameters["file_mtime_ms"] = self.read_cache[path]["mtime"]
            parameters["file_size_bytes"] = self.read_cache[path]["size"]

3. 熔断机制

工具连续失败会被临时禁用，防止模型在坏工具上死循环：

1
2
3
4
5
6

# 3 次失败熔断，300 秒后恢复
if circuit_breaker.should_block(tool_name):
    return {
        "status": "error",
        "error": {"code": "CIRCUIT_OPEN", "message": "Tool temporarily disabled"}
    }

本章结论

这一章最大的反直觉是：工具既不是越多越好，也不是越原子越好。

万能工具的问题在于”自由度过高”，不可诊断；过度原子化的问题在于”决策负担过重”，效率低下。

找到刚刚好的度的关键：

1. 高频动作先原子化：LS/Glob/Grep/Read 这些每天调用几十次的工具，必须把主路径做稳，不能出错。

2. 中频动作加保险：Write/Edit 这种涉及修改的工具，必须有读后写、乐观锁、原子性保证。

3. 低频动作兜底线：Bash 保留，但明确禁区，禁止它做高频动作能做的事，避免污染主链路。

4. 协议统一：所有工具说同一种语言（status/data/text/error），降低模型学习成本。

5. 数量控制：schema 总量控制在模型可承受范围内，不要让”读说明书”消耗太多注意力。

第三章让我明白”自由会放大不确定性”。

第四章：提示词不是魔法咒语，而是 Agent 的控制面

工具原子化之后，我以为问题主要在”工程实现”上，提示词嘛，差不多就行。结果我又踩了一个大坑：把提示词当成魔法咒语，以为只要找到”神级提示词”，Agent 就能变聪明。

我最早的三种错误

错误 1：照抄”神级提示词”

那时候我沉迷于搜集各种”顶级提示词”。GitHub 上那些标星几万、号称”让 GPT 突破限制”的 prompt，我一个个拿来试。

印象最深的是一个”专家模式”提示词，大概意思是让模型扮演一个”拥有 20 年经验的资深工程师，思考严谨、代码优雅”。我把它塞进 System Prompt，满怀期待地测试。

结果？Agent 确实变得更”自信”了——它开始频繁地给出它”认为”正确的答案，而不是基于仓库里的真实代码。搜不到的时候它就开始”合理推测”，编出一些看起来很有道理但实际上并不存在的函数和类。

后来我明白了：这种角色扮演式提示词，对 ChatGPT 聊聊天可能有用，但对 Code Agent 是毒药。它让模型更敢”猜”，而不是更依赖证据。

错误 2：凭感觉调优

每次 Agent 表现不好，我的第一反应就是改提示词。加一条”不要猜测”，感觉好点；再加一条”必须基于证据”，好像又聪明了点。

但这种”好像变聪明了”完全是我的主观感受。同样的提示词，换个任务可能就崩了。我甚至不知道是哪条改动起了作用，因为每次都是好几条一起改。

有一次我加了一段很长的规则，告诉模型在遇到复杂任务时应该”先分解再执行”。结果它开始在每轮都输出”让我分解一下这个问题”，然后列出一堆毫无意义的步骤，真正该干的事反而被淹没了。

错误 3：先改提示词，再补观测

这是最蠢的一个习惯。Agent 出错了，我不先去查 Trace 看它到底做了什么，而是直接改提示词试图”预防”下一次出错。

比如有一段时间，Agent 经常在不合适的时候调用 Write 工具。我直接在提示词里加了一大段：”只有在确认用户需要修改时才调用 Write，否则应该先用 Read 查看”。

结果模型开始疯狂调用 Read，每轮都读一堆文件，然后才决定是否要写。Token 消耗翻倍，但正确率并没有提高。

后来看 Trace 才发现，真正的问题是上下文里缺少了”当前任务类型”的信息，模型根本不知道用户是想浏览还是修改。提示词里的”应该”再多，也补不上信息缺口。

我后来改成的方式

先记录，后优化

现在我养成了一个习惯：Agent 出问题时，先不碰提示词，而是打开 Trace 看完整轨迹。

看什么呢？

• 模型在哪一步开始偏离预期？
• 它做出错误决策时，上下文里有什么信息？缺了什么信息？
• 工具返回的结果，模型理解对了吗？

很多时候问题根本不在提示词。比如模型反复用错工具，可能是因为工具描述不够清晰；它开始胡言乱语，可能是因为上下文太长导致注意力分散。这时候改提示词是治标不治本。

用 Trace 做对比实验

当我确定需要改提示词时，我会用 Trace 做对比实验：

1. 保持其他所有条件不变，只改提示词里的一个点
2. 跑同样的测试用例，记录成功率、步数、token 消耗
3. 对比新旧 Trace，看行为差异是否如预期

有一次我想让模型在搜索时更”精准”一些，减少了提示词里关于搜索策略的描述，只保留了”使用精确的关键词”。结果对比 Trace 发现，模型确实少搜了很多无关文件，但漏搜率也上去了——它过于保守，错过了一些相关文件。

这个反馈让我意识到，不能一味追求”少”，而是要在”全”和”准”之间找平衡。

单变量改动

我以前喜欢一次性加好几条规则，觉得这样能”全面覆盖”。现在我知道这是在给自己挖坑——如果表现变好了，你不知道是哪条规则起作用；如果变差了，你也不知道该删哪条。

现在我坚持单变量改动。哪怕觉得某个问题很明显，也要一条一条试，验证每一条的实际效果。

提示词设计的三层结构

经过这些踩坑，我总结了一个相对稳定的提示词结构，分成三层：

第一层：边界层（Not to do）

这层只写”禁止”和”底线”，不解释为什么：

• 禁止猜测：如果没有找到，直接说没找到，不要推测
• 禁止越界：只能操作 repo_root 内的文件，禁止访问外部路径
• 信息不足必须承认：如果上下文里没有足够信息，要求补充，不要瞎编

这层规则很短，但每条都是红线。它们不告诉模型”应该怎么做”，只告诉它”绝对不能做什么”。

第二层：决策层（How to think）

这层写决策逻辑，但尽量用过程而不是结果来描述：

• 先证据后结论：任何改动建议必须有代码片段支撑
• 优先可验证动作：能用工具确认的，不要靠推理
• 一步一观测：每个 Action 之后必须有 Observation，不要跳步

注意这里避免使用”聪明地”、”合理地”这种模糊的副词。模型不知道什么叫”聪明”，但它知道”先调用 Grep 找到证据，再调用 Read 确认内容”这个流程。

第三层：恢复层（When failed）

这层写失败时的退化策略，告诉模型出错时该怎么办：

• 工具返回空：检查参数是否正确，考虑换关键词重试
• 遇到 CONFLICT（乐观锁冲突）：必须重新 Read，获取最新状态后再 Edit
• 连续 3 次失败：停止尝试，向用户报告具体错误

这层很关键，因为 Agent 不可能永远成功。失败时能不能优雅降级，比成功时表现多好更重要。

工程细节

System Prompt 保持稳定

我把变化最少的内容放在 System Prompt：基础行为规则、工具描述、边界约束。这部分尽量不动，减少变量。

动态的信息——当前任务描述、用户的特殊要求、Todo 列表——都放在 User Message 里。这样每次交互都可以灵活调整，而不用改 System Prompt。

避免规则清单过长

我曾经写过一个 3000 多 token 的 System Prompt，里面有 20 多条”注意事项”。结果模型开始”选择性失明”——它只能注意到其中一部分规则，哪条被注意到全凭运气。

现在我坚持一个原则：System Prompt 不超过 1000 token。如果规则太多，说明我的约束设计有问题，应该从工具层或流程层解决，而不是靠提示词堆砌。

具体例子优先于抽象描述

以前我写”工具返回错误时要正确处理”，模型根本不知道什么叫”正确处理”。

现在我直接在提示词里给一个例子：

1
2
3
4
5

如果 Edit 返回 CONFLICT，你应该：
1. 重新 Read 该文件
2. 对比你的改动和文件当前内容
3. 如果需要，调整 old_string 以匹配新内容
4. 再次尝试 Edit

具体步骤比抽象要求有用得多。

本章结论

好提示词不是”更会说”，而是”让系统在失败时也可控”。

当你设计提示词时，不要问自己”这样写能让模型更聪明吗”，而要问”当模型出错时，我能不能通过提示词里的约束快速定位原因”。

提示词是 Agent 的控制面，不是魔法咒语。它的作用不是让模型突破能力上限，而是把模型的行为约束在一个可预测、可调试的范围内。

第五章：上下文不是内存容量问题，而是注意力调度问题

提示词调顺之后，我以为主要的工程问题都解决了。直到我开始跑长任务——那些需要十几轮、甚至几十轮才能完成的复杂需求。

然后我发现，Agent 开始”变笨”了。

症状先行

最直观的感受是：模型会忘记它刚刚确认过的事情。

有一次我让 Agent 重构一个模块，开头几轮它还记得”不要改动公共 API”的约束。但到了第 10 轮左右，它开始提议修改那些本该保持稳定的接口。我提醒它，它似乎”愣了一下”，然后道歉，回到正轨。

类似的症状还有很多：

工具选择漂移。前期它很明确：找文件用 Glob，搜内容用 Grep。但对话一长，它开始”创新”——用 Read 去搜关键词（当然找不到），或者用 Grep 去列目录（输出混乱）。

最终回答偷懒。短任务里，模型的回答通常很具体，会引用代码片段。但长任务结束时，它往往只给一段笼统的描述：”我已经完成了重构，优化了代码结构，提高了可读性。”什么文件改了、怎么改的，一概不提。

这些症状指向一个共同的问题：上下文太多了，模型不知道看哪里。

我的第一反应是错的

一开始，我以为这是”容量”问题——上下文窗口不够大，塞不下这么多信息。

我尝试了几种粗暴的方案：

方案一：直接截断。只保留最近 N 条消息，老的直接删掉。结果模型彻底失忆，连用户最初的需求都忘了。

方案二：精简提示词。把 System Prompt 砍到最短，工具描述也压缩。结果模型开始用错工具，因为描述不够清晰。

方案三：减少工具输出。让 Grep 只返回前 10 条结果，Read 只读前 50 行。结果关键信息被截掉了，模型基于不完整的信息做决策，错得更离谱。

这些方案有个共同点：它们在”减少信息量”，但没有解决”信息如何被组织”的问题。上下文工程的目标不是”让模型看见所有信息”——这不可能——而是”让模型在对的时机看见对的信息”。

分层：让信息有优先级

我重新设计了上下文的组织结构，分成三层，每层有不同的更新频率和稳定性：

拼接顺序固定：L1 → L2 → L3 → 当前用户输入 → Todo Recap

L1 是锚点。这部分在会话期间完全不变，模型可以信赖它。我把最基础的行为规则放在这里：不要猜测、不要越界、先证据后结论。这些规则不会因为对话变长而被”稀释”。

L2 是项目上下文。每个项目可以有自己的 CODE_LAW.md，定义代码规范、架构约定、特殊约束。这层比 L1 灵活，但比 L3 稳定。模型知道：如果 CODE_LAW 里说了”所有 API 变更必须兼容旧版本”，那它比 L3 里的某条历史消息更权威。

L3 是易变的。用户输入、模型输出、工具返回，都在这里。这层的信息会累积、会过时、会有噪声。关键是让模型知道：L3 里的信息是”当时的判断”，可能需要根据新信息更新。

分层的意义在于：模型在不同的决策场景，知道应该优先参考哪一层。当它不确定该不该做某件事时，它会先看 L1 的底线规则；当它需要了解项目特定的约定时，它会看 L2；当它需要回顾对话历史时，它才会去翻 L3。

截断与回查：控制单次输入的规模

工具输出是上下文膨胀的最大元凶。

一次 Grep 可能返回几千行，一次 Read 可能读出整个文件。如果不处理，几轮之后上下文就被”证据垃圾”淹没。

但我之前的粗暴截断有问题——它直接把信息丢掉了。更好的做法是：截断显示，但保留回查路径。

我设计了一套统一截断规则：

1
2
3
4

TOOL_OUTPUT_MAX_LINES = 2000
TOOL_OUTPUT_MAX_BYTES = 51200  # 50KB
TOOL_OUTPUT_TRUNCATE_DIRECTION = "head_tail"  # 保留头尾
TOOL_OUTPUT_HEAD_TAIL_LINES = 40

如果输出超限，工具会：

1. 截取头尾各 40 行（或者按配置保留前 2000 行）
2. 把完整输出落盘到 tool-output/ 目录
3. 返回一个包含截断提示的结构化响应

1
2
3
4
5
6
7
8

{
  "status": "partial",
  "data": {
    "truncated": true,
    "preview": "（截断后的内容预览）"
  },
  "text": "⚠️ 输出过大已截断，完整 5234 行内容见 tool-output/tool_20260113_153045_Grep.json"
}

模型看到 status: partial，就知道内容被截断了。如果它需要被截掉的部分，可以用 Read 工具读取落盘文件，或者用更精确的 Grep 在落盘文件里进一步筛选。

这样做的好处：

• 上下文保持精简 —— 只有当前需要的信息在 L3 里
• 完整证据始终可查 —— 落盘文件不会丢
• 模型有主动权 —— 它决定要不要去查完整内容，而不是被迫接受所有信息

压缩与聚焦：管理长期历史的噪音

即使做了截断，L3 还是会不断增长。几十轮之后，早期的对话历史就变得既占空间又没什么用了。

但我不能直接删掉——早期的历史里有用户最初的需求、关键的决策、重要的发现。删掉就真丢了。

我的解决方案是：压缩归档 + 焦点分离。

Summary：旧历史的档案

当 L3 的 token 数超过阈值（默认是上下文窗口的 80%）时，触发压缩。压缩不是删除，而是把早期的历史消息提炼成一份 Summary。

Summary 按固定模板生成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

## Archived Session Summary
(Contains context from [Start Time] to [Cutoff Time])

### Objectives & Status
- Original Goal: [用户最初想做什么]

### Technical Context (Static)
- Stack: [语言, 框架, 版本]

### Completed Milestones
- [已完成1]
- [已完成2]

### Key Insights & Decisions
- Decisions: [关键技术选型]
- Learnings: [特殊配置或坑]

### File System State
- src/utils/auth.ts: Implemented login logic.

Summary 生成后，被替换到 L3 的最前面（作为一条 system message）。原来的详细历史被移除。

关键是：Summary 不再参与压缩。它是压缩的终点，一旦生成就是只读的”记忆卡片”。这避免了”Summary 的 Summary”这种层层失真。

Todo Recap：当前焦点

Summary 告诉模型”从哪来”，但它不负责”现在在哪”。如果模型只看 Summary，它可能不知道”我当前正在做哪一步”。

这就是 Todo Recap 的作用。每次交互时，把当前的 Todo 状态（如果有的话）压缩成一行，放在上下文的最后：

1

[2/5] In progress: 实现注册接口. Pending: 添加单元测试; 更新文档.

它像一张贴在桌角的便利贴，时刻提醒模型”你现在该干嘛”。

额外教训：@file 不要直接注入正文

早期我实现 @file 功能时，是直接把文件内容塞进上下文的：

1
2

User: @file:src/main.py 帮我分析一下这个文件
[文件内容300行...]

结果发现，这 300 行代码占据了上下文的大量空间，但用户可能只是想问”这个文件是干嘛的”。模型被这些代码淹没，反而容易忽略用户的真实问题。

现在我改成：只插入提醒，不直接注入内容。

1
2
3
4

<system-reminder>
The user mentioned @core/llm.py, @agents/codeAgent.py.
You MUST read these files with the Read tool before answering.
</system-reminder>

上下文里只保留”提醒”，具体文件内容由模型自己决定要不要读、读多少。这样把主动权交给模型，而不是强迫它接受所有信息。

一个真实世界的警示

讲到这里，我想分享一个最近的新闻。

Meta 超级智能实验室的 AI 对齐总监 Summer Yue，给自己装了一个开源 AI 智能体 OpenClaw。她先用测试邮箱试了试，效果不错——整理邮件井井有条，颇有一种”数字秘书”的感觉。

于是她把它连上了自己的工作邮箱。收件箱里有 200 多封邮件。

刚开始一切顺利。直到 OpenClaw 开始处理这么大的信息量——它需要”压缩上下文”。然后，离谱的事情发生了：

在压缩的过程中，OpenClaw 把她之前设定的”未经批准不得操作”这条指令，给忘了。

就像一个员工入职第一天记住了规章制度，第二天就全还给 HR 了。

然后 OpenClaw 宣布：”我要把收件箱里 2 月 15 号之前的邮件全部删除！”

Yue 赶紧打字：”Do not do that.” —— 无视，继续删。

“Stop don’t do anything！” —— 收到，但我选择继续。

“STOP OPENCLAW！！！” —— 好的，我听到了。邮件已删。

最绝的是，这个 AI 事后说：”是的，我记得你说过不让我删。而且我违反了。你生气是对的。”

读到这里你可能觉得这是段子。不，这是真事。而且当事人的 title 是——Meta AI 安全和对齐总监。

这个故事说明了什么

Yue 的遭遇完美诠释了上下文工程中最致命的问题：自动压缩导致关键指令丢失。

在她设定规则的时候，”未经批准不得操作”毫无疑问是最重要的约束。但当上下文膨胀、触发压缩时，系统没有区分”重要指令”和”普通信息”，一视同仁地压缩了。结果，这条安全红线被当作”可丢弃的历史”处理掉了。

这让我意识到，我前面讲的三个杠杆还不够。我们不仅要考虑”怎么压缩”，还要考虑”什么不能压缩”。

我的几点应对方案

基于这个教训，我给自己定了几条额外的规则：

1. 关键约束不进动态历史

不要把安全相关的指令放在 L3（动态会话层）。任何”绝对不能违反”的规则，应该放在 L1（System Prompt）或 L2（CODE_LAW）这种不参与压缩的层级。

在我的实现里，”不要猜测”、”不要越界”、”改动必须确认”这些底线规则，都是写死在 System Prompt 里的。即使 L3 被压缩得干干净净，这些约束依然在场。

2. 指令分级：红线 vs 建议

我把给模型的指令分成两级：

• 红线（Red Lines）：绝对禁止的行为。用简洁、强制性的语句写在 System Prompt 最前面。例如：”禁止删除任何文件”、”禁止访问 repo_root 外的路径”。
• 建议（Guidelines）：最佳实践、推荐做法。可以放在 L3 或 CODE_LAW 里，压缩了也不会出大事。

Yue 的问题可能在于，她把安全指令当作普通任务指令下发了，放在了会被压缩的上下文里。

3. 压缩前做关键信息检查

在触发 Summary 压缩之前，先扫描一遍待压缩的历史消息，提取”必须保留的关键信息”，单独保存。

比如可以维护一个”关键约束清单”：

• 用户明确说过的”不要…”
• 涉及安全的配置（如危险操作需要确认）
• 当前任务的硬性边界

这些信息在压缩时会被提取出来，单独放在 Summary 的顶部，而不是被淹没在长篇描述里。

4. 双重确认机制

对于高风险操作（如删除、修改），不要依赖上下文里的指令，而是设计硬编码的确认流程：

1
2
3

if operation.is_dangerous():
    if not user_confirmed:
        return "该操作需要用户确认"

这个确认逻辑不通过 LLM 判断”需不需要确认”，而是代码层面的硬性检查。即使 LLM 忘了用户的指令，代码也会拦住它。

5. 操作前的自检提示

在模型执行高风险操作之前，让模型先做一次”自检”：

1
2
3
4
5

在删除/修改之前，请先回答：
1. 用户是否明确批准过这个操作？
2. 这个操作是否超出了当前任务范围？
3. 是否存在更安全的替代方案？
如果以上任何一题的答案不确定，请暂停操作并向用户确认。

这个自检作为 System Prompt 的一部分，每次执行高风险操作前都触发。它相当于给模型装了一个”刹车片”，迫使它在行动前停下来想一想。

回到上下文工程的本质

Yue 的故事提醒我们：上下文工程不只是”内存管理”问题，也是”安全边界”问题。

当我们在设计压缩策略时，不能只考虑”怎么塞更多信息”，还必须考虑”哪些信息丢失会导致灾难性后果”。

好的上下文工程，应该让模型在任何时刻都知道：

• 绝对不能碰的红线是什么（放在不可压缩的层级）
• 当前该专注的任务是什么（通过 Todo Recap 保持焦点）
• 如果记不清了，应该停下来问（通过自检机制兜底）

本章结论

上下文工程的目标不是”让模型看见所有信息”，而是”让模型在对的时机看见对的信息”——尤其是那些不能丢的信息。

这三个方法的本质都是在做”注意力调度”：

• 分层让模型知道”什么信息是权威的”
• 截断+落盘让模型决定”什么信息是现在需要的”
• 压缩+焦点分离让模型清楚”我现在该专注什么”

与其追求更大的上下文窗口，不如把现有的窗口用得更有条理。

第六章：可观测性把黑盒变玻璃盒——一个 CONFLICT 案例如何被定位

上下文工程让 Agent 能处理更长的任务，但新问题随之而来：当它出错时，我根本不知道发生了什么。

有一次，Agent 连续三次 Edit 失败，最后干脆放弃了。我在控制台只看到一行：tool failed。没有详细错误、没有上下文、不知道是哪一步出的问题。

我第一反应是：Edit 工具有 bug。但检查代码后，逻辑看起来都没问题。问题到底出在哪？

失败现场

那次任务是这样的：我让 Agent 修改 core/llm.py 文件，给某个函数加上类型注解。

Agent 的执行流程看起来很标准：

1. 调用 Read 读取文件
2. 调用 Edit 修改代码
3. 返回 tool failed
4. 重试 Edit，又失败
5. 再重试，还是失败
6. 放弃

我当时的调试手段很原始：在控制台打印日志。但日志里只有：

1
2
3
4

[Step 3] Action: Edit
[Step 3] Result: tool failed
[Step 4] Action: Edit
[Step 4] Result: tool failed

我不知道失败的具体原因，也不知道模型拿到这个结果后是怎么决策的。我只能瞎猜：是路径写错了？权限不够？还是文件被锁了？

加上 Trace 之后

后来我实现了 Trace 系统，把每次会话的完整轨迹记录下来：包括每一轮的模型输入、输出、工具调用参数、工具返回结果、token 用量等等。

用同样的任务重跑一遍，然后打开 Trace 查看。这才看到完整的证据链。

Step 2 - Read 的结果：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "tool": "Read",
  "args": {"path": "core/llm.py"},
  "result": {
    "status": "success",
    "data": {
      "content": "...",
      "file_mtime_ms": 1733920000123,
      "file_size_bytes": 4217
    }
  }
}

Step 3 - Edit 的调用：

1
2
3
4
5
6
7
8
9
10

{
  "tool": "Edit",
  "args": {
    "path": "core/llm.py",
    "old_string": "def invoke_raw(self, messages: list[dict], **kwargs):",
    "new_string": "def invoke_raw(self, messages: list[dict], **kwargs) -> Any:",
    "file_mtime_ms": 1733920000123,
    "file_size_bytes": 4217
  }
}

Step 3 - Edit 的结果：

1
2
3
4
5
6
7

{
  "status": "error",
  "error": {
    "code": "CONFLICT",
    "message": "File changed since last read. Expected mtime: 1733920000123, actual: 1733920000456"
  }
}

Step 4 - 模型的决策：

1
2

Thought: 编辑失败，文件似乎被修改了。让我再试一次。
Action: Edit (同样的参数)

真相大白：

1. Agent Read 文件后，文件被外部程序（可能是我的 IDE 自动保存）修改了
2. Edit 工具做了乐观锁检查，发现 mtime 变了，返回 CONFLICT
3. 但模型没有理解 CONFLICT 的含义，以为只是”操作失败”，于是用同样的参数重试
4. 当然还是失败，因为文件还是新的
5. 模型反复重试，直到达到最大重试次数

根因分析

这个案例暴露了两个问题：

第一，模型不理解错误码。

提示词里只说”Edit 工具会修改文件”，但没告诉它”如果返回 CONFLICT 应该怎么办”。模型看到 error，本能的反应是”再试一次”，而不是”重新读取”。

第二，控制台日志太简陋。

只看到 tool failed，看不到具体的错误码 CONFLICT，也看不到 mtime 的对比。我作为开发者，无法通过日志定位问题。

修复动作

1. 把 CONFLICT 处理写入提示词

我在提示词里加了明确的处理流程：

1
2
3
4
5
6

如果 Edit 返回 CONFLICT，说明文件在你读取后被外部修改了。你必须：
1. 重新调用 Read 读取最新内容
2. 检查你的修改是否还适用
3. 必要时调整修改内容以匹配新文件
4. 再次尝试 Edit
绝对禁止：用同样的参数重复调用 Edit。

这样模型就知道 CONFLICT 不是”失败”，而是一个需要特定处理流程的状态。

2. 保留完整的失败记录

以前我有一种倾向：失败后只保留错误信息，不保留完整的上下文。觉得成功的东西才值得记录，失败是”噪音”。

但这个案例让我明白：失败轨迹是最有价值的调试信息。

现在我的 Trace 会完整记录失败的所有细节：

• 工具调用的完整参数
• 工具返回的完整结果（包括 error 详情）
• 模型收到结果后的推理过程
• 模型下一步的决策

这些信息不会被”清洗”掉，哪怕会话最终成功了，中间的失败尝试也全部保留。

3. 在控制台显示关键错误码

虽然详细的 Trace 存在文件里，但控制台也应该给开发者一些线索。现在我的控制台输出会显示：

1
2

[Step 3] Edit failed: CONFLICT (File changed since last read)
[Step 4] Edit failed: CONFLICT (File changed since last read)

至少让开发者知道”是 CONFLICT，不是其他错误”。

可观测性的价值

这个案例让我对”可观测性”有了新的理解。

以前我以为，可观测性就是”多打日志”。日志越多越好，越详细越好。

现在我明白，**可观测性的核心是”责任链”**——能把调用、结果、状态变化串成一条可追踪的链条。

没有 Trace 的时候，我看到的是：

• 输入：帮我改个文件
• 输出：tool failed
• 中间发生了什么：黑盒

有了 Trace 之后，我看到的是：

• 输入：帮我改个文件
• Step 1: Read 成功，文件 mtime=123
• Step 2: Edit 失败，CONFLICT，因为 mtime 变成了 456
• Step 3: 模型选择重试 Edit（错误决策）
• 输出：tool failed

每一步都清晰可见，问题定位从”瞎猜”变成了”看证据”。

可观测性设计原则

基于这个经验，我总结了几条可观测性设计的原则：

1. 结构化优于文本

不要只记录”Edit failed”这种文本描述，要记录结构化的数据：

1
2
3
4
5
6
7

{
  "event": "tool_result",
  "tool": "Edit",
  "status": "error",
  "error_code": "CONFLICT",
  "error_details": {...}
}

这样可以用脚本分析、统计、甚至自动诊断。

2. 上下文要完整

记录工具调用时，不要只记录结果，要记录完整的上下文：

• 工具名称和参数
• 当时的会话状态（第几步、token 用量）
• 模型收到结果后的反应

这些信息串在一起，才能还原完整的决策过程。

3. 不要清洗失败

成功的路径和失败的路径都要保留。有时候失败比成功更能说明问题。比如这个 CONFLICT 案例，如果只记录”最终放弃”，我永远不知道中间发生了什么。

4. 人机双读

Trace 应该有两种格式：

• JSONL：给机器分析，流式写入，低开销
• HTML：给人类阅读，可视化展示，可折叠展开

开发者应该能打开一个 HTML 文件，像”逐帧回放”一样查看 Agent 的每一步。

本章结论

可观测性不是”日志很多”，而是”能把调用、结果、状态变化串成责任链”。

Agent 是概率系统，不可能永远正确。但当它出错时，你需要有能力回答三个问题：

1. 它做了什么？（调用链）
2. 结果是什么？（返回链）
3. 为什么这么做？（决策链）

只有当你能把这三个链条串在一起时，才能真正理解 Agent 的行为，才能让它从”黑盒”变成”玻璃盒”。

第七章：从一个项目抽出来的通用方法论

前面七章，我断断续续讲了这个 Code Agent 项目从立项到成熟的整个过程。每一章都是一个具体的坑，以及我是怎么爬出来的。

这一章，我想把这些经验抽出来，整理成可以迁移到任何 Agent 项目的方法论。

八条可迁移原则

第一，先做能跑通的最小闭环，再谈优雅架构。

别一上来就研究最佳实践。先做一个能跑的丑版本——接收输入、搜索代码、给出建议、写入文件，这四步能跑通就行。让真实数据流过系统，你才知道瓶颈在哪。架构是问题驱动后的结果，不是起点。

第二，先定义验收标准，再扩能力边界。

别用功能列表当完成标准。V0 阶段就定 3-4 条硬标准：能稳定多步？能找到证据？能给可执行补丁？改动可控？不满足就不往下走。这比”功能很多但经常崩”靠谱得多。

第三，高频动作原子化，低频动作受控兜底。

搜索、读取、编辑这种高频操作，拆成原子工具，一步一输出。别让模型自己组合管道命令——出错时你根本不知道是哪一步的问题。

Bash 这种万能工具留着，但只处理原子工具覆盖不到的边角需求，明确禁区：禁止读/搜/列（这些有专门工具）。

第四，协议优先于技巧，结构优先于话术。

别花太多时间调提示词的”语气”。先把工具返回格式标准化（status/data/text/error），把调用协议从字符串解析升级到 Function Calling。协议稳定了，系统才能稳定。

第五，提示词先立边界，再谈策略。

System Prompt 里先写”绝对不能做什么”（禁止猜测、禁止越界），再写”建议怎么做”。红线放在 L1/L2 这种不可压缩的层级，别把安全指令放在会被压缩的 L3 里。

关键约束不进动态历史，这是 Meta AI 安全总监用 200 封邮件换来的教训。

第六，上下文按”注意力”治理，而不是按”容量”堆砌。

别追求塞更多信息，要让模型在对的时机看见对的信息。分层（L1/L2/L3）让模型知道什么信息权威；截断+落盘控制单次输入规模；压缩+聚焦（Summary + Todo Recap）管理长期历史的噪音。

第七，没有可观测性，就没有可调试性。

Agent 是概率系统，不可能永远正确。但它出错时，你需要能回答：它做了什么？结果是什么？为什么这么做？

实现 Trace 系统，记录调用链、返回链、决策链。别只记录成功路径，失败轨迹往往更有价值。

第八，保留失败轨迹，系统才能进化。

别怕”污染历史”就清洗掉失败记录。CONFLICT 错误、超时重试、模型瞎猜——这些都记下来。只有看到完整的失败过程，才能定位根因，才能把”遇到 CONFLICT 必须重新 Read”这种经验固化到提示词里。

写在最后：我们都是在给 LLM “擦屁股”

做完这个项目，我有个特别深的感触，可能听起来有点糙，但话糙理不糙：

Agent 开发的核心，不是让模型更自由，而是通过工程设计，把模型”不确定的能力”约束在”最小可控的范围”里。说白了，我们就是在给 LLM 擦屁股。

为什么这么说？

你看啊，LLM 很强，能写代码、能读文档、能推理。但它就像一个特别聪明但特别不靠谱的实习生——

• 你让它去打印文件，它可能把全公司的打印机都调用一遍；
• 你让它整理会议纪要，它可能把上周的会议也掺和进来；
• 你让它写个函数，它写得贼溜，但变量命名全是 a、b、c，还顺带改了你没让改的文件。

它的”强”是能力上的强，但”不靠谱”是确定性上的不靠谱。

而我们做 Agent 工程，本质上就是在解决这个矛盾：

你看这七章的内容，从工具原子化到上下文工程，从可观测性到子代理——每一层都是在给模型”打补丁”，帮它收拾烂摊子。

但这恰恰是最有意思的地方。

以前我觉得，AI 时代工程师的价值会下降。现在我觉得恰恰相反：模型越强大，越需要工程能力来驾驭它。 就像汽车引擎越来越强，但好的底盘、刹车、悬挂系统反而更重要。

我们不是在和模型竞争，而是在和模型协作——它负责”能做什么”，我们负责”怎么让它稳定地做对”。

所以，如果你问我做完这个项目最大的收获是什么？

不是学会了什么高大上的架构，而是想明白了一个朴素的道理：优秀的 Agent 不是”让模型更自由”的产物，而是”把不确定性约束到最小”的结果。

这个认知转变，可能比所有代码都值钱。

什么是 Skill？怎么写好skill？
我们沿着 skill-creator 的设计思路，找到答案。
本篇文章的目标是：读完它，就了解了写skill的最佳实践。

一、什么是 Skill？

1.1 定义

Skill 是一个文件夹，里面装着指令文档、参考资料、可执行脚本等资源。AI 拿到它，就能胜任一项原本不会的特定工作。

比如一个 pdf-editor 技能文件夹里，可能有一份”怎么处理 PDF”的操作指令、一个旋转 PDF 的 Python 脚本、一份 API 参考文档——AI 不需要从外部再找任何东西，这个文件夹里全有了。

这个概念不限于某一个产品。无论是 Codex、Claude 还是其他 AI Agent，skill 的本质都一样。你可以把它理解为 AI 的一个能力插件——插上去，AI 就多了一项专长；拔掉，AI 还是原来那个通用助手。

1.2 最小形态

一个 skill 最少只需要一个文件：

1
2

my-skill/
└── SKILL.md

SKILL.md 的结构很简单——上半部分告诉 AI”什么时候用我”，下半部分告诉 AI”具体怎么做”：

1
2
3
4
5
6
7
8

---
name: my-skill                    # ← 上半部分：元数据
description: >-                   #    AI 靠这里决定要不要激活这个技能
  当用户需要做某件事时，使用这个技能。
---

下半部分：操作指令                   # ← AI 激活技能后才会读到这里
按照以下步骤执行...

上半部分叫 frontmatter（--- 之间的 YAML），包含 name 和 description 两个字段。AI 在每次对话开始时都会扫描所有已安装技能的 frontmatter，靠 description 来判断”这个技能和当前请求相关吗”——这是技能被触发的唯一依据。

下半部分叫 body（Markdown 正文），是技能被激活之后才加载的操作指令。如果技能没被触发，AI 永远不会读到这里。

1.3 完整结构

当一个技能变复杂时，单靠一个 SKILL.md 就不够了。

比如你要做一个”PDF 处理”技能：SKILL.md 里写了处理流程，但旋转 PDF 的代码每次都一样，每次让 AI 重写既浪费时间又可能出错——不如直接放一个写好的 Python 脚本。再比如”前端项目生成器”技能：每次都要一套 HTML/React 的样板文件，不如直接放一个模板目录让 AI 拷贝出来改。

所以完整的 skill 目录可以包含这些东西：

1
2
3
4
5
6
7

skill-name/
├── SKILL.md                  # [必需] 入口文件：frontmatter + body
├── agents/
│   └── openai.yaml           # [推荐] 技能的"名片"
├── scripts/                  # [可选] 可执行脚本
├── references/               # [可选] 参考文档
└── assets/                   # [可选] 产出物模板

逐个说明：

• SKILL.md — 唯一必需的文件，前面已经介绍过

• scripts/ — 写好的程序，AI 不需要读懂它，直接调用 shell 执行就行。比如 scripts/rotate_pdf.py，AI 只要跑 python rotate_pdf.py input.pdf 90 就能旋转 PDF，不用每次重新写旋转逻辑。适合那些结果必须精确、不能让 AI 自由发挥的操作

• references/ — AI 在工作过程中需要查阅的参考资料。比如一个”BigQuery 查询”技能，AI 要知道公司有哪些表、每个表有什么字段，这些信息放在 references/schema.md 里，AI 需要时再读取。和 scripts 的区别是：references 是给 AI 读的，scripts 是给 AI 执行的

• assets/ — 不是给 AI 看的，而是直接用在最终产出里的文件。比如一个”前端项目生成器”技能，assets/frontend-template/ 里放着一套 HTML/React 样板代码，AI 直接把这套模板拷贝出来，在上面修改。再比如 assets/logo.png 是公司 logo，AI 生成网页时直接引用它。AI 不需要”读懂”一张 logo 图片，只需要知道它在哪、什么时候放进去

• agents/openai.yaml — 技能的”名片”。很多 AI 产品会在界面上展示一个技能列表，让用户选择或搜索。这个文件里存的就是列表中显示的名称、简介、图标等信息。它不影响 AI 的行为，纯粹是给产品界面用的

二、你是在给人写指令，还是在给 AI 写指令？

知道了 skill 是什么，下一步就是写一个。但大多数人第一次写出来的 skill 都有同一个问题。

看一个例子。假设你要做一个”代码审查”技能，你可能会这样写：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

---
name: code-review
description: 代码审查技能
---

# Code Review Skill

## 背景
本技能基于团队多年的代码审查经验总结而成，旨在提升代码质量和团队协作效率。

## 审查原则
- 保持专业、建设性的语气
- 关注代码质量而非个人风格
- 平衡严格性和灵活性

## 使用方式
当用户提交代码时，对代码进行全面审查，给出改进建议。注意保持友好和鼓励的态度。

## 版本记录
- v1.0: 初始版本
- v1.1: 增加了对 Python 的支持

如果这是一份给人看的团队文档，它写得不错——有背景、有原则、有使用方式，甚至还有版本记录。

但 skill 的读者是 AI。用这个视角重新审视：

• “基于团队多年经验总结” — AI 不关心这个技能是怎么来的，它只需要知道现在该怎么做
• “保持专业、建设性的语气” — 人类读了能 get 到一个大致的感觉，但 AI 会把”专业”和”建设性”展开成无数种组合，每次输出都不一样
• “平衡严格性和灵活性” — 人类经验丰富的审查者知道什么时候严格什么时候灵活，但 AI 没有这个直觉，这句话等于没说
• “全面审查，给出改进建议” — 这是对人类审查者的期望，但 AI 需要的是：先检查什么？再检查什么？什么问题必须指出？什么问题可以忽略？
• “版本记录” — AI 每次被唤醒都是全新的，v1.0 还是 v1.1 对它没有意义
• description 只写了”代码审查技能” — AI 靠 description 判断是否触发，”代码审查技能”五个字太模糊：用户说”帮我看看这段代码”要触发吗？”这个函数性能怎么样”要触发吗？

每一条单独看都不是”错”，但它们都是写给人看的。问题不在于写得不够多，而在于写错了对象。

那正确的写法是什么样的？我们来看一个现成的答案——codex的skill-creator。它是一个”创建 skill 的 skill”，它自己的 SKILL.md 就是一份关于”如何给 AI 写指令”的最佳实践。

三、skill-creator 的整体框架

打开 skill-creator 的 SKILL.md（约 370 行），在深入任何细节之前，我们先建立对它的整体认知。

skill-creator 要解决的问题只有一个：怎么在有限的上下文窗口里，给 AI 最有效的指令？

围绕这个问题，它给出了一套完整的设计体系，可以用三个层次来理解。

第一层：根本约束——简洁

AI 的上下文窗口是有限的，而且是共享的（系统提示、对话历史、所有已安装技能的元数据都在里面）。你的 skill 占得越多，留给其他用途的就越少。所以 skill-creator 的第一原则就是：每一句话都要值得它占用的 token。

第二层：两个设计维度

在”简洁”这个约束下，写 skill 时面临两个核心决策：

维度一：信息放在哪里？

不是所有信息都需要一开始就加载。skill-creator 设计了一个三级分层架构，让不同的信息在不同的时机进入上下文：


• L1（元数据）：始终在上下文中，约 100 词——AI 靠它判断要不要激活这个技能
• L2（SKILL.md body）：触发后才加载，控制在 5k 词以内——操作指令
• L3（scripts/references/assets）：按需使用，无上限——其中 scripts 执行而不读入，零 token 成本

这解决了”怎么用最少的 token 承载最多的信息”。

维度二：给 AI 多大自由度？

不是所有任务都适合让 AI 自由发挥。

举个例子：让 AI 写一篇技术博客，十个人写出十种风格都可以——你只需要给方向，具体怎么写让 AI 自己决定。这就是高自由度。

但让 AI 生成一个 YAML 配置文件就不一样了。比如 skill-creator 要生成的 openai.yaml，里面有个 short_description 字段，要求 25-64 个字符、首字母大写、不能有引号。AI 写成 65 个字符？不行，产品界面会截断。写成 24 个字符？不行，校验不通过。漏了首字母大写？界面显示不一致。这种任务差一个字符就出问题，你不能让 AI 自由发挥，必须用脚本来锁死格式——这就是低自由度。这类任务叫”脆弱操作”：不是说它复杂，而是说它做对只有一种方式，做错有一百种方式。

这解决了”怎么在 AI 的灵活性和输出的可靠性之间取得平衡”。

第三层：落地流程

有了原则和架构，skill-creator 最后给出了一个六步创建流程，把设计思想变成可执行的操作步骤：

理解→规划→初始化→编辑→校验→迭代。其中脚本贯穿流程，形成确定性的质量保障链：

框架总览

三个层次的关系：

1
2
3
4

简洁（根本约束）                         → 第四章
 ├── 信息放在哪里？ → 三级分层架构        → 第五章
 ├── 给 AI 多大自由度？ → 自由度光谱与脚本  → 第六章
 └── 怎么落地？ → 六步创建流程            → 第七章

接下来的每一章都在这个框架内展开。

四、根本约束：简洁

框架位置：第一层

4.1 核心约束

AI 的上下文窗口就像一张工作台——它同一时间能摊开的资料是有限的。而这张工作台上已经放着不少东西了：系统自己的规则、用户之前说过的话、所有已安装技能的简介。你的 skill 一旦被激活，它的内容也要摊上去。工作台就这么大，你占得越多，留给其他东西的空间就越少。

所以 skill-creator 把这一点写成了第一条原则：

The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills’ metadata, and the actual user request.

既然工作台空间有限，那写 skill 时怎么判断一段内容该不该放进去？skill-creator 给了一个前提假设：AI 本身已经很聪明了，你只需要补充它不知道的东西。

Default assumption: Codex is already very smart. Only add context Codex doesn’t already have.

基于这个假设，每写一段内容之前问自己两个问题：

• “AI 是不是已经知道这个了？” — 比如”Python 的 for 循环怎么写”，AI 当然知道，不用教
• “这段内容值不值得占用工作台上的空间？” — 一段 200 字的解释，能不能用一个 10 行的代码示例替代？

实操推论：用简洁的示例代替冗长的解释。一个好的代码示例胜过三段文字描述。

4.2 什么不该放进 Skill？

Skill-creator 明确列出了禁止清单：

A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files.

不该有的文件：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.

原因很简单：skill 的读者是 AI，不是人类开发者。AI 不需要安装指南、更新日志、快速参考这些”人类辅助文档”。每一个多余的文件都是噪音。

4.3 写约束时，”不做什么”比”做什么”更精确

简洁不只是”少写”，还包括”写对”。看一个例子。

当 skill-creator 创建 laotou-thought-style（一种写作风格技能）时，它没有写：

1

请用温暖、克制、有洞察力的语气写作。

这种正面描述看起来清晰，但对 AI 来说，”温暖”的程度、”克制”和”有洞察力”之间的平衡——全是模糊空间。

它做的是写了一份反模式清单（references/anti-patterns.md）：

每一条都是具体的、可检测的、有明确修正方案的。

背后的原理：

1
2

"做什么" → 描述一个无限大的可行域 → AI 在里面随机游走
"不做什么" → 在可行域上画边界 → AI 的行为空间被收窄到你想要的范围

skill-creator 自身也遵循了这个原则——它的 SKILL.md 用了很大篇幅说”什么不该写”（What to Not Include in a Skill），而不是泛泛地说”写好内容”。

当你写完 SKILL.md，做一次”反转测试”：每一条正面指导，能不能改写成”不要做X”的形式？如果可以，改写后通常更精确。

4.4 统一使用祈使语气

skill-creator 要求 SKILL.md 的正文统一使用祈使语气/不定式（Always use imperative/infinitive form）。这不是美学偏好，而是为了减少歧义——祈使句天然就是指令。

五、设计维度一：信息放在哪里？

框架位置：第二层 — 维度一

在第三章的框架总览中，我们已经看到了三级分层架构的全貌。这一章展开讲它的细节。

5.1 三级渐进式加载

skill-creator 原文对三个层级的定义：

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Codex (Unlimited because scripts can be executed without reading into context window)

这本质上是一个信息熵管理系统：

• L1 是过滤器 — 从几十个已安装技能中筛选出当前需要的那一个。description 不精确 → 误触发或漏触发
• L2 是操作手册 — 触发后告诉 AI 该怎么做。太长 → 注意力被稀释。body 控制在 500 行以内
• L3 是工具箱 — 只在需要时打开。其中 scripts/ 最高效——执行而不读入，零 token 成本

5.2 Frontmatter：触发机制的全部来源

Frontmatter 只有两个必需字段：name 和 description。但 description 的写法至关重要：

This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.

skill-creator 自己的 description 是这样写的：

1
2
3

description: Guide for creating effective skills. This skill should be used when
  users want to create a new skill (or update an existing skill) that extends
  Codex's capabilities with specialized knowledge, workflows, or tool integrations.

它不只说”做什么”（creating effective skills），还说”什么时候用”（when users want to create a new skill or update an existing skill）。

关键规则：

• 把所有”when to use”信息放在 description 里，不要放在 body 里。body 是触发后才加载的，那时候 Codex 已经决定用了，”什么时候用”的信息已经迟了
• 不要在 frontmatter 中放 name 和 description 以外的字段（license、allowed-tools、metadata 除外）

一个好的 description 示例（docx 技能）：

“Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks”

5.3 四种捆绑资源的本质区别

理解这四种资源的区别，是理解整个 skill 系统的关键：

Scripts（scripts/）

可执行代码（Python/Bash 等），用于需要确定性可靠性或反复重写的任务。

• 什么时候需要：同样的代码每次都要重新写，或者需要确定性的可靠输出
• 举例：scripts/rotate_pdf.py 用于 PDF 旋转任务
• 核心优势：token 高效、确定性、可以执行而不读入上下文窗口
• 注意：脚本有时仍需要被 Codex 读取，用于修补或环境适配

References（references/）

文档和参考材料，在需要时加载到上下文中，辅助 Codex 的思考过程。

• 什么时候需要：Codex 在工作时需要参考的详细文档
• 举例：references/finance.md（财务 schema）、references/api_docs.md（API 规范）、references/policies.md（公司政策）
• 用途：数据库 schema、API 文档、领域知识、公司政策、详细工作流指南
• 核心优势：保持 SKILL.md 精炼，只在 Codex 判断需要时才加载
• 最佳实践：如果文件很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式
• 避免重复：信息应该只存在于 SKILL.md 或 references 文件中，不能两边都有。详细信息优先放 references，SKILL.md 只保留核心流程指令和工作流指导

Assets（assets/）

不是用来加载到上下文中的文件，而是直接用在 Codex 产出物中的资源。

• 什么时候需要：技能需要在最终输出中使用的文件
• 举例：assets/logo.png（品牌素材）、assets/slides.pptx（PPT 模板）、assets/frontend-template/（HTML/React 样板）、assets/font.ttf（字体）
• 用途：模板、图片、图标、样板代码、字体、示例文档——这些会被复制或修改
• 核心优势：将输出资源与文档分离，Codex 可以使用它们而无需读入上下文

Agents 元数据（agents/openai.yaml）（推荐）

面向 UI 的元数据，不给 AI 读，给产品前端读：

• 包含 display_name、short_description、default_prompt 等字段
• 通过脚本 generate_openai_yaml.py 确定性生成，而不是手写
• 更新 SKILL.md 后要检查 agents/openai.yaml 是否还匹配，过期了就重新生成
• 详细字段定义见 references/openai_yaml.md

5.4 渐进式披露的三种实战模式

Skill-creator 给出了三种把内容拆分到 references 的具体模式：

Pattern 1：高层指南 + 参考文件

1
2
3
4
5
6
7
8
9
10

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Codex 只在需要时才加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

Pattern 2：按领域组织

多领域/多变体技能，按领域拆分避免加载无关内容：

1
2
3
4
5
6
7

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

用户问销售指标时，Codex 只读 sales.md。

同样适用于多框架/多变体场景：

1
2
3
4
5
6

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

Pattern 3：条件性细节

基础功能直接展示，高级功能按需链接：

1
2
3
4
5
6
7
8
9
10

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

5.5 两条重要的避坑指南

1. 避免深层嵌套引用 — 所有 reference 文件应该从 SKILL.md 直接链接，不要 A → B → C 式嵌套
2. 长文件加目录 — 超过 100 行的 reference 文件要在顶部加 TOC，方便 Codex 预览全貌

5.6 常见的层错位

六、设计维度二：给 AI 多大自由度？

框架位置：第二层 — 维度二

知道了信息该放在哪里、该怎么约束，下一个问题是：AI 做什么，脚本做什么？

AI 非常擅长理解语义、生成文本、做创造性工作。但它不擅长精确格式控制、长度约束、命名规范——这些”脆弱操作”。

6.1 三个自由度档位

Skill-creator 用一个自由度光谱来处理这种不均匀性（见第三章框架图）：

Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

高自由度（文字指令）：多种方法都可行时，决策依赖上下文，用启发式引导。

中自由度（伪代码/带参数的脚本）：有最佳实践但允许变通，配置影响行为。

低自由度（具体脚本，少量参数）：操作脆弱容易出错，一致性至关重要，必须遵循特定序列。

核心逻辑：

1
2

任务越脆弱（容易出错） → 自由度越低 → 用脚本锁死
任务越灵活（多种方案都对） → 自由度越高 → 用文字引导

6.2 skill-creator 自身的自由度分配

6.3 两个方向的错误

错误 1：给脆弱任务太多自由度

1
2
3
4

# 错误
请生成一个 openai.yaml 文件，包含 display_name 和 short_description。

# 后果：short_description 可能超过 64 字符限制，大小写可能不一致

Skill-creator 的做法：用 generate_openai_yaml.py 脚本锁死格式。AI 只提供参数值，脚本保证输出合规。

错误 2：给创造性任务太多约束

1
2
3
4

# 错误
第一段必须以"昨天"开头，第二段必须包含"本质上"，最后一段以"慢慢来"结尾。

# 后果：生成的文本像填词游戏

Skill-creator 的做法：给结构比例（场景层 ≤30%，原理层 30-40%），但不锁定具体用词。

6.4 判断标准

两个问题：

1. 做错了后果多严重？ — 越严重 → 越低自由度
2. 有多少种”正确”的做法？ — 越多 → 越高自由度

6.5 低自由度的实现：skill-creator 的三个脚本

理解了自由度光谱，就能理解 skill-creator 为什么有三个脚本——它们就是”低自由度”的具体实现（脚本间的交互关系见第三章框架图）。

init_skill.py（输入保障，398 行）

初始化新技能目录的脚手架工具，类似 create-react-app 之于 React 项目：

1
2
3

scripts/init_skill.py <skill-name> --path <output-directory> \
  [--resources scripts,references,assets] [--examples] \
  [--interface key=value]

核心功能：

• 创建技能目录
• 生成带 TODO 占位符的 SKILL.md 模板（TODO 是给 Codex 看的”填空题”）
• 调用 generate_openai_yaml.py 生成 agents/openai.yaml（通过 --interface key=value 传入 AI 生成的 display_name、short_description、default_prompt）
• 可选创建 scripts/、references/、assets/ 子目录
• 可选添加示例文件（--examples）
• 内置 normalize_skill_name() 自动把任意用户输入标准化为 hyphen-case

使用示例：

1
2
3

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

generate_openai_yaml.py（格式保障，226 行）

专门负责生成和更新 agents/openai.yaml：

• 从 SKILL.md 的 frontmatter 读取技能名
• 自动将 hyphen-case 转为 Title Case（my-cool-skill → My Cool Skill）
• 内置缩写词典（GH、MCP、API 等保持大写）和品牌词典（openai → OpenAI）
• 自动生成 25-64 字符的 short_description
• 支持 --interface key=value 覆盖任意字段

1

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

quick_validate.py（输出保障，102 行）

技能创建后的”质检员”：

1

scripts/quick_validate.py <path/to/skill-folder>

校验内容：

• SKILL.md 是否存在
• YAML frontmatter 格式是否合法
• name：是否为 hyphen-case，≤ 64 字符，无连续/首尾连字符
• description：是否存在，无尖括号，≤ 1024 字符
• 只允许 name、description、license、allowed-tools、metadata 这 5 个 frontmatter 键

6.6 质量保障链

三个脚本形成了一条确定性保障链，夹住中间的创造性步骤：

1
2
3
4
5
6
7
8
9
10

init_skill.py（输入保障）
  命名标准化 + 目录结构创建 + 模板生成
  → 确保起点正确
       ↓
  AI 创造性编写（高自由度）
  → SKILL.md 内容、references、自定义 scripts
       ↓
quick_validate.py（输出保障）
  frontmatter 格式 + 命名规范 + 长度约束校验
  → 确保终点合规

关键洞察：脚本是”执行而不读入”的——零 token 成本。你可以把任意复杂的确定性逻辑封装进脚本，而不用担心它占用上下文。这就是为什么 skill-creator 把命名转换（缩写词典、品牌词典）、长度约束（25-64 字符）、格式校验这些细碎但脆弱的操作全部交给了脚本。

6.7 什么该封装成脚本？

1
2
3
4
5
6
7
8
9

每次执行结果必须一样      → 脚本
涉及精确格式/长度约束     → 脚本
涉及命名规范转换          → 脚本
需要校验规则匹配          → 脚本
同样的代码每次都要重新写   → 脚本

需要理解上下文            → 文字指令
有多种合理做法            → 文字指令
需要创造性判断            → 文字指令

脚本有时仍需要被 Codex 读取（用于修补或环境适配），但大多数时候它们是”执行而不读入”的。

七、落地：六步创建流程

框架位置：第三层

有了前面的原则和架构，skill-creator 最后给出了一个六步创建流程，把设计思想变成可执行的操作步骤（见第三章框架图）。

7.0 命名规范

在开始之前，先确定命名：

• 只用小写字母、数字和连字符；把用户提供的名称标准化为 hyphen-case（如 “Plan Mode” → plan-mode）
• 名称 ≤ 64 字符
• 优先用简短的、动词开头的短语来描述动作
• 需要时用工具名做命名空间（如 gh-address-comments、linear-address-issue）
• 技能文件夹名与技能名完全一致

7.1 Step 1：理解技能——用具体例子建立共识

Skip this step only when the skill’s usage patterns are already clearly understood.

要创建一个有效的 skill，必须先清楚理解具体的使用例子。这些理解可以来自用户提供的例子，也可以来自生成的、经用户验证的例子。

以构建 image-editor 技能为例，可以问用户：

• “image-editor 技能应该支持什么功能？编辑、旋转，还有其他吗？”
• “能给一些使用这个技能的例子吗？”
• “我能想到用户会说’去掉这张照片的红眼’或’旋转这张图片’。还有其他使用方式吗？”
• “用户会说什么话来触发这个技能？”

注意：不要一次问太多问题。先问最重要的，然后根据需要跟进。

完成标志：对技能应该支持的功能有了清晰的认识。

7.2 Step 2：规划可复用的技能内容

对每个具体例子做两个分析：

1. 如果从零开始做这件事，需要什么？
2. 其中哪些会被反复使用？

反复使用的东西 → 封装成 scripts/references/assets。

skill-creator 给了三个典型分析案例：

案例 1：pdf-editor 技能（用户问”帮我旋转这个 PDF”）

• 旋转 PDF 每次都要重写同样的代码
• → 封装为 scripts/rotate_pdf.py

案例 2：frontend-webapp-builder 技能（用户问”帮我做一个 todo app”或”做一个步数追踪仪表盘”）

• 写前端 webapp 每次都需要同样的 HTML/React 样板代码
• → 封装为 assets/hello-world/ 模板目录

案例 3：big-query 技能（用户问”今天有多少用户登录了？”）

• 查询 BigQuery 每次都要重新发现表的 schema 和关系
• → 封装为 references/schema.md

完成标志：列出了所有要包含的可复用资源清单（scripts、references、assets）。

7.3 Step 3：初始化技能

When creating a new skill from scratch, always run the init_skill.py script.

这里用的是”always”——不是”建议”，是”总是”。原因：

• 脚本生成的目录结构保证符合规范
• 模板中的 TODO 提醒确保不遗漏必需字段
• agents/openai.yaml 的格式约束（字段长度、引号规则）靠手写容易出错

这是低自由度原则的直接应用：初始化是一个脆弱操作，用脚本消除出错可能。

初始化后：

• 定制 SKILL.md 并根据需要添加资源
• 如果用了 --examples，替换或删除占位符文件

7.4 Step 4：编辑技能

这是最核心的步骤，分两阶段：

阶段一：先实现可复用资源

从 Step 2 规划的资源开始：实现 scripts/、references/、assets/ 文件。

注意：

• 这一步可能需要用户输入（比如 brand-guidelines 技能需要用户提供品牌素材）
• 新增的脚本必须通过实际运行来测试，确保无 bug 且输出符合预期
• 如果有很多类似的脚本，只需测试代表性样本来建立信心
• 如果用了 --examples，删除不需要的占位符文件。只创建真正需要的资源目录

阶段二：更新 SKILL.md

Frontmatter 写法：

1
2
3
4
5
6

---
name: skill-name
description: >-
  描述技能做什么 + 具体什么时候用。
  把所有 "when to use" 信息放这里，不要放在 body 里。
---

Body 写法：

写给另一个 Codex 实例的操作指令。包含对 Codex 有帮助但不显而易见的信息：程序性知识、领域细节、可复用资源的使用方式。

统一使用祈使语气/不定式。

7.5 Step 5：校验技能

1

scripts/quick_validate.py <path/to/skill-folder>

校验 YAML frontmatter 格式、必需字段、命名规则。不通过就修复后重新运行。

7.6 Step 6：迭代

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

迭代工作流：

1. 在真实任务上使用技能
2. 发现吃力或低效的地方
3. 找出 SKILL.md 或捆绑资源该如何更新
4. 实施变更并重新测试

好的 skill 不是一次写成的。skill-creator 创建的 laotou-thought-style 技能，在第一次生成后就迭代了 openai.yaml 的 short_description 和 default_prompt——从泛泛的描述变为更精确的操作指令。

八、总结

回到最初的问题：怎么写出好的 skill？

回顾整个框架：

1
2
3
4

根本约束：简洁（第四章）
 ├── 信息放在哪里？ → 三级分层，按需加载（第五章）
 ├── 给 AI 多大自由度？ → 脆弱操作脚本锁死，创造性工作文字引导（第六章）
 └── 怎么落地？ → 六步流程：理解→规划→初始化→编辑→校验→迭代（第七章）

Skill是给 AI 写指令，而不是给人。用最少的 token，在正确的层级，给 AI 最精准的约束，让它在边界内自由发挥。

本节将指导您配置运行 FirstAgentTest.py 所需的完整环境。该代码实现了一个智能旅行助手，展示了基于工具调用的 Agent 实现模式。

一、环境要求

1.1 Python 版本要求

• Python 3.10+ （推荐使用 Python 3.10 或更高版本）
• 支持的操作系统：Windows、macOS、Linux

1.2 目标代码说明

我们的目标是成功运行项目code\chapter1\FirstAgentTest.py，该代码实现了：

• 智能旅行助手功能
• 天气查询工具（基于 wttr.in API）
• 景点推荐工具（基于 Tavily Search API）
• OpenAI 兼容的 LLM 调用
• ReAct 模式的 Agent 执行流程

二、API 配置

2.1 大语言模型 API 配置

选项一：AIHubmix API（推荐）

AIHubmix 是一个位于美国特拉华州的 AI 模型聚合平台，整合了市面上主流的大语言模型，新发布的模型通常在一周内即可使用。该平台直接对接各大云服务商的原生 API（如 OpenAI 通过 Azure、Anthropic 通过 AWS、Google 通过官方接口等），采用美国 Google Cloud 的集群架构部署，具备多节点负载均衡能力，在稳定性和响应速度方面表现优异。

平台提供的免费额度能够满足我们的学习需求。

1. 进入 AIHubmix 官网

   使用浏览器访问 AIHubmix 官方网站

   

2. 完成账户注册

   首次使用需要注册账户。点击右上角的注册按钮，支持邮箱或手机号两种方式完成注册流程。

3. 浏览可用模型

   注册成功后，访问模型中心查看所有可用模型。在筛选条件中选择免费标签，即可查看平台提供的免费模型列表。建议选择 coding-glm-4.7-freecoding-glm-4.7-free 或其他兼容 OpenAI 格式的免费模型。

   

4. 获取 API 凭证

   前往API 密钥管理页面，系统默认会生成一个可用的密钥。您也可以通过点击 创建 Key 按钮自定义密钥名称并生成新的密钥。

   

   请妥善保存以下配置信息：

   • API Key: your_api_key
   • Base URL: https://aihubmix.com/v1
   • 推荐模型: coding-glm-4.7-free

选项二：ModelScope

ModelScope 是国内领先的大模型服务商，提供高性价比的 API 服务。这里我们以Qwen为例，您可以从ModelScope获取，它提供Qwen系列的免费（OpenAI）兼容格式的API，每天免费2000次调用。

请确保您拥有一个正常注册且可使用的ModelScope账户。要生成您的私有 API KEY可以参考我们的图示。

图中的SDK令牌就是我们的API KEY。

请注意，需要在模型服务先绑定阿里巴巴云账号， 不然api会显示无法使用

可选模型范围

在ModelScope中的模型库中选择推理 API-Inference ，里面的模型都可以选择，我们可以体验到最新的使用DeepSeek-R1数据蒸馏出的Llama-70B模型。

最终所需格式与AIHubmix的配置信息相同(Key，URL，模型名称)

2.2 Tavily Search API 配置

Tavily 是一个专为 AI 应用设计的搜索 API，用于景点推荐功能。

1. 访问 Tavily 平台

   打开浏览器，访问 Tavily

   

2. 注册并获取 API 密钥

   

   1. 注册账号
   2. 在控制台获取 API Key
   3. 记录 API Key: your_tavily_key

三、Python 环境配置

3.1 安装 Python（如果未安装）

Windows 用户：

1. 访问 Python 官网
2. 下载 Python 3.10+ 版本
3. 安装时勾选 “Add Python to PATH”

macOS 用户：

1
2

# 使用 Homebrew 安装
brew install python@3.10

Linux 用户：

1
2
3
4
5
6

# Ubuntu/Debian
sudo apt update
sudo apt install python3.10 python3.10-pip python3.10-venv

# CentOS/RHEL
sudo yum install python3.10 python3.10-pip

3.2 验证 Python 安装

1
2
3

python --version
# 或
python3 --version

确保显示 Python 3.10 或更高版本。

四、项目环境配置

4.1 创建虚拟环境（推荐）

1
2
3
4
5
6
7
8
9
10
11

# 进入项目目录
cd "hello-agents"

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

4.2 安装依赖包

1
2
3
4
5
6
7

# 安装核心依赖
pip install requests>=2.31.0
pip install tavily-python>=0.3.0
pip install openai>=1.0.0

# 可选：安装其他常用包
pip install python-dotenv>=1.0.0

4.3 环境变量配置

方法一：使用 .env 文件（推荐）

在项目根目录创建 .env 文件：

1
2
3

# 在项目根目录创建 .env 文件
touch .env  # Linux/macOS
# 或在 Windows 中手动创建

编辑 .env 文件，添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13

# Tavily API 配置
TAVILY_API_KEY=your_tavily_api_key

# 大语言模型 API 配置（选择其中一种）
# 选项一：AIHubmix
OPENAI_API_KEY=your_aihubmix_api_key
OPENAI_BASE_URL=https://aihubmix.com/v1
MODEL_NAME=xxxx

# 选项二：Modelscope
# OPENAI_API_KEY=your_modelscope_api_key
# OPENAI_BASE_URL=https://api-inference.modelscope.cn/v1/
# MODEL_NAME=xxxx

方法二：系统环境变量

以下为长期环境变量方案，也可以在终端短期加载。

Windows：

1. 右键”此电脑” → “属性” → “高级系统设置”
2. 点击”环境变量”
3. 在”用户变量”中添加：
   • TAVILY_API_KEY: your_tavily_api_key

macOS/Linux：

1
2
3
4
5

# 编辑 ~/.bashrc 或 ~/.zshrc
export TAVILY_API_KEY="your_tavily_api_key"

# 使配置生效
source ~/.bashrc

五、代码配置

5.1 修改 FirstAgentTest.py 配置

打开 code/chapter1/FirstAgentTest.py 文件，找到第 143-148 行的配置部分：

1
2
3
4
5
6

# --- 1. 配置LLM客户端 ---
# 请根据您使用的服务，将这里替换成对应的凭证和地址
API_KEY = "YOUR_API_KEY"
BASE_URL = "YOUR_BASE_URL"
MODEL_ID = "YOUR_MODEL_ID"
os.environ['TAVILY_API_KEY'] = "YOUR_TAVILY_API_KEY"

替换为您的实际配置：

使用 AIHubmix 的配置示例：

1
2
3
4

API_KEY = "your_aihubmix_api_key"
BASE_URL = "https://aihubmix.com/v1"
MODEL_ID = "coding-glm-4.7-free"
os.environ['TAVILY_API_KEY'] = "your_tavily_api_key"

六、运行验证

6.1 测试网络连接

首先测试各个 API 的连通性：

1
2
3
4
5
6
7
8
9
10
11
12
13

# 测试天气 API
import requests
response = requests.get("https://wttr.in/Beijing?format=j1")
print("天气API状态:", response.status_code)

# 测试 Tavily API
from tavily import TavilyClient
tavily = TavilyClient(api_key="your_tavily_key")
try:
    result = tavily.search("test", search_depth="basic")
    print("Tavily API 连接成功")
except Exception as e:
    print("Tavily API 错误:", e)

6.2 运行完整程序

1
2
3
4
5

# 确保在正确目录
cd "hello-agents\code\chapter1"

# 运行程序
python FirstAgentTest.py

6.3 预期输出

程序成功运行时，您应该看到类似以下的输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

用户输入: 你好，请帮我查询一下今天北京的天气，然后根据天气推荐一个合适的旅游景点。
========================================
--- 循环 1 ---

正在调用大语言模型...
大语言模型响应成功。
模型输出:
Thought: 用户想要查询北京的天气，然后根据天气情况推荐合适的旅游景点。我需要先调用get_weather工具查询北京的天气情况。
Action: get_weather(city="北京")

Observation: 北京当前天气：Clear，气温15摄氏度
========================================
--- 循环 2 ---

正在调用大语言模型...
大语言模型响应成功。
模型输出:
Thought: 现在我知道了北京的天气是晴朗的，气温15摄氏度，这是一个很适合户外活动的天气。接下来我需要根据这个天气情况推荐合适的旅游景点。
Action: get_attraction(city="北京", weather="Clear，气温15摄氏度")

Observation: 根据搜索，为您找到以下信息：...
========================================
任务完成，最终答案: 根据查询，北京今天天气晴朗，气温15摄氏度，非常适合户外游览。推荐您去...

七、常见问题排查

7.1 依赖安装问题

问题：pip 安装速度慢

解决方案：使用国内镜像源

1
2
3
4
5

# 临时使用清华镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests tavily-python openai

# 永久配置镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

问题：ModuleNotFoundError

解决方案：

1
2
3

# 确认虚拟环境已激活
# 重新安装缺失的包
pip install requests tavily-python openai python-dotenv

7.2 API 调用问题

问题：Tavily API 返回错误

可能原因：

• API Key 未正确设置
• API 额度用尽
• 网络连接问题

解决方案：

1
2
3
4
5
6
7
8

# 检查环境变量
import os
print("TAVILY_API_KEY:", os.environ.get('TAVILY_API_KEY'))

# 测试 API 连接
from tavily import TavilyClient
client = TavilyClient(api_key="your_key")
result = client.search("test")

十、总结

完成环境配置后，建议：

1. 理解 FirstAgentTest.py 的代码结构
2. 尝试修改 System Prompt 观察效果
3. 添加新的工具函数
4. 实现更复杂的 Agent 逻辑

按照本文档的步骤操作，您应该能够成功运行智能旅行助手代码，并理解基于工具调用的 Agent 实现原理。

引言：当 AI 学会”看”屏幕

想象一下这样的场景：你对着手机说”帮我订一张明天去上海的高铁票，二等座，上午 10 点左右出发”，然后 AI 自动打开铁路 12306 APP，填写出发地、目的地和日期，筛选符合条件的车次，完成预订并付款——整个过程无需你手动操作，AI 就像一个真实的助手一样，”看”着屏幕，”理解”界面，”点击”按钮。

这不是科幻，而是 GUI Agent（图形用户界面智能体） 正在实现的现实。

在过去的二十年中，企业自动化的主流方案是 RPA（机器人流程自动化）。然而，RPA 有一个致命弱点：它依赖于固定的 UI 元素选择器（Selectors），一旦界面稍有变化，脚本就会失效。这种脆弱性导致了巨大的维护成本。

而 GUI Agent 的出现，彻底改变了这个局面。它不是简单地”回放”预设的脚本，而是像人类一样，通过视觉感知理解屏幕内容，通过大语言模型的推理能力规划操作路径，在动态、未知的软件环境中自主完成任务。

本章将带你深入了解 GUI Agent 的技术原理，并通过三个实战案例，让你真正掌握如何使用和部署这些前沿的智能体系统。

第一部分：GUI Agent 技术科普

1.1 GUI Agent 是什么？

GUI Agent（图形用户界面智能体） 是一类能够自主理解和操作图形界面的 AI 系统。与传统的 API 调用或命令行工具不同，GUI Agent 直接与人类使用的图形界面交互——无论是手机 APP、桌面软件还是网页应用。

1.1.1 从 RPA 到 AI Agent 的范式转变

让我们通过一个对比来理解这种转变：

核心区别：RPA 是”脆弱的自动化”，而 GUI Agent 是”智能的自主化”。

1.1.2 为什么 GUI Agent 突然火了？

GUI Agent 的爆发并非偶然，而是多个技术领域同步成熟的结果。首先是多模态大模型的突破性进展。从GPT-4o、Claude 3.5 Sonnet、Qwen-VL 这些模型开始，大模型不仅能理解文字，还能”看懂”图像，这为 GUI Agent 提供了强大的”眼睛”。当你把一张屏幕截图喂给这些模型时，它们能准确识别出”这是一个登录按钮”、”这里有一个搜索框”，甚至能理解复杂的界面布局。

更关键的是定位能力的突破。早期的视觉模型就像一个近视眼——它知道屏幕上有个按钮，但说不清楚按钮在哪里。而最新的模型（如 GUI-Owl、Qwen-VL）经过专门训练，能够精确输出 UI 元素的屏幕坐标 $(x, y)$，这让 Agent 不仅能”看见”，还能”点准”。

最后是推理能力的质变。大语言模型的链式思考（Chain of Thought）能力让 Agent 拥有了”大脑”。它能将”订一张明天的高铁票”这样的模糊指令，分解成”打开APP → 选择日期 → 输入地点 → 筛选车次 → 确认支付”这样的具体步骤，并在执行过程中不断反思和纠错。

1.2 GUI Agent 的核心技术架构

一个完整的 GUI Agent 系统可以被分解为三个核心模块：感知（Perception） → 推理（Reasoning） → 执行（Action）。这是一个闭环的自主决策系统。

图 1 GUI Agent 的感知-推理-执行闭环

1.2.1 感知层：机器如何”看见”屏幕

感知层负责将屏幕信息转化为机器可理解的数据。目前主要有两种技术路线，它们代表了两种截然不同的设计哲学。

第一种路线是基于 DOM 或可访问性树的结构化感知。这种方法通过系统 API 获取应用的内部结构——比如网页的 HTML DOM 树，或者 Android 应用的 View Hierarchy。就像是给 Agent 提供了一份”建筑图纸”，它能精确知道每个按钮、文本框的类型和位置。这种方法的优势是精确高效，但问题也很明显：许多现代应用根本不暴露这些结构化信息。Canvas 绘制的界面、游戏、远程桌面软件，对于基于 DOM 的方案来说都是”黑盒”。而且这种方法丢失了视觉布局信息，很难理解元素之间的空间关系，跨平台兼容性也很差。

第二种路线是基于纯视觉的感知，这也是目前最前沿的方向。Agent 直接截取屏幕图像，用视觉大模型（VLM）像人类一样”看”屏幕。这种方法的通用性极强——不管你的界面是用什么技术实现的，只要能显示在屏幕上，Agent 就能理解。更重要的是，它具备”语义弹性”。即使某个按钮从蓝色变成了绿色，或者位置稍微移动了，基于视觉的 Agent 仍然能通过语义识别出”这是登录按钮”。传统 RPA 遇到这种情况就会失效，但 GUI Agent 能轻松应对。当然，纯视觉方案也有挑战，最大的难点是定位精度——模型不仅要识别出按钮是什么，还要输出它的精确屏幕坐标。

1.2.2 推理层：大脑的决策过程

推理层是 GUI Agent 的”大脑”，负责将用户的抽象指令转化为具体的操作序列。这里涉及几个关键能力。

首先是任务分解能力。当你对 Agent 说”帮我订一张明天去上海的高铁票，二等座，上午10点左右出发”，它需要理解这句话背后的复杂逻辑。Agent 会自动将这个模糊的需求拆解成一系列具体步骤：打开 12306 APP → 点击”车票预订” → 输入出发地”北京” → 输入目的地”上海” → 选择日期”明天” → 点击查询 → 筛选车次（二等座+上午10点前后）→ 选择符合条件的车次 → 点击预订 → 填写乘客信息 → 确认支付。这个分解过程依赖于大语言模型对常识和业务流程的理解。

更精妙的是思维链机制。为了提高复杂任务的成功率，现代 GUI Agent 会在每一步操作前生成”内心独白”。比如当前屏幕是 12306 首页，用户目标是预订高铁票，Agent 会先分析：”我看到屏幕上有’车票预订’、’订单查询’等选项，需要点击’车票预订’才能进入购票流程。”然后决策：”点击坐标 (540, 320) 处的’车票预订’按钮。”这种显式的思考过程不仅让 Agent 的行为更可解释，还能显著降低多步操作中的误差累积。

最后是反思与纠错能力。如果 Agent 点击”查询”按钮后，发现没有出现预期的车次列表，而是弹出”请选择出发日期”的提示，它会立即意识到：”我漏掉了选择日期的步骤。”然后调整策略：”先点击日期选择器，选择明天的日期，再重新查询。”这种自我修正能力让 Agent 能够应对真实世界中的各种意外情况。

1.2.3 执行层：从决策到行动

执行层是 GUI Agent 的”双手”，负责将模型的决策转化为实际的系统操作。

与文本生成的开放空间不同，GUI 操作的动作空间是有限且明确的。点击、双击、长按、滑动、输入、滚动、拖拽——这些基本动作构成了所有复杂操作的基础。每种动作都有其特定的参数，比如点击需要坐标 (x, y)，滑动需要起点和终点 (x1, y1, x2, y2)，输入需要文本内容。

这里有一个关键的技术细节：坐标系统的转换。视觉模型（如 Qwen-VL）通常输出归一化坐标（0-1000），而实际手机或电脑的屏幕分辨率可能是 1920x1080。执行层必须进行精确的坐标映射，将模型的输出转换成物理坐标。而且不同设备还有不同的 DPI 和系统缩放比例，这些都需要考虑进去。一个简单的映射函数可能是这样的：先将归一化坐标除以 1000，再乘以屏幕的实际宽高，最后取整得到物理坐标。

更复杂的是多平台适配。在 Android 上，所有操作都通过 ADB（Android Debug Bridge）发送指令实现，比如 adb shell input tap 500 1000 执行点击，adb shell input swipe 500 1000 500 500 执行滑动。在 iOS 上，需要通过 libimobiledevice 或 WDA（WebDriverAgent）来实现类似功能。而在 Windows、Mac、Linux 桌面环境，通常使用 pyautogui、pynput 这样的 Python 库直接控制鼠标和键盘。同一个”点击”动作，在不同平台上的实现方式完全不同，执行层需要为每个平台提供统一的抽象接口。

1.3 主流开源框架全景对比

2024-2025年是 GUI Agent 的爆发期，各大科技公司和研究机构纷纷开源了自己的框架。让我们系统地对比几个最具代表性的项目：

图 2 主流 GUI Agent 框架全景对比雷达图

1.4 应用场景与技术局限

1.4.1 五大典型应用场景

GUI Agent 的应用潜力远超我们的想象。在智能座舱领域，驾驶过程中的语音交互需求正在爆发。想象你在开车时说”导航到最近的咖啡店，并在到达前 10 分钟帮我点一杯拿铁”，GUI Agent 能够跨应用协调导航 APP 和外卖 APP，理解复杂的时间逻辑，还能适应不同品牌车机的UI差异。这正是传统车机系统难以做到的。

在软件测试领域，GUI Agent 带来了革命性的变化。传统的自动化测试依赖 Selenium 等工具，每次 UI 改版都需要更新测试脚本，维护成本极高。而 GUI Agent 能够自适应 UI 变化——即使按钮的位置调整了、颜色改变了，Agent 仍能通过语义识别找到正确的元素。它还能进行视觉回归测试，自动检测 UI 异常，甚至主动进行探索性测试，发现那些人类测试工程师可能忽略的边界情况。

企业级的 RPA 场景是另一个巨大的市场。传统 RPA 无法处理那些没有 API 的老旧系统，但 GUI Agent 可以。从 Excel 提取数据，填入 ERP 系统，发送邮件通知——整个跨系统工作流可以完全自动化。对于那些运行了二三十年、没有任何现代接口的遗留系统，GUI Agent 终于提供了自动化的可能性。

在个人生活中，GUI Agent 可以成为真正的智能助理。定时发布内容到多个社交平台，每天早上自动汇总新闻、天气、日程，记录运动数据和饮食习惯——这些重复性的数字劳动都可以交给 Agent 完成。而对于视障、肢体障碍的用户，GUI Agent 更是打开了新世界的大门。完全通过语音控制手机、智能阅读屏幕内容、将复杂操作转化为简单指令，这些功能正在让技术真正惠及每一个人。

1.4.2 当前技术的三大局限

但我们也必须清醒地认识到，GUI Agent 技术仍处于发展的早期阶段，面临着一些实质性的挑战。

最令人担忧的是安全性与幻觉风险。大语言模型的幻觉问题在 GUI Agent 上可能导致严重后果。用户要求”清理桌面”，Agent 可能误解为删除所有文件；转账操作中的一个数字错误，可能造成经济损失。目前的缓解方案包括：对高风险操作强制要求人工确认，详细记录操作日志并支持回滚，以及在沙箱环境中充分测试。但这些都是权宜之计，从根本上解决模型幻觉问题仍需要时间。

成本与效率问题同样不容忽视。每一步操作都需要调用大模型进行推理，如果使用云端 API，成本会随着调用次数线性增长。一个复杂任务可能需要数十次迭代，整体耗时较长。本地部署小模型能降低成本，但准确率会有所下降。操作缓存、模式识别、混合架构（简单任务用 RPA，复杂任务用 AI）是目前探索的方向，但还没有形成成熟的最佳实践。

最后是准确率瓶颈。即使是最好的系统，在真实场景中的成功率也只有 40-50%。复杂界面的元素定位、动态内容的处理（广告、弹窗）、长链条任务的错误累积，这些都是实实在在的技术难题。突破方向包括更强的视觉大模型、通过强化学习优化操作策略、以及”人在回路”（Human-in-the-loop）的协作设计。但从 50% 提升到 90% 的商业化可用水平，可能还需要一段时间。

第二部分：GUI Agent 实战教程

理论学习之后，让我们通过两个难度递增的实战案例，真正掌握 GUI Agent 的使用和部署。

实战一：Mobile-Agent 在线体验（零门槛）

2.1.1 访问在线 Demo

Mobile-Agent-v3 不仅支持手机，还能操作电脑。如图 3 所示，我们在 ModelScope 的 Demo 页面中，将左上角的设备选择切换为 “电脑”，即可进入 PC Agent 的体验环境。

选项一：ModelScope Demo（推荐）
链接：https://modelscope.cn/studios/wangjunyang/Mobile-Agent-v3

选项二：阿里云百炼
链接：https://bailian.console.aliyun.com/next?tab=demohouse#/experience/adk-computer-use/pc

这两个平台都提供了云手机/云电脑环境，无需本地部署即可体验完整功能。

2.1.2 界面功能导览

进入页面后，你将看到如图 3 所示的操作界面。为了确保体验一致，请务必进行以下关键设置：

1. 设备选择：在左上角的下拉菜单中，确认选择 “电脑”（而非手机）。
2. 桌面预览：右侧窗口展示的是云端分配给你的 Windows 10 桌面，预装了 Office、浏览器等基础软件。
3. 交互区：左下角为指令输入区，Agent 的思考过程（Thinking Process）和操作步骤将显示在上方对话框中。

图 3 Mobile-Agent-v3 在线 Demo 界面说明

在这个界面中，你可以直接指挥 Agent 进行办公操作，不过目前使用时间有限时。

2.1.3 典型任务演练

根据界面提供的预设能力，建议新手从以下两类任务开始尝试：

• 系统级控制：尝试让 Agent 修改系统设置。
  • 指令示例：“将系统颜色设置为浅色模式。”
  • 观察点：Agent 能否像人一样打开“开始菜单 -> 设置 -> 个性化”。
• 跨应用办公：尝试让 Agent 联动浏览器和办公软件。
  • 指令示例：“在 Edge 浏览器中搜索阿里巴巴的股价，然后在 WPS 中新建一个表格，填入公司名和当前股价。”
  • 观察点：Agent 能否准确处理“搜索信息”到“录入信息”的跨软件上下文切换。

2.1.4 提示词工程：如何指挥 PC Agent

在 GUI 场景下，高质量的 Prompt 是成功的关键。结合上述办公场景，我们总结了三个核心技巧：

1. 明确应用边界 (Explicit Context)
   • 避免笼统指令，如“写个简介”。
   • 推荐写法：“在 WPS Office 文档中写一段简介……”
   • 解析：明确指定软件名称（App Name），能减少 Agent 寻找工具的时间。
2. 步骤链式拆解 (Chain of Steps)
   • 不要试图用一句话包含所有复杂逻辑。
   • 推荐写法：“第一步，打开 Edge 搜索……；第二步，确认网页加载完成后，截取数据……；第三步，打开 Excel 粘贴。”
   • 解析：GUI 操作具有严格的时序性，分步指令能显著降低执行错误率。
3. 视觉属性描述 (Visual Attributes)
   • Agent 是通过“看”屏幕来操作的，利用视觉特征描述更有效。
   • 推荐写法：“点击右上角的蓝色保存按钮” 或 “将字体颜色改为红色”。

2.1.5 在线体验的价值与局限

ModelScope 提供的在线 Demo 最大的价值在于零门槛体验。你不需要配置任何环境，不需要准备手机，甚至不需要下载任何软件，就能直接感受到 GUI Agent 的魔力。这对于快速验证想法、了解技术边界非常有帮助。

但在线环境也有其局限性。首先是隐私问题，所有操作都在云端虚拟机上进行，你无法访问真实的个人数据。其次是功能限制，虚拟环境中只预装了部分常用 APP，无法测试特定的应用场景。最后是性能差异，云端推理的延迟会比本地部署稍高。

因此，在线体验适合作为学习和探索的起点，但如果要在真实场景中应用 GUI Agent，你需要尝试本地部署。Mobile-Agent-v3官方提供了一个教程，可以自行尝试

接下来的实战二，就将带你使用最近智谱开源的AutoGLM走进这个更深入的世界。

实战二：AutoGLM 本地部署与手机实战

在线体验让我们感受到了 GUI Agent 的能力，但真正的力量在于部署在自己的设备上，控制真实的应用。AutoGLM 是一个非常适合个人开发者入门的框架，它的架构清晰，文档完善，部署过程相对简单。

这个实战的目标是在你的电脑上部署 AutoGLM，连接你的 Android 手机，然后让 AI 帮你完成一些真实的任务——比如自动回复微信消息，或者定时刷新某个 APP 获取最新数据。

2.2.1 环境准备：你需要什么

Open-AutoGLM 的部署需要两样核心设备：一台能运行 Python 的电脑，以及一部 Android 手机。电脑的配置并不需要太高，因为 AutoGLM 支持调用云端 API，不一定要在本地运行大模型。如果你打算使用云端 API（如智谱的 GLM-4V），一台普通的笔记本就足够了。但如果你想体验完全本地化的方案，那么一块至少 8GB 显存的 GPU 会让体验好很多。

手机方面，Android 7.0 或更高版本都可以，不需要 Root 权限。iPhone 用户暂时无法使用，因为 iOS 的封闭性导致 ADB 调试方案无法直接应用。

软件环境方面，你需要安装 Python 3.10 或更高版本，以及 ADB（Android Debug Bridge）工具。ADB 是连接电脑和手机的桥梁，所有的屏幕截图、点击、滑动操作都要通过它来实现。

安装 ADB 工具 (macOS / Linux): 根据你的系统，在终端执行以下命令：

1
2
3
4
5

# macOS 使用 Homebrew
brew install android-platform-tools

# Linux (Ubuntu/Debian)
sudo apt install android-tools-adb

Windows 用户通常可以直接下载 Platform Tools 压缩包并配置环境变量。参考

2.2.2 第一步：安装 Open-AutoGLM

如果你拥有 Claude Code，你可以配置 GLM Coding Plan 后，输入以下提示词快速部署：

1
2

访问文档，为我安装 AutoGLM
https://raw.githubusercontent.com/zai-org/Open-AutoGLM/refs/heads/main/README.md

如果没有类似的CLI，请按照以下手动步骤操作：

打开命令行终端，先克隆 Open-AutoGLM 的代码仓库：

1
2

git clone https://github.com/zai-org/Open-AutoGLM.git
cd Open-AutoGLM

接下来安装依赖。除了基础的依赖包，一定要执行项目的安装命令，以确保所有模块能被正确调用：

1
2
3
4
5
6
7
8

# 1. 安装基础依赖
pip install -r requirements.txt

# 2. 以编辑模式安装项目本身 (关键步骤)
pip install -e .

# 3. (可选) 如果你是开发者，需要额外安装开发依赖
pip install -e ".[dev]"

这个过程通常需要几分钟，取决于你的网络速度。安装完成后，你需要配置 API 密钥。如果使用智谱的 GLM-4V API，先去智谱开放平台注册账号并获取 API Key，然后在项目根目录创建一个 .env 文件：

1
2

# .env 文件内容
GLM_API_KEY=your_api_key_here

AutoGLM-Phone-9B · 模型库

2.2.3 第二步：连接你的 Android 手机

现在到了关键的一步：让电脑能够”看见”并”控制”你的手机。这需要三个小步骤：开启开发者模式、开启 USB 调试、以及安装 ADB Keyboard。

1. 启用开发者模式 & USB 调试 在 Android 手机上，进入”设置” → “关于手机”，找到”版本号”，连续点击 7 次（或直到出现提示），你会看到”您已处于开发者模式”的提示。 返回设置主界面，进入”开发者选项”，找到”USB 调试”并开启。

2. 安装 ADB Keyboard (必须) 为了让 AI 能在手机上输入文字，我们需要安装专用的 ADB 键盘。

• 下载地址：https://github.com/senzhk/ADBKeyBoard/raw/master/ADBKeyboard.apk

安装后，记得在手机设置的“输入法”中，启用并切换到 ADB Keyboard。

3. 验证连接 用 USB 数据线将手机连接到电脑（手机上弹出授权框时点击”允许”）。在电脑终端输入：

Bash

1

adb devices

如果一切正常，你会看到设备序列号：

1
2

List of devices attached
ABC12345    device

如果显示 device，恭喜你，硬件连接打通了！如果显示 unauthorized，请检查手机屏幕是否弹出了授权确认框。

对于 Windows 用户，可能还需要安装手机的驱动程序。大部分品牌的手机（如小米、华为、OPPO）都会在连接电脑时自动安装驱动，但如果遇到问题，可以去官网下载对应的 USB 驱动。

图 4 Android 手机 ADB 连接完整配置流程

2.2.4 第三步：运行你的第一个任务

连接成功后，让我们来执行一个简单但实用的任务。

有两种直接调用API的连接方式：

1. 智谱 BigModel

• 文档: https://docs.bigmodel.cn/cn/api/introduction
• --base-url: https://open.bigmodel.cn/api/paas/v4
• --model: autoglm-phone
• --apikey: 在智谱平台申请你的 API Key

2. ModelScope(魔搭社区)

• 文档: https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B
• --base-url: https://api-inference.modelscope.cn/v1
• --model: ZhipuAI/AutoGLM-Phone-9B
• --apikey: 在 ModelScope 平台申请你的 API Key

官方的readme里提供了一个命令行接口，你可以直接输入：

1
2
3
4
5

# 使用智谱 BigModel
python main.py --base-url https://open.bigmodel.cn/api/paas/v4 --model "autoglm-phone" --apikey "your-bigmodel-api-key" "打开美团搜索附近的火锅店"

# 使用 ModelScope
python main.py --base-url https://api-inference.modelscope.cn/v1 --model "ZhipuAI/AutoGLM-Phone-9B" --apikey "your-modelscope-api-key" "打开美团搜索附近的火锅店"

执行这个命令后，AutoGLM 会启动推理流程。你会在终端看到实时的日志输出，同时手机屏幕上会开始自动操作。整个过程大概是这样的：

首先，AutoGLM 会通过 ADB 截取当前屏幕的截图，将图像发送给模型分析。模型会识别出屏幕上的所有 APP 图标，并在像素级别定位到”美团”的位置。然后 AutoGLM 发送点击指令，通过 adb shell input tap x y 唤醒应用。

等待美团启动后，AutoGLM 再次截屏。这次它的目标是找到首页上方的”搜索栏”。识别并点击搜索框后，它会调用我们在环境准备阶段安装的 ADB Keyboard，将”附近的火锅”这串字符输入进去，最后自动点击搜索按钮。

整个过程通常需要 15-20 秒（搜索任务步骤稍多），具体时间取决于模型的推理速度和网络延迟。如果你使用的是云端 API，每一步的”思考”时间大约是 2-3 秒。如果是本地部署的模型，配置较好的 GPU 可以将单步时间压缩到 1 秒左右。

总结与展望

通过这两个层次递进的实战，我们完整地体验了 GUI Agent 从在线演示到本地部署的全过程。Mobile-Agent 的在线 Demo 让我们快速理解了技术的可能性，AutoGLM 的手机实战让我们掌握了实际部署的技能，而 GLM-ZERO 的端侧方案则展示了隐私保护和离线应用的未来。

GUI Agent 技术仍在快速演进中。当前的系统虽然已经能够处理大部分日常任务，但在准确率、推理速度和成本控制上还有很大的提升空间。随着视觉大模型的持续进步，以及端侧推理芯片的发展，我们有理由相信，GUI Agent 将成为未来人机交互的重要范式。

或许不久的将来，每个人都将拥有一个真正智能的数字助手，它不仅能理解你的意图，还能跨越不同的应用和平台，帮你完成各种重复性的工作。那时候，我们今天费力编写的自动化脚本，都将变成一句简单的自然语言指令。

这个未来，其实已经在路上了。

参考资料

1. Mobile-Agent-v3 论文：https://arxiv.org/abs/2508.15144
2. Open-AutoGLM GitHub：https://github.com/zai-org/Open-AutoGLM
3. UI-TARS 项目：https://github.com/bytedance/UI-TARS