Ai-Agent

什么是 Agent 你在 ChatGPT 的网页里打一句话，它回一段话。问天气，它给你天气。让它写首诗，它给你一首诗。到这里为止，你手里的是一个大语言模型（Large Language Model，LLM），一个很会接话的问答机器。 可如果它自己握着键盘鼠标，自己翻仓库里的文件，自己往数据库里写数据，把一个"把项目做完"的任务从头做到尾，情况就变了。人们把这种形态叫做 Agent（智能体）。 Claude Code 的 CLI 界面 2025年2月，一款Agent产品横空出世，它就是Claude Code。上图为它的CLI界面。这个就是一个Agent。 很多人在本地把 Agent 跑通了。模型能回答，能调用一两个工具，看起来挺像回事。可一旦放到真实环境里，让它稳定处理用户一个个请求，问题就全冒出来了。模型偶尔把格式写错，工具偶尔抛异常，流程偶尔卡在一个地方不动。每一样都得有人兜底。 这两个东西之间差了一层外壳。 LLM 只负责一件事，把输入变成输出。它没有手，没有脚，连执行一段代码都做不到，它只能生成文字。Agent 的玩法，是让 LLM 当大脑，外面套一个能真正动手的外围工程系统（Harness）。大模型提供推理能力，Harness 提供除模型权重之外的所有基础设施，把模型那些不可靠的自然语言输出，转成工程上可控的系统行为。分开说就是一句话，Agent 等于一个会想的大脑，加一个会干活的身体。 这篇文章会拆开这层壳，一路往下讲。先看 Harness 由什么组成，再看 Agent 接到任务后怎么运转，接着把工具调用和技能积累这两块讲透。 Harness 基座 Harness 通常分成三个核心层。 Runtime（运行时）。维持模型运转的核心循环，负责提示词的组装、结构化输出的解析，以及异常重试机制。可以把它想成发动机，让模型一圈一圈转下去。 Capabilities（能力层）。赋予 Agent 实际操作环境的能力，包括工具注册表、上下文管理、长期记忆读写。这一层决定 Agent 能摸到什么东西。 Assurance（保障层）。也叫 Eval Harness，它存在于离线开发路径里。批量遍历测试数据集（Goldens），调用 Agent 跑完整任务，收集执行轨迹（Traces），再用评估指标打分，比如准确率、幻觉率、LLM-as-a-judge。没有这一层，Agent 就没法稳定迭代。 flowchart TB M["Model 大模型大脑"] subgraph HARNESS["Harness 基座"] direction TB R["Runtime 运行时组装提示词 · 解析输出 · 异常重试"] C["Capabilities 能力层工具注册表 · 上下文管理 · 长期记忆"] A["Assurance 保障层评测数据集 · 收集轨迹 · 打分"] end M --> R R --> C C --> A 想真正学会这套东西，最实在的办法是落到你自己熟悉的工程栈里。用 Python 做测验或复习系统，就抛开高级封装库，手写一个最简的 Runtime Loop，自己处理模型的 JSON 输出和本地业务逻辑的对接。等你亲手撞过一次 JSON 解析报错和无限重试循环，Harness 的价值就彻底清楚了。 ...

前言 如果你用过 GitHub Copilot、ChatGPT 或者其他 AI 编程助手，你可能会注意到它们在理解代码结构和语法方面表现得非常出色。这背后有一个关键技术—— Tree-sitter 。本文将深入探讨 Tree-sitter 的原理、它在 AI Agent 时代的不可替代性，以及如何在 Python 和 C++ 项目中构建一套代码解析流水线。 什么是 Tree-sitter？ 简单来说，Tree-sitter 是一个用于解析代码的增量解析器生成器，它可以将源代码解析成抽象语法树（AST），并提供高效的增量更新能力。它支持多种编程语言，并且可以生成高性能的解析器，使得开发者能够快速构建代码分析工具、编辑器插件和其他与代码相关的应用。 AST（抽象语法树） 抽象语法树（AST，Abstract Syntax Tree），简称 AST，是源代码的抽象语法结构的树状表示。它位于源代码和机器代码之间，提供了一种更高层次的代码表示方式。AST 的节点表示语言的语法结构，如变量声明、函数调用、条件语句等，而边则表示这些结构之间的关系。 AST 的核心作用 代码分析：AST 提供了对代码结构的深入理解，使得静态分析工具能够检测潜在的错误、代码风格问题和安全漏洞。 代码转换：通过操作 AST，开发者可以实现代码的自动重构、优化和转换，例如将一种编程语言的代码转换为另一种语言。 代码生成：编译器可以通过 AST 生成目标代码，从而实现源代码到机器代码的转换。 例如，在 JavaScript 中，以下代码： javascript Copy function add(a, b) { return a + b; } 可以被解析为如下的 AST： ...

前言 做 Agent 开发时，最让工程师头疼的问题往往不是底层大模型（LLM）不够聪明，而是 Agent 的行为难以可控。在真实的业务场景中，用户的一句话可能隐含多种意图，或者意图非常模糊。这就要求 Agent 必须学会在不同的"对话阶段"之间灵活切换——从最初的寒暄问候，到多轮的信息收集，再到决定调用外部工具，最后与用户确认并结束对话。 如果仅仅依靠 Prompt 让大模型自主决定下一步该做什么（例如纯粹的 ReAct 模式），系统会变得极其脆弱。模型可能会陷入死循环、产生幻觉，或者跳过关键的业务校验步骤。为了解决这种复杂性，我们需要引入软件工程中久经考验的标准工具：状态机（State Machine）。它能为概率性的 LLM 提供一个确定性的行为骨架。 什么是状态机 理解状态机最直观的方法是想象一扇普通的门。这扇门有两个状态：开 与 关。你可以对它施加两个事件（动作）：推 与 拉。 如果你对一扇处于关状态的门执行推事件，门就会进入开状态。但如果门已经是开的状态，再执行推就没有任何意义（甚至是一个非法操作）。这就是状态机的核心逻辑：当前状态 + 触发事件 $\to$ 新状态。 在计算机科学中，它的形式化定义通常是一个五元组： 状态集合（$S$）：系统所有可能状态的有限集合。 初始状态（$s_0$）：系统启动时的默认状态（$s_0 \in S$）。 事件集合（$E$）：触发状态改变的输入或条件。 转移函数（$\delta: S \times E \to S$）：定义了在特定状态下接收到特定事件时，应该转移到哪个新状态。 终止状态集合（$F$）：表示流程结束的状态集合（$F \subseteq S$）。 在构建 Agent 时，我们通常会遇到两种常见的状态机类型： 有限状态机（Finite State Machine, FSM）：状态和事件的数量是有限的，所有的状态流转（转移函数）都是在代码中严格预先定义好的。它非常适合逻辑固定、边界清晰的任务。 图状态机（Graph-based State Machine）：这是目前复杂 Agent 框架的主流（如 LangGraph）。它的状态流转可以是动态计算的，原生支持条件分支、循环回路以及并行处理，更适合处理多轮对话和复杂的逻辑编排。 为什么 Agent 需要状态机 一个可靠的 Agent 绝不能是一个"黑盒"。它的运行生命周期应该经历明确的阶段，并且每个阶段（状态）都有单一、清晰的职责。我们来看一个典型的 Agent 运转流程： flowchart TD A[空闲 IDLE] -->|用户提问| B[分析意图 ANALYZING] B -->|需要工具| C[调用工具 TOOL_CALL] B -->|无需工具| D[生成回复 RESPOND] C -->|工具完成| D D -->|发送回复| A 在这个流程中，核心关键点在于意图分析后的条件分支。有些用户请求（如"你是谁？"）可以直接生成回复；而有些请求（如"今天香港的天气如何？"）则必须先去调用天气 API。 ...

前言 笔者今天在处理一批 PDF 文档时，使用了 pyMuPDF 库来提取文本和表格。今天在查阅相关文档时无意间发现了一个名为 pymupdf4llm 的库，它是基于 pyMuPDF 的一个扩展，专门针对将 PDF 内容转换为适合 LLM 输入的 Markdown 格式进行了优化。这个库不仅能提取文本，还能识别表格和图片，并将它们以 Markdown 语法的形式输出，非常适合我们在 RAG 流水线中使用。在这篇文章中，我们先重点关注下pyMuPDF的基本使用。 关于 PyMuPDF PyMuPDF 是一个功能强大的 Python 库，用于处理 PDF、XPS、OpenXPS、CBZ 和 EPUB 等文档格式。它提供了丰富的 API 来提取文本、图像、表格等内容，并支持对文档进行修改和注释。PyMuPDF 的核心优势在于其高效的解析能力和对复杂文档结构的良好支持，使得它成为处理 PDF 文档的首选工具之一。 安装 在 Python 环境中安装 PyMuPDF 非常简单： bash Copy pip install --upgrade pymupdf PyMuPDF 基础功能 1. 打开文档 python Copy import fitz # PyMuPDF 的别名 doc = fitz.open("example.pdf") # 打开 PDF 文档（路径填写相对路径或者绝对路径） print(f"文档页数: {doc.page_count}") 这里，doc 是一个 Document 对象，表示打开的 PDF 文档。你可以通过 doc.page_count 获取文档的总页数。如果你查看 doc 对象的类型，你会发现它是一个 Document 类的实例。 ...