zgf's blog

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 会自动转换为小写

Agent Skill 技能系统：从能力封装到可进化资产的工程化全链路

Mon, 27 Jul 2026 00:00:00 GMT

2026-07-27 Agent Skill 技能系统：从”能力封装”到”可进化资产”的工程化全链路#

📅 学习日期：2026-07-27 | 📚 来源：AI Agent 知识库 | 📝 综合文章数：5 篇

为什么选这个主题#

前两篇笔记已覆盖了 Agent 架构演进（宏观坐标系）和记忆系统（成长性引擎），今天深入第三个核心组件——Skill 技能系统。在架构演进笔记中，Skill 是 Harness 能力层的关键组成、Loop 五原语之一；在记忆系统笔记中，“记忆与技能深度融合”被标记为演进趋势。Skill 是 Agent 从”能执行”到”能沉淀经验”再到”能自主进化”的中间枢纽——它把模型的一次性能力变成可复用、可组合、可治理的标准化资产。另外，你最近在用的 ima.copilot 的 skill 机制（比如刚创建的 daily-learning-note）本身就是 Agent Skill 的一个具体实例——今天从理论到实践全面拆解它。

核心要点#

要点 1：Skill 不是 Prompt，是结构化行为设计——三重分立架构是核心骨架#

多篇文章都强调同一个定义：Skill 不是一段 Prompt，而是围绕任务、工具、流程和输出边界的结构化行为设计。最小形态只需一个 SKILL.md 文件（YAML 元数据 + Markdown 指令），但背后有三重分立架构支撑：

分立层	角色	产出	核心问题
心智层（元）	人或协调者 Agent	spec.md / YAML 元数据	”做什么”
规范层（规）	SKILL.md 作为 SOP	SKILL.md 正文	”怎么做”
底座层（源）	执行资源与安全环境	scripts/、templates/、Docker沙箱	”怎么安全地做”

这个架构的设计哲学是声明式规范（Spec）作为唯一真理源——“外部规范架构接管内部概率输出”。人类锁定 Spec，AI 和 Skill 基于 Spec 实现，确保需求与实现精确对齐。代码被视为规范的”实现衍生品”，而非核心资产。

Skill 作为 Prompt 增强包的含义：它在基础 Prompt 之外，按需为 Agent 注入特定领域的知识、操作流程与输出约束。不是写死在系统提示词中，而是渐进式加载——仅在相关任务出现时才激活对应内容。目前已有 33+ 个 Agent 产品采纳此规范（Claude Code、Cursor 等）。

要点 2：三层懒加载是 Token 经济学的核心设计——上下文消耗降约 90%#

所有文章都认同：大模型上下文窗口是稀缺资源，Skill 系统必须解决”海量能力库 vs 有限窗口”的矛盾。三层懒加载（渐进式披露）是公认的解决方案：

层级	加载时机	内容	Token 消耗
L1 元数据层	系统启动时	name + description（每个~50-100 Token）	20个Skill仅1000-2000 Token
L2 指令层	任务匹配时	SKILL.md 正文（<5000 Token）	按需加载，不常驻
L3 资源层	执行引用时	scripts/、references/、assets/	仅在执行步骤中按需引用

关键数据：相比单体式提示词（把所有能力写死在 system prompt），上下文使用量减少约 90%。Anthropic 的16个官方 Skill 中，参考文档渐进加载型（如 pptx、mcp-builder）通过三层信息模型（L0概览~30Token/L1 body~500-2000/L2文档~1000-5000）节省 Token 最高约 46%。

编排场景的三层懒加载扩展：多 Skill 编排时，L1 作为全局路由索引，L2 作为编排流程每步的 SOP，L3 作为步骤落地的工具箱。动态匹配 → 技能链组合 → 条件分支，全部在三层架构内完成。

要点 3：5 种执行模式与一个关键发现——Function Calling 不是必需的#

源码拆解文章揭示了 Anthropic 16个官方 Skill 的 5 种执行模式，并得出一个颠覆直觉的结论：

模式	代表 Skill	特点	适用场景
纯 Prompt 注入型	frontend-design、brand-guidelines	只有 SKILL.md，无脚本无依赖	教规范/风格
脚本执行型	pdf、pptx、xlsx	SKILL.md当教程 + scripts/当工具箱	操作特定文件格式
库调用型	slack-gif-creator	自带 Python 库（core/），LLM现场写代码import	灵活组合 API
参考文档渐进加载型	pptx、mcp-builder	SKILL.md做路由表，详细文档按需加载	知识量大需分文档
编排型	skill-creator	32KB超详细编排指南+子Agent+脚本	复杂多步骤工作流

颠覆性发现：所有16个 Skill 均未使用 Function Calling，全部通过 SKILL.md 文本 + skill_run 沙箱命令驱动。原因有三：

LLM 本身就是最好的代码执行器——注册 function calling 限制灵活性，LLM 看示例后能自己写代码，完成技能作者未预想的操作
skill_run 是万能兜底——任何语言/命令只要能在 shell 跑就能执行；Token 经济上看，1个 skill_run Schema约20 Token vs 8个独立 function calling 约1600-4000 Token，10轮对话差 1.6万-4万 Token
Tools: 价值场景窄——只有调用不能靠代码/shell完成的操作（内部API、数据库等）才需要

结论公式：Skill 的执行力 = SKILL.md body 质量 × (Agent 基础工具 + skill_run 沙箱能力)。Function Calling 只是可省略的”可选配件”。

要点 4：五层纵深防御 + 七阶段闭环——Skill 不是”写完就跑”，而是全生命周期治理#

Skill 的工程化不只是写好 SKILL.md，而是需要从诞生到退役的完整治理体系：

五层协同纵深防御：

层级	治理内容
规范/设计层	安全基线”宪法”（constitution.md），安全左移
元数据/契约层	YAML声明最小权限集（allowed-tools）、风险等级
指令/执行层	流程嵌动态权限校验、风控链、强制人工审批断点（HITL）
资源/运行时层	Docker”每任务一容器”沙箱隔离、临时凭证注入
平台/治理层	企业级资产中心统一纳管、RBAC集成、集中审计

七阶段闭环管理：

规划与定义 → 2. 设计与开发 → 3. 测试与验证 → 4. 发布与上架 → 5. 发现与部署 → 6. 运行监控与治理 → 7. 迭代演进与下线

每个阶段之间有质量门禁：开发态→可发现态需通过所有测试+SBOM安全审查；可发现态→部署态必须”版本锁定”（禁 latest）；运行态→迭代态需数据评估+灰度预案。

“人在回路”断点机制：编排引擎内置 HITL 断点。执行到预设高风险环节（删生产数据、合规审查、资金交易、合并主干），自动将状态置为 AWAITING_APPROVAL，只有指定权限的人类审批后才继续。

要点 5：Google 的 5 种设计模式 + Anthropic 的评估体系——Skill 开发有成熟方法论#

Google ADK 的 5 种可组合设计模式：

模式	核心思路	示例
Tool Wrapper	给 Agent 装”技能包”，需要时加载领域知识	FastAPI规范 Skill
Generator	模板+风格指南强制一致输出，主动提问补信息	报告生成 Skill
Reviewer	分离”查什么”和”怎么查”，按清单打分解释WHY	代码审查 Skill
Inversion	Agent 先采访用户弄清需求再动手	项目规划 Skill
Pipeline	多步骤带质检关卡，不通过不向下	调研→起草→整合→交付

模式可组合：Pipeline+Reviewer（带质检的流水线）、Generator+Inversion（先问清楚再生成）。

Anthropic Skill-Creator 的评估体系——像做机器学习一样做 Prompt Engineering：

三个专业化子 Agent：Grader（评估断言通过与否+自我批评断言质量）、Comparator（双盲比较 A/B 输出）、Analyzer（揭盲分析胜负原因）
7种 JSON Schema 贯通数据流（evals→timing→metrics→grading→benchmark→comparison→analysis→history）
TDD 循环（RED-GREEN-REFACTOR）：先不带 Skill 跑压力场景记录违规，再写最小 Skill，最后堵新借口保持合规

四类 Skill 的差异化测试策略：

纪律执行型 → 最严测试（最大压力下仍守规）
技术指导型 → 应用场景正确性
思维模式型 → 判断何时用何时不用的准确性
参考资料型 → 检索发现性与覆盖度

要点 6：Skill 正在从静态资产走向可进化生态——记忆融合、自学习、联邦网络#

多篇文章都指向同一个趋势：Skill 不再是写完就锁定的静态资产，而是有内生进化机制的”活知识”。

自学习机制：失败驱动为核心触发。框架如 EXIF（探索者-执行者）、Memento-Skills（Read→Execute→Reflect→Write，性能提升116%）、Hermes（学习-固化-复用）。技能文档外化为”外部可训练状态”，能力与模型解耦——Skill 进化不需要重新训练模型。

记忆与技能深度融合：记忆演进为程序性记忆库，沉淀经验实现跨任务迁移与个性化自适应。这正是昨天记忆系统笔记中提到的趋势——今天从 Skill 视角看到了具体落地方式。

多 Agent 协作架构的量化成效：跨行业规模化落地后，错误率降低 65%、任务执行速度提升 40%、综合成本降低 25%。支撑路径包括”MCP协议+代码执行”范式（Token开销降超98%）、技能按需加载（基础上下文降约90%）、模型路由与语义缓存（降本30-50%）。

未来方向：

SkillOS（技能操作系统）：自主管理技能生命周期
联邦技能网络：跨组织安全共享协同，降重复建设
自适应编排：编排器具元推理与动态规划，自主重组任务、动态生成临时技能
从”技能工程”到”经验蒸馏”：从数字足迹提取技能

分歧与讨论#

Function Calling 是否必需？ Anthropic 16个官方 Skill 全部不用 Function Calling，只用 SKILL.md + skill_run。但这可能是因为这些 Skill 都是可以靠代码/shell 完成的操作型任务。对于需要调用内部API、数据库等不能用代码完成的场景，Function Calling 仍然不可替代。结论：不是”Function Calling 没用”，而是”大多数 Skill 不需要它，只在特定场景才用”。
单一职责 vs 复合编排：单一职责原则要求每个 Skill 只做一件事，但编排型 Skill（如 skill-creator）本身就是多步骤工作流。这两者如何平衡？答案可能是：单个 Skill 保持单一职责，复杂流程通过多 Skill 组合编排实现——而不是让一个 Skill 包办一切。
Spec 作为唯一真理源 vs 实际执行中的灵活性：声明式规范要求人类锁定 Spec 后 AI 基于其实现，但实际执行中 Agent 可能发现 Spec 没覆盖的边界情况。Hermes 的”LLM审判官”机制允许 Agent 自主生成和修改 Skill，这与 Spec-First 原则存在张力。可能的调和方式是：Spec 定义”做什么”，但允许 Agent 在边界情况下自主调整”怎么做”——只要最终结果符合验收标准。
Skill 生命周期治理的成本：七阶段闭环+五层纵深防御听起来很完善，但对小团队和早期项目，这个治理体系可能过于沉重。四阶段渐进式实施路径建议：先做1-2个高频场景试点，再逐步建设治理体系——治理是规模化后才需要的，早期先把 Skill 跑起来更重要。

与已学内容的联系#

07-23：Agent 架构演进

Skill 属于 Harness 能力层 → Loop 的五原语之一 → Agent OS 的组件
架构演进中”验证比生成重要”的结论，在 Skill 的五层纵深防御和 HITL 断点机制中得到了具体落地
“智能下沉到模型、确定性留给框架”的设计哲学，在 skill_run 沙箱执行中得到了体现——模型写代码，框架提供确定性执行环境

07-24：Agent 记忆系统

记忆系统笔记提到”记忆与技能深度融合”是演进趋势 → 今天从 Skill 视角看到了具体实现：技能文档外化为”外部可训练状态”，记忆演进为程序性记忆库
记忆系统的”写入门控”（决定什么值得存），在 Skill 的”写入过滤机制”中有对应设计——不是所有信息都值得写进记忆，也不是所有能力都值得封装成 Skill
Skill 的三层懒加载和记忆系统的三层架构（工作/短期/长期）有结构上的相似性——都是解决”海量信息 vs 有限资源”矛盾的分级管理方案

实际使用场景：ima.copilot 的 daily-learning-note Skill

你正在用的这个 Skill 本身就是 Agent Skill 的一个实例
SKILL.md 定义了5个阶段的 SOP（Phase 1-5）、关键约束、故障处理
触发方式完全依赖 description 字段的语义匹配（“今天的学习笔记”、“每日学习”等）
没有使用 Function Calling，完全靠 SKILL.md 指令驱动

💡 思考题#

你正在用的 daily-learning-note Skill 属于5种执行模式中的哪一种？如果要让它变得更强大（比如自动搜索+自动写笔记+自动推送），应该往哪种模式演进？需要加什么组件？ ——这道题帮你把今天的理论映射到正在用的实际产品上。
Anthropic 的发现”Function Calling 不是必需的”在你的工作场景中是否成立？你有多少任务是可以靠代码/shell完成的，有多少必须调用内部API或第三方服务？这个比例决定了你的 Skill 系统是否需要 Function Calling 层。 ——这道题帮你判断自己应该采用哪种 Skill 执行模式。

🎯 行动项#

拆解一个你正在使用的 Skill：读一下 /sandbox/workspace/skills/daily-learning-note/SKILL.md 的完整内容，对照今天的5种执行模式、三层懒加载、质量门禁，标注它目前属于哪一层、缺什么、可以怎么进化。这个练习会让今天的理论变成具体的改进方案。
尝试写一个最小 Skill：选一个你日常重复做的任务（比如”每天早上整理待办事项”），写一个只有 SKILL.md 的纯 Prompt 注入型 Skill，跑起来验证效果。先跑通再迭代——这是 Skill 开发的正确顺序。

参考文章#

[技能生成与管理的技术架构、编排机制、权限治理及全生命周期流程解析]（note_8063fdd1b44b6b1cc34019dc46a067c0_74472693264845147307200439519008，提供了三重分立架构、三层懒加载扩展、五层纵深防御和七阶段闭环的完整框架）
[Skill工程方法论：从规范驱动到资产封装的企业级AI落地指南]（note_8063fdd1b44b6b1cc34019dc46a067c0_74438053556704087307200439519008，提供了声明式规范、Spec-First原则和四阶段渐进式实施路径）
[Agent Skill规范、构建与设计模式]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_49650c6b0de0f7e8de9cdb799fe010557307200439519008，提供了Google5种设计模式、Skill-Creator评估体系和TDD循环）
[兄弟！你真的懂 Skill 吗？]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_5948286acfc6f1ab86db7272b9372c577307200439519008，提供了Anthropic16个官方Skill的源码拆解、5种执行模式、Function Calling非必需的发现）
[Agent Skills的系统化应用、管理与进化方法论]（note_8063fdd1b44b6b1cc34019dc46a067c0_74663622344997097307200439519008，提供了三位一体方法论、量化成效、自学习机制和未来演进方向）

Agent 记忆系统：从失忆症到可成长系统的工程化路径

Fri, 24 Jul 2026 00:00:00 GMT

2026-07-24 Agent 记忆系统：从”失忆症”到”可成长系统”的工程化路径#

📅 学习日期：2026-07-24 | 📚 来源：AI Agent 知识库 | 📝 综合文章数：5 篇

为什么选这个主题#

昨天学了 Agent 架构从 Prompt 到 Graph 的层叠递进路径，其中提到 Context Engineering 管理”模型该看到什么”，Memory 是其核心实现。但昨天的笔记只触及了 Memory 的概念定位，没有深入到”怎么设计”和”怎么落地”。今天的主题正好补上这块——Memory 是 Agent 从”一次性工具”升级为”可成长系统”的关键转折点，它决定了 Agent 能不能积累经验、能不能跨会话连续、能不能在长时间跨度保持稳定。也和你之前读的那篇 LangGraph 文章直接关联——create_react_agent 的 AgentState.messages 就是最简形态的工作记忆。

核心要点#

要点 1：上下文窗口不是记忆，是工作台——三层架构是行业共识#

所有 5 篇文章都指向同一个基本判断：大模型只有”当下”，没有”过去”。上下文窗口是临时的、有限的工作台，不是可以无限堆放的档案柜。

在这个共识基础上，三层记忆架构已经成为行业自然演化的标准结构：

层级	角色	存储内容	典型实现	核心解决的问题
工作记忆	便签（桌面上）	当前推理所需：目标、最近几步、工具返回	上下文窗口（经筛选压缩）	“此刻需要什么”
短期记忆	文件夹（手边）	当前任务周期内的摘要：做过什么、关键发现	Checkpointer、任务状态存储、SQLite	”这次任务做到哪了”
长期记忆	档案室（永久）	跨任务跨会话：用户偏好、项目规范、历史经验	向量数据库 + 图数据库、Store	”之前学到了什么”

三层协作机制：任务开始 → 从长期记忆检索相关信息注入工作记忆；执行过程中 → 关键信息写入短期记忆；工作记忆满时 → 归档到短期记忆，同时从短期记忆取回当前需要的内容；任务结束 → 有价值的经验沉淀到长期记忆。

Harness Memory 文章给出了一个精确的定位：“Agent 的能力来自模型，稳定性来自 Harness，成长性来自 Memory”——这是昨天”模型决定上限，Harness 决定上限能否稳定落地”之后，补上的第三句话。

要点 2：四个关键设计决策——决定记忆系统成败的不是架构而是策略#

架构是骨架，但真正决定系统好不好用的是四个设计决策：

决策一：写什么进记忆？

不是所有信息都值得记住。什么都写 → 噪声库 → 更难找到有用的
写入过滤机制：完整 JSON 返回不写，“调用了什么工具、核心结论是什么”写；失败本身不重要，“为什么失败、应该避免什么”很重要
2026年3月的综述论文提出五种核心机制：上下文压缩、检索增强存储、反思式自我改进、层级化虚拟上下文、策略驱动管理——共同特点是主动筛选和组织，而非被动堆积

决策二：何时读记忆？

读太频繁 → 增加延迟和成本；读太少 → 等于没有记忆
事件驱动检索：新任务、新阶段、遇到困难时触发，不是每一步都查
检索质量：关键词匹配远远不够，语义检索是基本要求，还要考虑时间维度（最近的更有价值）和任务相似度（类似任务的经验更值得调取）

决策三：如何更新和遗忘？

记忆不是只写不删的日志——信息会过时、被修正、互相矛盾
时间衰减：越久远权重越低，除非近期被引用
时间有效性窗口（Zep做法）：每条记忆标注何时生效、何时被替代
策展器维护 playbook（微软ACE）：增量更新、合并冲突、删除过时条目，避免无限膨胀
灾难性遗忘问题：引入新知识后旧技能被覆盖，EWC/正交更新抑制参数干扰

决策四：隔离与权限？

不同用户的偏好不应互相污染；不同 Agent 的任务经验不一定适合共享（代码审查Agent的经验对客服Agent可能误导）
命名空间或权限机制：用户级、任务级、系统级各自隔离，只在明确需要时跨域检索
多 Agent 环境下的记忆架构差异：私有+共享池、黑板系统、层级记忆模型、内在记忆模型各有取舍

要点 3：四大可靠性问题——记忆不是”存了就行”，存错了比没存更危险#

学术综述文章提炼了记忆系统的四大可靠性问题，这是工程实践中最容易踩的坑：

问题	表现	根因	解决方案
幻觉（含行动幻觉）	虚构记忆或错误回忆；工具场景中错误推断环境反馈	先验错配、检索误配、缺乏环境绑定	多体交叉评审、验证式RAG、不确定性标注
灾难性遗忘	新知识覆盖旧技能/偏好	参数干扰、分布漂移、回放失衡	EWC/正交更新、生成式回放、参数隔离
一致性冲突	共享记忆冲突断裂，Agent间状态观不一致	滑窗漂移、多源冲突、并发时延	因果版本化/CRDT、两阶段提交、快照检索
错误传播与自放大	早期错误写入记忆被重复引用形成”错误回路”	经验追随、无监督自证	写入门控、错误指纹绑定再验证、周期性体检

最危险的是错误传播——Xiong等的研究证明，无校验下错误会指数级放大。这意味着”存错了比没存更危险”——一条错误经验被反复引用，Agent 会越跑越偏。

工程启示：记忆系统需要写入门控——写入前做置信度阈值校验、多源一致性校验；高风险读取前做交叉核验；周期性自动冲突检测合并。这不是锦上添花，是必须有的防线。

要点 4：技术路径之争——向量+图混合架构正在成为主流#

从5篇文章中可以清晰看到记忆系统的技术路径分化与收敛：

向量数据库路线（如 Mem0 基础版）：语义检索为主，简单高效，但缺乏时间维度和关系推理。

时序知识图谱路线（如 Zep）：每条记忆带时间有效性窗口，能处理信息更新和过时，检索结合语义+BM25+广度优先搜索。

虚拟内存分页路线（如 LETTA/MemGPT）：Main Context + External Context，递归摘要压缩，Agent自主决定何时读写——让模型管理自己的记忆。

向量+图混合路线（当前主流方向）：Mem0-G、Zep、MemOS 都走这条路——向量做语义检索，图做实体-关系推理和时间维度管理，互补而非互斥。

LangGraph 的工程实践提供了具体的落地参考：

短期记忆用 Checkpointer（每个 super-step 保存图状态快照）
长期记忆用 Store（键值数据库，跨对话线程共享，支持语义搜索）
两者协同：短期保实时执行，长期保跨任务经验复用
上下文管理策略：修剪消息（trim）、删除消息（RemoveMessage）、总结消息（summarize）——不是全部保留，而是分级压缩

要点 5：记忆正在成为独立赛道——不再是框架的附属模块#

2026年的行业格局显示，记忆系统已经从 Agent 框架的一个功能模块，演化为独立的技术赛道：

产品	核心差异化
Mem0	上下文感知生成 + 相似记忆更新；开源Star最多；有图版本(Mem0-G)
Zep	自研图引擎Graphiti，时序知识图谱，时间感知，边失效机制
LETTA/MemGPT	虚拟内存分页思想，Agent自主管理记忆读写
MemOS	三类记忆（纯文本/激活/参数）可动态转换，统一MemCube抽象，LOCOMO SOTA
A-MEM	Zettelkasten卡片笔记法，动态建立连接，记忆演化
MIRIX	六模块记忆框架+Multi-Agent，粗检索→细检索分层

关键趋势信号：

精细化管理的”分而治之”：按场景、分类、形式分别优化，类似 Multi-Agent 的思路
多结构组合存储：向量 + 图 + 标签 + 全文的混合索引，弥补任何单一结构的不足
记忆作为可调度资源：MemOS 的愿景是记忆可跨平台、可协同进化、可全生命周期治理，未来可能产生价值并通过市场交换
记忆张量获亿元融资，商业前景获认可

分歧与讨论#

三层 vs 多层：Harness Memory 提出清晰的三层（工作/短期/长期），但学术综述按认知心理学分（工作/情景/语义），LangGraph按实现分（Checkpointer/Store），MemOS按载体分（文本/激活/参数）。不同分类维度各有道理，但工程落地时需要统一到一套命名空间——否则团队沟通成本很高。
遗忘机制的选择：艾宾浩斯曲线（MemoryBank）是学术化方案，时间有效性窗口（Zep）是工程化方案，策展器维护playbook（ACE）是治理化方案。三者分别对应”自然遗忘”、“结构化遗忘”、“人工介入遗忘”——在安全敏感场景下，策展器方案更可控，但也更重。
Agent自主管理记忆 vs 系统管理记忆：LETTA/MemGPT 让 Agent 自己决定何时读写记忆，Harness Memory 则主张由系统通过事件驱动机制管理。前者更”智能”但更不可控，后者更”确定”但可能错过 Agent 觉察到的微妙时机。实际工程中可能需要混合方案：系统管大部分确定性读写，Agent 在特定场景自主触发。
记忆系统的成本门槛：向量+图混合架构意味着需要同时维护向量数据库和图数据库，运维复杂度显著高于纯向量方案。对小团队和早期项目，先做三层架构的骨架，再逐步升级存储引擎可能比一步到位更务实。

与已学内容的联系#

昨天（2026-07-23）：Agent 架构演进

昨天学到 Context Engineering 管理”模型看到什么”，Memory 就是其核心实现——三层记忆架构是 Context Engineering 从”单次优化”升级为”持续管理”的具体落地
昨天学到 Harness 的设计哲学从防御到赋能，今天的”写入门控”和”策展器维护 playbook”正好是赋能式记忆治理的实践
昨天提到 Agent OS 五层架构中记忆是其中一层，今天的独立赛道趋势说明记忆已经超出”一层”的定位，正在成为 Agent 系统的独立基础设施

之前：LangGraph create_react_agent

AgentState.messages + add_messages reducer 就是最简形态的工作记忆
checkpointer 是短期记忆的实现（状态快照）
store 是长期记忆的实现（跨线程键值数据库）
今天的内容让这些实现细节有了理论框架的支撑

💡 思考题#

如果你给一个代码审查 Agent 设计记忆系统，你会把什么写入长期记忆？什么坚决不写？为什么？ ——这道题考验你对”写什么进记忆”这个设计决策的实际判断力。想想：代码风格偏好应该记吗？某次审查的具体 diff 应该记吗？审查中发现的模式性错误应该记吗？
“存错了比没存更危险”——在你的工作场景中，有没有遇到过”错误经验被反复引用导致越来越偏”的情况？Agent 的记忆错误传播和人类团队的”错误经验传承”有什么相似性？ ——这道题帮你把抽象的可靠性问题映射到日常经验。

🎯 行动项#

用 LangGraph 实现一个最小三层记忆 Demo：Checkpointer（短期）+ Store（长期）+ 消息总结策略（工作记忆压缩），跑一个跨 2 次会话的任务，观察 Agent 在第二次会话中是否能利用第一次的经验。这个 Demo 会把今天的理论变成可触摸的代码。
对比 Mem0 和 Zep 的架构差异：读两篇产品的官方文档，画出它们的存储结构和检索流程对比图。理解”向量+图混合”到底比纯向量好在哪——这个对比图后续学习 Skill 和 MCP 时还会用到。

参考文章#

[Harness Memory：AI Agent 长期记忆的三层架构与四个关键设计决策]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_2757b99f6ac279f42cc38c8eb3378cd07307200439519008，提供了三层架构定义、四个设计决策和”能力/稳定性/成长性”三位一体定位）
[智能体Agent记忆系统：分类、可靠性与未来前沿分析]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_bc9803f19d3c55f85cf0650328e15ab27307200439519008，提供了学术视角的分类体系和四大可靠性问题的详细方案）
[AI Agent 记忆系统：从短期到长期的技术架构与实践]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_83fdd87d4aa9ba6aca6d6777cb72d74e7307200439519008，提供了会话级/跨会话级划分、上下文工程策略和主流框架集成模式）
[让AI智能体拥有像人类的持久记忆：基于LangGraph的长短期记忆管理实践指南]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_11dc44a8739275964df271e7cbb690137307200439519008，提供了LangGraph Checkpointer/Store的具体实现和实战案例）
[Agentic AI 时代的记忆系统演进之路]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_0996edbf0269c07641131ffc1bdfa9e47307200439519008，提供了主流产品对比、技术演进趋势和独立赛道判断）

Agent 架构演进：从 Prompt 到 Graph 的工程化路径

Thu, 23 Jul 2026 00:00:00 GMT

2026-07-23 Agent 架构演进：从 Prompt 到 Graph 的工程化路径#

📅 学习日期：2026-07-23 | 📚 来源：AI Agent 知识库 | 📝 综合文章数：5 篇

为什么选这个主题#

这是学习笔记的第一篇，选 Agent 架构演进作为起点，因为它提供了整个知识库的核心概念坐标系——Prompt、Context、Harness、Loop、Graph 这些概念贯穿后续几乎所有文章。理解了这条演进主线，再学任何具体技术（Memory、Skill、Tool）都能找到它的位置。另外，你昨天刚读完一篇 LangGraph 的文章，今天这个主题正好从更高维度回答了”为什么要有 Graph”这个问题。

核心要点#

要点 1：模型是引擎，但引擎不是汽车——分层递进是不可回避的工程事实#

所有 5 篇文章都认同同一个起点：大模型是”裸 CPU”，它有语言理解和推理能力，但先天缺四大件——上下文窗口瓶颈（128K 物理上限）、注意力稀释（有效容量 ≠ 物理容量）、数据搬运谬误（搬数据易丢字段）、无状态（每次对话如新生）。

正因为这些先天约束，你不可能靠一层优化就把 Agent 做稳。5 篇文章描绘的演进路径是层叠递进的：

层级	核心问题	解决了什么	留下了什么瓶颈
Prompt Engineering	我该对模型说什么？	单次交互质量提升，活动效率+50%	指令遵从率随步骤骤降（10步<70%），无容错，上下文气球膨胀
Context Engineering	我该让模型看见什么？	Token消耗降60%+，30+步推理稳定	跨执行知识无法积累，系统无法自我改进
Harness Engineering	我该给Agent搭什么环境？	断点续传（15步失败→30秒恢复），进化闭环	单体Agent无法承载组织级复杂任务
Loop Engineering	我该设计什么循环让Agent自主跑？	任务自动触发/执行/验证/迭代	不能自设计循环、不能与其他Loop对话、不能质疑目标
Agent OS / Graph	认知与执行如何分离与编排？	五层架构成认知操作系统，治理闭环	元认知（知道自己不知道）仍在建设中

关键洞察：每一层因前一层的天花板而出现，又为下一层铺路。这不是”选哪个层次好”的问题，而是你不可能跳层——没有 Context 就没有 Harness，没有 Harness 就没有 Loop。

要点 2：验证比生成重要——这是贯穿所有层的不变要素#

第二篇文章（Prompt/Harness/Loop/Graph 到底在关注什么）提炼了三个不变要素：验证、分层、治理。其中验证是最核心的。

多篇文章从不同角度论证了这一点：

从 Prompt 到 Harness 的演进文中指出，五层修复管道曾占 ToolExecutor 50% 代码，但这恰恰说明早期设计过度防御，应该从”堵错误出口”转向”开正确入口”
Claude Code 的 TAOR 循环把 Orchestrator 设计得极其”愚蠢”（约50行核心代码），但配套了 23 项 bash 安全检查、五档信任光谱、Sub-Agent 隔离——验证机制才是稳定性的真正来源
Loop Engineering 文章明确说：“实现者和验证者必须分离”——Maker/Checker 分离是无人值守的保障

实践启示：设计 Agent 系统时，不是先想”怎么让模型输出正确”，而是先想”怎么让错误在结构上不发生”——这才是从防御范式到赋能范式的转变。

要点 3：智能下沉到模型，确定性留给框架#

Claude Code 的设计哲学提供了一个非常具体的工程示范：“Orchestrator 越笨，架构越稳定”。

这背后的逻辑是：

模型会越来越强（这是确定性趋势），硬编码的脚手架应该随时间变薄而非变厚
如果每次模型升级你都加更多脚手架，说明你在对抗模型而非利用模型
工具只提供四种能力原语（Read/Write/Execute/Connect），让模型自行组合
验证机制用确定性代码而非 LLM 自判——bashSecurity.ts 做 23 项静态检查，阈值判断用 execute_code 而非 LLM

WorkBuddy 的产品视角呼应了这一点：模型决定上限，上下文与 Harness 决定上限能否稳定落地。“模型够强，剩下交给提示词”是误区——即使模型天花板够高，没有 Harness 的引导、约束和反馈，输出仍不确定。

要点 4：人机边界的后退不是消失，而是角色升级#

所有文章都在描绘同一个趋势：人的参与点在不断后退，但从未消失。

具体演进：

Prompt 阶段：人手写每一步指令（操作者）
Harness 阶段：人设计运行环境（架构师）
Loop 阶段：人定义目标和验收标准（治理者）
Agent OS 阶段：人负责方向选择、标准定义、责任承担

WorkBuddy 文章特别强调了一个危险：“The danger is stopping having an opinion when loops run autonomously”——自主循环运行时，人容易停止思考和判断，这才是真正的风险。人不是被替代，而是从操作者升级为治理者。

要点 5：名词会继续变，但本质不变#

第二篇文章的结论简洁有力：验证、分层、治理——抓住这三个要素，不管下个月又出什么新名词都能看懂。

这和第一篇文章的演进分析看似矛盾（一个说各层递进、一个说本质不变），实则互补：演进描述的是”为什么需要每一层”，本质论描述的是”每一层在做什么”——都是在搭建验证机制、做关注点分离、推动人机边界后退。Loop、Graph 不是颠覆前一层，而是在前一层基础上加新的抽象维度。

分歧与讨论#

5 篇文章在几个关键点上存在张力：

“赋能范式” vs 实际仍大量防御：第一篇文章主张从”堵错误出口”转向”开正确入口”，但 Claude Code 的实践显示 23 项安全检查、五档信任光谱、Sub-Agent 隔离等机制仍然是典型的防御式设计。这说明”赋能”不是取消防御，而是让防御从运行时修补变成结构设计——错误在结构上不发生，而不是发生后再去修。
Loop vs Harness 的边界模糊：Claude Code 的 TAOR 循环既是 Harness（运行时外壳）也是 Loop（自主执行循环）。WorkBuddy 把两者分为不同层，但实际产品中它们的边界很难划清。这可能意味着未来不会严格分层，而是融合为一个整体运行时。
“智能下沉到模型”的前提条件：这个哲学成立的前提是模型确实在持续变强。但如果模型在某些领域天花板已现（如长程推理、复杂规划），那么”变薄脚手架”的策略就需要调整——不是对抗模型，而是承认模型在某些场景需要更多确定性支撑。

与已学内容的联系#

这是第一篇学习笔记，暂无历史主题可关联。但建立坐标系后，后续主题都能找到位置：

Memory（三层记忆架构） → 属于 Context/Harness 层的核心组件
Skill（技能协议/生命周期） → 属于 Harness 的能力层，Loop 的原语之一
Tool Calling（MCP/Function Calling） → 属于 Context 的工具注入，Harness 的确定性验证手段
LangGraph（Graph Engineering） → 属于 Loop/OS 层的编排抽象
多 Agent 协作 → 属于 Agent OS 层的 Ecosystem Engineering

💡 思考题#

如果你现在要做一个 Agent 产品（比如一个代码审查助手），你会从哪一层开始设计？为什么不能直接跳到 Loop？ —— 这道题考验你对”层叠递进不可跳层”的理解。
Claude Code 的”智能下沉到模型、确定性留给框架”哲学，在你的工作场景中是否成立？有没有模型目前做不到但你需要的功能，这时候脚手架应该变厚还是变薄？ —— 这道题考验你在具体场景下的判断力。

🎯 行动项#

画出你当前工作/项目中 Agent 技术栈的层次映射图：标注你目前在哪一层（Prompt？Context？Harness？），以及往上每一层你还缺什么。这张图会成为后续学习笔记的参照框架。
精读 Loop Engineering 的五原语设计：搜索知识库中关于 Automations/Scheduling、Skills、Sub-agents 的文章，逐个原语深入理解——它们是后续多篇笔记的基石概念。

参考文章#

[从 Prompt 到 Harness：企业级 Agent 工程的完整演进之路]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_382c1f737bf1581599bb0cd609466f987307200439519008，提供了完整的四阶段演进框架和 Agent OS 五层架构）
[从 Prompt、Harness、Loop 一直到 Graph，我们到底在关注什么]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_b05a9e78f4562219291be04e81db8c807307200439519008，提炼了验证/分层/治理三个不变要素）
[AI 工程演化：从 Prompt 到 Loop，未来的方向在哪里]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_8012592c3a27bd62ea6cd7050e0936a77307200439519008，给出了四层定义、五原语和三个未来方向）
[看看 Claude Code 怎么做 Harness，这才是 Agent 工程化的真正难点]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_0de4602d2eebfc597e0fd462432723817307200439519008，提供了具体产品案例和”智能下沉到模型”的设计哲学）
[从模型到Harness：WorkBuddy如何把Agent做成可用产品]（wechatarticle_8063fdd1b44b6b1cc34019dc46a067c0_9add9f05b74bd2313dab8558022ae1f67307200439519008，从产品视角拆解各层角色定位和人的角色变化）

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

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

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 创建各种复杂图表，包括流程图、时序图、ER 图、类图、状态图、XY 图、甘特图、思维导图等。

Mermaid 图表由 Merman 实现。Firefly 在 Astro 构建阶段生成亮色和深色两套静态 SVG，无需在浏览器中加载 Mermaid 渲染运行时。可以前往 Merman Playground 实时编辑语法并预览渲染结果。

流程图示例#

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

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

时序图示例#

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

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

ER 图示例#

ER 图（实体关系图）非常适合表示数据库结构。

writes

posts

has

belongs to

USER

int

string

username

string

datetime

created_at

ARTICLE

int

string

title

text

content

datetime

published

int

author_id

COMMENT

int

text

content

datetime

created_at

int

user_id

int

article_id

类图示例#

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

写作

发表

拥有

属于

User

+String username

+String password

+String email

+Boolean active

+login()

+logout()

+updateProfile()

Article

+String title

+String content

+Date publishDate

+Boolean published

+publish()

+edit()

+delete()

Comment

+String content

+Date commentDate

+addComment()

+deleteComment()

状态图示例#

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

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

XY 图示例#

XY 图表非常适合展示趋势和对比数据。

月度访问量趋势1月2月3月4月5月6月5000450040003500300025002000150010005000访问量

饼图示例#

饼图适合直观展示各部分在整体中的占比。

45%30%15%10%内容类型占比技术文章 [45]项目记录 [30]生活随笔 [15]其他 [10]

甘特图示例#

甘特图可以按时间轴展示项目阶段、任务依赖和当前进度。

07/0107/0307/0507/0707/0907/1107/1307/1507/17需求整理视觉设计功能实现内容迁移构建检查正式上线准备开发发布博客版本发布计划

思维导图示例#

思维导图适合梳理主题层级和知识结构。

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

时间线示例#

时间线用于按年份或阶段呈现项目的重要事件。

2024建立博客完成基础主题2025加入搜索与图库完善内容系统2026升级 Astro 7使用 Merman 渲染图表Firefly 演进时间线

用户旅程图示例#

用户旅程图能够描述用户在不同阶段的行为和体验评分。

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

Git 图示例#

Git 图可以清晰展示分支、提交和合并历史。

mainfeatureinitadd-diagramspolish-themesmerge-featurerelease

看板示例#

看板适合展示任务在不同工作阶段之间的分布。

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

Sankey 图示例#

Sankey 图通过连线宽度展示流量在不同节点之间的流向。

Home 1650Post list 1200Search 450Post detail 1220Related posts 260External shares 180

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了流程图、时序图、ER 图、类图、状态图、XY 图、饼图、甘特图、思维导图、时间线、用户旅程图、Git 图、看板和 Sankey 图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。图表会在构建时自动渲染为 SVG，无需客户端 JavaScript 加载。

可以前往 Merman Playground 尝试更多语法，再将图表代码粘贴到文章中。

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>