前端

Agent 可观测性决定了系统能不能被维护。没有日志和 trace，Agent 出错时只能靠猜。尤其是多步骤任务中，模型判断、工具调用、状态变化、用户确认和错误恢复都会影响最终结果。

可观测性不是简单打印 console，而是让开发者能复盘 Agent 的完整执行链路。

## 需要记录什么

一次 Agent 任务至少应记录用户请求、模型计划、工具调用、工具参数、工具结果、状态变化、用户确认、错误信息和最终输出。

敏感信息必须脱敏，例如 token、密码、个人信息、内部密钥。日志系统既要可调试，也要安全。

## Trace 结构

Trace 可以把任务表示成时间线或树。根节点是用户目标，子节点是计划步骤、工具调用和状态转移。

例如创建教程的 trace 包括查询文章、创建 tutorial、绑定文章、验证结果。每个节点记录输入、输出、耗时和状态。

这种结构比纯文本日志更适合排查复杂问题。

## 模型输入输出

是否记录完整 prompt 需要谨慎。完整 prompt 有助于调试，但可能包含敏感数据。生产系统可以记录摘要、哈希、脱敏内容或仅在调试模式记录。

模型输出也要记录关键决策，例如为什么选择某个工具，为什么认为任务完成。

## 工具调用日志

工具调用日志是最重要的部分。每次调用应记录工具名、参数、风险等级、执行结果、错误类型和耗时。

如果 Agent 报告成功但用户发现结果不对，工具日志能快速判断是模型误判、工具失败，还是后端接口返回异常。

## 状态变化

长任务需要记录状态变化。例如 pending 到 running，running 到 waiting_approval，waiting_approval 到 completed。

状态日志可以帮助判断任务卡在哪里。是等待授权，还是等待用户确认，还是某个工具一直失败。

## 指标监控

除了日志，还可以统计指标：任务成功率、平均执行时间、工具失败率、用户确认率、重试次数、模型调用成本。

这些指标能帮助发现系统性问题。例如某个工具失败率突然升高，可能是外部 API 变更。

## 小结

可观测性让 Agent 从“黑盒自动化”变成可解释的工程系统。日志、trace、状态记录和指标监控，是 Agent 进入生产环境的基础设施。

## 实战案例：追踪一次失败的工具调用

假设 Agent 调用 upload-link 后返回了一个看似成功的 URL，但页面图片无法显示。没有 trace 时，只能猜是前端、CDN 还是上传接口问题。

有了可观测性，就可以看到：Agent 选择了 material upload-link 工具，传入了外部 SVG URL，工具返回了 cdn.portal.levenx.com 地址，随后验证阶段 curl 返回 404。这样就能定位到上传接口返回了不可访问的旧 CDN URL，而不是标签更新错误。

这类 trace 对 Agent 非常关键。它不仅帮助开发者修 bug，也帮助用户理解 Agent 为什么需要重试、为什么需要修改流程。

## 从日志到告警

可观测性不应只停留在事后查看日志。生产系统还需要告警。例如某个工具连续失败、某类权限错误突然增加、平均执行时间显著升高、用户确认后仍执行失败，都应该触发告警。

这些告警可以帮助团队在用户反馈前发现问题。对于 Agent 系统，工具链和外部 API 变化很常见，自动化监控能显著降低维护成本。

## 成本与性能指标

Agent 可观测性还应包含成本指标。每次任务消耗多少 token、调用多少次模型、执行多少个工具、耗时多久，都应该被记录。

这些数据能帮助团队优化工作流。例如某个步骤总是重复检索，可能需要缓存；某个模型调用成本过高，可能可以换成小模型；某个工具耗时过长，可能需要异步化。

设计 Agent 可观测性系统，记录模型决策、工具调用、状态变化、用户确认和错误恢复过程。

AI Agent 实战教程 18：日志、Trace 与可观测性

很多 Agent Demo 都可以在一个文件里跑起来：定义一个模型、写几个工具函数、拼一段提示词，然后让模型决定下一步做什么。这个阶段很适合验证想法，但如果继续用这种结构承载真实业务，项目很快会失控。

AI Agent 项目天然比普通应用更容易变复杂。它既有模型调用，也有工具系统；既有提示词，也有状态机；既要处理业务数据，也要处理权限、日志、评测和错误恢复。因此，Agent 项目从一开始就应该有清晰的工程结构。

项目结构设计的目标不是追求目录数量，而是让每个模块职责清楚：谁负责理解任务，谁负责执行工具，谁负责保存状态，谁负责记录日志，谁负责评测质量。结构清晰后，团队协作、问题排查和后续扩展都会简单很多。

## 为什么 Agent 项目容易变乱

普通应用的核心逻辑通常比较明确。后端服务围绕 controller、service、model 组织；前端项目围绕页面、组件、状态和 API 组织。而 Agent 项目同时包含多个维度的逻辑：模型推理、工具调用、提示词、工作流、记忆、权限、审计、评测。

如果没有拆分，这些内容很容易混在一起。例如一个文件里既写系统提示词，又写工具函数，还写 API 请求，还保存任务状态。短期看开发很快，长期看每改一个工具都可能影响整个 Agent。

常见混乱表现包括：

- 所有工具都写在一个 tools 文件里；
- prompt 文本散落在代码中，无法版本化；
- 工具返回格式不统一；
- 状态只存在内存变量里，任务中断后无法恢复；
- 权限判断写在模型提示词里，而不是系统逻辑里；
- 没有统一日志，无法知道 Agent 为什么做出某个决策；
- 没有 evals，改一次 prompt 就可能破坏旧能力。

这些问题在演示时不明显，因为演示通常任务短、路径固定、数据少。但一旦进入真实系统，用户会提出模糊需求，接口会失败，权限会不足，任务会中断，工具会越来越多，单文件结构就很难维护。

## 推荐的目录分层

一个中等复杂度的 Agent 项目，可以从下面这些目录开始：

~~~text
agents/
tools/
workflows/
memory/
prompts/
evals/
logs/
config/
types/
~~~

这些目录不是固定标准，而是一种职责划分思路。项目小的时候可以合并，项目变大后可以继续细分。

### agents：定义 Agent 入口和角色

agents 目录用于定义不同 Agent 的角色和入口。例如：

- contentAgent：负责内容管理；
- codingAgent：负责代码修改；
- researchAgent：负责资料检索；
- taskAgent：负责待办和日程；
- reviewAgent：负责审查输出。

每个 Agent 不应该包含全部业务逻辑。它更像一个调度入口：接收用户目标，加载相关工具和 workflow，然后执行任务。

这样设计的好处是，新增一个 Agent 不会影响其他 Agent。比如你可以让 codingAgent 只加载文件和测试工具，而 contentAgent 只加载标签、文章和素材工具。

### tools：封装外部能力

tools 是 Agent 能力的边界。所有外部操作都应该通过工具封装，例如：

- 查询标签；
- 创建文章；
- 上传图片；
- 读取文件；
- 调用搜索 API；
- 创建任务；
- 执行测试命令。

工具应该尽量原子化。一个工具只做一类事情，并提供明确的输入输出。不要把“创建教程并绑定文章”写成一个底层工具，因为它包含多个业务步骤，更适合放在 workflow 中。

一个工具定义通常包含：

- name：工具名称；
- description：什么时候使用；
- schema：参数定义；
- riskLevel：风险等级；
- execute：执行函数；
- output：返回结构。

工具层还应该负责参数校验。例如 URL 是否合法、文件是否存在、ID 是否是数字、用户是否有权限访问目标资源。不要把这些校验交给模型自由判断。

### workflows：组织多步骤流程

workflow 负责把多个工具组合成流程。例如“创建 Treasure 标签并补图”不是一个原子工具，而是一个 workflow：

1. 查询标签是否存在；
2. 搜索合适图片；
3. 上传图片到自有素材系统；
4. 创建标签并绑定图片；
5. 查询标签验证结果；
6. 如果需要，加入标签集。

workflow 可以是简单顺序流程，也可以是状态机或图结构。它应该明确每一步的输入、输出、失败处理和验证方式。

把流程放在 workflow 层，而不是写进 prompt，有一个重要好处：流程可以测试，可以复用，也可以在失败后恢复。

### memory：管理短期和长期记忆

memory 目录用于管理 Agent 的记忆系统。短期记忆可以保存当前任务状态，长期记忆可以保存用户偏好和历史经验。

例如用户要求“每篇文章标签不超过 3 个”，这就是一个长期偏好。又比如“treasure article create 需要先创建 draftId”，这是一个工具经验。

记忆系统应该有写入规则，不应该把所有对话都保存下来。还要支持查看、删除、过期和脱敏。

### prompts：管理提示词

提示词应该作为项目资产管理，而不是散落在代码里。prompts 目录可以保存：

- 系统提示词；
- 工具使用说明；
- 输出格式模板；
- 审查提示词；
- 总结提示词；
- 任务拆解提示词。

提示词最好版本化。每次修改都应该知道改了什么、为什么改、影响了哪些评测。

### evals：评测与回归测试

Agent 项目如果没有 evals，很容易越改越不可控。evals 目录可以保存测试用例，例如：

- 创建标签时必须先查重；
- 图片不能直接使用外链，必须上传到自有素材系统；
- 删除操作必须确认；
- 文章正文不能带一级标题；
- 每篇文章标签不能超过 3 个。

这些规则都可以变成评测项。每次改 prompt、工具或 workflow 后跑一遍，能减少回归问题。

### logs：日志和 trace

logs 目录或日志模块用于记录 Agent 的执行过程。至少应该记录：用户目标、计划步骤、工具调用、参数、返回结果、错误信息、用户确认和最终输出。

生产环境中，不一定把日志写到本地目录，也可能写到数据库、对象存储或 observability 平台。但从项目结构上，日志能力应该是独立模块，而不是零散 console。

### config：配置与密钥

config 管理模型配置、工具开关、API Base、权限策略、重试次数和环境变量。

密钥不要写进代码。对于 Agent 项目尤其要注意，因为工具可能访问很多外部系统。配置层应该明确哪些信息来自环境变量，哪些可以写入配置文件，哪些必须通过用户授权获得。

## 一个示例结构

下面是一个简化示例：

~~~text
src/
  agents/
    content-agent.ts
    coding-agent.ts
  tools/
    treasure/
      tag-tools.ts
      article-tools.ts
      material-tools.ts
    filesystem/
      read-file.ts
      write-file.ts
  workflows/
    create-tag-with-image.ts
    create-tutorial-series.ts
  memory/
    preference-memory.ts
    task-state-store.ts
  prompts/
    system.md
    reviewer.md
  evals/
    create-tag.eval.json
    article-style.eval.json
  logs/
    trace.ts
  config/
    model.ts
    permissions.ts
~~~

这个结构的重点是：工具不直接决定业务流程，workflow 不直接写底层 API，Agent 不承载所有实现细节。

## 目录结构和团队协作

当团队多人协作时，清晰结构更加重要。负责工具的人可以维护 tools，负责内容质量的人可以维护 prompts 和 evals，负责平台稳定性的人可以维护 logs 和 config。

如果所有逻辑都在一个 Agent 文件里，任何人修改都可能影响全部能力。模块拆分后，变更边界更清楚，也更容易 code review。

## 常见误区

第一个误区是过早抽象。项目刚开始时不需要设计复杂框架，但至少要避免把工具、prompt 和流程混在一起。

第二个误区是只拆目录，不拆职责。目录很多但每个文件仍然互相调用、互相依赖，复杂度并没有降低。

第三个误区是忽略评测。Agent 项目最容易因为 prompt 改动产生隐性回归，没有 evals 很难发现。

第四个误区是忽略权限。工具目录里如果没有风险等级和权限说明，后续加审批会很痛苦。

## 小结

Agent 项目结构的目标，是让模型能力、工具能力和业务流程分离。agents 负责入口和角色，tools 负责外部能力，workflows 负责任务编排，memory 负责上下文和偏好，prompts 负责语言策略，evals 负责质量保障，logs 负责可观测性。

一个好的结构不会让项目一开始变复杂，而是让复杂度在增长时仍然可控。对于要进入真实业务的 AI Agent，这是非常值得提前设计的基础。

从工程角度拆解 Agent 项目目录结构，理解 tools、workflows、memory、prompts、evals 和 logs 如何分层组织。

AI Agent 实战教程 11：如何设计一个 Agent 项目结构

Agent 越能做事，越需要安全、授权和沙箱。一个只能回答问题的模型，风险主要是内容是否准确；一个能读文件、改代码、发消息、删数据、部署服务的 Agent，风险就变成了真实系统风险。

因此，Agent 安全不是上线前才补的功能，而是架构设计的一部分。权限、沙箱、人工确认和审计日志，决定了 Agent 能否在真实环境中可靠运行。

## Agent 安全要回答的问题

设计 Agent 安全机制时，至少要回答几个问题。

第一，Agent 能访问什么资源？例如哪些文件、哪些数据库、哪些 API、哪些用户数据。

第二，Agent 能执行什么操作？读取、创建、更新、删除、发布、发送、部署，这些操作风险完全不同。

第三，谁授权了这些操作？授权是一次性的，还是长期有效的？是否可以撤销？

第四，哪些操作必须人工确认？确认信息是否足够清晰？用户是否知道将发生什么？

第五，操作是否可审计？出问题后能否知道 Agent 做了什么、为什么做、结果是什么？

## 最小权限原则

最小权限原则要求 Agent 只获得当前任务需要的权限。

如果用户只是想查询标签列表，Agent 不应该拥有删除标签的权限。如果用户只是想读取文件，Agent 不应该能写入整个文件系统。

最小权限可以从多个层面实现：

- 工具级权限；
- API scope；
- 文件系统沙箱；
- 网络访问白名单；
- 用户身份隔离；
- 临时授权。

权限越细，系统越安全，但使用成本也会上升。因此需要在安全性和体验之间平衡。

## 沙箱机制

沙箱用于限制 Agent 的运行环境。它可以限制文件读写范围、网络访问、命令执行、环境变量和系统资源。

例如一个代码 Agent 可以被限制只能修改当前工作区文件，不能访问用户 Home 目录。一个内容管理 Agent 可以被限制只能调用查询接口，写入操作需要额外确认。

沙箱的价值不是阻碍 Agent，而是让用户敢于把更重要的任务交给 Agent。

## Human-in-the-loop

Human-in-the-loop 指在关键节点让人参与确认。它适合高风险操作，例如：

- 删除数据；
- 发布文章；
- 修改生产配置；
- 发送邮件或消息；
- 执行部署；
- 进行付费操作；
- 授权访问敏感系统。

确认应该具体，而不是简单问“是否继续”。好的确认会展示操作类型、目标资源、关键参数和潜在风险。

## 授权流程

Agent 授权通常分为两类。

第一类是平台授权，例如 OAuth。用户授权 Agent 访问日历、任务、文档等资源。

第二类是本地执行授权，例如允许 Agent 访问网络、写入某个目录、运行某个命令。

这两类授权经常同时存在。比如一个 Agent 创建飞书待办，既需要飞书 API scope，也需要本地执行环境允许调用 CLI 和访问 keychain。

## 审计日志

审计日志应该记录关键操作：

- 用户请求；
- Agent 计划；
- 工具名称；
- 调用参数；
- 返回结果；
- 用户确认；
- 时间；
- 操作者身份；
- 错误信息。

没有审计日志，Agent 出错后只能猜原因。生产系统必须能复盘。

## 常见安全误区

第一个误区是把权限全交给提示词。提示词可以提醒模型不要做危险事，但不能替代系统级权限控制。

第二个误区是默认信任工具参数。模型生成的参数必须校验。

第三个误区是为了方便关闭确认。短期体验变好了，长期风险会大幅增加。

第四个误区是忽略读取权限。读取敏感数据同样有风险，不只是写操作危险。

## 小结

Agent 安全的目标不是让 Agent 什么都不能做，而是在可控边界内让它放心地做事。最小权限、沙箱、人工确认和审计日志，是 Agent 从演示走向生产的必要条件。

从授权、沙箱、人工确认、审计日志和最小权限原则理解 Agent 安全设计。

AI Agent 实战教程 09：安全、授权与沙箱

Git是一个由林纳斯·托瓦兹为了更好地管理linux内核开发而创立的分布式版本控制／软件配置管理软件。需要注意的是和GNU Interactive Tools，一个类似Norton Commander界面的文件管理器相区分。



C 语言，是一种通用的、过程式的编程语言，广泛用于系统与应用软件的开发。具有高效、灵活、功能丰富、表达力强和较高的移植性等特点，在程序员中备受青睐。

C 语言是由 UNIX 的研制者丹尼斯·里奇（Dennis Ritchie）和肯·汤普逊（Ken Thompson）于 1970 年研制出的B语言的基础上发展和完善起来的。目前，C 语言编译器普遍存在于各种不同的操作系统中，例如 UNIX、MS-D

C语言

C++ 是一种通用的、静态类型的编程语言，它具有高效性、灵活性和可移植性等特点。C++ 基于 C 语言，同时支持面向对象编程和泛型编程，可以用于开发各种类型的应用程序，如系统软件、游戏、桌面应用程序、移动应用程序等。

C++ 的主要特点包括：

高效性：C++ 是一种编译型语言，可以生成高效的本地代码，在性能要求高的应用程序中得到广泛应用；
面向对象编程：C++ 支持面向对象编程，包括封装、继承

React 是一个由 Facebook 开发的流行的 JavaScript 库，用于构建交互式用户界面。它采用了一种基于组件化的开发模式，使得开发人员可以将 UI 拆分为独立的、可复用的组件，并由这些组件构建复杂的用户界面。

React 的主要特点包括：

组件化开发：React 将 UI 拆分为独立的、可复用的组件，开发人员可以将这些组件组合在一起构建复杂的用户界面；
虚拟 DOM：React

React

Web前端开发是从网页制作演变而来的，名称上有很明显的时代特征。在互联网的演化进程中，网页制作是Web 1.0时代的产物，那时网站的主要内容都是静态的，用户使用网站的行为也以浏览为主。2005年以后，互联网进入Web 2.0时代，各种类似桌面软件的Web应用大量涌现，网站的前端由此发生了翻天覆地的变化。网页不再只是承载单一的文字和图片，各种富媒体让网页的内容更加生动，网页上软件化的交互形式为用户提

JavaScript 是一种基于脚本的编程语言，主要用于在 Web 页面上实现交互式的效果和动态的内容。JavaScript 是一种解释性语言，不需要编译就可以直接在浏览器中运行。

JavaScript 的主要特点包括：

轻量级：JavaScript 代码通常比较短小，可以快速加载和执行。

可移植性：JavaScript 可以在各种不同的浏览器和操作系统上运行。

面向对象编程：JavaSc

JavaScript

Cypress 是一个前端自动化测试工具，用于测试基于Web的应用程序。它能够测试运行在浏览器中的应用，并且适用于单元测试、集成测试和端到端（E2E）测试。Cypress 提供了一个丰富的API集，以及一个友好的交互式界面，让开发和测试人员能够轻松编写、运行和调试测试用例。

Cypress

ORM（Object-Relational Mapping，对象关系映射）是编程中的一个概念，它指的是一种技术手段，可以将不兼容的类型系统转换为面向对象模型。换句话说，ORM 允许开发者在编程语言中使用对象的方式来操作数据库中的数据。

Linux 是一个广泛使用的开源操作系统内核，由林纳斯·托瓦兹（Linus Torvalds）于1991年创建。它是 Unix-like 操作系统的一个重要分支，并且它的设计和实现遵循了模块化的设计原则。Linux 内核本身可以与不同的用户空间组件配合，形成完整的操作系统。这些完整的系统被称为 Linux 发行版，例如 Ubuntu、Fedora、Debian、CentOS 和 Arch Linu

Linux

Vue.js（简称 Vue）是一种开源的轻量级 JavaScript 框架，由 Evan You 于2014年首次发布。Vue 致力于在用户界面（UI）开发中实现数据与视图的双向绑定，为创建现代化 Web 应用、单页面应用（SPA）以及多种复杂界面提供了一种简洁、高效且可扩展的解决方案。

#### 核心特性

- **组件化：** Vue 包含了独立的、可复用的组件，有助于将 UI 切成逻辑部分

Docker 是一个开源的容器化平台，允许开发者打包应用及其全部依赖到一个可移植的容器中，然后这个容器可以在任何机器上运行，确保应用在不同环境之间运行的一致性。Docker 使用了 Linux 容器（LXC）的技术，但进行了扩展，使其更为易用、功能更全面。

Docker

Rust是一种系统编程语言，由Mozilla Research开发。它是一种安全、并发和高效的语言，旨在为开发人员提供更好的内存安全和线程安全，同时保持高性能和可扩展性。

Rust的设计具有以下特点：

内存安全：Rust在编译时执行内存安全检查，防止常见的内存错误，例如使用空指针或释放不再使用的内存。

并发性：Rust具有一种称为"无等待"（lock-free）的并发模型，它可以确保线程安全

Rust

MySQL 是一款流行的关系型数据库管理系统（RDBMS）。它负责存储、检索和管理结构化数据，尤其是以表格形式存储的数据。MySQL 使用 SQL（Structured Query Language，结构化查询语言）作为查询和操作数据的接口，并遵循许多 SQL 标准。它是一种兼具性能、可靠性和易用性的数据库系统，适用于各种应用场景，从个人项目到大型企业应用。

MySQL

JavaScript 的升级版 TypeScript 已日益成为开发世界全新的演变里程碑。立足于 JavaScript 的优雅灵活与 TypeScript 的强类型体系，本教程旨在助您铸就极致的开发力量。

我们的 TypeScript 系列教程将自始至终地引导你掌握 TypeScript 的各种方面，与您一起，宏观理解 JavaScript 世界、深入钻研 TypeScript 规则与逻辑，探索

TypeScript

Mongoose 是一个面向 MongoDB 数据库的对象数据模型（ODM）库，用于在 Node.js 环境下建模和操作 MongoDB 文档结构。它提供了一些方便的特性，如数据验证、查询构建、业务逻辑钩子（hooks）和中间件，使得处理 MongoDB 文档更加直观和安全。


Mongoose

Tailwind CSS 是一个非常强大且受欢迎的实用型 CSS 框架，于2017年由.Adam Wathan、Jonathan Reinink、David Hemphill 和 Steve Schoger 共同创立。 这个框架的主要目标是帮助开发者快速构建定制化的用户界面，而无需从头开始编写 CSS 代码。
Tailwind 提供了一整套预先定义好的类名，代表 CSS 的各种属性，如颜色、字体大

Tailwind CSS

Elasticsearch（常写作 Elasticsearch）是基于 Lucene 的分布式搜索与分析引擎，面向海量数据提供近实时（NRT）的全文检索、结构化查询与聚合分析能力。它以 JSON 文档为核心数据模型，通过 索引（index）—分片（shard）—副本（replica） 的机制实现横向扩展与高可用：数据被切分到多个分片分布在不同节点上，副本用于容灾与提升读取吞吐。Elasticsea

ElasticSearch

Go，也称为 Golang，是一种开源的编程语言，由 Google 开发。Go 是一种静态类型、编译型、并发型的语言，它被设计为一种简单、快速、可靠和高效的语言。Go 语言的语法类似于 C 语言，但也借鉴了其他语言的一些特性，如 Python 和 Java。

Go 语言的设计目标是提供一种简单、易于学习和使用的语言，同时具有高效的执行速度和并发处理能力。Go 语言的主要特点包括：

1. 并发支

Golang

CSS（Cascading Style Sheets）是一种用于描述文档样式和布局的样式表语言，常用于 Web 开发中。它通过定义样式规则来控制 HTML 元素的外观和布局，使得开发人员可以更加灵活地控制页面的样式和排版。

CSS 的主要特点包括：

分离样式和内容：CSS 可以将样式信息从 HTML 内容中分离出来，使得样式和内容的管理更加清晰和易于维护；
层叠样式：CSS 中的样式规则是可以

Network（网络）是指连接在一起的计算机、设备和其他物体，它们可以彼此通信和交换信息。网络可以分为局域网（LAN）、广域网（WAN）、互联网（Internet）等不同的类型和层次，它们在不同的范围和层次上提供了不同的服务和功能。

网络的主要特点包括：

连通性：网络可以将不同的计算机、设备和应用程序连接在一起，实现彼此之间的通信和数据交换。

分布式：网络中的计算机和设备分布在不同的地理位置

Codex