Agent¶

参考文档¶

AI Agent 范式导论.md、MCP.md、Skills.md、Agent Teams.md、上下文管理和代码质量.md

知识地图¶

• 概念：先理解这个模块为什么存在。
• 工具：再看它通过哪些工具落地。
• 场景：最后判断什么时候该用，什么时候不该用。

核心整理¶

Agent 不是固定流程，而是模型能根据观察决定何时调用工具。Harness = Tools + Knowledge + Observation + Action + Permissions。MCP 是工具协议，Skills 是任务说明和脚本包。上下文管理决定复杂任务上限。

我在整理这部分时的重点是把工具放回工程场景，而不是孤立记名词。一个工具出现，通常是为了解决某种复杂度：协作复杂度、上下文复杂度、运行环境复杂度、系统规模复杂度或信息获取复杂度。

学习笔记¶

1. 先读 Why，确认它解决的问题。
2. 再读 What，建立概念边界。
3. 再读 How，补命令、API、配置和实践。
4. 最后用一个小 demo 验证。

实践清单¶

• 用自己的话解释本模块核心概念。
• 找一个最小 demo 跑通。
• 记录一个踩坑点。
• 把相关命令或配置写成可复用片段。
• 回看飞书原文，补齐遗漏的术语。

飞书思考题¶

Skills 渐进式披露流程是什么？¶

先通过 name/description 判断是否需要 Skill，再读取 SKILL.md；如需更多细节再读取 reference 或脚本。这样避免无关上下文污染。

如何自制一个 Skill？¶

选择重复且规则稳定的任务，创建 SKILL.md，写清触发条件、步骤、输入输出和验证标准；长规则放 reference，重复动作写脚本。

Agent 与 Workflow 的边界¶

飞书文档里特别强调：很多所谓“智能体”其实只是 Workflow。Workflow 的特点是流程预先写死，比如：用户输入 -> LLM 总结 -> if 判断 -> 调一个 API -> 返回结果。它很有用，但它不是严格意义上的 Agent。

我对二者的区分：

所以 Agent 的关键不只是“能调用工具”，而是模型能根据 observation 选择下一步 action。

Harness 的五个组成¶

飞书文档把 Harness 讲成 Agent 工作所需的一切环境。我把它拆成五个问题：

1. Tools：模型能用什么？文件、Shell、浏览器、数据库、API。
2. Knowledge：模型知道什么？项目文档、领域规范、接口文档、风格指南。
3. Observation：模型看见什么反馈？测试结果、日志、git diff、网页状态。
4. Action：模型能改变什么？修改文件、执行命令、调用接口、点击页面。
5. Permissions：模型不能随便做什么？删除文件、上传数据、改权限、泄露 secret。

Agent 成功不是单靠模型聪明，而是环境设计合理。

MCP 的理解¶

MCP 可以把外部系统包装成模型可用的工具。比如：

• 博客可以暴露搜索接口。
• 数据库可以暴露查询工具。
• 浏览器可以暴露打开页面、截图、点击工具。
• 本地项目可以暴露文件和命令执行工具。

MCP 的价值是标准化工具接入。没有标准时，每个工具都要为每个模型写一套适配；有 MCP 后，模型侧和工具侧能更统一地连接。

Skills 的理解¶

Skill 更像“任务说明书 + 稳定脚本 + 参考资料”。它不是远程服务协议，而是让 Agent 在某类任务上更稳定。

例如一个文档排版 Skill 可以包含：

doc-format-skill/
  SKILL.md
  references/style-guide.md
  templates/report.md
  scripts/format_doc.py

Agent 先读 SKILL.md，知道什么时候用；需要细节时再读 reference；真正格式化时可以跑脚本。

渐进式披露为什么重要¶

如果把所有工具说明、风格指南、模板、API 文档都塞给模型，上下文会很快变乱。渐进式披露的思路是：

先暴露最少描述
  -> 命中任务后读 SKILL.md
  -> 需要时再读 reference
  -> 可执行部分交给脚本

这样既有专业能力，又不把上下文浪费在当前任务用不到的信息上。

Subagent 与上下文隔离¶

上下文管理和代码质量.md 里提到 subagent。我的理解是：主对话不应该承载所有搜索、日志、文件阅读。某些支线任务可以交给子 agent，最后只返回摘要。

适合子 agent 的任务：

• 搜索某个库的用法。
• 阅读大量日志并总结错误。
• 扫一批文件找接口定义。
• 对某个模块做只读分析。

不适合随便交出去的任务：

• 需要立即决策的主路径任务。
• 需要修改同一批文件的任务。
• 权限敏感任务。

代码质量中的 Agent 使用原则¶

• 先让 AI 补测试，再让 AI 重构。
• 让 AI 修改前说明改动范围。
• 用 git diff 检查行为。
• 用测试结果作为 observation。
• 不让 AI 根据猜测改生产配置。
• 对删除、上传、改权限等操作保留人工确认。

一个小型 Agent 设计例子¶

目标：自动整理飞书内训资料。

Knowledge: feishu/*.md
Tools: rg、读取文件、写 Markdown
Observation: 文件列表、标题结构、思考题位置
Action: 生成模块笔记、创建索引
Permissions: 不删除源文件，不上传外部服务，不改无关目录

关键不是让模型“随便总结”，而是让它按可检查流程：先列源文件，再分组，再提取标题和思考题，最后生成笔记。

知识卡片¶

Tool Use¶

工具调用让模型从“只会说”变成“能观察和行动”。但工具越强，越需要权限约束。

Observation¶

真实反馈比模型自信更重要。测试失败、日志、截图、diff 都是 observation。

Human-in-the-loop¶

涉及删除、上传、权限、密钥、生产环境时，应保留人工确认。