195 lines
7.4 KiB
Markdown
195 lines
7.4 KiB
Markdown
---
|
||
name: write-agent-blog
|
||
description: 为 llm-to-agent 的《Agent进阶专题》系列创作中文文章。触发："为本次提交写篇文章""给这个功能写博客""记录这次实现"。不触发：修改 README、写代码注释、写 commit message。
|
||
---
|
||
|
||
# 创作 Agent 系列博客
|
||
|
||
为《Agent进阶专题》输出一篇 Hexo Markdown 文章到 `/Users/liyanyan/study/hexo-blog/source/_posts/agent/`。**源码是唯一事实来源，只写已实现的行为。**
|
||
|
||
---
|
||
|
||
## 必须（违反即错误）
|
||
|
||
### 工作流程
|
||
|
||
1. `git rev-parse --show-toplevel` 定位项目根目录。
|
||
2. 用 `git show` / `git diff` 读取目标变更；读取 `/Users/liyanyan/study/hexo-blog/source/_posts/agent/*.md` 确定编号、术语、避免重复。
|
||
3. 确定：阶段（P0/P1/P2）、阶段内序号、中文标题、英文 slug。
|
||
4. 只在 `/Users/liyanyan/study/hexo-blog/source/_posts/agent/` 新建一个 `2026-PX-0X-slug.md`，不覆盖已有文件。
|
||
|
||
### 文件名与元信息
|
||
|
||
```
|
||
2026-PX-0X-slug.md
|
||
```
|
||
|
||
- `PX` = 路线图阶段，`0X` = 阶段内序号（01 起），`slug` = 小写 ASCII + 短横线。
|
||
- 如果无法判断阶段或序号，暂停询问用户。
|
||
|
||
```yaml
|
||
---
|
||
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 -->
|
||
正文
|
||
```
|
||
|
||
- `<!-- more -->` 恰好出现一次，前后各空一行。
|
||
- 摘要说明"做了什么、为什么有价值"。
|
||
- 正文标题从 `##` 开始，不重复一级标题。
|
||
|
||
---
|
||
|
||
## 应该（尽量做到）
|
||
|
||
### 内容边界
|
||
|
||
- 标题就是边界。不讲无关协议、远期能力、实现细节。
|
||
- 导读/概念类 ~1000 中文字符；实现类按需，讲清即止。
|
||
- 2-4 个短章节即可，不为完整而堆章节。
|
||
|
||
### Extension 实现类文章
|
||
|
||
默认按以下主线组织：
|
||
|
||
```text
|
||
能力介绍 → 实现思路 → setup 行为 → start 行为 → stop 行为 → 抓手 → 下节引子
|
||
```
|
||
|
||
- 这是写作顺序，不是固定模板；根据源码实际行为扩展、合并或删除小节。
|
||
- 没有 `start` / `stop` 时直接省略，不创建空章节。
|
||
- “能力介绍”说明当前插件解决什么问题、提供什么结果，以文字为主，不在这里罗列接口和方法。
|
||
- “实现思路”说明数据模型、关键取舍和整体流程，以文字为主；路径、数据结构、内部方法等细节不要各自拆节。
|
||
- 代码尽量集中在 `setup`、`start`、`stop` 和“抓手”中。前两节只在没有代码就难以说清时放一段短示意。
|
||
- “抓手”专门说明当前插件**对外暴露**的命名能力。先用“对外暴露一个名为 `xxx` 的能力，它的契约是 `XxxService`”点题，再展示契约并逐项解释其中的字段和方法。
|
||
- 不重复介绍所有插件通用的注册、获取和消费方式；除非某个插件的连接方式确有特殊之处，否则省略 `context.add/get` 等样板代码。
|
||
- 解释契约时只写当前文章已经建立的概念。某个字段或方法涉及后续主题时，只说明它现在提供的结果，不点名尚未介绍的插件，也不展开后续流程。
|
||
- 当前插件没有对外能力时，省略“抓手”，不要为了凑结构扩展概念。
|
||
- 下节引子只承接一个最自然的后续能力。
|
||
|
||
### 叙事方式
|
||
|
||
- 从读者能理解的场景切入，不假定读者读过前文。
|
||
- "原本有什么 → 遇到什么问题 → 做出什么选择"推进。
|
||
- 读者已知的概念直接引用跳过，如"和 Express 中间件机制一致，略过"。
|
||
- 结尾自然引出下一篇的问题，不罗列阶段和术语。
|
||
- 首次出现 P0/P1 等编号时用自然语言解释。
|
||
|
||
### 文风
|
||
|
||
面向懂 TS 和基础 LLM、刚接触 Agent 工程的开发者。**笔记体**：结论先行，解释从简。
|
||
|
||
- ❌ "我们需要先回答一个不那么显眼、却会影响整个项目的问题"
|
||
- ✅ "先确定一件事：Kernel 不认业务概念。"
|
||
|
||
- ❌ "经过反复思考和持续调整，我们最终选择了一种简洁优雅的方案"
|
||
- ✅ "架构收缩为两个核心概念：Kernel + Extensions。"
|
||
|
||
- 每段一个重点，通常不超过三句话。
|
||
- 删除过渡句、重复总结、设问、修饰语。
|
||
- 可用"我们"，重心在技术推理。
|
||
- 不用营销语言、泛泛 AI 介绍、夸张结论。
|
||
- 不写散文，不用文学化铺垫。
|
||
|
||
### 格式
|
||
|
||
- 围栏代码块标注语言；标题/列表/代码块/`<!-- more -->` 前后空行。
|
||
- 代码尽量短，展示核心思路即可。省略处用 `...` 且确保不会误解。
|
||
- 不自行添加目录。
|
||
|
||
---
|
||
|
||
## 避免
|
||
|
||
- 假设读者读过系列其他文章（"如前所述""大家已经知道"）。
|
||
- 提前讲完后续文章的主题。
|
||
- 把计划/路线图写成已实现的能力。
|
||
- 流水账式叙述或填充式总结。
|
||
- 为同一概念反复更换中文译名。
|
||
|
||
---
|
||
|
||
## 最终检查
|
||
|
||
- [ ] 只新增/修改了一篇 `.md`
|
||
- [ ] 文件名匹配 `^2026-P[0-9]+-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$`
|
||
- [ ] 元信息字段完整，`<!-- more -->` 恰好一次
|
||
- [ ] 无占位内容残留
|
||
- [ ] 代码与仓库一致
|
||
- [ ] 回复含文件链接 + 一句话主题说明
|
||
|
||
---
|
||
|
||
## 参考：本作者已上线系列的共性特征
|
||
|
||
以下从 Java 专题和 AI 基础专题中提取，是已被验证有效的写作习惯。
|
||
|
||
### 开头
|
||
|
||
一句话交代本篇做什么，不做铺垫：
|
||
|
||
- "本篇简单记录常量和变量。"
|
||
- "开始之前，我们需要搭建一个基本的项目环境，基于 TypeScript 和 Node.js，且尽量简洁。"
|
||
|
||
### 系列衔接
|
||
|
||
可引用前文建立上下文，但只提直接相关的一篇：
|
||
|
||
- "上一节我们已经可以和大模型进行连续对话了，这节我们通过简单的例子来演示一下提示词管理的能力。"
|
||
|
||
### 代码呈现
|
||
|
||
- 实现类文章中，前两节以文字为主，代码集中到生命周期与“抓手”。
|
||
- 按生命周期或对外能力拆分代码块，每块配一行解释。
|
||
- 可在代码块之间穿插截图验证运行结果。
|
||
|
||
### 结尾
|
||
|
||
两种方式，按主题选择：
|
||
|
||
- **引出下一篇**："到此，我们的项目环境就搭建完成了，下一节我们将进行一个简单的对话。"
|
||
- **发散点列表**：列出 3-5 个后续可探索的方向，标注为"发散点"而非"计划"。
|
||
```md
|
||
发散点：
|
||
* 上下文长度管理 - 监控上下文的长度，并在超过限制时进行裁剪。
|
||
* 持久化 - 将上下文保存到文件或者数据库中。
|
||
```
|
||
|
||
### 跨知识引用
|
||
|
||
读者已知的概念直接跳过，不重复解释：
|
||
|
||
- "`if` 语句和 `javascript` 完全一致，略过。"
|
||
- "和 Express 中间件机制一致，略过。"
|
||
|
||
### 语气
|
||
|
||
- 用"我们"但不煽情，重心始终在技术本身。
|
||
- 笔记语气：记录过程、防止遗忘，不假装客观权威。
|
||
- [ ] 无占位内容残留
|
||
- [ ] 代码与仓库一致
|
||
- [ ] 回复含文件链接 + 一句话主题说明
|