learnNote

主题

📚 LearnNote - AI Agent 技术学习笔记 ​

这是一个关于 AI Agent 开发、协议规范和框架实现的学习笔记仓库，涵盖了 tRPC-Agent 框架深入学习、AI 协议对比分析以及实战开发经验。

🌐 在线浏览 ​

整个仓库已经做成 VitePress 文档站，所有 *.md 笔记、demo.html 可视化演示、code/ 示例代码都自动整合到一个站点里，支持全文搜索、深色模式、Mermaid 流程图与彩虹配色。

bash
npm install         # 首次准备
npm run dev         # 本地开发：http://localhost:5173
npm run build       # 生产构建：产物在 .vitepress/dist/

详细的技术栈与实现说明见文末 🛠️ 站点工程：技术栈与实现。

🗂️ 目录结构 ​

learnNote/
├── ai/                          # AI 相关技术分析
│   └── openclaw.md              # OpenClaw 深度分析与竞品对比
├── trpc-agent/                  # tRPC-Agent 框架学习
│   ├── base/                    # 框架基础知识
│   ├── concept/                 # 核心概念与协议
│   └── work_record/             # 工作记录与问题解决
├── LICENSE
└── README.md

📖 内容概览 ​

🤖 AI 技术分析 ​

文档描述
OpenClaw 深度分析OpenClaw、Claude Code、Codex CLI 三大 AI 编程工具对比分析

🔧 tRPC-Agent 框架学习 ​

基础篇（Base） ​

文档描述推荐优先级
学习计划tRPC-Agent 完整学习路线图，6 阶段 20+ 天计划⭐⭐⭐⭐⭐
核心概念Agent、Runner、Session、Event 四大核心概念详解⭐⭐⭐⭐⭐
Agent 系统BaseAgent、LlmAgent、多 Agent 编排深度解析⭐⭐⭐⭐⭐
Runner 执行器Agent 执行编排器的实现原理⭐⭐⭐⭐
Model 模型系统LLM 模型抽象层设计⭐⭐⭐⭐
Tool 工具系统工具定义、注册和调用机制⭐⭐⭐⭐
Session 与 Memory会话持久化和记忆管理⭐⭐⭐
Filter 过滤器洋葱模型的 Filter 机制⭐⭐⭐
Context 上下文调用上下文设计⭐⭐⭐
Event 事件系统事件驱动的流式输出⭐⭐⭐⭐
数据处理数据处理流程⭐⭐⭐
代码执行器安全代码执行机制⭐⭐⭐
Planner 规划器Agent 规划能力实现⭐⭐⭐
Knowledge 知识库知识库集成方案⭐⭐⭐
Evaluator 评估器Agent 评估框架⭐⭐
生态系统外部系统集成⭐⭐
部署服务化部署方案⭐⭐
取消机制任务取消实现⭐⭐
调试Debug Server 使用⭐⭐
流式工具流式工具调用⭐⭐⭐⭐

概念篇（Concept） ​

文档描述核心要点
SSE 协议Server-Sent Events 基础单向流式通信
Streamable HTTP新一代 HTTP 流式传输MCP 推荐方案
MCP 协议Model Context Protocol 完全指南Agent↔工具连接
A2A 协议Agent2Agent Protocol 学习指南Agent↔Agent 协作
AG-UI 协议Agent-User Interaction 协议Agent↔用户交互
OpenAI APIOpenAI API 规范行业标准接口

工作记录（Work Record） ​

文档描述
流式工具调用实现完整的流式工具调用实现总结
设计文档索引为什么需要这些文件
聊天历史记录问题讨论与解决过程
设计文档流式工具调用设计规范
OpenAI 模型集成OpenAI 模型层实现

🌟 核心知识点 ​

AI Agent 协议三角 ​

┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent 协议生态                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│     MCP (Anthropic)          A2A (Google)                        │
│         │                        │                               │
│         │ Agent↔工具             │ Agent↔Agent                   │
│         │ 垂直连接               │ 水平连接                       │
│         │                        │                               │
│         └────────────┬───────────┘                               │
│                      │                                           │
│                      ▼                                           │
│               ┌─────────────┐                                    │
│               │   AG-UI     │                                    │
│               │ (CopilotKit) │                                    │
│               │ Agent↔用户  │                                    │
│               └─────────────┘                                    │
│                                                                  │
│  三者互补，不是竞争！                                              │
│  - MCP：让 Agent 能"使用工具"                                     │
│  - A2A：让 Agent 能"协作对话"                                     │
│  - AG-UI：让 Agent 能"与用户交互"                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

tRPC-Agent 核心架构 ​

┌─────────────────────────────────────────────────────────────────┐
│                         Runner                                   │
│  (Agent 执行编排器，管理会话、事件流、Agent 调度)                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Agent                                    │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐                │
│  │LlmAgent │ │ChainAgent│ │Parallel │ │TeamAgent│                │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘                │
└─────────────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│   Model     │ │   Tools     │ │   Memory    │
│  (LLM 调用)  │ │ (工具调用)   │ │ (会话记忆)  │
└─────────────┘ └─────────────┘ └─────────────┘

🚀 快速开始 ​

推荐学习路线 ​

  1. 入门阶段（2-3 天）

  2. 核心组件（5-7 天）

  3. 协议学习（4-5 天）

  4. 进阶实战（3-4 天）

📊 协议对比速查表 ​

维度MCPA2AAG-UI
发起方AnthropicGoogleCopilotKit
发布时间2024.112025.042025.02
核心定位Agent↔工具Agent↔AgentAgent↔用户
消息格式JSON-RPC 2.0JSON-RPC 2.0JSON 事件流
传输方式stdio/HTTP/SSEHTTPSSE/WebSocket
核心能力工具调用、资源访问任务委派、能力发现流式聊天、状态同步
开源协议MITApache 2.0MIT

📝 文档特点 ​

  • ✅ 系统化：按学习阶段组织，由浅入深
  • ✅ 实战性：包含大量代码示例和架构图
  • ✅ 可记忆：每篇文档包含速记清单和公式总结
  • ✅ 避坑指南：记录常见问题和解决方案
  • ✅ 持续更新：跟踪最新协议版本和框架更新

📅 更新记录 ​

日期更新内容
2026-02-26初始化项目，整理文档结构
2026-02-09完成 MCP、A2A、AG-UI 协议学习指南
2026-02-07完成 OpenClaw 深度分析
2026-02-06流式工具调用 Callback 修复
2026-02-03A2A/AG-UI 流式工具调用优化，增量 Delta 传输
2026-01-27完成 tRPC-Agent 学习计划和核心概念文档

🔗 相关资源 ​

官方文档 ​

学习资源 ​

🛠️ 站点工程：技术栈与实现 ​

把仓库里 20 个主题、~180 篇 markdown、73 章 demo 和上百个 code 文件，零侵入 地组装成一个可在线浏览的文档站。

设计目标 ​

#目标解释
1零侵入不改任何已有 md / html / code 源文件，所有增强通过站点配置完成
2零运维增删改章节后，只要重跑 npm run dev，侧边栏 / 首页 / demo 链接全部自动更新
3三种内容统一展示同一章节页里依次呈现：md 正文 → 可视化 demo（iframe）→ 示例代码（代码组 + 高亮）
4样式精致自定义主题、Web Font、Mermaid 彩虹配色、深浅色双模式、宽屏布局

技术栈 ​

类别选型理由
站点框架VitePress 1.6对 markdown 一等公民支持、Vite 驱动 HMR 极快、内置代码高亮 / 搜索 / 深色模式，部署只是一坨静态文件
渲染运行时Vue 3.5VitePress 的底层，主题层用 enhanceApp 注入即可
流程图mermaid 11 + vitepress-plugin-mermaid 2.x226 个 mermaid 代码块全部按需渲染成 SVG
Web 字体@fontsource/inter + @fontsource/jetbrains-mono本地打包，无 CDN 依赖；中文继续走系统字体（PingFang / Yahei）
自动化自研 prebuild.mjs (Node ESM)扫描目录、生成侧边栏 / 导航 / manifest，并镜像 demo / code 静态资源
内容增强自研 Vite 插件 augmentChapters在 md 进入构建管道时按 manifest 末尾追加 demo iframe + code 代码组，源文件保持原样

目录结构 ​

text
learnNote/
├── package.json                 # 依赖与 dev / build / preview 脚本
├── index.md                     # 自动生成的首页（hero + 主题卡片）
├── .gitignore                   # 排除 node_modules / dist / 镜像资源
├── .vitepress/
│   ├── config.mts               # 主配置：mermaid 主题、Vite 插件、nav、sidebar
│   ├── theme/
│   │   ├── index.ts             # 引入字体 + 自定义样式
│   │   └── style.css            # 调色板、布局、mermaid 容器
│   ├── scripts/
│   │   └── prebuild.mjs         # 扫描目录 → 生成 sidebar/nav/index/manifest
│   └── generated/               # ⬅ 由 prebuild 写入（不入库）
│       ├── sidebar.json
│       ├── nav.json
│       ├── index.json
│       └── manifest.json
└── public/_assets/<topic>/...   # ⬅ 由 prebuild 镜像（不入库）
                                 #   demo.html 与 code/* 的可访问副本

三层数据流 ​

text
源仓库（kafka/01_intro.md, kafka/01_intro/demo.html, kafka/01_intro/code/*.py）
        │
        │  ① npm run dev / build  →  prebuild.mjs 扫描
        ▼
generated/*.json + public/_assets/*  ← 侧边栏树、导航、首页卡片、章节增强清单、可访问的 demo / code
        │
        │  ② vitepress 启动，config.mts 读 json → 渲染 nav/sidebar
        │     Vite 插件 transform(*.md) → 按 manifest 末尾追加 demo iframe + code group
        ▼
浏览器静态站点（HMR 模式下任何源文件改动都即时刷新）

关键实现思路 ​

1. 自动侧边栏 / 导航 / 首页（prebuild.mjs） ​

  • 递归扫描 顶层 20 个主题目录，按 naturalSort 给章节排序（01_xxx、10_xxx 数值正确）
  • 侧边栏标题取自每篇 md 的 第一行 # 标题（找不到则美化文件名 01_intro → 01 · intro）
  • 顶部 nav 不再平铺 20 项，而是按 NAV_GROUPS 配置分成 4 个下拉：数据 & 存储 / AI / 工程 & 工具 / 项目实战，每条带篇数（如 Kafka · 28 篇），未归类的会落到自动生成的 "其他 ▾"
  • 首页用 VitePress layout: home，hero 区 + 20 张主题卡片（auto-managed，含哨兵注释 <!-- learn-note:auto-index --> 防止覆盖手改版本）

2. demo.html / code/ 的注入与可访问（augmentChapters Vite 插件 + 镜像） ​

  • prebuild 时构建一份 manifest.json，键是 md 相对路径，值是 { demo, codeFiles[] }
  • 同时把每个 <chapter>/demo.html 与 <chapter>/code/* 镜像到 public/_assets/<rel>，VitePress 会把 public/ 原样发布，因此可独立访问 /_assets/kafka/01_intro/demo.html
  • 自定义 Vite 插件 enforce: 'pre'，在 transform(md) 时对照 manifest，把这两段内容追加到 md 末尾：
    • ## 🎬 可视化演示 + <iframe src="/_assets/..."> + 新标签页打开链接
    • ## 💻 示例代码 + VitePress ::: code-group，逐文件读源码 + 自动选语言（按扩展名映射 26 种）
  • 因为是构建期内存改写，源 md 0 字节修改，新建/重命名/删除章节后只要重跑 prebuild 全部跟新

3. Mermaid 集成与主题（config.mts） ​

  • 用 withMermaid() 把 VitePress 配置包一层，所有 ```mermaid 代码块自动渲染
  • 主题选 base（最自由）+ 自定义 themeVariables：橙色品牌 + 蓝色辅色 + 黄/绿/紫衍生色
  • 彩虹效果 通过 themeCSS 注入 :nth-of-type(7n+k) 规则，节点按 7 色循环（红→橙→黄→绿→蓝→靛→粉），每色独立 fill/stroke/text
  • 解决"长文本被截断"：htmlLabels: true + useMaxWidth: false + 容器 overflow-x: auto，节点 <foreignObject><div> 自然撑高撑宽，超宽图横向滚动而不是被压缩
  • 深色模式：vitepress-plugin-mermaid@2.0.17 源码硬编码深色时强制 theme: 'dark'（不接受 darkTheme），所以方案是：浅色用精心配色 + 深色让插件接管 + mermaid 容器用 var(--vp-c-bg-soft) 自适应深浅底色

4. 字体 / 布局微调（theme/style.css） ​

  • @fontsource/inter + @fontsource/jetbrains-mono 本地打包，避免 Google Fonts 被墙
  • --vp-font-family-base 覆盖：英文走 Inter，中文 fallback 系统字体（苹方 / 雅黑 / Noto）
  • --vp-layout-max-width: 100vw + 解开 .container max-width，让侧边栏 / 大纲贴近屏幕两边
  • mermaid 容器加双角径向渐变（橙 + 蓝晕染）和大圆角，深浅模式皆雅观

已知决策与权衡 ​

取舍选择原因
是否在 md 里写 demo iframe❌ 不写，由插件注入保持源 md 干净、可在 GitHub 直接预览
是否把 demo.html 留在源目录✅ 保留，再镜像到 public旧链接、IDE 预览仍能用；同时 VitePress 也能发布
深色模式下 mermaid 用什么主题让插件强切到内置 dark插件 v2 不支持 darkTheme，硬绕只会更脆
是否处理代码 fence 错误语言（如 ```12:14:src/x.ts）暂不处理源 md 内容问题，shiki 会回退到纯文本，不影响渲染
节点是否自动 wrap❌，强制 nowrap 单行wrap + rect 高度计算 mermaid 算不准会截断；想换行请在源里写 <br/>

常用命令 ​

bash
npm run dev      # prebuild + 启动 Vite dev server (HMR)
npm run build    # prebuild + 全量构建 → .vitepress/dist/
npm run preview  # 预览构建产物

想新增 / 调整内容怎么做 ​

我想...做什么
新增一个主题（如 etcd/）直接在仓库根新建目录、放 md 进去，重跑 npm run dev 即可，会自动出现在侧边栏与首页
把新主题放进顶部某个下拉改 prebuild.mjs 顶部 NAV_GROUPS 数组对应分组的 topics 列表
给某章加 demo / code在该章 md 同级建 <basename>/ 目录，里面放 demo.html 和 code/*，prebuild 自动检测
换 Mermaid 配色改 config.mts 顶部 RAINBOW 数组（fill / stroke / text 三色），或改 themeVariables.lineColor 等
让某页 mermaid 用其它主题在该 md frontmatter 加 mermaidTheme: forest 即可单页覆盖
自定义首页删掉 index.md 里 <!-- learn-note:auto-index --> 行，prebuild 后续不再覆盖你的版本

📄 License ​

MIT License - 详见 LICENSE 文件

最后更新：2026-04-18

最后更新: