Putao's blog

claude code的层层拼装

Mon, 27 Jul 2026 00:00:00 GMT

一、agent到agent loop#

单独的调用llm只能处理一次任务；即使把一次llm的调用封装为agent，当我们通过agent来处理任务的时候，只能通过工作流编排的方式来实现我们的任务，但这样的方式自主性并不高，更多的是人在做规划，llm的能力在这种方式里相当于一次工具调用。

但llm也是有推理能力和规划能力的，很多任务也可以交由llm来推理，来更灵活的规划，从而可以做复杂任务。

我们可以通过while循环的方式来让大模型能一直自己运作，产生的新的结果塞进上下文，下一轮循环进行新的推理。while循环的终止条件为没有新的工具调用。没有新的工具调用代表当前内容足够进行回答，不需要新的额外的内容来完整推理。

终止循环的条件，除了判断是否还需要工具以外，生产中还需要考虑如下：

上下文超出限制
超过可接受的最大轮次
模型不可用等等

二、agent+工具#

llm可以输出文字、输出代码，但是无法直接和计算机进行交互。想要和计算机交互最简单的方式就是通过bash实现各种各样的操作，由llm输出操作命令，再由代码接管执行命令，输出的结果再作为新的补充内容回到loop里；

但是对于简单的读取文件、写入文件、读取时间等等一系列操作，如果每次都需要大模型通过bash来做会变得复杂，多了一层翻译、浪费token、容易出错；

对于经常使用的操作我们可以封装为工具，为工具添加描述，在llm调用之前，将工具清单提供给llm进行推理和规划；如果大模型需要调用，则加入tool_use，后续进行调用。

在各种agent系统里，各自业务里常用的操作都可以封装为tool。

三、agent+禁止规则#

但我们赋予agent操纵工具的权利，并且希望能自主帮我们干活；我们就需要考虑风险问题。如果把电脑的操作权利交给一个不可控的东西的时候，我们就要想办法避免这种危险（harness思想）

在大模型调用后、工具执行之前，加上N道闸门

N道闸门，从严格到宽松，llm的每一次操作都需要经过这N道闸门的审核才能放行：

闸门	作用	命中后
1. 拒绝列表	永远禁止的操作（`rm -rf /`、`sudo`）	直接拒绝，不执行
2. 规则匹配	取决于上下文的操作（写工作区外、`rm` 文件）	交给闸门 3
3. 用户审批	闸门 2 命中后，暂停等用户确认	用户决定允许或拒绝

生产中除了这几道闸门以外，还包括：zod mod调用工具的参数类型检查、来自项目的规则、来自用户的规则等

四、agent+hook#

不断地组装新的内容来给大模型，如果我们只是按照顺序来塞进一轮循环中，循环体会变得臃肿；不符合高内聚低耦合的思想；

对于这个问题可以采用hook的方式，把这些操作从循环体中解耦出来；hook可以在工具执行前调用，也可以在工具执行后调用；

通过register_hook、trigger_hooks等方法来讲操作注册进hook中或者触发；

相关操作包括：permission、日志、摘要等

到此为止，整个agent可以安全和顺畅的进行工作

五、 agent+规划能力#

一个agent可以安全顺畅的进行一次任务处理了，但是对于复杂问题的时候，一轮一轮的执行会使得上下文变多，执行过程中产生的bug、以及bug的解决等无关问题会分散大模型的注意力，因为上下文的存在，会使得大模型在一次次的循环中效率下降，甚至脱离任务等。

参考plan and solve的范式可以解决这个问题；为了实现plan and solve，cc引入了todo list。让agent在解决问题之前先想清楚。

新增一个todo write的工具，让大模型在第一次调用的时候，给出解决计划，通过list的方式维护在内存中。list中的每一个元素都必须包含state来记录状态、和对应操作；后续的每一轮执行都可以看到这个list，以及修改list中元素的状态。

当几个轮次没有调用该工具时，需要在下轮的提示词中注入提醒：更新todo；防止走歪；

六、agent + sub Agent#

当一个agent处理一个工作量比较大的任务的时候，可能遇到了新的bug，为了继续下去只能去解决新的bug，在这个过程中产生了非常长的调用链，稀释了大模型的注意力；我们自己遇到bug时，也会新开一个agent来解决bug，解决完再回到原来窗口继续。

本质上就是开一个新的agent，并且把两个agent的上下文分隔开，不让第二个agent的调用内容来污染第一个agent

处理方式就是新增一个工具，允许agent在创建一个新的agent，新的subagent在工作结束后，把结果返回给第一个agent中，仅仅返回结果！；并且sub agent不能再创建新的sub agnet

七、agent + skill#

skill有点类似于tool，也是按需加载的，不同点在于，tool是硬编码的工具，入参到处理到返回结果，一套内容是写死的。但是skill是一套解决内容的方法论，可以包括提示词，相关文件，脚本。当大模型调用skill，读到skill里的内容，skill目录中的内容可以提示大模型怎么处理，可能完全按照流程，可能只走了部分流程，这个过程是灵活的。

工具：读文件、查天气、计算数值、、、（死的） skill：sql规范、前端规范、项目基建配置、、、（灵活的）

原理：harness会扫描skills，每个skill目录会包含一个skill.md文件，主要是包含名字，相关描述；当大模型需要处理相关内容时，如果有符合条件的skill，就会去针对性的加载该skill，把md注入进提示词里，引导大模型通过bash等操作去使用相关脚本、资源等

八、agent + 上下文#

复杂任务中，上下文会一直累积，可能读了许多文件，调用了许多工具，这些内容全部塞进上下文窗口里再去调用大模型，可能会导致超出token上限；但这些东西又没办法丢，可能还是有价值的；

所以需要引入上下文压缩：这几个处理方式分别对应不同情况： l1：对应消息数量太多 l2：对应旧内容太多了 l3：包含超大结果 l4：任然超过token阈值，交给大模型进行压缩提取摘要

九、agent + 记忆系统#

在第八节的内容中会对记忆进行压缩，但压缩后的记忆里的细节可能会丢失。

cc引入memory机制，有一个memory目录，被压缩过的上下文都会保存到这里，同时还有memory.md作为索引，记录了描述、类型等，索引会作为提示词被注入。

记忆有四类：user（记录用户）、feedback（记录一些规则）、project（记录项目情况）、reference（记录找东西怎么找）每一个记忆md

1
--- name: user-preference-tabs description: User prefers tabs for indentation type: user --- User prefers using tabs, not spaces, for indentation. **Why:** Consistency with existing codebase conventions. **How to apply:** Always use tabs when writing or editing files.

MEMORY.md,每一行记录一个链接

1
- [user-preference-tabs](user-preference-tabs.md) — User prefers tabs for indentation

十、agent + 提示词#

每一次塞给大模型的内容都可能会有很多，有来自用户的，有来自tool list的、有tool结果的，有memory、有skill、有subagent、、、、

所以对于每一次大模型的提示词，需要采取拼接的形式来组织。每一次调用替换对应的部分：

Section	加载策略	内容	判断依据
identity	始终	你是谁、怎么做事	始终存在
tools	始终	可用工具列表	`enabled_tools`
workspace	始终	工作目录	始终存在
memory	按需	相关记忆内容	`.memory/MEMORY.md` 是否存在

十一、 agnet+ error#

大模型的调用总是会遇到一些error，作为harness工程，必须要保证把这种不可控性控制住。

以下是常见的情况以及恢复方式：

模式	触发	恢复动作
输出截断	`max_tokens`	升级 8K→64K / 续写提示
上下文超限	`prompt_too_long`	reactive compact → 重试
临时故障	429 / 529	指数退避 + 抖动，连续 529 可切换备用模型
其他还包括：大模型厂商认证、超时等

这一过程在循环中的大模型调用阶段

十二、agent + task系统#

task#

这一部分是对于todo的升级；todo仅仅只是在缓存中，对于大型任务，时间长，任务重，并且需要有任务的先后顺序；所以引入task系统。

task设计为一个工具供大模型调用，创建一个task的json文件，持久化至磁盘，文件内容记录：任务、状态、前置任务列表、处理任务的agent。

1
class Task:
2
id: str
3
subject: str
4
description: str
5
status: str # pending | in_progress | completed
6
owner: str | None # Agent 名（多 Agent 场景） blockedBy: list[str] # 依赖的任务 ID 列表

由agent来认领任务去完成

完成前置任务解锁后置任务，类似力扣课程表的那题。

backgroun task#

有一些任务时耗费时间的，比如一些install之类的bash操作

cc中首先会识别出这些费时间的task（CC 的 bash 工具 schema 里有 run_in_background: boolean 参数（BashTool.tsx:241）

对于需要执行的这些任务，扔到其他线程执行，执行后的结果注入下一轮的提示词中

十三 agent赋予角色，多个合作#

作用与流程#

前面的sub agent只是临时工，完成这个任务就没了，但对于固定的工作模式，可以引入team的方式。

难点在于agent之间的通信。

leader agent启用新的队友，通过 spawn_teammate_thread 把新的agent跑在自己的线程里

每一个团队中的agent，都有一个jsonl邮箱，向某个agent通信，就往对方文件里append

cc中的队友agent的流程：

队友遇到需要审批的操作 → 发 permission_request 到 Lead 收件箱
Lead 的 useInboxPoller 检测到请求 → 路由到审批队列
用户审批后 → Lead 发 permission_response 回队友
队友的 useSwarmPermissionPoller（每 500ms 轮询）收到回复 → 继续或拒绝

约定#

到这一步多个agent可以互相干活了，但是缺少结构化的协议，agent 的通信中可能会涉及危险操作，比如：leader要关闭队友agent，或者队友要执行的操作需要leader来审批

通过一下三个组件来处理：

ProtocolState 每次通过ProtocolState来发起请求，主要关注request_id，后续的回复执行链路都基于这个request_id

1
@dataclass
2
class ProtocolState:
3
request_id: str # 唯一 ID，如 "req_004281"
4
type: str # "shutdown" | "plan_approval"
5
sender: str # 发起方
6
target: str # 接收方
7
status: str # pending | approved | rejected
8
payload: str # 计划文本或关机原因
9
created_at: float # 时间戳
10
pending_requests: dict[str, ProtocolState] = {}

dispatch_message match_response

举例：leader要让bob关机，ProtocolState的形式发送请求，bob收到之后通过dispatch_message路由到关机的相关操作方法，关机完成后match_response再回复leader，完成握手

十四、agent + 空闲轮询#

轮询#

多个agent能相互通信，但是leader发布了多个任务后，如果指定各个agent来处理任务会比较麻烦。

cc引入idle_poll，每五秒轮询一次，前面提到task的元数据里有state、agent，当一个agent完成任务提交后，会进入轮询状态，扫描到存在任务时pedding后，会接取任务并且去完成。完成后进行Summary，提交结果；

十五、 MCP#

前面提到的tool、skill都是自己装配上去的，但是存在一些工具，开发出来后需要适配到各个地方，于是通过mcp的方式来实现，统一了工具和各个host之间的协议，让工具可以随意的被所有人使用。

MCP相关概念：

概念	作用
MCPClient	Agent 端的客户端，连接 server、发现工具、调用工具
MCP Server	外部服务，实现 `tools/list` + `tools/call`
assemble_tool_pool	把内置工具和 MCP 工具组装成一个工具池
mcp_server_tool 命名	避免不同 server 的工具名冲突
Host	宿主，比如cursor、cc、dify

原理如下

host中的mcp client启动后，会扫描配置好的mcp，并检查哪些是可用的，这些mcp被放入注册表中，放入系统提示词中。
当host调用大模型，并且大模型判断需要使用某个mcp时，解析大模型吐出的这段文本，把它翻译成标准的JSON-RPC 2.0 协议格式，构建mcp请求，由mcp client发起调用；
请求来到 mcp service后，有三层，第一层负责通信，接受请求，第二层负责路由，检查这个请求调用了什么东西，并交由对应的方法去处理；第三层就是处理相关业务逻辑；最后再返回结果

jwt、session、token、cookie

Sun, 26 Jul 2026 00:00:00 GMT

session and cookie#

背景#

http的每次请求都是没有包含状态的，服务器不会认识每一个请求，在服务器眼里每一个请求都是单独的，独立的。但是作为用户，有些请求需要验证，如果每次都单独验证体验感会很差。所以需要验证一次，被服务器记住。

所以需要引入一种会话机制，来让服务器认识每一个请求—session。

session是在服务器记录的，每一个session都有一个session id，每一个session单独存放一个用户的相关信息或者其他需要的数据。

cookie存在浏览器，最重要的内容是session id，每一次带上session id去请求，服务器比对通过后，在session中获取对应的用户信息。从而实现上述需求。

cookie#

cookie保存在浏览器，每一次浏览器发起的请求都会自动携带。

特点：

浏览器自己管理，存储于浏览器
大小4kb
敏感信息不能明文存放（如密码）

session#

session是服务器为用户创建的一个用户专属的数据空间；用来保存用户的登录状态，一些简单的业务信息，比如购物车等。每一个session都有唯一的session id。

特点：

存储于服务器，redis、内存
第一次用户请求时创建
设置过期时间
安全
存储空间大

实践案例#

用户登录，创建，set信息

1
     // 2. 创建 Session（关键操作）
2
      HttpSession session = request.getSession();
3

4
      // 3. 将用户信息存入 Session（服务器端）
5
      session.setAttribute("userInfo", username);
6
      session.setAttribute("isLogin", true);

浏览器接收到 Set-Cookie 头，将 JSESSIONID=ABC123 保存到本地。
用户再次访问，进行校验 `

1
  // 2. 服务器根据 Cookie 中的 JSESSIONID 找到对应的 Session
2
    HttpSession session = request.getSession(false); // false 表示不存在不新建
3
    // 3. 校验用户是否已登录
4
    if (session != null && session.getAttribute("isLogin") != null) {
5
      String user = (String) session.getAttribute("userInfo");
6
      // 显示用户信息，访问正常
7
    } else {
8
    // 未登录，重定向到登录页
9
    response.sendRedirect("login.html");
10
    }

退出销毁session

JWT and token#

包含关系，jwt是token的一种实现

背景#

session方案在分布式系统中需要引入redis，同时cookie对于移动端支持不友好。

所以需要引入一种方法，让服务端不用存这些信息，而只是通过签发一个凭证，客户端每次请求带上凭证，服务器能计算出用户是谁。—token思想

而jwt是当前最主流的token实现方案。

jwt#

流程：用户登录后，服务器返回一个jwt，客户端在后续的请求Authorization Header 中携带特点：jwt是可以被公钥/私钥签名的，可确保内容安全传递

结构#

header：包含采用的算法
payload：包含要传递的数据
Signature：前两部分（Header + Payload）加上一个密钥（Secret），通过 Header 中指定的算法生成，用于验证 Token 是否被篡改。HMACSHA256( base64UrlEncode(header) + ”.” + base64UrlEncode(payload), secret )

优点：

无状态/可扩展性：服务器不存储任何 Session，天然支持水平扩展，无需 Redis 等中间件。
跨域/CORS友好：Cookie 有跨域限制（需复杂配置），JWT 通过 Header 传输，调用不同域名的 API 非常方便。
适合移动端：不依赖 Cookie，App 可以轻松存储和使用。
性能：验证只需计算签名和解析 JSON，不需要查询数据库（除非要查更详细的权限），在高并发下优势明显。

缺点： JWT 默认未加密，Payload 可被解码查看。如果被窃取（如 XSS 攻击），攻击者可冒充用户。防御：必须使用 HTTPS；敏感操作使用短有效期

特性	Session	JWT
存储位置	服务端（内存/Redis）	客户端（浏览器本地/App）
状态性	有状态（服务器需存储）	无状态（服务器不存储）
扩展性	需共享存储（Redis）	天然支持分布式
主动吊销	容易（调用 `invalidate`）	困难（必须等到过期）
数据大小	小（只传 Session ID）	可能较大（含完整信息）
安全性	较高（用户数据在服务端）	中等（Payload 可解码，需签名防篡改）
典型场景	传统 Web 应用、对安全性要求极高	RESTful API、微服务、移动应用

claude code task模块学习

Wed, 22 Jul 2026 00:00:00 GMT

背景#

引入背景：cc的todo模块，只存在于单次对话，没有进行持久化，会话结束就丢失；处理简单任务时，todo可以胜任，但处理负责任务时，需要多会话、长流程；需要引入系统性的任务管理能力。（harness）

task的设计#

Tasks 的三项核心改进（和todo的区别）#

Tasks 采用基于文件的存储方式，任务以 JSON 文件的形式保存在 ~/.claude/tasks 目录中。这一设计带来了三点关键变化：

1. 持久化存储

任务不再依赖会话内存。即使退出会话，Tasks 依然存在，因为它们本质上是系统中的真实文件。

2. 依赖关系管理

Tasks 支持显式的依赖关系定义，使得可以按顺序来处理任务。例如，Task B 需要在 Task A 完成后才能开始，Task C 则依赖 A 和 B。这种结构更贴近真实项目，而不是简单的待办列表。

3. 多会话协作

通过设置 CLAUDE_CODE_TASK_LIST_ID=name，多个 Claude Code 会话可以共享同一组任务。当某个会话更新任务状态时，其他会话会同步看到变化。

文件存储结构#

Tasks 以文件形式存储在 ~/.claude/tasks 目录下：

1
~/.claude/tasks/
2
└── /
3
    ├── 1.json
4
    ├── 2.json
5
    └── ...

每个任务都是一个独立的 JSON 文件，以 UUID 命名的文件夹作为容器。

任务 JSON 结构#

每个任务文件包含清晰的元数据：

1
{
2
  "id": "1",
3
  "subject": "Initialize project and install dependencies",
4
  "description": "Set up project structure, package.json, and install core dependencies (express, dotenv, cors, etc.)",
5
  "activeForm": "Initializing project",
6
  "status": "pending",
7
  "blocks": ["2"],
8
  "blockedBy": []
9
}

关键字段说明：

id — 任务标识符
subject — 任务标题
description — 需要完成的内容
activeForm — 执行中的显示文本
status — pending（待处理）、in_progress（进行中）、completed（已完成）
blocks — 等待此任务完成的其他任务（Task 2 无法开始直到 Task 1 完成）
blockedBy — 此任务依赖的任务（空数组表示可以立即开始）

这套依赖关系是以真实文件的形式存储的，而不是保存在内存或会话中。相比之下，传统的 Todos 在关闭终端或会话时就会消失。

任务管理工具#

Claude Code 提供了四个用于任务管理的工具，每个工具对应不同的编排需求。

TaskCreate：创建任务项#

1
TaskCreate({
2
  subject: "Implement JWT authentication middleware",
3
  description: "Add JWT validation to API routes with refresh token support",
4
  activeForm: "Setting up auth middleware..."
5
})

TaskGet：获取任务详情#

1
TaskGet({ taskId: "2" })
2
// 返回：描述、状态、blockedBy、blocks、所有者、时间戳

TaskUpdate：更新任务状态与关系#

1
// 认领任务
2
TaskUpdate({ taskId: "2", owner: "security-reviewer" })
3

4
// 开始工作
5
TaskUpdate({ taskId: "2", status: "in_progress" })
6

7
// 标记完成
8
TaskUpdate({ taskId: "2", status: "completed" })
9

10
// 设置依赖
11
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

TaskList：查看任务列表#

1
#1 [completed] Analyze codebase structure
2
#2 [in_progress] Review authentication module (owner: security-reviewer)
3
#3 [pending] Generate summary report [blocked by #2]

get_task: 查看完整细节#

list_tasks 只显示一行摘要。get_task 返回完整的任务 JSON，包括 description 和依赖细节。跨会话恢复时，Agent 需要读取完整描述才能继续工作：

1
def get_task(task_id: str) -> str:
2
    task = load_task(task_id)
3
    return json.dumps(asdict(task), indent=2)

后台任务#

背景#

如果所有任务都串行执行，会非常浪费时间；一轮对话，可能会产生多个工具调用；我们可以将耗费时间的操作丢到后台去异步执行，执行后返回结果到主会话中，因为llm的调用是loop的形式，后续将这些完成的task通过user message方式注入到后续轮次的主会话的llm调用中。

比如一些install、bash等操作

完整流程#

1
# ============================================================
2
# 处理 AI 响应中的工具调用（Tool Use）
3
# ============================================================
4

5
# 存储所有工具执行结果的列表
6
# 每个元素是一个字典，包含工具调用的返回信息
7
results = []
8

9
# 遍历 AI 响应中的每个内容块（content block）
10
# response.content 可能包含文本、工具调用等多种类型
11
for block in response.content:
12
    # --------------------------------------------------------
13
    # 第一步：过滤非工具调用块
14
    # --------------------------------------------------------
15
    # 只处理 tool_use 类型的块，文本或其他类型直接跳过
16
    # tool_use 表示 AI 决定调用某个工具（如 bash、read_file 等）
17
    if block.type != "tool_use":
18
        continue
19

20
    # --------------------------------------------------------
21
    # 第二步：判断是否需要在后台执行（异步）
22
    # --------------------------------------------------------
23
    # should_run_background 判断逻辑：
24
    #   1. 优先：用户是否显式指定 run_in_background=True
25
    #   2. 兜底：命令是否包含慢操作关键词（install/build/test 等）
26
    if should_run_background(block.name, block.input):
27
        # ---------- 分支 A：后台执行（异步） ----------
28
        # 启动后台任务，立即返回任务 ID
29
        # start_background_task 会：
30
        #   1. 生成唯一 ID（如 bg_0001）
31
        #   2. 在全局字典 background_tasks 中注册任务状态
32
        #   3. 启动守护线程执行实际工具调用
33
        #   4. 立即返回任务 ID（不等待执行完成）
34
        bg_id = start_background_task(block)
35

36
        # 立即返回一个"占位"结果，告知用户任务已在后台启动
37
        results.append({
38
            "type": "tool_result",
39
            "tool_use_id": block.id,          # 关联到具体的工具调用
40
            "content": f"[Background task {bg_id} started] "
41
                       f"Result will be available when complete."
42
        })
43
    else:
44
        # ---------- 分支 B：前台执行（同步） ----------
45
        # 直接执行工具调用，会阻塞直到完成
46
        # 适用于快速操作（如 ls、git status、read_file 等）
47
        output = execute_tool(block)
48

49
        # 返回实际的执行结果
50
        results.append({
51
            "type": "tool_result",
52
            "tool_use_id": block.id,
53
            "content": output                 # 命令的实际输出
54
        })
55

56
# ============================================================
57
# 构造发送给 AI 的 user 消息（包含工具执行结果）
58
# ============================================================
59

60
# 初始化用户消息内容列表
61
# 这个消息将包含两部分：
62
#   1. 后台任务完成的通知（如果有）
63
#   2. 所有工具的执行结果
64
user_content = []
65

66
# ------------------------------------------------------------
67
# 第一部分：收集后台任务完成的通知
68
# ------------------------------------------------------------
69
# collect_background_results() 会：
70
#   1. 检查 background_tasks 中已完成的任务
71
#   2. 从 background_results 中取出输出
72
#   3. 清理已完成的任务（防止内存泄漏）
73
#   4. 返回格式化的通知列表
74
bg_notifications = collect_background_results()
75

76
if bg_notifications:
77
    # 将每条通知作为独立的文本块添加到消息中
78
    # 例如："✅ Background task bg_0001 completed: npm install finished"
79
    for notif in bg_notifications:
80
        user_content.append({"type": "text", "text": notif})
81

82
# ------------------------------------------------------------
83
# 第二部分：添加所有工具的执行结果
84
# ------------------------------------------------------------
85
# 将之前收集的所有 tool_result 追加到消息中
86
# 包括：
87
#   - 同步执行的实际结果
88
#   - 异步执行的占位通知
89
user_content.extend(results)
90

91
# ------------------------------------------------------------
92
# 第三部分：将消息添加到对话历史
93
# ------------------------------------------------------------
94
# 将工具结果作为 user 消息发送给 AI
95
# 这样 AI 就能看到工具执行的结果，并据此生成后续响应
96
#
97
# 关键设计：使用 "user" 角色而不是 "tool" 角色
98
# 原因：某些 AI 模型（如 Claude）不支持 tool 角色
99
#       用 user 消息传递工具结果是兼容性更好的做法
100
messages.append({
101
    "role": "user",
102
    "content": user_content
103
})

展开收起

grpc和protobuf学习笔记

Mon, 20 Jul 2026 00:00:00 GMT

gRPC & Protobuf 知识点整理#

知识点一：Protobuf 是什么，为什么需要它#

1. 背景：服务之间怎么传数据？#

两个服务之间要通信，必须先把内存里的 Java 对象变成能传的东西。

老办法——JSON over HTTP：

1
服务 A  [Java对象] → JSON字符串 → 网络 → JSON字符串 → [Java对象] 服务B

这样做有几个问题：

JSON 是明文，字段名每次都重复传，浪费带宽（一个 “user_id” 字符串就占 7 字节）
字段改名字，生产和测试版本不一致，只能靠人肉保证
反序列化需要跑一遍 JSON parser，速度慢

2. Protobuf 是什么#

Protobuf（Protocol Buffers）= 一套用 .proto 文件定义数据格式的工具。

开发者写一个 .proto 文件描述”我要传什么字段、什么类型”，编译器（protoc）自动生成各种语言的代码（Java / Go / Python / …）。发送方用生成的类序列化，接收方用生成的类反序列化。

1
.proto 文件（人类可读） → protoc 编译 → 各语言代码（Java/Go/Python...）
2

3
                                           ↓
4

5
                                    序列化/反序列化
6

7
                                           ↓
8

9
                                    网络传输（字节流）

和 JSON 的本质区别：序列化后的字节流里只有字段编号 + 值，没有字段名字符串。user_id = 123 在 protobuf 里是 2 字节，在 JSON 里是 16 字节。

3. 项目里的实践#

看 proto/post/post.proto 顶部：

1
syntax = "proto3";
2

3
package com.dating.post.proto;
4

5

6

7
option java_multiple_files = true;
8

9
option java_package = "com.dating.post.proto";
10

11

12

13
import "common/result.proto";

几个关键点：

| 元素 | 含义 |

|------|------|

| syntax = "proto3" | 协议版本，当前主流用 proto3 |

| package com.dating.post.proto | 命名空间，避免不同服务之间的 message 撞名 |

| java_multiple_files = true | 每个 message 生成一个独立的 .java 文件（推荐写法） |

| java_package | 生成代码的 Java 包名 |

| import "common/result.proto" | 引用公共类型，路径是文件相对路径，不是 classpath |

字段编号是 Protobuf 的核心：每个字段有个编号（1、2、3…），序列化时只写编号不写名字，解码时按编号查表。所以编号一旦发布就不能改、不能重用，改字段名不影响二进制格式。

知识点二：gRPC 是什么#

gRPC = Google Remote Procedure Call。本质是一个 RPC 框架，让你像调本地方法一样调远程服务：

1
// 看起来就像普通方法调用
2

3
PostDetailResponse detail = postStub.getPostDetail(request);
4

5
// 实际上跨越了网络，用的是 protobuf 二进制传输

gRPC 跑在 HTTP/2 上，天生支持多路复用（一个连接上同时跑多个请求）和头部压缩；用 protobuf 做序列化，比 JSON 小 310 倍、快 20100 倍。

项目中每个服务自己实现 gRPC Server（监听独立端口），服务之间直接 gRPC 互通，不走 gateway。gateway 的角色是：App 的唯一入口，把 HTTP/JSON 转成 gRPC 调给后端。

生成的代码里，每个 service 会带三种 Stub：

1
UserServiceGrpc.newBlockingStub(channel);   // 阻塞，最常用
2

3
UserServiceGrpc.newFutureStub(channel);    // 返回 ListenableFuture
4

5
UserServiceGrpc.newStub(channel);         // 异步 StreamObserver

项目里用的是 BlockingStub，适合请求-响应场景。

知识点三：gRPC 一次调用到底发生了什么#

想象你在 Java 里写了这一行：

1
postStub.getPostDetail(request);

表面上是普通方法调用，实际上跨越了网络。

第一步：你在 Client 进程里写了一个 Java 对象。这个对象叫 Request，是 protobuf 编译器根据 .proto 文件自动生成的 Builder 模式类。你塞了一些字段进去，比如 post_id = 123。

第二步：客户端框架把这个 Java 对象变成一串字节。这一步叫序列化。protobuf 用 varint 编码，把字段编号（比如 1）和字段值（比如 123）压缩成尽可能短的二进制。post_id = 123 只需要 2 个字节，而同样的信息用 JSON 写”post_id: 123”得花 14 字节。这就是 protobuf 比 JSON 小的根本原因——字段名字符串不用重复出现在字节流里，只编一个数字编号就够了。

第三步：客户端框架把这串字节塞进 HTTP/2 frame 发出去。gRPC 跑在 HTTP/2 上，所以传输层是有结构的 HTTP/2 frame。请求包含两类：HEADERS frame 里写路径、方法名、metadata（比如 traceId）、鉴权 token；DATA frame 里装刚刚序列化好的 protobuf 字节。关键的省钱点：HTTP/2 是多路复用的，同一个 TCP 连接上可以同时跑多个请求，不用每个请求都重新三次握手。

第四步：服务器收到 frame，开始反着走一遍。HTTP/2 框架把 frame 拼回完整请求，HPACK 算法解压 headers 拿到方法路径，protobuf 反序列化把字节流还原成 Java Request 对象。这个过程对你是透明的——你只在最后写了一个 @Override public void getPostDetail(...) 方法，框架已经帮你做完了前面所有脏活。

第五步：gRPC 框架根据路径路由到你的方法。比如 :path = /com.dating.post.proto.PostService/GetPostDetail，框架查路由表找到对应的方法，调进去。你在方法里查数据库、返回数据。

第六步：你写的业务代码往 observer 里塞 Response。observer.onNext(response).onCompleted()，框架又帮你把它序列化回字节流。这一步和第二步是镜像的。

第七步：服务器把字节流通过 HTTP/2 frame 发回去。客户端框架再走一遍第四步的反向，把字节变成 Java Response 对象，赋值给 resp 变量。然后你代码里下一行 resp.getContent() 才被执行——这一步你看见了。

整条链路里，你作为业务开发只看到了两端：一端是构造 Request 调 stub，另一端是 @Override 方法被框架调进来。中间 5 步（序列化、HTTP/2 frame、headers、metadata、反序列化）全是框架干的。这就是为什么 gRPC 写起来像本地调用，但性能是网络级的。

拦截器在哪儿？ 它在第三步之前和第四步之后。在你的业务方法完全不知道的情况下，框架会先过一串拦截器：ServerInterceptor 可以在调业务方法之前验 token、抽 userId。所以项目里的 UserIdInterceptor 不用改任何业务代码，业务方法里 USER_ID_CONTEXT_KEY.get() 就能拿到登录用户——那串数值是拦截器偷偷放进 gRPC 的 Context（类似 ThreadLocal，但能跨线程）里的。

知识点四：项目里的 gRPC 实现#

1. 服务端#

只需要一个 @GrpcService 注解就能启动，继承生成的 ImplBase 类，重写对应的 RPC 方法：

1
@GrpcService
2

3
@RequiredArgsConstructor
4

5
public class PostGrpcService extends PostServiceGrpc.PostServiceImplBase {
6

7
    private final PostWriteService postWriteService;
8

9

10

11
    @Override
12

13
    public void createPost(CreatePostRequest request, StreamObserver<CreatePostResponse> observer) {
14

15
        long postId = postWriteService.createPost(extractUserId(request), request.getContent().trim(), request.getImageKeysList());
16

17
        observer.onNext(CreatePostResponse.newBuilder().setPostId(postId).build());
18

19
        observer.onCompleted();
20

21
    }
22

23
}

展开收起

底层用的是 net.devh:grpc-server-spring-boot-starter，默认监听 9090 端口。

2. 客户端#

Channel 是 HTTP/2 连接，必须在整个应用生命周期复用，不能每次调用都 new。正确做法是注入共享的 stub Bean：

1
@Bean
2

3
public UserServiceBlockingStub userServiceBlockingStub() {
4

5
    return UserServiceGrpc.newBlockingStub(
6

7
        ManagedChannelBuilder.forAddress(userServiceHost, userServicePort)
8

9
            .usePlaintext()   // dev 环境明文，生产要用 TLS
10

11
            .build()
12

13
    );
14

15
}

展开收起

3. 拦截器#

把”每个调用都要做的事”抽成拦截器，业务方法本身不知道它们的存在。比如 UserIdInterceptor 从请求的 metadata 里抽 x-user-id，写入 gRPC Context，业务方法里直接 USER_ID_CONTEXT_KEY.get() 就能拿到登录用户。

4. 错误处理#

gRPC 用 Status 表达错误，常见的有：NOT_FOUND（资源不存在）、INVALID_ARGUMENT（参数错误）、PERMISSION_DENIED（权限拒绝）、INTERNAL（服务器内部错误）、UNAVAILABLE（下游挂了）。

知识点五：proto 模块的构建机制#

1. 为什么单独拆出来#

proto/ 是一个独立 Maven 项目，所有服务都依赖它。好处是单一来源：一个 .proto 文件定义，全公司统一使用，不会出现各服务定义不一致的问题。

1
putao-workspace/
2

3
├── proto/                    ← 独立 Maven 项目，存放所有 .proto 文件
4

5
│   ├── common/               ← 公共 message（Result、Empty 等）
6

7
│   ├── user/
8

9
│   └── post/
10

11
│
12

13
└── dating-server/            ← 另一个独立 Maven 项目
14

15
    ├── post-service/         ← 依赖 post-proto.jar
16

17
    └── user-service/         ← 依赖 user-proto.jar

展开收起

2. 编译过程#

proto 模块的 pom.xml 里配了 protobuf-maven-plugin，执行 mvn compile 时：

protoc 把 .proto → xxxRequest.java、xxxResponse.java（message 类）
protoc-gen-grpc-java → XxxServiceGrpc.java（含 Stub 基类）

生成位置在 target/generated-sources/protobuf/。

3. 服务怎么用#

proto 模块 mvn install 后，业务服务声明依赖：

1
<dependency>
2

3
    <groupId>com.dating</groupId>
4

5
    <artifactId>post-proto</artifactId>
6

7
    <version>1.0.0-SNAPSHOT</version>
8

9
</dependency>

proto 改了必须：① 升版本号 ② mvn deploy 到 Nexus ③ 依赖方同步升级版本。这是硬性规定，否则调用方拿到旧版 stub，编译期就会失败（其实是好事——proto 改字段没法偷偷上线）。

知识点六：实际踩坑总结#

1. proto3 默认值陷阱 ⚠️#

proto3 里默认值字段（int=0、string=""、bool=false）序列化时根本不写进字节流。所以 if (request.getCursor() == 0) 无法区分”客户端没传”和”客户端真的传了 0”。项目里用 string 类型 + “0:0” 兜底规避了这个坑。

2. channel 必须复用 ⚠️#

每次调用都 new ManagedChannel 会耗尽文件描述符。必须注入共享 stub Bean，所有调用共用一个 channel。

3. 版本锁定 ⚠️#

grpc-spring-boot-starter 会拉旧版 grpc stub，和 proto 模块用的新版 grpc 不兼容，导致启动失败。解决方法是显式声明所有 grpc 子模块，统一锁到一个版本。

4. usePlaintext 仅限 dev#

.usePlaintext() 是明文传输，dev 可以用，生产必须改 .useTransportSecurity() 配 TLS 证书。

知识点七：调试工具#

grpcurl 是最常用的命令行工具：

Terminal window

1
# 列出所有服务
2

3
grpcurl -plaintext localhost:9090 list
4

5

6

7
# 调用方法
8

9
grpcurl -plaintext -d '{"post_id": 123}' \
10

11
    localhost:9090 \
12

13
    com.dating.post.proto.PostService/GetPostDetail

开启 gRPC Reflection 后，可以用 grpcurl 直接列出服务方法，不需要导入 .proto 文件：

1
grpc:
2

3
  server:
4

5
    reflection-service-enabled: true

总结：项目里 gRPC + Protobuf 的最佳实践#

✅ 做得好的地方#

proto 单独成模块：通过 Nexus 共享，避免重复定义
强类型契约：服务端改字段时客户端编译期就能发现
字段编号管理：有版本号机制保证兼容性
拦截器机制：UserIdInterceptor 把”获取登录用户”做成通用逻辑
Status 错误码：用标准 gRPC Status

参考资料#

Protocol Buffers 官方文档
gRPC 官方文档
protobuf-maven-plugin
gRPC Spring Boot Starter
项目源码：proto/post/post.proto、dating-server/post-service/pom.xml

Agent学习笔记-rag&HelloAgent

Sat, 11 Jul 2026 00:00:00 GMT

RAG相关知识点#

rag一般流程：

Chunking策略

策略	说明	推荐
固定长度	每N token切一刀	简单场景，512-1024tokens
语义切分	按段落/标题/句号切	结构化文档（首选）
层级Chunk	同时存大块+小块，先small再扩展	长文档
重叠	相邻chunk重叠10-20%	避免边界丢信息

检索策略

纯向量：语义召回好，关键词召回差
混合检索（hybird）：向量+BM25各召回一批，融合排序（生产环境推荐）
重拍（rerank）：先粗召回50-100，再用cross-encoder精排top-10
query扩展：让llm改写多个变体再检索4
HyDe：先让LLM生成“假设答案”，用答案去进行向量相似度检索

测评指标 Recall：召回率，答案被召回了多少 precision：召回的chunk中多少是相关的 mmr：第一个正确答案在第几位出现 ndcg：找到的答案是否被排在靠前的位置 answer faithfulness：最终答案是否忠实于检索内容

Hello Agent的rag系统#

整个系统主要有两个工作流程

数据处理流程：处理和存储知识文档，在这里我们采取工具Markitdown，设计思路是将传入的一切外部知识源统一转化为Markdown格式进行处理。
查询与生成流程：根据查询检索相关信息并生成回答。

系统设计#

1
用户层：RAGTool统一接口
2
  ↓
3
应用层：智能问答、搜索、管理
4
  ↓
5
处理层：文档解析、分块、向量化
6
  ↓
7
存储层：向量数据库、文档存储
8
  ↓
9
基础层：嵌入模型、LLM、数据库

RagTool作为Rag系统的统一入口#

初始化#

1
class RAGTool(Tool):
2
    """RAG工具
3

4
    提供完整的 RAG 能力：
5
    - 添加多格式文档（PDF、Office、图片、音频等）
6
    - 智能检索与召回
7
    - LLM 增强问答
8
    - 知识库管理
9
    """
10

11
    def __init__(
12
        self,
13
        knowledge_base_path: str = "./knowledge_base",
14
        qdrant_url: str = None,
15
        qdrant_api_key: str = None,
16
        collection_name: str = "rag_knowledge_base",
17
        rag_namespace: str = "default"
18
    ):
19
        # 初始化RAG管道
20
        # 创建默认管道

展开收起

1. 多模态文档载入#

1
RAG系统的核心优势之一是其强大的多模态文档处理能力。系统使用MarkItDown作为统一的文档转换引擎，支持几乎所有常见的文档格式。
2
MarkItDown，负责将任意格式的文档统一转换为结构化的Markdown文本。将PDF、Word、Excel、图片还是音频，转换为标准的Markdown格式，然后进入统一的分块、向量化和存储流程。

2. 智能分块策略#

1
经过MarkItDown转换后，所有文档都统一为标准的Markdown格式。
2

3

4
由于所有文档都已转换为Markdown格式，系统可以利用Markdown的标题结构（#、##、###等）进行精确的语义分割
5

6

7
在Markdown段落分割的基础上，系统进一步根据Token数量进行智能分块。由于输入已经是结构化的Markdown文本，系统可以更精确地控制分块边界，确保每个分块既适合向量化处理，又保持Markdown结构的完整性

1
标准Markdown文本 → 标题层次解析 → 段落语义分割 → Token计算分块 → 重叠策略优化 → 向量化准备
2
       ↓                ↓              ↓            ↓           ↓            ↓
3
   统一格式          #/##/###        语义边界      大小控制     信息连续性    嵌入向量
4
   结构清晰          层次识别        完整性保证    检索优化     上下文保持    相似度匹配

1. 输入参数

1
paragraphs: List[Dict]  # 已经切分好的段落列表，每个段落有content、start、end等
2
chunk_tokens: int       # 每个块的最大Token数（如512）
3
overlap_tokens: int     # 块与块之间的重叠Token数（如50）

2. 贪心累积策略

1
while i < len(paragraphs):
2
    p = paragraphs[i]
3
    p_tokens = _approx_token_len(p["content"]) or 1
4

5
    # 关键判断：如果加入当前段落不超过限制，或者当前块为空
6
    if cur_tokens + p_tokens <= chunk_tokens or not cur:
7
        cur.append(p)      # 添加段落
8
        cur_tokens += p_tokens
9
        i += 1             # 移动到下一个段落
10
    else:
11
        # 当前块已满，保存并创建新块
12
        save_current_chunk()
13
        # 处理重叠逻辑...

关键点：

贪心策略：尽可能多地塞入段落，直到塞不下为止
段落完整性：以段落为单位，不会切断一个段落（除非段落本身就超长）
特殊处理：or not cur 确保即使段落超长，也至少包含一个段落

3. 重叠（Overlap）机制

1
if overlap_tokens > 0 and cur:
2
    kept: List[Dict] = []
3
    kept_tokens = 0
4

5
    # 从当前块末尾往前取段落
6
    for x in reversed(cur):
7
        t = _approx_token_len(x["content"]) or 1
8
        if kept_tokens + t > overlap_tokens:
9
            break
10
        kept.append(x)
11
        kept_tokens += t
12

13
    # 反转回来，保持原始顺序
14
    cur = list(reversed(kept))
15
    cur_tokens = kept_tokens

展开收起

工作原理：

保存当前块后，从末尾开始往前取段落
累加Token数，直到达到overlap_tokens限制
这些段落会作为下一个块的起始部分

4. 保存分块

1
content = "\n\n".join(x["content"] for x in cur)  # 用双换行连接
2
start = cur[0]["start"]      # 块的起始位置
3
end = cur[-1]["end"]         # 块的结束位置

找到最后一个有标题路径的段落（用于上下文）

1
heading_path = next((x["heading_path"] for x in reversed(cur) if x.get("heading_path")), None)
2
chunks.append({
3
    "content": content,
4
    "start": start,
5
    "end": end,
6
    "heading_path": heading_path,  # 保留层级结构信息
7
})

3. 统一嵌入与向量存储#

嵌入模型是RAG系统的核心，它负责将文本转换为高维向量，使得计算机能够理解和比较文本的语义相似性。RAG系统的检索能力很大程度上取决于嵌入模型的质量和向量存储的效率。HelloAgents实现了统一的嵌入接口。

检索#

RAG系统的检索能力是其核心竞争力。在实际应用中，用户的查询表述与文档中的实际内容可能存在用词差异，导致相关文档无法被检索到。为了解决这个问题，HelloAgents实现了三种互补的高级检索策略：多查询扩展（MQE）、假设文档嵌入（HyDE）和统一的扩展检索框架。

（1）多查询扩展（MQE）多查询扩展（Multi-Query Expansion）是一种通过生成语义等价的多样化查询来提高检索召回率的技术。

MQE的优势在于它能够自动理解用户查询的多种可能含义，特别是对于模糊查询或专业术语查询效果显著。系统使用LLM生成扩展查询，确保扩展的多样性和语义相关性

1
def _prompt_mqe(query: str, n: int) -> List[str]:
2
    """使用LLM生成多样化的查询扩展"""
3
    try:
4
        from ...core.llm import HelloAgentsLLM
5
        llm = HelloAgentsLLM()
6
        prompt = [
7
            {"role": "system", "content": "你是检索查询扩展助手。生成语义等价或互补的多样化查询。使用中文，简短，避免标点。"},
8
            {"role": "user", "content": f"原始查询：{query}\n请给出{n}个不同表述的查询，每行一个。"}
9
        ]
10
        text = llm.invoke(prompt)
11
        lines = [ln.strip("- \t") for ln in (text or "").splitlines()]
12
        outs = [ln for ln in lines if ln]
13
        return outs[:n] or [query]
14
    except Exception:
15
        return [query]

展开收起

（2）假设文档嵌入（HyDE）

假设文档嵌入（Hypothetical Document Embeddings，HyDE）是一种创新的检索技术，它的核心思想是”用答案找答案”。

这种方法的优势在于，假设答案与真实答案在语义空间中更加接近，因此能够更准确地匹配到相关文档。即使假设答案的内容不完全正确，它所包含的关键术语、概念和表述风格也能有效引导检索系统找到正确的文档。

1
def _prompt_hyde(query: str) -> Optional[str]:
2
    """生成假设性文档用于改善检索"""
3
    try:
4
        from ...core.llm import HelloAgentsLLM
5
        llm = HelloAgentsLLM()
6
        prompt = [
7
            {"role": "system", "content": "根据用户问题，先写一段可能的答案性段落，用于向量检索的查询文档（不要分析过程）。"},
8
            {"role": "user", "content": f"问题：{query}\n请直接写一段中等长度、客观、包含关键术语的段落。"}
9
        ]
10
        return llm.invoke(prompt)
11
    except Exception:
12
        return None

（3）扩展检索框架

HelloAgents将MQE和HyDE两种策略整合到统一的扩展检索框架中。系统通过enable_mqe和enable_hyde参数让用户可以根据具体场景选择启用哪些策略：对于需要高召回率的场景可以同时启用两种策略，对于性能敏感的场景可以只使用基础检索。

扩展检索的核心机制是”扩展-检索-合并”三步流程。首先，系统根据原始查询生成多个扩展查询（包括MQE生成的多样化查询和HyDE生成的假设文档）；然后，对每个扩展查询并行执行向量检索，获取候选文档池；最后，通过去重和分数排序合并所有结果，返回最相关的top-k文档。这种设计的巧妙之处在于，它通过candidate_pool_multiplier参数（默认为4）扩大候选池，确保有足够的候选文档进行筛选，同时通过智能去重避免返回重复内容。

1
def search_vectors_expanded(
2
  #参数
3
) -> List[Dict]:
4
    """
5
    Search with query expansion using unified embedding and Qdrant.
6
    """
7
    if not query:
8
        return []
9

10
    # 创建默认存储
11

12

13
    # 查询扩展
14
    expansions: List[str] = [query]
15

16
    if enable_mqe and mqe_expansions > 0:
17
        expansions.extend(_prompt_mqe(query, mqe_expansions))
18
    if enable_hyde:
19
        hyde_text = _prompt_hyde(query)
20
        if hyde_text:
21
            expansions.append(hyde_text)
22

23
    # 去重和修剪
24
    uniq: List[str] = []
25
    for e in expansions:
26
        if e and e not in uniq:
27
            uniq.append(e)
28
    expansions = uniq[: max(1, len(uniq))]
29

30
    # 分配候选池
31

32
    # 构建RAG数据过滤器
33

34
    # 收集所有扩展查询的结果
35

36
    # 按分数排序返回
37
    merged = list(agg.values())
38
    merged.sort(key=lambda x: float(x.get("score", 0.0)), reverse=True)
39
    return merged[:top_k]

展开收起

Agent学习笔记-记忆模块

Fri, 10 Jul 2026 00:00:00 GMT

认知科学与智能体记忆#

三种记忆类型：

记忆类型	存储内容	何时读写
短期/工作记忆	当前对话历史，确保被高速访问和响应	每轮读写，单次会话内有效
长期记忆	用户偏好、长期事实、知识库；，通过对话了解到的用户偏好、需要长期遵守的指令或领域知识点，都适合存放在这里。	读：每次相关query；写：用户表达相关意图时
情景记忆	长期存储具体的交互事件和智能体的学习经历；包含了丰富的上下文信息，并支持按时间序列或主题进行回顾式检索，是智能体“复盘”和学习过往经验的基础	读：相似场景；写：每次对话结束

Hello Agent中引入感知记忆，负责存储图片、音视频等多模态信息

短期记忆#

生命周期=会话长度

压缩策略	原理	使用
原样保留	不压缩	短对话（<20轮）
滑动窗口	只保留最近N轮	长对话但只关心近期
摘要替换	前k轮摘要为短文	长对话需要整体上下文
层级摘要	多级摘要（最近详细+久远高度摘要）	超长对话
关键消息保留	规则识别出“重要消息”永不压缩	有明确“决策点”的任务

长期记忆#

采用向量+结构化记忆

非结构化知识采用向量+RAG的方式；缺点：语义重叠，过期数据难处理 结构化记忆：固定字段、知识图谱；缺点：设计耗时

情景记忆#

常用方式：

会话结束时把“目标+步骤+结果+反馈”存为一条情景
新会话开始时检索相似情景作为参考
相比向量库检索“知识”，情景记忆检索“经验”

例子：用户上次让Agent订机票，明确要求“靠窗座位”。这条偏好可以：

作为长期记忆存入用户profile（结构化）

作为情景记忆存入交互历史（“上次订机票时用户要靠窗”）下次再订机票时可能两个都命中，但出发条件不同

记忆冲突#

用户先说“我喜欢和咖啡”，后说“我不喜欢和咖啡了”---如何处理

以新覆旧：以最新实时为准（最简单，可能丢失上下文）
带时间戳保留：存两条+时间，检索时按最新的检索
LLM仲裁：交给大模型判断+提示词

Hello Agent记忆系统#

工作流程#

Hello Agent中的记忆系统工作流程： 操作类型分为三种：

添加记忆
- 基于内存和ttl管理的短期记忆
- SQLite+向量数据库的情景记忆
- 知识图谱+向量数据库的长期记忆
- SQLite+向量数据库的多模态记忆
搜索记忆：rag
管理记忆
- 记忆整合（短期记忆进阶为长期记忆/情景记忆）
- 遗忘策略
- 统计分析

memory tool#

业务流程中通过memory tool实现对记忆的管理

1
def execute(self, action: str, **kwargs) -> str:
2
    """执行记忆操作
3

4
    支持的操作：
5
    - add: 添加记忆（支持4种类型: working/episodic/semantic/perceptual）
6
    - search: 搜索记忆
7
    - summary: 获取记忆摘要
8
    - stats: 获取统计信息
9
    - update: 更新记忆
10
    - remove: 删除记忆
11
    - forget: 遗忘记忆（多种策略）
12
    - consolidate: 整合记忆（短期→长期）
13
    - clear_all: 清空所有记忆
14
    """
15

16
    if action == "add":
17
        return self._add_memory(**kwargs)
18
    elif action == "search":
19
        return self._search_memory(**kwargs)
20
    elif action == "summary":
21
        return self._get_summary(**kwargs)
22
    # ... 其他操作

展开收起

添加操作

1
def _add_memory(
2
    self,
3
    content: str = "",
4
    memory_type: str = "working",
5
    importance: float = 0.5,
6
    file_path: str = None,
7
    modality: str = None,
8
    **metadata
9
) -> str:
10
    """添加记忆"""
11
    try:
12
    # 添加记忆操作
13

14
    except Exception as e:
15
        return f"❌ 添加记忆失败: {str(e)}"

展开收起

三个关键任务：

会话ID的自动管理（确保每个记忆都有明确的会话归属）
多模态数据的智能处理（自动推断文件类型并保存相关元数据，不同记忆类型具体识别具体存储）
上下文信息的自动补充（为每个记忆添加时间戳和会话信息）

其中，importance参数（默认0.5）用于标记记忆的重要程度，取值范围0.0-1.0，这个机制模拟了人类大脑对不同信息重要性的评估。这种设计让Agent能够自动区分不同时间段的对话，并为后续的检索和管理提供丰富的上下文信息。

检索操作

1
def _search_memory(
2
    self,
3
    query: str,
4
    limit: int = 5,
5
    memory_types: List[str] = None,
6
    memory_type: str = None,
7
    min_importance: float = 0.1
8
) -> str:
9
    """搜索记忆"""
10
    try:
11
        # 参数标准化处理
12
        if memory_type and not memory_types:
13
            memory_types = [memory_type]
14

15
        results = self.memory_manager.retrieve_memories(
16
            query=query,
17
            limit=limit,
18
            memory_types=memory_types,
19
            min_importance=min_importance
20
        )
21

22
        # 减速以及结果处理
23

24
        return "\n".join(formatted_results)
25

26
    except Exception as e:
27
        return f"❌ 搜索记忆失败: {str(e)}"

展开收起

遗忘操作

1
def _forget(self, strategy: str = "importance_based", threshold: float = 0.1, max_age_days: int = 30) -> str:
2
    """遗忘记忆（支持多种策略）"""
3
    try:
4
        count = self.memory_manager.forget_memories(
5
            strategy=strategy,
6
            threshold=threshold,
7
            max_age_days=max_age_days
8
        )
9
        return f"🧹 已遗忘 {count} 条记忆（策略: {strategy}）"
10
    except Exception as e:
11
        return f"❌ 遗忘记忆失败: {str(e)}"

模拟人类大脑的选择性遗忘过程，支持三种策略：基于重要性（删除不重要的记忆）、基于时间（删除过时的记忆）和基于容量（当存储接近上限时删除最不重要的记忆）。

1
# 1. 基于重要性的遗忘 - 删除重要性低于阈值的记忆
2
memory_tool.execute("forget",
3
    strategy="importance_based",
4
    threshold=0.2
5
)
6

7
# 2. 基于时间的遗忘 - 删除超过指定天数的记忆
8
memory_tool.execute("forget",
9
    strategy="time_based",
10
    max_age_days=30
11
)
12

13
# 3. 基于容量的遗忘 - 当记忆数量超限时删除最不重要的
14
memory_tool.execute("forget",
15
    strategy="capacity_based",
16
    threshold=0.3
17
)

展开收起

合并操作

1
def _consolidate(self, from_type: str = "working", to_type: str = "episodic", importance_threshold: float = 0.7) -> str:
2
    """整合记忆（将重要的短期记忆提升为长期记忆）"""
3
    try:
4
        count = self.memory_manager.consolidate_memories(
5
            from_type=from_type,
6
            to_type=to_type,
7
            importance_threshold=importance_threshold,
8
        )
9
        return f"🔄 已整合 {count} 条记忆为长期记忆（{from_type} → {to_type}，阈值={importance_threshold}）"
10
    except Exception as e:
11
        return f"❌ 整合记忆失败: {str(e)}"

consolidate操作借鉴了神经科学中的记忆固化概念，模拟人类大脑将短期记忆转化为长期记忆的过程。默认设置是将重要性超过0.7的工作记忆转换为情景记忆，这个阈值确保只有真正重要的信息才会被长期保存。整个过程是自动化的，用户无需手动选择具体的记忆，系统会智能地识别符合条件的记忆并执行类型转换。

memory manager#

在底层与memory tool协作，分层设计体现了软件工程中的关注点分离原则，MemoryTool专注于用户接口和参数处理，而MemoryManager则负责核心的记忆管理逻辑。

MemoryTool在初始化时会创建一个MemoryManager实例，并根据配置启用不同类型的记忆模块。

MemoryManager作为记忆系统的核心协调者，负责管理不同类型的记忆模块，并提供统一的操作接口。 首先初始化各种记忆类的的存储、检索组件、配置等

针对四种记忆类型，实现各种记忆类型的

工作记忆（WorkingMemory）

工作记忆是记忆系统中最活跃的部分，它负责存储当前对话会话中的临时信息。工作记忆的设计重点在于快速访问和自动清理，这种设计确保了系统的响应速度和资源效率。

工作记忆采用了纯内存存储方案，配合TTL（Time To Live）机制进行自动清理。这种设计的优势在于访问速度极快，但也意味着工作记忆的内容在系统重启后会丢失。这种特性正好符合工作记忆的定位，存储临时的、易变的信息。工作记忆的检索采用了混合检索策略，首先尝试使用TF-IDF向量化进行语义检索，如果失败则回退到关键词匹配。这种设计确保了在各种环境下都能提供可靠的检索服务。评分算法结合了语义相似度、时间衰减和重要性权重，最终得分公式为：(相似度 × 时间衰减) × (0.8 + 重要性 × 0.4)。
情景记忆（EpisodicMemory）

情景记忆负责存储具体的事件和经历，它的设计重点在于保持事件的完整性和时间序列关系。

情景记忆采用了SQLite+Qdrant的混合存储方案，SQLite负责结构化数据的存储和复杂查询，Qdrant负责高效的向量检索。情景记忆的检索实现展现了复杂的多因素评分机制。它不仅考虑了语义相似度，还加入了时间近因性的考量，最终通过重要性权重进行调节。评分公式为：(向量相似度 × 0.8 + 时间近因性 × 0.2) × (0.8 + 重要性 × 0.4)，确保检索结果既语义相关又时间相关。
语义记忆（SemanticMemory）语义记忆是记忆系统中最复杂的部分，它负责存储抽象的概念、规则和知识。语义记忆的设计重点在于知识的结构化表示和智能推理能力。语义记忆采用了Neo4j图数据库和Qdrant向量数据库的混合架构，这种设计让系统既能进行快速的语义检索，又能利用知识图谱进行复杂的关系推理。

添加记忆时执行知识图谱的完整构建流程、以及向量化存储

检索实现了混合搜索策略，结合了向量检索的语义理解能力和图检索的关系推理能力

混合排序算法采用了多因素评分机制：语义记忆的评分公式为：(向量相似度 × 0.7 + 图相似度 × 0.3) × (0.8 + 重要性 × 0.4)。这种设计的核心思想是：
- 向量检索权重（0.7）：语义相似度是主要因素，确保检索结果与查询语义相关
- 图检索权重（0.3）：关系推理作为补充，发现概念间的隐含关联
- 重要性权重范围[0.8, 1.2]：避免重要性过度影响相似度排序，保持检索的准确性
感知记忆（PerceptualMemory）感知记忆支持文本、图像、音频等多种模态的数据存储和检索。它采用了模态分离的存储策略，为不同模态的数据创建独立的向量集合，这种设计避免了维度不匹配的问题，同时保证了检索的准确性

感知记忆的检索支持同模态和跨模态两种模式。同模态检索利用专业的编码器进行精确匹配，而跨模态检索则需要更复杂的语义对齐机制

Hello Agent第六章学习笔记

Fri, 10 Jul 2026 00:00:00 GMT

为何需要框架#

Agent框架本质：它将所有智能体共有的、重复性的工作（如主循环、状态管理、工具调用、日志记录等）进行抽象和封装，让我们在构建新的智能体时，能够专注于其独特的业务逻辑，而非通用的底层实现。

框架价值的体现：

提升代码复用：提供通用的agent基类，或者执行器；将封装好的内容直接提供进行使用，无论是ReAct还是Plan-and-Excuteed。
实现agent的解耦：
1. 模型层：负责大语言模型的交互、调用、路由、调度等
2. 工具层：mcp、tools，可以随意扩展新的工具而不影响已有代码
3. 记忆层：负责处理短期记忆、长期记忆；以及各种记忆策略（滑动窗口、摘要等）
标准化复杂的状态管理：使用状态管理的方式来辅助流程的处理，包括会话、上下文等，而不是一味地使用大量的if…else…等语句来实现业务流程
简化可观测性与调试过程：引入回调机制或者类似java aop切面编程的思想的方式，来实现日志、数据上报、链路监控等

主流框架对比#

AutoGen：基于对话驱动的协作框架。将多智能体系统抽象为可对话智能体群组，通过角色定义与交互规则配置，以自动化消息传递驱动多轮协作迭代，直至任务完成。

AgentScope：强调易用性与工程化，提供标准化编程接口，覆盖智能体定义、通信网络构建及应用生命周期管理。内置消息传递机制与分布式部署能力，适用于大规模复杂系统的开发与运维。智能体之间通过消息通信，而非函数调用
CAMEL：基于角色扮演的协作范式。通过为智能体分配角色与共同目标，结合初始提示引导，实现自主多轮对话与协同推理，显著降低多智能体对话流程的设计复杂度。
LangGraph：基于图结构的智能体执行框架。将执行流程建模为节点（操作单元）与边（跳转逻辑）构成的有向图，天然支持循环与分支，适合实现迭代修正、自我反思等复杂工作流。

主流框架学习#

AutoGen#

设计#

分层设计：拆分为两个核心模块

autogen-core：作为框架的底层基础，封装了与语言模型交互、消息传递等核心功能。它的存在保证了框架的稳定性和未来扩展性。
autogen-agentchat：构建于 core 之上，提供了用于开发对话式智能体应用的高级接口，简化了多智能体应用的开发流程。这种分层策略使得各组件职责明确，降低了系统的耦合度。 异步优先：在多智能体协作场景中，网络请求（如调用 LLM API）是主要耗时操作。异步模式提升了并发处理能力和系统资源的利用效率。

核心智能体组件#

AssistantAgent (助理智能体)：
- 这是任务的主要解决者，其核心是封装了一个大型语言模型（LLM）。
- 它的职责是根据对话历史生成富有逻辑和知识的回复，例如提出计划、撰写文章或编写代码。通过不同的系统消息（System Message），我们可以为其赋予不同的“专家”角色。
UserProxyAgent (用户代理智能体)： 这是 AutoGen 中功能独特的组件。
- 它扮演着双重角色：既是人类用户的“代言人”，负责发起任务和传达意图；
- 又是一个可靠的“执行器”，可以配置为执行代码或调用工具，并将结果反馈给其他智能体。
- 这种设计清晰地区分了“思考”（由 AssistantAgent 完成）与“行动”。

对话机制#

轮询群聊 (RoundRobinGroupChat)： 这是一种明确的、顺序化的对话协调机制。让参与的智能体按照预定义的顺序依次发言。这种模式非常适用于流程固定的任务，例如一个典型的软件开发流程：产品经理先提出需求，然后工程师编写代码，最后由代码审查员进行检查。
工作流：
1. 首先，创建一个 RoundRobinGroupChat 实例，并将所有参与协作的智能体（如产品经理、工程师等）加入其中。
2. 当一个任务开始时，群聊会按照预设的顺序，依次激活相应的智能体。
3. 被选中的智能体根据当前的对话上下文进行响应。
4. 群聊将新的回复加入对话历史，并激活下一个智能体。
5. 这个过程会持续进行，直到达到最大对话轮次或满足预设的终止条件。

通过这种方式，AutoGen 将复杂的协作关系，简化为一个流程清晰、易于管理的自动化“圆桌会议”。开发者只需定义好每个团队成员的角色和发言顺序，剩下的协作流程便可由群聊机制自主驱动。

AgentScope#

与 AutoGen 相比，AgentScope 的核心差异在于其消息驱动的架构设计和工业级的工程实践。 AgentScope 选择了组合式架构和消息驱动模式。这种设计增强了系统的模块化程度。

分层架构体系：#

694

第一层：地基 —— 基础组件层（Foundational Components） -Message（统一消息格式）

Memory（记忆管理）
Model API（模型调用层）
Tool（工具封装）

第二层：躯干 —— 智能体基础设施层（Agent-level Infrastructure）

内置智能体（Built-in Agents）：框架直接给你几个“半成品”Agent，比如能操作浏览器的、能做深度研究的、能做复杂任务规划的。你可以直接拿来用，或者二次改造。
ReAct 范式实现：这是让 Agent “边想边做”的核心机制。框架帮你把“推理（Reason）”和“行动（Act）”的循环流程写好了，并额外支持：
- 钩子（Hooks）
- 并行调用工具：Agent 一次可以同时调用多个工具，提高效率。
- 结构化输出：强制 Agent 按指定格式（如 JSON）输出，方便程序解析。
- 状态/会话管理：统一管理 Agent 的内部状态，解决你之前关心的“状态持久化”问题。
- 异步执行与实时控制：支持 Agent 在后台“边跑边等”，并且你可以在运行中“插手”调整它的方向（这是 AgentScope 的一大亮点）。

第三层：协作网 —— 多智能体协作层（Multi-Agent Cooperation）解决“多个 Agent 怎么配合干活”：

MsgHub（消息中心）：相当于一个“邮局”，负责所有 Agent 之间的消息转发、路由和状态同步。Agent 们不用互相知道对方地址，只跟 MsgHub 打交道就行。
Pipeline（工作流管道）：提供“流水线”编排能力。你可以设定 Agent 们是按顺序干（串行）、还是一起干（并行）、或者更复杂的模式。这让你能把多个 Agent 组织成一个高效的“流水线工厂”。

第四层：交付与运维 —— 开发与部署层（Development & Deployment）这一层负责“从写代码到上线

消息驱动#

AgentScope 的核心创新在于其消息驱动架构。在这个架构中，所有的智能体交互都被抽象为消息的发送和接收，而不是传统的函数调用。

1
from agentscope.message import Msg
2

3
# 消息的标准结构
4
message = Msg(
5
    name="Alice",           # 发送者名称
6
    content="Hello, Bob!",  # 消息内容
7
    role="user",           # 角色类型
8
    metadata={             # 元数据信息
9
        "timestamp": "2024-01-15T10:30:00Z",
10
        "message_type": "text",
11
        "priority": "normal"
12
    }
13
)

将消息作为交互的基础单元，带来了几个关键优势：

异步解耦: 消息的发送方和接收方在时间上解耦，无需相互等待，天然支持高并发场景。
位置透明: 智能体无需关心另一个智能体是在本地进程还是在远程服务器上，消息系统会自动处理路由。
可观测性: 每一条消息都可以被记录、追踪和分析，极大地简化了复杂系统的调试与监控。

智能体生命周期管理#

在 AgentScope 中，每个智能体都有明确的生命周期（初始化、运行、暂停、销毁等），并基于一个统一的基类 AgentBase 来实现。开发者通常只需要关注其核心的 reply 方法。

1
from agentscope.agents import AgentBase
2

3
class CustomAgent(AgentBase):
4
    def __init__(self, name: str, **kwargs):
5
        super().__init__(name=name, **kwargs)
6
        # 智能体初始化逻辑
7

8
    def reply(self, x: Msg) -> Msg:
9
        # 智能体的核心响应逻辑
10
        response = self.model(x.content)
11
        return Msg(name=self.name, content=response, role="assistant")
12

13
    def observe(self, x: Msg) -> None:
14
        # 智能体的观察逻辑（可选）
15
        self.memory.add(x)

展开收起

消息传递机制#

AgentScope 内置了一个消息中心 (MsgHub)，它是整个消息驱动架构的中枢。

LangGraph#

LangGraph 将智能体的执行流程建模为一种状态机，并将其表示为有向图。在这种范式中，图的节点代表一个具体的计算步骤（如调用 LLM、执行工具），而边（Edges) 则定义了从一个节点到另一个节点的跳转逻辑。

这种设计的革命性之处在于它天然支持循环，使得构建能够进行迭代、反思和自我修正的复杂智能体工作流变得前所未有的直观和简单。

全局状态（State）#

整个图的执行过程都围绕一个共享的状态对象进行。所有的节点都能读取和更新这个中心状态。

1
from typing import TypedDict, List
2

3
# 定义全局状态的数据结构
4
class AgentState(TypedDict):
5
    messages: List[str]      # 对话历史
6
    current_task: str        # 当前任务
7
    final_answer: str        # 最终答案
8
    # ... 任何其他需要追踪的状态

节点（Nodes）#

每个节点都是一个接收当前状态作为输入、并返回一个更新后的状态作为输出的 Python 函数。节点是执行具体工作的单元。

1
# 定义一个“规划者”节点函数
2
def planner_node(state: AgentState) -> AgentState:
3
    """根据当前任务制定计划，并更新状态。"""
4
    current_task = state["current_task"]
5
    # ... 调用LLM生成计划 ...
6
    plan = f"为任务 '{current_task}' 生成的计划..."
7

8
    # 将新消息追加到状态中
9
    state["messages"].append(plan)
10
    return state
11

12
# 定义一个“执行者”节点函数
13
def executor_node(state: AgentState) -> AgentState:
14
    """执行最新计划，并更新状态。"""
15
    latest_plan = state["messages"][-1]
16
    # ... 执行计划并获得结果 ...
17
    result = f"执行计划 '{latest_plan}' 的结果..."
18

19
    state["messages"].append(result)
20
    return state

展开收起

边（Edges）#

边负责连接节点，定义工作流的方向。最简单的边是常规边，它指定了一个节点的输出总是流向另一个固定的节点。而 LangGraph 最强大的功能在于条件边。它通过一个函数来判断当前的状态，然后动态地决定下一步应该跳转到哪个节点。这正是实现循环和复杂逻辑分支的关键。

1
def should_continue(state: AgentState) -> str:
2
    """条件函数：根据状态决定下一步路由。"""
3
    # 假设如果消息少于3条，则需要继续规划
4
    if len(state["messages"]) < 3:
5
        # 返回的字符串需要与添加条件边时定义的键匹配
6
        return "continue_to_planner"
7
    else:
8
        state["final_answer"] = state["messages"][-1]
9
        return "end_workflow"

在定义了状态、节点和边之后，我们可以像搭积木一样将它们组装成一个可执行的工作流。

1
from langgraph.graph import StateGraph, END
2

3
# 初始化一个状态图，并绑定我们定义的状态结构
4
workflow = StateGraph(AgentState)
5

6
# 将节点函数添加到图中
7
workflow.add_node("planner", planner_node)
8
workflow.add_node("executor", executor_node)
9

10
# 设置图的入口点
11
workflow.set_entry_point("planner")
12

13
# 添加常规边，连接 planner 和 executor
14
workflow.add_edge("planner", "executor")
15

16
# 添加条件边，实现动态路由
17
workflow.add_conditional_edges(
18
    # 起始节点
19
    "executor",
20
    # 判断函数
21
    should_continue,
22
    # 路由映射：将判断函数的返回值映射到目标节点
23
    {
24
        "continue_to_planner": "planner", # 如果返回"continue_to_planner"，则跳回planner节点
25
        "end_workflow": END               # 如果返回"end_workflow"，则结束流程
26
    }
27
)
28

29
# 编译图，生成可执行的应用
30
app = workflow.compile()
31

32
# 运行图
33
inputs = {"current_task": "分析最近的AI行业新闻", "messages": []}
34
for event in app.stream(inputs):
35
    print(event)

展开收起

Hello Agent第七章学习笔记

Fri, 10 Jul 2026 00:00:00 GMT

第七章学习地图#

手搓框架的目的#

市面框架的快速迭代与局限性
- 过度抽象的复杂性：许多框架为了追求通用性，引入了大量抽象层和配置选项。
- 快速迭代带来的不稳定性：开发者经常面临版本升级后代码无法运行的困扰，维护成本居高不下。
- 黑盒化的实现逻辑：遇到问题时只能依赖文档和社区支持，尤其是如果社区不够活跃，可能一个反馈意见会非常久也没有人推进，影响后续的开发效率。
- 依赖关系的复杂性：成熟框架往往携带大量依赖包，安装包体积庞大，在需要与别的项目代码配合使用可能出现依赖冲突问题。
从使用者到构建者的能力跃迁（成为Agent工程师的必由之路）
- 深度理解Agent工作原理：通过亲手实现每个组件，开发者能够真正理解Agent的思考过程、工具调用机制、以及各种设计模式的好坏与区别。
- 获得完全的控制权：自建框架意味着对每一行代码都有完全的掌控，可以根据具体需求进行精确调优，而不受第三方框架设计理念的束缚。
- 培养系统设计能力：框架构建过程涉及模块化设计、接口抽象、错误处理等软件工程核心技能，这些能力对开发者的长期成长具有重要价值。
定制化需求与深度掌握的必要性
- 特定领域的优化需求：金融、医疗、教育等垂直领域往往需要针对性的提示词模板、特殊的工具集成、以及定制化的安全策略。
- 性能与资源的精确控制：生产环境中，对响应时间、内存占用、并发处理能力都有严格要求，通用框架的”一刀切”方案往往无法满足精细化需求。

Hello Agent目录结构与学习内容#

1
hello-agents/
2
├── hello_agents/
3
│   │
4
│   ├── core/                     # 核心框架层
5
│   │   ├── agent.py              # Agent基类
6
│   │   ├── llm.py                # HelloAgentsLLM统一接口
7
│   │   ├── message.py            # 消息系统
8
│   │   ├── config.py             # 配置管理
9
│   │   └── exceptions.py         # 异常体系
10
│   │
11
│   ├── agents/                   # Agent实现层
12
│   │   ├── simple_agent.py       # SimpleAgent实现
13
│   │   ├── react_agent.py        # ReActAgent实现
14
│   │   ├── reflection_agent.py   # ReflectionAgent实现
15
│   │   └── plan_solve_agent.py   # PlanAndSolveAgent实现
16
│   │
17
│   ├── tools/                    # 工具系统层
18
│   │   ├── base.py               # 工具基类
19
│   │   ├── registry.py           # 工具注册机制
20
│   │   ├── chain.py              # 工具链管理系统
21
│   │   ├── async_executor.py     # 异步工具执行器
22
│   │   └── builtin/              # 内置工具集
23
│   │       ├── calculator.py     # 计算工具
24
│   │       └── search.py         # 搜索工具
25
└──

展开收起

HelloAgents的架构设计遵循了”分层解耦、职责单一、接口统一”的核心原则，这样既保持了代码的组织性，也便于按照章节扩展内容。

Hello Agent LLM扩展#

多提供商支持：实现对 OpenAI、ModelScope、智谱 AI 等多种主流 LLM 服务商的无缝切换，避免框架与特定供应商绑定。
本地模型集成：引入 VLLM 和 Ollama 这两种高性能本地部署方案，作为对第 3.2.3 节中 Hugging Face Transformers 方案的生产级补充，满足数据隐私和成本控制的需求。
自动检测机制：建立一套自动识别机制，使框架能根据环境信息智能推断所使用的 LLM 服务类型，简化用户的配置过程。

多供应商#

引入MyLLM的基类，通过重写__init__的方法，来支持扩展其他厂商的大模型

1
llm = MyLLM(provider="modelscope")

1
class MyLLM(HelloAgentsLLM):
2
    def __init__(
3
        self,
4
        model: Optional[str] = None,
5
        api_key: Optional[str] = None,
6
        base_url: Optional[str] = None,
7
        provider: Optional[str] = "auto",
8
        **kwargs
9
    ):
10
        # 检查provider是否为我们想处理的'modelscope'
11
        if provider == "modelscope":
12
            print("正在使用自定义的 ModelScope Provider")
13
            # 解析 ModelScope 的凭证
14
            # 验证凭证是否存在
15
            # 设置默认模型和其他参数
16
            # 使用获取的参数创建OpenAI客户端实例
17
        else:
18
            # 如果不是 modelscope, 则完全使用父类的原始逻辑来处理
19
            super().__init__(model=model, api_key=api_key, base_url=base_url, provider=provider, **kwargs)

展开收起

支持本地模型#

在本地实现高性能、生产级的模型推理服务： VLLM、Ollama高性能方案

首先安装并部署vllm、ollama，运行最后调用方式如下：

1
llm_client = HelloAgentsLLM(
2
    provider="vllm",
3
    model="Qwen/Qwen1.5-0.5B-Chat", # 需与服务启动时指定的模型一致
4
    base_url="http://localhost:8000/v1",
5
    api_key="vllm" # 本地服务通常不需要真实API Key，可填任意非空字符串
6
)

自动检测机制#

为了尽可能减少用户的配置负担并遵循“约定优于配置”的原则，HelloAgentsLLM 内部设计了两个核心辅助方法：

_auto_detect_provider ：负责根据环境信息推断服务商
_resolve_credentials：根据推断结果完成具体的参数配置。

_auto_detect_provider 方法负责根据环境信息，按照下述优先级顺序，尝试自动推断服务商：
1. 最高优先级：检查特定服务商的环境变量 这是最直接、最可靠的判断依据。框架会依次检查 MODELSCOPE_API_KEY, OPENAI_API_KEY, ZHIPU_API_KEY 等环境变量是否存在。一旦发现任何一个，就会立即确定对应的服务商。
2. 次高优先级：根据 base_url 进行判断 如果用户没有设置特定服务商的密钥，但设置了通用的 LLM_BASE_URL，框架会转而解析这个 URL。
3. 辅助判断：分析 API 密钥的格式 例如，某些服务商的 API 密钥有固定的前缀或独特的编码格式。不过，由于这种方式可能存在模糊性（例如多个服务商的密钥格式相似），因此它的优先级较低，仅作为辅助手段。
provider 被确定（无论是用户指定还是自动检测），_resolve_credentials 方法便会接手处理服务商的差异化配置。它会根据 provider 的值，去主动查找对应的环境变量，并为其设置默认的 base_url。

框架接口实现#

在上节构建了 HelloAgentsLLM 这一核心组件，解决了与大语言模型通信的关键问题。另外需要一系列配套的接口和组件来处理数据流、管理配置、应对异常，并为上层应用的构建提供一个清晰、统一的结构。

这部分学习以下三个核心文件：

message.py：定义了框架内统一的消息格式，确保信息传递的标准化。
config.py：中心化的配置管理方案，使框架的行为易于调整。
agent.py：定义了所有智能体的抽象基类（Agent），为后续实现不同类型的智能体提供统一的接口和规范。

Message 类#

将 role 字段的取值严格限制为 "user", "assistant", "system", "tool" 四种，对应 OpenAI API 的规范，保证了类型安全。
核心字段： content 和 role
增加了 timestamp 和 metadata字段，为日志记录和未来功能扩展预留了空间。
核心功能之一to_dict() 方法是其，负责将内部使用的 Message 对象转换为与 OpenAI API 兼容的字典格式

cofig类#

将配置项按逻辑划分为 LLM配置、系统配置 等，使结构一目了然。其次，每个配置项都设有合理的默认值，保证了框架在零配置下也能工作。最核心的是 from_env() 类方法，它允许用户通过设置环境变量来覆盖默认配置，无需修改代码，这在部署到不同环境时尤其有用。

Agent抽象基类#

Agent 类是整个框架的顶层抽象。它定义了一个智能体应该具备的通用行为和属性，但并不关心具体的实现方式。

1
"""Agent基类"""
2
from abc import ABC, abstractmethod
3
from typing import Optional, Any
4
from .message import Message
5
from .llm import HelloAgentsLLM
6
from .config import Config
7

8
class Agent(ABC):
9
    """Agent基类"""
10

11
    def __init__(
12
        self,
13
        name: str,
14
        llm: HelloAgentsLLM,
15
        system_prompt: Optional[str] = None,
16
        config: Optional[Config] = None
17
    ):
18
        self.name = name
19
        self.llm = llm
20
        self.system_prompt = system_prompt
21
        self.config = config or Config()
22
        self._history: list[Message] = []
23

24
    @abstractmethod
25
    def run(self, input_text: str, **kwargs) -> str:
26
        """运行Agent"""
27
        pass
28

29
    def add_message(self, message: Message):
30
        """添加消息到历史记录"""
31
        self._history.append(message)
32

33
    def clear_history(self):
34
        """清空历史记录"""
35
        self._history.clear()
36

37
    def get_history(self) -> list[Message]:
38
        """获取历史记录"""
39
        return self._history.copy()
40

41
    def __str__(self) -> str:
42
        return f"Agent(name={self.name}, provider={self.llm.provider})"

展开收起

造函数 __init__ 清晰地定义了 Agent 的核心依赖：名称、LLM 实例、系统提示词和配置

最重要的部分是使用 @abstractmethod 装饰的 run 方法，它强制所有子类必须实现此方法，从而保证了所有智能体都有统一的执行入口。

基类还提供了通用的历史记录管理方法，这些方法与 Message 类协同工作

Agent范式框架化#

首先实现基类Simple Agent、ReAct Agent、Reflection Agent的基类，当需要自定义时，基于这些基类进行扩展，最后实例化并使用自定义的范式Agent

示例：基于基类ReAct Agent实现框架化的Agent#

提示词优化：

1
MY_REACT_PROMPT = """你是一个具备推理和行动能力的AI助手。你可以通过思考分析问题，然后调用合适的工具来获取信息，最终给出准确的答案。
2

3
## 可用工具
4
{tools}
5

6
## 工作流程
7
请严格按照以下格式进行回应，每次只能执行一个步骤:
8

9
Thought: 分析当前问题，思考需要什么信息或采取什么行动。
10
Action: 选择一个行动，格式必须是以下之一:
11
- `{{tool_name}}[{{tool_input}}]` - 调用指定工具
12
- `Finish[最终答案]` - 当你有足够信息给出最终答案时
13

14
## 重要提醒
15
1. 每次回应必须包含Thought和Action两部分
16
2. 工具调用的格式必须严格遵循:工具名[参数]
17
3. 只有当你确信有足够信息回答问题时，才使用Finish
18
4. 如果工具返回的信息不够，继续使用其他工具或相同工具的不同参数
19

20
## 当前任务
21
**Question:** {question}
22

23
## 执行历史
24
{history}
25

26
现在开始你的推理和行动:
27
"""

展开收起

重写ReActAgent的完整实现

创建my_react_agent.py文件来重写ReActAgent：

my_react_agent.py展开收起

1
import re
2
from typing import Optional, List, Tuple
3
from hello_agents import ReActAgent, HelloAgentsLLM, Config, Message, ToolRegistry
4

5
class MyReActAgent(ReActAgent):
6
    """
7
    重写的ReAct Agent - 推理与行动结合的智能体
8
    """
9

10
    def __init__(
11
        self,
12
        name: str,
13
        llm: HelloAgentsLLM,
14
        tool_registry: ToolRegistry,
15
        system_prompt: Optional[str] = None,
16
        config: Optional[Config] = None,
17
        max_steps: int = 5,
18
        custom_prompt: Optional[str] = None
19
    ):
20
        super().__init__(name, llm, system_prompt, config)
21
        self.tool_registry = tool_registry
22
        self.max_steps = max_steps
23
        self.current_history: List[str] = []
24
        self.prompt_template = custom_prompt if custom_prompt else MY_REACT_PROMPT
25
        print(f"✅ {name} 初始化完成，最大步数: {max_steps}")

展开收起

其初始化参数的含义如下：

name： Agent的名称。
llm： HelloAgentsLLM的实例，负责与大语言模型通信。
tool_registry： ToolRegistry的实例，用于管理和执行Agent可用的工具。
system_prompt：系统提示词，用于设定Agent的角色和行为准则。
config：配置对象，用于传递框架级的设置。
max_steps： ReAct循环的最大执行步数，防止无限循环。
custom_prompt：自定义的提示词模板，用于替换默认的ReAct提示词。

框架化的ReActAgent将执行流程分解为清晰的步骤：

1
def run(self, input_text: str, **kwargs) -> str:
2
    """运行ReAct Agent"""
3
    self.current_history = []
4
    current_step = 0
5

6
    print(f"\n🤖 {self.name} 开始处理问题: {input_text}")
7

8
    while current_step < self.max_steps:
9
        current_step += 1
10
        print(f"\n--- 第 {current_step} 步 ---")
11

12
        # 1. 构建提示词
13
        tools_desc = self.tool_registry.get_tools_description()
14
        history_str = "\n".join(self.current_history)
15
        prompt = self.prompt_template.format(
16
            tools=tools_desc,
17
            question=input_text,
18
            history=history_str
19
        )
20

21
        # 2. 调用LLM
22
        messages = [{"role": "user", "content": prompt}]
23
        response_text = self.llm.invoke(messages, **kwargs)
24

25
        # 3. 解析输出
26
        thought, action = self._parse_output(response_text)
27

28
        # 4. 检查完成条件
29
        if action and action.startswith("Finish"):
30
            final_answer = self._parse_action_input(action)
31
            self.add_message(Message(input_text, "user"))
32
            self.add_message(Message(final_answer, "assistant"))
33
            return final_answer
34

35
        # 5. 执行工具调用
36
        if action:
37
            tool_name, tool_input = self._parse_action(action)
38
            observation = self.tool_registry.execute_tool(tool_name, tool_input)
39
            self.current_history.append(f"Action: {action}")
40
            self.current_history.append(f"Observation: {observation}")
41

42
    # 达到最大步数
43
    final_answer = "抱歉，我无法在限定步数内完成这个任务。"
44
    self.add_message(Message(input_text, "user"))
45
    self.add_message(Message(final_answer, "assistant"))
46
    return final_answer

展开收起

通过以上重构，我们将 ReAct 范式成功地集成到了框架中。

工具模块#

`Tool` 基类 — 核心抽象,定义接口规范#

1
class Tool(ABC):
2

3
def __init__(self, name: str, description: str): ...
4

5
@abstractmethod
6
def run(self, parameters: Dict[str, Any]) -> str: ...
7

8
@abstractmethod
9
def get_parameters(self) -> List[ToolParameter]: ...

设计思想：

run() 统一接口：所有工具以一致方式执行，收字典参数、返字符串结果
get_parameters() 自省能力：让框架能自动做参数验证和文档生成
name / description 元数据：支撑工具的可发现性和可理解性

(2) `ToolParameter` 参数，定义参数验证和文档生成支持#

1
class ToolParameter(BaseModel):
2

3
name: str
4

5
type: str
6

7
description: str
8

9
required: bool = True
10

11
default: Any = None

支持类型检查、默认值、文档自动生成。

(3) `ToolRegistry` 注册表 — 管理中枢#

两种注册方式：

方式	适用场景	特点
`register_tool(Tool对象)`	复杂工具	完整参数定义和验证
`register_function()`	简单工具	快速集成现有函数

关键方法：

register_tool() — 注册 Tool 实例
register_function() — 直接注册函数作为工具
get_tools_description() — 生成工具描述字符串（用于构建 Agent 提示词）
to_openai_schema() — 转换为 OpenAI function calling 标准格式

为什么需要 ToolRegistry？用一个故事讲解 场景：没有 ToolRegistry 的混乱世界

假设你在做一个”生活助手 Agent”，用户问：

“帮我算一下 15 * 8 + 32，然后再搜一下 Python 是什么” 如果没有 ToolRegistry，你的代码可能是这样的：

硬编码方式

1
class Agent:
2

3
def __init__(self):
4

5
self.calculator = MyCalculator() # 计算器写死在代码里
6

7
self.searcher = TavilySearch() # 搜索引擎也写死在代码里
8

9
def run(self, user_input):
10

11
if "计算" in user_input:
12

13
expr = parse_expr(user_input)
14

15
return self.calculator.run(expr)
16

17
elif "搜索" in user_input:
18

19
query = parse_query(user_input)
20

21
return self.searcher.search(query)

展开收起

问题来了：

想加一个新工具？改 Agent 的 __init__ 源码
想删掉某个工具？改 Agent 的 __init__ 源码
想给不同用户配不同工具？得写多个 Agent 类
想知道现在有哪些工具可用？翻源码数一数
想换一种工具实现（比如把 Tavily 换成 SerpApi）？改源码，改完还得测试整个 Agent

这就是紧耦合的痛苦。

用 ToolRegistry 的有序世界

有了 ToolRegistry，工具变成了”可插拔的零件”：

创建注册表（工具的”仓库”） registry = ToolRegistry()

需要什么工具，往里注册

1
registry.register_function("calculator", "数学计算", my_calculate)
2
registry.register_function("search", "搜索引擎", my_search)
3
registry.register_function("weather", "查天气", get_weather)

Agent 只认识注册表，不认识具体工具

1
agent = MySimpleAgent(
2
name="生活助手",
3
llm=llm,
4
tool_registry=registry,
5
enable_tool_calling=True
6
)

test123

Tue, 30 Jun 2026 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Firefly 代码块示例

Sat, 03 Jan 1970 00:00:00 GMT

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例</div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Firefly 布局系统详解

Sat, 03 Jan 1970 00:00:00 GMT

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

可以通过showBothSidebarsOnPostPage配置是否在文章详情页显示双侧边栏

当position为left或right时开启此项后，文章详情页将显示双侧边栏，主页等其他页面保持单侧边栏

适用在只想用单侧栏，但在文章详情页想用对侧栏的目录等组件的场景

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list", // 列表模式
4
    allowSwitch: true,   // 允许用户切换
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    allowSwitch: true,
5
    grid: {
6
      masonry: true,      // 开启瀑布流
7
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
8
    },
9
  },
10
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

Firefly 文章加密

Fri, 02 Jan 1970 00:00:00 GMT

这是一篇密码保护的示例文章，用于演示文章加密功能。

Firefly 一款清新美

Fri, 02 Jan 1970 00:00:00 GMT

🌟 项目概述#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

🏠我的博客： https://blog.cuteleaf.cn

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

CuteLeaf

Firefly

Waiting for api.github.com...

Waiting for api.github.com...

00K

Waiting...

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly使用文档获取完整的配置指南

Firefly 简单使用指南

Fri, 02 Jan 1970 00:00:00 GMT

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

KaTeX 数学公式示例

Fri, 02 Jan 1970 00:00:00 GMT

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)

极限与求和 (Limits and Sums)#

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2lim⁡x→0sin⁡xx=1\lim_{x \to 0} \frac{\sin x}{x} = 1x→0limxsinx=1

麦克斯韦方程组 (Maxwell’s Equations)#

∇⋅E=ρε0∇⋅B=0∇×E=−∂B∂t∇×B=μ0J+μ0ε0∂E∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

时序图示例#

时序图显示对象之间随时间的交互。

甘特图示例#

甘特图非常适合显示项目进度和时间线。

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

Markdown 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

***

在文章中嵌入视频

Thu, 01 Jan 1970 00:00:00 GMT

只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。

1
---
2
title: 在文章中嵌入视频
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

Putao's blog

claude code的层层拼装

一、agent到agent loop#

二、agent+工具#

三、agent+禁止规则#

四、agent+hook#

五、 agent+规划能力#

六、agent + sub Agent#

七、agent + skill#

八、agent + 上下文#

九、agent + 记忆系统#

十、agent + 提示词#

十一、 agnet+ error#

十二、agent + task系统#

task#

backgroun task#

十三 agent赋予角色，多个合作#

作用与流程#

约定#

十四、agent + 空闲轮询#

轮询#

十五、 MCP#

jwt、session、token、cookie

session and cookie#

背景#

cookie#

session#

实践案例#

JWT and token#

背景#

jwt#

结构#

claude code task模块学习

背景#

task的设计#

Tasks 的三项核心改进（和todo的区别）#

文件存储结构#

任务 JSON 结构#

任务管理工具#

TaskCreate：创建任务项#

TaskGet：获取任务详情#

TaskUpdate：更新任务状态与关系#

TaskList：查看任务列表#

相关操作：#

create_task: 创建任务#

can_start: 依赖检查#

claim_task: 认领任务#

complete_task: 完成与解锁#

get_task: 查看完整细节#

后台任务#

背景#

相关操作#

完整流程#

grpc和protobuf学习笔记

gRPC & Protobuf 知识点整理#

知识点一：Protobuf 是什么，为什么需要它#

1. 背景：服务之间怎么传数据？#

2. Protobuf 是什么#

3. 项目里的实践#

知识点二：gRPC 是什么#

知识点三：gRPC 一次调用到底发生了什么#

知识点四：项目里的 gRPC 实现#

1. 服务端#

2. 客户端#

3. 拦截器#

4. 错误处理#

知识点五：proto 模块的构建机制#

1. 为什么单独拆出来#

2. 编译过程#

3. 服务怎么用#

知识点六：实际踩坑总结#

1. proto3 默认值陷阱 ⚠️#

2. channel 必须复用 ⚠️#

3. 版本锁定 ⚠️#

4. usePlaintext 仅限 dev#

知识点七：调试工具#

总结：项目里 gRPC + Protobuf 的最佳实践#

✅ 做得好的地方#

参考资料#

Agent学习笔记-rag&HelloAgent

`Tool` 基类 — 核心抽象,定义接口规范#

(2) `ToolParameter` 参数，定义参数验证和文档生成支持#

(3) `ToolRegistry` 注册表 — 管理中枢#