一盏时暗时亮的灯

开始

Tue, 10 Nov 2026 16:00:00 GMT

开始

很久以前，我在深夜刷到一个人的博客

页面很素，白底黑字，侧边栏一列日期，往前翻能翻到七八年前。他写买的第一台相机，写搬家时弄丢的一箱书，写某年冬天骑车摔了一跤。没什么金句，也没配图。我却一页一页往下看，看到两点多。

那天晚上我起了个念头：我也要弄一个。

接下来几天，我搜”如何搭建个人博客”，把 Hexo、WordPress、域名、备案、图床这些词抄进备忘录。收藏夹里存了十几篇教程，有几篇的标题我现在还能想起来。然后…，收藏夹就再没打开过。

我知道，那是懒

后来每隔一两年，这个念头会回来一次。我重新搜一遍教程，发现工具全换了，又得从头学，于是又放下。这样反复了几回，我差不多认了：这事我大概做不成。

大学期间很迷惘，每天总在刷手机，刷完什么都记不住。有一天我突然想，我这一天到底做了什么、想了什么，好像一点痕迹都没有。这个念头比”做博客”更具体，也更让我不舒服。

于是又想起那个白底黑字的页面。

很多事卡在“准备充足”这一关。总想等万事俱备，等思路清晰，等没有疏漏，最后直接原地停下。

所以有了你现在看到的这一页。样式还很简陋，栏目也是空的。我不确定这里以后会写什么。大概会是些很具体的东西：一个表格公式怎么算日销，养的大肥鱼为什么快死了，键盘换轴之后手感的差别，这个月的账怎么又超了。也可能写些不成形的东西：某天下班路上想不通的一件事，或者一句让我记了很久的话。

这一次我换了做法。不再先研究怎么搭，而是先把第一篇写出来，随便找个地方放着。用哪个框架、买不买域名、要不要备案，全都往后排。

我不敢承诺多久更新一次。过去那些年我承诺过太多次，都落空了。这次只保证一件事：先把它开起来，然后写第二篇。

这篇算不上什么作品，只是打破停滞的第一步。往后会在这里记下零碎的思考、踩过的故障、算过的数据，那些没人在意的细碎小事。想到什么就写什么

昨晚看一部剧，我很喜欢

《伪人降临，我是全场唯一预言家》

看到凌晨三点

然后早上睡过头了

今天居然是双11吗

2022年的下雨天

Sun, 08 Nov 2026 16:00:00 GMT

2022年6月，新一卷数学，考完的那个下午是阴天。

云压得很低，光从云缝里漏下来是灰白色的，远处楼顶的轮廓看不清。我不讨厌晴天，只是对这种朦胧的阴天有种另类的偏爱——什么都模模糊糊，边界不清，人也就不用被太阳照得太清楚。

铃响，卷子从桌角被抽走。走出考场的时候走廊上全是人，都在说话，声音嗡嗡地压在头顶，我一句也没听进去。

那张卷子对我来说，挺难的，真的很难。我的考场有一位女生在抽泣，还有一个男生在捶胸。外面蒙蒙细雨，我们就这样坐上校车返校准备下一场，

打饭的时候遇到一位朋友，她笑，我也跟着笑，她懂，我也懂；相顾无言。

那是一种难以言喻的悲伤。更多的，是对自己实力不足感到的悲哀。前者是会过去的，后者不会。

第三天上午，最后一科，地理。我对地理一直不擅长。进场之前我在走廊上翻了两页笔记，翻完自己也知道没什么用。干脆不看了，我向来都这样，这是坏事吗？我现在也不懂。

卷子发下来，我很早就做完了，我并不擅长地理还剩十五分钟的时候

我把笔放下，抬头望向窗外

窗外是普师的广场，一棵树的影子斜斜地铺在地上。上午的天光是那种不刺眼的亮，走廊里偶尔有监考老师的脚步声过去，鞋底在瓷砖上拖得很短。别的考场还在答题，翻卷子的声音隔着墙都听不见，安静得很不真实。

就是在那十五分钟里，脑子里浮出来一句话：

人总是为了扮演各种各样的社会角色而生存。

学生、孩子、同学、某个人的朋友、某个班级里排在某一名的那个名字。一路走过来，好像每一步都有人替你安排好了这个角色该做什么。而现在这个角色马上就要演完了，下一场戏已经在后台等着。我又想，高考之后再无真正的宁静。

这句话当时想得很重。十八岁的人说这种话，其实说得太早了，现在看甚至有点自怜。但那十五分钟的安静是真的——不是因为题目写完了，是因为在那十五分钟里，没有任何人要求我做任何事。不能提前交卷，不能走，不能想下一场考试，只能坐着，看着窗外那棵树。那是我少有的、出乎意料的、真正属于我自己的时间。

铃响，起立，收卷。地理结束，高中结束。

十二点多，我们从考场出来。因为选的是物化地，这一科考完，所有考场就都结束了，我是最早离校的一批。

宿舍楼下的行李早就收好了，两个包，三年的东西就这么点。教室里还剩几个同批的人，桌子已经被清空，椅子腿在水泥地上刮出声音。我在靠窗的位置坐下来，从书包里摸出手机。屏幕亮起来，桌面还是考前换的那张图。指尖悬在上面，翻了两下相册，又退出来，锁屏，再亮起来。一时间居然不知道该干什么。

没有想象里的解脱，脑子里只有一句话，来来回回地响：高中结束了，真的结束了。

我说不出来那是什么感觉。身体里像有一块地方被轻轻挖走了，不疼，但是空。那一刻我隐约预感到，以后的某个瞬间我会想起这段时光——当时那只是一个预感，没想到它准得有点过分。

离校了。带着不多的行李走在街上。

学校附近这一带有点偏僻，路上没什么车。我站在树荫边上等，看屏幕上那个小车图标在远处兜圈子，兜了很久才朝这边挪。

天阴着，不晒，风里有点潮。我不着急，那时候觉得时间还很多，多到可以随便浪费。

车来了，司机问去哪，我说万泰汇。他哦了一声，没再说别的。五去万泰汇吃了自助餐。

不好吃。烤肉盘上的油一直在响，我拿了一堆，最后剩了半盘。饮料太甜，冰块化得很快，杯壁上全挂着水珠。店里有冷气，人很少，桌子和桌子挨得很近，隔壁那桌在聊假期要去哪。

吃的时候我想起2021年同段时间，我也在这里。

那天浑身湿透了。我记得衣服贴在背上的重量，记得坐下来的时候水顺着裤脚滴到地上。但我并不气馁——那时候我以为只要肯用力，什么都能追上。

这一次衣服是干的，人也坐得很稳。可心里有一团雾雾的东西，说不清，比一年前那场雨更让我难受。

吃烤肉的时候，我发了一条朋友圈：我一个旧时代的人，新时代没有能承载我的船了。

发出去了，我随便发的。好吧其实不随便

我站在原地看着一堆没被定义的东西，不知道该怎么量自己。

吃完继续在街上闲逛。那时候的精力真好，走了很久也不觉得累。商场、街口、便利店、亮着灯的药房，我一间间走过去，什么也没买。现在出门能不带包就不带，走两公里就想找个地方坐下。

天慢慢暗下来，路灯是一盏一盏亮的，不是同时亮。

我在一家便利店门口站了一会儿。玻璃上贴着夏季促销的海报，边角已经卷起来。店员在柜台后面刷手机，抬头看了我一眼，又低下去。我拿了瓶水，走出来才想起来自己其实不渴。

那时候我还没有”要回家”这个概念。学校不用去了，家在那里，但今天回不回，好像也没有人真的在意。

我站在路口，看着马路上来来往往的车辆。

有那么一瞬间，我处于第三视角。好像从身体里退出半步，站在旁边看着那个站在路口的人：穿着短袖，背一个包，手里捏着手机，不知道要去哪里。

我很想用文字把那个瞬间表达出来。可我讲不出，说不清。

我只知道那是一种悬浮感，一种和自己错开的感觉。像隔着一层毛玻璃看自己，看得见轮廓，摸不到温度。

这件事在之后几年反复回来找我：有些感受我能清清楚楚地感觉到，却没法转述给别人，甚至没法转述给自己。文字在那里是失效的。大概也是从那时候起，我开始想写点东西。不是为了写给谁看，是想给自己找一条把雾说清楚的通道。

回到家已经十点。还是第一次那么晚到家。

楼道里灯是声控的，我走上去，它亮一下，又灭。

我放下包，坐在那不想动。心里还是想出去，但我不知道去哪。这个念头很奇怪：人已经到家了，身体却还想往外走。

后来我站到窗边看楼下。路上的车少了，路灯亮着，树影铺在地上。或许没有目的地，才是最好的。那天我确实是这么想的，而且这句话在之后的很多年里一直没有失效。

夜里躺在床上，外边空调外机的声音一阵一阵。手机翻到很晚，也没翻出什么。以前这个点我应该在做卷子，或者在看第二天的安排。现在我没有任何要准备的东西。这种没有准备的状态，比准备本身更让人睡不着。

几年过去了。我确实在某个瞬间想起了那一天，不止一次。那天没有给我的生活一个答案。它只是停在那里，像那个阴天，边界不清。

我现在能把它写下来了。虽然文采还是有限，雾也还是没有完全散。至于船的事，后来我想明白一点：那艘船可能本来就不存在，也没有谁答应过要给我。没有船也可以走，只是慢一点，湿一点。

那句”高考之后再无真正的宁静”，我现在也不完全认了。后来确实有过很吵的日子，也确实有过很静的时刻。宁静不是一考完就被收走的，它只是换了地方，换了一种更难找到的形式。

我还是喜欢那个下午的阴天。天色一暗，世界就模糊一点，人也就没那么容易被看清。

GameApp-Ahk

Fri, 06 Nov 2026 16:00:00 GMT

酒窝宏管理工具 · 源码解析文档

默认键位一览

变量	功能	默认值
`DriftKey`	漂移键	`q`
`NitroKey`	氮气键	`e`
`BoostKey`	小喷键	`Up`
`ForwardKey`	前进键	`w`
`Hotkey_BaoLi`	暴力出弯	`PgDn`
`Hotkey_WuHen`	无痕三喷	`Ctrl`
`Hotkey_Cut`	快速切断	`Enter`
`Hotkey_KaQi1`	一段连卡	`Left`
`Hotkey_KaQi2`	二段连卡	`Down`
`Hotkey_LianKa`	三四五连卡	`Right`
`Hotkey_F1`	总开关	`F1`
`Hotkey_F2`	隐藏窗口	`F2`
`Hotkey_F3`	重置	`F3`
`Hotkey_F10`	快速切断（单键启停）	`F10`
`Hotkey_F11`	三四五连卡（单键启停）	`F11`
`Hotkey_F12`	暴力出弯（单键启停）	`F12`

默认延迟参数（ms）

参数	含义	默认值
`CutHoldTime`	快速切断 · 按住	22
`CutInterval`	快速切断 · 间隔	22
`KaQi1HoldTime`	一段连卡 · 按住	22
`KaQi1MinTotal`	一段连卡 · 保底总时长	25
`KaQi2FirstHold`	二段连卡 · 一段按住	22
`KaQi2WaitTime`	二段连卡 · 两段之间等待	618
`KaQi2SecondHold`	二段连卡 · 二段按住	22
`LianKaFirstHold`	三四五连卡 · 首按	22
`LianKaWaitTime`	三四五连卡 · 间隔	618
`LianKaSecondHold`	三四五连卡 · 连按	22
`LianKaCount`	连卡数量（3/4/5）	4
`LianKaMode`	连卡模式（1=A 先漂移 / 2=B 首段带小喷）	1
`BaoLiVersion`	暴力版本（珊瑚 / 酒窝）	珊瑚
`BaoLiHoldTime`	酒窝暴力 · 按住时长（50–500）	300

一、头部指令与权限检查

脚本编译版本声明、全局选项、发送模式、延迟设置，以及管理员权限校验与高精度计时器频率获取。

; <COMPILER: v1.1.37.02>
#NoEnv
#SingleInstance, Force
#Persistent
#InstallKeybdHook
#InstallMouseHook
#KeyHistory, 0
#MaxHotkeysPerInterval, 1000000
SendMode, Input
ListLines, Off
SetBatchLines, -1
SetKeyDelay, -1, -1
SetMouseDelay, -1
SetControlDelay, -1
SetWinDelay, -1
if not A_IsAdmin {
  MsgBox, 16, 权限错误, 请右键以管理员身份运行本脚本！`n否则无法正常使用功能。
  ExitApp
}
Global Frequency := 0
if (!DllCall("QueryPerformanceFrequency", "Int64*", Frequency)) {
  MsgBox, 48, Error, Failed to get high precision timer frequency!
  ExitApp
}

二、默认键位与运行状态变量

四大驾驶键位、六大功能热键、各功能启停状态、各段延迟参数、连卡数量/模式与暴力版本等默认值。

DriftKey := "q"
NitroKey := "e"
BoostKey := "Up"
ForwardKey := "w"
Hotkey_BaoLi := "PgDn"
Hotkey_WuHen := "Ctrl"
Hotkey_Cut := "Enter"
Hotkey_KaQi1 := "Left"
Hotkey_KaQi2 := "Down"
Hotkey_LianKa := "Right"
Hotkey_F1 := "F1"
Hotkey_F2 := "F2"
Hotkey_F3 := "F3"
Hotkey_F10 := "F10"
Hotkey_F11 := "F11"
Hotkey_F12 := "F12"
baoLiOn := false
wuHenOn := false
spaceCut := false
kaQi1On := false
kaQi2On := false
lianKaOn := false
Global BaoLiRunning := false
Global LianKaRunning := false
CutHoldTime := 22
CutInterval := 22
KaQi1HoldTime := 22
KaQi1MinTotal := 25
KaQi2FirstHold := 22
KaQi2WaitTime := 618
KaQi2SecondHold := 22
LianKaFirstHold := 22
LianKaWaitTime := 618
LianKaSecondHold := 22
LianKaCount := 4
LianKaMode := 1
BaoLiVersion := "珊瑚"
BaoLiHoldTime := 300
guiShow := true
KeyMapWindowOpen := false
DelayWindowOpen := false
OverviewWindowOpen := false
FKeyWindowOpen := false

三、配置文件路径

INI 配置文件存放于脚本同目录。

ConfigFile := A_ScriptDir . "\酒窝配置.ini"

四、按键合法性校验 IsKeyValid()

判断输入的按键名称是否为 AHK 可识别的合法键位，支持功能键、方向键、鼠标键、单字母/数字/符号等。

IsKeyValid(KeyName) {
  if (KeyName = "")
    return false
  if (StrLen(KeyName) > 15)
    return false
  ValidKeys := ["F1","F2","F3","F4","F5","F6","F7","F8","F9","F10","F11","F12","F13","F14","F15","F16","F17","F18","F19","F20","F21","F22","F23","F24"
  ,"Space","Tab","Enter","Return","Escape","Esc","Backspace","BS","Delete","Del","Insert","Ins","Home","End","PgUp","PgDn","PageUp","PageDown"
  ,"Up","Down","Left","Right"
  ,"Ctrl","Control","Shift","Alt","LWin","RWin","LControl","LShift","LAlt","RControl","RShift","RAlt"
  ,"Numpad0","Numpad1","Numpad2","Numpad3","Numpad4","Numpad5","Numpad6","Numpad7","Numpad8","Numpad9"
  ,"NumpadDot","NumpadEnter","NumpadAdd","NumpadSub","NumpadMult","NumpadDiv","NumpadDel","NumpadIns"
  ,"LButton","RButton","MButton","XButton1","XButton2","WheelUp","WheelDown","WheelLeft","WheelRight"]
  for index, valid in ValidKeys {
    if (KeyName = valid) {
      return true
    }
    StringLower, KeyLower, KeyName
    StringLower, ValidLower, valid
    if (KeyLower = ValidLower) {
      return true
    }
  }
  if (RegExMatch(KeyName, "^[a-zA-Z]$"))
    return true
  if (RegExMatch(KeyName, "^[0-9]$"))
    return true
  if (RegExMatch(KeyName, "^[!@#$%^&*()_+\-=\[\]{};:'"",./<>?\\|`~]$"))
    return true
  if (StrLen(KeyName) > 2)
    return false
  try {
    vk := GetKeyVK(KeyName)
    if (vk != "")
      return true
  }
  return false
}

五、读取配置 LoadConfig()

从 INI 读取键位、热键、延迟参数、连卡数量/模式与暴力版本；对越界取值做默认值兜底。

LoadConfig() {
  global
  if !FileExist(ConfigFile)
    return
  IniRead, DriftKey, %ConfigFile%, KeyMapping, DriftKey, %DriftKey%
  IniRead, NitroKey, %ConfigFile%, KeyMapping, NitroKey, %NitroKey%
  IniRead, BoostKey, %ConfigFile%, KeyMapping, BoostKey, %BoostKey%
  IniRead, ForwardKey, %ConfigFile%, KeyMapping, ForwardKey, %ForwardKey%
  IniRead, Hotkey_BaoLi, %ConfigFile%, Hotkeys, BaoLi, %Hotkey_BaoLi%
  IniRead, Hotkey_WuHen, %ConfigFile%, Hotkeys, WuHen, %Hotkey_WuHen%
  IniRead, Hotkey_Cut, %ConfigFile%, Hotkeys, Cut, %Hotkey_Cut%
  IniRead, Hotkey_KaQi1, %ConfigFile%, Hotkeys, KaQi1, %Hotkey_KaQi1%
  IniRead, Hotkey_KaQi2, %ConfigFile%, Hotkeys, KaQi2, %Hotkey_KaQi2%
  IniRead, Hotkey_LianKa, %ConfigFile%, Hotkeys, LianKa, %Hotkey_LianKa%
  IniRead, Hotkey_F10, %ConfigFile%, Hotkeys, F10, %Hotkey_F10%
  IniRead, Hotkey_F11, %ConfigFile%, Hotkeys, F11, %Hotkey_F11%
  IniRead, Hotkey_F12, %ConfigFile%, Hotkeys, F12, %Hotkey_F12%
  IniRead, CutHoldTime, %ConfigFile%, Delays, CutHold, %CutHoldTime%
  IniRead, CutInterval, %ConfigFile%, Delays, CutInterval, %CutInterval%
  IniRead, KaQi1HoldTime, %ConfigFile%, Delays, KaQi1Hold, %KaQi1HoldTime%
  IniRead, KaQi1MinTotal, %ConfigFile%, Delays, KaQi1Min, %KaQi1MinTotal%
  IniRead, KaQi2FirstHold, %ConfigFile%, Delays, KaQi2First, %KaQi2FirstHold%
  IniRead, KaQi2WaitTime, %ConfigFile%, Delays, KaQi2Wait, %KaQi2WaitTime%
  IniRead, KaQi2SecondHold, %ConfigFile%, Delays, KaQi2Second, %KaQi2SecondHold%
  IniRead, LianKaFirstHold, %ConfigFile%, Delays, LianKaFirst, %LianKaFirstHold%
  IniRead, LianKaWaitTime, %ConfigFile%, Delays, LianKaWait, %LianKaWaitTime%
  IniRead, LianKaSecondHold, %ConfigFile%, Delays, LianKaSecond, %LianKaSecondHold%
  IniRead, LianKaCount, %ConfigFile%, Delays, LianKaCount, %LianKaCount%
  if (LianKaCount < 3 || LianKaCount > 5)
    LianKaCount := 4
  IniRead, LianKaMode, %ConfigFile%, Delays, LianKaMode, %LianKaMode%
  if (LianKaMode != 1 && LianKaMode != 2)
    LianKaMode := 1
  IniRead, BaoLiVersion, %ConfigFile%, Settings, BaoLiVersion, %BaoLiVersion%
  IniRead, BaoLiHoldTime, %ConfigFile%, Settings, BaoLiHoldTime, %BaoLiHoldTime%
}

六、保存配置 SaveConfig()

把当前键位、热键、延迟与设置写回 INI 文件。

SaveConfig() {
  global
  IniWrite, %DriftKey%, %ConfigFile%, KeyMapping, DriftKey
  IniWrite, %NitroKey%, %ConfigFile%, KeyMapping, NitroKey
  IniWrite, %BoostKey%, %ConfigFile%, KeyMapping, BoostKey
  IniWrite, %ForwardKey%, %ConfigFile%, KeyMapping, ForwardKey
  IniWrite, %Hotkey_BaoLi%, %ConfigFile%, Hotkeys, BaoLi
  IniWrite, %Hotkey_WuHen%, %ConfigFile%, Hotkeys, WuHen
  IniWrite, %Hotkey_Cut%, %ConfigFile%, Hotkeys, Cut
  IniWrite, %Hotkey_KaQi1%, %ConfigFile%, Hotkeys, KaQi1
  IniWrite, %Hotkey_KaQi2%, %ConfigFile%, Hotkeys, KaQi2
  IniWrite, %Hotkey_LianKa%, %ConfigFile%, Hotkeys, LianKa
  IniWrite, %Hotkey_F10%, %ConfigFile%, Hotkeys, F10
  IniWrite, %Hotkey_F11%, %ConfigFile%, Hotkeys, F11
  IniWrite, %Hotkey_F12%, %ConfigFile%, Hotkeys, F12
  IniWrite, %CutHoldTime%, %ConfigFile%, Delays, CutHold
  IniWrite, %CutInterval%, %ConfigFile%, Delays, CutInterval
  IniWrite, %KaQi1HoldTime%, %ConfigFile%, Delays, KaQi1Hold
  IniWrite, %KaQi1MinTotal%, %ConfigFile%, Delays, KaQi1Min
  IniWrite, %KaQi2FirstHold%, %ConfigFile%, Delays, KaQi2First
  IniWrite, %KaQi2WaitTime%, %ConfigFile%, Delays, KaQi2Wait
  IniWrite, %KaQi2SecondHold%, %ConfigFile%, Delays, KaQi2Second
  IniWrite, %LianKaFirstHold%, %ConfigFile%, Delays, LianKaFirst
  IniWrite, %LianKaWaitTime%, %ConfigFile%, Delays, LianKaWait
  IniWrite, %LianKaSecondHold%, %ConfigFile%, Delays, LianKaSecond
  IniWrite, %LianKaCount%, %ConfigFile%, Delays, LianKaCount
  IniWrite, %LianKaMode%, %ConfigFile%, Delays, LianKaMode
  IniWrite, %BaoLiVersion%, %ConfigFile%, Settings, BaoLiVersion
  IniWrite, %BaoLiHoldTime%, %ConfigFile%, Settings, BaoLiHoldTime
}

七、刷新总览界面 RefreshOverview()

把当前键位、延迟、连卡与暴力版本同步刷新到“配置总览”窗口。

RefreshOverview() {
  global
  GuiControl, Overview:, OV_Drift, %DriftKey%
  GuiControl, Overview:, OV_Nitro, %NitroKey%
  GuiControl, Overview:, OV_Boost, %BoostKey%
  GuiControl, Overview:, OV_Forward, %ForwardKey%
  GuiControl, Overview:, OV_Cut, 按住 %CutHoldTime%ms / 间隔 %CutInterval%ms
  GuiControl, Overview:, OV_K1, 按住 %KaQi1HoldTime%ms / 保底 %KaQi1MinTotal%ms
  GuiControl, Overview:, OV_K2, 一段 %KaQi2FirstHold%ms / 等待 %KaQi2WaitTime%ms / 二段 %KaQi2SecondHold%ms
  LianKaCountDesc := (LianKaCount = 3 ? "三连" : LianKaCount = 4 ? "四连" : "五连")
  LianKaModeDesc := (LianKaMode = 2 ? "模式B（首段带小喷）" : "模式A（先漂移）")
  GuiControl, Overview:, OV_LianKa, 首按 %LianKaFirstHold%ms / 间隔 %LianKaWaitTime%ms / 连按 %LianKaSecondHold%ms
  GuiControl, Overview:, OV_LianKaCount, 当前连卡：%LianKaCountDesc%（%LianKaModeDesc%）
  OV_VersionText := (BaoLiVersion = "珊瑚" ? "珊瑚暴力（固定300ms）" : "酒窝暴力（可调50-500ms）")
  GuiControl, Overview:, OV_Version, %OV_VersionText%
  GuiControl, Overview:, OV_HoldTime, %BaoLiHoldTime%ms
  Tooltip, 已刷新
  SetTimer, RemoveTooltip, -1000
}

八、同步所有界面 SyncAllGUI()

将当前变量同步到主窗口、键位映射、延迟参数、总览、F 功能键等已打开的子窗口控件。

SyncAllGUI() {
  global
  GuiControl, Main:, BaoLiEdit, %Hotkey_BaoLi%
  GuiControl, Main:, WuHenEdit, %Hotkey_WuHen%
  GuiControl, Main:, SpaceEdit, %Hotkey_Cut%
  GuiControl, Main:, KaQi1Edit, %Hotkey_KaQi1%
  GuiControl, Main:, KaQi2Edit, %Hotkey_KaQi2%
  GuiControl, Main:, LianKaEdit, %Hotkey_LianKa%
  if (KeyMapWindowOpen) {
    GuiControl, KeyMap:, KMP_Drift, %DriftKey%
    GuiControl, KeyMap:, KMP_Nitro, %NitroKey%
    GuiControl, KeyMap:, KMP_Boost, %BoostKey%
    GuiControl, KeyMap:, KMP_Forward, %ForwardKey%
  }
  if (DelayWindowOpen) {
    GuiControl, Delay:, DCutHoldEdit, %CutHoldTime%
    GuiControl, Delay:, DCutIntervalEdit, %CutInterval%
    GuiControl, Delay:, DK1HoldEdit, %KaQi1HoldTime%
    GuiControl, Delay:, DK1MinEdit, %KaQi1MinTotal%
    GuiControl, Delay:, DK2FirstEdit, %KaQi2FirstHold%
    GuiControl, Delay:, DK2WaitEdit, %KaQi2WaitTime%
    GuiControl, Delay:, DK2SecondEdit, %KaQi2SecondHold%
    GuiControl, Delay:, DLKFirstEdit, %LianKaFirstHold%
    GuiControl, Delay:, DLKWaitEdit, %LianKaWaitTime%
    GuiControl, Delay:, DLKSecondEdit, %LianKaSecondHold%
    if (LianKaCount = 3) {
      GuiControl, Delay:, DLK3, 1
    } else if (LianKaCount = 4) {
      GuiControl, Delay:, DLK4, 1
    } else {
      GuiControl, Delay:, DLK5, 1
    }
    if (LianKaMode = 2)
      GuiControl, Delay:, DLianKaModeCB, 1
    else
      GuiControl, Delay:, DLianKaModeCB, 0
    GuiControl, Delay:, DBaoLiHoldEdit, %BaoLiHoldTime%
    if (BaoLiVersion = "珊瑚") {
      GuiControl, Delay:, DBVShanhu, 1
      GuiControl, Delay:Disable, DBaoLiHoldEdit
    } else {
      GuiControl, Delay:, DBVJiuwo, 1
      GuiControl, Delay:Enable, DBaoLiHoldEdit
    }
  }
  if (FKeyWindowOpen) {
    GuiControl, FKey:, F10Edit, %Hotkey_F10%
    GuiControl, FKey:, F11Edit, %Hotkey_F11%
    GuiControl, FKey:, F12Edit, %Hotkey_F12%
  }
  UpdateBaoLiVersionUI()
  if (OverviewWindowOpen) {
    RefreshOverview()
  }
}

九、主窗口 GUI 构建

创建主界面：六大功能行、控制热键行、功能按钮区、状态提示与退出按钮，并设置标题、配色与字号。

Gui, Main:New, +AlwaysOnTop -MinimizeBox -MaximizeBox +LastFound
Gui, Main:Color, F0F5FA, FFFFFF
Gui, Main:Font, s11 c222222, 微软雅黑
Gui, Main:Margin, 15, 15
Gui, Main:Font, s14 c0055BB, 楷体
Gui, Main:Add, Text, x0 y0 w450 h35 c0055BB, 作者：酒窝
Gui, Main:Add, Text, x0 y28 w450 h25 c0055BB, 联系方式：神龙见首不见尾
Gui, Main:Font, s11 c222222, 微软雅黑
Gui, Main:Add, Text, x480 y4 w110 h25 c666666, F2隐藏窗口
Gui, Main:Add, GroupBox, x0 y60 w600 h280 c3377CC, 六大功能
Gui, Main:Add, Text, x20 y90 w100 h25, 暴力出弯：
Gui, Main:Add, Edit, x130 y87 w100 h25 vBaoLiEdit, %Hotkey_BaoLi%
Gui, Main:Add, Button, x240 y87 w90 h25 gBindBaoLi, 绑定
Gui, Main:Add, Button, x340 y87 w100 h25 gToggleBaoLi, 启停
Gui, Main:Add, Text, x450 y90 w80 h25 vStateB cFF0000, 未启用
Gui, Main:Add, Text, x20 y130 w100 h25, 无痕三喷：
Gui, Main:Add, Edit, x130 y127 w100 h25 vWuHenEdit, %Hotkey_WuHen%
Gui, Main:Add, Button, x240 y127 w90 h25 gBindWuHen, 绑定
Gui, Main:Add, Button, x340 y127 w100 h25 gToggleWuHen, 启停
Gui, Main:Add, Text, x450 y130 w80 h25 vStateW cFF0000, 未启用
Gui, Main:Add, Text, x20 y170 w100 h25, 快速切断：
Gui, Main:Add, Edit, x130 y167 w100 h25 vSpaceEdit, %Hotkey_Cut%
Gui, Main:Add, Button, x240 y167 w90 h25 gBindSpace, 绑定
Gui, Main:Add, Button, x340 y167 w100 h25 gToggleSpace, 启停
Gui, Main:Add, Text, x450 y170 w80 h25 vStateS cFF0000, 未启用
Gui, Main:Add, Progress, x15 y205 w570 h2 cCCCCCC BackgroundCCCCCC, 100
Gui, Main:Add, Text, x20 y225 w100 h25, 一段连卡：
Gui, Main:Add, Edit, x130 y222 w100 h25 vKaQi1Edit, %Hotkey_KaQi1%
Gui, Main:Add, Button, x240 y222 w90 h25 gBindKaQi1, 绑定
Gui, Main:Add, Button, x340 y222 w100 h25 gToggleKaQi1, 启停
Gui, Main:Add, Text, x450 y225 w80 h25 vStateK1 cFF0000, 未启用
Gui, Main:Add, Text, x20 y265 w100 h25, 二段连卡：
Gui, Main:Add, Edit, x130 y262 w100 h25 vKaQi2Edit, %Hotkey_KaQi2%
Gui, Main:Add, Button, x240 y262 w90 h25 gBindKaQi2, 绑定
Gui, Main:Add, Button, x340 y262 w100 h25 gToggleKaQi2, 启停
Gui, Main:Add, Text, x450 y265 w80 h25 vStateK2 cFF0000, 未启用
Gui, Main:Add, Text, x20 y305 w100 h25, 三四五连卡：
Gui, Main:Add, Edit, x130 y302 w100 h25 vLianKaEdit, %Hotkey_LianKa%
Gui, Main:Add, Button, x240 y302 w90 h25 gBindLianKa, 绑定
Gui, Main:Add, Button, x340 y302 w100 h25 gToggleLianKa, 启停
Gui, Main:Add, Text, x450 y305 w80 h25 vStateLK cFF0000, 未启用
Gui, Main:Add, GroupBox, x0 y350 w600 h85 c3377CC, 控制热键（可自定义）
Gui, Main:Add, Text, x20 y375 w90 h20, F1（总开关）：
Gui, Main:Add, Edit, x120 y372 w90 h24 vF1Edit, %Hotkey_F1%
Gui, Main:Add, Button, x220 y372 w70 h24 gBindF1, 绑定
Gui, Main:Add, Text, x320 y375 w90 h20, F2（隐藏）：
Gui, Main:Add, Edit, x420 y372 w90 h24 vF2Edit, %Hotkey_F2%
Gui, Main:Add, Button, x520 y372 w70 h24 gBindF2, 绑定
Gui, Main:Add, Text, x20 y410 w90 h20, F3（重置）：
Gui, Main:Add, Edit, x120 y407 w90 h24 vF3Edit, %Hotkey_F3%
Gui, Main:Add, Button, x220 y407 w70 h24 gBindF3, 绑定
Gui, Main:Add, Button, x15 y455 w95 h28 gOpenKeyMappingWindow, 键位映射
Gui, Main:Add, Button, x115 y455 w95 h28 gOpenDelaySettingsWindow, 延迟参数
Gui, Main:Add, Button, x215 y455 w95 h28 gOpenOverviewWindow, 配置总览
Gui, Main:Add, Button, x315 y455 w95 h28 gOpenHelpWindow, 按键说明
Gui, Main:Add, Button, x415 y455 w85 h28 gSaveConfig, 保存配置
Gui, Main:Add, Button, x505 y455 w95 h28 gOpenFKeyWindow, F功能键
Gui, Main:Add, Text, x15 y488 w500 h20 vBindStatus c666666, 点击"绑定"修改键位
Gui, Main:Add, Text, x15 y510 w250 h20 cFF0000 vWindowStatus, 请切换到游戏窗口 (GameApp.exe)
Gui, Main:Add, Button, x0 y540 w600 h30 gExitApp cEE4444, 退出程序
Gui, Main:Font, s10 c0066CC, 楷体
Gui, Main:Add, Text, x0 y574 w600 vAuthorText c0066CC, 作者：酒窝 | 联系方式：就不告诉你
Gui, Main:Show, xCenter yCenter w620 h615, 宏管理工具

十、状态初始化与全局热键注册

初始化各功能状态颜色，载入并同步配置，注册 F1/F2/F3/F10/F11/F12 及各功能热键、方向键与数字切换键，启动窗口检测定时器。

SetStateColor("StateB", "未启用", "FF0000")
SetStateColor("StateW", "未启用", "FF0000")
SetStateColor("StateS", "未启用", "FF0000")
SetStateColor("StateK1", "未启用", "FF0000")
SetStateColor("StateK2", "未启用", "FF0000")
SetStateColor("StateLK", "未启用", "FF0000")
LoadConfig()
SyncAllGUI()
Hotkey, $%Hotkey_F1%, F1Action, On
Hotkey, $%Hotkey_F2%, F2Action, On
Hotkey, $%Hotkey_F3%, F3Action, On
Hotkey, $%Hotkey_F10%, F10Action, On
Hotkey, $%Hotkey_F11%, F11Action, On
Hotkey, $%Hotkey_F12%, F12Action, On
Hotkey, $%Hotkey_BaoLi%, FuncWrapper, On
Hotkey, $%Hotkey_WuHen%, FuncWrapper, On
Hotkey, %Hotkey_Cut%, FuncWrapper, On
Hotkey, $%Hotkey_KaQi1%, FuncWrapper, On
Hotkey, $%Hotkey_KaQi2%, FuncWrapper, On
Hotkey, $%Hotkey_LianKa%, FuncWrapper, On
Hotkey, *Left, FuncWrapper, On
Hotkey, *Down, FuncWrapper, On
Hotkey, *Right, FuncWrapper, On
Hotkey, $3, FuncWrapper, On
Hotkey, $4, FuncWrapper, On
Hotkey, $5, FuncWrapper, On
SetTimer, CheckWindow, 500
OnMessage(0x201, "WM_LBUTTONDOWN")

十一、无边框拖动 WM_LBUTTONDOWN

主窗口标题区按下左键时发送拖动消息，实现无标题栏拖动。

WM_LBUTTONDOWN() {
  if (!A_GuiControl)
    PostMessage, 0xA1, 2,,, A
}

十二、暴力版本 UI 同步 UpdateBaoLiVersionUI()

根据当前暴力版本（珊瑚/酒窝）切换延迟窗口输入框的可用状态，并刷新总览与主窗口提示。

UpdateBaoLiVersionUI() {
  global BaoLiVersion, DelayWindowOpen
  if (DelayWindowOpen) {
    if (BaoLiVersion = "珊瑚") {
      GuiControl, Delay:, DBVShanhu, 1
      GuiControl, Delay:Disable, DBaoLiHoldEdit
    } else {
      GuiControl, Delay:, DBVJiuwo, 1
      GuiControl, Delay:Enable, DBaoLiHoldEdit
    }
  }
  if (OverviewWindowOpen)
    RefreshOverview()
  if (BaoLiVersion = "珊瑚") {
    GuiControl, Main:, BindStatus, 已切换到：珊瑚暴力（固定）| 按住时长固定300ms
  } else {
    GuiControl, Main:, BindStatus, 已切换到：酒窝暴力（可调）| 按住时长可调（50-500ms）
  }
}

十三、状态文本与颜色工具

SetStateColor / SetFKeyState 统一更新控件文字与颜色；UpdateFKeyStates 同步 F 功能键窗口的启用状态。

SetStateColor(ControlName, Text, Color) {
  GuiControl, Main:, %ControlName%, %Text%
  GuiControl, Main:+c%Color%, %ControlName%
  GuiControl, Main:+Redraw, %ControlName%
}
SetFKeyState(ControlName, Text, Color) {
  global FKeyWindowOpen
  if (FKeyWindowOpen) {
    GuiControl, FKey:, %ControlName%, %Text%
    GuiControl, FKey:+c%Color%, %ControlName%
    GuiControl, FKey:+Redraw, %ControlName%
  }
}
UpdateFKeyStates() {
  global
  if (spaceCut) {
    SetFKeyState("StateF10", "已启用", "009933")
  } else {
    SetFKeyState("StateF10", "未启用", "FF0000")
  }
  if (lianKaOn) {
    SetFKeyState("StateF11", "已启用", "009933")
  } else {
    SetFKeyState("StateF11", "未启用", "FF0000")
  }
  if (baoLiOn) {
    SetFKeyState("StateF12", "已启用", "009933")
  } else {
    SetFKeyState("StateF12", "未启用", "FF0000")
  }
}

十四、高精度等待 PreciseSleep()

基于 QueryPerformanceCounter 的高精度延时：超过 15ms 先 Sleep 近似值再忙等校准，其余直接忙等。

十五、清除悬浮提示 RemoveTooltip

定时器回调，清空 Tooltip 悬浮提示。

RemoveTooltip:
Tooltip
return

十六、按键说明窗口 OpenHelpWindow

把内置帮助文本写入临时文件并用记事本打开；包含键位写法、各功能用法与版本说明。

OpenHelpWindow:
HelpContent =
(
很重要必须要看！！！！！！
	右键管理员运行！！！右键管理员运行！！！！右键管理员运行！！！！！！

1.修改按键请务必按照写法
    例如：小键盘数字8修改小喷键为Numpad8（N必须大写）
          如果要修改的键位为功能键位，例如Enter，Tab，Ctrl，F1-F2等，逐个字母输入且首字母大写
          比如切断改为Tab，就依次输入T，a，b；回车键位就输入E，n，t,e,r
本软件没有修改按键映射没有写捕获功能，请务必好好输入，氮气键位游戏内是Ctrl和E，如果你是常用
e放氮气那你改为Ctrl（其实不改也一样）

2.二段连卡为q+（小喷+q），即卡接，要记住第一个是没有w键位的，需要定制的找酒窝（你找了我也不理你）
为什么卡接设置成q+w（w是小喷）q；因为有时候落地卡接会出现小喷的声音，用过森涩卡气宏应该知道

3.暴力出弯；拉三喷，小喷灯亮了可以按一下暴力出弯键，只要亮了就包出百分百

4.无痕：这个要压喷，压住按氮气会出；目前市面上的无痕宏都是这样

5.这点是最重要的，酒窝永远最帅！！！！

6.修改按键映射，请务必好好看看第一条说明；

7.延迟配置里面，默认珊瑚暴力就好了；切断和卡气的延迟我也调好了可以不用懂，拿到手改一下按键映射
就能直接用；如果你感兴趣可以改改延迟，60帧率大概一帧是16.67ms

8.qq号：3192821508，没事请勿加谢谢

9.2026-8.15,好了我新增了读取文件，改完按键保存配置就好了，同一台电脑不用每次打开都改按键了

10.市面上还有小喷宏和起步宏；但是他们是月卡起卖，太贵了，我没办法拿到借鉴，如果谁有办法做一个并想融合
到这里面请添加qq备注（我应该会感谢你，可能我也用的到？）

11.其实还有左侧卡宏，但我觉得大家一般大差不差我就没加进去，有需要的话再找我吧~

12.另，本软件无加壳（其实我想加但是感觉没必要），哈哈哈哈

13.新增三四五连卡（默认热键Right，可在界面改绑）：模式A：先按一下q起漂，之后每一次都是q和小喷同时按下；模式B（勾选"首段带小喷"）：第一下就带小喷，全程q+小喷同时按；`n连数（三连/四连/五连）、模式（A/B）和延迟（首按/间隔/连按）都在"延迟参数"窗口里调；游戏内可直接按 3/4/5 切换连卡数量（按3=三连 按4=四连 按5=五连，桌面按 3/4/5 正常输入数字，触发仍用Right）

)
FileDelete, %A_Temp%\酒窝按键说明.txt
FileAppend, %HelpContent%, %A_Temp%\酒窝按键说明.txt
Run, notepad.exe "%A_Temp%\酒窝按键说明.txt"
return

十七、延迟参数应用回调

快速切断、一段连卡、二段连卡、三四五连卡的参数从延迟窗口读回，更新状态提示与悬浮说明。

ApplyCutDelayFromWindow:
Gui, Delay:Submit, NoHide
CutHoldTime := DCutHoldEdit + 0
CutInterval := DCutIntervalEdit + 0
GuiControl, Main:, BindStatus, 快速切断：按住 %CutHoldTime%ms / 间隔 %CutInterval%ms
Tooltip, 快速切断参数已更新
SetTimer, RemoveTooltip, -1500
return
ApplyK1DelayFromWindow:
Gui, Delay:Submit, NoHide
KaQi1HoldTime := DK1HoldEdit + 0
KaQi1MinTotal := DK1MinEdit + 0
GuiControl, Main:, BindStatus, 一段连卡：按住 %KaQi1HoldTime%ms / 保底 %KaQi1MinTotal%ms
Tooltip, 一段连卡参数已更新
SetTimer, RemoveTooltip, -1500
return
ApplyK2DelayFromWindow:
Gui, Delay:Submit, NoHide
KaQi2FirstHold := DK2FirstEdit + 0
KaQi2WaitTime := DK2WaitEdit + 0
KaQi2SecondHold := DK2SecondEdit + 0
GuiControl, Main:, BindStatus, 二段连卡：一段 %KaQi2FirstHold%ms / 等待 %KaQi2WaitTime%ms / 二段 %KaQi2SecondHold%ms
Tooltip, 二段连卡参数已更新
SetTimer, RemoveTooltip, -1500
return
ApplyLianKaDelayFromWindow:
Gui, Delay:Submit, NoHide
LianKaFirstHold := DLKFirstEdit + 0
LianKaWaitTime := DLKWaitEdit + 0
LianKaSecondHold := DLKSecondEdit + 0
LianKaCountDesc := (LianKaCount = 3 ? "三连" : LianKaCount = 4 ? "四连" : "五连")
GuiControl, Main:, BindStatus, 三四五连卡：首按 %LianKaFirstHold%ms / 间隔 %LianKaWaitTime%ms / 连按 %LianKaSecondHold%ms / %LianKaCountDesc%
Tooltip, 三四五连卡参数已更新
SetTimer, RemoveTooltip, -1500
return

十八、连卡数量 / 模式 / 暴力版本切换回调

单选/勾选变化时更新连卡数量、连卡模式（A/B）、暴力按住时长与暴力版本（珊瑚/酒窝），并刷新界面与提示。

OnLianKaCountChange:
GuiControlGet, IsDLK3,, DLK3
GuiControlGet, IsDLK4,, DLK4
if (IsDLK3 = 1) {
  LianKaCount := 3
} else if (IsDLK4 = 1) {
  LianKaCount := 4
} else {
  LianKaCount := 5
}
LianKaCountDesc := (LianKaCount = 3 ? "三连" : LianKaCount = 4 ? "四连" : "五连")
GuiControl, Main:, BindStatus, 三四五连卡：首按 %LianKaFirstHold%ms / 间隔 %LianKaWaitTime%ms / 连按 %LianKaSecondHold%ms / %LianKaCountDesc%
if (OverviewWindowOpen)
  RefreshOverview()
Tooltip, 连卡已切换为：%LianKaCountDesc%
SetTimer, RemoveTooltip, -1500
return
OnLianKaModeChange:
GuiControlGet, IsModeB,, DLianKaModeCB
if (IsModeB = 1)
  LianKaMode := 2
else
  LianKaMode := 1
LianKaModeDesc := (LianKaMode = 2 ? "模式B（首段带小喷）" : "模式A（先漂移）")
GuiControl, Main:, BindStatus, 三四五连卡：%LianKaModeDesc%
if (OverviewWindowOpen)
  RefreshOverview()
Tooltip, 连卡模式已切换为：%LianKaModeDesc%
SetTimer, RemoveTooltip, -1500
return
ApplyBaoLiHoldFromWindow:
if (BaoLiVersion = "珊瑚") {
  Tooltip, 珊瑚暴力为固定300ms，不可调节！
  SetTimer, RemoveTooltip, -1500
  return
}
Gui, Delay:Submit, NoHide
BaoLiHoldTime := DBaoLiHoldEdit + 0
if (BaoLiHoldTime < 50)
  BaoLiHoldTime := 50
if (BaoLiHoldTime > 500)
  BaoLiHoldTime := 500
GuiControl, Main:, BindStatus, 暴力按住时长：%BaoLiHoldTime%ms
Tooltip, 暴力按住时长已更新：%BaoLiHoldTime%ms
SetTimer, RemoveTooltip, -1500
return
OnBaoLiVersionChangeFromWindow:
GuiControlGet, IsShanhu,, DBVShanhu
if (IsShanhu = 1) {
  BaoLiVersion := "珊瑚"
  GuiControl, Delay:Disable, DBaoLiHoldEdit
  UpdateBaoLiVersionUI()
  Tooltip, 已切换到：珊瑚暴力（固定）`n按住时长固定300ms
} else {
  BaoLiVersion := "酒窝"
  GuiControl, Delay:Enable, DBaoLiHoldEdit
  UpdateBaoLiVersionUI()
  Tooltip, 已切换到：酒窝暴力（可调）`n按住时长可调（50-500ms）
}
SetTimer, RemoveTooltip, -1500
return

十九、键位映射窗口

漂移/氮气/小喷/前进四个驾驶键位的编辑窗口：保存时逐项校验合法性，支持恢复默认与关闭销毁。

OpenKeyMappingWindow:
if (KeyMapWindowOpen) {
  Gui, KeyMap:Show
  return
}
KeyMapWindowOpen := true
Gui, KeyMap:New, +AlwaysOnTop +ToolWindow +OwnerMain
Gui, KeyMap:Color, F0F5FA, FFFFFF
Gui, KeyMap:Font, s11 c222222, 微软雅黑
Gui, KeyMap:Margin, 15, 15
Gui, KeyMap:Add, Text, x0 y0 w340 h30 Center c0055BB, ★ 全局键位映射设置
Gui, KeyMap:Font, s10 c222222
Gui, KeyMap:Add, Text, x20 y45 w70 h22, 漂移键：
Gui, KeyMap:Add, Edit, x95 y42 w60 h24 vKMP_Drift, %DriftKey%
Gui, KeyMap:Add, Text, x170 y45 w70 h22, 氮气键：
Gui, KeyMap:Add, Edit, x245 y42 w60 h24 vKMP_Nitro, %NitroKey%
Gui, KeyMap:Add, Text, x20 y80 w70 h22, 小喷键：
Gui, KeyMap:Add, Edit, x95 y77 w60 h24 vKMP_Boost, %BoostKey%
Gui, KeyMap:Add, Text, x170 y80 w70 h22, 前进键：
Gui, KeyMap:Add, Edit, x245 y77 w60 h24 vKMP_Forward, %ForwardKey%
Gui, KeyMap:Add, Text, x20 y115 w300 h20 c666666 Center, 修改后点击"保存"立即生效
Gui, KeyMap:Add, Button, x60 y145 w70 h28 gApplyKeyMappingFromWindow, 保存
Gui, KeyMap:Add, Button, x140 y145 w80 h28 gResetKeyMapping, 恢复默认
Gui, KeyMap:Add, Button, x230 y145 w70 h28 gCloseKeyMapWindow, 取消
Gui, KeyMap:Show, xCenter yCenter w360 h200, 全局键位映射
return
ApplyKeyMappingFromWindow:
Gui, KeyMap:Submit, NoHide
if (!IsKeyValid(KMP_Drift)) {
  MsgBox, 48,, 漂移键 "%KMP_Drift%" 无效！`n请输入正确的按键名称。
  return
}
if (!IsKeyValid(KMP_Nitro)) {
  MsgBox, 48,, 氮气键 "%KMP_Nitro%" 无效！`n请输入正确的按键名称。
  return
}
if (!IsKeyValid(KMP_Boost)) {
  MsgBox, 48,, 小喷键 "%KMP_Boost%" 无效！`n请输入正确的按键名称。
  return
}
if (!IsKeyValid(KMP_Forward)) {
  MsgBox, 48,, 前进键 "%KMP_Forward%" 无效！`n请输入正确的按键名称。
  return
}
DriftKey := KMP_Drift
NitroKey := KMP_Nitro
BoostKey := KMP_Boost
ForwardKey := KMP_Forward
GuiControl, Main:, BindStatus, 键位已更新：漂移=%DriftKey% 氮气=%NitroKey% 小喷=%BoostKey% 前进=%ForwardKey%
Tooltip, 键位映射已更新！
SetTimer, RemoveTooltip, -2000
Gui, KeyMap:Destroy
KeyMapWindowOpen := false
return
ResetKeyMapping:
GuiControl, KeyMap:, KMP_Drift, q
GuiControl, KeyMap:, KMP_Nitro, e
GuiControl, KeyMap:, KMP_Boost, Up
GuiControl, KeyMap:, KMP_Forward, w
Tooltip, 已恢复默认键位
SetTimer, RemoveTooltip, -1500
return
CloseKeyMapWindow:
Gui, KeyMap:Destroy
KeyMapWindowOpen := false
return
KeyMapGuiClose:
Gui, KeyMap:Destroy
KeyMapWindowOpen := false
return

二十、延迟参数设置窗口

集中编辑切断、一段/二段连卡、三四五连卡的各段延时，以及连卡数量、模式、暴力版本与按住时长。

OpenDelaySettingsWindow:
if (DelayWindowOpen) {
  Gui, Delay:Show
  return
}
DelayWindowOpen := true
Gui, Delay:New, +AlwaysOnTop +ToolWindow +OwnerMain
Gui, Delay:Color, F0F5FA, FFFFFF
Gui, Delay:Font, s11 c222222, 微软雅黑
Gui, Delay:Margin, 15, 15
Gui, Delay:Add, Text, x0 y0 w440 h30 Center c0055BB, ★ 延迟参数设置
Gui, Delay:Font, s10 c222222
Gui, Delay:Add, Text, x20 y45 w70 h20, 快速切断：
Gui, Delay:Add, Text, x95 y45 w40 h20, 按住
Gui, Delay:Add, Edit, x140 y42 w50 h24 vDCutHoldEdit, %CutHoldTime%
Gui, Delay:Add, UpDown, x140 y42 w50 h24 vDCutHoldUD Range5-100, %CutHoldTime%
Gui, Delay:Add, Text, x200 y45 w40 h20, 间隔
Gui, Delay:Add, Edit, x245 y42 w50 h24 vDCutIntervalEdit, %CutInterval%
Gui, Delay:Add, UpDown, x245 y42 w50 h24 vDCutIntervalUD Range5-100, %CutInterval%
Gui, Delay:Add, Button, x310 y40 w70 h24 gApplyCutDelayFromWindow, 应用
Gui, Delay:Add, Text, x20 y80 w70 h20, 一段连卡：
Gui, Delay:Add, Text, x95 y80 w40 h20, 按住
Gui, Delay:Add, Edit, x140 y77 w50 h24 vDK1HoldEdit, %KaQi1HoldTime%
Gui, Delay:Add, UpDown, x140 y77 w50 h24 vDK1HoldUD Range5-100, %KaQi1HoldTime%
Gui, Delay:Add, Text, x200 y80 w40 h20, 保底
Gui, Delay:Add, Edit, x245 y77 w50 h24 vDK1MinEdit, %KaQi1MinTotal%
Gui, Delay:Add, UpDown, x245 y77 w50 h24 vDK1MinUD Range5-100, %KaQi1MinTotal%
Gui, Delay:Add, Button, x310 y75 w70 h24 gApplyK1DelayFromWindow, 应用
Gui, Delay:Add, Text, x20 y115 w70 h20, 二段连卡：
Gui, Delay:Add, Text, x95 y115 w40 h20, 一段
Gui, Delay:Add, Edit, x140 y112 w50 h24 vDK2FirstEdit, %KaQi2FirstHold%
Gui, Delay:Add, UpDown, x140 y112 w50 h24 vDK2FirstUD Range5-100, %KaQi2FirstHold%
Gui, Delay:Add, Text, x200 y115 w40 h20, 等待
Gui, Delay:Add, Edit, x245 y112 w50 h24 vDK2WaitEdit, %KaQi2WaitTime%
Gui, Delay:Add, UpDown, x245 y112 w50 h24 vDK2WaitUD Range100-2000, %KaQi2WaitTime%
Gui, Delay:Add, Text, x305 y115 w40 h20, 二段
Gui, Delay:Add, Edit, x350 y112 w50 h24 vDK2SecondEdit, %KaQi2SecondHold%
Gui, Delay:Add, UpDown, x350 y112 w50 h24 vDK2SecondUD Range5-100, %KaQi2SecondHold%
Gui, Delay:Add, Button, x415 y110 w70 h24 gApplyK2DelayFromWindow, 应用
Gui, Delay:Add, Text, x20 y150 w95 h20, 三四五连卡：
Gui, Delay:Add, Text, x95 y150 w40 h20, 首按
Gui, Delay:Add, Edit, x140 y147 w50 h24 vDLKFirstEdit, %LianKaFirstHold%
Gui, Delay:Add, UpDown, x140 y147 w50 h24 vDLKFirstUD Range5-100, %LianKaFirstHold%
Gui, Delay:Add, Text, x200 y150 w40 h20, 间隔
Gui, Delay:Add, Edit, x245 y147 w50 h24 vDLKWaitEdit, %LianKaWaitTime%
Gui, Delay:Add, UpDown, x245 y147 w50 h24 vDLKWaitUD Range100-2000, %LianKaWaitTime%
Gui, Delay:Add, Text, x305 y150 w40 h20, 连按
Gui, Delay:Add, Edit, x350 y147 w50 h24 vDLKSecondEdit, %LianKaSecondHold%
Gui, Delay:Add, UpDown, x350 y147 w50 h24 vDLKSecondUD Range5-100, %LianKaSecondHold%
Gui, Delay:Add, Button, x415 y147 w70 h24 gApplyLianKaDelayFromWindow, 应用
Gui, Delay:Add, Text, x20 y178 w50 h20, 连数：
Gui, Delay:Add, Radio, x70 y175 w60 h20 Group vDLK3 gOnLianKaCountChange, 三连
Gui, Delay:Add, Radio, x135 y175 w60 h20 vDLK4 gOnLianKaCountChange, 四连
Gui, Delay:Add, Radio, x200 y175 w60 h20 vDLK5 gOnLianKaCountChange, 五连
Gui, Delay:Add, CheckBox, x280 y175 w210 h20 vDLianKaModeCB gOnLianKaModeChange, 首段带小喷（模式B）
Gui, Delay:Add, Text, x20 y210 w70 h20, 暴力版本：
Gui, Delay:Add, Radio, x95 y207 w150 h20 Group -Wrap vDBVShanhu gOnBaoLiVersionChangeFromWindow, 珊瑚（固定300ms）
Gui, Delay:Add, Radio, x245 y207 w200 h20 -Wrap vDBVJiuwo gOnBaoLiVersionChangeFromWindow, 酒窝（可调50-500ms）
Gui, Delay:Add, Text, x20 y238 w80 h20, 按住时长：
Gui, Delay:Add, Edit, x105 y235 w50 h24 vDBaoLiHoldEdit, %BaoLiHoldTime%
Gui, Delay:Add, UpDown, x105 y235 w50 h24 vDBaoLiHoldUD Range50-500, %BaoLiHoldTime%
Gui, Delay:Add, Text, x160 y238 w25 h20, ms
Gui, Delay:Add, Button, x310 y235 w70 h24 gApplyBaoLiHoldFromWindow, 应用
Gui, Delay:Add, Button, x170 y275 w100 h28 gCloseDelayWindow, 关闭
if (BaoLiVersion = "珊瑚") {
  GuiControl, Delay:, DBVShanhu, 1
  GuiControl, Delay:Disable, DBaoLiHoldEdit
} else {
  GuiControl, Delay:, DBVJiuwo, 1
  GuiControl, Delay:Enable, DBaoLiHoldEdit
}
if (LianKaCount = 3) {
  GuiControl, Delay:, DLK3, 1
} else if (LianKaCount = 4) {
  GuiControl, Delay:, DLK4, 1
} else {
  GuiControl, Delay:, DLK5, 1
}
if (LianKaMode = 2)
  GuiControl, Delay:, DLianKaModeCB, 1
else
  GuiControl, Delay:, DLianKaModeCB, 0
Gui, Delay:Show, xCenter yCenter w500 h315, 延迟参数设置
return
CloseDelayWindow:
Gui, Delay:Destroy
DelayWindowOpen := false
return
DelayGuiClose:
Gui, Delay:Destroy
DelayWindowOpen := false
return

二十一、配置总览窗口

只读展示当前键位映射、延迟参数、连卡数量与模式、暴力版本及按住时长，支持手动刷新。

OpenOverviewWindow:
if (OverviewWindowOpen) {
  Gui, Overview:Show
  return
}
OverviewWindowOpen := true
Gui, Overview:New, +AlwaysOnTop +ToolWindow +OwnerMain
Gui, Overview:Color, F0F5FA, FFFFFF
Gui, Overview:Font, s11 c222222, 微软雅黑
Gui, Overview:Margin, 15, 15
Gui, Overview:Add, Text, x0 y0 w440 h35 Center c0055BB, ★ 当前配置总览
Gui, Overview:Font, s10 c222222
Gui, Overview:Add, Text, x15 y45 w150 h22, 【键位映射】
Gui, Overview:Add, Text, x15 y70 w70 h22, 漂移键：
Gui, Overview:Add, Text, x90 y70 w60 h22 vOV_Drift, %DriftKey%
Gui, Overview:Add, Text, x170 y70 w70 h22, 氮气键：
Gui, Overview:Add, Text, x245 y70 w60 h22 vOV_Nitro, %NitroKey%
Gui, Overview:Add, Text, x15 y100 w70 h22, 小喷键：
Gui, Overview:Add, Text, x90 y100 w60 h22 vOV_Boost, %BoostKey%
Gui, Overview:Add, Text, x170 y100 w70 h22, 前进键：
Gui, Overview:Add, Text, x245 y100 w60 h22 vOV_Forward, %ForwardKey%
Gui, Overview:Add, Text, x15 y135 w150 h22, 【延迟参数】
Gui, Overview:Add, Text, x15 y160 w80 h20, 快速切断：
Gui, Overview:Add, Text, x100 y160 w150 h20 vOV_Cut, 按住 %CutHoldTime%ms / 间隔 %CutInterval%ms
Gui, Overview:Add, Text, x15 y185 w80 h20, 一段连卡：
Gui, Overview:Add, Text, x100 y185 w150 h20 vOV_K1, 按住 %KaQi1HoldTime%ms / 保底 %KaQi1MinTotal%ms
Gui, Overview:Add, Text, x15 y210 w80 h20, 二段连卡：
Gui, Overview:Add, Text, x100 y210 w230 h20 vOV_K2, 一段 %KaQi2FirstHold%ms / 等待 %KaQi2WaitTime%ms / 二段 %KaQi2SecondHold%ms
LianKaCountDesc := (LianKaCount = 3 ? "三连" : LianKaCount = 4 ? "四连" : "五连")
LianKaModeDesc := (LianKaMode = 2 ? "模式B（首段带小喷）" : "模式A（先漂移）")
Gui, Overview:Add, Text, x15 y235 w95 h20, 三四五连卡：
Gui, Overview:Add, Text, x100 y235 w280 h20 vOV_LianKa, 首按 %LianKaFirstHold%ms / 间隔 %LianKaWaitTime%ms / 连按 %LianKaSecondHold%ms
Gui, Overview:Add, Text, x15 y258 w220 h20 cE60000 vOV_LianKaCount, 当前连卡：%LianKaCountDesc%（%LianKaModeDesc%）
Gui, Overview:Add, Text, x15 y285 w150 h22, 【暴力模式】
Gui, Overview:Add, Text, x15 y310 w80 h20, 当前版本：
OV_VersionText := (BaoLiVersion = "珊瑚" ? "珊瑚暴力（固定300ms）" : "酒窝暴力（可调50-500ms）")
Gui, Overview:Add, Text, x100 y310 w180 h20 vOV_Version, %OV_VersionText%
Gui, Overview:Add, Text, x15 y335 w80 h20, 按住时长：
Gui, Overview:Add, Text, x100 y335 w80 h20 vOV_HoldTime, %BaoLiHoldTime%ms
Gui, Overview:Add, Button, x120 y380 w90 h28 gRefreshOverview, 刷新
Gui, Overview:Add, Button, x220 y380 w90 h28 gCloseOverviewWindow, 关闭
Gui, Overview:Show, xCenter yCenter w460 h435, 当前配置总览
return
RefreshOverview:
GuiControl, Overview:, OV_Drift, %DriftKey%
GuiControl, Overview:, OV_Nitro, %NitroKey%
GuiControl, Overview:, OV_Boost, %BoostKey%
GuiControl, Overview:, OV_Forward, %ForwardKey%
GuiControl, Overview:, OV_Cut, 按住 %CutHoldTime%ms / 间隔 %CutInterval%ms
GuiControl, Overview:, OV_K1, 按住 %KaQi1HoldTime%ms / 保底 %KaQi1MinTotal%ms
GuiControl, Overview:, OV_K2, 一段 %KaQi2FirstHold%ms / 等待 %KaQi2WaitTime%ms / 二段 %KaQi2SecondHold%ms
LianKaCountDesc := (LianKaCount = 3 ? "三连" : LianKaCount = 4 ? "四连" : "五连")
LianKaModeDesc := (LianKaMode = 2 ? "模式B（首段带小喷）" : "模式A（先漂移）")
GuiControl, Overview:, OV_LianKa, 首按 %LianKaFirstHold%ms / 间隔 %LianKaWaitTime%ms / 连按 %LianKaSecondHold%ms
GuiControl, Overview:, OV_LianKaCount, 当前连卡：%LianKaCountDesc%（%LianKaModeDesc%）
OV_VersionText := (BaoLiVersion = "珊瑚" ? "珊瑚暴力（固定300ms）" : "酒窝暴力（可调50-500ms）")
GuiControl, Overview:, OV_Version, %OV_VersionText%
GuiControl, Overview:, OV_HoldTime, %BaoLiHoldTime%ms
Tooltip, 已刷新
SetTimer, RemoveTooltip, -1000
return
CloseOverviewWindow:
Gui, Overview:Destroy
OverviewWindowOpen := false
return
OverviewGuiClose:
Gui, Overview:Destroy
OverviewWindowOpen := false
return

二十二、F 功能键窗口

F10 快速切断、F11 三四五连卡、F12 暴力出弯的单独绑定与启停界面。

OpenFKeyWindow:
if (FKeyWindowOpen) {
  Gui, FKey:Show
  return
}
FKeyWindowOpen := true
Gui, FKey:New, +AlwaysOnTop +ToolWindow +OwnerMain
Gui, FKey:Color, F0F5FA, FFFFFF
Gui, FKey:Font, s11 c222222, 微软雅黑
Gui, FKey:Margin, 15, 15
Gui, FKey:Add, Text, x0 y0 w450 h30 Center c0055BB, ★ F功能键控制
Gui, FKey:Font, s10 c222222
Gui, FKey:Add, Text, x20 y45 w120 h22, F10 快速切断：
Gui, FKey:Add, Edit, x150 y42 w60 h24 vF10Edit, %Hotkey_F10%
Gui, FKey:Add, Button, x220 y42 w60 h24 gBindF10, 绑定
Gui, FKey:Add, Button, x285 y42 w60 h24 gToggleF10, 启停
Gui, FKey:Add, Text, x355 y45 w80 h22 vStateF10 cFF0000, 未启用
Gui, FKey:Add, Text, x20 y80 w120 h22, F11 三四五连卡：
Gui, FKey:Add, Edit, x150 y77 w60 h24 vF11Edit, %Hotkey_F11%
Gui, FKey:Add, Button, x220 y77 w60 h24 gBindF11, 绑定
Gui, FKey:Add, Button, x285 y77 w60 h24 gToggleF11, 启停
Gui, FKey:Add, Text, x355 y80 w80 h22 vStateF11 cFF0000, 未启用
Gui, FKey:Add, Text, x20 y115 w120 h22, F12 暴力出弯：
Gui, FKey:Add, Edit, x150 y112 w60 h24 vF12Edit, %Hotkey_F12%
Gui, FKey:Add, Button, x220 y112 w60 h24 gBindF12, 绑定
Gui, FKey:Add, Button, x285 y112 w60 h24 gToggleF12, 启停
Gui, FKey:Add, Text, x355 y115 w80 h22 vStateF12 cFF0000, 未启用
Gui, FKey:Add, Text, x20 y150 w410 h20 c666666, 按 F10/F11/F12 可单独启停对应功能
Gui, FKey:Add, Button, x175 y180 w100 h28 gCloseFKeyWindow, 关闭
UpdateFKeyStates()
Gui, FKey:Show, xCenter yCenter w450 h220, F功能键控制
return
CloseFKeyWindow:
Gui, FKey:Destroy
FKeyWindowOpen := false
return
FKeyGuiClose:
Gui, FKey:Destroy
FKeyWindowOpen := false
return

二十三、游戏窗口检测与热键分发 FuncWrapper

IsGameActive 判断前台是否为游戏进程；FuncWrapper 为所有热键统一入口，未在游戏内时原样透传按键，游戏内按启用状态分发到对应宏动作。

二十四、总开关 F1 / 隐藏 F2 / 重置 F3

F1 全部开/全部关；F2 切换主窗口显示隐藏；F3 强制把所有功能重新开启。

F1Action:
allOn := (baoLiOn && wuHenOn && spaceCut && kaQi1On && kaQi2On && lianKaOn)
if (allOn) {
  if (baoLiOn) {
    baoLiOn := false
    Hotkey, $%Hotkey_BaoLi%, FuncWrapper, Off
    SetStateColor("StateB", "未启用", "FF0000")
  }
  if (wuHenOn) {
    wuHenOn := false
    Hotkey, $%Hotkey_WuHen%, FuncWrapper, Off
    SetStateColor("StateW", "未启用", "FF0000")
  }
  if (spaceCut) {
    spaceCut := false
    Hotkey, %Hotkey_Cut%, FuncWrapper, Off
    SetStateColor("StateS", "未启用", "FF0000")
  }
  if (kaQi1On) {
    kaQi1On := false
    if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
      Hotkey, $%Hotkey_KaQi1%, FuncWrapper, Off
    }
    SetStateColor("StateK1", "未启用", "FF0000")
  }
  if (kaQi2On) {
    kaQi2On := false
    if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
      Hotkey, $%Hotkey_KaQi2%, FuncWrapper, Off
    }
    SetStateColor("StateK2", "未启用", "FF0000")
  }
  if (lianKaOn) {
    lianKaOn := false
    if (Hotkey_LianKa != "Right") {
      Hotkey, $%Hotkey_LianKa%, FuncWrapper, Off
    }
    SetStateColor("StateLK", "未启用", "FF0000")
  }
  Send, {%NitroKey% up}
  Send, {%ForwardKey% up}
  Send, {%BoostKey% up}
  Send, {Ctrl up}
  Send, {%DriftKey% up}
  Tooltip, 所有功能已全部关闭
  GuiControl, Main:, BindStatus, [已关闭] 全部已关闭
} else {
  if (!baoLiOn) {
    baoLiOn := true
    Hotkey, $%Hotkey_BaoLi%, FuncWrapper, On
    SetStateColor("StateB", "已启用", "009933")
  }
  if (!wuHenOn) {
    wuHenOn := true
    Hotkey, $%Hotkey_WuHen%, FuncWrapper, On
    SetStateColor("StateW", "已启用", "009933")
  }
  if (!spaceCut) {
    spaceCut := true
    Hotkey, %Hotkey_Cut%, FuncWrapper, On
    SetStateColor("StateS", "已启用", "009933")
  }
  if (!kaQi1On) {
    kaQi1On := true
    if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
      Hotkey, $%Hotkey_KaQi1%, FuncWrapper, On
    }
    SetStateColor("StateK1", "已启用", "009933")
  }
  if (!kaQi2On) {
    kaQi2On := true
    if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
      Hotkey, $%Hotkey_KaQi2%, FuncWrapper, On
    }
    SetStateColor("StateK2", "已启用", "009933")
  }
  if (!lianKaOn) {
    lianKaOn := true
    if (Hotkey_LianKa != "Right") {
      Hotkey, $%Hotkey_LianKa%, FuncWrapper, On
    }
    SetStateColor("StateLK", "已启用", "009933")
  }
  Tooltip, 所有功能已全部开启
  GuiControl, Main:, BindStatus, [已开启] 全部已开启
}
UpdateFKeyStates()
SetTimer, RemoveTooltip, -1500
return
F2Action:
guiShow := !guiShow
if (guiShow)
  Gui, Main:Show, xCenter yCenter
else
  Gui, Main:Hide
return
F3Action:
if (!baoLiOn) {
  baoLiOn := true
  Hotkey, $%Hotkey_BaoLi%, FuncWrapper, On
  SetStateColor("StateB", "已启用", "009933")
}
if (!wuHenOn) {
  wuHenOn := true
  Hotkey, $%Hotkey_WuHen%, FuncWrapper, On
  SetStateColor("StateW", "已启用", "009933")
}
if (!spaceCut) {
  spaceCut := true
  Hotkey, %Hotkey_Cut%, FuncWrapper, On
  SetStateColor("StateS", "已启用", "009933")
}
if (!kaQi1On) {
  kaQi1On := true
  if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
    Hotkey, $%Hotkey_KaQi1%, FuncWrapper, On
  }
  SetStateColor("StateK1", "已启用", "009933")
}
if (!kaQi2On) {
  kaQi2On := true
  if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
    Hotkey, $%Hotkey_KaQi2%, FuncWrapper, On
  }
  SetStateColor("StateK2", "已启用", "009933")
}
if (!lianKaOn) {
  lianKaOn := true
  if (Hotkey_LianKa != "Right") {
    Hotkey, $%Hotkey_LianKa%, FuncWrapper, On
  }
  SetStateColor("StateLK", "已启用", "009933")
}
Tooltip, 所有功能已全部开启（已重置）
GuiControl, Main:, BindStatus, [已开启] 全部已开启（重置）
UpdateFKeyStates()
SetTimer, RemoveTooltip, -1500
return

二十五、F10 / F11 / F12 动作与窗口检测

F10/F11/F12 分别调用对应启停函数；CheckWindow 定时器每 500ms 更新主窗口的游戏激活状态提示。

F10Action:
ToggleCutFunc()
return
F11Action:
ToggleLianKaFunc(true)
return
F12Action:
ToggleBaoLiFunc()
return
CheckWindow:
if WinActive("ahk_exe GameApp.exe") {
  GuiControl, Main:, WindowStatus, 游戏窗口已激活 (GameApp.exe)
  GuiControl, Main:+cGreen, WindowStatus
} else {
  GuiControl, Main:, WindowStatus, 请切换到游戏窗口 (GameApp.exe)
  GuiControl, Main:+cRed, WindowStatus
}
return

二十六、通用宏解析 RunIniMacro()

解析以 @ 分段、| 分隔动作的宏数据，支持 send 按键（替换四个驾驶键位占位符）与 sleep 延时两类动作。

RunIniMacro(MacroData) {
  if !IsGameActive()
    return
  StringSplit, Parts, MacroData, @
  if (Parts0 < 2) {
    return
  }
  ActionList := Parts2
  Actions := []
  Loop, Parse, ActionList, |
  {
    Actions.Push(A_LoopField)
  }
  for index, Action in Actions
  {
    Action := Trim(Action)
    if (Action = "")
      continue
    if (SubStr(Action, 1, 4) = "send") {
      KeyPart := SubStr(Action, 6)
      KeyPart := StrReplace(KeyPart, "{DriftKey}", DriftKey)
      KeyPart := StrReplace(KeyPart, "{NitroKey}", NitroKey)
      KeyPart := StrReplace(KeyPart, "{BoostKey}", BoostKey)
      KeyPart := StrReplace(KeyPart, "{ForwardKey}", ForwardKey)
      Send, %KeyPart%
    }
    else if (SubStr(Action, 1, 5) = "sleep") {
      Ms := SubStr(Action, 7)
      Ms := Ms + 0
      if (Ms > 0)
        Sleep, %Ms%
    }
    else {
    }
  }
}

二十七、核心宏动作序列

暴力出弯（珊瑚固定 300ms / 酒窝可调）、无痕三喷、快速切断、一段/二段卡气、三四五连卡（模式 A/B）等具体按键时序。

二十八、方向键动作 Left / Down / Right

方向键优先转发到已启用的对应卡气/连卡功能，否则原样发送方向键。

LeftAction:
if (kaQi1On) {
  if (Hotkey_KaQi1 = "Left") {
    Gosub, KaQi1Action
    return
  }
}
Send, {Blind}{Left}
return
DownAction:
if (kaQi2On) {
  if (Hotkey_KaQi2 = "Down") {
    Gosub, KaQi2Action
    return
  }
}
Send, {Blind}{Down}
return
RightAction:
if (lianKaOn) {
  if (Hotkey_LianKa = "Right") {
    Gosub, LianKaAction
    return
  }
}
Send, {Blind}{Right}
return

二十九、六大功能键绑定回调

读取输入框新键位，校验合法性后解绑旧键、绑定新键；提示按 F3 使新键位生效。

BindBaoLi:
GuiControlGet, n,, BaoLiEdit
if (n = Hotkey_BaoLi) {
  MsgBox, 262144,, 该键位已经是暴力出弯的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
try Hotkey, $%Hotkey_BaoLi%, FuncWrapper, Off
  Hotkey_BaoLi := n
if (baoLiOn)
  Hotkey, $%Hotkey_BaoLi%, FuncWrapper, On
GuiControl, Main:, BindStatus, 暴力出弯已绑定为：%n%
MsgBox, 262144,, 暴力出弯已绑定为：%n%`n按 F3 使新键位生效
return
BindWuHen:
GuiControlGet, n,, WuHenEdit
if (n = Hotkey_WuHen) {
  MsgBox, 262144,, 该键位已经是无痕三喷的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
try Hotkey, $%Hotkey_WuHen%, FuncWrapper, Off
  Hotkey_WuHen := n
if (wuHenOn)
  Hotkey, $%Hotkey_WuHen%, FuncWrapper, On
GuiControl, Main:, BindStatus, 无痕三喷已绑定为：%n%
MsgBox, 262144,, 无痕三喷已绑定为：%n%`n按 F3 使新键位生效
return
BindSpace:
GuiControlGet, n,, SpaceEdit
if (n = Hotkey_Cut) {
  MsgBox, 262144,, 该键位已经是快速切断的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
try Hotkey, %Hotkey_Cut%, FuncWrapper, Off
  Hotkey_Cut := n
if (spaceCut)
  Hotkey, %Hotkey_Cut%, FuncWrapper, On
GuiControl, Main:, BindStatus, 快速切断已绑定为：%n%
MsgBox, 262144,, 快速切断已绑定为：%n%`n按 F3 使新键位生效
return
BindKaQi1:
GuiControlGet, n,, KaQi1Edit
if (n = Hotkey_KaQi1) {
  MsgBox, 262144,, 该键位已经是一段连卡的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
  try Hotkey, $%Hotkey_KaQi1%, FuncWrapper, Off
  }
Hotkey_KaQi1 := n
if (n != "Left" && n != "Down") {
  if (kaQi1On)
    Hotkey, $%n%, FuncWrapper, On
  else
    Hotkey, $%n%, FuncWrapper, Off
}
GuiControl, Main:, BindStatus, 一段连卡已绑定为：%n%
MsgBox, 262144,, 一段连卡已绑定为：%n%`n按 F3 使新键位生效
return
BindKaQi2:
GuiControlGet, n,, KaQi2Edit
if (n = Hotkey_KaQi2) {
  MsgBox, 262144,, 该键位已经是二段连卡的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
  try Hotkey, $%Hotkey_KaQi2%, FuncWrapper, Off
  }
Hotkey_KaQi2 := n
if (n != "Left" && n != "Down") {
  if (kaQi2On)
    Hotkey, $%n%, FuncWrapper, On
  else
    Hotkey, $%n%, FuncWrapper, Off
}
GuiControl, Main:, BindStatus, 二段连卡已绑定为：%n%
MsgBox, 262144,, 二段连卡已绑定为：%n%`n按 F3 使新键位生效
return
BindLianKa:
GuiControlGet, n,, LianKaEdit
if (n = Hotkey_LianKa) {
  MsgBox, 262144,, 该键位已经是三四五连卡的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (Hotkey_LianKa != "Right") {
  try Hotkey, $%Hotkey_LianKa%, FuncWrapper, Off
  }
Hotkey_LianKa := n
if (n != "Right") {
  if (lianKaOn)
    Hotkey, $%n%, FuncWrapper, On
  else
    Hotkey, $%n%, FuncWrapper, Off
}
GuiControl, Main:, BindStatus, 三四五连卡已绑定为：%n%
MsgBox, 262144,, 三四五连卡已绑定为：%n%`n按 F3 使新键位生效
return

三十、控制键绑定回调（F1/F2/F3/F10/F11/F12）

逐个校验控制键，禁止与其他控制键重复占用，解绑旧键并绑定新键，即时生效。

BindF1:
GuiControlGet, n,, F1Edit
if (n = Hotkey_F1) {
  MsgBox, 262144,, 该键位已经是 F1 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F2 || n = Hotkey_F3 || n = Hotkey_F10 || n = Hotkey_F11 || n = Hotkey_F12) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F1%, F1Action, Off
  Hotkey_F1 := n
Hotkey, $%Hotkey_F1%, F1Action, On
GuiControl, Main:, BindStatus, F1 已绑定为：%n%
MsgBox, 262144,, F1（总开关）已绑定为：%n%
return
BindF2:
GuiControlGet, n,, F2Edit
if (n = Hotkey_F2) {
  MsgBox, 262144,, 该键位已经是 F2 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F1 || n = Hotkey_F3 || n = Hotkey_F10 || n = Hotkey_F11 || n = Hotkey_F12) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F2%, F2Action, Off
  Hotkey_F2 := n
Hotkey, $%Hotkey_F2%, F2Action, On
GuiControl, Main:, BindStatus, F2 已绑定为：%n%
MsgBox, 262144,, F2（隐藏窗口）已绑定为：%n%
return
BindF3:
GuiControlGet, n,, F3Edit
if (n = Hotkey_F3) {
  MsgBox, 262144,, 该键位已经是 F3 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F1 || n = Hotkey_F2 || n = Hotkey_F10 || n = Hotkey_F11 || n = Hotkey_F12) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F3%, F3Action, Off
  Hotkey_F3 := n
Hotkey, $%Hotkey_F3%, F3Action, On
GuiControl, Main:, BindStatus, F3 已绑定为：%n%
MsgBox, 262144,, F3（强制重置）已绑定为：%n%
return
BindF10:
GuiControlGet, n,, F10Edit
if (n = Hotkey_F10) {
  MsgBox, 262144,, 该键位已经是 F10 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F1 || n = Hotkey_F2 || n = Hotkey_F3 || n = Hotkey_F11 || n = Hotkey_F12) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F10%, F10Action, Off
  Hotkey_F10 := n
Hotkey, $%Hotkey_F10%, F10Action, On
GuiControl, Main:, BindStatus, F10 已绑定为：%n%
MsgBox, 262144,, F10（快速切断）已绑定为：%n%
return
BindF11:
GuiControlGet, n,, F11Edit
if (n = Hotkey_F11) {
  MsgBox, 262144,, 该键位已经是 F11 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F1 || n = Hotkey_F2 || n = Hotkey_F3 || n = Hotkey_F10 || n = Hotkey_F12) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F11%, F11Action, Off
  Hotkey_F11 := n
Hotkey, $%Hotkey_F11%, F11Action, On
GuiControl, Main:, BindStatus, F11 已绑定为：%n%
MsgBox, 262144,, F11（三四五连卡）已绑定为：%n%
return
BindF12:
GuiControlGet, n,, F12Edit
if (n = Hotkey_F12) {
  MsgBox, 262144,, 该键位已经是 F12 的键位，无需重复绑定！
  return
}
if (!IsKeyValid(n)) {
  MsgBox, 48,, 按键 "%n%" 无效！`n请输入正确的按键名称。
  return
}
if (n = Hotkey_F1 || n = Hotkey_F2 || n = Hotkey_F3 || n = Hotkey_F10 || n = Hotkey_F11) {
  MsgBox, 48,, 该键位已被其他控制键占用！
  return
}
try Hotkey, $%Hotkey_F12%, F12Action, Off
  Hotkey_F12 := n
Hotkey, $%Hotkey_F12%, F12Action, On
GuiControl, Main:, BindStatus, F12 已绑定为：%n%
MsgBox, 262144,, F12（暴力出弯）已绑定为：%n%
return

三十一、功能启停切换函数

各功能独立的开/关切换：注册/注销热键、更新状态颜色与提示；包含连卡开启时默认回到四连等逻辑。

ToggleF10:
ToggleCutFunc()
return
ToggleF11:
ToggleLianKaFunc(true)
return
ToggleF12:
ToggleBaoLiFunc()
return
ToggleBaoLi:
ToggleBaoLiFunc()
return
ToggleBaoLiFunc() {
  global
  baoLiOn := !baoLiOn
  if (baoLiOn) {
    Hotkey, $%Hotkey_BaoLi%, FuncWrapper, On
    SetStateColor("StateB", "已启用", "009933")
    Tooltip, 暴力出弯已开启
    GuiControl, Main:, BindStatus, 暴力出弯已开启
  } else {
    Hotkey, $%Hotkey_BaoLi%, FuncWrapper, Off
    SetStateColor("StateB", "未启用", "FF0000")
    Tooltip, 暴力出弯已关闭
    GuiControl, Main:, BindStatus, 暴力出弯已关闭
  }
  UpdateFKeyStates()
  SetTimer, RemoveTooltip, -1500
}
ToggleWuHen:
wuHenOn := !wuHenOn
if (wuHenOn) {
  Hotkey, $%Hotkey_WuHen%, FuncWrapper, On
  SetStateColor("StateW", "已启用", "009933")
} else {
  Hotkey, $%Hotkey_WuHen%, FuncWrapper, Off
  SetStateColor("StateW", "未启用", "FF0000")
}
return
ToggleSpace:
ToggleCutFunc()
return
ToggleCutFunc() {
  global
  spaceCut := !spaceCut
  if (spaceCut) {
    Hotkey, %Hotkey_Cut%, FuncWrapper, On
    SetStateColor("StateS", "已启用", "009933")
    Tooltip, 快速切断已开启
    GuiControl, Main:, BindStatus, 快速切断已开启
  } else {
    Hotkey, %Hotkey_Cut%, FuncWrapper, Off
    SetStateColor("StateS", "未启用", "FF0000")
    Tooltip, 快速切断已关闭
    GuiControl, Main:, BindStatus, 快速切断已关闭
  }
  UpdateFKeyStates()
  SetTimer, RemoveTooltip, -1500
}
ToggleKaQi1:
kaQi1On := !kaQi1On
if (kaQi1On) {
  if (Hotkey_KaQi1 = "Left" || Hotkey_KaQi1 = "Down") {
  } else {
    Hotkey, $%Hotkey_KaQi1%, FuncWrapper, On
  }
  SetStateColor("StateK1", "已启用", "009933")
} else {
  if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
    Hotkey, $%Hotkey_KaQi1%, FuncWrapper, Off
  }
  SetStateColor("StateK1", "未启用", "FF0000")
}
UpdateFKeyStates()
return
ToggleKaQi2:
kaQi2On := !kaQi2On
if (kaQi2On) {
  if (Hotkey_KaQi2 = "Left" || Hotkey_KaQi2 = "Down") {
  } else {
    Hotkey, $%Hotkey_KaQi2%, FuncWrapper, On
  }
  SetStateColor("StateK2", "已启用", "009933")
} else {
  if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
    Hotkey, $%Hotkey_KaQi2%, FuncWrapper, Off
  }
  SetStateColor("StateK2", "未启用", "FF0000")
}
UpdateFKeyStates()
return
ToggleLianKa:
ToggleLianKaFunc(false)
return
ToggleLianKaFunc(ResetToFour) {
  global
  lianKaOn := !lianKaOn
  if (lianKaOn) {
    if (ResetToFour) {
      LianKaCount := 4
      LianKaCountDesc := "四连"
      if (DelayWindowOpen)
        GuiControl, Delay:, DLK4, 1
      if (OverviewWindowOpen)
        RefreshOverview()
    }
    if (Hotkey_LianKa != "Right") {
      Hotkey, $%Hotkey_LianKa%, FuncWrapper, On
    }
    SetStateColor("StateLK", "已启用", "009933")
    Tooltip, 三四五连卡已开启
    ExtraHint := ResetToFour ? "（默认四连）" : ""
    GuiControl, Main:, BindStatus, 三四五连卡已开启%ExtraHint%
  } else {
    if (Hotkey_LianKa != "Right") {
      Hotkey, $%Hotkey_LianKa%, FuncWrapper, Off
    }
    SetStateColor("StateLK", "未启用", "FF0000")
    Tooltip, 三四五连卡已关闭
    GuiControl, Main:, BindStatus, 三四五连卡已关闭
  }
  SetTimer, RemoveTooltip, -1500
}
ToggleKaQiBothFunc() {
  global
  if (kaQi1On && kaQi2On) {
    kaQi1On := false
    kaQi2On := false
    if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
      Hotkey, $%Hotkey_KaQi1%, FuncWrapper, Off
    }
    if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
      Hotkey, $%Hotkey_KaQi2%, FuncWrapper, Off
    }
    SetStateColor("StateK1", "未启用", "FF0000")
    SetStateColor("StateK2", "未启用", "FF0000")
    Tooltip, 一二段连卡已关闭
    GuiControl, Main:, BindStatus, 一二段连卡已关闭
  } else {
    kaQi1On := true
    kaQi2On := true
    if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
      Hotkey, $%Hotkey_KaQi1%, FuncWrapper, On
    }
    if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
      Hotkey, $%Hotkey_KaQi2%, FuncWrapper, On
    }
    SetStateColor("StateK1", "已启用", "009933")
    SetStateColor("StateK2", "已启用", "009933")
    Tooltip, 一二段连卡已开启
    GuiControl, Main:, BindStatus, 一二段连卡已开启
  }
  UpdateFKeyStates()
  SetTimer, RemoveTooltip, -1500
}

三十二、退出与窗口关闭

退出前解绑全部热键、抬起所有按下的按键；主窗口关闭时走同一退出流程。

ExitApp:
Hotkey, $%Hotkey_BaoLi%, FuncWrapper, Off
Hotkey, $%Hotkey_WuHen%, FuncWrapper, Off
Hotkey, %Hotkey_Cut%, FuncWrapper, Off
if (Hotkey_KaQi1 != "Left" && Hotkey_KaQi1 != "Down") {
  Hotkey, $%Hotkey_KaQi1%, FuncWrapper, Off
}
if (Hotkey_KaQi2 != "Left" && Hotkey_KaQi2 != "Down") {
  Hotkey, $%Hotkey_KaQi2%, FuncWrapper, Off
}
if (Hotkey_LianKa != "Right") {
  Hotkey, $%Hotkey_LianKa%, FuncWrapper, Off
}
Hotkey, $%Hotkey_F1%, F1Action, Off
Hotkey, $%Hotkey_F2%, F2Action, Off
Hotkey, $%Hotkey_F3%, F3Action, Off
Hotkey, $%Hotkey_F10%, F10Action, Off
Hotkey, $%Hotkey_F11%, F11Action, Off
Hotkey, $%Hotkey_F12%, F12Action, Off
Send, {%NitroKey% up}
Send, {%ForwardKey% up}
Send, {%BoostKey% up}
Send, {%DriftKey% up}
ExitApp
GuiClose:
Gosub, ExitApp
return

附：源码规模

原始总行数：1646 行
脚本类型：AutoHotkey v1（.ahk）
配置文件：脚本同目录下 酒窝配置.ini

关于本站

Wed, 04 Nov 2026 16:00:00 GMT

这是博客的介绍页，记录我搭建它的缘由与始末

最初想要一个属于自己的博客，这件事在心里放了很久。

我不是开发者，也没有扎实的前端功底，看不懂复杂的框架源码，写不出精巧的组件。

只是长久以来，一直想要一处安静、干净、贴合自己审美的地方，用来安放文字。

不是社交平台里转瞬就被信息流淹没的动态，不是被算法裹挟、需要迎合他人眼光的内容，只是单纯的、属于我自己的一小块空间。

可以放随笔、旧回忆，记下某一刻冒出来的想法，存一些零散的思考，不必追求流量，不用在意有没有人看。

我尝试想象过它该是什么样子：页面不要花哨，配色克制，排版舒服，文字是这里的主角。不需要繁杂的特效，没有多余的弹窗，打开之后，目光可以自然落在内容上。

但我清楚自己的局限，从零搭建一套静态博客，对我来说门槛太高。Astro、主题、组件、样式、部署，一串陌生名词摆在面前，光是想想就觉得棘手。

我没有能力独立完成一整套框架，很长一段时间里，这个想法就只是安静躺在心里，不知道什么时候才能落地。

后来偶然在 GitHub 闲逛，刷到了 cosZone/astro-koharu 这个仓库。

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

点开预览页的时候，一下子就觉得很合适。

这算是幸运吗？

想来应该算的。茫茫多的开源博客主题里，刚好遇见一个审美契合、结构成熟、文档清晰的模板，不用凭空摸索，省去了大量从零开始的煎熬。

当然，它并不是直接原样照搬上线。拿到仓库之后，我对照着文档，一点点做了一些细微的调整。

大多是很细碎的改动：微调了一点间距，修改了部分文案，调整了侧边栏的展示逻辑，适配我自己的文章分类，修改了描述、标签、封面的配置习惯，适配我写随笔、回忆类内容的需求。

底层的 Astro 结构、主题的核心逻辑、原本的布局框架，我全都保留了，没有做大刀阔斧的重构。

网站左上角有个’Dimple’的雪花svg，我很喜欢。

Dimple = 酒窝

我没有去改动它原本的骨架，只是在这个已经很好的容器里，慢慢打磨成适合我使用的模样。

这就是，站在’前人的肩膀’

部署的过程也不算一帆风顺，踩过不少细碎的小坑：YAML 缩进写错、图片路径不对、分类配置不匹配、构建的时候莫名报错。遇到不懂的地方，就翻仓库的说明，搜零散的教程，一点点试错、回滚、再调整。

好在主题本身的维护很完善，大部分问题都有迹可循。

折腾的过程不算轻松，但每修好一处小问题，看着页面按照预想的样子渲染出来，会有一种淡淡的踏实感。

现在站点终于跑起来了。

它依旧是 astro-koharu，内核没有变，只是被我添上了属于我的痕迹。

这里会放我写的随笔，像之前那篇 2022 年高考阴天的回忆，也会记录日常里零碎的思绪、偶然的感触，一些不适合发在别处的文字。

不追求更新频率，不强迫自己产出，想到什么、想写什么的时候，就坐下来敲一段。

开源的魅力大概就是这样。有人愿意花费时间，写出好看、好用的主题，无偿分享出来，给像我这样不懂开发、只是想拥有一块自留地的人一个机会。

感谢这个主题的作者，把 Koharu 带到 GitHub 上。如果未来你也喜欢这个风格，也可以去仓库看一看。

仓库地址：https://github.com/cosZone/astro-koharu

它没有多么特别，只是一个在现成主题之上，微调出来的、符合我审美的小博客。

一个存放我文字的地方。

一篇 Markdown 在构建时经过了什么

Mon, 11 May 2026 12:05:00 GMT

写主题文档时经常被问到：「为什么这个语法在加密块里也能用？」「链接卡片的数据是什么时候抓的？」答案都藏在构建顺序里。这篇用几张图把一篇 Markdown 文章从源文件到 HTML 的路径画出来。

本文由 AI 根据 astro.config.mjs 的插件注册顺序起草，我核对过顺序并删改了措辞。插件的增减以仓库当前代码为准。

总览

flowchart TD
    A[Markdown 源文件] --> B[frontmatter 校验<br/>content.config.ts]
    B --> C[remark 阶段<br/>处理 Markdown 语法树]
    C --> D[rehype 阶段<br/>处理 HTML 语法树]
    D --> E[Shiki 代码高亮]
    E --> F[页面模板渲染]
    F --> G[Pagefind 建立搜索索引]

frontmatter 先经过 Zod schema 校验。字段写错类型（比如把 tags 写成字符串）会在这一步直接报错，而不是渲染出奇怪的页面。

remark 阶段

remark 处理的是 Markdown 语法树（mdast），这里的顺序有讲究：

flowchart LR
    P[Shoka 预处理] --> M[数学公式]
    M --> S[隐藏文字]
    S --> R[注音 Ruby]
    R --> E[下划线与高亮]
    E --> D[加密块指令]
    D --> L[链接卡片]

Shoka 预处理必须第一个跑。它会重新解析原始文本，修正 GFM 和 Shoka 语法之间的冲突。
数学公式要在注音、隐藏文字之前，否则 $a^b$ 里的 ^ 可能被当成注音语法。
链接卡片在最后，这时段落结构已经稳定，只需要找出「单独成段的链接」。

链接卡片的数据从哪来

sequenceDiagram
    participant B as 构建进程
    participant C as .cache/og-data.json
    participant W as 目标网站
    B->>C: 查询 URL
    alt 缓存有效
        C-->>B: 返回标题、描述、图片
    else 缓存缺失或过期
        B->>W: 请求页面并解析 Open Graph
        W-->>B: OG 信息或错误
        B->>C: 写回缓存
    end
    B->>B: 渲染卡片，失败则保留普通链接

成功的结果默认缓存 30 天（content.previewCacheTime），失败的结果只缓存一天，方便下次构建重试。这个缓存文件是特意提交到 Git 的，CI 上构建时就不必重新抓取。

rehype 阶段

rehype 处理 HTML 语法树（hast）：

给标题生成 id，并附上锚点链接
处理 Shoka 的花括号属性语法（给元素追加 class）
给图片加上低质量占位图（LQIP）
用 KaTeX 渲染公式
最后才是加密：整篇加密和 :::encrypted 块

加密放在最后，是因为它要加密的是已经完全渲染好的 HTML。这也回答了开头的问题：加密块里的代码高亮、公式、链接，在加密之前就已经处理完了。

代码块

代码块由 Shiki 在构建时高亮，所以页面上不需要加载任何高亮脚本。title、mark、command 这些元信息由一个 Shiki transformer 解析：

example.js

const site = 'astro-koharu';
console.log(`Hello from ${site}`);

Mermaid 代码块被排除在 Shiki 之外，交给 Mermaid 单独渲染，本文的几张图就是这样来的。

小结

pie title 一篇文章的处理阶段（按插件数量粗略划分）
    "remark" : 9
    "rehype" : 7
    "Shiki transformer" : 2

记住两条就够用：remark 管语法，rehype 管结构；加密永远在最后。

Shoka 主题 Markdown 语法演示

Sat, 07 Feb 2026 04:00:00 GMT

本文展示了从 Hexo Shoka 主题迁移的所有特殊 Markdown 语法。

文字特效

下划线 (ins)

++这是下划线文字++

++波浪下划线++{.wavy}

++着重点标记++{.dot}

这是下划线文字

波浪下划线

着重点标记

下划线颜色

++主色调++{.primary} ++成功++{.success} ++警告++{.warning} ++危险++{.danger} ++信息++{.info}

主色调成功警告危险信息

高亮 (mark)

==这是高亮文字==

这是高亮文字

上下标

H~2~O 是水的化学式
E = mc^2^ 是质能方程

H₂O 是水的化学式

E = mc² 是质能方程

颜色文字

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow} [绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

红色粉色橙色黄色绿色水色蓝色紫色灰色

彩虹文字

[这段文字会有彩虹渐变效果]{.rainbow}

这段文字会有彩虹渐变效果

键盘键

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

Ctrl + C 复制，Ctrl + V 粘贴

隐藏文字 (Spoiler)

这里有一段!!隐藏文字，鼠标点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

这里有一段隐藏文字，鼠标点击显示

这里有一段模糊文字，鼠标悬停显示

标签块 (Labels)

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info} [成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

默认主要信息成功警告危险

提醒块 (Note Blocks)

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块，用于提供额外信息
:::

:::success
这是成功提醒块，用于正面反馈
:::

:::warning
这是警告提醒块，请注意
:::

:::danger
这是危险提醒块，务必谨慎
:::

:::info no-icon
这是没有图标的信息块
:::

这是默认提醒块

这是主要提醒块，用于重要提示

这是信息提醒块，用于提供额外信息

这是成功提醒块，用于正面反馈

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

这是没有图标的信息块

折叠块 (Collapse)

+++primary 点击展开详细内容
这里是折叠的内容，点击标题可以展开或收起。

支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
这里列出一些需要注意的问题：

1. 注意事项一
2. 注意事项二
+++

+++danger 危险操作
请确保你知道自己在做什么！

```bash
rm -rf /  # 请勿执行此命令
```
+++

点击展开详细内容

这里是折叠的内容，点击标题可以展开或收起。

支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

这里列出一些需要注意的问题：

注意事项一
注意事项二

危险操作

请确保你知道自己在做什么！

rm -rf /  # 请勿执行此命令

标签卡 (Tabs)

;;;tab1 JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;tab1 Python
```python
print('Hello, World!')
```
;;;

;;;tab1 Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

注音

{取り返す^とりかえす}是日语中"取回"的意思。

{漢字^かんじ}的注音示例。

取り返す(とりかえす)是日语中"取回"的意思。

漢字(かんじ)的注音示例。

代码块增强

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

hello.js查看源码

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

数学公式

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=π ∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

友链卡

{% links %}
- site: 余弦の博客
  url: https://blog.cosine.ren
  owner: cos
  desc: FE / ACG / 手工
  image: https://blog.cosine.ren/img/avatar.webp
  color: '#ed788b'
- site: 示例博客
  url: https://example.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

多媒体

音频

{% media audio %}
- name: 示例音频
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

音频歌单

{% media audio %}
- title: 诗岸歌单 山山～全是山山～
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 『诗岸』全是山山！
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频

{% media video %}
- name: "测试 1"
  url: https://cdn.kastatic.org/ka-youtube-converted/O_nY1TM2RZM.mp4/O_nY1TM2RZM.mp4#t=0
- name: "测试 2"
  url: https://cdn.kastatic.org/ka-youtube-converted/O_nY1TM2RZM.mp4/O_nY1TM2RZM.mp4#t=0
{% endmedia %}

练习题

支持四种题型：单选题、多选题、判断题、填空题。

单选题

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

多选题

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库，不属于 CSS 布局。

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库，不属于 CSS 布局。

判断题

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。它没有逻辑控制能力。

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。它没有逻辑控制能力。

填空题

- 在 JavaScript 中，`typeof null` 的结果是 [object]{.gap}。{.quiz .fill}

> 解析：这是一个历史遗留 bug。`null` 的类型标签与 object 相同，因此 `typeof null` 返回 `"object"`。常见错误答案是 [null]{.mistake}。

在 JavaScript 中，typeof null 的结果是 object。

解析：这是一个历史遗留 bug。null 的类型标签与 object 相同，因此 typeof null 返回 "object"。常见错误答案是 null。

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局，而 Float 是传统的布局方式。

解析：Flexbox 是一维布局模型（行或列），Grid 是二维布局模型（行和列同时控制），Float 是 CSS2 时代的传统布局方式。

加密内容块 (Encrypted Block)

使用 :::encrypted{password="密码"} 语法可以创建加密区块。区块内的内容在构建时使用 AES-256-GCM 进行真正加密，密码不会出现在最终的 HTML 中。读者需要输入正确密码才能解密查看。

适用场景：防止搜索引擎/爬虫收录敏感内容（如私人资源链接、付费内容片段等）。

前端无法实现真正意义上的加密：密码总需要在客户端输入，密文和算法都对用户可见，安全性完全取决于密码强度。本功能的目的不是对抗有针对性的破解，而是防止搜索引擎和爬虫直接收录明文内容。对于这个场景，AES-256-GCM 已经足够：构建产物中只有密文，不含密码和明文，搜索引擎无法索引加密区块的内容。


:::encrypted{password="test"}
这里是加密的内容，支持完整的 Markdown 语法：

- **粗体**、*斜体*、~~删除线~~
- `行内代码`
- [链接](https://example.com)

```js
console.log('加密内容中的代码也有语法高亮！');
```

行内公式 $E = mc^2$ 也可以正常渲染。
:::

:::encrypted{password="another"}
每个加密块可以设置独立的密码。
:::

astro-koharu 使用指南

Mon, 29 Dec 2025 13:55:00 GMT

一份完整的 astro-koharu 博客系统使用指南，帮助你快速上手并充分利用所有功能特性。

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

快速开始

项目简介

astro-koharu 是一个基于 Astro 7.x 构建的现代化博客系统，从 Hexo 迁移而来，设计灵感和初衷都来自 Shoka 主题。欢迎 fork 出来制作自己的主题。

核心特点：

基于 Astro 7.x，静态站点生成，性能优异
优雅的深色/浅色主题切换
基于 Pagefind 的无后端全站搜索
完整的 Markdown 增强功能（GFM、代码高亮、自动目录）
灵活的多级分类与标签系统（从 Shoka 主题迁移，后续会考虑将其改为可关闭的）
多系列文章支持（周刊、书摘等自定义系列，支持自定义 URL slug）
响应式设计
草稿与置顶功能
阅读进度条与阅读时间估算
移动端文章阅读头部
友链系统与归档页面
多语言支持（i18n）
RSS 订阅支持
LQIP（低质量图片占位符）
圣诞特辑（可开关）

本地开发

# 克隆项目
git clone https://github.com/cosZone/astro-koharu.git
cd astro-koharu

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

快速部署

使用 Vercel 进行一键部署：

构建缓存说明

项目将 .cache/og-data.json 提交到 Git 仓库。该文件缓存了链接嵌入功能抓取的外部链接 OG 元数据（标题、描述、图片等），提交到 Git 后 Vercel、Netlify 等平台构建时可直接复用，无需每次重新抓取，显著加速构建速度。

.cache/ 目录下的其他文件（如 transformers/ 模型缓存、summaries-cache.json）仍被 .gitignore 忽略，不会提交。

基本配置

站点配置

编辑 config/site.yaml 文件配置站点基本信息：

# =============================================================================
# 站点基础信息
# =============================================================================
site:
  title: 余弦の博客 # 网站标题
  alternate: cosine # 英文短名（用作 logo 文本）
  subtitle: WA 的一声就哭了 # 副标题
  name: cos # 站点作者简称
  description: FE / ACG / 手工 / 深色模式强迫症 / INFP # 站点简介
  avatar: /img/avatar.webp # 头像路径
  showLogo: true # 是否显示 logo
  author: cos # 文章作者
  url: https://blog.cosine.ren/ # 站点域名
  startYear: 2020 # 站点创建年份
  keywords: # SEO 关键词
    - cos
    - cosine
    - 博客
    - 技术
    - 前端

本地轻 CMS 应用

本项目提供独立的 CMS 管理应用，支持文章管理、浏览器内编辑、Markdown 预览等功能。

启动 CMS：

# 首次使用需安装依赖
pnpm cms:install

# 启动 CMS（默认端口 4322）
pnpm cms

CMS 提供以下功能：

📊 文章仪表盘：查看文章统计、分类分布、最近更新
📝 浏览器内编辑器：与公开写作室共用 CodeMirror 源码编辑、Shoka 实时预览及中文语法手册，CMS 可保存完整 Markdown 原文
🔄 草稿/发布切换：一键切换文章状态
📌 置顶管理：快速置顶/取消置顶文章
➕ 新建文章：交互式创建文章，自动生成 frontmatter

本地编辑器跳转

开发环境下，文章页「复制 Markdown」按钮组的下拉菜单支持一键跳转到本地编辑器（VS Code / Cursor / Zed 等）。

配置文件： config/site.yaml 的 dev 部分

dev:
  localProjectPath: "/Users/yourname/path/to/astro-koharu" # 本地项目绝对路径
  contentRelativePath: "src/content/blog" # 博客内容目录
  editors:
    - id: vscode
      name: VS Code
      icon: devicon-plain:vscode # 可从 https://icon-sets.iconify.design/ 搜寻图标
      urlTemplate: "vscode://file/{path}"
    - id: cursor
      name: Cursor
      icon: simple-icons:cursor
      urlTemplate: "cursor://file/{path}"
    - id: zed
      name: Zed
      icon: simple-icons:zedindustries
      urlTemplate: "zed://file/{path}"

配置说明：

localProjectPath 必须是本机的绝对路径，否则无法生成正确的文件路径
urlTemplate 支持占位符，会被替换为文件的完整路径
配置后，开发环境的文章页下拉菜单会列出这些编辑器，点击可直接在本地编辑器中打开文件

特色分类配置：

在首页底部展示的精选分类卡片：

featuredCategories:
  - link: life # 分类链接（对应 category_map）
    label: 随笔 # 显示名称
    image: /img/cover/2.webp # 封面图片
    description: 生活记录、年度总结等 # 描述
  - link: note/front-end
    label: 前端笔记
    image: /img/cover/1.webp
    description: 前端相关的笔记
  # ... 更多分类

多系列文章配置：

配置特色系列（如周刊、书摘等），支持多个系列，每个系列拥有独立页面和自定义 URL：

featuredSeries:
  - slug: weekly # URL 路径: /weekly（必填，作为页面路由）
    categoryName: 周刊 # 分类名称（用于匹配文章）
    label: FE Bits # 显示标签
    fullName: FE Bits 前端周周谈 # 完整名称
    description: | # 描述（支持多行）
      之前在自己的频道进行一些输出，于是有了这个周刊！
      更新时间期望是在每周天
    cover: /img/weekly_header.webp # 封面图
    enabled: true # 是否启用
    icon: ri:newspaper-line # 导航图标（可选）
    highlightOnHome: true # 是否在首页高亮最新文章（可选，默认 true）
    links: # 相关链接
      github: https://github.com/your-username/your-repo
      rss: /rss.xml

  - slug: reading # URL 路径: /reading
    categoryName: 书摘
    label: 读书笔记
    fullName: 我的读书笔记
    description: 读书摘录与感悟
    cover: /img/reading_header.webp
    enabled: true
    highlightOnHome: false # 此系列不在首页高亮

字段说明：

字段	必填	说明
`slug`	✅	URL 路径，如 `weekly` 对应 `/weekly`
`categoryName`	✅	分类名称，用于匹配文章
`label`	❌	显示标签（默认使用 categoryName）
`enabled`	❌	是否启用此系列（默认 true）
`fullName`	❌	完整名称（用于页面标题）
`description`	❌	系列描述
`cover`	❌	封面图片路径
`icon`	❌	导航图标（Iconify 格式）
`highlightOnHome`	❌	是否在首页高亮最新文章（默认 true）
`links`	❌	相关链接（github、rss 等）

社交媒体配置

在 config/site.yaml 中配置社交媒体链接：

social:
  github:
    url: https://github.com/your-username
    icon: ri:github-fill # Iconify 图标名
    color: "#191717" # 主题色
  bilibili:
    url: https://space.bilibili.com/your-uid
    icon: ri:bilibili-fill
    color: "#da708a"
  email:
    url: mailto:your@email.com
    icon: ri:mail-line
    color: "#55acd5"
  rss:
    url: /rss.xml
    icon: ri:rss-line
    color: "#ff6600"
  # ... 更多平台

支持的平台：GitHub, Twitter, Bilibili, 网易云音乐, Email, RSS 等。完整配置请参考 config/site.yaml 文件。

导航配置

在 config/site.yaml 中自定义导航菜单：

navigation:
  - name: 首页
    path: /
    icon: fa6-solid:house-chimney
  - name: 周刊
    path: /weekly # 对应 featuredSeries 中 slug: weekly 的系列
    icon: ri:newspaper-line
  - name: 读书笔记
    path: /reading # 对应 featuredSeries 中 slug: reading 的系列
    icon: ri:book-open-line
  - name: 文章
    icon: ri:quill-pen-ai-fill
    children: # 支持嵌套子菜单
      - name: 分类
        path: /categories
        icon: ri:grid-fill
      - name: 标签
        path: /tags
        icon: fa6-solid:tags
      - name: 归档
        path: /archives
        icon: ri:archive-2-fill
  - name: 友链
    path: /friends
    icon: ri:links-line
  - name: 关于
    path: /about
    icon: fa6-regular:circle-user

注意：系列页面的路径格式为 /{slug}，需要与 featuredSeries 中配置的 slug 字段一致。

分类映射配置

在 config/site.yaml 中配置中文分类名到 URL slug 的映射：

# =============================================================================
# Category Map
# Maps Chinese category names to URL-friendly English slugs
# =============================================================================
categoryMap:
  # Primary categories
  随笔: life
  笔记: note
  工具: tools
  周刊: weekly # 用于分类页面 /categories/weekly
  书摘: reading # 用于分类页面 /categories/reading
  # Secondary categories (for nested paths)
  前端: front-end
  # Add more as needed:
  # 后端: back-end
  # 算法: algorithm

这样，"随笔" 分类的 URL 会是 /categories/life，而不是 /categories/随笔。

注意：categoryMap 仅用于分类页面（/categories/*）的 URL 映射。系列页面的 URL（如 /weekly、/reading）由 featuredSeries 中的 slug 字段单独配置。

文章系统

创建文章

方式一：使用 Koharu CLI（推荐）

使用交互式 CLI 工具快速创建文章：

pnpm koharu new post

CLI 工具会引导你输入标题、分类、标签等信息，自动生成 frontmatter 和 markdown 文件。

方式二：手动创建

在 src/content/blog/ 目录下创建 Markdown 文件。目录结构会影响文章的分类：

src/content/blog/
├── life/              # 随笔分类
│   └── 2024-life-review.md
├── note/
│   ├── front-end/     # 笔记 > 前端
│   │   └── react/
│   │       └── React学习小记.md
│   └── algorithm/     # 笔记 > 算法
│       └── 动态规划学习笔记.md
└── tools/             # 工具分类
    └── vscode插件推荐.md

Frontmatter 字段说明

每篇文章开头需要包含 YAML frontmatter：

必填字段：

---
title: 文章标题 # 必填
date: 2024-12-06 # 必填，发布日期
---

常用可选字段：

---
title: 文章标题
date: 2024-12-06
updated: 2024-12-15 # 最近更新时间（可选，存在时会在文章页显示）
description: 文章摘要描述 # 用于 SEO 和列表展示，如不填写会自动使用 AI 摘要或提取正文前 150 字
link: custom-url-slug # 自定义 URL（默认使用文件名）
cover: /img/cover/1.webp # 封面图片
tags: # 标签列表
  - JavaScript
  - React
categories: # 分类（见下方详细说明）
  - 笔记
subtitle: 副标题 # 文章副标题
catalog: true # 是否计入分类页的分类树与篇数（默认 true）
tocNumbering: true # 是否显示目录编号（默认 true）
draft: false # 是否为草稿（默认 false）
sticky: false # 是否置顶（默认 false）
excludeFromSummary: false # 是否排除 AI 摘要和相似度计算（默认 false，系列文章建议设为 true）
math: false # 是否启用数学公式渲染（默认 false，启用后支持 KaTeX）
quiz: false # 是否启用练习题交互（默认 false，启用后支持四种题型）
password: mySecret # 整篇文章加密密码（可选，设置后整篇文章需输入密码才能阅读）
keywords: # 文章关键词（可选）
colophon: # 文章落款（可选，见下方「文章落款」）
  - handwritten
---

关于 description 字段：

文章描述的优先级：手写 description > AI 自动摘要 > Markdown 正文前 150 字

建议为重要文章手写描述，以获得更好的 SEO 效果
如果省略描述，系统会自动使用 AI 生成的摘要（需运行 pnpm generate:summaries）
如果既没有手写描述也没有 AI 摘要，则自动提取文章正文的前 150 个字符

关于 link 字段（自定义 URL）：

⚠️ 重要：link 字段会被自动转换为小写，以保持 URL 的一致性和规范性。

规范化行为：无论你输入 MyPost、myPost 还是 mypost，最终 URL 都会是 /post/mypost
文件名大小写无关：文章文件名可以使用任意大小写（如 MyPost.md），系统会自动处理
AI 摘要和相似度：生成的 summaries.json 和 similarities.json 中的 key 也会统一为小写
最佳实践：建议直接使用小写和连字符（如 my-awesome-post），避免混淆

# ✅ 推荐写法
link: my-awesome-post  # URL: /post/my-awesome-post

# ⚠️ 会被转为小写
link: MyAwesomePost    # URL: /post/myawesomepost（不是 /post/MyAwesomePost）
link: My-Awesome-Post  # URL: /post/my-awesome-post

如果省略 link 字段，系统会使用文件名（同样会转为小写）：

# 文件: src/content/blog/MyPost.md
# 省略 link 字段 → URL: /post/mypost

分类系统

astro-koharu 支持灵活的分类配置：

单层分类：

categories:
  - 工具 # 或者 ['工具']

对应 URL: /categories/tools（根据 categoryMap 映射）

多层嵌套分类：

categories:
  - [笔记, 前端, React]

这会创建层级关系：笔记 → 前端 → React

对应 URL: /categories/note/front-end/react

标签系统

标签是扁平的，不支持层级：

tags:
  - JavaScript
  - TypeScript
  - 学习笔记

所有标签会在 /tags 页面展示，点击标签可查看该标签下的所有文章。

草稿功能

设置 draft: true 将文章标记为草稿：

---
title: 未完成的文章
draft: true
---

行为：

本地开发 (pnpm dev)：草稿可见，文章卡片右上角显示 "DRAFT" 标识
生产构建 (pnpm build)：草稿自动过滤，不会出现在任何列表中

置顶功能

设置 sticky: true 将文章置顶：

---
title: 重要公告
sticky: true
---

行为：

置顶文章显示在首页 "置顶文章" 区域
置顶文章按日期排序（最新的在前）
不影响其他页面（分类、标签、归档）的排序

系列文章

配置了 featuredSeries 的系列（见基本配置），其分类下的文章会：

拥有专属的系列页面（URL 由 slug 决定，如 /weekly、/reading）
不出现在普通文章列表（/posts）中
如果系列设置了 highlightOnHome: true，最新一篇会在首页高亮显示

示例：

---
title: FE Bits Vol.16
categories:
  - 周刊 # 对应某个 featuredSeries 的 categoryName
excludeFromSummary: true # 可选：排除 AI 摘要生成
---

---
title: 《代码大全》读书笔记
categories:
  - 书摘 # 对应另一个 featuredSeries 的 categoryName
---

提示：文章的 categories 字段需要与 featuredSeries 中某个系列的 categoryName 匹配才会被归入该系列。

独立页面

除了博客文章外，你可以在 src/pages/ 目录下创建 .md 文件来添加独立页面（如"关于"、"歌单"等）。这些页面使用 PageLayout.astro 布局，支持完整的 Markdown 增强语法。

创建独立页面：

在 src/pages/ 目录下新建 .md 文件：

---
layout: ../layouts/PageLayout.astro
title: "歌单"
description: "我喜欢的音乐"
coverTitle: "我的歌单"
comments: false
---

页面内容...

Frontmatter 字段：

字段	必填	说明
`layout`	✅	固定为 `../layouts/PageLayout.astro`
`title`	✅	页面标题（用于浏览器标签页）
`description`	❌	页面描述（用于 SEO）
`coverTitle`	❌	封面显示的标题（默认使用 `title`）
`comments`	❌	是否显示评论区（默认 `true`）

添加导航入口：

在 config/site.yaml 的 navigation 中添加对应菜单项：

navigation:
  # ...
  - name: 歌单
    path: /music
    icon: ri:music-2-fill

提示：src/pages/ 下所有 .md 文件会被 Koharu CLI 的备份功能自动覆盖，无需额外配置。

界面功能

主题切换

点击右上角的太阳/月亮图标切换深色/浅色模式。

代码高亮：

浅色模式：github-light
深色模式：github-dark

全站搜索

基于 Pagefind 的静态站点搜索，无需后端服务器。

打开搜索：

点击导航栏搜索图标
快捷键：Cmd/Ctrl + K

特性：

支持中文分词
实时搜索结果
高亮匹配关键词
显示文章摘要和元信息

文章阅读功能

目录导航 (Table of Contents)：

自动提取文章标题（h2-h6）生成目录
使用 CSS 计数器自动为标题添加层级编号（如 1., 1.1., 1.1.1.）
支持通过 frontmatter 的 tocNumbering: false 字段关闭编号显示
点击目录项跳转到对应章节
滚动时自动高亮当前章节
桌面端显示在右侧边栏，移动端折叠

目录编号控制：

---
title: 我的文章
tocNumbering: false # 关闭目录编号（默认为 true）
---

默认情况下，所有文章的目录都会显示层级编号
设置 tocNumbering: false 可以关闭特定文章的编号显示
编号通过 CSS 计数器实现，零运行时开销
同时适用于桌面端侧边栏和移动端下拉目录

阅读进度条：

页面顶部显示阅读进度
实时更新当前阅读位置

标题锚点链接：

每个标题自动生成 ID
悬停标题时显示 # 链接图标
点击可复制带锚点的 URL

系列文章导航：

基于最深层分类自动分组
按发布日期排序
显示文章标题和封面

阅读时间估算：

文章卡片显示预计阅读时间（基于字数计算）。

移动端文章阅读头部：

在移动端（≤992px）浏览文章时，顶部导航栏会显示专为阅读优化的头部：

圆形阅读进度 - 实时显示当前阅读进度的圆形进度条
当前章节标题 - 显示当前所在的 H2/H3 章节标题，切换时带有平滑动画
可展开目录 - 点击标题区域可展开完整的文章目录，快速跳转到任意章节

特性：

滚动时自动更新当前章节
支持 prefers-reduced-motion 减少动画

文章落款

落款用来告诉读者一篇文章是怎么写出来的、读之前要注意什么，比如「手写」「与 AI 合写」「含剧透」「可能已过时」。标记的字典定义在 config/site.yaml 的 colophon 段，文章在 frontmatter 里按 id 引用：

---
title: 我的文章
colophon:
  - ai-cowrite # 直接引用字典里的标记
  - { id: spoiler, note: 含《我推的孩子》第二季剧透 } # note 是本篇自己的补充说明
  - { icon: 'fa6-solid:mug-hot', label: 两杯咖啡 } # 一次性标记，不进字典
---

字典的结构：

config/site.yaml

colophon:
  enabled: true
  groups:
    authorship:
      label: 执笔
      exclusive: true # 互斥组：一篇文章只能选一个
      placement: [meta, seal, card]
    notice:
      label: 阅读提示
      placement: [meta, banner]
  marks:
    handwritten:
      group: authorship
      icon: ri:quill-pen-line
      label: 手写
      description: 每个字都是我自己敲的。
    spoiler:
      group: notice
      icon: ri:eye-off-line
      label: 含剧透
      tone: warn # muted（默认）| accent | warn

默认标记：handwritten（手写）、ai-cowrite（与 AI 合写）、ai-lead（AI 主笔）属于互斥的「执笔」组；spoiler（含剧透）、outdated（可能已过时）属于「阅读提示」组
显示位置（placement）：meta 封面信息行、banner 正文前的提示条、seal 文末落款、card 文章列表卡片。标记上的设置优先于分组
图标：只能使用 ri、fa6-solid、fa6-regular、gg 四套 Iconify 图标，一次性标记也一样
多语言：在 config/i18n-content.yaml 的 <locale>.colophon 下覆盖分组和标记的文案
默认标记（defaults）：文章没有某一组的标记时自动补上，主题默认 defaults: [handwritten]，没写执笔的文章都显示「手写」。不想显示任何标记的文章写 colophon: []
删掉整个 colophon 配置段即可关闭此功能

站内的示例文章：《我推的孩子》第二季观后感（手写 + 含剧透）、Tailwind CSS v4 升级笔记（可能已过时）、一篇 Markdown 在构建时经过了什么（AI 主笔）、容器查询实战（与 AI 合写 + 一次性标记）。

文章操作：复制 Markdown 与在写作室打开

文章页面包屑右侧有一组操作按钮：

复制 Markdown：复制整篇文章的原始 Markdown，包括 frontmatter
下载：把原文保存为 .md 文件
在写作室打开：在写作室里打开这篇文章继续编辑

config/site.yaml

postActions:
  copyMarkdown: true
  downloadMarkdown: true
  openInEditor: everyone # off | dev | everyone

openInEditor 的三个取值：off 不显示；dev 只在本地开发服务器显示；everyone 对所有访客显示，访客打开的是一份浏览器里的草稿副本，不会改动博客本身。这个按钮还要求 editor.enabled: true，写作室没开启时不会出现。

设置了 password 的整篇加密文章，以及正文里含 :::encrypted 局部加密块的文章，都不提供原文，也不显示这些按钮，避免明文和密码随源文件公开。

响应式设计

桌面端：

双栏布局（主内容 + 侧边栏）
固定导航栏
悬浮目录

平板：

自适应布局调整
简化侧边栏

移动端：

单栏布局
抽屉式导航菜单（汉堡菜单）
折叠式目录
触摸优化的交互
文章页专属阅读头部（进度圈 + 当前标题 + 可展开目录）

特色功能

系列文章系统

featuredSeries 支持配置多个系列，每个系列会自动生成独立页面：

专属系列页面 (/{slug})：

每个启用的系列都有独立页面（如 /weekly、/reading）
显示该系列的所有文章
系列头图和介绍
相关链接（GitHub, RSS 等）

首页展示：

设置 highlightOnHome: true 的系列，其最新文章会在首页高亮显示
设置 highlightOnHome: false 的系列不在首页展示
所有系列文章独立于普通文章列表

💡 设计说明：分离关注点

featuredSeries 的设计初衷是将高产出分类从首页分离，避免首页被单一类型文章刷屏。适用场景：

周刊/日记：更新频繁，数量庞大

读书笔记/书摘：独立成系列，方便按系列浏览

任何文章数量较多的分类：当某分类文章数量远超其他分类时

首页行为：

系列文章从首页主列表排除

设置 highlightOnHome: true 时，最新一篇在首页顶部高亮

其余文章通过系列专属页面（如 /weekly）访问

其他页面正常展示：系列文章在归档、分类、标签、搜索等页面仍与普通文章一起显示，仅首页主列表做了分离。

配置示例：

featuredSeries:
  - slug: weekly
    categoryName: 周刊
    highlightOnHome: true # 首页展示最新周刊
    # ...
  - slug: reading
    categoryName: 书摘
    highlightOnHome: false # 不在首页展示
    # ...

归档页面

访问 /archives 查看所有文章的归档视图：

按年份分组
显示每年的文章数量
时间线式展示
包含文章发布日期、标题、分类

友链系统

访问 /friends 查看友情链接页面：

功能：

友链卡片展示
友链申请表单（可自定义）
支持头像、名称、描述、链接

LQIP（低质量图片占位符）

LQIP（Low Quality Image Placeholder）是一种图片加载优化技术，在高清图片加载完成前，先显示一个低质量的占位符，避免页面出现空白或布局抖动。

特性：

🎨 构建时自动提取图片主色调，生成 CSS 渐变占位符
⚡ 零运行时开销 —— 纯 CSS 实现，无需 JavaScript 解码
📦 极小数据体积 —— 每张图片仅需 18 字符存储
🔄 外部图片自动降级为纯色占位符

支持的组件：

文章卡片封面 (PostItemCard)
页面横幅 (Cover)
分类卡片背景 (CategoryCards)
系列封面 (SeriesCover)
侧边栏头像 (HomeInfo)

使用方式：

# 生成 LQIP 数据（处理 public/img/ 下所有图片）
pnpm generate:lqips

生成效果：

LQIP 数据保存在 src/assets/lqips.json，格式如下：

{
  "cover/1.webp": "87a3c4c2dfefbddae9",
  "cover/2.webp": "6e3b38ae7472af7574"
}

每个值是 18 个十六进制字符（3 个颜色），运行时解码为 CSS 渐变：

linear-gradient(135deg, #87a3c4 0%, #c2dfef 50%, #bddae9 100%)

原理：

使用 sharp 将图片缩放到 2×2 像素
提取四象限的平均色（左上、右上、左下、右下）
选取 3 个颜色生成 135 度斜向渐变
存储为紧凑的十六进制字符串

在组件中使用：

---
import { getLqipStyle, getLqipProps } from '@lib/lqip';

// 方式 1：直接获取样式字符串
const style = getLqipStyle('/img/cover/1.webp');
// 返回: "background-image:linear-gradient(...)"

// 方式 2：获取完整的 props（支持外部图片降级）
const lqipProps = getLqipProps(coverUrl);
// 本地图片返回: { style: "background-image:..." }
// 外部图片返回: { class: "lqip-fallback" }
---

<div style={style}>
  <img src="/img/cover/1.webp" />
</div>

注意事项：

生成的 src/assets/lqips.json 需要提交到 git
添加新图片后需要重新运行 pnpm generate:lqips
外部图片（http/https 开头）会自动使用纯色占位符降级

模型	大小	维度	优势
`Snowflake/snowflake-arctic-embed-m-v2.0`	~90MB	768	质量高，中英文均衡
`sentence-transformers/all-MiniLM-L6-v2`	~23MB	384	轻量快速
`BAAI/bge-small-zh-v1.5`	~95MB	512	中文专用

AI 自动摘要

基于 transformers.js 的智能摘要生成系统，使用先进的 AI 模型为文章自动生成高质量摘要。

与相关文章推荐的关系：

AI 摘要功能与相关文章推荐功能相辅相成：

相似度计算需要读取文章全文，计算成本较高（约 3-5 分钟）
AI 摘要可以在不读取全文的情况下提供优质描述，同时生成的摘要也能帮助改善相似度计算的效果
两者共享相同的模型缓存机制，节省存储空间

特性：

🤖 基于先进的文本生成模型（Xenova/LaMini-Flan-T5-783M）
📝 自动为缺少描述的文章生成摘要
✨ 文章详情页支持打字机动画展示，增强阅读体验
🎯 智能 fallback：优先使用手写 description，无描述时自动使用 AI 摘要
🚀 构建时预生成，运行时零开销
♿ 支持无障碍访问和 prefers-reduced-motion

使用方式：

# 生成 AI 摘要（本地运行，首次会下载模型，约需 5-10 分钟）
pnpm generate:summaries

# 生成的文件要提交到 git，然后可以在 Vercel 等平台直接使用

生成效果：

AI 摘要会保存在 src/assets/summaries.json 文件中，格式如下：

{
  "article-slug": {
    "title": "文章标题",
    "summary": "AI 生成的摘要内容..."
  }
}

在哪里使用：

文章详情页：面包屑导航下方显示可折叠的 AI 摘要卡片
- 默认收起状态，点击"展开"按钮触发
- 展开后以打字机动画逐字显示摘要内容
- 打字机动画仅播放一次，支持 prefers-reduced-motion 用户偏好
文章卡片：作为描述的 fallback
- 优先级：手写 description > AI 摘要 > Markdown 前 150 字
- 在文章列表、首页、分类页等处自动使用

模型选择：

默认使用 Xenova/LaMini-Flan-T5-783M 模型：

模型大小：约 300MB（首次运行会自动下载到 .cache/transformers 目录）
生成质量：高质量的中英文摘要生成
生成时间：约 5-10 分钟（169 篇文章）

如需更换模型，编辑 src/scripts/generateSummaries.ts 中的 MODEL_NAME：

const MODEL_NAME = "Xenova/LaMini-Flan-T5-783M";
// 可选替代方案：
// const MODEL_NAME = 'Xenova/distilbart-cnn-6-6'; // 更快，英文效果好
// const MODEL_NAME = 'facebook/bart-large-cnn';   // 质量更高，但速度较慢

配置提示词：

可以自定义生成摘要的提示词，编辑 src/scripts/generateSummaries.ts 中的 PROMPT_TEMPLATE：

const PROMPT_TEMPLATE = (title: string, content: string) =>
  `请为以下文章生成一段简洁的摘要（100-150字）：\n\n标题：${title}\n\n内容：${content}`;

注意事项：

需要本地运行生成脚本（Vercel 等平台无法运行大模型）
生成的 src/assets/summaries.json 需要提交到 git
如果没有生成摘要文件，会自动 fallback 到 Markdown 文本提取
模型文件会缓存在 .cache/transformers 目录（已添加到 .gitignore）
首次运行需要下载模型，建议在网络良好的环境下进行

最佳实践：

与相似度计算配合使用：

# 先生成摘要
pnpm generate:summaries
# 再计算相似度（可以使用摘要代替全文，提升速度）
pnpm generate:similarities

选择性生成摘要：为了节省时间，脚本会跳过已有 description 的文章
提交到版本控制：将生成的 JSON 文件提交到 git，避免在 CI/CD 环境重复生成

圣诞特辑

节日限定的圣诞氛围特效系统，包含多种可独立开关的视觉效果，为博客增添节日气氛。

特性：

雪花飘落 —— Canvas 实现的雪花动画，分前景和背景两层，支持视差效果
圣诞配色 —— 红绿金主题色替换默认粉蓝配色，支持深色/浅色模式
圣诞帽装饰 —— 侧边栏头像上的圣诞帽
圣诞灯串 —— Header 顶部的装饰灯串动画
圣诞饰品切换 —— 导航栏的装饰饰品
运行时开关 —— 右下角浮动按钮可随时切换特效，设置自动保存

配置方式：

编辑 config/site.yaml 中的 christmas 配置：

christmas:
  enabled: true # 总开关
  features:
    snowfall: true # 雪花飘落
    christmasColorScheme: true # 圣诞配色
    christmasCoverDecoration: true # 灯串装饰
    christmasHat: true # 圣诞帽
    readingTimeSnow: true # 阅读时间雪花特效
  snowfall:
    speed: 0.5 # 飘落速度（默认 0.5）
    intensity: 0.7 # 桌面端雪花密度（0-1）
    mobileIntensity: 0.4 # 移动端雪花密度（0-1）
    maxLayers: 6 # 最大雪花层数
    maxIterations: 8 # 最大迭代次数
    mobileMaxLayers: 4 # 移动端最大层数
    mobileMaxIterations: 6 # 移动端最大迭代次数

用户控制：

页面右下角悬浮按钮（雪花图标）可切换圣诞特效开关
用户偏好自动保存到 localStorage，跨会话保持
支持 prefers-reduced-motion 偏好，自动禁用动画

技术实现：

雪花使用 Canvas 2D 渲染，分层实现视差效果
配色通过 CSS 变量覆盖，零运行时开销
状态管理使用 nanostores，支持跨组件同步
完全响应式，移动端自动降低雪花密度

关闭圣诞特效：

设置 christmasConfig.enabled = false 即可完全关闭所有圣诞特效。

站点公告系统

无后端的站点公告系统，支持在配置文件中管理公告，首次访问自动弹出，关闭后可通过页脚入口再次查看。

特性：

无后端 —— 公告内容写在配置文件，无需数据库
Toast 通知 —— 右下角浮动通知，支持多条堆叠显示
多条公告 —— 支持配置多条公告，按优先级排序
时间控制 —— 支持设置公告的开始/结束日期，自动控制显示
自定义颜色 —— 每条公告可设置独立颜色，覆盖默认类型颜色
时间线弹窗 —— 公告列表采用时间线样式，带渐变连接线
Hover 已读 —— 悬停 Toast 1 秒后自动标记已读
已读追踪 —— localStorage 记录已读状态，返回访问不重复弹出
再次查看 —— 页脚入口可随时查看所有公告，带未读红点提示

配置方式：

编辑 config/site.yaml 添加公告：

announcements:
  - id: welcome-2026 # 唯一标识
    title: 2026 年新年快乐! # 公告标题
    content: 新年快乐! 感谢大家一直以来的支持~ # 公告内容
    type: info # 类型：info | warning | success | important
    priority: 300 # 优先级（越高越先显示）
    color: "#ED788C" # 自定义颜色（可选，覆盖 type 默认色）
    publishDate: "2026-01-01" # 显示日期（可选，用于时间线展示）
    startDate: "2025-12-31T00:00:00+08:00" # 开始日期（可选）
    endDate: "2026-01-15T23:59:59+08:00" # 结束日期（可选）
  - id: site-update-01
    title: 站点更新公告
    content: 新增站点公告系统，现在支持多条公告同时显示！
    type: info
    priority: 500
    color: "#6366F1"
    publishDate: "2025-01-02"

如果需要添加链接（可选）：

announcements:
  - id: example-with-link
    title: 示例公告
    content: 公告内容
    type: info
    link:
      url: https://example.com
      text: 了解更多
      external: true

公告类型样式：

类型	说明	默认颜色
`info`	信息通知	蓝色 (#3b82f6)
`warning`	警告提示	黄色 (#eab308)
`success`	成功消息	绿色 (#22c55e)
`important`	重要公告	红色 (#ef4444)

设置 color 字段可覆盖上述默认颜色

交互流程：

首次访问：0.5 秒后自动弹出未读公告 Toast（多条堆叠显示）
Hover 已读：悬停在 Toast 上 1 秒后自动标记已读
手动关闭：点击 Dismiss 关闭 Toast
点击"View all"：关闭所有 Toast，打开时间线弹窗
时间线弹窗：点击公告卡片标记已读，显示发布日期和渐变连接线
页脚入口：随时可点击查看所有公告，未读时显示红点
返回访问：只显示真正未读的公告

注意事项：

公告 id 必须唯一，用于追踪已读状态
省略 startDate 表示立即生效，省略 endDate 表示永不过期
publishDate 用于时间线弹窗中的日期显示，省略时使用 startDate
过期公告建议从配置中删除，保持配置简洁
已读状态存储在 localStorage，key 为 announcement-read-ids:v1（旧 key 会自动迁移）

Markdown 增强

语法支持：

GitHub Flavored Markdown (GFM)
- 表格
- 任务列表
- 删除线
- 自动链接

Mermaid 图表：

支持在 Markdown 中使用 Mermaid 语法绘制流程图、时序图、架构图等。

```mermaid
flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]
```

flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]

支持的图表类型：

flowchart / graph - 流程图
sequenceDiagram - 时序图
classDiagram - 类图
stateDiagram - 状态图
erDiagram - ER 图
gantt - 甘特图
pie - 饼图
mindmap - 思维导图

图表会自动跟随深色/浅色主题切换。更多语法参考 Mermaid 官方文档。

Infographic 信息图：

支持使用 @antv/infographic 在 Markdown 中绘制精美的信息图表，适合展示流程、对比、层级、统计等数据。

使用方式：在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
```

infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch

可用模板类型：

列表类 (list-*)：展示信息列表
- list-grid-badge-card - 卡片网格布局
- list-grid-candy-card-lite - 糖果风格卡片
- list-row-horizontal-icon-arrow - 水平图标箭头列表
流程/顺序类 (sequence-*)：展示步骤、流程或阶段
- sequence-zigzag-steps-underline-text - 之字形步骤
- sequence-circular-simple - 圆形流程
- sequence-roadmap-vertical-simple - 垂直路线图
- sequence-pyramid-simple - 金字塔结构
对比类 (compare-*)：二元或多元对比
- compare-binary-horizontal-simple-fold - 水平二元对比
- compare-swot - SWOT 分析
- compare-hierarchy-left-right-circle-node-pill-badge - 层级左右对比
层级类 (hierarchy-*)：展示树形结构
- hierarchy-tree-tech-style-capsule-item - 科技风格树形图
- hierarchy-tree-curved-line-rounded-rect-node - 曲线连接树形图
图表类 (chart-*)：数据可视化
- chart-column-simple - 柱状图
- chart-bar-plain-text - 条形图
- chart-pie-plain-text - 饼图
- chart-line-plain-text - 折线图
其他
- quadrant-* - 象限分析图
- relation-* - 关系图

数据字段说明：

title - 标题（可选）
desc - 描述文本（可选）
items - 条目数组，每个条目可包含：
- label - 主标签文本
- value - 数值（用于图表类模板）
- desc - 描述文本
- icon - 图标名称（格式：mdi/icon-name）
- children - 子条目（用于层级结构）

主题定制：

可以在数据后添加 theme 块自定义颜色：

```infographic
infographic sequence-pyramid-simple
data
  items
    - label 基础层
    - label 中间层
    - label 顶层
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
```

信息图会自动跟随深色/浅色主题切换，并使用项目的寒蝉全圆体字体渲染。更多模板和语法参考 Infographic 官方文档。

代码高亮：

基于 Shiki
支持双主题（深色/浅色）
支持语言标注
行号显示

示例：

```javascript
function hello() {
  console.log("Hello, world!");
}
```

function hello() {
  console.log("Hello, world!");
}

标题自动链接：

所有标题自动生成可点击的锚点链接。

链接自动嵌入：

独行的特殊链接会自动转换为嵌入组件：

Twitter/X 链接：自动嵌入 Tweet 组件
CodePen 链接：自动嵌入交互式 CodePen 演示
其他链接：显示 OG 预览卡片（包含标题、描述、图片等）

示例：

<!-- 独行链接会被嵌入 -->

https://x.com/vercel_dev/status/1997059920936775706

https://codepen.io/botteu/pen/YPKBrJX/

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

<!-- 段落中的链接保持不变 -->

这是一个 [普通链接](https://example.com)，不会被嵌入。

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

这是一个普通链接，不会被嵌入。

Shoka 兼容 Markdown 语法：

astro-koharu 从 Hexo Shoka 主题迁移了一套丰富的 Markdown 扩展语法，所有功能均可通过 config/site.yaml 的 content 配置项独立开关。

文字特效（enableShokaEffects）：

支持多种行内文字装饰效果：

语法	效果	说明
`++文字++`	下划线	`<ins>` 标签
`++文字++{.wavy}`	波浪下划线	支持 `.wavy` 修饰符
`++文字++{.dot}`	着重点	支持 `.dot` 修饰符
`++文字++{.primary}`	彩色下划线	支持 `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	高亮	`<mark>` 标签
`~文字~`	下标	`<sub>` 标签，如 H₂O
`^文字^`	上标	`<sup>` 标签，如 E=mc²

示例效果：

这是下划线文字波浪下划线着重点标记

主色调成功警告危险信息

这是高亮文字

H₂O 是水的化学式，E = mc² 是质能方程

颜色文字与特殊样式（enableShokaAttrs）：

使用 文字 语法为文字添加颜色和样式：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow}
[绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

[这段文字会有彩虹渐变效果]{.rainbow}

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info}
[成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

示例效果：

红色粉色橙色黄色绿色水色蓝色紫色灰色

这段文字会有彩虹渐变效果

Ctrl + C 复制，Ctrl + V 粘贴

默认主要信息成功警告危险

隐藏文字 / Spoiler（enableShokaSpoiler）：

这里有一段!!隐藏文字，点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

示例效果：

这里有一段隐藏文字，点击显示

这里有一段模糊文字，鼠标悬停显示

默认模式：点击后粒子消散动画揭示文字（基于 spoilerjs Web Component）
.blur 模式：鼠标悬停时模糊消失

注音标注 / Ruby（enableShokaRuby）：

为 CJK 文字添加注音，适用于日语假名、汉语拼音等：

{漢字^かんじ}的注音示例

{取り返す^とりかえす}是日语中"取回"的意思

示例效果：

漢字(かんじ)的注音示例。取り返す(とりかえす)是日语中"取回"的意思。

渲染为 HTML <ruby> 标签，浏览器原生支持。

提醒块 / Note Blocks（enableShokaContainers）：

使用 ::: 语法创建不同样式的提醒块：

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块
:::

:::success
这是成功提醒块
:::

:::warning
这是警告提醒块
:::

:::danger
这是危险提醒块
:::

:::info no-icon
这是没有图标的信息块
:::

示例效果：

这是信息提醒块，用于提供额外信息

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

支持的样式：default、primary、info、success、warning、danger。添加 no-icon 可隐藏图标。提醒块内部支持嵌套 Markdown 语法。

折叠块 / Collapse（enableShokaContainers）：

使用 +++ 语法创建可折叠内容（渲染为 <details> + <summary>）：

+++primary 点击展开详细内容
折叠的内容，支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
需要注意的内容
+++

+++danger 危险操作
请确保你知道自己在做什么！
+++

示例效果：

点击展开详细内容

折叠的内容，支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

需要注意的内容

支持的样式：primary、info、success、warning、danger。

标签卡 / Tabs（enableShokaContainers）：

使用 ;;; 语法创建标签页切换，同一组 ID 的标签卡会自动组合：

;;;mygroup JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;mygroup Python
```python
print('Hello, World!')
```
;;;

;;;mygroup Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

示例效果：

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

;;;groupId 标签名 定义一个标签页，同一 groupId 的标签自动组合
第一个标签默认激活
标签内支持任意 Markdown 内容

友链卡片（enableShokaHexoTags）：

使用 {% links %} 标签在文章中插入友链卡片网格：

{% links %}
- site: 博客名称
  url: https://example.com
  owner: 站长昵称
  desc: 站点描述
  image: https://example.com/avatar.png
  color: '#ed788b'
- site: 另一个博客
  url: https://example2.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

示例效果：

卡片数据使用 YAML 格式，支持 site、url、owner、desc、image、color 字段。

音频播放器（enableShokaHexoTags）：

使用 {% media audio %} 标签嵌入音频播放器，支持网易云音乐、QQ 音乐等平台（通过 Meting API 解析）。

默认使用 https://163.hyc.moe/ 作为 Meting API，可在 config/site.yaml 的 bgm.metingApi 中自定义，推荐自部署以获得更稳定的服务。

{% media audio %}
- name: 歌曲名称
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

示例效果：

支持歌单模式，可配置多个分组：

{% media audio %}
- title: 歌单名称 1
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 歌单名称 2
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频播放器（enableShokaHexoTags）：

使用 {% media video %} 标签嵌入视频播放器：

{% media video %}
- name: 视频 1
  url: https://example.com/video1.mp4
- name: 视频 2
  url: https://example.com/video2.mp4
{% endmedia %}

多个视频时自动显示播放列表。

练习题系统（enableQuiz）：

支持四种交互式题型，适合教程和学习笔记。需在文章 frontmatter 中设置 quiz: true。

单选题：

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型。

示例效果：

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

选项标记为正确答案，{.options} 为干扰项

多选题：

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。

示例效果：

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库。

添加 .multi 标记启用多选模式

判断题：

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML 是标记语言，不是编程语言。

示例效果：

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。

添加 .true 表示陈述正确，不添加 .true 则表示错误

填空题：

- CSS 中，[Flexbox]{.gap} 适合一维布局，[Grid]{.gap} 适合二维布局。{.quiz .fill}

> 常见错误：[Float]{.mistake}

示例效果：

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局。

常见错误：Float

[答案] 标记正确答案（支持多个空）
[错误答案] 标记常见错误（首次答错时提示）
> 引用块内容为解析说明

数学公式（enableMath）：

基于 KaTeX 渲染数学公式。需在文章 frontmatter 中设置 math: true：

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

示例效果：

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

代码块增强（enableCodeMeta）：

代码块支持额外的元数据标注：

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

元数据	说明
`title="文件名"`	显示代码块标题
`url="链接"`	添加外部源码链接
`linkText="文字"`	自定义链接文字（默认为 URL）
`mark:1,3`	高亮指定行
`command:("$":1-3)`	标记 shell 命令行（显示 `$` 前缀）

示例效果：

hello.js查看源码

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

Shoka 功能配置总览：

所有 Shoka 兼容功能均可在 config/site.yaml 的 content 部分独立开关：

content:
  # Shoka 兼容功能（默认全部启用，设为 false 可关闭）
  enableShokaContainers: true   # :::提醒块 ;;;标签卡 +++折叠块
  enableShokaAttrs: true        # text 属性语法
  enableShokaEffects: true      # ++下划线++ ==高亮== ~下标~ ^上标^
  enableShokaSpoiler: true      # !!隐藏文字!!
  enableShokaRuby: true         # {文字^注音} 注音标注
  enableShokaHexoTags: true     # {% links %} {% media %} Hexo 标签
  enableMath: true              # $数学公式$ KaTeX 渲染
  enableCodeMeta: true          # 代码块增强 (title, mark, command)
  enableQuiz: true              # 练习题交互功能
  enableEncryptedBlock: true    # :::encrypted{password="..."} 加密内容块

提示：完整的语法演示可参考 Shoka 主题 Markdown 语法演示文章。

内容加密（enableEncryptedBlock）：

博客支持两种加密方式，满足不同的内容保护需求：

1. 加密块 —— 文章局部加密

在文章中使用 :::encrypted{password="..."} 语法包裹需要加密的内容：

这部分内容公开可见。

:::encrypted{password="demo"}
这段内容需要输入密码 "demo" 才能查看。

支持完整的 Markdown 语法，包括代码块、列表、图片等。
:::

这部分也是公开的。

加密块适合在一篇文章中部分隐藏敏感内容（如答案、剧透、私密笔记），其余内容正常展示。需要在 config/site.yaml 中启用 enableEncryptedBlock: true。

2. 加密文章 —— 整篇文章加密

在文章的 frontmatter 中添加 password 字段即可加密整篇文章：

---
title: 我的私密文章
date: 2026-01-01
password: mySecretPassword
categories:
  - 笔记
---

这里的所有内容都会被加密...

加密文章会显示一个全屏的解锁界面，输入正确密码后才能查看内容。解锁后代码高亮、目录导航、Mermaid 图表等增强功能会自动重新初始化。

安全模型说明：

加密功能使用 AES-256-GCM 算法，安全模型如下：

构建时加密：密码仅在 pnpm build 时用于加密，生成的 HTML 中不包含密码明文
客户端解密：读者在浏览器中输入密码后，通过 Web Crypto API 在本地解密，密码不会发送到任何服务器
密钥派生：使用 PBKDF2（100,000 次迭代）从密码派生加密密钥，提高暴力破解成本
搜索排除：加密内容自动添加 data-pagefind-ignore，不会被 Pagefind 搜索索引

⚠️ 注意：此加密设计的主要目的是防止搜索引擎和爬虫索引加密内容，而非抵御针对性攻击。密文和盐值嵌入在公开的 HTML 中，理论上可被离线暴力破解。请使用强密码，不要用于保护高度敏感的信息。

加密文章的特殊行为：

方面	行为
RSS 订阅	标题前加 🔒 前缀，内容替换为"此文章已加密"提示
SEO / meta	description 使用 frontmatter 中的 `description`（若未设置则显示通用加密提示）
搜索索引	加密内容不会被 Pagefind 索引
目录导航	解锁前不显示，解锁后自动重建
AI 摘要	基于加密前的原文生成（构建时可访问明文）

其他增强：

自动目录生成
阅读时间计算
外部链接自动添加 target="_blank"

多语言支持（i18n）

博客内置完整的国际化支持，可轻松添加多种语言。

基本配置

在 config/site.yaml 的 i18n 部分配置支持的语言：

i18n:
  defaultLocale: zh        # 默认语言（URL 无前缀）
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
      # enabled: false     # 设为 false 可暂时禁用（保留内容但不生成路由）

配置多语言后：

默认语言的页面 URL 不带前缀（如 /post/hello）
其他语言自动加前缀（如 /en/post/hello）
导航栏（桌面端）和移动端抽屉中自动显示语言切换器
每个语言各自生成独立的 RSS 订阅源（如 /en/rss.xml）
HTML <head> 中自动输出 hreflang 标签，有利于 SEO

如果只配置了一种语言，i18n 功能不会激活，不会产生额外的路由或 UI 元素。

翻译体系

i18n 系统采用两层翻译架构：

1. UI 字符串（TypeScript）

界面上的按钮文字、提示信息等 UI 文本通过 TypeScript 翻译字典管理，位于 src/i18n/translations/ 目录：

zh.ts：默认语言（中文），包含所有翻译 key（约 170 个），是唯一的 source-of-truth
en.ts：英文翻译，只需提供需要覆盖的 key，未提供的自动回退到中文

翻译字符串支持 {param} 占位符插值：

// zh.ts
'post.totalPosts': '共 {count} 篇文章',

// en.ts
'post.totalPosts': '{count} posts',

2. 内容字符串（YAML）

分类名、系列名、精选分类描述等内容级文本通过 config/i18n-content.yaml 管理。默认语言的值直接读取 config/site.yaml，此文件仅存放非默认语言的翻译：

en:
  categories:
    life: Life
    note: Notes
    tools: Tools
  series:
    weekly:
      label: My Weekly
      fullName: My Tech Weekly
  featuredCategories:
    life:
      label: Life
      description: Life journals and essays

其中 categories 的 key 是分类的 URL slug（对应 config/site.yaml 中 categoryMap 的值），series 的 key 是系列的 slug。

添加翻译文章

将翻译文章放在 src/content/blog/<locale>/ 目录下，保持与默认语言相同的路径结构：

src/content/blog/
├── life/hello-world.md            # 默认语言 (zh)
├── tools/getting-started.md       # 默认语言 (zh)
├── en/life/hello-world.md         # 英文翻译
└── en/tools/getting-started.md    # 英文翻译

回退机制：当用户切换到非默认语言时，系统会显示该语言已有的翻译文章，对于尚未翻译的文章则自动回退显示默认语言内容，并在文章顶部标注提示信息。

添加新语言

以添加日语（ja）为例：

在 config/site.yaml 的 i18n.locales 中添加新语言：

i18n:
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
    - code: ja
      label: 日本語

创建 UI 翻译文件 src/i18n/translations/ja.ts：

import type { UIStrings } from '../types';

export const uiStrings: UIStrings = {
  'nav.home': 'ホーム',
  'common.search': '検索',
  // ... 按需翻译，未提供的 key 自动回退到中文
};

在 src/i18n/translations/index.ts 中注册：

import { uiStrings as ja } from './ja';

export const translations: Record<string, DefaultUIStrings | UIStrings> = {
  zh,
  en,
  ja, // 新增
};

4.（可选）在 config/i18n-content.yaml 中添加日语的内容翻译。

5.（可选）在 src/content/blog/ja/ 目录下添加日语文章。

在组件中使用翻译

Astro 组件（.astro 文件）中：

---
import { getLocaleFromUrl, t, localizedPath } from '@/i18n';

const locale = getLocaleFromUrl(Astro.url.pathname);
---

<h1>{t(locale, 'post.totalPosts', { count: 10 })}</h1>
<a href={localizedPath('/archives', locale)}>归档</a>

React 组件（.tsx 文件）中：

import { useTranslation } from '@hooks/useTranslation';

function MyComponent() {
  const { t, locale } = useTranslation();
  return <button>{t('common.search')}</button>;
}

RSS 订阅

访问 /rss.xml 获取 RSS feed。启用多语言时，每个语言有独立的 RSS 源（如 /en/rss.xml）。

包含内容：

最新文章列表
文章摘要
发布日期
文章链接

数据统计

集成 Umami 分析（可选）。

在 config/site.yaml 中配置：

analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://stats.example.com
    # 页面访问量展示（可选）
    statistics_display:
      token: your-umami-share-token  # Umami 分享链接令牌（只读，可安全暴露到客户端）
      article_page_views: true        # 在文章卡片和详情页显示访问量
      footer_site_stats: true         # 在页脚显示全站访问量

获取 Umami Share Token

statistics_display.token 是 Umami 的分享链接令牌，用于通过公开 API 读取统计数据（只读权限，可安全暴露到前端）。获取步骤：

登录你的 Umami 后台
进入 Settings → Websites，选择你的站点
点击右侧 Share URL 按钮（分享图标）
开启 Enable share URL 开关，此时会生成一个分享链接，形如：https://stats.example.com/share/xxxxxxxx/site-name
链接中 /share/ 后面的那段字符串（如 xxxxxxxx）即为 share token，将其填入 statistics_display.token 即可

注：Share token 仅提供只读权限，无法通过它修改任何数据或配置，因此可以安全地暴露到客户端代码中。

开发指南

目录结构

astro-koharu/
├── src/
│   ├── components/      # 组件
│   │   ├── common/      # 通用组件（错误边界等）
│   │   ├── ui/          # UI 组件（按钮、卡片等）
│   │   ├── layout/      # 布局组件（头部、侧边栏等）
│   │   ├── post/        # 文章相关组件
│   │   ├── category/    # 分类组件
│   │   └── theme/       # 主题切换
│   ├── content/
│   │   └── blog/        # 博客文章（Markdown）
│   │       └── en/      # 英文翻译文章（按 locale 子目录组织）
│   ├── i18n/            # 国际化模块
│   │   ├── config.ts    # locale 配置（读取 site.yaml）
│   │   ├── utils.ts     # 翻译函数、URL 工具
│   │   ├── content.ts   # 内容翻译加载（读取 i18n-content.yaml）
│   │   └── translations/  # UI 翻译字典（zh.ts, en.ts）
│   ├── layouts/         # 页面布局模板
│   ├── pages/           # 页面路由
│   │   └── [lang]/      # 非默认语言的镜像路由
│   ├── lib/             # 工具函数
│   ├── hooks/           # React hooks
│   ├── constants/       # 常量配置
│   ├── store/           # 全局状态（nanostores）
│   ├── scripts/         # 构建脚本
│   ├── styles/          # 全局样式
│   └── types/           # TypeScript 类型定义
├── public/              # 静态资源
│   └── img/             # 图片资源
├── config/
│   ├── site.yaml        # 站点配置（含分类映射、i18n 配置）
│   └── i18n-content.yaml  # 内容级翻译（分类名、系列名等）
├── astro.config.mjs     # Astro 配置
├── tailwind.config.mjs  # Tailwind 配置
└── tsconfig.json        # TypeScript 配置

路径别名

项目配置了以下路径别名（在 tsconfig.json 中）：

import { something } from "@/xxx"; // → src/xxx
import Component from "@components/xxx"; // → src/components/xxx
import { util } from "@lib/xxx"; // → src/lib/xxx
import config from "@constants/xxx"; // → src/constants/xxx
// ... 更多别名见 tsconfig.json

常用命令

# 开发
pnpm dev              # 启动开发服务器（默认 localhost:4321）

# 构建
pnpm build            # 构建生产版本
pnpm preview          # 预览生产构建

# 代码质量
pnpm lint             # 运行 ESLint
pnpm lint-md          # 检查 Markdown 文件
pnpm lint-md:fix      # 自动修复 Markdown 问题
pnpm knip             # 查找未使用的文件和依赖

# Koharu CLI
pnpm koharu                   # 交互式主菜单
pnpm koharu new               # 新建内容（交互式选择）
pnpm koharu new post          # 新建博客文章
pnpm koharu new friend        # 新建友情链接
pnpm koharu backup            # 备份博客内容（--full 完整备份）
pnpm koharu restore           # 还原备份（--latest, --dry-run）
pnpm koharu migrate           # 迁移旧内容链接（--dry-run）
pnpm koharu update            # 更新主题（--check, --clean, --rebase, --tag, --dry-run 等）
pnpm koharu generate          # 生成内容资产（交互式选择）
pnpm koharu generate lqips    # 生成 LQIP 占位符
pnpm koharu generate similarities  # 生成相似度向量
pnpm koharu generate summaries     # 生成 AI 摘要
pnpm koharu generate all      # 生成全部资产
pnpm koharu clean             # 清理旧备份（--keep N）
pnpm koharu list              # 查看所有备份

# 工具
pnpm change           # 生成 CHANGELOG.md（基于 git-cliff）

Docker 部署

astro-koharu 支持通过 Docker 进行容器化部署，适合需要自托管的场景。

快速开始：

# 1. 编辑 config/site.yaml，配置 comment.remark42 和 analytics.umami 部分

# 2. 构建并启动
docker compose -f docker/docker-compose.yml up -d --build

# 3. 访问
open http://localhost:4321

目录结构：

docker/
├── Dockerfile           # 多阶段构建配置
├── docker-compose.yml   # 编排配置
├── nginx/
│   └── default.conf     # Nginx 静态服务配置
└── rebuild.sh           # 便捷重建脚本

关于生成脚本：

以下脚本需要在本地运行，不能在 Docker 构建时执行：

脚本	原因
`pnpm generate:lqips`	使用 `sharp` 原生模块处理图片
`pnpm generate:similarities`	需下载 500MB+ 的 ML 模型
`pnpm generate:summaries`	需连接本地 LLM 服务器

推荐工作流：

# 本地开发：添加新图片或文章后
pnpm generate:all

# 提交生成的数据文件
git add src/assets/*.json
git commit -m "chore: update generated assets"

# 重建 Docker 容器
./docker/rebuild.sh

使用 rebuild.sh：

cd docker
./rebuild.sh

该脚本会：

检查环境变量文件
停止现有容器
重新构建并启动

评论与统计配置：

在 config/site.yaml 中配置评论系统和统计：

# 评论系统（可选）
comment:
  remark42:
    enabled: true
    host: https://your-remark-server.com/
    siteId: your-site-id

# 统计系统（可选）
analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://your-umami-server.com
    # 页面访问量展示（可选，需要 share token）
    # statistics_display:
    #   token: your-umami-share-token
    #   article_page_views: true
    #   footer_site_stats: true

Docker 端口可在 .env 中配置 BLOG_PORT=4321。

注意事项：

生成的 JSON 文件必须提交到 git，Docker 构建时会直接使用
如果忘记运行生成脚本，相关功能（LQIP 占位符、相关文章推荐等）将不可用
Docker 镜像基于 nginx
，仅包含静态文件，无需 Node.js 运行时

Koharu CLI

博客自带交互式命令行工具，提供备份还原、主题更新、内容生成、新建内容等功能。

启动方式：

pnpm koharu              # 交互式主菜单

新建内容

使用 CLI 快速创建博客文章和友链：

# 交互式选择创建类型（文章或友链）
pnpm koharu new

# 或直接指定类型
pnpm koharu new post     # 新建博客文章
pnpm koharu new friend   # 新建友情链接

新建博客文章功能：

交互式输入文章信息：
- 标题 - 文章标题（必填）
- Slug - 自定义 URL（可选，默认根据标题自动生成拼音）
- 描述 - 文章摘要（可选）
- 分类 - 从已有分类中选择（必选）
- 标签 - 添加标签，逗号分隔（可选）
- 草稿 - 是否保存为草稿（默认否）
自动生成 frontmatter（包含 title、date、categories、tags 等）
检查文件是否已存在，避免覆盖
文章保存在对应的分类目录下（如 src/content/blog/note/front-end/my-post.md）

新建友情链接功能：

交互式输入友链信息：
- 站点名称 - 友站的名称（必填）
- 站点 URL - 友站的链接（必填，需完整 URL）
- 站长昵称 - 友站站长的昵称（必填）
- 站点描述 - 友站的简介（必填）
- 头像 URL - 友站的头像链接（必填）
- 主题色 - 友站的主题色（可选，可选择预设颜色或自定义十六进制）
自动追加到 config/site.yaml 的 friends.data 数组
保留 YAML 文件的格式和注释

使用示例：

# 创建新文章
pnpm koharu new post
# 按提示输入：
# 标题: React Hooks 使用指南
# Slug: (自动生成 react-hooks-shi-yong-zhi-nan，可修改或清空)
# 描述: React Hooks 的完整使用教程
# 分类: 选择"笔记 → 前端"
# 标签: React, Hooks, 教程
# 草稿: 否

# 创建友链
pnpm koharu new friend
# 按提示输入友站信息

备份与还原

更新主题前，建议先备份你的个人内容：

# 基础备份（博客文章、配置、头像、.env）
pnpm koharu backup

# 完整备份（包含所有图片和生成的资产）
pnpm koharu backup --full

# 查看所有备份
pnpm koharu list

# 还原最新备份
pnpm koharu restore --latest

# 预览将要还原的文件（不实际还原）
pnpm koharu restore --dry-run

# 强制还原（覆盖已存在的文件）
pnpm koharu restore --force

# 清理旧备份（保留最近 5 个）
pnpm koharu clean --keep 5

备份文件存储在 backups/ 目录，格式为 backup-YYYY-MM-DD-HHMMSS.tar.gz。

更新主题

使用 CLI 自动更新主题，完成备份 → 拉取 → 合并 → 安装依赖的完整流程：

# 完整更新流程（默认会先备份）
pnpm koharu update

# 仅检查是否有更新
pnpm koharu update --check

# 跳过备份直接更新
pnpm koharu update --skip-backup

# 强制模式（跳过工作区检查和确认）
pnpm koharu update --force

# 更新到指定版本（如 v2.1.0）
pnpm koharu update --tag v2.1.0

# clean 模式（零冲突，强制备份，适合首次迁移或冲突较多时）
pnpm koharu update --clean

# rebase 模式（重写历史，强制备份，适合熟悉 git 的用户）
pnpm koharu update --rebase

# 预览操作（不实际执行，可配合 --clean 或 --rebase 使用）
pnpm koharu update --dry-run

选项说明：

选项	说明
`--check`	仅检查更新，不执行合并
`--skip-backup`	跳过备份步骤（clean/rebase 模式下无效，强制备份）
`--force`	跳过工作区脏检查和确认提示（不影响合并方式）
`--tag`	指定目标版本（如 `v2.1.0`），支持升级和降级
`--clean`	Clean 模式，零冲突更新（替换主题文件 + 还原用户内容）
`--rebase`	Rebase 模式，重写历史完全同步上游（强制要求备份）
`--dry-run`	预览操作，不实际执行

三种更新模式：

模式	命令	适合场景	备份	冲突处理
默认	`pnpm koharu update`	日常更新	可选	用户内容自动保留，主题冲突手动解决
Clean	`--clean`	首次迁移、冲突较多	强制	零冲突
Rebase	`--rebase`	熟悉 git 的用户	强制	需手动解决

默认模式（Merge）：

使用 git merge --no-ff 合并上游更新，保留 merge-base 信息，让后续更新的冲突更少。

智能冲突处理：

用户内容文件（博客文章、配置、独立页面、图片等）发生冲突时，自动保留本地版本
主题文件（组件、脚本、样式等）发生冲突时，需要手动解决
如果所有冲突都是用户内容 → 整个更新自动完成，零手动操作

📝 提交格式：

chore: merge upstream theme v2.3.2

Clean 模式：

用上游最新版本替换所有主题文件，然后从备份还原用户内容，实现零冲突更新。

执行流程：

强制备份你的博客内容
创建 merge commit 记录版本关系
用上游文件覆盖本地所有文件
从刚才的备份还原用户内容（博客文章、配置、独立页面、图片、.env）

⚠️ 注意：

你对主题文件的自定义修改（如改了某个组件、布局、样式）不会被保留
备份范围包含：src/content/blog/、config/site.yaml、src/pages/*.md、public/img/、.env
使用 --full 备份选项可额外保留 favicon、LQIP、相似度、AI 摘要等生成资产

适用场景：

首次从旧版本迁移，历史冲突太多无法正常 merge
没有自定义主题文件，只写了博客内容

Rebase 模式：

执行 git rebase upstream/main（或指定的 tag），将本地提交重放到上游之上。适合熟悉 git 操作的用户。

⚠️ 注意：Rebase 模式会重写 Git 历史，请确保已备份重要内容。CLI 会强制要求备份（忽略 --skip-backup 和 --force）。

使用 --dry-run 预览：

所有模式都支持 --dry-run 预览操作效果：

pnpm koharu update --dry-run          # 预览默认 merge
pnpm koharu update --clean --dry-run  # 预览 clean 模式
pnpm koharu update --rebase --dry-run # 预览 rebase 操作

💡 给熟悉 git 的用户： CLI 更新命令是对 git 操作的封装便利工具。如果你对 git 比较熟悉，建议直接使用 git fetch upstream && git rebase upstream/main 手动操作，这样能更精确地控制合并过程。

更新流程说明：

检查 Git 状态 — 确保工作区干净（无未提交的更改）
备份当前内容 — 可选（clean/rebase 模式强制备份）
设置 upstream — 自动添加 upstream remote（如果不存在）
获取最新代码 — git fetch upstream
显示更新预览 — 列出新增的提交和更新日志
执行更新 — 根据所选模式执行 merge / clean / rebase
安装依赖 — pnpm install

处理合并冲突：

默认 merge 模式下，用户内容冲突会被自动解决（保留本地版本）。如果主题文件仍有冲突，CLI 会显示冲突文件列表。你可以：

选择"中止合并"恢复到更新前状态
手动解决冲突后运行 git add . && git commit

# 如果选择手动解决冲突
git status                    # 查看冲突文件
# 编辑冲突文件，保留需要的内容
git add .
git commit -m "merge: resolve conflicts"

更新时使用的 Git 命令：

操作	命令
检查工作区状态	`git status --porcelain`
获取当前分支	`git rev-parse --abbrev-ref HEAD`
检查 upstream	`git remote -v`
添加 upstream	`git remote add upstream https://github.com/cosZone/astro-koharu.git`
获取更新	`git fetch upstream`
查看新提交数量	`git rev-list --left-right --count HEAD...upstream/main`
查看新提交列表	`git log HEAD..upstream/main --pretty=format:"%h \| %s \| %ar \| %an"`
默认合并	`git merge --no-ff upstream/main`
Clean 合并	`git merge -s ours upstream/main` + `git checkout upstream/main -- .`
Rebase	`git rebase upstream/main`
中止合并	`git merge --abort`

内容生成

生成各种内容资产：

# 交互式选择生成类型
pnpm koharu generate

# 或直接指定类型
pnpm koharu generate lqips        # 生成 LQIP 图片占位符
pnpm koharu generate similarities # 生成语义相似度向量
pnpm koharu generate summaries    # 生成 AI 摘要
pnpm koharu generate all          # 生成全部

如何添加新页面

在 src/pages/ 目录创建 .astro 文件
Astro 使用文件系统路由，文件路径即 URL 路径

示例：

src/pages/about.astro       → /about
src/pages/tags/[tag].astro  → /tags/:tag（动态路由）

如何自定义样式

全局样式：

编辑 src/styles/index.css。

组件样式：

使用 Tailwind CSS 工具类或 Astro 的 <style> 标签。

Tailwind 配置：

编辑 tailwind.config.ts 自定义主题、颜色、字体等。

主题变量：

在 src/styles/index.css 中定义的 CSS 变量：

:root {
  --primary-color: #ff6b6b;
  /* ... 更多变量 */
}

动画系统

使用 CSS 动画以及 Motion。

动画配置：

在 src/constants/anim/ 目录中：

spring.ts - 弹簧动画配置
variants.ts - 动画变体定义
props.ts - 可复用的动画属性

使用示例：

import { motion } from "motion/react";
import { fadeIn } from "@constants/anim/variants";

<motion.div variants={fadeIn} initial="hidden" animate="visible">
  内容
</motion.div>;

与 Hexo/Shoka 主题的对比

保留的特性

✅ 分类和标签系统
✅ 文章置顶功能
✅ 深色/浅色主题切换
✅ 响应式设计
✅ 友链页面
✅ 归档页面

改进之处

性能：

⚡ 静态站点生成 (SSG)，加载速度更快
⚡ 按需加载 JavaScript
⚡ 图片优化

开发体验：

🛠️ TypeScript 类型安全
🛠️ 热模块替换 (HMR)
🛠️ 现代化的开发工具链

功能增强：

🔍 更强大的全站搜索（Pagefind）
📝 内容集合 (Content Collections) 类型安全
🎨 Tailwind CSS 4.x 样式系统
🌊 View Transitions API 页面过渡

技术栈差异

方面	Hexo + Shoka	astro-koharu
框架	Hexo (Node.js)	Astro 7.x
模板引擎	EJS/Pug	Astro + React
样式	Stylus	Tailwind CSS 4.x
构建工具	Webpack	Vite
类型检查	无	TypeScript
内容管理	文件系统	Content Collections

常见问题

如何修改封面图片？

在文章 frontmatter 中设置 cover 字段：

cover: /img/cover/1.webp

图片放在 public/img/ 目录。如果不设置，会使用默认封面。

如何自定义域名？

部署到 Vercel 后，在 Vercel 项目设置中添加自定义域名，然后更新 config/site.yaml 中的 site.url 字段。

如何添加评论功能？

项目支持四种评论系统：Waline、Giscus、Remark42、Twikoo。在 config/site.yaml 的 comment 配置块中选择使用的提供商。

Waline（推荐）

Waline 是一个简洁、安全的评论系统，支持多种部署方式（Vercel、Railway、Zeabur 等）。

特点：

🚀 部署简单，支持多种平台一键部署
💬 支持 Markdown、表情、@提及、邮件通知
📊 内置浏览量统计、评论管理后台
🔐 支持多种登录方式（匿名、社交账号）
🛡️ 内置反垃圾评论、敏感词过滤
🎨 自动跟随站点深色/浅色主题

前置要求：

部署 Waline 服务端（部署指南）
获取服务端 URL

配置示例：

comment:
  provider: waline
  waline:
    serverURL: https://your-waline-server.vercel.app # Waline 服务端地址（必填）
    lang: zh-CN # 语言
    dark: html.dark # 暗黑模式 CSS 选择器
    meta: # 评论者信息字段
      - nick
      - mail
      - link
    requiredMeta: # 必填字段
      - nick
    login: enable # 登录模式 ('enable' | 'disable' | 'force')
    wordLimit: 0 # 评论字数限制 (0 = 无限制)
    pageSize: 10 # 每页评论数
    imageUploader: false # 图片上传功能
    highlighter: true # 代码高亮
    texRenderer: false # LaTeX 渲染
    search: false # 搜索功能
    reaction: false # 文章反应功能
    # recaptchaV3Key: '' # reCAPTCHA v3 Key (可选)
    # turnstileKey: '' # Cloudflare Turnstile Key (可选)

参数说明：

参数	类型	默认值	说明
`serverURL`	`string`	必填	Waline 服务端地址
`lang`	`string`	`'zh-CN'`	界面语言（支持 zh-CN, en, jp 等）
`dark`	`string`	`'html.dark'`	暗黑模式 CSS 选择器
`meta`	`string[]`	`['nick','mail','link']`	评论者信息字段
`requiredMeta`	`string[]`	`['nick']`	必填字段
`login`	`'enable'` \| `'disable'` \| `'force'`	`'enable'`	登录模式
`wordLimit`	`number`	`0`	评论字数限制（0 = 无限制）
`pageSize`	`number`	`10`	每页评论数
`imageUploader`	`boolean`	`false`	是否启用图片上传
`highlighter`	`boolean`	`true`	是否启用代码高亮
`texRenderer`	`boolean`	`false`	是否启用 LaTeX 渲染
`search`	`boolean`	`false`	是否启用搜索功能
`reaction`	`boolean`	`false`	是否启用文章反应功能
`recaptchaV3Key`	`string`	-	reCAPTCHA v3 Key（可选，防垃圾评论）
`turnstileKey`	`string`	-	Cloudflare Turnstile Key（可选）

部署 Waline 服务端：

推荐使用 Vercel 一键部署：

访问 Waline 快速开始
点击 "Deploy with Vercel" 按钮
登录 Vercel，授权 GitHub 仓库
配置环境变量（数据库连接、管理员邮箱等）
部署完成后获取服务端 URL（如 https://your-waline.vercel.app）

主题自动切换：

Waline 组件已实现主题自动切换，通过 dark 参数（默认 html.dark）自动跟随站点深色/浅色模式。

参考链接：

Remark42

Remark42 是一个轻量级的自托管评论系统，隐私友好，无需第三方服务。

特点：

🔒 自托管，完全掌控数据
🚫 无广告、无追踪
💾 支持多种存储后端（BoltDB、Memory）
🔐 支持多种社交登录（GitHub、Google、Twitter 等）
📧 邮件通知、评论审核
🎨 自动跟随站点深色/浅色主题

前置要求：

部署 Remark42 服务端（部署指南）
配置站点 ID 和域名

配置示例：

comment:
  provider: remark42
  remark42:
    host: https://comment.example.com/ # Remark42 服务器地址（必填）
    siteId: your-site-id # 站点 ID（必填）

参数说明：

参数	类型	说明
`host`	`string`	Remark42 服务器地址（必填，需带 `http://` 或 `https://`）
`siteId`	`string`	站点 ID（必填，在 Remark42 服务端配置中定义）

部署 Remark42 服务端：

推荐使用 Docker 部署：

docker run -d \
  --name remark42 \
  -p 8080:8080 \
  -e REMARK_URL=https://comment.example.com \
  -e SECRET=your-secret-key \
  -e SITE=your-site-id \
  -e AUTH_GITHUB_CID=your-github-client-id \
  -e AUTH_GITHUB_CSEC=your-github-client-secret \
  -v /path/to/data:/srv/var \
  umputun/remark42:latest

详细配置请参考 Remark42 安装指南。

主题自动切换：

Remark42 组件已实现主题自动切换，使用 MutationObserver 监听站点主题变化，自动调用 window.REMARK42.changeTheme() 更新评论框主题。

参考链接：

Giscus

Giscus 是基于 GitHub Discussions 的评论系统，无需自建后端，评论数据存储在你的 GitHub 仓库中。

具体配置可以看看这篇文章：https://zhuanlan.zhihu.com/p/693434928

前置要求：

仓库必须是公开的
安装 giscus app
在仓库中启用 Discussions 功能

获取配置参数：

访问 giscus.app
输入你的仓库名称（格式：owner/repo）
选择页面与 Discussion 的映射方式（推荐 pathname）
选择 Discussion 分类（推荐 Announcements）
启用所需功能（reactions、评论框位置等）
复制生成的 data-repo-id 和 data-category-id

配置示例：

comment:
  provider: giscus
  giscus:
    repo: username/repo # GitHub 仓库名 (owner/repo 格式)
    repoId: R_kgDOxxxxxx # 仓库 ID (从 giscus.app 获取)
    category: Announcements # Discussion 分类名称
    categoryId: DIC_kwDOxxxxxx # 分类 ID (从 giscus.app 获取)
    mapping: pathname # 映射方式
    reactionsEnabled: "1" # 启用 reactions ('1' 启用, '0' 禁用)
    emitMetadata: "0" # 发送元数据
    inputPosition: top # 输入框位置 ('top' | 'bottom')
    lang: zh-CN # 语言

参数说明：

参数	类型	说明
`repo`	`string`	GitHub 仓库，格式为 `owner/repo`
`repoId`	`string`	仓库 ID，从 giscus.app 获取
`category`	`string`	Discussion 分类名称
`categoryId`	`string`	分类 ID，从 giscus.app 获取
`mapping`	`string`	页面与 Discussion 的映射方式
`term`	`string`	当 `mapping` 为 `specific` 或 `number` 时使用
`strict`	`'0' \| '1'`	严格匹配模式，默认 `'0'`
`reactionsEnabled`	`'0' \| '1'`	是否启用 reactions，默认 `'1'`
`emitMetadata`	`'0' \| '1'`	是否发送页面元数据，默认 `'0'`
`inputPosition`	`'top' \| 'bottom'`	评论输入框位置，默认 `'top'`
`lang`	`string`	界面语言，默认 `'zh-CN'`
`host`	`string`	自托管 Giscus 实例的地址（可选）
`theme`	`string`	固定主题（不设置则跟随站点主题切换）
`loading`	`'lazy' \| 'eager'`	加载方式，默认 `'lazy'`

映射方式说明：

pathname（推荐）：使用页面路径匹配，如 /post/my-article
url：使用完整 URL 匹配
title：使用页面标题匹配
og:title：使用 Open Graph 标题匹配
specific：使用 term 参数指定的值
number：使用 term 参数指定的 Discussion 编号

主题自动切换：

本主题已实现 Giscus 评论框的主题自动切换，会跟随站点的深色/浅色模式自动调整。实现原理：

组件挂载时读取当前主题
使用 MutationObserver 监听 document.documentElement 的 class 变化
检测到主题切换时通过 postMessage 通知 Giscus iframe 更新主题

参考链接：

Twikoo

Twikoo 是一个搭建免费，部署简单，功能丰富的简洁、安全、易用的静态网站评论系统。

特点：

☁️ 云开发 / 自托管双部署模式
🔒 隐私安全，无广告、无恶意追踪
📧 支持邮件 / 微信公众号评论通知
⚙️ 后台评论审核、敏感词过滤
😊 内置表情包、支持图片上传
🌙 原生支持深色 / 浅色主题切换
👥 访客标记、评论点赞、楼中楼回复
🛡️ 内置反垃圾评论防护

前置要求：

部署 Twikoo 服务端（腾讯云开发 / 自托管，部署指南）
配置云开发环境 ID 或自托管服务地址

配置示例：

comment:
  provider: twikoo
  twikoo:
    envId: # Twikoo 环境 ID (腾讯云) 或 Vercel 环境地址 (必填)
    region: # 环境地域，默认为 ap-shanghai
    path: # 用于区分不同文章的自定义 js 路径，如果您的文章路径不是 location.pathname，需传此参数
    lang: # 语言 (默认: 'zh-CN')

参数说明：

参数	类型	说明
`envId`	`string`	Twikoo 环境 ID (必填，需带 `https://` 或 `https://`）
`region`	`string`	环境地域，默认为 `'ap-shanghai'`
`path`	`string`	用于区分不同文章的自定义 js 路径，如果您的文章路径不是 location.pathname，需传此参数
`lang`	`string`	语言 (默认: `'zh-CN'`)

部署 Twikoo 服务端：

参考 Twikoo 官网获取详细部署指南。

主题自动切换：

Twikoo 已实现主题自动切换

参考链接：

Twikoo 官网

草稿文章如何预览？

运行 pnpm dev 本地开发模式，草稿会自动显示（带 DRAFT 标识）。

如何关闭某些功能？

关闭某个系列：设置该系列的 enabled: false

featuredSeries:
  - slug: weekly
    enabled: false # 禁用此系列
    # ...

关闭所有系列：将 featuredSeries 设为空数组 []
关闭搜索：移除 astro.config.mjs 中的 pagefind() 集成
关闭统计：设置 analytics.umami.enabled = false
关闭评论：移除 comment.provider 配置或将其设置为空
关闭 Shoka 语法：在 config/site.yaml 的 content 部分将对应功能设为 false，如 enableShokaContainers: false（关闭提醒块/折叠块/标签卡）、enableShokaSpoiler: false（关闭隐藏文字）等
关闭数学公式：设置 content.enableMath = false
关闭练习题：设置 content.enableQuiz = false

如何更改文章 URL 格式？

默认使用文件名作为 URL。可以通过 link 字段自定义：

link: my-custom-url

URL 特殊字符处理

文章链接（link）和标签（tags）支持包含特殊字符，系统会自动进行 URL 编码处理。

文章链接特殊字符：

---
title: C# 学习笔记
link: test-C# # 包含 # 字符
---

访问时 URL 会自动编码为 /post/test-C%23，确保浏览器正确解析。

标签特殊字符：

tags:
  - C#
  - C++
  - .NET
  - Node.js

标签会自动转换为 URL 安全的格式：

C# → /tags/c%23
C++ → /tags/c%2B%2B
.NET → /tags/.net
Node.js → /tags/node.js

注意事项：

特殊字符包括：#、+、&、?、%、空格等
标签中的 / 会被替换为 -（如 前端/React → 前端-react）
分类名称通过 categoryMap 映射，建议使用纯英文 slug 避免编码问题

参考资源

更新日志

查看 CHANGELOG.md 了解版本更新历史。

如有问题或建议，欢迎在 GitHub Issues 中反馈。

Markdown 增强功能演示

Mon, 01 Jan 2024 16:00:00 GMT

本文展示 astro-koharu 支持的所有 Markdown 增强功能。

链接嵌入功能

astro-koharu 支持自动嵌入独行链接，包括 Tweet 和通用链接预览。

Tweet 嵌入测试

下面是一条独行的 Twitter 链接，应该自动转换为 Tweet 组件：

这是普通段落中的链接 Vercel Tweet，不应该被嵌入。

使用新域名 x.com 的 Tweet：

通用链接预览测试

这是段落中的链接 react-tweet，不应该被嵌入。

下面是一个独行的普通链接，应该显示 OG 预览卡片：

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

这是没有 OG 图的链接

react-tweet.vercel.app

https://react-tweet.vercel.app/

这是获取不到 OG 信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

Codepen 链接嵌入

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

链接嵌入规则

独行的 Twitter/X 链接自动转换为 Tweet 组件
独行的其他链接显示 OG 预览卡片
段落内的链接保持原样
支持深色/浅色主题切换

代码高亮

支持多种编程语言的语法高亮，并自动跟随主题切换。

JavaScript

function greet(name) {
  console.log(`Hello, ${name}!`);
  return {
    message: "Welcome to astro-koharu",
    timestamp: Date.now(),
  };
}

greet("World");

TypeScript

interface BlogPost {
  title: string;
  date: Date;
  tags: string[];
  content: string;
}

const post: BlogPost = {
  title: "My First Post",
  date: new Date(),
  tags: ["astro", "blog"],
  content: "Hello World!",
};

Python

def fibonacci(n: int) -> list[int]:
    """Generate Fibonacci sequence"""
    if n <= 0:
        return []
    elif n == 1:
        return [0]

    fib = [0, 1]
    for i in range(2, n):
        fib.append(fib[i-1] + fib[i-2])
    return fib

print(fibonacci(10))

Bash

#!/bin/bash
# Start development server
pnpm install
pnpm dev

echo "Server is running at http://localhost:4321"

GFM 表格

功能	支持状态	说明
表格	✅	支持对齐
任务列表	✅	复选框
删除线	✅	删除文本
自动链接	✅	自动识别 URL

任务列表

安装 astro-koharu
配置站点信息
写第一篇文章
部署到 Vercel

Mermaid 图表

流程图

flowchart LR
    A[编写文章] --> B[本地预览]
    B --> C{满意吗?}
    C -->|是| D[推送代码]
    C -->|否| A
    D --> E[自动部署]
    E --> F[上线成功]

时序图

sequenceDiagram
    participant U as 用户
    participant B as 浏览器
    participant S as 服务器

    U->>B: 访问博客
    B->>S: 请求页面
    S-->>B: 返回 HTML
    B-->>U: 渲染页面

饼图

pie title 博客内容分布
    "技术笔记" : 45
    "生活随笔" : 25
    "项目分享" : 20
    "其他" : 10

文本样式

粗体文本
斜体文本
删除线
行内代码
链接文本

引用

这是一段引用文本。

astro-koharu 让博客搭建变得简单而优雅。

标题层级

本文展示了 h2-h6 各级标题，它们都会自动生成锚点链接，方便分享和引用。

三级标题

四级标题

五级标题

六级标题

分割线

列表

无序列表

项目一
- 子项目 A
- 子项目 B
项目二
项目三

有序列表

第一步
第二步
1. 子步骤 A
2. 子步骤 B
  1. 子步骤 C
第三步

图片

图片会自动应用 LQIP（低质量图片占位符）效果：

示例图片

Shoka 兼容 Markdown 语法

除了上述标准 Markdown 增强外，astro-koharu 还支持从 Hexo Shoka 主题迁移的丰富扩展语法，包括：

文字特效 — 下划线 ins、高亮 mark、上下标 _sub / ^sup、颜色文字
隐藏文字 — Spoiler 粒子动画隐藏文字和模糊效果
注音标注 — Ruby 漢字(かんじ)
容器块 — 提醒块 :::info、折叠块 +++primary 标题、标签卡 ;;;tab
友链卡片 — YAML 数据渲染为交互卡片
音视频播放器 — 支持网易云/QQ 音乐歌单
数学公式 — KaTeX 行内 E=mc2E=mc^2E=mc2 和块级 $$...$$
代码块增强 — title、mark 行高亮、command 提示符
练习题系统 — 单选、多选、判断、填空四种题型
加密内容块 — :::encrypted AES-256-GCM 加密，防止爬虫收录

所有功能均可在 config/site.yaml 中独立开关。完整语法演示和用法请参阅 Shoka 主题 Markdown 语法演示。

加密内容块

使用 :::encrypted{password="密码"} 语法创建加密区块。内容在构建时使用 AES-256-GCM 真正加密，密码不会出现在最终 HTML 中，有效防止搜索引擎和爬虫收录敏感内容。

加密块内的 Markdown 会获得与普通内容完全相同的渲染处理（Shiki 代码高亮、KaTeX 公式等），解密后直接展示。

前端无法实现真正意义上的加密，因为密码需在客户端输入，密文和算法对用户可见，安全性完全取决于密码强度。本功能的目的是防止搜索引擎和爬虫直接收录明文内容，而非对抗有针对性的破解。

:::encrypted{password="demo"}
这段内容已加密，输入密码 `demo` 即可查看。

支持 **完整 Markdown 语法**，包括代码块：

```python
print("Hello from encrypted block!")
```

:::

总结

以上展示了 astro-koharu 支持的主要 Markdown 功能。更多功能请参考使用指南。