📒 学霸笔记：05｜核心交互模型——所有 Agent 的通用语言：上下文注入与 Shell 执行

Top Student Notes: 05 | Core Interaction Model — The Universal Language of Agents: Context Injection and Shell Execution

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 05
主题 / Topic: @ 上下文注入、! Shell 执行、感知-行动闭环
核心关键词 / Keywords: Context / Action / Structured Interaction / Human-in-the-loop / Perception-Action Loop

一、这一讲在整个课程里的位置

Where This Lecture Fits in the Course

前 4 讲做了两件事：

1. 建立 AI 原生开发的认知框架
2. 搭好 Claude Code + 国产模型的运行环境

从这一讲开始，课程正式进入：

Claude Code 的实际操作层

也就是说，之前你只是“有了武器”，这一讲开始你才真正学习“怎么挥剑”。

二、本讲的核心结论

Core Conclusion of This Lecture

Tony 反复强调：高阶 AI Agent 的协作方式，不是简单的一问一答，而是：

结构化的、双向的、人机协作式对话

在这套对话模型里，最核心的两个符号就是：

• @：上下文注入 / Context Injection
• !：Shell 执行 / Shell Execution

一句话理解

@ 让 AI 看见世界，! 让 AI 作用于世界。

三、AI 的“两只手”：新的交互哲学

AI’s “Two Hands”: A New Interaction Philosophy

Tony 用了一个非常好的比喻：

• @ 是 AI 的 眼睛和耳朵
• ! 是 AI 的 双手

这不是两个普通命令，而是一种新的协作哲学。

1. 传统交互方式

传统开发中，你和计算机的关系是：

• 你写命令
• 机器执行命令
• 是单向的、命令式的

2. AI 原生交互方式

在 AI 原生开发里，交互更像：

• 你提供上下文
• AI 理解上下文
• AI 提议动作
• 你审批动作
• AI 执行动作
• 你继续基于结果沟通

这是：

双向、协作式、带反馈回路的人机工作流

3. 心智模型：像和资深同事结对编程

Tony 给出的类比非常重要：

典型协作方式

1. 你指着某段代码：@某个文件
2. 同事看完后说：先跑个测试吧：!go test
3. 测试通过后，同事提出下一步修改建议
4. 你授权，他去改

Claude Code 中的 @ 和 !，本质上就是把这种人与人协作模式，映射成了人与 Agent 的协作协议。

四、@ 指令：给 AI 提供结构化上下文

The @ Command: Structured Context for AI

1. 为什么 @ 很重要？

它解决的是课程一开始就提到的老问题：

上下文摩擦力

如果没有 @，你就需要：

• 复制代码
• 粘贴到对话框
• 手工描述路径和位置
• 再补充项目结构说明

而 @ 把这个过程变成了：

精确、结构化、可追溯的上下文引用

2. @ 的本质

当你输入：

@main.go

你实际上是在和 AI 建立一个明确契约：

“接下来的对话，请以 main.go 当前内容为依据。”

所以 @ 不是“附件上传”，而是：

把本地工程对象正式纳入当前对话语境

五、@ 的第一类用法：引用单个文件

First Use of @: Referencing a Single File

语法

@/path/to/your/file

Claude Code 支持：

• 路径自动补全
• 文件名联想
• Tab 补全

因此实际使用非常接近 IDE 体验。

适合什么场景？

单文件引用适用于：

• 解释某个文件
• 生成某个函数的测试
• 审查一份配置文件
• 修改一小块明确范围的逻辑
• 基于一个函数/文件进行重构建议

实战场景 1：解释陌生文件

例如：

@Dockerfile
帮我逐行解释这个 Dockerfile，特别是多阶段构建逻辑。

Claude Code 会：

1. 读取该文件
2. 提取结构
3. 逐行解释
4. 在技术层面补充最佳实践

学霸理解

这比“复制几十行 Dockerfile 到聊天框”强很多，因为：

• 引用更快
• 不易漏内容
• 路径信息还保留着
• 对话更自然

实战场景 2：基于已有代码生成测试

例如：

@utils/math.go
为 Add 函数编写完整单元测试，使用 testing 包，覆盖正常、负数和零的情况。

Claude Code 会：

• 读取文件
• 理解函数签名
• 生成 math_test.go
• 申请写文件权限
• 写入后给出测试说明和后续建议

关键点

这说明 @ 不只是“解释文件”，还可以作为后续生成任务的输入基础。

单文件 @ 的价值总结

它适合：

• 精准任务
• 低噪音上下文
• 小范围代码工作

一句话

单文件 @ = 最精准的上下文狙击模式

六、@ 的第二类用法：引用整个目录

Second Use of @: Referencing a Directory

这是 @ 真正“拉开层次”的地方。

语法

@/path/to/your/directory/

当你引用一个目录时，Claude Code 不会无脑把所有文件内容全部塞进上下文，而是会进行智能处理。

1. Git 感知（Git-aware）

这是一个非常关键的点。

Claude Code 会自动：

1. 找到项目里的 .gitignore
2. 读取忽略规则
3. 在分析目录时自动忽略：
   • node_modules/
   • vendor/
   • 构建产物
   • .git/
   • 其他噪音目录

学霸理解

这意味着 Claude Code 在目录上下文里天然做了“上下文清洗”。

所以目录级 @ 的本质不是“喂更多内容”，而是：

给 AI 一个干净的项目级视角

2. 适合什么场景？

目录引用适合：

• 项目结构分析
• 技术栈分析
• 启动方式探索
• 跨文件理解
• 大范围重构规划
• 模块边界梳理

实战场景 3：项目总览

例如：

@./
这是一个 Go 项目，请帮我分析整体结构、核心功能、主要依赖以及如何运行起来。

Claude Code 可能会自动去读：

• README.md
• go.mod
• main.go
• Makefile
• cmd/
• internal/
• web/

然后给你一份像资深同事 onboarding 一样的总结报告。

学霸理解

这类能力意味着：

AI 已经不只是“代码补全器”，而是“项目理解器”

实战场景 4：目录级重构

比如：

@internal/github/
请分析这个包的职责，并给出将 REST API 调用迁移到 GraphQL API 的重构方案。

Claude Code 会：

• 读包下多个文件
• 理解文件关系
• 理解 API 调用链路
• 给出系统级方案
• 在授权下修改多个文件

这和单文件最大区别是什么？

单文件只适合局部问题，目录级 @ 才能支撑：

• 架构理解
• 模块间关系分析
• 多文件重构

目录 @ 的价值总结

目录 @ = 给 AI 打开“上帝视角”

七、@ 的本质定位

The Core Position of @

Tony 给出的结论非常值得记住：

@ 是 AI Agent 的输入管道。

它的作用是把：

• 文件
• 项目结构
• 文档
• 配置
• 本地工程上下文

转化为 AI 可以理解的结构化语境。

一句话总结

精通 @，就是从“拿 AI 当聊天工具”升级到“拿 AI 当工程工具”。

八、! 指令：让 AI 进入真实执行世界

The ! Command: Let AI Act in the Real Execution World

如果说 @ 是 AI 的眼睛，那么 ! 就是它的手。

1. 为什么 ! 非常关键？

因为 AI 如果只能“看”和“说”，那还只是顾问。
只有当它能：

• 执行命令
• 查询环境
• 跑测试
• 读 diff
• 参与 git 工作流

它才真正成为：

工作流中的执行者

2. ! 的本质

! 打通了：

• AI 的思考层
• 本地 shell 环境
• 实际工程操作

但它又不是裸奔式自动执行，而是带有人在回路中的审批机制。

九、! 的第一类用法：在对话中手动执行单行命令

First Use of !: Manually Execute a Single Shell Command

语法

! <your_shell_command>

例如：

!go list -m github.com/redis/go-redis/v9

这允许你在 Claude Code 会话中不离开当前环境，直接做快速验证。

适合什么场景？

• 检查依赖
• 看文件列表
• 跑测试
• 查看 Git 状态
• 运行构建命令
• 获取系统信息

实战场景 1：即时查询

你正在和 AI 讨论 Redis 依赖，想看本地是否已安装：

!go list -m github.com/redis/go-redis/v9

命令执行结果会直接显示在会话中。

学霸理解

这使得对话和验证合一，不需要：

• 切出 Claude Code
• 去另一个 shell 执行
• 再回来转述结果

十、! 的第二类用法：把命令输出自动纳入下一轮上下文

Second Use of !: Use Command Output as Context for the Next Turn

这是 ! 最强大的特性之一。

关键机制

! 的输出，会自动成为下一轮对话上下文

也就是说，AI 不只是“看到你执行了命令”，而是“理解了命令结果”。

实战场景 2：让 AI 基于 diff 写 commit message

例如：

!git add README-zh-TW.md
!git diff --staged

接着你说：

根据上面的 diff，帮我写一条符合 Conventional Commits 规范的 commit message。

Claude Code 会基于刚才 git diff --staged 的输出，为你生成高质量提交说明。

为什么这个特性很强？

因为它让你可以构造一个“命令链”：

!命令A
!命令B
!命令C
自然语言提问

而 AI 会把 A/B/C 的结果综合起来理解。

学霸理解

这其实是在用 shell 输出“喂养”AI 的即时工作记忆。

十一、! 的第三类用法：让 AI 主动提议并执行命令

Third Use of !: Let AI Propose and Execute Commands

这是最“AI 原生”的用法。

传统用法

你自己决定执行什么命令。

高阶用法

你只给任务目标，例如：

帮我分析这个项目的外部模块依赖。

Claude Code 会自己判断：

• 需要读 go.mod
• 可能需要 go list -m all
• 可能需要 grep
• 可能需要 git status

然后以工具调用 / 交互卡片的方式向你提出执行建议。

核心机制：提议 - 审批

Tony 特别强调：

AI 不会在你不知情的情况下擅自执行危险命令

默认模式下，Claude Code 会：

1. 提议动作
2. 说明用途
3. 等待你批准
4. 再执行

这就是 Human-in-the-loop 的安全设计。

危险模式

如果使用：

claude --dangerously-skip-permissions

那么权限审批会被跳过。

学霸提醒

这个模式虽然顺滑，但有明显风险。生产环境或重要项目中必须慎用。

十二、一个重要细节：Claude Code 没有沉浸式 Shell 子模式

Important Detail: No Immersive Shell Submode

一些其他 Agent 工具有“输入 ! 后进入连续 shell 模式”的能力。
Claude Code 没有这种沉浸式 shell 子环境。

正确做法

如果你要执行多条命令，就逐条写：

!git status
!go test ./...
!git diff

为什么这么设计反而有好处？

因为这样：

• 每条命令独立
• 每条输出清晰
• AI 能逐步理解每一步结果
• 对话上下文更干净
• 不容易出现“shell 混乱状态”

学霸理解

这是一种更强调“可解释、可跟踪”的交互设计。

十三、@ + ! 组合：形成感知-行动闭环

@ + !: Forming the Perception-Action Loop

这讲最核心的能力，不是单独会用 @ 或 !，而是会把它们组合起来。

基本闭环模型

@ 感知当前状态
→ 自然语言表达目标
→ AI 提议行动
→ 你审批
→ ! 执行命令 / 写文件 / 修改代码
→ 输出结果回流为新上下文
→ 继续下一轮

这就是：

AI 原生开发中的 Perception → Action → Feedback Loop

十四、实战闭环案例：添加依赖并编写示例函数

Practical Closed-Loop Example: Add a Dependency and Write a Sample Function

Tony 用一个完整流程把 @ 和 ! 串了起来。

步骤 1：感知现状

@go.mod

让 Claude Code 了解当前依赖状态。

步骤 2：输入意图

你告诉 AI：

• 要添加某个依赖
• 写一个示例函数
• 放到什么位置

Claude Code 会据此：

• 提出要创建文件
• 写入代码
• 申请你授权

步骤 3：执行环境变更

你用：

!go get ...

来更新依赖。

步骤 4：验证与提交

再继续：

!git add ...
!git diff --staged

然后让 AI 生成 commit message。

这个案例说明什么？

说明你已经不再是“逐行手写代码的人”，而更像：

提出目标、审批决策、验证结果的架构师 / 指挥者

而 AI 负责高频、机械、流程化的感知-行动循环。

十五、本讲最重要的抽象模型

The Most Important Abstract Model in This Lecture

模型 1：AI 的眼和手

• @ = 感知 / perception
• ! = 行动 / action

模型 2：结构化交互

• 不是随便聊天
• 而是精确引用上下文 + 有控制地执行动作

模型 3：Human-in-the-loop

• AI 负责提议
• 人负责审批
• 形成受控自动化

模型 4：感知-行动闭环

Context → Plan → Action → Feedback → Next Context

这就是后面更复杂 Agent 工作流的基础原型。

十六、思考题怎么答：只用 ! + 自然语言找出超过 500 行的 Go 文件并分析最大文件

How to Answer the Reflection Question

题目要求：

不用 @，只用 ! 和自然语言
找出项目中所有超过 500 行的 Go 文件，并对其中最大的那个做复杂度分析

一个高质量指令链示例

步骤 1：列出所有 Go 文件及行数

!find . -name "*.go" -type f | xargs wc -l | sort -nr

这会输出所有 .go 文件的行数排序结果。

步骤 2：自然语言要求 AI 过滤出 > 500 行文件

请根据上面的输出，列出所有超过 500 行的 Go 文件，并指出其中最大的那个。

AI 会根据上一条 ! 输出进行筛选。

步骤 3：查看最大文件内容或结构

假设最大文件是 internal/github/github.go，可以继续：

!sed -n '1,260p' internal/github/github.go
!sed -n '261,520p' internal/github/github.go

或者先看函数分布：

!grep -n "^func " internal/github/github.go

步骤 4：让 AI 做复杂度分析

请基于上面的函数分布和文件内容，对这个文件做代码复杂度分析，重点关注：
1. 是否职责过多
2. 是否存在超长函数
3. 是否存在高耦合问题
4. 如果要拆分，应如何分模块

学霸理解

这道题考察的是：

你是否理解 ! 的输出可以变成持续上下文，从而把 shell 管道能力和 AI 分析能力串起来。

十七、与后续内容的关系

Relation to Later Lectures

这一讲是后续一切高级能力的地基。

因为后面的：

• CLAUDE.md
• 长期记忆
• Spec 驱动执行
• Agent Teams
• 自动化工作流

本质上都建立在两个基础能力之上：

1. 如何把正确上下文喂给 AI → @
2. 如何让 AI 进入真实工作流 → !

所以可以说：

不会 @ 和 !，后面所有高级能力都只是空中楼阁。

十八、学霸速记表

Quick Revision Table

十九、学霸自检题

Self-Check Questions

基础题

1. @ 和 ! 分别代表什么？
2. 单文件 @ 和目录 @ 的适用场景有什么不同？
3. 为什么说 ! 的输出会自动成为下一轮上下文这一点很重要？

进阶题

4. 为什么 Claude Code 处理目录 @ 时要尊重 .gitignore？
5. “AI 提议执行命令”与“你自己写 !命令 执行”有什么本质区别？
6. 为什么 Claude Code 没有沉浸式 shell 模式，反而可能更适合可追踪协作？

思辨题

7. 在你的项目里，哪些任务适合单文件 @，哪些适合目录 @？
8. 你是否能设计一个完整的 @ + ! 指令链，用于“发现问题 → 修改代码 → 运行测试 → 生成提交信息”？

二十、学霸总结

Top-Student Summary

这一讲正式打开了 Claude Code 的实战入口。核心内容看似只有两个符号：@ 和 !，但本质上讲的是一种新的 AI 原生人机协作模型。

• @ 负责上下文注入，让 AI 获得感知世界的能力
• ! 负责 Shell 执行，让 AI 获得作用于真实工程环境的能力

通过 @，我们可以精确引用单个文件，也可以智能地引入整个目录，让 AI 从“只会回答问题”升级为“真正理解项目”。
通过 !，我们可以在对话中执行命令、把命令结果变成上下文，甚至让 AI 主动提出要执行哪些命令，再由人审批执行。

最关键的是，这两者组合起来形成了一个完整的：

感知 → 行动 → 反馈 工作流闭环

这意味着开发者的角色不再是每一步都亲手执行，而是：

• 给出目标
• 注入上下文
• 审批动作
• 验证结果

而 AI 则承担越来越多的局部执行和环境交互工作。

二十一、一句话记忆

One-Sentence Memory Hook

@ 让 AI 看懂项目，! 让 AI 动手做事；两者组合，就是 AI 原生开发最基础的感知-行动闭环。