2026-07-31 15:45:50 +08:00

7.4 KiB

Raw Blame History

name, description

name	description
write-agent-blog	为 llm-to-agent 的《Agent进阶专题》系列创作中文文章。触发："为本次提交写篇文章""给这个功能写博客""记录这次实现"。不触发：修改 README、写代码注释、写 commit message。

创作 Agent 系列博客

为《Agent进阶专题》输出一篇 Hexo Markdown 文章到 /Users/liyanyan/study/hexo-blog/source/_posts/agent/。源码是唯一事实来源，只写已实现的行为。

必须（违反即错误）

工作流程

git rev-parse --show-toplevel 定位项目根目录。
用 git show / git diff 读取目标变更；读取 /Users/liyanyan/study/hexo-blog/source/_posts/agent/*.md 确定编号、术语、避免重复。
确定：阶段（P0/P1/P2）、阶段内序号、中文标题、英文 slug。
只在 /Users/liyanyan/study/hexo-blog/source/_posts/agent/ 新建一个 2026-PX-0X-slug.md，不覆盖已有文件。

文件名与元信息

2026-PX-0X-slug.md

PX = 路线图阶段，0X = 阶段内序号（01 起），slug = 小写 ASCII + 短横线。
如果无法判断阶段或序号，暂停询问用户。

---
title: 【Agent进阶专题】中文标题
tags: [AI, Agent]
categories:
- AI
date: YYYY-MM-DD HH:mm:ss
permalink: /YYYY/agent/slug/
---

date 用当前本地时间，适当加工避开工作时间，permalink的YYYY从date中提取。
标题具体、体现结果，不用"一些思考"等模糊标题。

事实约束

只写代码中已存在的行为。未实现的能力标注"计划中"，不写成已实现。
禁止虚构：调试经历、性能数据、设计争论、命令输出、用户反馈。
代码片段必须与仓库一致，附近标注仓库相对路径。
脚手架/配置类提交：解释目的和后续价值，不夸大现有能力。

文章结构

元信息
摘要（1-2 句）
<!-- more -->
正文

 恰好出现一次，前后各空一行。
摘要说明"做了什么、为什么有价值"。
正文标题从 ## 开始，不重复一级标题。

应该（尽量做到）

内容边界

标题就是边界。不讲无关协议、远期能力、实现细节。
导读/概念类 ~1000 中文字符；实现类按需，讲清即止。
2-4 个短章节即可，不为完整而堆章节。

Extension 实现类文章

默认按以下主线组织：

能力介绍 → 实现思路 → setup 行为 → start 行为 → stop 行为 → 抓手 → 下节引子

这是写作顺序，不是固定模板；根据源码实际行为扩展、合并或删除小节。
没有 start / stop 时直接省略，不创建空章节。
“能力介绍”说明当前插件解决什么问题、提供什么结果，以文字为主，不在这里罗列接口和方法。
“实现思路”说明数据模型、关键取舍和整体流程，以文字为主；路径、数据结构、内部方法等细节不要各自拆节。
代码尽量集中在 setup、start、stop 和“抓手”中。前两节只在没有代码就难以说清时放一段短示意。
“抓手”专门说明当前插件对外暴露的命名能力。先用“对外暴露一个名为 xxx 的能力，它的契约是 XxxService”点题，再展示契约并逐项解释其中的字段和方法。
不重复介绍所有插件通用的注册、获取和消费方式；除非某个插件的连接方式确有特殊之处，否则省略 context.add/get 等样板代码。
解释契约时只写当前文章已经建立的概念。某个字段或方法涉及后续主题时，只说明它现在提供的结果，不点名尚未介绍的插件，也不展开后续流程。
当前插件没有对外能力时，省略“抓手”，不要为了凑结构扩展概念。
下节引子只承接一个最自然的后续能力。

叙事方式

从读者能理解的场景切入，不假定读者读过前文。
"原本有什么 → 遇到什么问题 → 做出什么选择"推进。
读者已知的概念直接引用跳过，如"和 Express 中间件机制一致，略过"。
结尾自然引出下一篇的问题，不罗列阶段和术语。
首次出现 P0/P1 等编号时用自然语言解释。

文风

面向懂 TS 和基础 LLM、刚接触 Agent 工程的开发者。笔记体：结论先行，解释从简。

❌ "我们需要先回答一个不那么显眼、却会影响整个项目的问题"
✅ "先确定一件事：Kernel 不认业务概念。"
❌ "经过反复思考和持续调整，我们最终选择了一种简洁优雅的方案"
✅ "架构收缩为两个核心概念：Kernel + Extensions。"
每段一个重点，通常不超过三句话。
删除过渡句、重复总结、设问、修饰语。
可用"我们"，重心在技术推理。
不用营销语言、泛泛 AI 介绍、夸张结论。
不写散文，不用文学化铺垫。

格式

围栏代码块标注语言；标题/列表/代码块/ 前后空行。
代码尽量短，展示核心思路即可。省略处用 ... 且确保不会误解。
不自行添加目录。

避免

假设读者读过系列其他文章（"如前所述""大家已经知道"）。
提前讲完后续文章的主题。
把计划/路线图写成已实现的能力。
流水账式叙述或填充式总结。
为同一概念反复更换中文译名。

最终检查

只新增/修改了一篇 .md
文件名匹配 ^2026-P[0-9]+-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$
元信息字段完整， 恰好一次
无占位内容残留
代码与仓库一致
回复含文件链接 + 一句话主题说明

参考：本作者已上线系列的共性特征

以下从 Java 专题和 AI 基础专题中提取，是已被验证有效的写作习惯。

开头

一句话交代本篇做什么，不做铺垫：

"本篇简单记录常量和变量。"
"开始之前，我们需要搭建一个基本的项目环境，基于 TypeScript 和 Node.js，且尽量简洁。"

系列衔接

可引用前文建立上下文，但只提直接相关的一篇：

"上一节我们已经可以和大模型进行连续对话了，这节我们通过简单的例子来演示一下提示词管理的能力。"

代码呈现

实现类文章中，前两节以文字为主，代码集中到生命周期与“抓手”。
按生命周期或对外能力拆分代码块，每块配一行解释。
可在代码块之间穿插截图验证运行结果。

结尾

两种方式，按主题选择：

引出下一篇："到此，我们的项目环境就搭建完成了，下一节我们将进行一个简单的对话。"

发散点列表：列出 3-5 个后续可探索的方向，标注为"发散点"而非"计划"。

发散点：
* 上下文长度管理 - 监控上下文的长度，并在超过限制时进行裁剪。
* 持久化 - 将上下文保存到文件或者数据库中。

跨知识引用

读者已知的概念直接跳过，不重复解释：

"if 语句和 javascript 完全一致，略过。"
"和 Express 中间件机制一致，略过。"

语气

用"我们"但不煽情，重心始终在技术本身。
笔记语气：记录过程、防止遗忘，不假装客观权威。
无占位内容残留
代码与仓库一致
回复含文件链接 + 一句话主题说明

7.4 KiB Raw Blame History Unescape Escape