docs: 添加 ag-ui 和 crewai 项目 skills 及更新文档

2026-03-02 17:02:09 +08:00
parent 6fdbc34526
commit ca1ce3d84a
43 changed files with 56074 additions and 3 deletions
@@ -0,0 +1,16 @@
+# Agents
+
+**作用**: 介绍 AG-UI 中 Agent 的概念、架构、类型和实现方式。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 35-451
+
+**内容索引**:
+- 什么是 Agent (行 47-62)
+- Agent Architecture - AbstractAgent, 核心组件 (行 63-91)
+- Agent Types - HttpAgent, Custom Agents (行 93-130)
+- Implementing Agents - 基本实现示例 (行 132-197)
+- Agent Capabilities - 交互通信、工具使用、状态管理、多 Agent 协作、人机协作、对话记忆 (行 199-358)
+- 使用 Agent (行 360-399)
+- Agent Configuration (行 401-424)
+- Agent State Management (行 426-439)
@@ -0,0 +1,17 @@
+# Core Architecture
+
+**作用**: 介绍 AG-UI 的核心架构、设计原则和运行机制。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 453-679
+
+**内容索引**:
+- Design Principles - 事件驱动、双向交互、灵活中间件 (行 463-489)
+- Architectural Overview - 客户端-服务器架构 (行 491-534)
+- Protocol layer - run(input) -> Observable<BaseEvent> (行 537-567)
+- Standard HTTP client - HttpAgent, SSE/HTTP binary (行 569-585)
+- Message types - Lifecycle, Text, Tool, State, Special 事件 (行 587-609)
+- Running Agents (行 611-640)
+- State Management - STATE_SNAPSHOT, STATE_DELTA (行 642-652)
+- Tools and Handoff (行 653-662)
+- Base Event 属性 (行 664-677)
@@ -0,0 +1,15 @@
+# Contributing & Roadmap
+
+**作用**: 贡献指南、路线图和更新日志。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 3443-3485
+
+**内容索引**:
+- Contributing (行 3443-3460):
+  - Naming conventions - integrations/, wip-, community- 前缀 (行 3448-3459)
+- Roadmap (行 3462-3481):
+  - 公开路线图链接 (行 3467-3468)
+  - Get Involved - 贡献方式 (行 3470-3474)
+- What's New (行 3477-3485):
+  - 2025-04-09: AG-UI 仓库公开发布 (行 3482-3484)
@@ -0,0 +1,53 @@
+# Drafts
+
+**作用**: 介绍 AG-UI 协议中正在考虑或开发中的提案功能。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 3492-3854 (Generative UI), 3860-4105 (Interrupts), 4111-4349 (Meta Events), 4355-4846 (Multimodal)
+
+**Drafts 概述** (行 4847-4887):
+- Drafts 状态定义 - Draft/Under Review/Accepted/Implemented/Withdrawn (行 4880-4886)
+
+**Generative User Interfaces** (行 3492-3854):
+  - Summary - 问题陈述与动机 (行 3494-3508)
+  - Challenges and Limitations - 工具描述长度、JSON Schema 约束 (行 3515-3531)
+  - Detailed Specification:
+    - Two-Step Generation Process - 两步生成流程图 (行 3535-3543)
+    - Step 1: What to Generate? - generateUserInterface 工具 (行 3545-3596)
+    - Step 2: How to Generate? - 次级 LLM 生成实际 UI (行 3598-3612)
+  - Implementation Examples:
+    - UISchemaGenerator - JSON Schema 输出 (行 3615-3673)
+    - ReactFormHookGenerator - React Hook Form 代码生成 (行 3675-3795)
+  - Implementation Considerations - SDK 变更 (行 3797-3819)
+  - Use Cases - 动态表单、数据可视化、交互式工作流 (行 3821-3838)
+
+**Interrupt-Aware Run Lifecycle** (行 3860-4105):
+  - Summary - 人机协作暂停机制 (行 3862-3875)
+  - Updates to RUN_FINISHED Event - outcome, interrupt 字段 (行 3897-3920)
+  - Updates to RunAgentInput - resume 字段 (行 3922-3937)
+  - Contract Rules (行 3939-3945)
+  - Implementation Examples (行 3947-4026)
+  - Use Cases - 人类批准、信息收集、策略强制 (行 4028-4051)
+  - Implementation Considerations (行 4052-4091)
+
+**Meta Events** (行 4111-4349):
+  - Summary - 独立于 Agent 运行的事件注解 (行 4115-4127)
+  - MetaEvent Type - metaType, payload (行 4145-4170)
+  - Implementation Examples:
+    - User Feedback - thumbs_up, thumbs_down (行 4174-4206)
+    - Annotations - note, tag (行 4208-4239)
+    - External System Events - analytics, moderation (行 4241-4276)
+  - Common Meta Event Types 表 (行 4278-4292)
+  - Use Cases (行 4294-4318)
+
+**Multimodal Messages** (行 4355-4846):
+  - Summary - 支持多模态输入消息 (行 4357-4371)
+  - Status: Implemented (行 4373-4376)
+  - Detailed Specification:
+    - Modality Types 表 - text, image, audio, video, document (行 4473-4483)
+    - Source Types - InputContentDataSource, InputContentUrlSource (行 4485-4509)
+    - Content Part Types - TextInputPart, ImageInputPart, AudioInputPart, VideoInputPart, DocumentInputPart (行 4511-4561)
+    - Provider Metadata (行 4562-4571)
+  - Implementation Examples (行 4573-4764)
+  - Implementation Considerations (行 4766-4798)
+  - Use Cases (行 4800-4827)
@@ -0,0 +1,20 @@
+# Events
+
+**作用**: 详细介绍 AG-UI 协议中的所有事件类型，包括生命周期、文本、工具调用、状态管理、推理等事件。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 680-1475
+
+**内容索引**:
+- Event Types Overview - 事件分类表 (行 692-703)
+- Base Event Properties (行 705-713)
+- Lifecycle Events - RunStarted, RunFinished, RunError, StepStarted, StepFinished (行 715-754)
+- Text Message Events - TextMessageStart, TextMessageContent, TextMessageEnd, TextMessageChunk (行 835-937)
+- Tool Call Events - ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult, ToolCallChunk (行 938-1066)
+- State Management Events - StateSnapshot, StateDelta, MessagesSnapshot (行 1067-1155)
+- Activity Events - ActivitySnapshot, ActivityDelta (行 1156-1189)
+- Special Events - Raw, Custom (行 1191-1233)
+- Reasoning Events - ReasoningStart, ReasoningMessageStart/Content/End/Chunk, ReasoningEnd, ReasoningEncryptedValue (行 1234-1368)
+- Deprecated Events - THINKING_* 事件迁移 (行 1369-1389)
+- Draft Events - Meta Events, Modified Lifecycle Events (行 1391-1446)
+- Event Flow Patterns - Start-Content-End, Snapshot-Delta, Lifecycle (行 1447-1474)
@@ -0,0 +1,11 @@
+# Generative UI Specs
+
+**作用**: 介绍 AG-UI 与生成式 UI 规范的关系（A2UI、MCP-UI、Open-JSON-UI）。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 1476-1496
+
+**内容索引**:
+- AG-UI and Generative UI Specs - AG-UI 不是生成式 UI 规范，而是用户交互协议 (行 1476-1496)
+- AG-UI 与 A2UI、MCP-UI、Open-JSON-UI 的关系说明
+- Generative UI 实现详情见 [drafts](drafts.md) 的 Generative User Interfaces 章节 (行 3492-3854)
@@ -0,0 +1,21 @@
+# Messages
+
+**作用**: 介绍 AG-UI 中消息的结构、类型和同步机制。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 1498-1952
+
+**内容索引**:
+- Message Structure - BaseMessage 接口, role, encryptedContent (行 1510-1537)
+- Message Types:
+  - UserMessage - 用户消息, 支持多模态 InputContent (行 1543-1576)
+  - AssistantMessage - 助手消息, 含 toolCalls (行 1578-1591)
+  - SystemMessage - 系统消息 (行 1593-1604)
+  - ToolMessage - 工具结果消息 (行 1606-1627)
+  - ActivityMessage - 前端专用活动消息 (行 1628-1653)
+  - DeveloperMessage - 开发/调试消息 (行 1654-1665)
+  - ReasoningMessage - 推理消息 (行 1667-1704)
+- Vendor Neutrality - 供应商中立性, 格式转换示例 (行 1705-1735)
+- Message Synchronization - MESSAGES_SNAPSHOT, 流式消息 (行 1736-1794)
+- Tool Integration - ToolCall, ToolResult 结构 (行 1795-1889)
+- Practical Example - 完整对话示例 (行 1891-1939)
@@ -0,0 +1,18 @@
+# Middleware
+
+**作用**: 介绍 AG-UI 中间件，用于转换、过滤和增强事件流。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 1954-2158
+
+**内容索引**:
+- What is Middleware? - 中间件的作用 (行 1965-1973)
+- How Middleware Works - 中间件链式调用 (行 1975-1991)
+- Function-Based Middleware - 函数式中间件示例 (行 1993-2019)
+- Class-Based Middleware - 类中间件示例 (行 2021-2055)
+- Built-in Middleware - FilterToolCallsMiddleware (行 2062-2086)
+- Middleware Patterns - 日志、认证、限流 (行 2088-2090)
+- Combining Middleware (行 2092-2103)
+- Execution Order - 中间件执行顺序 (行 2104-2124)
+- Best Practices (行 2126-2134)
+- Conditional Middleware (行 2136-2153)
@@ -0,0 +1,28 @@
+# AG-UI Overview
+
+**作用**: AG-UI 协议总体介绍，包括协议定位、核心特性、与其他协议的关系、以及构建块概览。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 4894-5261
+
+**内容索引**:
+- 协议定义 - 开放、轻量、事件驱动的 Agent-User 交互协议 (行 4894-4901)
+- Agentic Protocols - MCP/A2A/AG-UI 三层协议栈 (行 4910-4923)
+- Building Blocks (行 4926-5088):
+  - Streaming chat - 流式对话 (行 4930-4941)
+  - Tool calling - 工具调用 (行 4943-4953)
+  - Structured state - 结构化状态 (行 4955-4965)
+  - Generative UI - 生成式 UI (行 4967-4977)
+  - Contextual context - 上下文管理 (行 4979-4989)
+  - Client-side tools - 客户端工具 (行 4991-5001)
+  - Auth & multi-tenancy - 认证与多租户 (行 5003-5013)
+  - Debugging & evals - 调试与评估 (行 5015-5025)
+  - Upcoming: Reasoning continuity - 推理连续性 (行 5027-5037)
+  - Upcoming: Multi-modal - 多模态 (行 5039-5049)
+  - Upcoming: Generative UI - 生成式 UI (行 5051-5061)
+  - Upcoming: Interrupts & approval flows - 中断与审批流程 (行 5063-5073)
+  - Upcoming: Meta events - 元事件 (行 5075-5085)
+- Protocol Basics (行 5090-5261):
+  - Agent Definition - Agent 定义 (行 5095-5109)
+  - Event Stream - 事件流 (行 5111-5129)
+  - Common Patterns - 常见模式 (行 5131-5151)
@@ -0,0 +1,11 @@
+# Protocol
+
+**作用**: 介绍 AG-UI 与 MCP、A2A 协议的关系，以及 AG-UI 作为连接 Agent 与用户应用的协议定位。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 1-33
+
+**内容索引**:
+- Agentic Protocols 概述 (MCP, A2A, AG-UI)
+- AG-UI 与 MCP、A2A 的握手
+- Generative UI Specs 介绍
@@ -0,0 +1,26 @@
+# Reasoning
+
+**作用**: 介绍 AG-UI 对 LLM 推理的支持，包括链式思维可视化和加密推理内容。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 2160-2638
+
+**内容索引**:
+- Overview - 推理可见性、状态连续性、隐私合规 (行 2171-2188)
+- ReasoningMessage - 推理消息结构 (行 2190-2217)
+- Reasoning Events:
+  - Event Flow - 推理事件流程图 (行 2223-2246)
+  - Event Types 表 (行 2248-2258)
+- Privacy and Compliance:
+  - Zero Data Retention (ZDR) - 零数据保留 (行 2264-2273)
+  - Visibility Control - 可见性控制 (行 2274-2284)
+  - Compliance Considerations 表 - GDPR, SOC 2, HIPAA (行 2285-2293)
+- Example Implementations:
+  - Basic Reasoning Flow (行 2296-2348)
+  - Encrypted Content for State Continuity (行 2350-2396)
+  - Attaching Encrypted Reasoning to Tool Calls (行 2398-2430)
+  - ZDR-Compliant Implementation (行 2432-2475)
+  - Using Convenience Chunk Event (行 2477-2503)
+- Client Integration - 处理推理事件, 传递加密推理 (行 2505-2563)
+- Migration from Thinking Events - THINKING_* 迁移到 REASONING_* (行 2565-2617)
+- Best Practices (行 2619-2632)
@@ -0,0 +1,21 @@
+# Serialization
+
+**作用**: 介绍 AG-UI 事件流的序列化，用于历史恢复、分支和时间旅行。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 2640-2827
+
+**内容索引**:
+- Core Concepts:
+  - Stream serialization - 事件流转为 JSON (行 2660-2662)
+  - Event compaction - 压缩事件流 (行 2662-2663)
+  - Run lineage - parentRunId 实现 git 类日志 (行 2664-2665)
+- Updated Event Fields - RunStarted 新增 parentRunId, input (行 2667-2685)
+- Event Compaction - compactEvents 函数, 压缩规则 (行 2686-2704)
+- Branching and Time Travel - parentRunId 创建分支, git 类日志 (行 2705-2729)
+- Examples:
+  - Basic Serialization (行 2732-2744)
+  - Event Compaction - 压缩前后示例 (行 2746-2774)
+  - Branching With parentRunId (行 2776-2795)
+  - Normalized Input (行 2797-2814)
+- Implementation Notes (行 2816-2822)
@@ -0,0 +1,18 @@
+# State Management
+
+**作用**: 介绍 AG-UI 中 Agent 与前端之间的状态同步机制。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 2829-3080
+
+**内容索引**:
+- Shared State Architecture - 共享状态架构, 双向通信 (行 2842-2857)
+- State Synchronization Methods:
+  - State Snapshots - STATE_SNAPSHOT 事件 (行 2862-2882)
+  - State Deltas - STATE_DELTA 事件, JSON Patch (行 2884-2902)
+- JSON Patch Format:
+  - RFC 6902 操作: add, replace, remove, move, copy, test (行 2903-2944)
+- State Processing in AG-ui - fast-json-patch 使用示例 (行 2946-2977)
+- Human-in-the-Loop Collaboration - 人机协作示例 (行 2978-3005)
+- CopilotKit Implementation - useCoAgent, copilotkit_emit_state (行 3007-3050)
+- Best Practices (行 3052-3068)
@@ -0,0 +1,24 @@
+# Tools
+
+**作用**: 介绍 AG-UI 中工具的定义、使用和人在环工作流。
+
+**源文件**: `llms-full.txt`
+**行号范围**: 3082-3441
+
+**内容索引**:
+- What Are Tools? - 工具的作用 (行 3095-3105)
+- Tool Structure - Tool 接口定义 (行 3107-3130)
+- Frontend-Defined Tools - 工具由前端定义并传递给 Agent (行 3132-3175)
+- Tool Call Lifecycle:
+  - ToolCallStart (行 3179-3191)
+  - ToolCallArgs - 流式参数 (行 3193-3217)
+  - ToolCallEnd (行 3219-3229)
+- Tool Results - ToolMessage 结构 (行 3231-3246)
+- Human-in-the-Loop Workflows - 人机协作工作流 (行 3248-3270)
+- CopilotKit Integration - useCopilotAction hook (行 3272-3304)
+- Tool Examples:
+  - User Confirmation (行 3310-3332)
+  - Data Retrieval (行 3334-3358)
+  - User Interface Control (行 3360-3381)
+  - Content Generation (行 3383-3412)
+- Best Practices (行 3414-3428)