前端

> Skill 地址：https://www.skills.sh/remotion-dev/skills/remotion-best-practices

remotion-best-practices 是一个面向 Remotion 视频开发的 Agent Skill。Remotion 的特点是用 React、TypeScript 和 Web 技术生成视频，这让前端开发者可以像写组件一样写视频。但视频项目和普通 Web 页面不同，它需要关注帧、时间轴、渲染性能、资源加载、音视频同步和最终导出质量。

这个 Skill 的价值在于，让 Agent 在生成或修改 Remotion 项目时遵循更稳定的工程实践，而不是只写出一段能预览的组件代码。它适合帮助开发者构建可维护、可渲染、性能更稳定的视频工程。

## 它主要解决什么问题

remotion-best-practices 主要解决 AI Agent 写 Remotion 代码时容易忽略的视频工程细节。

普通 React 页面关注交互和状态，而 Remotion 项目关注时间和帧。一个动画是否正确，不只看组件结构，还要看帧数、fps、duration、composition、资源加载和渲染确定性。如果 Agent 不理解这些约束，生成的视频可能在预览中勉强可用，但渲染时出现闪烁、卡顿、资源缺失或时间不准。

这个 Skill 通常会提醒 Agent：

- 正确使用 Composition 和 durationInFrames；
- 使用 useCurrentFrame、interpolate 等 Remotion API 控制动画；
- 避免依赖非确定性逻辑；
- 处理图片、字体、音频和视频资源加载；
- 保证组件在不同帧下可预测渲染；
- 注意渲染性能和导出稳定性；
- 让视频代码更接近真实项目，而不是临时 Demo。

它适合用于生成产品宣传视频、代码演示视频、数据可视化视频、自动化短视频、字幕动画、社交媒体视频模板等场景。

## 安装与启用方式

可以使用 Skills CLI 安装这个 Skill：

~~~bash
npx skills add remotion-dev/remotion-best-practices
~~~

安装后，通常需要重启或刷新 Agent，让它重新加载 skills metadata。之后，当你要求 Agent 创建 Remotion 视频、修改 Remotion Composition、优化视频渲染或排查 Remotion 项目问题时，它就应该优先应用这个 Skill 的规则。

安装后可以用一个简单任务验证：

~~~text
帮我用 Remotion 做一个 10 秒的产品功能介绍视频，包含标题入场、三段功能卡片动画和结尾 CTA。
~~~

如果 Agent 不只是写 React 组件，而是主动考虑 fps、durationInFrames、时间轴、动画插值和资源组织，就说明这个 Skill 开始发挥作用。

## 推荐使用方式

使用这个 Skill 时，最好把视频目标描述清楚。Remotion 项目对时间结构很敏感，所以提示词里建议包含视频时长、分辨率、fps、画面结构、素材来源和动画风格。

例如：

~~~text
帮我创建一个 Remotion 视频，时长 12 秒，分辨率 1920x1080，30fps。内容是 AI Agent 产品介绍：前 3 秒展示标题，接着 6 秒展示三个能力卡片，最后 3 秒展示 CTA。动画要简洁、科技感，不要过度花哨。
~~~

如果是优化已有项目，可以这样写：

~~~text
请 review 这个 Remotion composition，检查时间轴、动画插值、资源加载和渲染性能问题，并给出修改建议。
~~~

如果是排查问题，可以提供错误信息、composition 名称、视频时长和相关组件，让 Agent 更容易定位。

## 实战中应该关注的细节

第一，时间线要清晰。视频代码最好明确每个阶段从哪一帧开始、持续多少帧。不要把所有动画时间写成散落的魔法数字。

第二，动画要可预测。Remotion 渲染要求同一帧输出稳定结果，因此不要在渲染过程中使用随机数、当前时间或不可控副作用。如果需要随机效果，应使用固定 seed。

第三，资源要提前规划。图片、字体、音频、视频素材都可能影响渲染。Agent 应该关注资源路径、加载方式、文件大小和格式兼容性。

第四，性能要考虑。复杂 SVG、大量 DOM、过多滤镜、频繁布局计算都会拖慢渲染。视频越长、分辨率越高，性能问题越明显。

第五，组件要可复用。标题动画、卡片动画、字幕、Logo、背景这些元素可以抽成组件，避免每个视频都从头写一遍。

## 常见误区

第一个误区是把 Remotion 当普通 React 页面写。普通页面可以依赖用户交互和运行时状态，但 Remotion 更强调帧级确定性。

第二个误区是忽略 durationInFrames。视频长度不明确时，动画很容易提前结束或超出画面。

第三个误区是只关注预览，不关注最终渲染。预览能播放不代表导出稳定，尤其是外部资源、字体和音频。

第四个误区是过度动画。视频不一定越炫越好。产品视频更需要节奏清晰、信息可读、视觉一致。

## 与其他 Skill 的配合

remotion-best-practices 可以和 frontend-design 配合。frontend-design 负责视觉结构、信息层级和画面风格，remotion-best-practices 负责把这些设计转化成稳定的视频时间轴和 Remotion 实现。

它也可以和代码审查类 Skill 配合，用于检查 composition 是否可维护、是否有性能风险、是否存在资源加载问题。

如果视频内容来自数据，还可以配合数据可视化类 Skill，把图表、指标和趋势设计成适合视频呈现的动画。

## 小结

remotion-best-practices 的核心价值，是让 Agent 更懂 Remotion 视频工程。它不仅帮助生成代码，还会关注帧、时间轴、资源、性能和渲染确定性。对于想用 AI Agent 生成产品视频、动态演示和自动化视频模板的开发者来说，这是一个非常实用的 Skill。

介绍 remotion-best-practices Skill 的功能、安装方式、使用方法、Remotion 视频工程实践、常见误区和与其他 Skill 的配合方式。

Agent Skills 教程 02：remotion-best-practices 视频生成实践

> Skill 地址：https://www.skills.sh/anthropics/skills/frontend-design

frontend-design 是一个专门面向前端界面设计与实现的 Agent Skill。它的重点不是让 Agent 随机生成一段“看起来能运行”的页面代码，而是帮助 Agent 按更接近真实产品设计的方式工作：先理解页面目标，再规划信息层级，确定视觉风格，拆分组件结构，补齐交互状态，最后落到可维护的前端实现。

如果你经常让 AI 生成页面，就会遇到一个典型问题：代码能跑，元素也齐全，但页面缺少产品感。比如间距混乱、视觉层级不清、按钮状态缺失、移动端布局崩掉、表单没有错误态。这正是 frontend-design 这类 Skill 适合解决的问题。

## 它主要解决什么问题

frontend-design 的作用可以理解为给 Agent 增加一套前端设计判断力。普通代码生成通常更关注“功能是否实现”，而这个 Skill 会提醒 Agent 同时关注“用户是否容易理解和使用”。

它适合处理这些任务：

- 设计 SaaS 官网、产品落地页、活动页；
- 构建 Dashboard、管理后台、数据分析页面；
- 优化表单、弹窗、卡片、导航、表格等组件；
- 为已有页面做 UI/UX review；
- 改善颜色、字体、间距、层级和响应式；
- 检查页面是否包含 loading、empty、error、disabled 等状态；
- 让一个粗糙页面更接近成熟产品。

它的价值不是“让页面更花哨”，而是让页面更清晰、更一致、更符合用户目标。

## 安装与启用方式

安装方式取决于你使用的 Agent 平台。大多数 Skills 都遵循类似结构：一个 skill 目录中包含 SKILL.md，里面定义 skill 名称、触发说明和使用规则。

如果你从 Skills 平台安装，可以打开 frontend-design 的页面，复制平台提供的安装命令，安装到当前 Agent 的 skills 目录。常见安装方式是使用 「npx skills add」。例如可以执行：

~~~bash
npx skills add anthropics/frontend-design
~~~

安装完成后，通常需要重启或刷新 Agent，让它重新加载 skill metadata。

如果手动安装，可以把 skill 放到类似这样的目录：

~~~text
~/.agents/skills/frontend-design/SKILL.md
~~~

或者放到项目约定的本地 skills 目录中。关键是 Agent 启动时能扫描到它的 name 和 description。

安装后可以用一个简单任务验证：

~~~text
帮我设计一个 AI 工具产品的 landing page，面向开发者，包含 Hero、功能介绍、使用流程、价格和 FAQ。
~~~

如果 Agent 开始先分析页面目标、用户群体、模块结构和视觉风格，而不是直接输出一坨代码，说明这个 Skill 已经发挥作用。

## 推荐使用方式

使用 frontend-design 时，提示词越具体，效果越稳定。不要只说“帮我写个页面”，最好说明产品类型、目标用户、视觉风格、技术栈和页面模块。

比如可以这样写：

~~~text
帮我设计一个 AI Agent 产品落地页，目标用户是开发者。风格要专业、有科技感，但不要过度炫酷。技术栈使用 React + Tailwind。页面包含 Hero、核心能力、使用流程、价格和 FAQ。
~~~

如果是优化已有页面，可以这样写：

~~~text
请 review 这个 Dashboard 页面，重点检查信息层级、间距、按钮状态、响应式和可访问性，并给出可以直接落地的修改建议。
~~~

如果是组件级任务，可以这样写：

~~~text
帮我设计一个文件上传组件，需要支持拖拽、上传中、上传失败、空状态和成功状态，风格要和现有后台系统一致。
~~~

更推荐的工作流是：先让 Agent 给出设计方案和组件拆分，再进入实现。这样你可以先确认方向，避免它直接生成大量不符合预期的代码。

## 实战中应该关注的细节

第一，要明确页面目标。落地页要突出价值主张和转化按钮，后台页面要突出效率和数据密度，设置页要突出清晰分组和安全感。不同页面不能用同一套视觉套路。

第二，要遵守现有设计系统。如果项目已经使用 Ant Design、shadcn/ui、Material UI 或内部组件库，就应该优先复用已有组件、颜色 token、间距和交互规范。不要让 Agent 重新发明一套风格。

第三，要补齐真实状态。一个产品级组件至少要考虑默认态、hover、focus、disabled、loading、empty、error 和 success。很多 AI 页面看起来像截图，就是因为只有理想状态，没有真实数据状态。

第四，要考虑响应式。桌面端三栏布局在移动端可能需要变成单列；复杂表格在小屏可能需要横向滚动或卡片化展示；按钮组也需要考虑换行和触控尺寸。

第五，要关注可访问性。按钮要有明确文案，表单要有 label，颜色对比度要足够，交互元素要能键盘访问。可访问性不是额外加分项，而是产品质量的一部分。

## 常见误区

一个常见误区是过度追求“AI 感”。大量渐变、发光边框、玻璃拟态和复杂动画并不一定高级。如果产品是 B2B 工具，清晰、稳定、专业往往比炫酷更重要。

另一个误区是只看首屏。很多页面首屏不错，但价格区、FAQ、表单状态、移动端表现很弱。frontend-design 更适合帮助你系统性检查整页体验。

还有一个误区是让 Agent 直接改代码，但不给项目上下文。实际项目中，应该先让 Agent 读取现有组件和样式约定，再做修改。否则生成的 UI 可能和项目风格割裂。

## 与其他 Skill 的配合

frontend-design 可以和代码实现类 Skill 配合。它负责设计判断、页面结构和体验建议，代码类 Skill 负责落地实现、重构和测试。

如果项目涉及复杂图表，也可以配合数据可视化类 Skill；如果涉及文案和品牌表达，可以配合写作类 Skill；如果涉及组件库规范，可以配合设计系统相关 Skill。

## 小结

frontend-design 的价值在于让 Agent 不只是“会写前端”，而是更懂“如何设计一个可用、好用、像产品的前端界面”。它适合用于页面设计、组件实现、UI 优化和体验审查。正确使用它时，你应该提供清晰业务目标和项目约束，让 Agent 先做设计判断，再进入代码实现。

介绍 frontend-design Skill 的适用场景、核心能力、推荐工作流、提示词示例和落地注意事项，帮助开发者用 AI Agent 生成更接近产品级的前端界面。

Agent Skills 教程 01：frontend-design 前端设计技能

很多 AI Agent Demo 看起来很惊艳：用户输入一个目标，模型自动规划，调用工具，最后给出结果。但 Demo 能跑通，并不代表它已经具备生产可用性。生产环境关心的是稳定性、安全性、可维护性、成本和可复盘能力。

这一篇是整个系列的落地清单。你可以把它当作上线前检查表，用来判断一个 Agent 项目是否已经从“能演示”走向“能负责”。

## 目标边界是否清晰

首先要确认 Agent 解决什么问题，不解决什么问题。很多项目一开始想做“万能助手”，最后会变成工具很多、边界模糊、失败难查的系统。

更好的方式是从明确场景开始，例如内容管理助手、任务管理助手、代码审查助手、知识库问答助手。每个场景都要定义输入范围、输出目标、允许工具和拒绝条件。

如果用户提出超出边界的请求，Agent 应该说明原因，而不是硬着头皮执行。

## 工具系统是否稳定

生产 Agent 必须有稳定工具系统。每个工具都要有清晰 schema、参数校验、风险等级、结构化返回和错误类型。

检查清单包括：工具是否原子化，参数是否有类型和必填约束，写操作是否区分风险，返回值是否包含 id、url、status，错误是否可被 Agent 理解，是否支持幂等和重试。

如果工具只返回自然语言，后续步骤很难可靠引用结果。如果工具没有风险等级，高风险操作就容易被误执行。

## 权限和审批是否到位

Agent 需要两层控制：授权和审批。授权决定它能访问哪些系统，审批决定本次操作是否可以执行。

上线前要检查 OAuth scope 是否最小化，不同用户数据是否隔离，删除、发布、发消息、部署是否需要确认，审批前是否展示操作预览，用户拒绝后是否停止执行，审批记录是否进入日志。

不要依赖提示词让模型“谨慎一点”。安全边界必须由系统强制执行。

## 状态和恢复是否可靠

只要任务超过一步，就需要状态管理。系统要知道当前执行到哪一步，哪些资源已经创建，哪些步骤失败，用户是否确认过。

检查点包括：是否有任务状态，是否有步骤状态，是否支持断点续跑，重试是否幂等，等待授权或审批时是否保存上下文，失败后是否能给出可执行建议。

没有状态的 Agent 很容易重复创建资源，或者在失败后仍然报告成功。

## RAG 和 Memory 是否可控

如果 Agent 使用 RAG，要检查文档切分、Embedding、索引更新、权限过滤和引用来源。模型回答应区分资料明确说明和模型推断。

如果 Agent 使用 Memory，要检查用户是否能查看、修改和删除记忆。敏感信息不能默认进入长期记忆，偏好记忆也要有作用域和更新时间。

知识和记忆越强，越需要治理。

## 评测与可观测性

上线前应准备评测集，覆盖常见任务、边界情况、权限场景和失败恢复。上线后要持续记录日志和 trace。

关键指标包括任务成功率、工具失败率、平均耗时、模型调用成本、重试次数和用户反馈。评测不只看最终回答，还要看工具调用过程、权限确认和线上状态。

## 小结

从 Demo 到生产，AI Agent 需要的不只是更强模型，而是一整套工程体系。目标边界、工具系统、权限审批、状态恢复、RAG、Memory、评测和可观测性缺一不可。真正可靠的 Agent，不是偶尔表现聪明，而是在大量真实任务中稳定、可控、可复盘。

## 最后一道上线门槛

真正上线前，建议做一次端到端演练。让 Agent 从一个真实用户目标开始，完整执行工具调用、权限确认、状态恢复、结果验证和日志记录。

演练结束后，不只看结果是否成功，还要检查每一步是否可解释、失败时是否能恢复、用户是否能理解确认信息、日志是否足够复盘。只有这些都通过，Agent 才算从 Demo 进入可负责的生产系统。

总结 AI Agent 从 Demo 到生产的检查清单，覆盖目标边界、工具、权限、状态、评测、日志和运营。

AI Agent 实战教程 20：从 Demo 到生产系统的落地清单

AI Agent 从 Demo 走向生产时，最先暴露的问题往往不是模型不会回答，而是系统跑不稳、响应太慢、成本过高、外部工具偶发失败。一个本地 Demo 可以忽略并发、队列、超时和限流，但线上 Agent 面对的是真实用户、真实数据和真实费用。

因此，部署 Agent 时不能只考虑“模型能不能调用成功”，还要把它当成一个长期运行的任务系统来设计。这个系统需要能排队、能恢复、能限流、能降级，也要能追踪每一次模型调用和工具执行的成本。

## 同步 API 与异步任务

最简单的部署方式是同步 API。用户发起请求，服务端调用模型和工具，最终返回结果。这种方式适合短任务，例如简单问答、格式转换、单次查询。

但 Agent 经常执行多步骤任务，例如检索资料、创建文章、上传图片、等待用户确认、绑定教程、验证结果。这样的任务可能持续几十秒甚至几分钟。如果仍然使用同步请求，用户体验会很差，也容易遇到超时。

更稳的方式是异步任务。用户提交目标后，系统返回 taskId，后台执行 Agent 流程。前端可以轮询任务状态，也可以通过 WebSocket 或事件推送更新进度。这样用户能看到任务处于 running、waiting_approval、failed、completed 哪个阶段。

## 队列与并发控制

Agent 任务通常会调用模型和外部工具，这些资源都不是无限的。没有队列控制时，短时间大量请求可能导致模型 API 限流、数据库连接耗尽、工具服务超时。

可以按任务类型建立队列。例如普通问答走轻量队列，内容生成走长任务队列，批量写入走低并发队列。对于写操作，还可以按资源加锁，避免两个 Agent 同时修改同一个教程或同一篇文章。

并发控制不是为了降低性能，而是为了保证系统在压力下仍然可预测。

## 限流策略

限流可以按用户、组织、模型、工具和风险等级设计。

例如普通用户每分钟最多触发一定次数任务；高成本模型每天有配额；上传、发布、删除等写操作限制并发；同一个资源在同一时间只能被一个任务修改。

限流策略最好返回明确错误，让 Agent 能解释原因，而不是简单报“请求失败”。比如提示“当前任务过多，请稍后重试”或“今日高成本模型额度已用完”。

## 成本来源与优化

Agent 成本不只来自模型单价。一次任务可能包含多次模型调用、多轮检索、多次工具执行和大量上下文传输。

常见成本来源包括 Planner 调用强模型、每个步骤都带完整历史、工具返回内容过长、检索结果未压缩、失败后无限重试、多 Agent 讨论过多轮。

优化策略包括：简单任务使用小模型，复杂规划使用强模型；工具结果先摘要再进入上下文；重复检索做缓存；失败任务限制重试次数；长任务拆成可恢复步骤，只重试失败部分。

## 超时和降级

每个工具都应该有超时设置。搜索、上传、数据库查询、浏览器自动化都可能卡住。超时后要返回明确错误类型，供 Agent 决定下一步。

降级策略也很重要。强模型不可用时可以切换备用模型；实时搜索失败时可以先使用已有知识库；图片上传失败时可以先创建草稿并标记待补图；非核心步骤失败时可以让主流程继续。

## 小结

部署 Agent 的关键，是把它当成可观测、可限流、可恢复的任务系统。模型能力决定上限，工程治理决定它能否稳定服务真实用户。真正可上线的 Agent，不仅要会思考，还要能在成本、并发、失败和权限边界内稳定运行。

## 实战案例：内容生成任务的成本控制

以批量生成 20 篇教程为例，如果每篇都使用强模型完整生成、再多轮自检，成本会快速上升。更合理的做法是先生成统一大纲，再分篇扩写；通用结构可以复用，具体内容再使用强模型补充。

工具调用也要控制成本。比如验证文章是否创建成功，可以读取必要字段，而不是拉取完整内容。这样既减少网络传输，也减少后续模型上下文消耗。

理解 AI Agent 上线后的部署形态、限流策略、并发控制、模型成本、缓存和降级方案。

AI Agent 实战教程 19：部署、限流与成本优化

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 走向可靠系统。一个 Agent 偶尔完成任务并不代表它稳定；真正重要的是在大量类似任务中，它是否持续选对工具、遵守权限、正确处理错误并给出可信结果。

Agent 评测比普通文本评测复杂，因为它不仅要看最终输出，还要看执行过程。

## 评测维度

第一个维度是任务成功率。给定目标，Agent 是否完成了用户真正想要的结果。

第二个维度是工具调用准确率。它是否选择了正确工具，参数是否正确，调用顺序是否合理。

第三个维度是权限遵守。高风险操作是否确认，未授权时是否停止或发起授权。

第四个维度是事实可靠性。回答是否基于工具结果和检索内容，是否编造不存在的信息。

第五个维度是用户体验。错误提示是否可理解，是否给出下一步建议。

## 单步工具评测

单步评测用于检查工具选择。例如用户说“查一下标签是否存在”，期望调用 tag list，而不是 tag create。

这类评测可以自动化，检查工具名、参数和返回处理是否符合预期。

## 多步任务评测

多步任务更接近真实场景。例如创建教程，需要创建文章、创建 tutorial、绑定文章、验证结果。评测时不能只看最终回答，而要检查每一步是否执行正确。

可以为每个步骤设置断言，例如是否创建了资源、是否保留原标签、是否没有重复创建。

## 权限评测

权限评测非常关键。测试用例应覆盖删除、发布、批量修改、外部发送等高风险操作。

期望行为不是“完成操作”，而是“触发确认”。如果 Agent 直接执行，哪怕结果正确，也是失败。

## 回归测试

每次修改 prompt、工具描述、模型版本或工作流，都可能影响旧能力。回归测试可以用固定任务集检测退化。

指标可以包括成功率、平均步骤数、工具误用率、确认触发率和平均耗时。

## 人工评审

文章质量、方案合理性、解释清晰度等指标很难完全自动化。可以结合人工评审，让评审者按结构、准确性、实用性打分。

## 小结

可靠 Agent 不是一次表现好，而是在可重复评测中稳定符合预期。评测体系应覆盖结果、过程、权限、错误恢复和用户体验。

## 实战案例：评测内容创建 Agent

如果 Agent 负责在 Treasure 中创建文章和 tutorial，评测不能只看最终是否说“创建成功”。应该检查线上是否真的存在文章、文章是否绑定正确标签、正文是否没有一级标题、内容长度是否符合要求、tutorial 是否包含正确文章顺序。

这些都可以写成自动断言。例如读取 article 内容，检查 content 不以“# ”开头；读取 tutorial，检查 articleCount 是否等于目标数量；检查每篇 tagCount 是否不超过 3。

当 Agent 或 CLI 逻辑变更时，跑一次这些评测，就能及时发现回归问题。评测越贴近真实业务，越能提升 Agent 的可靠性。

## 评测数据集建设

评测不是一次性工作，需要持续积累数据集。每次线上 Agent 出错，都可以沉淀成一个测试用例：用户输入是什么，期望工具是什么，哪些操作必须确认，最终状态应该如何。

随着用例增加，评测集会覆盖越来越多真实边界情况。它不仅能测试模型，也能测试工具 schema、权限规则、CLI 行为和后端接口兼容性。好的评测集，本质上是 Agent 系统的安全网。

## 线上反馈如何进入评测

评测集不应该只由开发者拍脑袋设计。真实用户反馈、失败任务、人工纠正记录，都应该定期转化为测试样例。比如用户指出文章内容太短、标题重复、标签数量超限，这些都可以变成自动检查项。

这样 Agent 每次迭代都会吸收真实问题。评测不只是质量检查，也是产品持续改进机制。

建立 Agent 评测体系，覆盖工具调用准确率、多步任务成功率、幻觉率、权限遵守和回归测试。

AI Agent 实战教程 17：如何评测一个 Agent 是否可靠

Agentic RAG 是把 RAG 从固定问答流程升级为 Agent 可决策的知识获取能力。传统 RAG 通常每次问题都检索一次；Agentic RAG 则让 Agent 判断是否需要检索、检索哪个知识源、是否需要二次检索，以及如何处理检索不足。

这种方式更适合真实任务，因为用户问题不总是简单问答。有些问题需要外部知识，有些只需要模型推理，有些需要多个知识源组合。

## 基础 RAG 回顾

基础 RAG 包括文档切分、Embedding、向量入库、查询向量化、相似度检索和答案生成。

它解决了模型知识过期、无法访问私有文档的问题。但固定 RAG 也有局限：检索策略单一，无法根据任务动态调整，也不擅长处理多知识源问题。

## Agentic RAG 的核心

Agentic RAG 把检索封装成工具。Agent 可以在需要时调用，比如 search_docs、search_codebase、search_meeting_notes。

如果第一次检索结果不足，Agent 可以改写 query，扩大范围，或询问用户更多信息。它也可以决定不检索，直接回答通用概念。

## 文档切分

切分策略影响检索质量。过大的 chunk 包含太多噪音，过小的 chunk 丢失上下文。较好的做法是按标题、段落、语义边界切分，并保留 metadata。

metadata 可以包括文档标题、路径、更新时间、权限、业务模块。这些字段能帮助过滤和引用。

## 检索工具返回

检索工具不应只返回纯文本。更好的返回结构包括：内容片段、来源、标题、相似度、更新时间、权限信息。

这样模型可以判断资料可信度，也能在回答中引用来源。

## Rerank 与多轮检索

向量检索返回的结果未必最适合生成答案。可以加入 rerank 模型重新排序，也可以结合关键词搜索和规则过滤。

Agent 还可以根据初次结果判断是否需要二次检索。例如发现资料都是旧版本，就按更新时间重新过滤。

## 权限与引用

企业 RAG 必须遵守权限。用户不能访问的文档，不应该进入检索结果。回答中也要避免泄露来源之外的信息。

对于关键回答，最好让模型给出引用，区分“资料明确说明”和“模型推断”。

## 小结

Agentic RAG 的价值在于把检索变成一种可决策能力。它不仅检索知识，还能判断何时检索、如何检索、结果是否足够，以及如何安全地使用结果。

## 实战案例：文档助手中的 Agentic RAG

假设用户问“这个接口为什么创建文章失败”。普通 RAG 可能只检索接口文档，然后生成答案。Agentic RAG 会更进一步：先检索文档，再查看错误日志，再查询相关代码，最后结合接口约定判断问题可能来自 draftId 缺失。

这个过程需要多个检索工具协作。文档检索回答“接口应该怎么用”，代码检索回答“实际实现是什么”，日志检索回答“线上发生了什么”。Agent 根据每一步结果决定是否继续检索。

因此，Agentic RAG 的重点不是一次检索，而是围绕任务动态获取证据。它更像研究助手，而不是固定问答机器人。

## Query 改写与检索计划

Agentic RAG 中，用户原始问题不一定适合直接检索。Agent 可以先把问题改写成多个查询。例如“文章创建为什么失败”可以拆成“/admin/article draftId 参数”“Duplicate entry REL 唯一键”“article create 后端实现”。

多个查询可以覆盖不同证据来源。Agent 再把检索结果合并，判断哪些信息一致、哪些互相冲突。相比单次向量检索，这种检索计划更适合排障、研究和复杂问答。

从文档切分、Embedding、检索工具、rerank、引用约束和 Agent 决策角度构建 Agentic RAG。

AI Agent 实战教程 16：构建 Agent 驱动的 RAG 问答系统

Memory 系统让 Agent 能够长期协作，但它也是最容易失控的模块之一。没有记忆，Agent 每次都像新手；记忆太多，Agent 会被噪音干扰，甚至带来隐私风险。

构建可控 Memory 系统的关键，是明确什么该记、什么时候记、如何检索、如何更新、如何删除。

## 记忆类型

Agent 的记忆可以分为几类。

任务记忆保存当前任务状态，例如已完成步骤、资源 ID、错误原因。

偏好记忆保存用户长期偏好，例如文章不要一级标题、每篇标签不超过 3 个。

知识记忆保存项目背景，例如某个系统的 API 约定、业务规则、部署方式。

经验记忆保存执行过程中发现的问题，例如某个 CLI 创建文章必须先创建 draftId。

不同记忆类型不应该混在一起，因为它们的生命周期和使用场景不同。

## 写入策略

Memory 不应该自动保存所有内容。写入条件可以包括：用户明确要求、偏好重复出现、任务结束后生成摘要、关键经验经过确认。

对于敏感信息，例如 token、密码、个人信息，默认不进入长期记忆。确实需要保存时，也要脱敏、加密、设置过期时间。

## 读取策略

读取记忆时要根据当前任务检索相关内容。写文章时读取内容风格偏好，操作系统时读取工具使用经验，排障时读取历史错误记录。

向量检索适合从大量记忆中找相似内容，但结果仍需要过滤。不是所有相似记忆都应该进入上下文。

## 记忆压缩

长期任务会产生很多细节。保存完整对话通常不划算，更好的方式是保存摘要和决策。

例如一次排障可以压缩成：“treasure article create 需要先创建 draftId，否则后端会报错。”这条经验比保存整段对话更有用。

## 用户控制

可控 Memory 必须让用户可查看、可修改、可删除。用户说“忘掉这个偏好”时，系统必须真正删除，而不是后续继续使用。

这不仅是体验问题，也是隐私和合规问题。

## 小结

Memory 的目标不是无限记忆，而是保留对未来任务有价值的信息。好的 Memory 系统应该分类清晰、写入克制、检索精准、可被用户控制。

## 实战案例：保存用户内容偏好

在内容管理 Agent 中，用户可能反复提出偏好：正文不要一级标题、教程内容控制在 1500 到 2000 字符、每篇文章最多 3 个标签、搜索图片必须上传到自有素材系统。

这些信息如果只存在当前对话中，下一次任务就可能丢失。可以把它们写入偏好记忆，并标注适用范围：内容创作、Treasure 平台、教程文章。后续创建文章时，Agent 先检索这些偏好，再生成内容和执行命令。

但偏好记忆也要允许覆盖。用户这次要求 1500 到 2000 字符，并不代表所有内容都必须如此。因此记忆最好带有来源、时间和作用域，而不是变成全局不可变规则。

## 记忆更新与冲突处理

记忆不是只新增不修改。用户偏好可能变化，项目规则也可能更新。比如最初要求文章 1500 到 2000 字符，后续可能要求更短的摘要版。Memory 系统需要能识别新旧规则冲突，并优先使用最近、作用域更精确、用户明确确认过的规则。

一种可行做法是为每条记忆保存 metadata，包括来源对话、创建时间、适用范围、置信度和是否用户确认。检索到多条冲突记忆时，Agent 不应该随意选择，而应按规则排序，必要时向用户澄清。

## 删除与遗忘机制

可控 Memory 还需要“遗忘”能力。用户可能要求删除某条偏好，也可能要求清理某个项目的历史上下文。系统应支持按用户、项目、记忆类型和时间范围删除。删除后，Agent 不应继续在后续任务中使用这条记忆。

对于企业系统，遗忘机制还涉及合规要求。比如用户离职、项目归档、敏感数据过期，都可能要求清理相关长期记忆。因此 Memory 系统最好从一开始就把删除和审计纳入设计。

从记忆写入、检索、压缩、过期、用户可见性和隐私删除角度，构建可控的 Agent Memory 系统。

AI Agent 实战教程 15：构建可控的 Memory 系统

权限、审批和 Human-in-the-loop 是 Agent 进入真实系统的前提。一个只能回答问题的模型，最多给出错误建议；一个能删除数据、发布内容、修改配置、发送消息的 Agent，如果没有审批机制，就可能造成真实损失。

因此，Agent 的安全设计不是上线前补一个提示词，而是要贯穿工具、工作流和执行环境。

## 授权和审批的区别

授权解决的是“Agent 有没有权限访问某个系统”。例如通过 OAuth 授权访问任务、日历、文档或代码仓库。

审批解决的是“这一次具体操作是否允许执行”。即使 Agent 已经有写入权限，也不代表每次写操作都可以自动执行。

例如 Agent 拥有任务写权限，可以创建待办。但如果它要批量删除任务，仍然需要用户确认。

## 风险分级

可以把工具分成几个风险等级。

低风险操作通常是读取和查询，例如查看标签、读取文章、搜索资料。

中风险操作会创建或修改资源，例如创建草稿、上传素材、更新文章内容。

高风险操作可能造成不可逆影响，例如删除数据、发布内容、修改权限、部署生产服务、发送外部消息。

不同风险等级对应不同执行策略：低风险可自动执行，中风险视上下文确认，高风险必须确认。

## 操作预览

审批前应该展示操作预览，而不是只问“是否继续”。预览应包括：

- 操作类型；
- 目标资源；
- 关键参数；
- 影响范围；
- 是否可回滚；
- 执行后如何验证。

例如发布文章前，应该展示标题、short、标签、状态变化；删除资源前，应该展示 ID、名称和不可恢复风险。

## 确认的粒度

确认粒度不能太粗。用户说“帮我整理这些文章”，不等于同意删除文章。用户说“创建一个教程”，可以创建资源，但如果需要覆盖已有 tutorial，就应该再次确认。

确认应该绑定具体操作和参数，避免确认 A 操作后执行 B 操作。

## 审批记录

审批必须可审计。系统应记录用户看到的预览、确认时间、确认人、执行参数和执行结果。

当 Agent 行为有争议时，审计记录可以说明系统是否按用户确认执行。

## 沙箱与审批配合

沙箱限制 Agent 能访问什么，审批限制 Agent 能执行什么。两者配合才能形成完整边界。

例如文件系统沙箱限制 Agent 只能写工作区；审批机制要求删除文件前确认。即使模型误判，也无法越权执行。

## 小结

Human-in-the-loop 不是反自动化，而是让自动化可控。真正可靠的 Agent 应该自动处理低风险任务，在高风险节点停下来，把决定权交还给用户。

## 实战案例：发布内容前的审批

以内容发布 Agent 为例，创建草稿可以自动执行，但发布到线上应该进入确认流程。确认信息不能只写“是否发布”，而应该展示文章标题、short、标签、封面、摘要，以及发布后用户会看到的入口。

如果用户确认，系统再执行发布操作；如果用户拒绝，任务进入 cancelled 或 waiting_revision 状态。这个过程还应该写入审计日志，记录用户确认的具体版本，避免后续内容被悄悄修改后仍复用旧确认。

审批机制还可以支持 dry-run。Agent 先生成将要执行的请求和影响范围，让用户预览。用户确认后，再使用同一份参数执行真实写入。这样可以降低误操作风险。

## 审批体验设计

审批流程还要关注用户体验。频繁弹出确认会让用户疲劳，完全不确认又不安全。实践中可以把确认做成分层机制：低风险自动执行，中风险展示简短确认，高风险展示详细预览。

对于重复性操作，可以支持“本次任务内信任”。例如用户确认批量创建 8 篇文章后，Agent 可以在这个任务范围内继续创建，但不能把这个授权扩展到删除或发布操作。审批的作用域越清晰，系统越安全。

设计 Agent 的风险分级、审批流程、操作预览与人工确认机制，让 Agent 在真实系统中安全执行。

AI Agent 实战教程 14：权限、审批与 Human-in-the-loop

长任务 Agent 最怕两件事：执行到一半失败，以及失败后不知道从哪里恢复。状态机、断点续跑和任务恢复，就是为了解决这个问题。

很多 Agent Demo 只有一次模型调用，不需要复杂状态。但真实任务往往包含多个步骤：查询数据、等待授权、创建资源、上传文件、绑定关系、验证结果。任何一步都可能失败。如果系统没有状态，Agent 只能从头再来，甚至重复执行已经完成的写操作。

## 为什么需要状态机

状态机把任务执行过程拆成明确阶段。每个阶段代表当前任务处于什么状态，以及下一步允许去哪里。

常见状态包括：

- pending：任务已创建但未开始；
- running：任务正在执行；
- waiting_approval：等待用户确认；
- waiting_auth：等待授权；
- retrying：正在重试；
- failed：执行失败；
- completed：任务完成；
- cancelled：用户取消。

这些状态不是为了形式化，而是为了让系统在中断、失败、等待用户时保持可恢复。

## 步骤级状态

除了任务状态，还需要步骤状态。比如创建一个教程模块，可能包含：

1. 检查标签是否存在；
2. 创建缺失标签；
3. 上传标签图片；
4. 创建文章；
5. 创建 tutorial；
6. 绑定文章；
7. 验证结果。

每一步都应该记录输入、输出、状态、错误、开始时间、结束时间。这样第 4 步失败时，系统可以知道前 3 步已经完成，不需要重复执行。

## 断点续跑

断点续跑的核心是“执行前先检查”。例如创建文章前，根据 short 查询是否已存在；上传图片前，判断 URL 是否已经是自有素材；绑定 tutorial 前，查询当前已绑定文章。

这样即使脚本中断，重新执行时也能跳过已完成部分。

## 等待用户

Agent 经常需要等待用户授权或确认。比如缺少某个 API scope，需要用户打开授权链接；删除数据前，需要用户确认。

等待期间任务状态应进入 waiting_auth 或 waiting_approval，并保存当前步骤和上下文。用户回来后，系统继续执行，而不是重新发起整个任务。

## 错误分类

错误恢复要基于错误类型。网络错误可以重试；参数错误需要修正；权限错误需要授权；资源冲突需要合并；高风险操作需要确认。

不要对所有错误都简单重试，也不要所有错误都直接失败。分类越清楚，恢复策略越稳定。

## 防止重复执行

重复执行是 Agent 长任务中的高频问题。解决方式包括唯一 key、查重、幂等接口、操作日志和步骤状态。

例如创建资源时使用 short 作为唯一标识；绑定关系时先读取现有关联；更新内容时保留原 ID。这些都能降低重复执行风险。

## 小结

状态机让 Agent 从一次性对话变成可恢复任务系统。只要任务包含多个步骤、用户确认、外部工具或写操作，就应该考虑状态、断点续跑和错误恢复。

## 实战案例：创建内容教程的断点续跑

假设 Agent 要创建一套 18 篇文章的教程。这个任务很容易中断：前几篇文章可能创建成功，后几篇失败；tutorial 可能创建成功，但文章绑定失败；图片可能上传成功，但更新标签失败。

如果没有状态机，重跑任务时 Agent 可能重复创建文章，或者覆盖已经绑定好的顺序。更稳的方式是为每个步骤记录状态：文章创建步骤记录 short 和 articleId，tutorial 创建步骤记录 tutorialId，绑定步骤记录当前 sortIds。重试时先读取线上状态，再决定跳过、更新还是继续执行。

这种设计看起来麻烦，但它能把“失败后人工排查”变成“失败后自动恢复”。对于任何包含写操作的 Agent，断点续跑都应该尽早纳入设计。

理解长任务 Agent 为什么需要状态机，如何设计 pending、running、waiting、failed、completed 等状态并支持恢复。