这份笔记偏向 AI 工具、Agent、项目约束与实际使用问题，尽量把“工具怎么用”单独整理出来，不和模型价格、套餐、网站信息混在一起，主要回答几个问题：“有哪些 AI 工具、Agent 是怎么工作的、项目里如何给 agent 加约束和扩展”。

这篇笔记的内容具有明显的时效性，当前原始信息时间是 2026 年 3 月，我并没有精力去持续更新。

一、AI 工具的主要类型

目前常见的大模型工具大致包括：

  • Web 对话（Web Chat）
  • IDE 插件（Plugin-Based）
  • AI 原生 IDE
  • CLI
  • 桌面版应用

典型代表包括：

  • Web：ChatGPT、Google Gemini
  • IDE 插件：GitHub Copilot、Cline、通义灵码 Lingma
  • AI 原生 IDE：Cursor、Windsurf、Google Antigravity、Trae / Trae CN、AWS Kiro，通义灵码也有 IDE 产品
  • CLI：Claude Code、Codex、Gemini CLI、OpenCode（可视作 Claude Code 的开源替代之一）
  • 桌面应用：有些应用（例如 Codex）从 CLI 或 AI 原生 IDE 继续演化而来，更接近纯 vibe coding 的桌面应用。这种形式相比 CLI 更易用，相比 IDE 则直接砍掉了编辑界面，形式上类似网页端多轮对话加本地项目管理。

这些类型的大致适用场景：

  • Web 对话最适合日常问答、轻度搜索和简单文案工作。
  • IDE 插件适合在现有编辑器中做补全、解释代码和局部修改。
  • AI 原生 IDE 更适合较重度的 agent 编程，因为权限更大、交互更深。
  • CLI 更适合直接对本地项目执行读取、搜索、修改、测试等操作。
  • 桌面应用通常面向更轻量的本地项目管理和多轮协作，强调易用性。

补充：

  • 大多数网页端主要还是多轮对话聊天，最多加上一些可选的网络搜索等功能；但有的网页端则更接近完整的 agent，实质就是服务商在远程启动一个虚拟机环境并执行 agent 工具。
  • IDE 插件还可以细分成快速代码补全工具和对话式 agent 工具。前者对补全延迟要求很高，因此可能需要在本地运行一个小模型，或者使用其他加速手段；后者则是基于对话的 agent，通过读取用户输入和 IDE 提供的上下文信息来工作。
  • AI 原生 IDE 往往基于 VS Code 或 Electron fork，权限更大；相比 IDE 插件，插件通常运行在 IDE 提供的沙盒环境中，因此 AI 原生 IDE 更容易做深度定制，agent 编程体验通常更顺畅。
  • 这些工具还可以按照是否允许切换后端大模型来区分：有的允许自由切换大模型和提供商 API；有的只允许在内置模型范围内切换；有的只能使用自家模型；还有些国内厂商区分国内版和国际版，对应可使用模型也不一样。

二、什么是 Agent

并不是所有 AI 工具都是 Agent。很多 AI 工具只是普通的对话或补全界面，而 Agent 更强调“会自己调用工具、观察结果、再继续行动”。

1
2
3
4
5
6
7
8
+----------+      +-------+      +---------+
|   User   | ---> |  LLM  | ---> |  Tool   |
|  prompt  |      |       |      | execute |
+----------+      +---+---+      +----+----+
                        ^               |
                        |   tool_result |
                        +---------------+
                        (loop continues)

对于 Agent 工具，一个著名的概念是 ReAct：让模型边思考边行动。

具体来说，在每一步，模型先推理当前状况（Thought），再执行具体操作（Action），然后观察结果（Observation），再进入下一轮思考。

例如：

1
2
3
4
5
6
7
8
9
Question: 某地区A和地区B的面积总和是多少？
Thought: 我需要分别查到A和B的面积，然后相加。
Action: search[地区A 面积]
Observation: 1234 平方公里
Thought: 现在需要查地区B的面积。
Action: search[地区B 面积]
Observation: 5678 平方公里
Thought: 现在可以计算总和了，1234 + 5678 = 6912。
Action: finish[6912 平方公里]

这个指导思想已经在各种 agent 工具中得到应用，虽然并不是完全遵循这种原始方式。例如 Claude Code 的任务执行通常也会分成“收集上下文、采取行动、验证结果”等阶段。

三、Agent 相关概念

3.1 Function Calling

  • Function Calling (2023)：由 OpenAI 首先提出，允许大型语言模型以结构化方式调用外部 API。这意味着 agent 可以通过简单的指令来查询天气、发送邮件或者获取最新新闻，而不需要了解背后的复杂细节。
  • Function Calling 早期更多依赖 prompt 的“软约束”，现在很多模型会直接在解码层面做“硬约束”，以保证输出格式合法。

3.2 MCP

  • MCP (2024)：Anthropic 推出的 Model Context Protocol，为工具提供统一描述格式。借助 MCP，开发者只需对工具进行一次封装，就能在任何支持该协议的平台上轻松部署和使用。
  • CLI 工具的出现稍微动摇了 MCP 的必要性，因为很多场景下直接在终端执行命令就足够了。

3.3 Skills

  • Skills (2025)：Anthropic 提出并推广的概念。它是一种将复杂指令、最佳实践、领域知识和可选脚本封装为独立“技能包”的机制，核心优势是渐进式披露和按需加载。
  • 很多人认为 skills 可能会取代部分 MCP 场景，这是目前 agent 生态中的一个设计分歧。
  • 目前各家的 Skills 通常采用相同或相近的格式规范，例如 Agent Skills，但对目录名称和扫描顺序的约定并不统一。
  • 除此之外，也可以使用 OpenSkills 给一般 AI 工具提供 Skills 支持：把元信息写入 AGENTS.md 文件，要求 agent 主动读取 AGENTS.md 文件以获取 Skills 信息即可。

四、项目内的约束与扩展

4.1 项目说明文件与约束文件

很多 agent 工具支持通过 AGENTS.md 或 CLAUDE.md 这类文件给 agent 提供长期项目说明。项目里的这类约束文件，本质上是在给 agent 提供稳定的、可复用的上下文。和每次在对话里重复解释相比，这种方式更适合长期项目。

比较常见的用途：

  • 说明项目背景
  • 规定编码和提交习惯
  • 说明哪些目录可以修改、哪些不能动
  • 给出目录约定
  • 提供常用命令或验证方式
  • 规定危险操作限制
  • 告诉 agent 什么时候应该使用特定 skill

4.2 Skills 的写法与约束

“自己写 skill”已经是一个很常见的需求。可以把 skill 理解成一个可复用的小型能力包，本质上是“说明文档 + 可选脚本 + 可选模板/参考资料”的组合，而不是某种神秘的新格式。

skill 的核心入口通常是一个 SKILL.md 文件。Agent 先看到 skill 的名称和简介，再按需读取 SKILL.md，必要时继续读取其中引用的脚本、模板或参考文件。

SKILL.md 顶部通常使用 YAML frontmatter，至少包含 name 和 description 两个字段；正文部分实际就是给大模型看的 prompt 和工作说明，要写清楚，便于理解和执行。

一个常见的 skill 目录大致如下：

1
2
3
4
5
6
7
8
my-skill/
├── SKILL.md
├── scripts/
│   └── run.sh
├── assets/
│   └── output.md
└── references/
    └── notes.md

比较固定的约束包括：

  • name 要求严格和父目录同名，例如目录叫 pdf-processing/，那么 frontmatter 里的 name 也应写成 pdf-processing。
  • name 限制为 1 到 64 个字符，只使用小写字母、数字和连字符 -，不允许以 - 开头或结尾，也不应出现连续的 --。
  • description 一般要求非空，长度不要太长；它不仅要说明“这个 skill 能做什么”，还要说明“什么时候该用它”。
  • description 最好带上足够具体的关键词，因为很多 agent 在启动时只会先读取 name 和 description，skill 能不能被正确触发，往往主要取决于这里写得好不好。

SKILL.md 通常至少应包含这些内容：

  • 这个 skill 是做什么的，适用什么场景，不适用什么场景。
  • Agent 何时应该使用它，触发条件是什么。
  • 处理任务时建议遵循的步骤顺序。
  • 需要读取哪些额外文件，路径相对谁解析。
  • 如果有脚本，脚本的作用、输入输出、副作用和使用限制是什么。
  • 最终产出应长什么样，最好给一个最小示例。

好的 skill 文档一般有几个共同点：

  • 边界清楚：明确这个 skill 解决什么问题，不顺手包办一大堆相邻需求。
  • 触发明确：写清“用户提到什么词”或“任务具备什么特征”时才调用，避免 agent 滥用。
  • 步骤具体：尽量写成可执行流程，而不是泛泛而谈的经验总结。
  • 渐进披露：先让 Agent 读到最小必要说明，只有在需要时再去看 references/ 或运行脚本。
  • 低副作用：如果脚本会改文件、联网、消耗 API、覆盖输出，必须提前写清楚。
  • 正文要克制：SKILL.md 正文最好保持精简，详细资料放到 references/，模板和静态资源放到 assets/，避免把所有内容都塞进一个文件里。
  • 引用用相对路径：在 SKILL.md 中引用其他文件时，通常使用相对于 skill 根目录的路径，方便跨工具迁移。

一个最小示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
---
name: my-skill
description: 用于把访谈、会议记录或调研笔记整理成结构化摘要。适合长文本总结和固定格式输出场景。
compatibility: 适用于支持 Agent Skills 的通用 agent；不依赖联网。
---

# My Skill

## Purpose
用于把原始访谈记录整理成结构化摘要。

## Use When
- 用户要求总结访谈、会议记录、调研笔记
- 输入文本较长，且需要固定格式输出

## Do Not Use When
- 用户只要一句话结论
- 输入不是文本记录

## Workflow
1. 先读取原始文本，判断是否包含多位说话人。
2. 按主题聚类关键信息。
3. 根据 `assets/output.md` 生成输出。
4. 如果需要术语解释，再读取 `references/notes.md`。

## Files
- `assets/output.md`：输出模板
- `references/notes.md`：领域术语说明

## Output
输出应包含：背景、关键观点、争议点、待跟进事项。

实际写 skill 时，重点不是“格式写得多复杂”，而是让 Agent 在低成本读取后，立刻知道三件事：这东西什么时候该用、用了之后按什么步骤做、需要时去哪里继续拿上下文。如果这三点写清楚了，这个 skill 通常就已经可用了。

五、实际使用中的问题

5.1 Agent 工具的一些特点

  • 支持 Plan 和 Act 两种模式，先规划，再执行。
  • 有的工具支持在 Plan 和 Act 模式使用不同模型，例如前者可以使用高推理能力模型，后者可以使用低成本模型。
  • 操作权限是非常关键的问题：通常会默认允许在当前工作文件夹中进行文件读写操作，还可以设置更保守的只允许只读操作，敏感的命令执行前需要手动确认，有时工具还会使用系统提供的沙盒环境。
  • 这些产品为了吸引用户，很多都提供免费使用方式，但免费版本通常伴随很多限制，例如模型较弱、调用次数受限、需要排队等。
  • 目前这些产品仍处于飞速发展阶段，再加上项目本身也在大量利用 AI 加速开发，因此往往每隔几天甚至每天就会发布一个新版本，网上很多教程很快就会过时。

5.2 配置切换

对于 CLI 工具的配置修改，有时虽然实质只是修改 base_url 和 model，但通常需要手动编辑配置文件，而各家的配置文件存储位置和字段规范并不相同。可以使用 cc-switch 这类 GUI 工具在多个配置方案之间快速切换，目前支持的工具包括 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw。

5.3 API 兼容层与灰色地带

目前大多数大模型工具在调用模型时，考虑到生态兼容性，通常会使用公开的 API 与模型服务通信，例如 OpenAI 风格的 /v1/chat/completions、/v1/responses，或者 Anthropic 风格接口。

因此，当客户端运行在用户设备上时，其网络请求在技术上通常可以通过代理或抓包工具进行观察；同时，也可以通过反向代理或 API 网关对请求进行转发、记录或替换模型服务。

这种技术特性也为一些灰色或非法行为提供了空间，例如：通过抓包分析客户端请求结构后搭建兼容 API 的代理服务，将第三方模型伪装成官方接口对外出售；或者通过反向代理转发真实 API 请求，从而规避平台的访问限制、计费机制或身份验证等。这类行为在一些“共享 API”“低价中转 API”中较为常见。

5.4 使用风险

除了常规编程 Agent，还有像 OpenClaw 这类具有极高系统权限、可对接聊天软件的完全 Agent 机器人，但风险也非常高。

个人更适合把这类工具限制在受限环境中使用，例如：

  • Docker
  • 虚拟机

并且只做一些和数据安全无关的简单任务，比如自动搜集网络信息并提供汇报，或者写文案草稿。

OpenClaw 是 GitHub 上的开源项目，代码主要由各种 AI 工具生成和维护，现在看来代码质量并不好，难以维护。实际上，大约几千行代码就可以复刻一个同类产品。

5.5 大模型输出的不确定性

对于 Transformer 大模型，理论上在 temperature=0（贪心解码）时应当是确定的，因为此时完全消除了采样的不确定性，但在实际系统中通常难以严格复现，主要原因包括：

  • 浮点数与并行计算的不确定性：浮点运算不满足结合律，GPU 并行归约顺序不固定，叠加低精度（FP16/BF16），会导致 logits 存在微小差异；
  • 解码过程的高敏感性：多个候选 token 概率接近时，微小扰动即可改变 argmax 结果；自回归生成会迅速放大这一差异，导致整体输出分叉；
  • MoE + batching 引入的结构性不确定性：专家选择是逐 token 进行，但专家容量在 batch 内共享；同一输入在不同 batch 组合下可能被路由到不同专家，从而改变前向计算路径；

此外，服务侧还可能存在：动态 batching / 调度，推理图优化（kernel fusion 等），多副本部署等，都会引入不确定性。

在工具层面，主流 Agent 工具通常都在内部固定温度参数，不再允许用户自行设置。