blog

Imported from oreoft/blog (AGENTS.md). Install upstream with npx skills add oreoft/blog. Copyright stays with the author.

AGENTS.md

这是一个 Jekyll 个人博客（https://www.someget.cn ）。这份文件写给在这个仓库里干活的 AI 助手：怎么写、怎么改、什么不要碰。规则不多，但每一条都是改稿改出来的，新 session 先读完再动手。

一、三条硬规则

1. 只有 main，直接在 main 上改，不要新建分支。 改完停在工作区，不要自己 commit，不要 push。作者看过之后，认可就自己提交，不认可就直接丢掉。只有作者明确说"提交"时才 commit；commit message 沿用 feat: / style: / fix: 前缀。
2. 不要翻译，不要碰 en/ 目录。 push 到 main 后，GitHub Actions（.github/workflows/auto-translate.yml）会自动把 _posts/<年份>/ 和 zh/ 下变动的中文文件翻译成英文，写到 en/_posts/ 和 en/，然后自动提交。手写英文版只会被覆盖。commit message 带 --all 会触发全量补翻，带 [skip ci] 会跳过翻译，一般都不需要。
3. 说人话。 文章是写给同行和以后的自己看的，像当面把一件事讲清楚那样写。具体见第三节。

二、项目约定

目录与命名

• 文章放在 _posts/<年份>/，文件名 YYYY-MM-DD-<英文-slug>.md，slug 小写加连字符，例如 2026-09-05-redis-cluster-address-remap-moved-storm.md。

• _posts/待完成/、_posts/存档/ 和 _posts/ 根目录下那些没有日期前缀的零散文件，是作者的未完成草稿。Jekyll 不发布，翻译脚本也跳过。不要动，也不要拿去当风格参考。

• _drafts/template.md 已经过时（没有 lang，代码块用 ~~~），新文章照最近的文章写，不要照抄模板。

• 图片都在作者自己的图床（mypicgogo.oss-cn-hangzhou.aliyuncs.com），助手拿不到。写作时用占位符留位置，作者 review 时自己替换，不要编造图片 URL：

  <center>（配图占位：一句话说明这张图该展示什么）</center><br>
  

  作者自己配好的图，下面是一行 <center>一句话说明</center><br> 作图注。

• 本地预览用 bundle exec jekyll serve（见 README）。改文章一般不需要起服务。

front matter

---
layout: post
title: 一句话说清楚这篇讲了什么
excerpt: 两三句话。交代这篇讲什么、为什么值得看。
category: middleware
keywords: redis, valkey, redis-py, cluster, 生产事故, 排查
lang: zh
---

• lang: zh 必须写。翻译脚本只处理 lang 为 zh 或缺省的文件，翻译后会自动改成 en。
• category 是单个小写 slug，会进 URL。现有的：middleware（数据库、缓存、消息队列、线上排查）、cloud（AWS / GCP、网络、跳板机）、 linux、tools（IDE、抓包、效率工具、自己写的插件）、java、spring_boot、cc（计算机基础）、ds（算法）、cn（网络）、other （硬件折腾、心得、产品体验，什么都放）。
• keywords 逗号分隔，英文技术词为主，可以夹几个中文标签。

站内链接

permalink 是 /:category/:year/:month/:day/:title.html，:title 是文件名去掉日期的部分。引用另一篇文章时 category 段不能漏：

[redis 加了个分片，把线上写挂了一个多小时](/middleware/2026/09/03/redis-cluster-resharding-client-stuck.html)

系列文章在前言第一句就把上一篇链上。

脱敏

文章是公开的。写进去之前把这些换掉：

• 公司名、产品名、服务和仓库的真名：按职能叫，推荐服务、API 服务、事件消费服务、数据库、跳板机。
• 内网 IP、域名、endpoint：10.0.0.1、10.0.0.2、节点A / 节点B、xxxxxx.cache.amazonaws.com。
• PR 号、issue 号、commit hash、同事名字：不写。
• 带业务前缀的环境变量名、配置 key：改成通用名，或者只描述它的作用。
• 任何密钥、token、账号：不写。

库和框架自己的名字（redis-py、address_remap、ElastiCache）可以写，那是公开知识。作者自己开源的项目（github.com/oreoft/...）也可以写。

三、写作风格

通用：所有文章都适用

核心一句话：第一人称，平实，把事情讲清楚。 读者是同行，不需要被吸引，需要被讲明白。

• 像当面给同事讲。可以有情绪，但要克制："这就对不上了"、"我就寻思"、"干脆自己写一个得了"，到此为止。不哗众取宠，不自嘲出丑，不煽情，不说教。

标题和摘要一句话说清楚这篇讲什么。技术文章不用夸张比喻和营销腔（触目惊心、打脸、压死、钉死、终极方案这一类）。工具和心得类可以活泼一点，作者自己用过" 爷青结"、"神器"这种标题，但正文还是要讲为什么和怎么做，不堆形容词。

• 一个名词第一次出现，用一句话说它是什么，或者直接描述它做了什么。宁可多写半句，也不要甩一个没解释的词。（例：不说"猴子补丁" ，说"在运行时把客户端的某个方法换成自己的版本"。）
• 中文为主，技术名词、命令、参数、错误信息保留原文并加反引号。
• 开头固定 ## 前言：交代背景和这篇要讲什么，读者看完前言就该知道要不要往下读。结尾一节叫 ## 总结（收结论）或 ## 后言 （说感想、后续打算，语气更随意），有参考资料再加一节 ## 参考。
• 中间的节用 ## 一、…、## 二、…（中文数字加顿号）或者直接用描述性短句做标题，例如"先搞清楚是哪些机器在连"、"Token 这块，绕了一个小弯路"。不用"分析"、"排查"、"正文"这种空标题。需要再分层用 ### 1. 或 ### 短句。
• 粗体只加在关键结论和定义上，不要满篇都是。不用 emoji，表格里也不用。
• 代码块用三个反引号并标语言；日志和输出裁到只剩看得懂的那几行。

不替作者表达作者没有的想法。不知道作者当时怎么想的，就只写发生了什么。（例：作者从来没觉得那是两个独立的问题，稿子里就不能写" 我一开始也以为是两个问题"。）

• 能删的删。说得太多，别人反而不会重视。

类型一：事故排查 / case study

标题多是"一次 xx 的排查"、"xx 把线上写挂了 xx"。category 一般是 middleware。样本：

• _posts/2026/2026-08-22-event-loop-frozen-by-sync-call-cascade.md：作者自己写的，风格基准。
• _posts/2026/2026-09-05-redis-cluster-address-remap-moved-storm.md：助手起草、作者改了五轮之后的定稿。

要求：

• 前言写清楚现象、影响面、一段话预告结论。系列文章第一句链上一篇。
• 正文按排查的实际顺序写。每一个假设都按 怀疑 → 验证 → 对不上 → 排除 走，这是作者最看重的一条：
  1. 为什么怀疑它：先把假设说成一个能闭环的结论，"如果是 X，那么应该能看到 Y"。
  2. 去验证：拿什么证据去验的，具体做了什么。
  3. 对不上：证据和预期哪里不一致。
  4. 排除：一句话收掉，进下一个假设。 不写"事后看这显然不对"，当时就是那么想的，如实写。最后真正的原因也用同样的方式验证，而不是"于是我发现了"。
• 只留支撑论点的数字，每个数字都要说明它证明了什么。不为了显得严谨堆数据。
• 和主线无关的插曲（比如排查途中把跳板机跑挂了）不写。
• 倒数第二节写复盘：具体做了哪些改动、以后怎么避免，写做法不写感悟金句。最后一节 ## 总结，一段话说清楚就停，不留故弄玄虚的尾巴。
• 篇幅两万字以内。

类型二：工具与教程

装软件、配环境、连内网、IDE 技巧这一类。category 多是 tools、linux、cloud。样本： _posts/2026/2026-08-21-connect-aws-gcp-redis-via-gui.md、_posts/2021/2021-04-16-charles01_install.md。

• 先用一到两节讲为什么：现在的做法哪里难受、为什么不能走更直接的路（例如"为什么云厂商不给 Redis 开公网" ）。读者理解了背景，后面的步骤才记得住。
• 然后讲怎么做：步骤用有序列表，命令块可以直接复制运行，实例 ID、域名这类值用明显的占位（i-0123456789abcdef0、xxxxxx）。
• 每个关键步骤配一张截图占位。
• 环境限制、免责声明写在前言末尾，一句话带过（"p.s. 操作环境是 macOS，Windows 差不多"）。
• 结尾说配完之后体验变成什么样，哪些功能没展开、为什么。
• 语气可以轻松，但每一步都要能照着做出来，不要省略"这一步为什么要做"。

类型三：自己做的东西

插件、小工具、开源项目的介绍。category 是 tools。样本：_posts/2026/2026-07-30-idea-github-actions-plugin.md、 _posts/2026/2026-07-30-restful-controller-idea-plugin.md。

• 前言从痛点开始：哪个操作重复得太多次、现有方案（官方的、市面上的）各差在哪，所以自己写一个。
• 正文写设计取舍和绕过的弯路，不是功能清单："往人家面板里插东西靠不靠谱"、"Token 一开始想让用户自己填，后来发现能复用 IDE 已登录的账号"。读者看的是你怎么想的。
• 功能展示一节，每个功能一张图加一句图注，图注就是描述性的一句话。
• 开发过程如实写，包括哪些是和 AI 一起做的、AI 哪里帮到了、哪里还得自己翻源码。
• ## 后言 放仓库链接、上架情况、后续打算，落脚在"一个小痛点顺手解决了"，不拔高。

类型四：原理梳理 / 知识笔记

重新理解某个概念，例如事务隔离级别、Java 内存模型、TCP。category 多是 middleware、java、cc、cn。样本： _posts/2026/2026-07-08-Isolation-levels-for-mysql-and-postgre.md。

• 前言由一个实际遇到的问题引出（"最近遇到一个死锁"、"从 MySQL 切到 PG"），不要从定义开始背。
• 先分清最容易混的两三个概念，再往下展开。对比用表格，表格只放事实。
• 每一节落到一个可以加粗的结论，例如"读已提交不等于当前读"。
• 敢于说教材和八股里哪条其实没那么重要，但要给依据（历史来源、实现差异、实际业务影响）。
• ## 后言 写这次重新理解之后自己的看法和适用边界。有出处的放 ## 参考。

类型五：体验与心得

产品体验、硬件折腾、职业感悟、面试记录、编码习惯这一类。category 多是 other。样本：_posts/2026/2026-01-01-stickerbox.md、 _posts/2021/2021-02-04-reflection_1.md、_posts/2021/2021-08-04-redis_case01.md。

• 这是最主观的一类，允许观点和情绪，但每个观点都要有理由：为什么觉得这个产品结合得好、为什么这个命名方式更好。
• 产品和硬件类按时间线分节（开箱、设置、使用体验），图多、每张图一句图注；价格、缺点、等待时间照实写，不写成软文。
• 感悟类按观点分节，一个观点一节；用自己的经历举例，不引用名人名言。
• 面试和讨论类先把题目原样列出来（引用块），再写自己的思路、当时答的和后来想到的。
• 结尾可以留余地（"现在的认知可能有失偏颇"），但要先给出自己此刻的判断。

四、和作者协作的方式

• 动笔前先判断这篇属于上面哪一类，读一遍对应的样本再写。类型不清楚就问。
• 作者给出草稿让你修改时，只在原稿基础上做最小改动，不重写，不加内容。
• 作者的反馈是逐条的：只改被指出的地方，不顺手改别处。
• 不主动回头改旧文章，除非作者要求做风格 review。
• 改完按文件列出改了什么，一两句一条，不贴大段 diff。