Rocky‘s Blog

求真求实

2026-10-21T00:00:00+00:00

谮言并非是空洞的务虚的口号，而是一个人踩过的坑，
或许只有亲身经历才能理解谮言本身的含义，

人教人教不会，事教人一遍就成。人只能教谮言，但谮言本身的含义需要受教人亲自去领会才可以；

再多的言语和再多的细节都是苍白无力的，在这之前，求真求实是受教人的基础，也是尽可能的降低受损；

狂妄自负在清醒后的代价，在领悟谮言后会变得可笑

自己拥有过的，自己亲眼见过的才可宣之于口，吹嘘就是一种虚荣的表现，在恋人朋友之前吹嘘能带来什么呢？什么都不会有，因为时间的暴露你的本质，恋人朋友迟早会直到你的本质但惧怕暴露并非是拒绝虚荣的理由，与其说拒绝虚荣，不如直面自己来的正当；

—— 记失恋后反思自己过错的小总结

2026-10-20T12:00:00+00:00

2026年10月20日 20:00（东八区 / 北京时间）

RSS/Atom 订阅只见部分文章、刷不出新文：根因定位与修复方案

概述

本轮排查「订阅后仅获取部分文章、且无法刷新获取后续新增文章」的问题。结论是：不是订阅器不刷新，也不是 feed 没更新，而是站点没有全站 RSS/Atom，只有分板块 feed；而订阅入口只暴露了 Nanolog 和「Blog(01Write_blog)」两个板块，后者基本是空的，新文章都发在别的板块里，所以订阅者永远刷不到。

无全站 feed：zola.toml 只写了 feed_filenames，缺 generate_feeds = true，Zola 因此不生成根目录 /atom.xml、/rss.xml（线上 404）；
只有分板块 feed：各板块 _index.md 里 generate_feeds = true，各自生成独立 feed；自动发现只暴露 feed_sections 里声明的 Nanolog 与 Blog 两个板块；
「Blog」板块几乎没文章：01Write_blog 实际只有 2 篇 6 月的测试文，长文分散在 CXX20 / Share / Debug / Math 等十几个板块；
新文都发在别的板块：最近新增文章全部落在 01Write_blog_CXX20 与 03Share_blog，不在被订阅的板块里；
加密文章被过滤：scripts/post-build.mjs 会把 encrypt = true 的文章从 feed 与搜索索引中移除（当前约 8 篇）。

一、现象

订阅 RSS / Atom 之后，只能看到一部分文章；
之后站点持续更新，但订阅器刷新也拿不到新增文章。

二、根因定位

2.1 站点级 feed 从未生成（主因）

zola.toml 里只配置了：

feed_filenames = ["atom.xml", "rss.xml"]

但全文件没有 generate_feeds = true。Zola 只有开了 generate_feeds 才会生成根目录的 atom.xml / rss.xml。实测同版本 Zola（0.23.6）：不开该开关时构建产物里没有根 feed，线上 https://suchaharcan.github.io/atom.xml 返回 404。

2.2 实际存在的只有「分板块」feed，自动发现只暴露 2 个板块

主题 partials/head.html 会按 zola.toml 的 feed_sections 输出订阅链接，目前只有：

名称	板块	feed 地址
Nanolog	`@/nanolog/_index.md`	`/nanolog/atom.xml`
Blog	`@/01Write_blog/_index.md`	`/01Write_blog/atom.xml`

于是从首页点订阅，只能选到这两个之一。而 generate_feeds = true 的板块其实有十几个，每个板块各自生成独立 feed。

2.3 被当作「Blog」的 01Write_blog 板块几乎没有文章

线上 /01Write_blog/atom.xml 实际只有 2 条，都是 6 月的测试文（One、Third）。真正的长文全部分散在：

板块	文章数
`03Share_blog`	15
`00Read_blog_Math`	8
`00Read_blog_English`	7
`02Engineer_blog_Debug`	7
`01Write_blog_CXX20`	5
`01Write_blog_CMake` / `01Write_blog_AlgorithmDesign`	各 5
其余写作子板块	各 1–2

2.4 新文章恰好都发在「没被订阅」的板块

最近一次提交 Create New Blogs And Update Old Blogs 的新增文章全部落在：

01Write_blog_CXX20/2026-10-15-CMake、2026-10-15-Markdown、2026-10-15-Zola-Blog
03Share_blog/2026-10-15-ASCII-Mac

这些板块既不在自动发现列表里，也和用户订阅的 Nanolog / Blog 无关。所以即使部署成功、对应板块 feed 也更新了，订阅器刷新时依旧一个「新文章」都看不到。

2.5 加密文章被主动剔除

scripts/post-build.mjs 会把所有 encrypt = true 的文章从 feed 与搜索索引中过滤掉（约 8 篇），这是设计行为（正文加密，feed 不放明文），也让「部分文章缺失」更明显。

三、修复方案

方案 A（推荐，一步到位）：生成全站 feed

在 zola.toml 顶层补一行：

generate_feeds = true
feed_filenames = ["atom.xml", "rss.xml"]

这样根目录会生成 /atom.xml 与 /rss.xml，收录全站所有带 date 的文章（跨板块，按日期倒序）。本地已用同版本 Zola 验证：开启后根 feed 同时包含不同板块的文章。订阅者只需订阅这一个地址即可收到全站更新。

方案 B：扩充自动发现的板块

把真正在更新的板块补进 feed_sections，例如：

feed_sections = [
  { name = "Nanolog", path = "@/nanolog/_index.md" },
  { name = "Blog", path = "@/01Write_blog/_index.md" },
  { name = "CXX20", path = "@/01Write_blog_CXX20/_index.md" },
  { name = "Share", path = "@/03Share_blog/_index.md" },
]

首页订阅入口会相应多出这些板块的 feed 链接，但订阅者仍需分别订阅每个关心的板块。

方案 C（订阅者侧临时办法）

直接订阅具体板块的 feed，例如：

https://suchaharcan.github.io/01Write_blog_CXX20/atom.xml
https://suchaharcan.github.io/03Share_blog/atom.xml

四、注意

全站 feed 只收录带 date 字段、且未被 include_in_feeds = false 排除的文章；design、kanban 等无 date 的页面不会进入 feed；
encrypt = true 的文章仍会被 scripts/post-build.mjs 过滤，这是加密功能的设计行为；
新增文章后需触发一次构建/部署，feed 才会更新（CI 已在每次推送时自动构建部署）。

相关链接：首页 · Nanolog 列表 · Ametrine 主题

CMake

2026-10-15T00:00:00+00:00

定期更新该博客

总结CMake常用命令之前，先明确为什么要使用CMake?

C++ 源码编译链接的原理，在代码膨胀到多文件，项目复杂度，代码文件管理难度，跨平台等问题，需要一个更智能更现代的构建工具。因为以上的问题和缺陷，所以需要CMake;

rmbuild

cmake ..
cmake --build .
cmake --build . -j 9 # 并行构建

Markdown

2026-10-15T00:00:00+00:00

`同步翻译整理 Markdown 官方和其他优秀归纳文章即可

参考 Ametrine主题开发者本人网站，博客源码参照而主题内置的样例博客可作为重要参考

对自身的要求仅是熟练使用，无迁移晋升的空间

Markdown

Text can be bold, italic, ~~strikethrough~~, and ~~all at the same time~~.
Link to another page^[1].

标题

There should be whitespace between paragraphs^[2].

| 段落 |

要创建段落，请使用空行分隔一行或多行文本。

换行

借助 Alfred 的快捷文本 mkbr进行快速触发 <br/>

“Original content is original only for a few seconds before getting old”

Rule #21 of the internet 加粗字体

**

引用块 ✅

嵌套引用块 要创建引用块，请在段落前添加 >。

引用块可以嵌套。在要嵌套的段落前添加 >>。

包含其他元素的引用块

引用块可以包含其他 Markdown 格式的元素。并非所有元素都可以使用——你需要进行实验以查看哪些元素有效。

Useful information that users should know, even when skimming content.

Helpful advice for doing things better or more easily.

Key information users need to know to achieve their goal.

Urgent info that needs immediate user attention to avoid problems.

Advises about risks or negative outcomes of certain actions.

有序列表

添加带有数字和句号的行项目。数字不必按数字顺序排列，但列表应从数字一开头。

无序列表

在行项目前添加破折号 (-)、星号 (*) 或加号 (+)。
缩进一个或多个项目以创建嵌套列表。

为了兼容性，请不要在同一列表中混合和匹配分隔符——选择一个并坚持使用它。

第一项
第二项
第三项
- 缩进项
- 缩进项
第四项
Item 1
Item 2
- Item 2.1
- Item 2.2
Item 3
Item 4

Perform step #1
Proceed to step #2
Conclude with step #3

Milk
Eggs
Flour
Coffee
Combustible lemons

要在列表中添加另一个元素，同时保留列表的连续性，请将元素缩进四个空格或一个制表符，如下例所示。

This is the first list item.
Here’s the second list item.

A blockquote would look great below the second list item.
And here’s the third list item.

代码

Character	Show	Quotes
Derpy Hooves	My Little Pony	I just don’t know what went wrong
Gir	Invader ZIM	GUESS WHO MADE WAAAAFFLES?!!
WALL-E	WALL-E	Ooooo 0.0
Taco	Inanimate Insanity	SOUR CREAM!

let highlight = true;

10pre mark {
12  display: block;
13  color: currentcolor;
14}
15pre table td:nth-of-type(1) {
17  color: #6b6b6b;
18  font-style: italic;
19}

水平线 ✅

单独的一行上使用三个或更多星号 (***)、破折号 (—) 或下划线 (___)^[3]。

Components - 组件

Ametrine provides a few useful components that simplify some tasks. They can be used on all pages.

As of version 0.21.0, Zola supports GitHub flavored alerts natively, without this component. It can be enabled by adding the following to zola.toml:
[markdown]
github_alerts = true

Required variables are:

icon: Icon from phosphoricons.com that will be used in the alert.
title: Title of the alert.

Optional variables are:

color: Color that the alert should be colored into. Available colors are: red, orange, yellow, green, blue, and purple.

Hi, I’m a fake custom alert.

I’m a list with an inline link.

链接 ⭐

必须是英文引号填充悬浮提示
添加标题您可以选择为链接添加标题。当用户将鼠标悬停在链接上时，它将显示为工具提示。要添加标题，请在 URL 后用引号将其括起来。

eg: Duck Duck Go.

[Duck Duck Go](https://duckduckgo.com "The best search engine for privacy").
[Spotify](https://open.spotify.com/playlist/7zbBvAvpb9NJfkO0e7lJx3)

Images and Videos

By default images and videos come with some generic styling, such as rounded corners and shadow. To fine-tune these, you can use components with different argument combinations.

Available variables are:

url: URL to an image.
url_min: URL to compressed version of an image, original can be opened by clicking on the image.
alt: Alt text, same as if the text were inside square brackets in Markdown.
full: Forces image to be full-width.
start: Float image to the start of paragraph and scale it down.
end: Float image to the end of paragraph and scale it down.
pixels: Uses nearest neighbor algorithm for scaling, useful for keeping pixel-art sharp.
has_alpha: Removes rounded corners and shadow, useful for images with transparency.
drop_shadow: Uses drop shadow instead of box shadow, useful for images with transparency.
no_hover: Removes zoom on hover. 悬停取消缩放
spoiler: Blurs image until hovered over/pressed on, useful for plot rich game screenshots. 模糊图像，直到悬停/点击适用内容丰富敏感的内容
spoiler with solid: Ditto, but makes the image completely hidden.

{{ <image src="graph.png" alt="This is an image" class="no-hover"/> }}

Image with an alt text and without zoom on hover

Image with compressed version, an alt text, and without zoom on hover

Image with an alt text, hidden behind a spoiler

Alternatively, you can append the following URL anchors. It can be more handy in some cases, e.g. such images will render normally in any Markdown editor, opposed to the Zola components.

#full: Forces image to be full-width.
#start: Float image to the start of paragraph and scale it down.
#end: Float image to the end of paragraph and scale it down.
#pixels: Uses nearest neighbor algorithm for scaling, useful for keeping pixel-art sharp.
#has-alpha: Removes rounded corners and shadow, useful for images with transparency.
#drop-shadow: Uses drop shadow instead of box shadow, useful for images with transparency.
#no-hover: Removes zoom on hover.
#spoiler: Blurs image until hovered over/pressed on, useful for plot rich game screenshots.
#spoiler with #solid: Ditto, but makes the image completely hidden.

Full-width image with an alt text, pixel-art rendering, drop shadow, and with no rounded corners and zoom on hover

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim aeque doleamus animo, cum corpore dolemus, fieri tamen permagna accessio potest, si aliquod aeternum et infinitum impendere malum nobis opinemur.

For videos it’s all the same except for a few differences: no_hover and url_min variables are not available.

Additionally, the following attributes can be set:

autoplay: Start playing the video automatically.
controls: Display video controls such as volume control, seeking and pause/resume.
loop: Play the video again once it ends.
muted: Turn off the audio by default.
playsinline: Prevent the video from playing in fullscreen by default (depends on the browser).

{{ <video sources={["video.webm"]} alt="This is a video" controls={true}/> }}

Duckling preening

CRT

Alright, this one doesn’t simplify anything, it just puts ASCII art into a CRT-like box.

As this element is intended to be purely decorative (e.g. for displaying ASCII art), it is hidden from screen readers unless a label is supplied. Ensure that no vital content is wrapped in it.

{% <crt label="ASCII illustration of public library halls."> %}
-> ASCII art <-
{% </crt> %}


---

|.'', Public_Library_Halls ,''.|
|.'.'', ,''.'.|
|.'.'.'', ,''.'.'.|
|.'.'.'.'', ,''.'.'.'.|
|.'.'.'.'.| |.'.'.'.'.|
|.'.'.'.'.|===; ;===|.'.'.'.'.|
|.'.'.'.'.|:::|', ,'|:::|.'.'.'.'.|
|.'.'.'.'.|---|'.|, _______ ,|.'|---|.'.'.'.'.|
|.'.'.'.'.|:::|'.|'|???????|'|.'|:::|.'.'.'.'.|
|,',',',',|---|',|'|???????|'|,'|---|,',',',',|
|.'.'.'.'.|:::|'.|'|???????|'|.'|:::|.'.'.'.'.|
|.'.'.'.'.|---|',' /%%%\ ','|---|.'.'.'.'.|
|.'.'.'.'.|===:' /%%%%%\ ':===|.'.'.'.'.|
|.'.'.'.'.|%%%%%%%%%%%%%%%%%%%%%%%%%|.'.'.'.'.|
|.'.'.'.',' /%%%%%%%%%\ ','.'.'.'.|
|.'.'.',' /%%%%%%%%%%%\ ','.'.'.|
|.'.',' /%%%%%%%%%%%%%\ ','.'.|
|.',' /%%%%%%%%%%%%%%%\ ','.|
|;________****/%%%%%Spicer%%%%%%\_****_______;|

Alternatively, if you have syntax highlighting enabled and you need to preserve whitespace, you can use a code block with crt=true added right after three backticks.

The downside of this approach is that it will keep the ASCII art accessible to screen readers, which is bad for accessebility. Whitespace issue should hopefully be fixed with the release of Zola 0.23.0. See #116.

```crt=true
  /\
 /  \
/____\
```

  /\
 /  \
/____\

Audio

Places a useless audio button with a funny hover animation. Needs extra.audio_button to be enabled on page, section, or config level for it to work.

{{ <audio name="Party!" url="party-horn.mp3"/> }}

Hi everyone! You know what I like doing? That’s right, throwing ! Actually I don’t I just wanted to show off audio button.

YouTube

Allows to embed a YouTube video using youtube-nocookie.

Available variables are:

autoplay: Whether the video should autoplay.
start: On which second video should start.

{{ <youtube id="0Da8ZhKcNKQ"/> }}

Vimeo

Allows to embed a Vimeo video.

Available variables are:

autoplay: Whether the video should autoplay.

{{ <vimeo id="869483483"/> }}

BiliBili

[!NOTE] B站版本的视频调用方式我要仿写实现

Overflow Auto

Sometimes, an element gets too wide, and it’s not possible to make it adaptive in any sensible way (think tables), this is when this component comes in.

{% <overflow_auto> %}
Table (for example)
{% </overflow_auto> %}

Accepts either of the two optional arguments:

overshoot: Adds a vertical overshoot, to make the cutoff visually nicer.
overshoot_row: Ditto, but horizontal.

{% <overflow_auto overshoot_row={true}> %}
| #   | Song                          | Artist        | Duration | Popularity | Genres | Year | Added      |
| --- | ----------------------------- | ------------- | -------- | ---------- | ------ | ---- | ---------- |
| 1   | Good Morning                  | gifting guide | 03:22    | 2          |        | 2025 | 2026-01-30 |
| 2   | On Little Cat Feet            | Nightmargin   | 02:35    | 46         |        | 2016 | 2025-12-21 |
| 3   | Take Responsibility (Hear Me) | Koa           | 03:25    | 11         |        | 2024 | 2025-12-21 |
{% </overflow_auto> %}

#	Song	Artist	Duration	Popularity	Year	Added
1	Good Morning	gifting guide	03:22	2	2025	2026-01-30
2	On Little Cat Feet	Nightmargin	02:35	46	2016	2025-12-21
3	Take Responsibility (Hear Me)	Koa	03:25	11	2024	2025-12-21

Description List

<dl>
  <dt>Something</dt>
  <dd>And its description</dd>
</dl>

Name: Godzilla
Born: 1952
Birthplace: Japan
Color: Green

Form Input

<input type="checkbox" /> <label>Checkbox</label>

Milk
Eggs
Flour
Coffee
Combustible lemons

With switch class:

<input class="switch" type="checkbox" /> <label>Checkbox</label>

Milk
Eggs
Flour
Coffee
Combustible lemons

With switch and big classes:

<input class="switch big" type="checkbox" /> <label>Checkbox</label>

Milk
Eggs
Flour
Coffee
Combustible lemons

With radio type:

<input type="radio" name="test" /> <label>Radio</label>

Milk
Eggs
Flour
Coffee
Combustible lemons

With color type:

<label>Color:</label> <input type="color" value="#000000" />

Color:

Disabled:

With range type:

<input type="range" max="100" value="33" />

Figure Captions

<figure>
  -> Whatever content <-
  <figcaption>Caption of content above</figcaption>
</figure>

The Office where Stanley works, it has yellow floor and beige walls

Accordion

<details>
  <summary>Accordion title</summary>
  -> Contents here <-
</details>

Reveal accordion

Get it? I know, it’s an awful pun.

Side Comment

<small>Small, cute text that doesn't catch attention.</small>

Small, cute text that doesn’t catch attention.

Abbreviation

<abbr title="American Standard Code for Information Interchange">ASCII</abbr>

The ASCII art is awesome!

Aside

<aside>-> Contents here <-</aside>

A quill is a writing tool made from a moulted flight feather (preferably a primary wing-feather) of a large bird. Quills were used for writing with ink before the invention of the dip pen, the metal-nibbed pen, the fountain pen, and, eventually, the ballpoint pen.

As with the earlier reed pen (and later dip pen), a quill has no internal ink reservoir and therefore needs to periodically be dipped into an inkwell during writing. The hand-cut goose quill is rarely used as a calligraphy tool anymore because many papers are now derived from wood pulp and would quickly wear a quill down. However it is still the tool of choice for a few scribes who have noted that quills provide an unmatched sharp stroke as well as greater flexibility than a steel pen.

Keyboard Input

<kbd>⌘ Command</kbd>.

To switch the keyboard layout, press ⌘ Super + Space.

Mark Text

<mark>Marked text</mark>

You know what? I’m gonna say some very important stuff, so important that even bold is not enough.

Deleted and Inserted Text

<del>Something deleted</del> <ins>Something added</ins>

~~Text deleted~~ Text added

Progress Indicator

<progress></progress> <progress value="33" max="100"></progress>

Sample Output

<samp>Sample Output</samp>

Sample Output

Inline Quotation

<q>Someone said something</q>

Blah blah Inline Quote hmm.

Unarticulated Annotation

<u>Gmarrar mitsakes</u>

Yeet the sus drip while vibing with the TikTok fam on a cap-free boomerang.

Titles

<strong class="title">Title-Looking Text</strong>

Title-Looking Text

External Links

<a class="external" href="https://example.org">External link</a>

Link to site

Spoilers

<span class="spoiler">Some spoiler</span>

You know, Ametrines are very pretty. I know, crazy.

With solid class:

<span class="spoiler solid">Some spoiler</span>

You know, Ametrines are very pretty. I know, crazy.

Buttons

<div class="buttons">
  <a href="#top">Go to Top</a>
  <a class="suggested external" href="https://example.org">Example</a>
</div>

Go to Top Example

With centered and big classes:

<div class="buttons centered big">
  <button class="suggested">Do Something…</button>
</div>

Standalone:

<button class="suggested">Do Something…</button>
<a class="button external" href="https://example.org">Example</a>

Example

Disabled:

<button disabled class="suggested">Do Something…</button>
<a aria-disabled="true" class="button external" href="https://example.org"
  >Example</a
>

Example

Accent Color

For demo purposes only, usually it should be changed from the config file.

hsl(, , )

下载指定路径中的文件

例如当前博客文件夹中的playlist.csv

若图片文件能索引到，可以更好的显示
<a id="download-csv" class="card" href="playlist.csv"> playlist.csv • 9.1 kB</a>

URL 和电子邮件地址

Spotify

要快速将 URL 或电子邮件地址变成链接，请用尖括号将其括起来^[4]。

http://markdownguide.cn fake@example.com

呈现的输出如下所示

http://markdownguide.cn

格式化链接 ⭐✅

[!WARNING] > [!WARNING] 警告要强调链接，请在方括号和圆括号前后添加星号。要将链接表示为代码，请在方括号中添加反引号。

引用式链接

⚠️ 文内引用跨文引用，找更直观的理解

引用式链接是一种特殊的链接，它使 URL 在 Markdown 中更易于显示和阅读。引用式链接由两部分构成：一部分与文本保持一致，另一部分存储在文件中的其他位置，以保持文本易于阅读。

图像^[5]

添加一个感叹号 (!)，后跟方括号中的备用文本，以及括号中图片资源的路径或 URL。您可以在路径或 URL 后添加引号中的标题（可选）。 ![图片名称](图片URL "图片悬浮信息")
路径是相对于该博客路径为基础，相对于图片的位置，若图片和博客为同一路径，直接书写图片名称即可
推荐png格式

标题 ID \

许多 Markdown 处理器支持标题的自定义 ID——一些 Markdown 处理器会自动添加它们。添加自定义 ID 允许您直接链接到标题并使用 CSS 修改它们。要添加自定义标题 ID，请在与标题同行的花括号中括起自定义 ID。

My Great Heading \

HTML 如下所示

My Great Heading

链接到标题 ID 您可以通过创建带有数字符号 (#) 和自定义标题 ID 的标准链接来链接到文件中带有自定义 ID 的标题。这些通常称为锚链接。

Markdown HTML 呈现的输出标题 ID 标题 ID

标题 ID 其他网站可以通过将自定义标题 ID 添加到网页的完整 URL 来链接到标题（例如，标题 ID）。

UML等图

前置条件: 项目中需要引入指定的js文件实现渲染转换，后续再引入该功能

Footnote (link) ↩
Footnote ↩
https://genius.com/37573135 ↩
https://genius.com/29300699 ↩
Update: between first revision of this post and the time I write this at we played it again after such a ↩

Zola

2026-10-15T00:00:00+00:00

本文受众：Zola博客引擎， ametrine博客主题，复现本博客网站的爱好者，以及 ¯\(°_o)/¯ me

单独说明，若是我个人针对ametrine博客主题添加的网站特写会单独说明
tldr： 直接去主题开发者或你熟知的 github.io 参考 workflows中的部署yml文件进行本地部署复现
然后根据文档和 AI 进行逐行熟悉源项目再魔改成自己的

Blog-md 标签头

颜色

色相（Hue）‌：颜色在色轮上的位置，范围 0–360 度。0 是红色、120 是绿色、240 是蓝色。
饱和度（Saturation）‌：颜色的鲜艳程度，0% 是灰色，100% 是最鲜艳的纯色。
亮度（Lightness）‌：颜色的明暗程度，0% 是黑色，100% 是白色。‌‌

可借助Snipaste-截图贴图中的取色器获取到RGB值，在RGB转HSL在线网站转换即可

accent_color = ["red", "blue", "orange","green"] # 懒惰写法
accent_color = ["hsl(123, 33%, 60%)", "hsl(27.567572, 87%, 67%)"] # 更符合人类感知

hsl(123, 86%, 33%) # 柔和草绿

# Has several modes:
# - Use one of the presets (applies to both light and dark modes):
#   accent_color = "<red, orange, yellow, green, blue, purple>"
# - Use a single HSL color for both light and dark modes:
#   accent_color = "hsl(270, 50%, 60%)"
# - Use separate colors for light and dark modes (it's possible to mix both
# presets and HSL colors):
#   Presets:    accent_color = ["red", "blue"]
#   Preset + HSL:   accent_color = ["red", "hsl(270, 50%, 60%)"]
#   HSLs: accent_color = ["hsl(270, 50%, 60%)", "hsl(27.567572, 87%, 67%)"]
#
# Custom colors must be in HSL format. You can also define your own color

RSS/Atom订阅

updated = 2026-10-15
date = 2026-10-15 # 该字段必须要有的

归类

优先使用现有归类，除非后续博客产出过多，否则不单独新增归类

categories = ["Doc","Tracking"] # 需要持续迭代更新的帮助文档

字体字号

全局字体位置：sass/fonts.scss (line 5)

:root {
  --font-sans-serif: "Golos Text";
  --font-monospace: "Commit Mono";
}

主题的 body 直接消费它（themes/ametrine/sass/citrine/sass/base/_base.scss:33）：

body {
  font-family: var(--font-sans-serif), var(--font-system-ui), var(--font-emoji);
}

所以改 –font-sans-serif 就能改全站默认正文/UI 字体；代码块仍走 –font-monospace。如果换成新字体，先在同一个文件里补 @font-face，再把变量指过去

+++
title = "文章标题"
date = 2026-10-21
[extra]
body_font_size = "19px"  # 可选，不写则继承全局 21px
body_font = "pop"
+++

#	body_font取值	字体字典	Duration
1	golos Golos Text	golos Golos Text	主题默认字体
2	`pop`	华康 POP1 体	Identify-V 中文
3	essay	Essay Text	Identify-V 英文
4	mono	Commit Mono	等宽
1	wenkai	霞鹜文楷	主题默认字体
2	fangsong	仿宋	Identify-V 中文
3	sarasa	纱黑体	Identify-V 英文
4	pingfang	系统 PingFang SC（Apple 设备）	等宽

加解密

个人功能

跳转链接查看示例效果

+++
title = "通过 Little Snitch 屏蔽网站"
description = "基础教程"
updated = 2026-06-21
date = 2026-06-20
[taxonomies]
tags = ["Network"]
[extra]
accent_color = ["hsl(145 22% 34%)", "hsl(145 28% 50%)"]
[extra.encryption]
encrypt = true
+++

屏蔽RSS/Atom订阅

个人功能正确写法是放在 front matter 顶层（不要放进 [extra]）该文章会从根 feed 和所在板块 feed 中消失，文章本身仍能正常访问。它只影响订阅源，不影响页面发布；如果还想让它不进搜索，再另加 in_search_index = false

encrypt = true 的文章因为 post-build.mjs 的过滤，本身已经不会出现在 feed 里；include_in_feeds = false 更适合“不加密、但就是不想进 RSS”的普通文章。两者都写时也不冲突，include_in_feeds = false 会在 Zola 生成 feed 阶段就先排除。

+++
title = "不进入 RSS 的文章"
date = 2026-10-20
include_in_feeds = false
+++

+++
title = "Untitled 2025.m3u"
description = "My musical preferences of 2025, in a playlist form."
updated = 2026-07-04
[taxonomies]
tags = ["Music", "Playlist"]
[extra]
accent_color = ["hsl(209.49, 35.76%, 32.35%)", "hsl(200.0, 15.19%, 69.02%)"]
banner = "banner.webp"
styles = ["blog/2025-playlist/style.css"]
+++

Blog-md 内容主体

[!WARNING] > [!WARNING] 警告

看板

主题更新 -ametrine

以ametrine主题为当前核心主题

cd ~/00BlogZola

# ① 先回到主仓库当前记录的提交，确保是干净基线（可选但推荐）
git submodule update themes/ametrine

# ② 拉取新版主题：main 分支最新 + 初始化并递归更新嵌套子模块
#    （--init --recursive 会拉取 sass/citrine，这是新版能编译的关键）
git submodule update --remote --init --recursive themes/ametrine

# ③ 先编译验证（与 CI 完全一致的完整流程用 ./build-site.sh）
zola build

# ④ 编译失败 → 撤销本次拉取，回到主仓库记录的旧提交
git submodule update themes/ametrine
git diff                # themes/ametrine 应不再出现
git submodule status    # 前面无 + / - 符号即已回到记录提交

#如果第 ④ 步提示本地有改动不让覆盖，加 --force：
git submodule update --force themes/ametrine

# 上述是给读者详解，以下是 个人一键命令使用的
cd ~/00BlogZola

git submodule update --remote --init --recursive themes/ametrine

if zola build; then
  echo "✅ 新版主题编译通过（尚未记录，确认保留后再提交）"
else
  echo "❌ 编译失败，自动撤销本次拉取"
  git submodule update themes/ametrine
fi

关键提醒

回退为什么有效：主仓库「记录的」子仓库提交始终是旧的 fc6f62c217ae，只要你在成功之前不执行 git add themes/ametrine，git submodule update themes/ametrine（不带 –remote）就能把工作区拉回这个记录提交，相当于放弃新版。
确认保留新版时才提交：

git add themes/ametrine
 git commit -m "upgrade ametrine theme"
 提交之后，「记录提交」就变成新版了，此后第 ④ 步会回退到新版而不是旧版。

citrine 残留无害：回退后 themes/ametrine/sass/citrine 这个目录可能还留在本地，旧版主题不引用它，不影响编译，不用特意删。
更确定的拉取方式（可选）：如果不想依赖 –remote 对嵌套子模块的自动行为，也可以进子仓库手动拉取，与 CI 完全一致

cd ~/00BlogZola/themes/ametrine git fetch origin main git checkout origin/main git submodule update –init –recursive cd ~/00BlogZola

 之后的编译验证和回退步骤同上。

ASCII - 表情符号在博客文章

2026-10-15T00:00:00+00:00

rocket菜单栏常驻双击``触发可模糊搜索

博客文章编写，代码注释，聊天通讯均可使用，但含义必须明确通用

技术性博客编写：基于场景需求约束目标步骤验证复现这6点顺序编写

字典映射规则集合

关键字	图标含义	图标
star	重点醒目提示	⭐
white-check-mark	可行性提醒完成状态安全	✅
interrobang	有疑问	⁉️
pushpin	置顶提醒	📌
gear	配置规则	⚙️
warning		⚠️

2026-10-13T14:07:00+00:00

2026年10月13日 22:07（东八区 / 北京时间）

看板命名与 URL 唯一化：多天 / 全天 / 上午 / 下午 / 晚上五类各自独立可达 · 修复 path collisions

概述

本轮处理新建看板后构建直接失败的问题，并一次把它根治：

报错：新建 2026-10-13 晚上看板后，构建报 Found path collisions，两块不同日期的看板抢同一条 URL；
根因：Zola 会把文件名开头的 YYYY-MM-DD 当成页面日期剥离，只剩「晚上」参与 slug，于是 2026-08-11_晚上.md 与 2026-10-13_晚上.md 都会变成 /kanban/wan-shang/；编辑器此前只保证文件名唯一，没管 URL 唯一；
修复（URL）：每块看板都由编辑器自动写入 slug（= URL 安全化的文件名），让五类看板各有唯一可达的 URL；
修复（命名与锁定）：多天看板改用 周开始-周结束-打开编辑器时的时分 命名（如 2026-06-16-06-22-2236.md），从文件名上就和单日「全天」区分开；同时收紧编辑锁定 —— 单日看板的周开始、周结束都锁定，多天看板只锁定周开始；新建时还会提示「该时间段已有看板」；
收尾：把 2026-06/07 创建的 4 块多天看板也统一迁移到新命名，并用 aliases 保住旧 URL。

一、报错现象

在 GUI 里新建单日看板，按提示在仓库里创建文件、粘贴生成的 Markdown 并保存后，本地 zola serve 与 zola build 同时失败：

ERROR Failed to build the site
ERROR Found path collisions:
- `/kanban/wan-shang/` from files
  {content/kanban/2026-08-11_晚上.md, content/kanban/2026-10-13_晚上.md}

粘贴的 Markdown 本身没有语法问题：front matter 合法、栏目与卡片规则也正确。问题出在文件名 → URL 这一层。

二、根因：文件名的日期段被剥离成页面日期

Zola 会把页面文件名开头的 YYYY-MM-DD 当作页面日期，并从 slug 里去掉，只让剩下的部分参与 URL：

文件	生成的 URL
`2026-06-16.md`	`/kanban/2026-06-16/`
`2026-08-11_晚上.md`	`/kanban/wan-shang/` ← 只剩「晚上」被转写成拼音
`2026-10-13_晚上.md`	`/kanban/wan-shang/` ← 与上一行撞车

结论：只要两块单日看板的时段相同（上午 / 下午 / 晚上），无论日期差多远，都会落到同一条输出路径。命名规则 week_start_时段 只保证了文件名唯一，而 Zola 恰好把日期前缀吃掉了。

复现方式：在最小 Zola 工程里放两个不同日期、同一时段的文件，得到一字不差的同一条报错；给其中一块补上 slug 后立刻构建通过。

三、修复方案

3.1 编辑器自动写入 slug

static/js/kanban-editor.js：新增时段拼音映射与 buildUrlSlug()：
- 上午 → shang-wu、下午 → xia-wu、晚上 → wan-shang；
- stateToBoard() 把 slug = URL 安全化的文件名 写进 front matter（五类看板都写，不再依赖 Zola 从文件名推导）。
static/js/kanban-rules.js：serializeMarkdown() 在 date 之后输出 slug 行；解析器本来就能读任意顶层键，所以用 GUI 修改已有看板时也不会把 slug 弄丢。

3.2 文件名与 URL 方案

看板类型	文件名	生成的 URL
多天（跨天周计划）	`2026-06-16-06-22-2236.md`（周开始 - 周结束的月-日 - 打开编辑器时的时分）	`/kanban/2026-06-16-06-22-2236/`
单日「全天」（不选时段）	`2026-10-13.md`	`/kanban/2026-10-13/`
单日上午	`2026-10-13_上午.md`	`/kanban/2026-10-13-shang-wu/`
单日下午	`2026-10-13_下午.md`	`/kanban/2026-10-13-xia-wu/`
单日晚上	`2026-10-13_晚上.md`	`/kanban/2026-10-13-wan-shang/`

文件名同时就是「生成并复制到剪贴板 / 同步到仓库」提示的目标文件名；多天看板的时分取自打开 GUI 编辑器的那一刻，编辑过程中不再变化；
修改已有看板时沿用原文件名、并保留已有 slug，所以改内容不会改 URL。

3.3 编辑锁定规则

看板类型	周开始	周结束	时段
单日（含「全天」）	锁定	锁定（起止同一天）	锁定
多天（跨天）	锁定	可改（开始 +13 天以内）	不适用

3.4 现有文件与文档

出问题的 content/kanban/2026-10-13_晚上.md 补上 slug = "2026-10-13-wan-shang"，构建立刻恢复；
旧的 2026-08-11_晚上.md 保持原样，URL 仍是 /kanban/wan-shang/，不影响既有链接；

2026-06/07 创建的 4 块多天看板已统一迁移到新命名，并同时写入 slug（新 URL）与 aliases（旧 URL）：

旧文件名	新文件名	新 URL	旧 URL（redirect）
`2026-06-16.md`	`2026-06-16-06-22-0934.md`	`/kanban/2026-06-16-06-22-0934/`	`/kanban/2026-06-16/`
`2026-06-22.md`	`2026-06-22-06-23-0934.md`	`/kanban/2026-06-22-06-23-0934/`	`/kanban/2026-06-22/`
`2026-06-25.md`	`2026-06-25-06-30-1316.md`	`/kanban/2026-06-25-06-30-1316/`	`/kanban/2026-06-25/`
`2026-07-13.md`	`2026-07-13-07-19-1800.md`	`/kanban/2026-07-13-07-19-1800/`	`/kanban/2026-07-13/`

（迁移用的时分取自各文件原本的最后修改时间；旧 URL 会 301/跳转到新 URL，历史 nanolog 里指向 /kanban/2026-06-16/ 的链接依旧可用。）

content/kanban/kanban-mapping.md 补上命名规则、URL 对照表、编辑锁定规则、带 slug 的 front matter 示例与字段说明；
scripts/verify-kanban-build.mjs 同步按新规则推导输出目录（多天 / 全天 / 时段三种命名都能校验）。

3.5 新建时的重复看板提示

编辑器会读取列表页内嵌的看板清单（热力图容器的 data-json），在新建时判断所选时间段是否与已有看板重叠；
完全相同 → 提示「该时间段已有看板：<核心任务>（起 ~ 止），建议点它的「✎ 编辑」修改」；部分重叠 → 提示会并存两块重叠看板；
修改已有看板时不显示该提示。

3.6 让 aliases 在 GUI 修改后仍然保留

kanban-rules.js：parseFrontMatter() 识别顶层 aliases = ["…"]，serializeMarkdown() 在 slug 之后重新输出 aliases；
kanban-editor.js：boardToState() 读入 aliases、stateToBoard() 写回；
这样用 GUI 编辑迁移后的看板再保存，旧 URL 的跳转不会丢。

四、验证

逻辑 + 端到端：直接加载真实的规则引擎、并从编辑器源码里抽取真实的 buildSlug() / buildUrlSlug() 跑用例（新建五类 + 修改三类 + 同一天「多天 vs 全天」互不冲突），再把生成的 Markdown 放进一个最小 Zola 工程构建 —— 五类看板的 URL 各自唯一，无冲突；
重复提示：用真实的看板清单数据跑冲突判定 —— 完全相同 / 部分重叠 / 不重叠 / 修改模式四种情况结果正确；
front matter 回写：解析后再序列化，slug 与 aliases 都能原样保留；
真站构建：zola build 通过（285 个页面 = 原有页面 + 4 个旧 URL 跳转页），scripts/verify-kanban-build.mjs 通过（6 块看板，列表卡片与周页一一对应）；
页面可达：新看板详情页 /kanban/2026-10-13-wan-shang/、迁移后的 4 个新 URL 全部生成；4 个旧 URL 均生成跳转页（如 /kanban/2026-06-16/ → /kanban/2026-06-16-06-22-0934/）；旧看板 /kanban/wan-shang/ 不受影响。

五、注意事项

新命名生效后，多天、全天、上午、下午、晚上五类看板可以在同一天共存，URL 各自唯一；4 块历史多天看板已迁移到新命名并通过 aliases 保住旧链接，只有更早的 2026-08-11_晚上.md 还保留着「URL 只剩余下时段」的历史形态；
旧的 2026-08-11 晚上看板如果日后用 GUI 编辑并保存，会自动获得 slug = "2026-08-11-wan-shang"，其 URL 会从 /kanban/wan-shang/ 变为 /kanban/2026-08-11-wan-shang/（如需保住旧链接，可再加 aliases）；
新建看板若与已有看板时间段重叠，编辑面板会给出提示，避免无意间建出两块同周看板；
顺带调整：/kanban/ 热力图的月份选择器改为默认当前月份；若当月还没有看板，卡片列表会自动回退展示最近一个有看板的月份并给出提示，避免整屏空白。

相关链接：周计划看板 · 映射说明 · Ametrine 主题

2026-10-13 晚上计划

2026-10-13T00:00:00+00:00

待办

进行中

单词速记

@start 2026-10-13 @due 2026-10-13 @priority 3 @goal risk @top purple @cover full

考研报名 - 材料准备

@start 2026-10-13 @due 2026-10-13 @priority 3 @goal risk @top purple @cover full

15日后正式报名不可错过

已完成

Tealdeer - cmake 手册维护

@start 2026-10-13 @due 2026-10-13 @priority 1 @goal complete @bg yellow @top green @cover half

cmake - 自定义页面
sc-cmake - 自定义页面

学习掌握 TLDR语法维护cmake 自定义页面

主题仓库更新 - Tera2

@start 2026-10-13 @due 2026-10-13 @priority 4 @goal complete @bg blue

进度

10-13 周二

主题更新

谮言 · 滞后性

2026-10-11T00:00:00+00:00

结果有滞后性，习惯培养有滞后性，法律本身就是滞后性，可我们有时候就很简单直接的没有预见这个问题，将失败当作结果，没有坚持下去。

我在这里并非是去歌颂坚持或解构放弃，而是站在事物发展的角度上思考，如何具体的审视是否存在滞后性，若存在该如何判断

Tealdeer v1.8安装教程

2026-10-11T00:00:00+00:00

TLDR

Tealdeer 是Rust版的TLDR工具；个人感觉比tldr(tlrc) 更好用；但文档不清晰，现有教程落后，补充当前可用操作；

安装和通用配置命令

brew install tealdeer #通过Homebrew  安装tealdeer
tldr --seed-config # 创建默认配置 必须要操作

https://docs.tealdeer.org/stable/ 简单查看配置中节点说明默认配置中会直接设置在线文档的URL，既往搜索记录均是错误这是一个踩坑点
默认配置中手动指定语言，与tlrc和既往版本不一致
若仓库已经安装过tldr 或 tlrc ,必须先 brew unlink tldr/tlrc

常见命令

tldr --show-paths
tldr git --edit-page # 修改自定义页面
tldr git --edit-patch # 修改 自定义补丁页面

常见场景：

上游现有页面
自定义页面（覆盖同名1） .page.md
扩展现有页面 (追加 1 ) .patch.md 警告，扩展不对自定义页面服务

后期定期将自定义路径中扩展页面上传到仓库中归档保存备份

为何要用TLDR ?

tldr 在日常开发和系统管理工作中扮演着重要的角色，极大地提升了效率：

优点：

尊重时间：用户普遍认为 tldr 在最短时间内提供了最直接、可操作的命令示例，极大地提升了日常工作效率。
极高的易用性和记忆效率：简洁的格式不仅易于快速消化，也更容易被用户记住。
社区驱动的活力：开放的贡献模式使得内容能够持续更新和完善。
灵活的跨平台支持：多样化的客户端满足了不同用户和环境的需求。缺点与权衡：
深度和全面性不足：这是最常被提及的缺点。tldr 为了简洁而牺牲了全面性，对于不常见的用例或需要理解命令底层工作原理的场景，用户仍需回归 man 页面。
覆盖范围有限：对于一些较新、较小众或特定领域的命令行工具，可能不存在对应的 tldr 页面。
示例可能过于简化：在某些情况下，tldr 提供的示例可能无法满足中高级用户的复杂需求。
潜在的依赖风险：一些经验丰富的用户担忧，过度依赖 tldr 可能会让新手养成“只知其然，不知其所以然”的习惯，从而阻碍他们深入学习和理解 shell 命令及操作系统。

以实例为中心：这是 tldr 最受赞誉的特点。它不解释命令的每一个参数，而是直接展示 80% 最常见的用例。例如，对于 tar 或 ffmpeg 等拥有大量复杂参数的命令，tldr 直接提供“解压一个 .tar.gz 文件”或“从视频中提取音频”等具体示例，让用户能够快速上手。 比手册man更快
简洁易读的格式： tldr 的信息结构简洁明了，通常只包含几行文字和几个代码示例。输出通常带有语法高亮，格式清晰统一，非常适合快速扫读和复制粘贴。

离线访问能力：大多数 tldr 客户端在首次运行时会下载并缓存所有页面到本地。这意味着一旦页面被缓存，即使在没有网络连接的环境下，用户也能快速查询命令用法，确保了工作流的连续性

自定义页面/补丁扩展页面: 解决在线文档没有覆盖但个人需要的部分

github_proxy：一个开关接管 zsh、git 与 Homebrew 的 GitHub 加速

2026-10-02T00:00:00+00:00

github_proxy：一个开关接管 zsh、git 与 Homebrew 的 GitHub 加速

TL;DR：无代理、无 VPN 的国内网络下，github_proxy on 让 zsh 里的 git clone/fetch、curl/wget，以及 Homebrew 升级时对 GitHub 的直连 全部改走镜像；github_proxy off 一键恢复直连。核心依据是三个实测结论：brew 调用外部命令时会过滤非 HOMEBREW_ 前缀的环境变量；HOMEBREW_ARTIFACT_DOMAIN 在这版 brew 里只管 ghcr.io；真正能接管 brew 网络请求的是它的 shim（HOMEBREW_CURL / HOMEBREW_GIT）。实测同一个 GitHub 托管的 cask：直连 240 秒超时失败，走镜像 2 秒完成，且文件 SHA-256 与官方一致。

1. 前置条件与适用环境

项目	本机实测值	说明
系统	macOS 27.2 / Apple Silicon	Intel 机器同样适用
Shell	zsh 5.9 + Oh My Zsh	依赖交互式 zsh 加载 `~/.zshrc`
Homebrew	7.0.7（`/opt/homebrew`）	接管 Homebrew 需要 4.x 以上
git / curl	git 2.56.0 / curl 8.7.1	macOS 自带或 brew 安装均可
网络	国内直连，无代理无 VPN	hf-mirror、gh-proxy 可达
镜像	`https://gh-proxy.com/`	可用 `GITHUB_PROXY_MIRROR` 替换
已存在的本机镜像	USTC：API / bottles / brew.git / homebrew-core.git	与本方案互补，不冲突

前置认知：镜像只能解决“能不能下、下得快不快“，不能改变下载内容——所有经镜像下载的文件仍由原工具按 SHA-256 校验，校验不过就重来，不存在被镜像掉包的风险。

适用边界：本方案面向“在终端里干活“的场景。
浏览器、VS Code、npm/pip/go、以及程序内自建 HTTP 客户端的下载（例如 focr）不经过 zsh 也不经过 brew，
函数无法接管——那类工具要用它自己的镜像参数（如 --manifest、PIP_INDEX_URL）。

> **需求场景描述**

Homebrew 下载更新（cask类型； Formula –build-form-source 类型；第三方Tap 走github做仓库） brew update, brew upgrade, brew install –build-from-source
Github url 安装更新拉取模型，例如 focr focr pull
Github 代码仓库 git clone , git pull ,git push

2. 文件与路径一览

路径	作用	需要手动提供？
`~/.zsh/functions/github_proxy.zsh`	主脚本（约 590 行），由 `~/.zshrc` 自动 source	✅ 唯一需要你放的文件
`~/.local/state/github-proxy/state`	开关状态文件，唯一权威来源（内容为 `on` / `off`）	❌ 首次 `on`/`off` 时自动生成
`~/.local/state/github-proxy/bin/brew-curl`	自动生成的 curl 包装器（镜像地址写死在文件内）	❌ 加载脚本时自动生成
`~/.local/state/github-proxy/bin/brew-git`	自动生成的 git 包装器	❌ 加载脚本时自动生成
`~/.local/state/github-proxy/debug`	调试开关的标记文件（存在即记录）	❌ 仅 `debug on` 时创建
`~/.local/state/github-proxy/brew.log`（含 `.1`）	调试日志：包装器实际请求的地址，超 1 MB 自动轮转	❌ 仅调试时写入

结论：你只需要提供 1 个文件——主脚本（附录 A）。
其余 5 个都是运行时产物，删掉后下次开 shell 会自动重建；反过来，把它们拷贝给别人也没有意义（包装器里写死了镜像地址与绝对路径）。

附录 B 列出了自动生成文件的具体内容，方便先审阅再落地。

加载链路：github_proxy.zsh 放在哪个目录由你决定，关键是在 ~/.zshrc 里写出这个路径并 source 它——这就是全部的“安装动作“：

# ~/.zshrc —— 指向你自己存放该脚本的位置（本项目示例放在 ~/.zsh/functions/）
source ~/.zsh/functions/github_proxy.zsh

若习惯把自定义函数集中管理，也可以整目录遍历加载（此时无需逐个写文件名）：

if [ -d ~/.zsh/functions ]; then
    for func in ~/.zsh/functions/*.zsh; do
        source "$func"
    done
fi

状态目录则固定在 XDG_STATE_HOME（默认 ~/.local/state）下，属于“可重建的运行态“，删掉也能自动重建。

3. 功能

3.1 命令速查

github_proxy            # 看状态
github_proxy on         # 开启（默认状态）
github_proxy off        # 关闭，全部直连
github_proxy toggle     # 切换
github_proxy test       # 实测镜像 vs 直连速度
github_proxy url <URL>  # 只看改写结果，方便排查
github_proxy brew       # 看 Homebrew 接管状态
github_proxy debug on   # 记录包装器实际请求的地址（排查用）

3.2 接管范围矩阵

场景	是否接管	走向
`git clone / fetch / pull / ls-remote / submodule`	✅	走镜像
`git push`	➖ 不动	仍走你自己的 SSH（见 4.2）
`curl` / `wget` 中的 github 域名	✅	走镜像
Homebrew 升级时的 cask 包 / formula 源码 / tap 定义	✅	走镜像
Homebrew 的 API / bottles / 核心仓库	➖ 不动	你已有的 USTC 镜像
`gh` CLI	❌	自带客户端，只能用 `HTTPS_PROXY`
npm / pip / go / VS Code / 浏览器 / focr	❌	不经过 zsh，需各自配置
SSH 形式 `git@github.com:…`	❌	保持直连（国内一般可用）

3.3 三种状态语义

状态	含义	持久化
`on`	走镜像（默认）	写入 state 文件
`off`	完全直连，且不残留任何环境变量	写入 state 文件
`GITHUB_PROXY_FORCE=off zsh`	只影响这次会话的临时覆盖	不动 state 文件

4. 设计：三层接管

flowchart TD
    A["你在 zsh 里敲命令"] --> B["git / curl / wget 函数包装层<br/>改写参数里的 URL"]
    C["brew upgrade / fetch"] --> D["HOMEBREW_CURL_PATH<br/>HOMEBREW_GIT_PATH"]
    D --> E["生成的包装器<br/>brew-curl / brew-git"]
    B --> F["https://gh-proxy.com/https://github.com/…"]
    E --> F
    F --> G["镜像回源并返回<br/>原工具仍校验 SHA-256"]

4.1 第一层：zsh 函数改写参数

curl / wget 被函数包裹，只改写以 http(s):// 开头的参数，其余参数（-o、-H、--data 等）原样透传：

curl() {
  local -a args=()
  local a
  for a in "$@"; do
    case "$a" in
      http://*|https://*) args+=("$(_gp_url "$a")") ;;
      *)                  args+=("$a") ;;
    esac
  done
  command curl "${args[@]}"
}

改写是双向可逆的：_gp_unmirror 会先剥掉已有的镜像前缀再按当前开关决定，所以从浏览器复制来的 gh-proxy.com/https://github.com/… 在关闭状态下会自动还原成直连地址。

4.2 第二层：借 git 自己的 URL 重写规则

git 函数不直接改参数，而是注入 git 原生的重写配置——这样仓库里记录的 remote 地址仍然是原始 GitHub 地址，关掉开关就自动恢复直连，不会把镜像地址固化进 .git/config：

git() {
  ...
  local -a cfg=()
  for h in github.com raw.githubusercontent.com codeload.github.com \
           gist.github.com objects.githubusercontent.com; do
    cfg+=(-c "url.${m}https://${h}/.insteadOf=https://${h}/")
  done
  command git "${cfg[@]}" "$@"
}

git push 不做任何注入，保持原样——本机全局配置里本来就有 pushInsteadOf = https://github.com/（推送改走 SSH），所以写操作永远不受影响。

唯一需要补救的是 git clone：实测 git 会把实际使用的地址写进 .git/config。因此 clone 结束后脚本会把 remote 还原成原始地址，子模块一并处理：

if (( rc == 0 )); then
  case "$sub" in
    clone)     _gp_clone_target_dir "$@" && _gp_fix_remotes "$target" ;;
    submodule) _gp_fix_remotes "$PWD" ;;
  esac
fi

4.3 第三层：Homebrew 的 shim 才是接管点

brew 是 Ruby 程序，它发出的请求不经过 zsh。但它调用外部命令时会先经过自己的 shim，而 shim 会执行 $HOMEBREW_CURL / $HOMEBREW_GIT：

# /opt/homebrew/Library/Homebrew/shims/shared/curl（节选）
try_exec_non_system "${HOMEBREW_CURL:-curl}" "$@"
safe_exec "/usr/bin/curl" "$@"

而 brew.sh 的 setup_curl() / setup_git() 会优先采纳环境变量：

elif [[ -n "${HOMEBREW_CURL_PATH}" ]]
then
  HOMEBREW_CURL="${HOMEBREW_CURL_PATH}"

于是 github_proxy on 只要生成两个包装器脚本并导出两个变量，brew 的全部 curl/git 调用就都过我们的手了。验证方式极简——让 brew 自己告诉我们它用的是谁：

$ HOMEBREW_CURL_PATH=/path/to/wrapper brew config | grep '^Curl:'
Curl: 8.7.1 => /path/to/wrapper

4.4 三个反直觉的实测结论

① brew 会过滤非 HOMEBREW_ 前缀的环境变量。 用一个只记录参数的探针包装器挂在 HOMEBREW_CURL_PATH 上，同时导出 GITHUB_PROXY_MIRROR 和 GITHUB_PROXY_DEBUG，包装器收到的是空值：

MIRROR_ENV=[] DEBUG_ENV=[]

结论：镜像地址不能靠环境变量传给包装器，必须在生成包装器时写死进文件。

② HOMEBREW_ARTIFACT_DOMAIN 在这版 brew 里只管 ghcr.io。 翻源码可以看到它只对 GitHub Packages 域名生效：

# Library/Homebrew/download_strategy/curl_download_strategy.rb
u.sub(%r{^https?://#{GitHubPackages::URL_DOMAIN}/}o, "#{domain}/")
# github_packages.rb: URL_DOMAIN = "ghcr.io"

所以网上那套“设置 HOMEBREW_ARTIFACT_DOMAIN 就能给所有下载加速“的说法，在 7.x 上对 github.com 无效。

③ 导出的开关变量会泄漏，导致“关了却还是开着“。 早期版本把 GITHUB_PROXY 导出给子进程判断，结果它被子进程继承，新终端里读到的仍是 1，状态文件写着 off 却依然走镜像。修法是让状态文件成为唯一权威，GITHUB_PROXY 只做本 shell 内镜像变量且不导出；需要临时覆盖时用语义明确的 GITHUB_PROXY_FORCE。

④ 有些请求的命令行里根本没有 URL。 brew update 更新第三方 tap 时执行的是 git -C <tap目录> fetch --force origin——地址来自仓库 .git/config 里的 remote.origin.url。只改写命令行参数的包装器对这类请求完全无效，于是 20 个 tap 各自裸连 github.com，各卡满 75 秒连接超时。修法是让包装器额外注入 git 原生的重写规则：

cfg=()
for h in github.com raw.githubusercontent.com codeload.github.com gist.github.com; do
  cfg+=(-c "url.${MIRROR}https://${h}/.insteadOf=https://${h}/")
done
# …改写命令行参数后一并传入
exec "$REAL" "${cfg[@]}" "${args[@]}"

验证方式是用 GIT_TRACE=1 看真实连接，修复后变成 git-remote-https origin https://gh-proxy.com/https://github.com/<user>/homebrew-tap；同一台机器上 brew update 从「20 个 tap 全部 75 秒超时」变成 14 秒完成、0 失败。

5. 关键实现片段

生成的 curl 包装器（brew-curl，由主脚本按当前镜像生成）：

#!/bin/bash
# 由 github_proxy.zsh 自动生成，请勿手改
MIRROR="https://gh-proxy.com/"
REAL="/usr/bin/curl"
args=()
for a in "$@"; do
  case "$a" in
    https://github.com/*|https://raw.githubusercontent.com/*|https://codeload.github.com/*|https://gist.github.com/*|https://objects.githubusercontent.com/*)
      args+=("${MIRROR}${a}") ;;
    *) args+=("$a") ;;
  esac
done
exec "$REAL" "${args[@]}"

几个刻意的设计选择：

只改写白名单域名，https://itsycal.s3.amazonaws.com/… 这类非 GitHub 地址原样直连，避免把镜像当成通用代理而拖垮无关下载。
REAL 写死为真实 curl 路径（默认 /usr/bin/curl，设了 HOMEBREW_FORCE_BREWED_CURL 则用 brew 的 curl），不通过 PATH 查找，杜绝包装器递归调用自己。
brew-git 对 push 直接 exec 原样放行，写操作绝不经过镜像。
brew-git 额外注入 -c url.*.insteadOf：brew 更新第三方 tap 用的是 git fetch origin，命令行里没有 URL，只改写参数的写法会漏掉这类请求（见 4.4 ④）。
off 时还原而非清空：如果用户自己设过 HOMEBREW_CURL_PATH，脚本先记下原值，关闭时完整还回去。

调试日志的埋点也很克制——包装器每次只多一次文件存在性判断，github_proxy debug on 时才追加写入，日常零开销：

if [ -e "$MARKER" ]; then
  { printf '== %s\n' "$(date +%T)"; for a in "${args[@]}"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
fi

6. 测试与验证

6.1 探针：先看 brew 到底请求了什么

把只记录、不改写的探针挂在 HOMEBREW_CURL_PATH 上跑一次 brew fetch --build-from-source，抓到的真实地址正是 USTC 镜像覆盖不到的部分：

https://raw.githubusercontent.com/Homebrew/homebrew-core/3a68ac0…/Formula/d/dust.rb
https://codeload.github.com/bootandy/dust/tar.gz/refs/tags/v1.2.6
https://github.com/bootandy/dust/archive/refs/tags/v1.2.6.tar.gz

这解释了为什么配了 USTC 镜像，升级时依然会卡——元数据和 bottle 走了镜像，formula 定义、源码包、cask 的 app 包仍然是直连。

6.2 速度对比

场景	直连	走镜像
`brew fetch --cask hiddenbar`（约 2 MB，GitHub Releases）	240 s 超时失败	2.0 s
`brew fetch --cask maccy`（约 5 MB，GitHub Releases）	未单独计时	2.2 s
`brew fetch --build-from-source jq`（源码包在 GitHub）	单次 >160 s 仍未完成	—
10 MB 单文件三次采样	158 / 11 / 45 KB/s	24 / 51 / 44 KB/s

必须诚实地说：镜像不是恒定更快。上表最后一行显示两者都在抖动区间里，本机也测到过镜像 9.4 MB/s 的高峰与几十 KB/s 的低谷。镜像的主要价值是可达性兜底——直连会出现彻底超时（000）或长时间挂住，镜像通常能救回；具体该开还是该关，用 github_proxy test 当场判断。

6.3 内容完整性

经镜像下载的文件全部与原工具校验值一致：

文件	校验结果
`tokenizer.json`（9.5 MB，GitHub Releases）	SHA-256 与官方清单一致
`Hidden-Bar-v1.11.1-macos.zip`	与 cask 的 `sha256` 一致
`Maccy.app.zip`	与 cask 的 `sha256` 一致

6.4 on/off 双状态校验

用真正走 source ~/.zshrc 的全新交互式终端逐项验证：

检查项	ON	OFF
`HOMEBREW_CURL_PATH`	指向 `brew-curl`	未设置
`brew config` 的 Curl 行	`=> …/bin/brew-curl`	`=> /usr/bin/curl`
`git ls-remote github.com`	正常（走镜像）	直连，可能超时（网络本身抖动）
`curl` 取 raw.githubusercontent 文件	200	200
`brew info`（USTC API）	正常	正常
GitHub 托管的 cask 下载	正常	依赖直连状态
`git push`	走 SSH，不受影响	走 SSH，不受影响

另外专门构造了“脏环境“测试：故意 export GITHUB_PROXY=1 并注入 HOMEBREW_CURL_PATH，在状态文件为 off 时启动新终端——结果正确关闭（HOMEBREW_CURL_PATH 被清掉、brew 回到 /usr/bin/curl）。这正是 4.4 ③ 那个缺陷的回归验证。

6.5 踩坑记录

现象	根因	处置
改了 `HOMEBREW_ARTIFACT_DOMAIN` 对 github 无效	该变量只管 ghcr.io	改用 shim 接管
包装器拿不到镜像地址	brew 过滤非 `HOMEBREW_` 变量	生成时写死进包装器
clone 出来的仓库 push 失败	git 把镜像地址写进了 remote	clone 后自动还原 + 子模块同步
`off` 后新终端仍走镜像	导出的状态变量被继承	状态文件唯一权威、变量不导出
`brew fetch --build-from-source` 仍很慢	该路径会先拉 formula 的 `.rb` 与源码包	这两处现在也在白名单里

7. 局限与边界

只对交互式 zsh 生效；command git、绝对路径调用、脚本里的 #!/bin/sh 不经过函数。
gh CLI 走自己的 HTTP 客户端，URL 改写对它无效，只能配 HTTPS_PROXY。
SSH 形式地址保持直连；若 SSH 也不通，可在 ~/.ssh/config 里改用 ssh.github.com:443。
镜像可达性取决于第三方服务，gh-proxy.com 之外的其他候选（ghfast.top、ghproxy.net、hk.gh-proxy.com）在本机实测均已失效或极慢，所以脚本保留了“主镜像 + HF 镜像兜底“的顺序，并允许用 GITHUB_PROXY_MIRROR 随时替换。
brew 下载的大件（如 cask 里的几百 MB 应用）仍会受镜像带宽限制；此时 brew upgrade 建议放在 tmux 里跑。

8. 速查与维护

# 换镜像
export GITHUB_PROXY_MIRROR="https://你的镜像/"
github_proxy on                 # 重新生成包装器并生效

# 只关 Homebrew 接管，保留 git/curl 接管
export GITHUB_PROXY_BREW_ON=0

# 排查：看包装器实际请求了哪些地址
github_proxy debug on
brew fetch --cask maccy
tail -n 20 ~/.local/state/github-proxy/brew.log

# 体检
github_proxy status
github_proxy brew
github_proxy test

维护要点：状态目录整体可删（下次开 shell 自动重建）；off 若发现残留，先 github_proxy off 再开新终端即可，因为状态文件是唯一权威。

9. 移植到别人的机器

9.1 前置检查

zsh --version                        # 需要 zsh（macOS 自带）
ls ~/.zshrc                          # 交互式 shell 的入口配置

第一步：决定脚本放哪。 任意目录都行，下文统一以 ~/.zsh/functions/ 举例。

第二步：在 ~/.zshrc 里写出这个路径。 这是唯一必须手工添加的一行，路径换成你实际存放的位置：

source ~/.zsh/functions/github_proxy.zsh

如果同时管理多个自定义函数，可以改成整目录遍历（新增脚本就不用再改 .zshrc）：

if [ -d ~/.zsh/functions ]; then
    for func in ~/.zsh/functions/*.zsh; do
        source "$func"
    done
fi

改完后可以用这一行确认路径确实被引用了：

grep -n "github_proxy\|zsh/functions" ~/.zshrc

要求：必须是交互式 zsh（~/.zshrc 只被交互式 shell 加载）。bash、fish、脚本里的 #!/bin/sh 都不会生效。

9.2 放置脚本

方式一（推荐）：下载到你选定的目录（下面以 ~/.zsh/functions/ 为例，必须与 9.1 里写进 .zshrc 的路径一致）

mkdir -p ~/.zsh/functions
curl -fLo ~/.zsh/functions/github_proxy.zsh \
  https://suchaharcan.github.io/03Share_blog/github-proxy-zsh-brew/github_proxy.zsh

方式二：把文末 附录 A 的源码整段复制进你那个路径下的 github_proxy.zsh。

只需要这一个文件。第一次被 source 时，脚本会自己在状态目录里创建运行时文件，各文件的生成时机如下：

运行时会生成	生成时机	内容
`bin/brew-curl`、`bin/brew-git`	每次加载脚本 / `github_proxy on`	镜像地址写死在内的包装器（附录 B）
`state`	第一次执行 `on` 或 `off`	`on` / `off`，默认开启时不写文件
`debug`	`github_proxy debug on`	空标记文件
`brew.log`（+ `.1`）	调试开启且 brew 真正调用包装器时	实际请求的地址，超 1 MB 自动轮转

所以不要把 bin/brew-curl 之类拷给别人用——里面的镜像地址和 REAL 路径是按本机写死的，交给别人反而失效；让他们从主脚本自动生成即可。

9.3 生效与验收

exec zsh                  # 或直接开一个新终端
github_proxy status       # 期望：开启（走镜像）
github_proxy brew         # 有 Homebrew 时期望：curl 已接管 / git 已接管

逐项自测清单：

自测命令	期望结果
`github_proxy url https://github.com/a/b`	输出带镜像前缀的地址
`git ls-remote https://github.com/octocat/Hello-World.git HEAD`	能拿到 commit hash
`github_proxy test`	打印镜像/直连两组速度
`brew config \| grep '^Curl:'`	ON 时指向 `…/github-proxy/bin/brew-curl`，OFF 时是 `/usr/bin/curl`
`brew fetch --cask maccy`	日志（`github_proxy debug on`）里出现镜像地址
`git push`（任意自己的仓库）	仍走 SSH，与装之前一致

9.4 按需调整

变量	默认	作用
`GITHUB_PROXY_MIRROR`	`https://gh-proxy.com/`	换镜像（末尾斜杠必须保留）
`GITHUB_PROXY_BREW_ON`	`1`	设为 `0` 只关 Homebrew 接管，保留 git/curl 接管
`GITHUB_PROXY_FORCE`	未设置	`on` / `off` 临时覆盖一次会话，不改状态文件
`GITHUB_PROXY_HOSTS`	源码内 7 个域名	要增删改写的域名，改这一处即可

路径与平台差异：

状态目录遵循 XDG：${XDG_STATE_HOME:-$HOME/.local/state}/github-proxy/，想挪位置改 GITHUB_PROXY_STATE 一行。
brew 位置自动探测：Apple Silicon /opt/homebrew、Intel Mac /usr/local、Linuxbrew /home/linuxbrew/.linuxbrew，也可用 HOMEBREW_PREFIX 显式指定。
机器上没有 brew 时，Homebrew 那部分会静默跳过，只保留 zsh 层的 git/curl 接管——Linux 用户同样可用。

9.5 卸载

github_proxy off                        # 先关闭，撤掉导出的 HOMEBREW_* 变量
rm  ~/.zsh/functions/github_proxy.zsh   # 删脚本（换成你实际的存放路径）
rm -rf ~/.local/state/github-proxy      # 删状态与自动生成的包装器（可随时重建）
exec zsh

最后把 ~/.zshrc 里那行 source …/github_proxy.zsh 一并删掉（用整目录遍历的则跳过这步）。

附录 A：完整源码

与本文同步的版本共 591 行，文件名 github_proxy.zsh。直接下载：github_proxy.zsh

#!/usr/bin/env zsh
# ============================================================================
#  github_proxy.zsh —— GitHub 国内加速开关（zsh 交互式环境）
#
#  作用：把在 zsh 里发出的 github 相关请求自动改写到国内加速镜像；
#        关闭后立刻恢复直连。默认「开启」。
#
#  用法（github_proxy help 可随时查看）：
#    github_proxy            # 看状态
#    github_proxy on         # 开启（默认状态）
#    github_proxy off        # 关闭，全部直连
#    github_proxy toggle     # 切换
#    github_proxy test       # 实测镜像 vs 直连速度
#    github_proxy url <URL>  # 只看改写结果，方便排查
#    github_proxy brew       # 看 Homebrew 接管状态
#    github_proxy debug on   # 记录包装器实际请求的地址（排查用）
#
#  覆盖范围（只在交互式 zsh 里生效，且不能用 `command xxx` / 绝对路径调用）：
#    ✅ git clone / fetch / pull / ls-remote / submodule / archive
#    ✅ git push —— 完全不受影响：你自己的 pushInsteadOf 规则会把 https 推送
#       改写成 SSH，镜像只做只读加速，绝不会碰到写操作
#    ✅ curl / wget 参数里出现的 github.com、raw.githubusercontent.com、
#       codeload.github.com、gist.github.com、objects.githubusercontent.com
#    ✅ Homebrew —— 用 HOMEBREW_CURL_PATH / HOMEBREW_GIT_PATH 指向本脚本生成的
#       包装器来接管。USTC 镜像只管 API / bottles / 两个核心仓库；brew 升级时对
#       github.com、codeload.github.com、raw.githubusercontent.com 的直连
#       （cask 的 app 包、formula 的源码包、tap 的 formula 定义）由这里加速
#    ❌ 程序自身发起的其它请求：npm / pip / go、VS Code、浏览器、focr 等
#       这些不经过 zsh 也不经过 brew，函数无法接管（focr 用 --manifest 方案解决）
#    ❌ gh CLI：走 api.github.com 且自带客户端，只能用 HTTPS_PROXY
#    ❌ SSH 形式（git@github.com:…）：保持直连，国内一般可用；
#       若不通，可在 ~/.ssh/config 里改用 ssh.github.com:443
#
#  依赖：git / curl（macOS 自带或 Homebrew 安装均可）
#  自定义镜像：export GITHUB_PROXY_MIRROR="https://你的镜像/"
#  只想关掉 Homebrew 接管（保留 git/curl 接管）：export GITHUB_PROXY_BREW_ON=0
# ============================================================================

# ---------------------------------------------------------------------------
# 配置区（可用环境变量覆盖）
# ---------------------------------------------------------------------------
: ${GITHUB_PROXY_MIRROR:=https://gh-proxy.com/}   # 末尾斜杠必须有
typeset -g GITHUB_PROXY_MIRROR

# 命中这些域名就改写
typeset -ga GITHUB_PROXY_HOSTS=(
  github.com
  www.github.com
  raw.githubusercontent.com
  codeload.github.com
  gist.github.com
  objects.githubusercontent.com
  api.github.com
)

# 开关状态持久化位置（默认开启，只有显式 off 才写文件）
typeset -g GITHUB_PROXY_STATE="${XDG_STATE_HOME:-$HOME/.local/state}/github-proxy/state"

# ---- Homebrew 接管（curl / git 包装器由本脚本生成，固定在状态目录里）----
typeset -g GITHUB_PROXY_STATE_DIR="${GITHUB_PROXY_STATE:h}"
typeset -g GITHUB_PROXY_BIN="${GITHUB_PROXY_STATE_DIR}/bin"
typeset -g GITHUB_PROXY_BREW_CURL="${GITHUB_PROXY_BIN}/brew-curl"
typeset -g GITHUB_PROXY_BREW_GIT="${GITHUB_PROXY_BIN}/brew-git"
typeset -g GITHUB_PROXY_DEBUG_MARKER="${GITHUB_PROXY_STATE_DIR}/debug"
typeset -g GITHUB_PROXY_BREW_LOG="${GITHUB_PROXY_STATE_DIR}/brew.log"
# brew 位置：优先用环境变量，缺失时按常见安装路径自动探测
# （Apple Silicon: /opt/homebrew；Intel Mac: /usr/local；Linuxbrew: ~/.linuxbrew）
typeset -g GITHUB_PROXY_PREFIX="${HOMEBREW_PREFIX:-}"
if [[ -z "$GITHUB_PROXY_PREFIX" ]]; then
  typeset _gp_p
  for _gp_p in /opt/homebrew /usr/local /home/linuxbrew/.linuxbrew "$HOME/.linuxbrew"; do
    if [[ -x "$_gp_p/bin/brew" ]]; then GITHUB_PROXY_PREFIX="$_gp_p"; break; fi
  done
  : ${GITHUB_PROXY_PREFIX:=/opt/homebrew}
  unset _gp_p
fi
typeset -g GITHUB_PROXY_BREW_ON="${GITHUB_PROXY_BREW_ON:-1}"   # 0 = 不接管 Homebrew

# 被我们改写之前的值，off 时原样还回去
typeset -g  GITHUB_PROXY_PREV_CURL_PATH GITHUB_PROXY_PREV_GIT_PATH
typeset -gi GITHUB_PROXY_PREV_CURL_SET=0 GITHUB_PROXY_PREV_GIT_SET=0

# ---------------------------------------------------------------------------
# 内部：状态读写
# ---------------------------------------------------------------------------
_gp_state_read() {
  local v=""
  [[ -r "$GITHUB_PROXY_STATE" ]] && v="$(<"$GITHUB_PROXY_STATE" 2>/dev/null)"
  case "$v" in
    off|0|false|no) print -r -- off ;;
    on|1|true|yes)  print -r -- on  ;;
    *)              print -r -- on  ;;   # 默认开启
  esac
}

_gp_enabled() {
  # 状态文件是唯一权威。GITHUB_PROXY 只作为本 shell 内的镜像变量、且不导出，
  # 否则它会被子进程/其它程序继承，出现「文件写着 off 但新终端仍是 on」的假象。
  # 需要临时覆盖时用 GITHUB_PROXY_FORCE=on|off（显式、不会被误继承）。
  case "${GITHUB_PROXY_FORCE-}" in
    on|1|true|yes)  return 0 ;;
    off|0|false|no) return 1 ;;
  esac
  [[ "$(_gp_state_read)" == on ]]
}

_gp_set() {
  local want="$1" dir="${GITHUB_PROXY_STATE:h}"
  [[ -d "$dir" ]] || mkdir -p "$dir" 2>/dev/null
  [[ -w "$dir" ]] && print -r -- "$want" >| "$GITHUB_PROXY_STATE" 2>/dev/null
  export -n GITHUB_PROXY 2>/dev/null      # 不导出：避免泄漏给子进程
  if [[ "$want" == on ]]; then
    GITHUB_PROXY=1
    _gp_brew_enable
  else
    GITHUB_PROXY=0
    _gp_brew_disable
  fi
}

# ---------------------------------------------------------------------------
# Homebrew 接管
#   brew 调 curl/git 时会把非 HOMEBREW_ 前缀的环境变量过滤掉（实测
#   GITHUB_PROXY_MIRROR 传不进包装器），所以镜像地址必须写死在包装器脚本里，
#   每次开启时重新生成一次。
# ---------------------------------------------------------------------------
_gp_brew_available() {
  [[ "$GITHUB_PROXY_BREW_ON" == 0 ]] && return 1
  [[ -x "${GITHUB_PROXY_PREFIX}/bin/brew" ]] || return 1
  return 0
}

_gp_write_brew_wrappers() {
  local dir="$GITHUB_PROXY_BIN" tpl
  [[ -d "$dir" ]] || mkdir -p "$dir" 2>/dev/null
  [[ -d "$dir" ]] || return 1

  # 还原成 brew 原本会用的真实程序
  local real_curl="${GITHUB_PROXY_PREFIX}/opt/curl/bin/curl"
  if [[ -z "${HOMEBREW_FORCE_BREWED_CURL-}" || ! -x "$real_curl" ]]; then
    real_curl="/usr/bin/curl"
  fi
  local real_git="${GITHUB_PROXY_PREFIX}/bin/git"
  [[ -x "$real_git" ]] || real_git="/usr/bin/git"

  # ---- curl 包装器：把 github 域名改写到镜像，其余原样放行 ----
  tpl=$(cat <<'CURL_TPL'
#!/bin/bash
# 由 github_proxy.zsh 自动生成，请勿手改
MIRROR="__MIRROR__"
REAL="__REAL__"
MARKER="__MARKER__"
LOG="__LOG__"
args=()
for a in "$@"; do
  case "$a" in
    https://github.com/*|https://raw.githubusercontent.com/*|https://codeload.github.com/*|https://gist.github.com/*|https://objects.githubusercontent.com/*)
      args+=("${MIRROR}${a}") ;;
    *) args+=("$a") ;;
  esac
done
if [ -e "$MARKER" ]; then
  if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
  { printf '== %s\n' "$(date +%T)"; for a in "${args[@]}"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
fi
exec "$REAL" "${args[@]}"
CURL_TPL
)
  tpl="${tpl//__MIRROR__/$GITHUB_PROXY_MIRROR}"
  tpl="${tpl//__REAL__/$real_curl}"
  tpl="${tpl//__MARKER__/$GITHUB_PROXY_DEBUG_MARKER}"
  tpl="${tpl//__LOG__/$GITHUB_PROXY_BREW_LOG}"
  print -r -- "$tpl" >| "$GITHUB_PROXY_BREW_CURL" 2>/dev/null

  # ---- git 包装器：只读操作走镜像，push 原样放行 ----
  #  关键点：brew update 更新第三方 tap 时执行的是
  #      git -C <tap> fetch --force origin
  #  命令行里没有 URL，地址来自仓库 .git/config 里的 remote.origin.url。
  #  因此除了改写命令行参数，还必须注入 git 原生的 insteadOf 重写规则，
  #  否则这类请求会绕过镜像直接裸连 github.com。
  tpl=$(cat <<'GIT_TPL'
#!/bin/bash
# 由 github_proxy.zsh 自动生成，请勿手改
MIRROR="__MIRROR__"
REAL="__REAL__"
MARKER="__MARKER__"
LOG="__LOG__"
sub=""
for a in "$@"; do
  case "$a" in -*) continue ;; *) sub="$a"; break ;; esac
done
if [ "$sub" = "push" ]; then
  if [ -e "$MARKER" ]; then
    if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
    { printf '== %s (push, 原样放行)\n' "$(date +%T)"; for a in "$@"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
  fi
  exec "$REAL" "$@"
fi
# git 原生重写规则：覆盖 remote.origin.url 这类"写在配置里"的地址
cfg=()
for h in github.com raw.githubusercontent.com codeload.github.com gist.github.com; do
  cfg+=(-c "url.${MIRROR}https://${h}/.insteadOf=https://${h}/")
done
args=()
for a in "$@"; do
  case "$a" in
    https://github.com/*|https://raw.githubusercontent.com/*|https://codeload.github.com/*|git@github.com:*)
      args+=("${MIRROR}${a}") ;;
    *) args+=("$a") ;;
  esac
done
if [ -e "$MARKER" ]; then
  if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
  { printf '== %s\n' "$(date +%T)"; for a in "${args[@]}"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
fi
exec "$REAL" "${cfg[@]}" "${args[@]}"
GIT_TPL
)
  tpl="${tpl//__MIRROR__/$GITHUB_PROXY_MIRROR}"
  tpl="${tpl//__REAL__/$real_git}"
  tpl="${tpl//__MARKER__/$GITHUB_PROXY_DEBUG_MARKER}"
  tpl="${tpl//__LOG__/$GITHUB_PROXY_BREW_LOG}"
  print -r -- "$tpl" >| "$GITHUB_PROXY_BREW_GIT" 2>/dev/null

  chmod 755 "$GITHUB_PROXY_BREW_CURL" "$GITHUB_PROXY_BREW_GIT" 2>/dev/null
  [[ -x "$GITHUB_PROXY_BREW_CURL" && -x "$GITHUB_PROXY_BREW_GIT" ]]
}

_gp_brew_enable() {
  _gp_brew_available || return 0
  _gp_write_brew_wrappers || return 1

  if (( ! GITHUB_PROXY_PREV_CURL_SET )) &&
     [[ -n "${HOMEBREW_CURL_PATH-}" && "${HOMEBREW_CURL_PATH}" != "$GITHUB_PROXY_BREW_CURL" ]]; then
    GITHUB_PROXY_PREV_CURL_PATH="${HOMEBREW_CURL_PATH}"
    GITHUB_PROXY_PREV_CURL_SET=1
  fi
  export HOMEBREW_CURL_PATH="$GITHUB_PROXY_BREW_CURL"

  if (( ! GITHUB_PROXY_PREV_GIT_SET )) &&
     [[ -n "${HOMEBREW_GIT_PATH-}" && "${HOMEBREW_GIT_PATH}" != "$GITHUB_PROXY_BREW_GIT" ]]; then
    GITHUB_PROXY_PREV_GIT_PATH="${HOMEBREW_GIT_PATH}"
    GITHUB_PROXY_PREV_GIT_SET=1
  fi
  export HOMEBREW_GIT_PATH="$GITHUB_PROXY_BREW_GIT"
}

_gp_brew_disable() {
  if [[ "${HOMEBREW_CURL_PATH-}" == "$GITHUB_PROXY_BREW_CURL" ]]; then
    if (( GITHUB_PROXY_PREV_CURL_SET )) &&
       [[ "${GITHUB_PROXY_PREV_CURL_PATH-}" != "$GITHUB_PROXY_BREW_CURL" ]]; then
      export HOMEBREW_CURL_PATH="${GITHUB_PROXY_PREV_CURL_PATH}"
    else
      unset HOMEBREW_CURL_PATH
    fi
  fi
  if [[ "${HOMEBREW_GIT_PATH-}" == "$GITHUB_PROXY_BREW_GIT" ]]; then
    if (( GITHUB_PROXY_PREV_GIT_SET )) &&
       [[ "${GITHUB_PROXY_PREV_GIT_PATH-}" != "$GITHUB_PROXY_BREW_GIT" ]]; then
      export HOMEBREW_GIT_PATH="${GITHUB_PROXY_PREV_GIT_PATH}"
    else
      unset HOMEBREW_GIT_PATH
    fi
  fi
}

_gp_brew_active() {
  [[ "${HOMEBREW_CURL_PATH-}" == "$GITHUB_PROXY_BREW_CURL" ||
     "${HOMEBREW_GIT_PATH-}" == "$GITHUB_PROXY_BREW_GIT" ]]
}

# ---------------------------------------------------------------------------
# 内部：URL 改写
# ---------------------------------------------------------------------------
_gp_is_github_url() {
  local u="$1" rest host
  [[ "$u" == http://* || "$u" == https://* ]] || return 1
  rest="${u#*://}"
  host="${rest%%/*}"
  host="${host%%:*}"
  host="${host##*@}"
  (( ${GITHUB_PROXY_HOSTS[(I)$host]} ))
}

# 加镜像前缀
_gp_mirror() {
  local u="$1"
  if _gp_is_github_url "$u"; then
    print -r -- "${GITHUB_PROXY_MIRROR}${u}"
  else
    print -r -- "$u"
  fi
}

# 去掉已存在的镜像前缀（复制粘贴带前缀的地址也能正确还原）
_gp_unmirror() {
  local u="$1"
  if [[ "$u" == ${GITHUB_PROXY_MIRROR}* ]]; then
    print -r -- "${u#${GITHUB_PROXY_MIRROR}}"
  else
    print -r -- "$u"
  fi
}

# 归一化 + 按当前开关改写：这是所有包装器共用的出口
_gp_url() {
  local u="$1"
  u="$(_gp_unmirror "$u")"
  if _gp_enabled; then
    _gp_mirror "$u"
  else
    print -r -- "$u"
  fi
}

# ---------------------------------------------------------------------------
# 包装器 1：curl
# ---------------------------------------------------------------------------
curl() {
  local -a args=()
  local a
  for a in "$@"; do
    case "$a" in
      http://*|https://*) args+=("$(_gp_url "$a")") ;;
      *)                  args+=("$a") ;;
    esac
  done
  command curl "${args[@]}"
}

# ---------------------------------------------------------------------------
# 包装器 2：wget
# ---------------------------------------------------------------------------
wget() {
  local -a args=()
  local a
  for a in "$@"; do
    case "$a" in
      http://*|https://*) args+=("$(_gp_url "$a")") ;;
      *)                  args+=("$a") ;;
    esac
  done
  command wget "${args[@]}"
}

# ---------------------------------------------------------------------------
# 内部：把一个仓库（含子模块）里指向镜像的 remote 地址还原成原始地址
#   git clone 会把"实际使用的地址"写进 .git/config，若不还原，之后 push
#   这条 remote 会指向镜像（镜像不支持写操作）。
# ---------------------------------------------------------------------------
_gp_fix_remotes_one() {
  local dir="$1" name url clean
  [[ -d "$dir" ]] || return 0
  for name in ${(f)"$(command git -C "$dir" remote 2>/dev/null)"}; do
    url="$(command git -C "$dir" remote get-url "$name" 2>/dev/null)" || continue
    clean="$(_gp_unmirror "$url")"
    [[ "$clean" == "$url" ]] || command git -C "$dir" remote set-url "$name" "$clean" 2>/dev/null
  done
}

_gp_fix_remotes() {
  local dir="$1" mod
  [[ -d "$dir/.git" ]] || return 0
  _gp_fix_remotes_one "$dir"
  for mod in "$dir"/.git/modules/*(N/); do
    _gp_fix_remotes_one "$mod"
  done
}

# 从 clone 的参数里找出目标目录
_gp_clone_target_dir() {
  local -a args=("$@")
  local i url="" dir=""
  for (( i = 2; i <= $#args; i++ )); do
    local a="${args[i]}"
    if [[ -z "$url" ]]; then
      [[ "$a" == *://* || "$a" == *@*:* ]] && url="$a"
      continue
    fi
    [[ "$a" == -* ]] && continue
    dir="$a"; break
  done
  [[ -n "$url" ]] || return 1
  [[ -n "$dir" ]] || dir="${${url%%\?*}#*/}"      # 去掉 query，取路径最后一段
  dir="${dir%.git}"
  [[ -n "$dir" ]] || return 1
  print -r -- "$dir"
}

# ---------------------------------------------------------------------------
# 包装器 3：git
#   通过注入 git 自身的 URL 重写规则实现：
#     · 读操作（clone/fetch/pull/...）自动走镜像
#     · 写操作（push）不注入任何规则，保持你原有的 SSH 推送习惯
#     · clone 结束后把 remote 还原成原始 github 地址，仓库保持"干净"
# ---------------------------------------------------------------------------
git() {
  if ! _gp_enabled; then
    command git "$@"
    return
  fi

  # 找出子命令（跳过选项）
  local sub="" a
  for a in "$@"; do
    [[ "$a" == -* ]] && continue
    sub="$a"; break
  done

  local m="$GITHUB_PROXY_MIRROR" h
  local -a cfg=()
  for h in github.com raw.githubusercontent.com codeload.github.com \
           gist.github.com objects.githubusercontent.com; do
    cfg+=(-c "url.${m}https://${h}/.insteadOf=https://${h}/")
  done

  command git "${cfg[@]}" "$@"
  local rc=$?

  # clone / submodule 之后收拾 remote 地址
  if (( rc == 0 )); then
    case "$sub" in
      clone)
        local target
        target="$(_gp_clone_target_dir "$@")" && _gp_fix_remotes "$target"
        ;;
      submodule)
        _gp_fix_remotes "$PWD"
        ;;
    esac
  fi
  return $rc
}

# ---------------------------------------------------------------------------
# 对外命令
# ---------------------------------------------------------------------------

# 帮助文本（github_proxy help / -h / --help / usage / 参数写错时显示）
_gp_help() {
  local state="关闭（直连）"
  _gp_enabled && state="开启（走镜像）"

  print -r -- "github_proxy —— GitHub 国内加速开关（当前：${state}）"
  print -r -- ""
  print -r -- "  github_proxy            # 看状态"
  print -r -- "  github_proxy on         # 开启（默认状态）"
  print -r -- "  github_proxy off        # 关闭，全部直连"
  print -r -- "  github_proxy toggle     # 切换"
  print -r -- "  github_proxy test       # 实测镜像 vs 直连速度"
  print -r -- "  github_proxy url <URL>  # 只看改写结果，方便排查"
  print -r -- "  github_proxy brew       # 看 Homebrew 接管状态"
  print -r -- "  github_proxy debug on   # 记录包装器实际请求的地址（排查用）"
  print -r -- ""
  print -r -- "接管范围："
  print -r -- "  git clone / fetch / pull / ls-remote / submodule / archive  → 走镜像"
  print -r -- "  git push                                                   → 不受影响，仍走你的 SSH"
  print -r -- "  curl / wget 中的 github 域名                               → 走镜像"
  print -r -- "  Homebrew 升级时的 github 直连（cask 的 app 包、formula 源码、"
  print -r -- "  tap 的 formula 定义 —— USTC 镜像管不到的部分）              → 走镜像"
  print -r -- ""
  print -r -- "接管不到："
  print -r -- "  npm / pip / go、VS Code、浏览器、focr 等程序自身发起的请求"
  print -r -- "  gh CLI（走 api.github.com，只能用 HTTPS_PROXY）"
  print -r -- "  SSH 形式地址 git@github.com:…"
  print -r -- ""
  local brew_state="未接管"
  _gp_brew_active && brew_state="已接管（brew 的 curl/git → 包装器）"
  print -r -- "Homebrew：${brew_state}"
  print -r -- "镜像：    ${GITHUB_PROXY_MIRROR}   （用 GITHUB_PROXY_MIRROR 环境变量可替换）"
  print -r -- "状态文件：${GITHUB_PROXY_STATE}"
  print -r -- "临时覆盖：GITHUB_PROXY_FORCE=off zsh   （只影响这一次会话，不动状态文件）"
}

github_proxy() {
  local cmd="${1:-status}"
  case "$cmd" in
    on|enable|1)
      _gp_set on
      print -r -- "GitHub 代理：已开启  →  ${GITHUB_PROXY_MIRROR}"
      ;;

    off|disable|0)
      _gp_set off
      print -r -- "GitHub 代理：已关闭  →  直连 github.com（国内通常很慢或超时）"
      ;;

    toggle|switch)
      if _gp_enabled; then github_proxy off; else github_proxy on; fi
      ;;

    status|"")
      local state="关闭（直连）"
      _gp_enabled && state="开启（走镜像）"
      local brew_state="未接管"
      _gp_brew_active && brew_state="已接管"
      print -r -- "GitHub 代理：${state}"
      print -r -- "镜像地址： ${GITHUB_PROXY_MIRROR}"
      print -r -- "Homebrew： ${brew_state}（github_proxy brew 看详情）"
      print -r -- "接管的域名：${(j:, :)GITHUB_PROXY_HOSTS}"
      print -r -- "状态文件： ${GITHUB_PROXY_STATE}"
      ;;

    brew|homebrew)
      local c="未接管" g="未接管" gen="缺失"
      [[ "${HOMEBREW_CURL_PATH-}" == "$GITHUB_PROXY_BREW_CURL" ]] && c="已接管"
      [[ "${HOMEBREW_GIT_PATH-}" == "$GITHUB_PROXY_BREW_GIT" ]] && g="已接管"
      [[ -x "$GITHUB_PROXY_BREW_CURL" && -x "$GITHUB_PROXY_BREW_GIT" ]] && gen="已生成"

      print -r -- "Homebrew 接管：curl ${c} / git ${g}"
      print -r -- "  包装器：        ${gen}（${GITHUB_PROXY_BIN}）"
      print -r -- "  HOMEBREW_CURL_PATH=${HOMEBREW_CURL_PATH:-（未设置）}"
      print -r -- "  HOMEBREW_GIT_PATH =${HOMEBREW_GIT_PATH:-（未设置）}"
      if (( $+commands[brew] )); then
        print -r -- "  brew 实测："
        command brew config 2>/dev/null | command grep -E "^(Curl|Git):" | command sed 's/^/    /'
      fi
      print -r -- "  说明：USTC 镜像管 API / bottles / 两个核心仓库；"
      print -r -- "        cask 的 app 包、formula 源码包、tap 定义仍会直连 github.com，"
      print -r -- "        开启后由本包装器改写（下载完仍由 brew 校验 sha256）。"
      ;;

    debug)
      case "${2:-}" in
        on|1)
          [[ -d "$GITHUB_PROXY_STATE_DIR" ]] || mkdir -p "$GITHUB_PROXY_STATE_DIR" 2>/dev/null
          : >| "$GITHUB_PROXY_DEBUG_MARKER" 2>/dev/null
          print -r -- "调试日志：已开启  →  ${GITHUB_PROXY_BREW_LOG}"
          print -r -- "  （只记录 brew 经包装器发出的请求；用 github_proxy debug off 关闭）"
          ;;
        off|0)
          command rm -f "$GITHUB_PROXY_DEBUG_MARKER" 2>/dev/null
          print -r -- "调试日志：已关闭（日志文件保留在 ${GITHUB_PROXY_BREW_LOG}）"
          ;;
        *)
          if [[ -e "$GITHUB_PROXY_DEBUG_MARKER" ]]; then
            print -r -- "调试日志：开启（${GITHUB_PROXY_BREW_LOG}）"
          else
            print -r -- "调试日志：关闭"
          fi
          ;;
      esac
      ;;

    url)
      if [[ -z "$2" ]]; then
        print -ru2 -- "用法：github_proxy url <URL>"
        return 2
      fi
      print -r -- "$(_gp_url "$2")"
      ;;

    test|check|bench)
      local probe_gh="https://github.com/Dicklesworthstone/franken_ocr/releases/download/models-v1/tokenizer.json"
      print -r -- "探测文件：tokenizer.json (9.5 MB)"
      print -r -- "-- 镜像 --"
      command curl -sL --max-time 25 -o /dev/null \
        -w "   ${GITHUB_PROXY_MIRROR}\n   速度 %{speed_download} B/s  HTTP %{http_code}\n" \
        "${GITHUB_PROXY_MIRROR}${probe_gh}"
      print -r -- "-- 直连 --"
      command curl -sL --max-time 15 -o /dev/null \
        -w "   https://github.com\n   速度 %{speed_download} B/s  HTTP %{http_code}\n" \
        "$probe_gh"
      ;;

    help|-h|--help|usage|-help)
      _gp_help
      ;;

    *)
      print -ru2 -- "github_proxy: 未知参数 '$cmd'"
      print -ru2 -- ""
      _gp_help
      return 2
      ;;
  esac
}

# 让本 shell 内的脚本能判断开关状态：GITHUB_PROXY 故意「不导出」，
# 免得它被子进程继承（曾导致状态文件为 off 时新终端仍判为开启）。
export -n GITHUB_PROXY 2>/dev/null
unset GITHUB_PROXY

# 同步状态 + Homebrew 接管（静默执行，加载时不打印任何东西）
if _gp_enabled; then
  GITHUB_PROXY=1
  _gp_brew_enable 2>/dev/null
else
  GITHUB_PROXY=0
  _gp_brew_disable 2>/dev/null
fi

附录 B：自动生成的文件长什么样

主脚本会在 ~/.local/state/github-proxy/ 下生成运行时文件。它们不需要你提供，但值得先看清楚——这毕竟是一个会往你磁盘写可执行文件的操作。下面以本机为例（家目录用 ~ 简写）。

B.1 `bin/brew-curl`（19 行）

#!/bin/bash
# 由 github_proxy.zsh 自动生成，请勿手改
MIRROR="https://gh-proxy.com/"
REAL="/usr/bin/curl"
MARKER="~/.local/state/github-proxy/debug"
LOG="~/.local/state/github-proxy/brew.log"
args=()
for a in "$@"; do
  case "$a" in
    https://github.com/*|https://raw.githubusercontent.com/*|https://codeload.github.com/*|https://gist.github.com/*|https://objects.githubusercontent.com/*)
      args+=("${MIRROR}${a}") ;;
    *) args+=("$a") ;;
  esac
done
if [ -e "$MARKER" ]; then
  if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
  { printf '== %s\n' "$(date +%T)"; for a in "${args[@]}"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
fi
exec "$REAL" "${args[@]}"

要点：

MIRROR 与 REAL 在生成时就写死——brew 会把非 HOMEBREW_ 前缀的环境变量过滤掉（见 4.4 ①），靠环境变量传参行不通。
只改写白名单里的 5 个 GitHub 域名，其它 URL（S3、CDN 等）原样放行。
exec "$REAL" 用绝对路径，避免包装器递归调用自己。
日志只在 debug 标记存在时写入，且超过 1 MB 自动轮转成 brew.log.1，忘记关也不会撑爆磁盘。

B.2 `bin/brew-git`（35 行）

#!/bin/bash
# 由 github_proxy.zsh 自动生成，请勿手改
MIRROR="https://gh-proxy.com/"
REAL="/opt/homebrew/bin/git"
MARKER="~/.local/state/github-proxy/debug"
LOG="~/.local/state/github-proxy/brew.log"
sub=""
for a in "$@"; do
  case "$a" in -*) continue ;; *) sub="$a"; break ;; esac
done
if [ "$sub" = "push" ]; then
  if [ -e "$MARKER" ]; then
    if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
    { printf '== %s (push, 原样放行)\n' "$(date +%T)"; for a in "$@"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
  fi
  exec "$REAL" "$@"
fi
# git 原生重写规则：覆盖 remote.origin.url 这类"写在配置里"的地址
cfg=()
for h in github.com raw.githubusercontent.com codeload.github.com gist.github.com; do
  cfg+=(-c "url.${MIRROR}https://${h}/.insteadOf=https://${h}/")
done
args=()
for a in "$@"; do
  case "$a" in
    https://github.com/*|https://raw.githubusercontent.com/*|https://codeload.github.com/*|git@github.com:*)
      args+=("${MIRROR}${a}") ;;
    *) args+=("$a") ;;
  esac
done
if [ -e "$MARKER" ]; then
  if [ -f "$LOG" ] && [ "$(wc -c < "$LOG" 2>/dev/null || echo 0)" -gt 1048576 ]; then mv -f "$LOG" "$LOG.1" 2>/dev/null; fi
  { printf '== %s\n' "$(date +%T)"; for a in "${args[@]}"; do printf '   %s\n' "$a"; done; } >> "$LOG" 2>/dev/null
fi
exec "$REAL" "${cfg[@]}" "${args[@]}"

与 curl 版的两点差异：push 直接 exec 原样放行，写操作绝不经过镜像；地址白名单里除 https 之外还认 git@github.com: 这种 SSH 形式。

B.3 另外三个文件

state：3 字节文本，内容 on 或 off。
debug：0 字节标记文件，存在即记录、删除即停止。
brew.log / brew.log.1：纯文本追加日志，形如：

== 10:23:15
   --disable
   --fail
   --location
   https://gh-proxy.com/https://github.com/p0deje/Maccy/releases/download/2.7.1/Maccy.app.zip

github_proxy debug off 只删除标记文件，日志保留供事后查看；想彻底清空直接删掉 brew.log 即可。

Git

2026-09-29T00:00:00+00:00

定期更新该博客

日常开发中遇到的 git场景，在搜索应用后，总结到这里来，便于后续积累迁移

clone - 初次拉取

单分支无历史提交式

场景描述：只获取最新，分支标签关联仓库历史提交全部舍弃

git clone --depth 1 --single-branch --branch main --no-tags \
  https://mirrors.tuna.tsinghua.edu.cn/git/llvm-project.git \
  ~/00CXX_GitRes/llvm-project

–depth 1 只取最新一条提交
–single-branch 不抓其它分支（LLVM 有几千个分支，不限制会多几百 MB）
–no-tags 不抓 tag（LLVM 的 tag 极多，这是体积大头之一）

好习惯

克隆完立刻把“只更新 main、永不抓 tag、自动清理“固化进本地配置：

cd ~/00CXX_GitRes/llvm-project
## 良好习惯，后续每次拉取都要针对该本地仓库的基础配置进行优先设置
## bat .git/config ##进行查看该本地仓库的配置
git config --local remote.origin.fetch '+refs/heads/main:refs/remotes/origin/main'
git config --local remote.origin.tagOpt --no-tags
git config --local fetch.prune true
git config --local fetch.pruneTags true
git config --local gc.pruneExpire now

常用别名

# 一条命令完成"取最新快照 + 丢弃本地提交/改动"
git config --local alias.update \
  '!git fetch --depth 1 --no-tags --prune origin main && git reset --hard origin/main && git log --oneline -1'

# 定期瘦身
git config --local alias.slim \
  '!git reflog expire --expire=now --all && git gc --prune=now --quiet && git count-objects -vH'

注意：Git 没有持久化的“默认浅深度“配置项（fetch.depth 不是有效键，我查了本机 git 2.55 的配置文档确认过）。
所以 –depth 1 必须每次 fetch 时显式带上——这正是 git update 别名帮你固化的事，
别直接敲裸 git pull。

后续更新：永远只有一份快照

cd ~/00CXX_GitRes/llvm-project

git update # = fetch --depth 1 + reset --hard，等价于下面两行

验证“确实没在攒历史“

# 任何时候三条命令自检：
git rev-parse --is-shallow-repository   # 必须是 true
git rev-list --count HEAD               # 必须恒等于 1
git tag | wc -l                         # 必须恒等于 0
git count-objects -vH                   # size-pack 明显膨胀时跑一次 git slim

如果 is-shallow-repository 变成 false，说明中间某次更新用了不带 –depth 的命令（或镜像不支持 shallow 而返回了全量），最省事的处理是删掉重克隆一次。
额外网络优化（可选）：git config –global http.version HTTP/1.1 和 git config –global http.postBuffer 524288000 能缓解大包传输偶发卡死；如果你本机有代理（看到你装过 Geph），可以只给 GitHub 走代理、国内镜像直连

代码提交跟踪管理 - .gitignore

忽略整个文件夹‌：logs/ 或 logs/**，匹配该目录及子目录下的所有文件。
仅忽略文件夹内文件，保留文件夹本身‌：logs/*，不会忽略空目录，但会忽略其直接子文件和子目录。
取消对已跟踪文件的忽略‌：.gitignore 只对未跟踪文件生效；若文件已提交，需先执行 git rm –cached <路径>，再提交删除记录

build/*  #cmake搭建的C++项目，编译文件不提交，但该空目录是编译构建路径，建议提交，可采用该写法
logs/** # 日志在项目运行实时产生，无需提交到仓库中进行跟踪管理

add - 添加到仓库

add .

commit - 提交

git commit -m "Update File md"

push - 推送

git push origin mian

status - 状态

git status

额外常见命令

cloc - 统计代码量

cloc . # 在当前目录下按文件类型进行代码量统计

2026-09-26T08:30:00+00:00

2026年09月26日 16:30（东八区 / 北京时间）

网站引擎升级：Zola 0.23.6 + Ametrine tera2 迁移完成 · 看板/归档/热力图修复

概述

本轮把整站从「Zola 0.22 时代」推到 Zola 0.23.6 + Ametrine tera2，并顺手修掉三处长期不舒服的地方：

引擎与主题升级：主题子仓库由 main 切到同仓库的 tera2 分支，适配 Tera 2；
模板全量迁移：旧语法（宏导入、宏调用、shortcode、concat 过滤器）逐条改写为新语法，zola build 重新跑通；
功能修复：看板界面恢复渲染与编辑、归档剔除无标题的空链接、热力图支持月初标记与悬浮日期。

一、为什么要换到 tera2

Zola 0.23.6 内置的模板引擎已经是 Tera 2，它删掉了一批我们一直在用的老写法：

旧写法（Tera 1 / 老主题 main）	现状	新写法（Zola 0.23.6）
`{% import "macros/macros.html" as macros %}`	标签已移除，直接报 `Unknown tag`	`{% component 名字(参数) %}` 定义，`{{ <名字参数/> }}` 调用
`{{ macros::icon(name="x") }}`	不再是合法表达式	`{{ <icon name="x"/> }}`
`{{ 列表	concat(with=另一个列表) }}`	过滤器已移除
`templates/shortcodes/*.html` + `{{ 短代码() }}`	shortcode 机制被组件取代	放到 `templates/components/*.html`
`trim_start_matches` / `slice` / `filter(attribute=…)` / `linebreaksbr`	过滤器已移除	`trim_start`、数组切片 `arr[1:-1]`、`for` 循环筛选

结论：只升级 Zola 不动主题，整站会在第一个模板处就编译失败；旧主题 main 与新引擎不兼容，所以必须用为重写而生的 tera2。

二、子仓库与构建环境

themes/ametrine：main → tera2（f125214），嵌套的 icons 子模块同步到 859c0e7；
.gitmodules: 增加 branch = tera2，子仓库自身的 branch.<name> 也指向 tera2，以后 git submodule update --remote 会跟着 tera2 走；
本地 zola --version = 0.23.6，主题要求 min_version = 0.22.1。

# 切换并拉取子仓库新分支
git -C themes/ametrine fetch origin --prune
git -C themes/ametrine checkout -B tera2 origin/tera2
git -C themes/ametrine submodule update --init --recursive

# 构建
zola build          # 或 ./build-site.sh（含加密同步 + 后置校验）

三、站点侧迁移清单

宏 → 组件：article_list、kanban、kanban_list、nanolog_list、music_player、badges、beeper、now_playing、online、design、design_app 等模板里的宏调用全部换成 {{ <icon …/> }}；
导入 → 直接包含：basb.html 原本通过宏渲染 basb_list.html，改为设置变量后 {% include %}；
未使用的宏文件 → 组件：templates/macros/encryption.html（早已没人调用）拆成 templates/components/ 下 3 个组件：is_encrypted_page、payload_data_path、page_encrypt_enabled；
区块 shortcode → 组件：10 个板块首页的 ASCII 电子屏横幅由 {% crt(label=…) %} 改为 {% <crt label="…"> %}；
过滤器替换：archive.html、heatmap_component.html、kanban_heatmap_component.html、article_list.html 的 concat 改成展开语法；age.html 的 as_str/slice 改成字符串拼接 + 数组切片；games.html 的 filter(attribute=…) 改成循环筛选；
Tera 2 更严格的两点：
- 子模板顶层只能出现 extends / block / component，index.html、basb.html、404.html 里游离的 HTML 与注释被收进区块；
- 访问可能不存在的字段要写成可选链，例如 page.extra.encryption?.encrypt、paginator?.pages；
文档型文章：模板速查、v1.0 发布说明、4 篇 nanolog、CMake 文章里用来演示的模板代码，统一改成 Tera 的 raw 区块包裹（避免示例被当成真模板执行），页面展示内容保持不变。

四、主题侧修复（tera2 仍属预发布状态）

tera2 分支自带两处小毛病，已在本地补齐（后续若更新子仓库需重新打补丁，建议同时上报上游）：

templates/partials/head.html：[...styles, page.extra.styles] 这类写法在 Tera 2 里是「把数组塞进数组」，会导致每页/每板块的 styles、scripts 渲染成 /[ kanban style.css"] 之类的乱码路径 —— 这正是看板页 CSS/JS 全都没加载、界面只有裸骨架的根因。已改为展开 + 字符串兼容写法；
templates/partials/header.html：404 页没有 section 变量，section.generate_feeds 会直接抛错，已改为 section?.generate_feeds。

五、本轮功能修复

5.1 看板（/kanban/）

界面恢复渲染：资源路径修好后，kanban/style.css 与 4 个看板脚本正常加载，卡片布局与进度条恢复正常；
默认月份不再是空窗：以前默认选中「当前月」，当月还没写看板时列表一片空白；现在当月没有看板会自动回退到最近一个有看板的月份，并支持年 / 月下拉切换；
空态提示：选中的月份确实没有看板时，列表区给出「该月暂无看板，可切换月份或点击＋新建看板」的提示，而不是留白；
新建看板可触发：＋新建看板 按钮正常出现并打开 GUI 编辑器（看板信息、列、卡片、重要等级、背景色、Markdown 预览、生成并复制、Token 同步）；
编辑看板可用：左上角站点图标连点 6 次进入管理员模式后，卡片右上角 ✎ 编辑 出现，点击即带入该看板的原始 Markdown 进入「修改」模式。

5.2 归档（/archive/）

弄清「无目标文章链接」的成因：归档列表之前把 nanolog 的文章也一起聚合了，而 nanolog 正文没有 title 字段（标题由时间生成），于是渲染出一堆只有日期、点进去也不知道是什么的空链接；
修复：归档范围收缩回既定板块（英语、数学、分享、写博客、工程、Debug），不再收录 nanolog；同时给标题加上兜底（无 title 时退回 slug 或「（无标题）」），保证每条明细都有章节名。

5.3 热力图（归档页 / 文章页 / 看板页）

月初标记：每月 1 号的格子上加了一个金色圆点 + 描边（看板年视图里是「包含 1 号的那一周」），一眼能看出月份分界；
悬浮看日期：所有格子（包括没有文章的空白格）悬浮都会显示 年-月-日，有文章时附加篇数与标题，月初再加「月初」提示；
空白格改用 aria-disabled 而不是 disabled，这样禁用状态的格子也能响应悬浮提示。

六、验证

zola build                     # 通过：272 个 HTML 页面
node scripts/verify-kanban-build.mjs   # 通过：5 个看板周页与列表卡片一致

浏览器实测：/kanban/ 卡片显示、＋新建看板 打开编辑器、管理员模式后 ✎ 编辑 带入原文、Markdown 生成与复制正常；
/archive/ 共 55 条明细，0 条 nanolog、0 条空标题，热力图 12 个月均有月初标记；
文章页热力图（近 35 天）与看板月/年视图的月初标记、悬浮日期均已生效。

七、已知问题与后续

tera2 仍是预发布分支，上面两处主题补丁属于本地修改，跟上游同步后需要重新打（或等上游合并）；
构建时仍有主题的弃用警告：4 处 get_taxonomy_url(name=…) 建议改用 term=；代码块语言 tera / git / Plaintext 未被高亮器识别（仅警告，不影响输出）；
content/archive/_index.md 的 aliases = ["Archive"] 与真实目录 /archive/ 在 macOS（大小写不敏感）上会互相覆盖，部署到 Linux 环境不受影响；
归档目前已剔除 nanolog；如果之后希望 nanolog 也进归档，需要先给 nanolog 生成标题再放开。

相关链接：归档 · 周计划看板 · 映射说明 · Ametrine 主题

M4 Mini 外置显示器重启后分辨率重置问题

2026-09-16T00:00:00+00:00

已经查清楚了。结论先给你：这次分辨率变成 800×600，不是某个软件或脚本“主动设置”的，而是屏幕重新上电时发生了一次热插拔抖动，系统没能读到显示器的 EDID（模式列表），于是触发了 macOS 自带的“安全模式回退”，最后落到了 800×600。

下面是我从系统日志里还原出的完整时间线（今天 09:34:50 附近，正好是你说的最近一次关屏再开屏）：

09:34:50.731 屏幕重新上电，系统报 Display 1 hot plug in。这次 EDID 读取是成功的，显示器被正确识别为 Kuycon G27P，模式是 5120×2880，也就是你平时看到的 2560×1440（HiDPI）。
09:34:51.109 显示器又立刻掉线了一次，日志报 Display 1 hot plug 0。这就是“上电瞬间热插拔抖动”。
紧接着系统报出关键错误：
- Preferred mode missing: display 0x1 pref=0x0
- No valid CA modes found for display 1
意思是：系统已经拿不到这个显示器的任何有效模式了。
09:34:51.723 前后，一个 1920×1080 的虚拟屏短暂顶了上来（这个是 BetterDisplay 创建的虚拟显示器）。
09:34:57.343 物理屏再次接入，但这次 EDID 没读全，被系统当成了 “Generic Display”（无 EDID 的通用显示器）。
系统开始按安全模式枚举低分辨率：
- 09:34:57.806 先设成 640×480
- 09:34:58.275 最终设成 800×600 @60Hz（RGB 8bit） ← 就是你看到的 800×600。

关于“是什么软件触发”：

我检查了安装的软件和后台项，没有发现 displayplacer、SwitchResX 这类专门改分辨率的工具，也没有任何脚本/定时任务去设置分辨率。
当时在跑的 Wine（wineloader/winedevice.exe） 只是 Windows 运行环境里的设备守护进程，日志显示它们只是在重新枚举鼠标键盘，并没有调用改分辨率。
机器上确实装了 BetterDisplay，而且它当时在运行，还创建了虚拟屏；它也把这个“Generic Display（800×600）”记录成了一个新显示器。但真正把物理屏设成 800×600 的，是 macOS 在“读不到 EDID、没有可用模式”时的安全回退，不是 BetterDisplay 主动设置的分辨率。

一个很有力的佐证是，系统保存的显示配置里同时存在这两条：

真实屏 Kuycon G27P 的配置是 2560×1440（HiDPI，Scale 2）——这是你的“原来分辨率”；
另有一个新身份 Generic Display（UUID 是 CADA3176…）被存成了 800×600——这就是这次降级后的身份。

所以本质原因是连接层面的 EDID 握手失败，最可能是：显示器彻底断电后立刻开机造成的上电时序抖动，或者线材、接口、转接器/扩展坞接触不稳定。

建议你这样处理：

再正常开关一次显示器，或者把视频线（HDMI/DP）拔掉重插一下，让系统重新读到 EDID，通常会自动回到 2560×1440。
如果经常在“彻底关屏再开屏”后变成 800×600，重点检查视频线、接口和转接器；有条件换一条线或换一个口试试。
如果你在用 BetterDisplay 的虚拟屏功能，可以顺便检查它“断开物理屏时自动连接虚拟屏”的选项，避免物理屏掉线瞬间它把虚拟屏变成主屏、让画面看起来被替换。另外这台机器上的 BetterDisplay 目前程序文件不完整（缺少框架文件，命令行工具无法加载），如果你并不用它，建议修复或卸载，减少干扰因素。

概率论 · 核心章节

2026-08-18T00:00:00+00:00

目标分数拆解科目满分目标底线说明数学二 150 125 110 决定上限，最大变量 408 150 115 105 你有 CS 底子，重点是捡起来英语二 100 78 72 相对友好，稳住阅读政治 100 70 65 后期突击为主合计 500 388 352 目标冲 390+，底线分不够稳

按 388 来拆：政治 70 + 英二 78 + 数学 125 + 408 115。数学和 408 是主战场，政治英语不能拖后腿。总体时间轴 8.19–9.30（约 6 周）：基础强化期，数学一轮 + 408 一轮 + 英语单词阅读。 10.1–11.15（约 6.5 周）：强化提升期，数学二轮真题 + 408 二轮大题 + 英语真题 + 政治启动。 11.16–12.18（约 4.5 周）：冲刺期，全科限时成套真题/模拟 + 背诵。 12.14–12.18：收尾调整，按考试时间全真模拟 2–3 次。分阶段详细计划阶段一：8.19–9.30，把底子捡起来这一阶段目标很明确：数学完成一轮，408 完成一轮选择题，英语恢复词汇和长难句，政治先不碰。数学二（每天 5 小时，优先级最高）第 1–2 周：高数——极限与连续、一元微分、一元积分。这是数二绝对核心，题量要足。第 3 周：多元函数微分、二重积分、常微分方程。第 4–5 周：线性代数——行列式、矩阵、向量组、线性方程组、特征值特征向量、二次型。第 6 周：查漏 + 阶段小测，重点把「极限、导数、积分、方程组、特征值」这几块做扎实。注意数二范围比数一少：不考概率、不考无穷级数、三重积分、曲线曲面积分和空间解析几何，别浪费时间在这些上。 408（每天 2.5–3 小时）数据结构和计组各 2 周，操作系统 1.5 周，计算机网络 1 周。顺序建议：数据结构 → 计算机组成原理 → 操作系统 → 计算机网络。用王道四本书过一轮，只做选择题，配合看王道视频/讲义。计组的存储、CPU、指令系统是重灾区，要慢一点。英语二（每天 1–1.5 小时）每天背单词，用「墨墨/不背单词」刷核心词，目标 9 月底把核心词过一遍。每周精读 3 篇英二阅读真题，逐句翻译长难句，不追求速度，先找回语感。政治：本阶段不开，最多每天 10 分钟翻翻框架。阶段二：10.1–11.15，上强度和真题数学二（每天 4.5 小时）开始做分章节真题，从较近的年份往前做，建立错题本。薄弱模块做专题：中值定理、积分计算、线代综合题等。 10 月底至少完成近 10 年真题的分章版。 408（每天 3 小时）二轮 + 大题专项：数据结构算法题、计组大题、OS 的 PV 操作和内存管理、网络 TCP/IP。开始成套做 408 真题，先不限时，重点是「会分析、能写出过程」。建立自己的背诵笔记：计组、OS、网络的概念型考点很多，后期靠它反复看。英语二（每天 1.5 小时）真题阅读每天 1–2 篇，二刷重点段落，总结题型套路。 10 月下旬开始练翻译和新题型。作文 10 月底起步：先背结构和常用句式，每周写 1 篇小作文 + 1 篇大作文。政治（10 月启动，每天 1–1.5 小时）徐涛强化课倍速过一遍（马原、史纲、毛中特、思修），配合肖秀荣 1000 题。目标 11 月 15 日前完成一轮选择题。阶段三：11.16–12.18，全真冲刺这个阶段每天基本按考试节奏练，重点变成「限时、成套、复盘」。数学二（每天上午 4 小时）成套真题近 10 年 + 李林 6+4 等模拟卷，严格 3 小时限时。错题本反复看，公式卡片随身背。目标考前稳定在 120 以上。 408（每天下午 3 小时）成套 408 真题反复做，近 8 年至少 2 遍，王道模拟挑着做。用笔记背诵计组、OS、网络的常考点。英语二（每天 1.5 小时）成套真题模拟 + 作文模板定稿并背熟。阅读保持每天手感，作文是性价比最高的提分点。政治（每天 2 小时，逐渐加到 3 小时）肖八 11 月出来后做选择题，反复刷错题。肖四 12 月出来后，大题背到考前，腿姐背诵手册/肖秀荣冲刺手册二选一。阶段四：12.14–12.18，收尾按真实考试时间做 2–3 次全真模拟：上午政治、下午英语；第二天上午数学、下午 408。数学只看公式和错题，408 只背笔记，英语只背作文模板，政治集中背肖四大题。调作息到早睡早起，不要再开新的大块内容。每日作息模板（脱产） 07:30 起床 08:00–09:00 英语单词 / 后期政治背诵 09:00–12:00 数学 12:00–14:00 午饭 + 午休 14:00–15:30 408 15:50–17:20 英语 17:20–18:30 晚饭 + 活动 18:30–20:30 数学刷题 / 408 错题 20:40–22:00 复盘 + 错题本 + 政治（后期）每天有效学习 9–10 小时即可，关键是持续，不要熬夜换时长。各科资料和要点数学二：武忠祥高数 + 李永乐线代为主，张宇或李林模拟卷；真题优先。每天都要动手算，不能只看视频。 408：王道四本 + 王道真题和模拟。你有计算机基础，不要陷进教材细枝末节，以考纲和王道为准，重点是反复刷题。英语二：英二真题（黄皮书）+ 唐迟阅读 + 田静语法长难句 + 王江涛/石雷鹏作文。单词背到考前。政治：肖秀荣精讲精练/1000题/肖八/肖四 + 徐涛强化课 + 腿姐冲刺背诵手册。政治是后期拉分成本最低的一科，但别太早花大块时间。报名和关键节点 9 月：关注中科大研招网和研招网，确认最新招生简章、拟招生人数和考试科目。 10 月 9 日左右：预报名。 10 月中旬：正式报名，登录研招网（yz.chsi.com.cn）填写信息。 11 月上旬：网上确认，务必按时完成，否则不能考试。 12 月 19–20 日：初试（以准考证为准）。每周复盘规则每周日晚上固定做四件事：统计本周各科完成率、把错题归类、判断下周是否要调整时间分配、检查有没有掉进「只看课不做题」的坑。数学和 408 用「做题量」而不是「看课量」来验收进度，这是脱产 4 个月最需要盯住的一点。一句话总结你的策略：数学二每天雷打不动 4 小时以上，408 靠真题反复滚，英语保住阅读和作文，政治 10 月后逐步加码、最后靠肖四收口。按这个节奏冲 390，比单纯堆资料和堆时长更重要

C++26 反射注解：自动成员验证

2026-08-17T00:00:00+00:00

在探索 C++26 系列的过程中，我之前的文章已经介绍了如何在 Ubuntu 上搭建 C++26 构建环境。之后，我探索了另一个名为模板的特性，并通过一个简单的示例讲解了反射的用法，并进一步学习了如何使用反射进行 JSON 序列化。在本文中，我将解释另一个极其强大的 C++26 特性，它叫做……注释以及它们与反思相结合如何使我们的生活更轻松。

首先，让我们来看下面这个假设的MotorConfig班级：

class MotorConfig
{
public:
    MotorConfig(int rpm, double maxTemperature, std::string deviceName);

    [[nodiscard]]
    int rpm() const noexcept
    {
        return m_rpm;
    }

    [[nodiscard]]
    double max_temperature() const noexcept
    {
        return m_maxTemperature;
    }

    [[nodiscard]]
    const std::string& device_name() const noexcept
    {
        return m_deviceName;
    }

private:
    int m_rpm;
    double m_maxTemperature;
    std::string m_deviceName;
};

这个类有一些私有成员m_rpm，m_maxTemperature这些m_deviceName成员在构造函数创建对象时会被初始化为特定的值。现在，假设你不希望类实例创建时使用超出某个范围的值，并且你想确保在构造时进行验证。你有哪些选择呢？你可以在构造函数中执行类似下面的操作：

MotorConfig::MotorConfig(int rpm, 
                         double maxTemperature, 
                         std::string deviceName)
    : m_rpm{rpm},
      m_maxTemperature{maxTemperature},
      m_deviceName{std::move(deviceName)}
{
    if (m_rpm < 0 || m_rpm > 10000)
    {
        throw std::out_of_range(
            "m_rpm is outside the permitted range [0, 10000]");
    }

    if (m_maxTemperature < -40.0 || m_maxTemperature > 150.0)
    {
        throw std::out_of_range(
            "m_maxTemperature is outside the permitted range [-40, 150]");
    }

    if (m_deviceName.empty())
    {
        throw std::invalid_argument(
            "m_deviceName is required");
    }
}

太好了！但是，如果向类中添加了另一个类成员，而该成员的值也需要验证，那么您必须在构造函数中手动添加验证代码来处理新成员。手动添加很容易出错。在 C++26 中，我们可以使用注解等特性，并结合反射等特性来自动化此验证过程。

使用注释 C++26 引入了注解的概念。注解的一般语法如下：

[[=constant-expression]] declaration 这意味着您可以将常量表达式与声明关联起来，然后在编译时检索这些值。我们稍后会详细介绍。此类注解的示例如下所示：

[[=42]] int value; 我们还可以使用用户自定义数据类型来定义更个性化的注释。

注解的用户自定义类型您还可以使用已定义的类型作为声明的注解，如下所示：

[[=AnnotationType{arguments…}]] declaration 例如，在我们的示例代码中，我们可以声明类型为 and 的注解Range，Required如下所示：

struct Range
{
    double minimum;
    double maximum;
};

struct Required
{
};

声明完成后，我们现在可以使用用户定义的类型注解将 MotorConfig 类重写如下：

class MotorConfig
{
public:
    MotorConfig(int rpm, double maxTemperature, std::string deviceName);

    [[nodiscard]]
    int rpm() const noexcept
    {
        return m_rpm;
    }

    [[nodiscard]]
    double max_temperature() const noexcept
    {
        return m_maxTemperature;
    }

    [[nodiscard]]
    const std::string& device_name() const noexcept
    {
        return m_deviceName;
    }

private:
    [[= Range{0.0, 10000.0}]] 
    int m_rpm;
    [[= Range{-40.0, 150.0}]] 
    double m_maxTemperature;
    [[= Required{}]] 
    std::string m_deviceName;
};

仔细阅读声明：

[[= Range{0.0, 10000.0}]] 
int m_rpm;
它表示成员变量的允许取值范围m_rpm为0.00 到10000.01。然而，目前该注解仅提供附加信息，它本身并不强制执行取值范围，除非后续代码强制执行，否则可以忽略。

现在反思一下
如上文代码所示，一旦注释就位，我们现在就可以利用反射来提取它们并在代码中使用它们。

首先，我们将编写一个循环来遍历类中的所有非静态成员MotorConfig：
```C++
template for (constexpr std::meta::info member : 
              std::define_static_array(
              std::meta::nonstatic_data_members_of(^^T,
                              std::meta::access_context::unchecked())))

我在本文template for中详细讨论了这一点。简而言之，它表示类型为的反射，在本例中为。它返回一个包含所有非静态成员反射的向量。但由于该向量使用动态存储，因此不能用作的范围。要将其与一起使用，我们需要将其复制到静态数组中，这可以通过来实现。^^TTMotorConfigstd::meta::nonstatic_data_members_oftemplate fortemplate forstd::define_static_array

然后，在每次迭代中，我们提取每个成员的注释：

constexpr auto ranges =
            std::define_static_array(std::meta::annotations_of_with_type(
                                     member, ^^Range));

该函数std::meta::annotations_of_with_type返回一个向量，其中包含所有类型为 <input> 的注解的反射Range。std::define_static_array它将这些反射复制到一个静态存储的数组中，并返回一个std::span指向该数组的引用。<input> 通常将其元素存储在动态分配的内存中，因此其内容不能直接存储在constexpr变量中ranges。

单注与多注请记住，每种类型中只能有一个注解：

[[= Range{0.0, 10000.0}]] int m_rpm; 但是，也可以在一个类型中包含多个注解：

[[=Range{0.0, 10000.0}, =Range{1000.0, 8000.0}]] int m_rpm; 你可以用以下任何一种方式表达：

[[=Range{0.0, 3000.0}, =Range{7000.0, 10000.0}]] int m_rpm; 或者分别如下：

[[=Range{0.0, 3000.0}]] [[=Range{7000.0, 10000.0}]] int m_rpm; 因此，在以下表达式中，ranges表示span引用注解的静态反射数组：

constexpr auto ranges = std::define_static_array(std::meta::annotations_of_with_type( member, ^^Range)); 在我们的例子中，我们只有一个注解，其反射可以用表示ranges[0]。为了提取可用范围，我们可以这样做：

constexpr Range range = std::meta::extract(ranges[0]); 剪接表达我们即将能够访问每个成员的当前值并将其与允许的范围进行比较。可以使用以下拼接表达式访问成员值：

template for (constexpr std::meta::info member : std::define_static_array(
                      std::meta::nonstatic_data_members_of(^^T,
                      std::meta::access_context::unchecked())))
    {
     ...
     ...
     constexpr auto ranges =
            std::define_static_array(std::meta::annotations_of_with_type(member, ^^Range));
        if constexpr (!ranges.empty())
        {
            ...
            const auto& value = object.[:member:];

[:member:]这是一个 C++26 拼接表达式。它将反射转换回该反射所代表的实体。因此，在第一次迭代中object.[:member:]，它将给出的值object.m_rpm，现在我们可以进行如下比较：

if (value < range.minimum || value > range.maximum) { throw std::out_of_range(std::string{name} + “ is outside the permitted range [“ + std::to_string(range.minimum) + “, “ + std::to_string(range.maximum) + “]”); } 在下一次迭代中，它将object.[:member:]给出值，object.m_maxTemperature依此类推。以下代码片段实现了所有这些功能：

template <typename T>
void validate_or_throw(const T& object)
{
    template for (constexpr std::meta::info member : std::define_static_array(
                      std::meta::nonstatic_data_members_of(^^T,
                      std::meta::access_context::unchecked())))
    {
        constexpr auto ranges =
            std::define_static_array(std::meta::annotations_of_with_type(
                member, ^^Range));
        if constexpr (!ranges.empty())
        {
            constexpr Range range = std::meta::extract<Range>(ranges[0]);

            const auto& value = object.[:member:];

            if (value < range.minimum || value > range.maximum)
            {
                throw std::out_of_range(std::string{name} 
                                    + " is outside the permitted range ["
                                    + std::to_string(range.minimum) + ", "
                                    + std::to_string(range.maximum) + "]");
            }
        }

注解的处理方式Required非常相似，可以大致按如下方式实现：

constexpr auto required =
    std::define_static_array(std::meta::annotations_of_with_type(member, ^^Required));

if constexpr (!required.empty())
{
    const auto& value = object.[:member:];
    if constexpr (requires { value.empty(); })
    {
        if (value.empty())
        {
            throw std::invalid_argument(std::string{name} + " is required");
        }
    }
    else
    {
        static_assert(
            requires { value.empty(); },
            "Required annotation can only be applied to a type "
            "that provides empty()");
    }
}

施工阶段验证验证功能在以下模板函数中实现：

template <typename T>
void validate_or_throw(const T& object)
{
    template for (constexpr std::meta::info member : std::define_static_array(
                      std::meta::nonstatic_data_members_of(^^T,
                                                           std::meta::access_context::unchecked())))
    {
        constexpr std::string_view name = std::meta::identifier_of(member);
        std::cout << "Validating member: " << name << '\n';

        constexpr auto ranges =
            std::define_static_array(std::meta::annotations_of_with_type(member, ^^Range));

        constexpr auto range_count = ranges.size();

        std::cout << "Found " << range_count << " range annotations for member: " << name << '\n';

        if constexpr (!ranges.empty())
        {
            constexpr Range range = std::meta::extract<Range>(ranges[0]);

            const auto& value = object.[:member:];

            if (value < range.minimum || value > range.maximum)
            {
                throw std::out_of_range(std::string{name} + " is outside the permitted range ["
                                        + std::to_string(range.minimum) + ", "
                                        + std::to_string(range.maximum) + "]");
            }
        }

        constexpr auto required =
            std::define_static_array(std::meta::annotations_of_with_type(member, ^^Required));

        if constexpr (!required.empty())
        {
            const auto& value = object.[:member:];

            if constexpr (requires { value.empty(); })
            {
                if (value.empty())
                {
                    throw std::invalid_argument(std::string{name} + " is required");
                }
            }
            else
            {
                static_assert(
                    requires { value.empty(); },
                    "Required annotation can only be applied to a type "
                    "that provides empty()");
            }
        }
    }
}

完整的源代码可在 GitHub 链接中找到。要编译代码，请在命令行中执行以下操作：

g++ -std=c++26 \
    -freflection \
    -Wall \
    -Wextra \
    -Wpedantic \
    reflection_validation.cpp \
    -o reflection_validation

./reflection_validation
Validating member: m_rpm
Found 1 range annotations for member: m_rpm
Construction failed: m_rpm is outside the permitted range [0, 10000]
Validating member: m_rpm
Found 1 range annotations for member: m_rpm
Validating member: m_maxTemperature
Found 1 range annotations for member: m_maxTemperature
Validating member: m_deviceName
Found 0 range annotations for member: m_deviceName
Valid configuration created.
RPM: 5000
Maximum temperature: 85
Device name: motor-controller-1

为了在程序启动时就启用验证，我们可以按如下方式在类validate_or_throw的构造函数中调用验证函数模板：MotorConfig

MotorConfig::MotorConfig(int rpm, double maxTemperature, std::string deviceName)
    : m_rpm{rpm},
      m_maxTemperature{maxTemperature},
      m_deviceName{std::move(deviceName)}
{
    validate_or_throw(*this);
}

这样可以确保当传递给构造函数的MotorConfig参数值超出允许范围时，构造函数会抛出异常。手动检查传递的参数值的麻烦就此消失了！

Mac-CrossOver-第五人格网络加速

2026-08-17T00:00:00+00:00

第五人格（CrossOver）更新资源慢：海外节点定位与解决报告

排查日期：2026-08-17

一、环境信息

项目	值
操作系统	macOS 27.0（Build 26A5406e），Apple Silicon（arm64）
CrossOver	26.3（Build 26.3.0.39832）
第五人格 PC 版	显示版本 `2.103.125221.2958769`（`update.ini` 记录 `2.103.2958769`）
游戏引擎	neox3 2.0.2589074（engine build：`release_2025_1217`）
网络	有线 Ethernet（en0 协商 100baseTX，理论峰值约 12.5MB/s）；出口 IP 杭州电信 36.24.57.87
运行方式	CrossOver 瓶子 `Identify-V`，游戏目录 `/data/Identify-V`（Z 盘）

二、问题现象

通过 CrossOver 安装/更新第五人格（dwr）时，“更新资源”阶段下载速度仅 0.2 ~ 1MB/s；
观察到 netease.com 相关 IP 归属为巴黎地区；
期望：国内网络、网易总部在杭州，资源更新不应这么慢。

三、排查过程与证据

3.1 更新链路域名与解析结果

游戏实际访问的更新域名全部 CNAME 到 Akamai，且固定返回巴黎节点：

用途	域名	Akamai 节点	归属
资源 CDN	`h55.gsf.netease.com`	`2.22.250.108 / 2.22.250.122`	法国巴黎（AS20940）
补丁 CDN	`h55.gph.netease.com`	`2.21.72.217 / 2.21.244.167`	法国巴黎（AS20940）
更新列表	`h55.update.netease.com`	`104.85.40.73`	法国巴黎（AS16625）
官方安装包	`a50.gdl.netease.com`	`92.123.238.200 / 92.123.238.170`	法国巴黎（AS20940）

分别使用阿里 223.5.5.5、腾讯 119.29.29.29、114.114.114.114、8.8.8.8、1.1.1.1 解析，并带 EDNS 客户端子网（杭州 / 香港 / 日本 / 新加坡）测试，返回结果完全一致——均为上述巴黎 IP。结论：不是本机 DNS 设置问题，是网易这些域名被 Akamai 固定映射到了巴黎节点。

3.2 路由跟踪：流量确实出国

192.168.1.1（本地网关）
→ 杭州电信骨干 202.97.x（约 10ms）
→ GTT 国际线路 154.54.x（第 11 跳起 RTT 跳到 180~250ms）
→ 巴黎 Akamai 节点

杭州电信直连巴黎约 200ms+ RTT，跨国链路上单条 TCP 连接被限制在 1MB/s 左右。

3.3 本机网络本身无问题

无代理/VPN 时出口为杭州电信（36.24.57.87）；
使用 8 个并行连接同时下载同一文件：单连接 0.4~1.0MB/s，合计约 6.3MB/s；
说明瓶颈是“跨国链路单连接限速”，而不是本机带宽或网卡。

3.4 游戏日志实锤

log.txt 中 patch_download_info.cur_speed ≈ 1183000 B/s（1.13MB/s），与用户感知一致；
cloud.json 配置 downloader_connect_num: 2，实测游戏进程只有 2 条 ESTABLISHED TCP 连接（Wine/WinINET 默认每主机 2 连接）；
首次安装日志（.dlstorage/downloading/download.log）显示 2026-01-29 使用 h55-h.gdl.netease.com 下载 13GB，速度 119MB/s——证明网易国内节点完全可以跑满，当前只是更新配置指向了海外。

3.5 两个“无效尝试”的原因分析

尝试	现象	原因
修改 `cloud.json` 连接数	无效	引擎实际读取 `Documents/cloud.json`，且每次启动会被引擎重写回 `downloader_connect_num: 2`；只改根目录 `cloud.json` 不生效。另外即使连接数放开，巴黎链路单连接限速约 1MB/s，提升有限
网易 UU 加速器	无效	UU 只接管了 `h55.update.netease.com`（仅 3.8KB 的列表），真正下载资源的 `h55.gsf.netease.com` 仍直连巴黎（lsof 可见 `192.168.1.101 → 2.22.250.122`）。游戏进程需在 UU 启动后重启，UU 才会接管该域名

四、根因结论

网易 PC 版更新 CDN 被 Akamai 固定映射到巴黎节点（h55.gsf/gph/update.netease.com 等），不随 DNS/EDNS 变化；大陆直连跨国国际链路，单连接约 1MB/s；
游戏下载器实际只维持 2 条连接（配置未生效 + Wine/WinINET 默认每主机 2 连接），进一步限制吞吐；
本机 100Mbps 网口（理论峰值约 12.5MB/s）不是主因，但是最终吞吐的天花板。

五、解决方案（已实施并验证）

5.1 放开连接数限制

修改根目录 /data/Identify-V/cloud.json：
- downloader_connect_num: 2 → 32
- （Documents/cloud.json 会被引擎重置，不必修改）
向 CrossOver 瓶子 Identify-V 写入注册表（解除 Wine/WinINET 每主机 2 连接限制）：
- HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings\MaxConnectionsPerServer = 32
- HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings\MaxConnectionsPer1_0Server = 32
- HKCU\Software\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_MAXCONNECTIONS\dwrg.exe = 32

# 1) 把瓶子名改成你自己的（默认 Identify-V）
export WINEPREFIX="$HOME/Library/Application Support/CrossOver/Bottles/Identify-V"
export CX_BOTTLE="Identify-V"

# 2) 定位 CrossOver 自带的 wine（注意：不能用系统 wine）
WINE="/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine"
test -x "$WINE" || WINE="$HOME/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine"

# 3) 写入注册表：解除 WinINET 每主机 2 连接限制
"$WINE" reg add "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings" /v MaxConnectionsPerServer /t REG_DWORD /d 32 /f
"$WINE" reg add "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings" /v MaxConnectionsPer1_0Server /t REG_DWORD /d 32 /f
"$WINE" reg add "HKCU\\Software\\Microsoft\\Internet Explorer\\Main\\FeatureControl\\FEATURE_MAXCONNECTIONS" /v dwrg.exe /t REG_DWORD /d 32 /f

# 4) 验证是否写入成功
"$WINE" reg query "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings" /v MaxConnectionsPerServer
"$WINE" reg query "HKCU\\Software\\Microsoft\\Internet Explorer\\Main\\FeatureControl\\FEATURE_MAXCONNECTIONS" /v dwrg.exe

或者

打开 CrossOver → 选中瓶子 Identify-V → 点运行命令…（Run Command）；
输入 regedit 并运行，打开注册表编辑器；
依次新建三个值：

路径 HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings
- MaxConnectionsPerServer = DWORD 32
- MaxConnectionsPer1_0Server = DWORD 32
路径 HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_MAXCONNECTIONS
- 新建项 dwrg.exe = DWORD 32

关闭 regedit，重启游戏（先开 UU）。

重启游戏，使配置生效。

5.2 让 UU 加速器接管资源下载

先开启网易 UU 加速器（第五人格 PC 版），再启动游戏；
重启后 UU 接管 h55.gsf.netease.com，下载目标从巴黎 Akamai 变为国内节点：
- 122.228.15.35（浙江温州电信）
- 183.146.26.98 / 183.146.26.91（浙江金华电信）
- 45.253.145.166（网易北京机房，AS45062）

5.3 验证结果

指标	修复前	修复后
下载速度	0.2 ~ 1MB/s	8.5 ~ 9.5MB/s（15 秒持续采样约 5.9MB/s）
活动连接数	2（直连巴黎）	5+（经 UU 转国内节点）
更新总量	3.8GB	预计数分钟完成

六、备份与回滚

修改前的备份文件：

/tmp/cloud.json.root.20260817121545.bak
/tmp/cloud.json.doc.20260817121545.bak
/tmp/user.reg.20260817121545.bak

如需还原：停止游戏后，将对应备份复制回原路径，或删除新增注册表项。

七、日常使用建议

每次游戏更新前：先开 UU 加速，再启动游戏；
不要修改 Documents/cloud.json（引擎启动时会重写）；根目录 cloud.json 可保持 downloader_connect_num: 32；
若更换网络/加速器，可用 lsof -nP -iTCP -sTCP:ESTABLISHED | rg dwrg 观察连接目标是否为国内节点；
当前有线网口协商在 100Mbps，理论上限约 12.5MB/s；如需更高速度，检查网线/转接器是否支持千兆。

附录：关键文件与命令

关键文件

游戏目录：/data/Identify-V
更新配置：/data/Identify-V/cloud.json
运行日志：/data/Identify-V/log.txt
云下载日志：/data/Identify-V/Documents/cloud_logs/cloud_log.txt
旧安装日志：/data/Identify-V/.dlstorage/downloading/download.log
CrossOver 瓶子：~/Library/Application Support/CrossOver/Bottles/Identify-V

关键命令

# 查看游戏进程连接目标
lsof -nP -iTCP -sTCP:ESTABLISHED | rg dwrg

# DNS 对比解析（多个公共 DNS）
dig +short h55.gsf.netease.com @223.5.5.5
dig +short h55.gsf.netease.com @8.8.8.8

# 路由跟踪
traceroute -n -m 20 h55.gsf.netease.com

# 并行下载测速（验证单连接 vs 多连接）
for i in {1..8}; do curl -s -m 25 -r 0-4194303 -o /dev/null \
  -w "$i:%{speed_download} " <URL> & done; wait

2026-08-11T20:00:00+00:00

2026年08月12日 04:00（东八区 / 北京时间）

看板微调：描述正文悬停浮层 · 看板字体加大加粗

概述

卡片存在描述正文时，悬停「☰ 有描述」徽标或卡片内描述区，浮层显示完整描述（跟随鼠标、自动防溢出、离开消失）；
看板界面字体整体 大 2 号并加粗（列头 / 卡片标题 / 徽标 / 清单 / 描述 / 元信息 / 列表页卡片）。

1. 描述正文悬停浮层

bindDescTooltip()：有内容时给「☰」徽标与内联描述区绑定 mouseenter / mousemove / mouseleave；
浮层 kanban-desc-tooltip 复用 renderDescription()（支持加粗 / 代码 / 换行），跟随鼠标偏移显示，越界自动翻转，pointer-events: none 避免抖动；
离开控件即隐藏。

2. 字体加大加粗（+2 号）

元素	调整
列头	0.9rem → 1.06rem，weight 700 → 800
列计数	0.72rem → 0.82rem，加粗
卡片正文	0.82rem → 0.94rem，weight 500
卡片标题	0.88rem → 1.06rem，weight 700
清单行	0.78rem → 0.9rem，weight 600
卡片描述	0.78rem → 0.9rem，weight 600
徽标 / 标签药丸	0.7rem → 0.82rem / 0.68rem → 0.78rem，加粗
看板元信息	0.8rem → 0.9rem，weight 600
工具栏按钮	0.82rem → 0.92rem，weight 600
列表页周卡	标题 1.2rem weight 800；元信息 / 统计 0.9rem weight 700

3. 验证

node --check 通过；zola build 0 ERROR；verify-kanban-build OK（5 周看板）。

相关链接：映射说明 · 周计划列表

2026-08-11T18:00:00+00:00

2026年08月12日 02:00（东八区 / 北京时间）

看板微调：全封面整卡着色 · 卡片时间只显示月-日 · 移除列头 ⋯ 按钮

概述

按截图反馈做三处细节调整：

封面区分度：@cover full 由“更高的色条”改为整卡背景着色（浅色自动深字），与半封面的顶部色条一眼可辨；
卡片时间格式：卡片徽标中的开始/截止日期去掉年份，只显示 MM-DD（悬停 tooltip 保留完整日期）；
列头按钮：移除待办 / 进行中等列头右侧的 ⋯ 按钮及其弹层（添加卡片、重命名、排序、删除入口同步清理；排序仍可在 GUI 编辑器列表面板设置，双击列名仍可重命名）。

1. 全封面 = 整卡背景

详情页：cover-full 时卡片背景 = @bg 颜色，标题/清单/描述按背景明暗自动切换白字或深字（isLightColor 判定 + cover-text-dark）；
半封面（默认）：保持顶部色条 + 白底正文，对比明显；
GUI 编辑器画布同步同款渲染，预览所见即所得。

2. 卡片时间只显示月-日

详情页 startBadge / dueBadge：📅 06-16、🕒 08-13（tooltip 保留 2026-06-16 完整日期）；
编辑器画布徽标同步 MM-DD；
进度列日卡标题本就是 MM-DD 周X，保持一致。

3. 移除列头 ⋯ 按钮

renderBoard 不再生成 .kanban-column-menu-btn；
删除 openColumnMenu / handleColumnAction / popoverItem / popoverSep 死代码；
保留：双击列名重命名、列底「＋添加卡片」、看板「＋添加列表」、GUI 编辑器内的列排序/增删。

4. 验证

node --check 通过；zola build 0 ERROR；verify-kanban-build OK（5 周看板）。

相关链接：映射说明 · 周计划列表

2026-08-11T16:00:00+00:00

2026年08月11日 24:00（东八区 / 北京时间）

看板修复：GUI 编辑器拖拽真正生效 · 置顶按钮完善 · 中文时段文件名 slug 对齐

概述

上一轮「画布卡片拖拽 / 置顶」在本地代码已存在，但存在三个致命细节导致实际不可用/不可见，本轮定位并修复：

GUI 编辑器拖拽失效根因：画布列元素缺少 data-col-idx，放置时 toColIdx = NaN，松手永远不落位；
置顶可见性与交互：画布置顶图标改为可点击按钮，详情页置顶徽标改为 <button> 且空闲态样式修正（此前 .is-idle 选择器嵌套错误不生效）；
中文文件名 slug 错位：Zola 将 2026-08-11_晚上.md 转写成拼音 URL slug wan-shang，导致编辑“修改/新建”判定与 Codeberg 链接指向错误文件名。

1. GUI 编辑器卡片拖拽

renderCanvas() 为每个画布列写入 colEl.dataset.colIdx = ci，setupCanvasCardDrag 放置逻辑可正确解析目标列；
同列拖拽插入目标卡片前、跨列拖拽移入目标列（末尾或目标卡片前）；
松手后 renderAll() 重绘画布并刷新 Markdown 预览，预览与拖拽结果保持一致。

2. 置顶功能完善

画布卡片：📌 改为 <button>，每张卡片均可点击置顶/解除（已置顶高亮），点击不触发选中；
详情页卡片：徽标行置顶按钮改为 <button>；解锁模式每卡显示（未置顶 = 虚线灰 📌，已置顶 = 高亮「📌 置顶」）；锁定只读仅显示已置顶徽标；
CSS 修正：.kanban-card-badge--pin.is-idle 独立选择器（此前嵌套在 .is-pinned 下永不生效）；button.kanban-card-badge 字体继承。

3. 中文时段文件名 slug 对齐

Zola 对 2026-08-11_晚上.md 生成 URL slug wan-shang，但仓库文件名仍是 2026-08-11_晚上.md；
列表页 / 明细页 data-slug 与 Edit Post 链接改用 page.relative_path 提取的真实文件名（split(pat='/') | last | replace(from='.md', to='')）；
编辑器「修改/新建」判定、Codeberg 编辑链接、Token 同步目标均指向真实文件名；
verify-kanban-build.mjs：纯日期 slug 仍校验输出目录；带时段的 slug 因无法确定拼音转写，改验列表页已渲染该周（data-week-start 存在）+ 卡片计数一致。

4. 验证

用户已通过 GUI 新建出 content/kanban/2026-08-11_晚上.md（单日 + 时段命名实战通过）；
zola build 0 ERROR，verify-kanban-build OK（5 周看板）；
构建产物：列表页 data-slug=2026-08-11_晚上、明细页 wan-shang 页面 Edit Post 指向真实文件名。

相关链接：映射说明 · 周计划列表

2026-08-11T14:00:00+00:00

2026年08月11日 22:00（东八区 / 北京时间）

看板缺陷修复：时间粒度 1–14 天 · 单日时段命名唯一 · 置顶完善

概述

三项修复：

时间细化：最小 1 天、最大 14 天；新建默认 今日 → 今日；编辑已有看板时开始时间锁定；卡片开始/截止按创建时间默认填充且不越界；
单日时段命名：YYYY-MM-DD_上午 / _下午 / _晚上，保证同一天多张 1 天看板文件唯一；
置顶完善：详情页解锁模式每张卡片均有置顶/取消置顶切换按钮，GUI 编辑器卡片面板按钮保留。

1. 时间粒度与约束

项	实现
最小 1 天 / 最大 14 天	`validate()`：`daySpan < 1` 不再报错（同日合法），`> 14` 报错
新建默认今日	`defaultState()`：`weekStart = weekEnd = 今日`，时段按当前小时预选（5–12 上午 / 12–18 下午 / 其余晚上）
编辑时开始锁定	修改模式 `weekStart` 输入 `disabled`；时段同样锁定（文件名标识）
最大时间不可选	结束日期 `max = 开始 + 13 天`（`buildBoardPanel` + `applyDateBounds` 双处生效）
卡片默认日期	GUI 新增卡片 / 详情页快捷添加：`@start = @due = 今日`，越界时自动夹取到 `[week_start, week_end]`；后续可编辑

2. 单日时段命名唯一

2026-08-11_上午.md
2026-08-11_下午.md
2026-08-11_晚上.md

Front Matter 新增 period（无 / 上午 / 下午 / 晚上），仅单天看板参与文件名（buildSlug()）；
多天看板忽略时段，文件名保持 YYYY-MM-DD；
所有「目标文件」逻辑（模式徽标、流程指引、Token 同步、Codeberg 链接）统一改用 buildSlug()；
列表卡片新增 data-slug（= page.slug），编辑器 existingSlugs 与修改判定按完整文件名；
列表页 / 明细页展示时段徽标（kanban-period-chip）；
verify-kanban-build.mjs 正则支持 日期_时段.md。

3. 置顶完善

详情页卡片徽标行：解锁模式下每张卡片显示置顶切换（未置顶 = 灰色 📌，已置顶 = 高亮「📌 置顶」），点击切换；
锁定只读模式仍显示置顶徽标（不可点击）；
GUI 编辑器卡片面板「置顶 / 解除置顶」按钮 + 画布 📌 指示保留；
置顶卡片始终排在同列表顶部（sortCards() 置顶优先，多卡可同时置顶）。

4. 涉及文件

文件	作用
`static/js/kanban-rules.js`	`period` Front Matter 序列化
`static/js/kanban-editor.js`	默认今日/时段、开始锁定、结束上限、卡片默认日期、`buildSlug()`、置顶按钮
`static/js/kanban-board.js`	快捷添加默认日期、置顶切换按钮、GUI 事件携带 slug
`templates/kanban_list.html` / `kanban.html`	`data-slug`、时段徽标
`scripts/verify-kanban-build.mjs`	支持 `日期_时段.md`
`sass/kanban/style.scss`	时段徽标、置顶空闲态
`content/kanban/kanban-mapping.md` / `_index.md`	命名与约束文档

5. 验证

node --check 四个 JS 通过；
规则测试：现有 4 看板往返无损；period 序列化保留；
zola build 无错误，verify-kanban-build OK（含新的命名正则）。

相关链接：映射说明 · 周计划列表

2026-08-11T12:00:00+00:00

2026年08月11日 20:00（东八区 / 北京时间）

看板微调：卡片拖拽修复 · 热力图弹层滚动修复 · 各板块 ASCII 电子屏图

概述

本轮三项工作：

卡片拖拽恢复：详情页解锁模式与 GUI 编辑器画布均改用指针拖拽（mousedown/mousemove/mouseup + 拖拽幽灵），规避 macOS Chrome 上 HTML5 DnD 不触发的问题；列头拖拽仍走原生 DnD；
热力图同日多篇弹层滚动修复：弹层内部滚动不再触发“关闭弹层”，滚动条常驻可点；
ASCII 电子屏图：参照英语板块的 {% crt %} 效果，为每个板块生成主题横幅。

1. 卡片拖拽修复

详情页（解锁管理员模式）

新增 setupDragDrop 指针拖拽：按下卡片移动 ≥6px 生成 kanban-drag-ghost 幽灵，高亮目标列，松手跨列移动并写入脏状态；
不再依赖 HTML5 卡片 DnD（macOS Chrome 偶发不触发 dragstart），列头拖拽保留原生 DnD；
拖拽期间卡片 cursor: grabbing，结束自动清理幽灵/高亮。

GUI 编辑器（画布）

画布卡片带 data-col-idx / data-card-idx，新增 setupCanvasCardDrag()：
- 同列拖拽：插入到目标卡片前（源卡索引位移已修正）；
- 跨列拖拽：移入目标列末尾或目标卡片前；
- 松手后更新 selection 并 renderAll() 重绘。

2. 热力图同日多篇弹层滚动修复

问题	修复
弹层内部滚动立即关闭弹层	`scroll` 捕获监听改为忽略 `popoverState.el.contains(event.target)` 的滚动，仅外层滚动关闭
滚动条控件消失、无法滚选	`.heatmap-popover-list` 增加 `overscroll-behavior: contain`、`scrollbar-width: thin`、WebKit 滚动条样式，`max-height: min(190px, 45vh)`
翻转到底部后可能超出视口	`positionPopover` 增加视口下限钳制

3. 各板块 ASCII 电子屏图

参照英语板块 {% crt(label=...) %} 短代码（CRT 扫描线 + 闪烁 + 发光），用 figlet banner3-D 像素风字体生成主题横幅，插入各板块 _index.md：

板块	横幅	主题标签
数学	MATH	∫ ∑ √ π · 导数微积分线性代数概率论离散数学
CMake	CMAKE	构建 · 安装 · 打包 · 导出
CXX20	CXX20	现代 C++ · 模块 · 协程 · 范围
Jai	JAI	语言规范 · 编译器 · 极致性能
论文精读	PAPER	精读 · 核心思想 · 实验 · 复现
算法设计	ALGO	字符串 · 树 · 图 · 排序 · 408
读后感	READING	书籍 · 文档 · 笔记 · 感想
随笔	ESSAY	随想 · 杂记 · 短思考
Debug	DEBUG	追踪 · 剖析 · 修复（替换原房屋图）
分享	SHARE	工具 · 技巧 · 收藏（替换原房屋图）

4. 涉及文件

文件	作用
`static/js/kanban-board.js`	详情页指针拖拽
`static/js/kanban-editor.js`	画布卡片拖拽
`static/js/heatmap-init.js`	弹层滚动关闭条件、视口钳制
`static/css/heatmap.css`	弹层列表滚动条与 overscroll
`sass/kanban/style.scss`	拖拽幽灵 / 高亮 / 抓取光标
各板块 `content/**/_index.md`	CRT ASCII 横幅

5. 验证

node --check 四个 JS 通过；
zola build 无错误，verify-kanban-build OK；
构建产物中 10 个板块页面均含 class="crt" 与对应横幅文本。

相关链接：映射说明 · 周计划列表

2026-08-11T10:00:00+00:00

2026年08月11日 18:00（东八区 / 北京时间）

看板功能微调：顶格时间约束 · 默认六列布局 · 卡片置顶

概述

在看板 GUI 编辑器与明细页上完成三项微调：

顶格时间约束：week_start / week_end 必须优先设置，跨度 2 ~ 14 天，所有卡片 @start / @due 不得超出该区间；
默认新建布局：待办 / 进行中 / 已完成 / 进度四列竖向，资源 / 目标底部并排；进度列按天生成卡片并预填勾选清单；
卡片置顶：新增 @pin 指令，同列表可多卡片置顶，置顶优先显示且带 📌 徽标。

1. 顶格时间约束

规则	实现
必须优先设置	检查器“看板信息”面板将周起止放在首位；未设置无法通过校验
跨度 2–14 天	`validate()`：`daySpan < 2` 或 `> 14` 均报错并提示当前天数
卡片时间不得越界	`validate()` 逐卡片检查 `@start` / `@due` 是否落在 `[week_start, week_end]`；错误信息带列/卡片定位
日期选择器联动	周开始 `max=周结束`、周结束 `min=周开始`；卡片开始/截止 `min=周开始`、`max=周结束`（`applyDateBounds()`）

2. 默认新建布局

待办    进行中    已完成    进度        ← 主流程列（竖向一排）
资源    目标                             ← 底部并排一行

columnKind 新增 progress 识别（进度 / progress / timeline），进度列青色头样式；
明细页 renderBoard 改为两行容器：.kanban-board-main（主流程列）+ .kanban-board-bottom（资源/目标并排）；
编辑器画布同步两行预览（.kanban-editor-canvas-row）；
进度列按天生成：dayCardsBetween(week_start, week_end)，每张卡片标题 MM-DD 周X，默认预填一条勾选清单「记录当日完成内容」（可勾选/划线）；
修改顶格时间且进度列仍为自动生成样式（标题匹配 MM-DD 周X）时，maybeRegenerateProgress() 自动重排天数（仅新建模式）。

3. 卡片置顶

规则引擎：@pin / @置顶 指令 ↔ 卡片 pinned 字段，序列化往返无损；
sortCards() 置顶优先：同一列表置顶卡片始终排在最前（手动模式保持相对顺序；按截止/优先级等排序时置顶组仍置顶）；
明细页：置顶卡片带 📌 置顶 徽标（左侧强调边框），解锁模式点击徽标取消置顶；
GUI 编辑器：卡片面板新增「置顶 / 解除置顶」按钮，画布卡片右上角显示 📌。

4. 涉及文件

文件	作用
`static/js/kanban-rules.js`	`@pin`、progress 列识别、置顶优先排序
`static/js/kanban-editor.js`	默认六列 + 进度按天、时间校验、日期边界联动、置顶按钮
`static/js/kanban-board.js`	两行布局、置顶徽标交互
`sass/kanban/style.scss`	两行容器、进度列配色、置顶样式
`content/kanban/kanban-mapping.md`	规则与布局文档同步

5. 验证

node --check 三个 JS 通过；
规则测试：现有 4 看板往返无损；@pin 解析/序列化、置顶+按截止混合排序、progress 列识别全部通过；
zola build 无错误，verify-kanban-build OK。

相关链接：映射说明 · 周计划列表

2026-08-11T08:00:00+00:00

2026年08月11日 16:00（东八区 / 北京时间）

看板详情页：Trello 1:1 重构 · 规则引擎升级 · GUI 编辑器布局重设计

概述

本轮先以产品经理视角调研 Trello（官方 Support 文档 + 开源仿 Trello 项目 Planka / Kan / kanbany），对照自建看板做差距分析；随后：

看板详情页 UI 全盘对齐 Trello（头部/背景/列/卡片正面/筛选/菜单抽屉/快捷添加）；
规则映射引擎新增 @done、@cover、列级 @sort/@sort-order，Front Matter 新增 board_bg/favorite；
GUI 编辑器由“单列长表单”重构为 Trello 式「画布 + 检查器」 双栏布局；
映射文档与 nanolog 同步更新。

按需求排除复杂功能：附件、成员/角色指定、评论、Power-Ups/Butler 自动化、贴纸。

1. Trello 调研结论（功能矩阵）

Trello 元素	核心功能	本轮采用	说明
看板 Board	标题 + 收藏星标	✅	`extra.favorite`，星标状态写入 Markdown
看板背景	纯色 / 图片 / 渐变	✅	`extra.board_bg` + 12 种预置渐变 + 自定义
看板菜单	关于 / 背景 / 搜索 / 更多	✅	右侧抽屉
筛选 Filter	关键词 / 标签 / 截止 / 成员 / 保存视图	✅（去成员/保存视图）	快捷键 `F`
列表 List	头部（名+计数+⋯菜单）/ 添加列表 / 拖拽排序	✅	排序（截止/优先级/标题/清单）、重命名、删除、拖拽列头
卡片正面	标签 / 标题 / 徽标行 / 封面	✅	标签药丸、封面 `@bg`+`@cover`、徽标行
截止徽标	灰/黄/红/粉/绿状态色	✅	`dueState()` 5 态
清单进度	卡面进度条 + x/y	✅	`checklistStats()`
标记完成	卡面圆圈打勾	✅	`@done` 指令
快捷添加	列底“+ 添加卡片” / 右侧“+ 添加列表”	✅	解锁模式，保存走 Edit Post
归档 / 评论 / 成员 / 附件 / Power-Up / Butler	—	❌	需求排除

2. 详情页 UI 重构（Trello 1:1 对齐）

2.1 看板头部

返回链接 → 标题 + 收藏星标 → 元信息行（开始/截止/剩余天数/进度/星级）→ 工具栏。

工具栏（管理员可见）：锁定 / 筛选（F）/ 菜单 / GUI 编辑 / Edit Post / ReDeplog / 映射说明。

2.2 背景

extra.board_bg 驱动 .kanban-page 背景；深色背景自动切换浅色文字（has-board-bg）。菜单抽屉内提供 12 色渐变 + 默认 + 自定义输入。

2.3 列

头部 = 列名（解锁后双击内联重命名）+ 计数 + ⋯ 菜单；菜单含：添加卡片 / 排序（手动/截止/优先级/标题/清单，升/降序）/ 删除列。解锁后列头可拖拽调整顺序。

2.4 卡片正面

标签药丸（带文字、浅色自动深字）· 封面条（@bg，@cover full 加高）· 完成圆圈（有 @due 时显示，切换 @done）· 徽标行（描述 / 开始 / 截止 / 清单进度 / 优先级）。

截止徽标色义（Trello）：灰=未到 · 黄=今天/即将到期 · 红=逾期 · 粉=逾期超 1 天 · 绿=已完成。

2.5 筛选与菜单抽屉

筛选弹层：关键词 + 标签多选 + 截止状态 + 最低优先级 + 隐藏已完成；列计数实时显示 可见/总数；清除一键复位。
菜单抽屉：关于此看板（进度条）· 背景色板 · 搜索卡片（回车进入筛选）· 更多（GUI 编辑 / 保存 / ReDeplog / 映射说明）。

2.6 快捷添加

解锁后每列底部「＋添加卡片」、看板右侧「＋添加列表」，内联输入回车提交；所有本地修改（拖拽/勾选/排序/添加/背景/收藏/完成标记）统一提示“有未保存的本地修改”，保存走 Edit Post。

3. 规则映射引擎升级（kanban-rules.js）

新增	语法	说明
完成状态	`@done` / `@complete`	卡片 `done` 布尔，截止徽标变绿、标题划线
封面尺寸	`@cover half / full`	默认 half；配合 `@bg` 使用
列排序	`@sort manual/due/priority/title/checklist`	列对象 `sort` 字段
排序方向	`@sort-order asc/desc`	列对象 `sortOrder` 字段
看板背景	`extra.board_bg`	预置色名 / 色值 / gradient
收藏	`extra.favorite`	布尔，写入 front matter

新增辅助函数：checklistStats()、dueState()（5 态截止徽标）、sortCards()、resolveBoardBg()、BOARD_BG_PRESETS。解析器新增列级指令分支；序列化按新模型往返无损（4 个现有看板测试通过）。

兼容性说明：@bg 语义由“整卡背景色”调整为 Trello 封面（卡片正面顶部色块，正文白底），映射文档已同步。

4. GUI 编辑器布局重设计（Trello 画布 + 检查器）

区域	内容
顶部	模式徽标（新建/修改）· 标题 · 目标文件提示 · 关闭
左：画布	实时渲染看板（背景/列/卡片封面/标签/徽标）；点击列或卡片选中；「添加列表」「添加卡片」直达
右：检查器	按选中对象切换：看板信息（含背景色板/收藏）· 列表设置（列名/排序/方向/增删移）· 卡片设置（全部 `@` 指令，下拉/手输/色板/清单/描述）
底部	可折叠 Markdown 预览 + 结果流程区（复制/创建/修改指引/Token 同步）

原“单列长表单”改为“选中即编辑”，字段与指令一一对应，覆盖新增的 @cover、@done、@sort、board_bg、favorite。

5. 涉及文件

文件	作用
`static/js/kanban-rules.js`	新指令解析/序列化、截止状态、清单统计、排序、背景预置
`static/js/kanban-board.js`	详情页 Trello 渲染、筛选、菜单抽屉、快捷添加、列拖拽、脏状态
`templates/kanban.html`	新头部/筛选栏/菜单抽屉结构
`static/js/kanban-editor.js`	画布+检查器编辑器、字段映射、复制、创建/修改流程、Token 同步
`templates/partials/kanban_editor.html`	编辑器模态框新结构
`sass/kanban/style.scss`	详情页 + 编辑器新样式
`content/kanban/kanban-mapping.md`	新指令/字段/布局文档

6. 验证

node --check 三个 JS 全部通过；
规则引擎往返测试：现有 4 个看板列/卡片无损；新指令（@done/@cover/@sort/board_bg/favorite）生成→解析→再生成全部保留；
zola build 无错误，verify-kanban-build 通过（4 周看板完整）；
明细页 HTML 已包含筛选栏/菜单抽屉/收藏星标/编辑器画布等新节点。

7. 后续计划

真机浏览器走查：剪贴板权限、拖拽、弹层定位、深色主题；
卡片/列表“归档 + 恢复”（Trello Archive）；
筛选条件保存为视图（URL hash）；
编辑器移动端布局细化。

相关链接：映射说明 · 周计划列表

2026-08-11T06:00:00+00:00

2026年08月11日 14:00（东八区 / 北京时间）

看板 GUI 编辑器：新建 / 修改 · 剪贴板 · 创建与修改流程指引

概述

本轮为看板补充 GUI 编辑器：不再需要手写 @ 指令 Markdown，而是通过表单（下拉 / 手输）设置看板的每个“图标/指令“可选值，自动生成 Markdown 并复制到剪贴板，随后给出 创建 or 修改 的完整操作流程提示。

1. 入口

位置	按钮	模式
列表页 `/kanban/` 页头	＋新建看板	新建：默认本周一～周日 + 五列（待办/进行中/已完成/资源/目标）
列表页每张周卡片	✎ 编辑	修改：读取该周已有 Markdown 载入表单
明细页工具栏（解锁后）	GUI 编辑	修改：读取当前看板载入表单

2. 字段与指令映射（下拉或手输）

表单字段	生成指令	输入方式
开始 / 截止日期	`@start` / `@due`	日期选择
重要等级	`@priority 1–5`	星级下拉
目标类型	`@goal complete / risk`	下拉
颜色标签	`@labels`	预设色块多选 + 自定义色值手输
背景色 / 顶栏色	`@bg` / `@top`	预设色名下拉 + 自定义 `#RRGGBB` + 实时色块
勾选清单	`- [ ] / - [x]`	逐行增删勾选
描述正文	其余 Markdown	多行文本
列	`# 列名`	列名输入 + 添加/删除 + 快速列
周起止 / 核心任务 / 星级	Front Matter	日期 / 文本 / 下拉

3. 生成 → 剪贴板 → 流程提示

表单右侧实时 Markdown 预览；
点「生成并复制到剪贴板」：
- 自动复制序列化后的 Markdown；
- 弹出流程提示，明确区分创建与修改：
  - 创建（文件不存在）：Codeberg 新建文件 → 粘贴 → 保存提交 → ReDeplog 部署 → 刷新列表；
  - 修改（文件已存在）：Codeberg 覆盖文件 → 全选替换 → 保存提交 → ReDeplog 部署 → 刷新列表；
- 提供「打开 Codeberg 编辑器」「打开 ReDeplog」快捷按钮；
若已保存 kanbanToken，可「用 Token 直接同步到仓库」（POST 创建 / PUT 覆盖，复用原 API 逻辑）。

4. 权限调整

新建看板按钮：管理员模式可见可触发；
Mac-Chrome 浏览器（UA / platform / userAgentData 三重检测，排除 Edge/Opera/Samsung）也放行；
卡片 ✎ 编辑与明细页 GUI 编辑保持管理员门控。

5. 涉及文件

文件	作用
`static/js/kanban-editor.js`	表单渲染、字段映射、序列化、剪贴板、流程提示、Token 同步、浏览器检测
`templates/partials/kanban_editor.html`	编辑器模态框（列表页 / 明细页共用）
`templates/kanban_list.html`	新建看板按钮 + 卡片 ✎ 编辑 + 模态框
`templates/kanban.html`	明细页 GUI 编辑 + 模态框 + 脚本
`sass/kanban/style.scss`	编辑器样式
`content/kanban/_index.md`	注册 `js/kanban-editor.js`
`content/kanban/kanban-mapping.md`	GUI 编辑器文档

6. 验证

node --check 语法通过；
zola build 无错误；verify-kanban-build 通过（4 周看板完整）；
用真实 kanban-rules.js 做序列化往返测试：现有 4 个看板列/卡片/指令全部保持；新建模式全字段样例生成正确；校验边界（日期倒置、跨度 > 14 天、空列/空卡片）全部拦截；
Mac-Chrome 检测 7 种 UA 场景全部正确。

7. 后续计划

真实浏览器交互走查（解锁、弹窗、剪贴板权限）；
支持从 GUI 编辑器直接拖拽排序列 / 卡片；
编辑器表单的移动端布局优化；
历史看板一键“复制为本周模板“。

相关链接：映射说明 · 周计划列表

2026-08-11T04:00:00+00:00

2026年08月11日 12:00（东八区 / 北京时间）

文章页热力图：今日标记 · 35 天窗口 · 同日多文章弹层

概述

临近月中，集中将最近一个月的更新内容进行推送

本轮针对文章页（templates/article.html 右上角固定挂件）热力图做三项调整：

今日单元格醒目标记（GitHub 贡献图主流的蓝色描边环）；
时间窗口由默认 2 个月改为最后一个格子 = 今日、向前 35 天；
同日多篇文章交互：点击格子一次性展示当天全部文章，可手动选择任意一篇跳转。

构建流程（zola build / zola serve / ./dev.sh / ./build-site.sh）与 CI 均未改动。

1. 今日单元格醒目标记

采用 GitHub 贡献图的主流标记方式：今日格子外圈加 2px 实色描边环 + 半透明外晕，浅色模式 #0969da、深色模式 #4493f8；同时补充 aria-current="date" 与「今日」前缀的读屏标签。

项	值
类名	`.heatmap-day.is-today`
样式文件	`static/css/heatmap.css`
逻辑	`static/js/heatmap-init.js` `renderHeatmap()`
无障碍	`aria-current="date"` + `今日 yyyy-mm-dd：…`

该标记对归档页/看板页同样生效（今日格子在当年视图中也会显示描边环）。

2. 时间窗口：最后格子 = 今日，向前 35 天

原实现（文章模式）取「上个月 1 日 → 下个月末日」共 2 个自然月。现改为：

start = 今日 - 34 天
end   = 今日
共 35 个格子，最后一个格子始终是今日

实现要点：

点	说明
常量	`ARTICLE_DAYS = 35`，改数值即可调整跨度
范围	`getRange("article")` 返回 `[今日-34, 今日]`
未来格子	今日所在周内、今日之后的格子不再渲染（最后一个单元格 = 今日）
周对齐	仍按 GitHub 式“列=周“布局，首列可含窗口前空档，末列仅到今天
月份标签	以实际渲染的周列数重算 `--heatmap-weeks`，标签不错位

3. 同日多篇文章的交互

3.1 交互设计

状态	行为
单篇文章的日期	悬停显示标题 tooltip；点击直接跳转（原行为不变）
多篇文章的日期	悬停 tooltip 汇总「N 篇：标题1、标题2…」；点击弹出当天全部文章列表
弹层内	每篇一行（序号 + 标题），点击任意一行跳转对应文章
关闭方式	`Esc`、点击弹层外部、页面滚动、窗口缩放
无障碍	格子带 `aria-haspopup="dialog"` / `aria-expanded`；弹层带 `role="dialog"` 与日期+篇数标签

弹层默认显示在格子正上方，空间不足时自动翻转到下方（带箭头指示），水平方向自动防溢出。

3.2 实现

文件	改动
`static/js/heatmap-init.js`	`bindDayCell()` 分支处理；新增 `openDayPopover()` / `positionPopover()` / `closePopover()`
`static/css/heatmap.css`	新增 `.heatmap-popover` 系列样式与 `.heatmap-day.is-today` 标记
`templates/partials/heatmap_component.html`	无改动（数据本就包含当天全部文章）

4. 验证与部署

# 本地验证（改动 static/ 下的 JS/CSS 后 zola serve 会自动生效）
./dev.sh            # 或 zola serve
# 打开任意文章页（如 /01Write_blog_CMake/cmake-project-fix/）

检查点：

今日格子有蓝色描边环，深色/浅色主题各正确；
热力图最右侧一列 = 本周，本周内今日之后无格子；
找一个同日多篇文章的日期（如 2026-06-24），点击弹出列表并可跳转。

构建与部署流程不变：./build-site.sh 会把 static/ 原样拷贝进 public/。

词根 -duc-/-duct-（引导）考研高频词

2026-08-11T00:00:00+00:00

词根 -duc- / -duct-（引导）

-duc- / -duct- 来自拉丁语 ducere「引导、带领」。词族庞大，是阅读高频来源。

核心词族

单词	词性	释义	拆解
introduce	v.	引入、介绍	intro（向内）+ duce
conduct	v./n.	进行、实施；行为	con（共同）+ duct
reduce	v.	减少	re（回）+ duce
produce	v./n.	生产；农产品	pro（向前）+ duce
deduce	v.	推断、演绎	de（向下）+ duce
induce	v.	诱导、引起	in（向内）+ duce
educate	v.	教育	e（向外）+ duc + ate
product	n.	产品	pro + duct
productive	adj.	多产的、高效的	product + ive
conductor	n.	指挥、导体	conduct + or
duct	n.	管道	duct
seduce	v.	诱惑	se（分开）+ duce

考研高频短语

短语	释义	例句
conduct an experiment / survey	进行实验/调查	They conducted a survey of 2,000 people.
reduce … to …	减少到；使沦为	The problem can be reduced to a simple equation.
deduce … from …	从…推断出	We can deduce the truth from the evidence.
be induced to do sth	被诱导做某事	Consumers are induced to buy more.
introduce sth into	把…引入	The policy introduced reforms into the system.
productive capacity	生产能力	The factory is running at full productive capacity.
produce an effect	产生效果	The drug produced a noticeable effect.

真题语境例句

例句 1：The researchers conducted a series of experiments to test the hypothesis. 研究人员进行了一系列实验来验证假设。

例句 2：From these facts we can deduce that the economy is recovering. 从这些事实我们可以推断经济正在复苏。

例句 3：Advertising can induce people to consume beyond their needs. 广告能诱导人们超出需求地消费。

例句 4：A productive worker benefits both the company and society. 高效的工人对公司和社会的都有益。

词族扩展树

                 -duc-/-duct-（引导）
        ┌───────────┼───────────┬──────────────┐
    introduce   conduct    reduce       produce
    introduction conduction reduction   product
                  conductor  reducible  productive
     deduce（演绎）   induce（诱导）   educate（教育）
     deduction      induction     education
     deductive      inductive     educator
      seduce（诱惑） duct（管道）  aqueduct（引水渠）

记忆技巧

re + duce：往回带 → 减少；
pro + duce：向前带出来 → 生产；
con + duct：一起带着走 → 引导/进行；
de + duce：向下推导 → 演绎推断；
in + duce：往内带 → 诱导；
e + duc + ate：向外引导 → 教育（把潜力引导出来）。

上一篇：词根 -ject- ｜下一篇：词根 -pos-（放置）

词根 -fer-（携带）考研高频词

2026-08-11T00:00:00+00:00

词根 -fer-（携带）

-fer- 来自拉丁语 ferre「带、拿、承受」。派生词多且高频，是完形/阅读的常客。

核心词族

单词	词性	释义	拆解
offer	v./n.	提供、报价	of（向）+ fer
transfer	v./n.	转移、换乘	trans（越过）+ fer
refer	v.	提到、查阅、指代	re（回）+ fer
prefer	v.	更喜欢	pre（先）+ fer
infer	v.	推断	in（向内）+ fer
confer	v.	商议、授予	con（共同）+ fer
differ	v.	不同、有分歧	dif（分开）+ fer
suffer	v.	遭受、忍受	suf（在下）+ fer
defer	v.	推迟	de（下）+ fer
fertile	adj.	肥沃的、多产的	fer + tile
ferry	n./v.	渡船；摆渡	fer + ry
circumference	n.	周长	circum（周围）+ fer + ence

考研高频短语

短语	释义	例句
refer to	指的是；查阅	The term “GDP” refers to gross domestic product.
prefer A to B	比起 B 更喜欢 A	I prefer tea to coffee.
infer … from …	从…推断	We inferred the cause from the data.
transfer … to …	转移到	The patient was transferred to another hospital.
offer to do sth	主动提出做某事	He offered to help with the project.
differ from / in	与…不同 / 在…方面不同	The two versions differ in detail.
suffer from	遭受…之苦	Many people suffer from sleep loss.
confer a degree on sb	授予某人学位	The university conferred an honorary degree on him.
defer payment / decision	推迟付款/决定	The decision was deferred to next month.

真题语境例句

例句 1：The report refers to several studies published last year. 报告提到了去年发表的几项研究。

例句 2：Readers can infer the author’s attitude from the tone. 读者能从语气推断作者的态度。

例句 3：Remote workers transfer files through cloud services. 远程工作者通过云服务传输文件。

例句 4：Companies that offer flexible hours attract better talent. 提供弹性工时的公司能吸引更优秀的人才。

词族扩展树

                 -fer-（携带）
        ┌───────────┼───────────┬──────────────┐
      offer     transfer     refer      prefer
     offering   transferable reference  preference
                          referee     preferable
      infer（推断） confer（商议/授予） differ（不同）
      inference  conference       difference
      inferential conferral       different
     suffer（遭受） defer（推迟） fertile（多产的）
     suffering    deferral      fertilizer
     ferry（渡船） circumference（周长）

记忆技巧

of + fer：带到面前 → 提供；
trans + fer：从一边带到另一边 → 转移；
re + fer：带回去查 → 提及/查阅；
pre + fer：优先拿 → 更喜欢；
in + fer：往里带进结论 → 推断；
con + fer：把意见带到一起 → 商议；
dif + fer：分开带 → 不同；
suf + fer：在下面承受 → 遭受。

上一篇：词根 -tract-

词根 -ject-（投掷）考研高频词

2026-08-11T00:00:00+00:00

词根 -ject-（投掷）

-ject- 来自拉丁语 jacere「投、掷」。核心动词都带“抛向某处“的画面感。

核心词族

单词	词性	释义	拆解
project	n./v.	项目、工程；投射、计划	pro（向前）+ ject
inject	v.	注射、注入	in（向内）+ ject
reject	v.	拒绝、排斥	re（回）+ ject
eject	v.	弹出、逐出	e（向外）+ ject
subject	n./adj./v.	主题、学科；使遭受；受…支配的	sub（在下）+ ject
object	n./v.	物体、目标；反对	ob（相对）+ ject
objective	n./adj.	目标；客观的	object + ive
trajectory	n.	轨迹、弹道	tra（穿过）+ ject + ory
dejected	adj.	沮丧的	de（向下）+ ject + ed
conjecture	n./v.	推测、猜想	con（共同）+ ject

考研高频短语

短语	释义	例句
be subject to	受…支配；易遭受	Workers are subject to strict safety rules.
object to	反对	Many residents objected to the new plan.
be objective about	客观看待	We should be objective about the data.
inject capital into	向…注入资金	The government injected capital into the market.
reject an offer / proposal	拒绝提议	The committee rejected the proposal.
carry out a project	实施项目	The team carried out the project on time.
subject matter	主题内容	The subject matter is difficult to understand.

真题语境例句

例句 1：The new evidence subjected the theory to serious doubt. 新证据使该理论受到严重质疑。

例句 2：Many people object to the construction of the dam. 许多人反对修建大坝。

例句 3：The rocket’s trajectory was calculated precisely. 火箭的弹道被精确计算。

例句 4：Don’t conjecture without sufficient evidence. 没有充分证据不要臆测。

词族扩展树

                  -ject-（投掷）
        ┌──────────┼───────────┬─────────────┐
     project    inject     reject      eject
    projection  injection  rejection  ejection
    projector   injectable
     subject（主题/使遭受）
     object（物体/反对）
     objective（目标/客观的）
     trajectory（轨迹）
     dejected（沮丧的）
     conjecture（推测）

记忆技巧

pro + ject：向前抛 → 投射 → 项目（抛出的计划）；
re + ject：抛回去 → 拒绝；
in + ject：往里打 → 注射；
e + ject：往外抛 → 弹出；
sub + ject：抛在下面 → 受支配 → 主题（被谈论对象）。

上一篇：词根 -spect- ｜下一篇：词根 -duc-（引导）

词根 -pos-/-posit-（放置）考研高频词

2026-08-11T00:00:00+00:00

词根 -pos- / -posit-（放置）

-pos- / -posit- 来自拉丁语 ponere「放、置」。许多“位置/构成/提议“类单词都源于它。

核心词族

单词	词性	释义	拆解
position	n.	位置、职位	pos + ition
compose	v.	组成、创作	com（共同）+ pose
expose	v.	暴露、揭露	ex（向外）+ pose
propose	v.	提议、求婚	pro（向前）+ pose
impose	v.	强加、征税	im（向内）+ pose
oppose	v.	反对	op（相反）+ pose
deposit	v./n.	存放、存款；押金	de（向下）+ posit
postpone	v.	推迟	post（后）+ pone
dispose	v.	处理、处置	dis（分开）+ pose
supposed	adj.	假定的、被认为的	sup（下）+ pose + ed
positive	adj.	积极的、正的	posit + ive
opposite	adj./n.	相反的；对立面	op + pos + ite

考研高频短语

短语	释义	例句
be composed of	由…组成	Water is composed of hydrogen and oxygen.
be exposed to	暴露于；接触到	Children are exposed to too much screen time.
impose … on …	把…强加于	The law imposes heavy fines on polluters.
be opposed to	反对	Many experts are opposed to the plan.
be supposed to do	应该做	You are supposed to submit the report today.
dispose of	处理、清除	The company must dispose of waste safely.
put off / postpone	推迟（同义）	The meeting was postponed until Friday.
make a deposit	存款 / 交押金	He made a deposit of 1,000 yuan.

真题语境例句

例句 1：The committee proposed a series of measures to cut costs. 委员会提出了一系列削减成本的措施。

例句 2：New taxes were imposed on imported goods. 进口商品被征收了新税。

例句 3：The report exposed serious problems in the system. 报告揭露了系统中的严重问题。

例句 4：A positive attitude is essential for success. 积极的态度对成功至关重要。

词族扩展树

                 -pos-/-posit-（放置）
        ┌───────────┼───────────┬──────────────┐
     compose    expose     propose      impose
    composition exposure   proposal     imposition
    composer    exposed    proposer
     oppose（反对）   dispose（处理）  deposit（存放）
     opposite        disposal      depositor
     position（位置）  postpone（推迟） suppose（假定）
     positive（积极的）              supposed（假定的）

记忆技巧

com + pose：放在一起 → 组成；
ex + pose：放到外面 → 暴露；
pro + pose：摆到前面 → 提议；
im + pose：硬放上去 → 强加；
op + pose：反着放 → 反对；
post + pone：放到后面 → 推迟。

上一篇：词根 -duc- ｜下一篇：词根 -tract-（拉）

词根 -spect-（看）考研高频词

2026-08-11T00:00:00+00:00

词根 -spect-（看）

-spect- / -spic- 来自拉丁语 specere「看」。考研中高频出现，掌握一个词根 ≈ 一串单词。

核心词族

单词	词性	释义	拆解
inspect	v.	检查、视察	in（向内）+ spect
respect	n./v.	尊重、方面	re（再次）+ spect
prospect	n.	前景、展望	pro（向前）+ spect
expect	v.	期望、预料	ex（向外）+ pect
perspective	n.	视角、观点、透视	per（贯穿）+ spect
spectator	n.	观众	spect + ator（人）
retrospect	n./v.	回顾	retro（向后）+ spect
suspect	v./n.	怀疑、嫌疑犯	sus（下）+ pect
spectacle	n.	景象、奇观	spect + acle
conspicuous	adj.	显眼的、显著的	con + spic + uous
circumspect	adj.	谨慎周到的	circum（周围）+ spect

考研高频短语

短语	释义	例句
in respect of / with respect to	关于、就…而言	With respect to the environment, we should act now.
in retrospect	回想起来	In retrospect, the decision was too hasty.
from one’s perspective	从…的角度	From an economic perspective, the policy works.
live up to one’s expectations	不辜负期望	The product lived up to our expectations.
beyond expectation	出乎意料	The results were beyond expectation.
a prospective buyer / employee	潜在的买家/雇员	The house attracted many prospective buyers.
hold sb in high regard (respect)	高度尊重	He is held in high regard by his colleagues.

真题语境例句

例句 1：Government officials should inspect the quality of food products regularly. 政府官员应定期检查食品质量。

例句 2：From a long-term perspective, investing in education yields the highest return. 从长远角度看，投资教育回报最高。

例句 3：In retrospect, the company’s failure was predictable. 回想起来，公司的失败是可以预见的。

例句 4：The findings are conspicuous and cannot be ignored. 这些发现十分显著，不容忽视。

词族扩展树

                  -spect-（看）
        ┌──────────┼───────────┬─────────────┐
     inspect    respect    prospect     suspect
    inspection  respectful prospective  suspicion
    inspector   respectable             suspicious
                 irrespective
                 perspective（视角）
                 retrospect（回顾）
                 spectator（观众）
                 spectacle（奇观）
                 circumspect（谨慎）
                 conspicuous（显眼的）

记忆技巧

in + spect：向里看 → 检查；
re + spect：反复看 → 重视 → 尊重；
pro + spect：向前看 → 前景；
per + spect：贯穿地看 → 透视 → 视角；
sus + pect：在下面偷偷看 → 怀疑。

下一篇：词根 -ject-（投掷）

词根 -tract-（拉）考研高频词

2026-08-11T00:00:00+00:00

词根 -tract-（拉）

-tract- 来自拉丁语 trahere「拉、拖」。几乎所有派生词都能用“拉“的动作理解。

核心词族

单词	词性	释义	拆解
attract	v.	吸引	at（向）+ tract
extract	v./n.	提取、摘录	ex（向外）+ tract
contract	n./v.	合同；收缩；感染	con（共同）+ tract
distract	v.	分散（注意力）	dis（分开）+ tract
subtract	v.	减去	sub（下）+ tract
abstract	adj./n./v.	抽象的；摘要；提取	abs（离开）+ tract
retract	v.	撤回、缩回	re（回）+ tract
tractor	n.	拖拉机	tract + or（工具）
traction	n.	牵引力、摩擦力	tract + ion
intractable	adj.	难对付的	in（不）+ tract + able
protract	v.	延长	pro（向前）+ tract

考研高频短语

短语	释义	例句
attract attention / investment	吸引注意/投资	The project attracted wide attention.
extract … from …	从…提取	Scientists extracted DNA from the sample.
sign / enter into a contract	签订合同	The two firms entered into a contract.
be distracted by	被…分心	Students are easily distracted by phones.
in the abstract	抽象地、理论上	It sounds good in the abstract.
abstract thinking	抽象思维	Mathematics develops abstract thinking.
contract a disease	感染疾病	He contracted a rare disease.
subtract A from B	从 B 中减去 A	Subtract 5 from 8 and you get 3.

真题语境例句

例句 1：A good leader must attract and keep talented people. 优秀的领导者必须吸引并留住人才。

例句 2：The company extracted useful data from the survey. 公司从调查中提取了有用数据。

例句 3：Social media can distract students from their studies. 社交媒体会分散学生学习的注意力。

例句 4：Some problems remain intractable despite decades of research. 尽管研究了几十年，一些问题仍难以解决。

词族扩展树

                 -tract-（拉）
        ┌───────────┼───────────┬──────────────┐
     attract    extract    contract     distract
    attraction  extraction contraction  distraction
    attractive  extractor
     abstract（抽象的/摘要） subtract（减去）
     abstraction             subtraction
     retract（撤回） tractor（拖拉机）
     traction（牵引力） protract（延长）
     intractable（难对付的）

记忆技巧

at + tract：往这边拉 → 吸引；
ex + tract：向外拉 → 提取；
con + tract：拉在一起 → 收缩；拉到一起签的协议 → 合同；
dis + tract：把注意力拉散 → 分心；
sub + tract：往下拉掉 → 减去；
ab + stract：拉离具体 → 抽象。

上一篇：词根 -pos- ｜下一篇：词根 -fer-（携带）

高等数学 · 多元微积分（偏导 / 重积分 / 线面积分）

2026-08-11T00:00:00+00:00

高等数学 · 多元微积分

考研高数后半程：偏导 → 全微分 → 方向导数/梯度 → 极值 → 重积分 → 线面积分 → 三大公式。

1. 多元函数极限与连续

lim((x,y)→(x₀,y₀)) f(x,y) = A

判断极限不存在：取两条不同路径（如 y=kx、y=x²），极限不同则不存在。

2. 偏导数

fₓ(x₀,y₀) = lim(Δx→0) [f(x₀+Δx, y₀) − f(x₀,y₀)] / Δx
fᵧ(x₀,y₀) = lim(Δy→0) [f(x₀, y₀+Δy) − f(x₀,y₀)] / Δy

高阶偏导

fₓₓ、fₓᵧ、fᵧₓ、fᵧᵧ
若 fₓᵧ 与 fᵧₓ 连续 ⇒ 二者相等（混合偏导与次序无关）

隐函数偏导

F(x,y,z)=0 确定 z=z(x,y)：

∂z/∂x = −Fₓ/F_z，∂z/∂y = −Fᵧ/F_z

3. 全微分

dz = fₓ(x,y)·dx + fᵧ(x,y)·dy

可微 ⇒ 偏导存在；偏导连续 ⇒ 可微；可微 ⇒ 连续。

复合函数链式法则（中间变量法）：

z = f(u,v)，u=u(x,y)，v=v(x,y)
∂z/∂x = (∂z/∂u)(∂u/∂x) + (∂z/∂v)(∂v/∂x)

4. 方向导数与梯度

方向导数 ∂f/∂l = fₓ·cos α + fᵧ·cos β
梯度 grad f = (fₓ, fᵧ)

梯度方向是函数增长最快的方向，其模为方向导数最大值。

5. 多元函数极值

无条件极值（二阶偏导判别）

驻点 (x₀,y₀)：fₓ=fᵧ=0，记

A = fₓₓ，B = fₓᵧ，C = fᵧᵧ
AC − B² > 0 且 A < 0 ⇒ 极大；AC − B² > 0 且 A > 0 ⇒ 极小
AC − B² < 0 ⇒ 非极值（鞍点）；AC − B² = 0 ⇒ 需另判

条件极值（拉格朗日乘数法）

在 φ(x,y)=0 下求 f(x,y) 极值：
L(x,y,λ) = f(x,y) + λ·φ(x,y)
解 Lₓ=Lᵧ=L_λ=0

6. 二重积分

∬(D) f(x,y) dxdy

直角坐标

区域类型	积分次序
X 型	`∫(a..b) dx ∫(y₁(x)..y₂(x)) f dy`
Y 型	`∫(c..d) dy ∫(x₁(y)..x₂(y)) f dx`

极坐标

x = r·cos θ，y = r·sin θ，dxdy = r·drdθ

适合圆域、被积函数含 x²+y²。

对称性

D 关于 x 轴对称：f 关于 y 为奇 ⇒ 0；为偶 ⇒ 2 倍
D 关于 y=x 对称：∬f(x,y) = ∬f(y,x)

7. 三重积分

方法	适用	公式
先一后二（投影法）	一般区域	`∫∫ dxdy ∫(z₁..z₂) f dz`
先二后一（截面法）	旋转体	`∫(a..b) dz ∬(D_z) f dxdy`
柱坐标	旋转体	`x=r cosθ, y=r sinθ, z=z`，dv = r drdθdz
球坐标	球域	`x=r sinφ cosθ, …`，dv = r² sinφ drdφdθ

8. 曲线积分

第一类（对弧长）

∫(L) f(x,y) ds，参数化 x=x(t),y=y(t)：
ds = √(x'² + y'²) dt

与方向无关，物理意义：质量、弧长。

第二类（对坐标）

∫(L) P dx + Q dy = ∫ P·x'(t) dt + Q·y'(t) dt

与方向有关。

格林公式

∮(L⁺) P dx + Q dy = ∬(D) (∂Q/∂x − ∂P/∂y) dxdy

与路径无关 ⇔ ∂P/∂y = ∂Q/∂x ⇔ 存在势函数 u 使 du = P dx + Q dy。

9. 曲面积分

第一类（对面积）

∬(Σ) f dS = ∬(D) f(x,y,z(x,y))·√(1+zₓ²+zᵧ²) dxdy

第二类（对坐标）

∬(Σ) P dydz + Q dzdx + R dxdy，定向曲面，与侧有关

高斯公式（通量）

∯(Σ) P dydz + Q dzdx + R dxdy = ∭(Ω) (∂P/∂x + ∂Q/∂y + ∂R/∂z) dv

斯托克斯公式（环量）

∮(L) P dx + Q dy + R dz = ∬(Σ) rot F · n dS

10. 考研常考题型

二重积分换序 / 极坐标转换；
对称性化简重积分；
条件极值（拉格朗日）应用题；
格林公式补线（挖洞：奇点处小圆）；
高斯公式补面、方向（内侧/外侧）；
方向导数与梯度求最值方向。

例题速览

例 1：∬(D) (x²+y²) dxdy，D 为 x²+y² ≤ 1 第一象限。

极坐标：∫(0..π/2) dθ ∫(0..1) r²·r dr = (π/2)·(1/4) = π/8

例 2：求 f(x,y)=x²+y² 在 x+y=1 下的最小值。

L = x²+y² + λ(x+y−1)
2x+λ=0，2y+λ=0，x+y=1 ⇒ x=y=1/2
最小值 = 1/4 + 1/4 = 1/2

11. 易错点清单

混合偏导相等需先验证连续；
二重积分换序必画区域图；
极坐标别漏因子 r；
第二类曲线/曲面积分注意方向与侧；
格林/高斯公式使用前检查封闭性与奇点。

上一篇：一元微积分｜下一篇：线性代数

高等数学 · 一元微积分（积分学 + 微分方程）

2026-08-11T00:00:00+00:00

高等数学 · 一元微积分（积分学 + 微分方程）

考研高频板块：一元函数积分学 + 常微分方程。掌握 基本积分表 → 换元/分部 → 定积分工具 → 应用 的主线。

1. 原函数与不定积分

∫ f(x) dx = F(x) + C   （其中 F'(x) = f(x)）

性质：

∫ [f(x) ± g(x)] dx = ∫ f dx ± ∫ g dx
∫ k·f(x) dx = k·∫ f(x) dx
[∫ f(x) dx]' = f(x)

基本积分表（必背）

被积函数	积分
`x^μ`（μ≠−1）	`x^(μ+1)/(μ+1) + C`
`1/x`	`ln
`e^x`	`e^x + C`
`a^x`	`a^x/ln a + C`
`sin x`	`−cos x + C`
`cos x`	`sin x + C`
`sec²x`	`tan x + C`
`csc²x`	`−cot x + C`
`1/(1+x²)`	`arctan x + C`
`1/√(1−x²)`	`arcsin x + C`
`sec x·tan x`	`sec x + C`
`tan x`	`ln

2. 换元积分法

第一类换元（凑微分）

∫ f(φ(x))·φ'(x) dx = ∫ f(u) du，u = φ(x)

常见凑微分：

x dx = ½ d(x²)；1/x dx = d(ln x)；e^x dx = d(e^x)
cos x dx = d(sin x)；1/√(1−x²) dx = d(arcsin x)

第二类换元（去根号）

含根式	换元
`√(a²−x²)`	`x = a·sin t`
`√(a²+x²)`	`x = a·tan t`
`√(x²−a²)`	`x = a·sec t`
`√(ax+b)`	`t = √(ax+b)`

3. 分部积分法

∫ u dv = uv − ∫ v du

选择 u 的口诀（反对幂指三）：反三角函数 > 对数 > 幂函数 > 指数 > 三角，越靠前越优先当 u。

典型：

∫ x·e^x dx = x·e^x − e^x + C
∫ ln x dx = x·ln x − x + C
∫ x·sin x dx = −x·cos x + sin x + C

4. 有理函数积分

∫ P(x)/Q(x) dx：先真分式，再部分分式分解：
1/(x−a)(x−b) = A/(x−a) + B/(x−b)

常用技巧：分母配方 + 凑微分。

5. 定积分

定义（黎曼和）

∫(a..b) f(x) dx = lim(λ→0) Σ f(ξᵢ)·Δxᵢ

基本性质

∫(a..b) f dx = −∫(b..a) f dx
∫(a..b) [f±g] dx = ∫f dx ± ∫g dx
∫(a..b) f dx = ∫(a..c) f dx + ∫(c..b) f dx
f ≤ g ⇒ ∫f dx ≤ ∫g dx
|∫(a..b) f dx| ≤ ∫(a..b) |f| dx

积分中值定理

∃ξ∈[a,b]：∫(a..b) f(x) dx = f(ξ)·(b−a)

牛顿–莱布尼茨公式

F'(x) = f(x) ⇒ ∫(a..b) f(x) dx = F(b) − F(a)

变上限积分

Φ(x) = ∫(a..x) f(t) dt  ⇒  Φ'(x) = f(x)
[∫(a..φ(x)) f(t) dt]' = f(φ(x))·φ'(x)

常用对称性

f 为奇函数：∫(−a..a) f dx = 0
f 为偶函数：∫(−a..a) f dx = 2·∫(0..a) f dx

华里士（点火）公式

∫(0..π/2) sinⁿx dx = ∫(0..π/2) cosⁿx dx
  n 为奇数：(n−1)!!/n!!
  n 为偶数：(n−1)!!/n!! · π/2

6. 反常积分

类型	定义	收敛条件举例
无穷限	`∫(a..+∞) f dx = lim(b→+∞)∫(a..b) f dx`	`∫(1..∞) 1/x^p dx`：p>1 收敛，p≤1 发散
瑕积分	无界点处取极限	`∫(0..1) 1/x^p dx`：p<1 收敛，p≥1 发散

比较判别法 / 极限比较法：与 1/x^p 比较。

7. 定积分应用

应用	公式
平面面积	`A = ∫(a..b)
旋转体体积（绕 x 轴）	`V = π∫(a..b) [f(x)]² dx`
旋转体体积（柱壳）	`V = 2π∫(a..b) x·f(x) dx`
曲线弧长	`s = ∫(a..b) √(1+[f'(x)]²) dx`
旋转体侧面积	`S = 2π∫(a..b) f(x)·√(1+[f'(x)]²) dx`
变力做功 / 水压力	微元法：`dW = F(x) dx`

8. 常微分方程

一阶方程

类型	形式	解法
可分离变量	`dy/dx = f(x)·g(y)`	分离后两边积分
齐次方程	`dy/dx = φ(y/x)`	令 `u = y/x` 化为可分离
一阶线性	`y' + P(x)y = Q(x)`	公式：`y = e^(−∫P dx)·[∫Q·e^(∫P dx) dx + C]`
伯努利	`y' + P(x)y = Q(x)·yⁿ`	令 `z = y^(1−n)` 化为一阶线性

二阶常系数线性方程

y'' + p·y' + q·y = f(x)

齐次（f(x)=0）：特征方程 r² + pr + q = 0

特征根	通解
两不等实根 `r₁,r₂`	`C₁e^(r₁x) + C₂e^(r₂x)`
重根 `r`	`(C₁ + C₂x)·e^(rx)`
共轭复根 `α±βi`	`e^(αx)·(C₁cos βx + C₂sin βx)`

非齐次：通解 = 齐次通解 + 特解（待定系数法按 f(x) 类型设特解，含指数/多项式/三角）。

9. 考研常考题型

不定积分计算（换元 + 分部组合）；
对称区间定积分（奇偶性秒杀）；
变上限积分求导与极限；
反常积分判敛；
旋转体体积与面积；
一阶线性 / 二阶常系数方程求解（初值问题）；
积分中值定理与夹逼结合的极限题。

例题速览

例 1：∫(0..π) x·sin x dx

分部积分：= [−x·cos x](0..π) + ∫(0..π) cos x dx
        = (π) + 0 = π

例 2：解 y' + y/x = x²（一阶线性）

P = 1/x，∫P dx = ln x，e^(∫P dx) = x
y = x⁻¹·[∫x²·x dx + C] = x⁻¹·(x⁴/4 + C) = x³/4 + C/x

10. 易错点清单

不定积分别忘了 +C；
∫1/x dx = ln|x|（带绝对值）；
换元时注意积分上下限同步替换（定积分）；
分部积分 u、v 选错会越积越复杂；
二阶非齐次特解与齐次通解“撞根“时乘 x 或 x²。

上一篇：导数与微分｜下一篇：多元微积分

高等数学 · 导数与微分

2026-08-11T00:00:00+00:00

高等数学 · 导数与微分

考研高频板块：一元函数微分学。核心是 定义 + 公式 + 中值定理 + 应用 四件事。

1. 导数定义

函数 y = f(x) 在 x₀ 处的导数：

f'(x₀) = lim(Δx→0) [f(x₀+Δx) − f(x₀)] / Δx
       = lim(x→x₀) [f(x) − f(x₀)] / (x − x₀)

左导数 / 右导数

名称	定义	记号
左导数	`lim(x→x₀⁻) [f(x)−f(x₀)]/(x−x₀)`	`f'₋(x₀)`
右导数	`lim(x→x₀⁺) [f(x)−f(x₀)]/(x−x₀)`	`f'₊(x₀)`

可导 ⇔ 左导数 = 右导数。

可导与连续的关系

可导 ⇒ 连续；连续 ⇏ 可导（反例：y=|x| 在 x=0 连续但不可导）。

常用等价形式（求极限题）：

f'(x₀) = lim(h→0) [f(x₀+h) − f(x₀)] / h

2. 基本求导公式表（必背）

函数	导数	函数	导数
`C`（常数）	`0`	`x^μ`	`μ·x^(μ−1)`
`a^x`	`a^x·ln a`	`e^x`	`e^x`
`log_a x`	`1/(x·ln a)`	`ln x`	`1/x`
`sin x`	`cos x`	`cos x`	`−sin x`
`tan x`	`sec²x`	`cot x`	`−csc²x`
`sec x`	`sec x·tan x`	`csc x`	`−csc x·cot x`
`arcsin x`	`1/√(1−x²)`	`arccos x`	`−1/√(1−x²)`
`arctan x`	`1/(1+x²)`	`arccot x`	`−1/(1+x²)`

3. 求导法则

四则运算法则

(u ± v)' = u' ± v'
(uv)'    = u'v + uv'          （乘积）
(u/v)'   = (u'v − uv')/v²     （商，v ≠ 0）

复合函数求导（链式法则）

y = f(g(x))  ⇒  y' = f'(g(x)) · g'(x)

其他常用方法

方法	适用	要点
隐函数求导	`F(x,y)=0`	方程两边对 x 求导，把 y 看作 y(x)
参数方程求导	`x=φ(t), y=ψ(t)`	`dy/dx = ψ'(t)/φ'(t)`；二阶：`d²y/dx² = d(dy/dx)/dt ÷ dx/dt`
反函数求导	`x=f(y)`	`(f⁻¹)'(y) = 1/f'(x)`
对数求导法	幂指函数 / 多因子乘除	两边取 ln 再求导

幂指函数：y = u(x)^v(x) ⇒ ln y = v·ln u，再求导。

4. 高阶导数

莱布尼茨公式

(uv)^(n) = Σ(k=0..n) C(n,k) · u^(k) · v^(n−k)

常见高阶导数

函数	n 阶导数
`e^(ax)`	`aⁿ·e^(ax)`
`sin(ax+b)`	`aⁿ·sin(ax+b + nπ/2)`
`cos(ax+b)`	`aⁿ·cos(ax+b + nπ/2)`
`ln(1+x)`	`(−1)^(n−1)·(n−1)!/(1+x)ⁿ`
`1/(ax+b)`	`(−1)ⁿ·n!·aⁿ/(ax+b)^(n+1)`

5. 微分

dy = f'(x)·dx
Δy ≈ dy = f'(x₀)·Δx     （当 Δx → 0）

可微 ⇔ 可导（一元函数）。微分用于近似计算：f(x₀+Δx) ≈ f(x₀) + f'(x₀)·Δx。

6. 中值定理（三大定理 + 洛必达）

定理	条件	结论
罗尔 Rolle	[a,b] 连续、(a,b) 可导、f(a)=f(b)	∃ξ∈(a,b)：f’(ξ)=0
拉格朗日 Lagrange	[a,b] 连续、(a,b) 可导	∃ξ：f(b)−f(a)=f’(ξ)(b−a)
柯西 Cauchy	两函数满足罗尔条件且 g’(x)≠0	∃ξ：[f(b)−f(a)]/[g(b)−g(a)] = f’(ξ)/g’(ξ)

洛必达法则

0/0 或 ∞/∞ 型：lim f/g = lim f'/g'（满足条件时）。

其他未定式转化：0·∞ → 0/0、∞−∞ → 通分、1^∞ / 0⁰ / ∞⁰ → 取 ln。

7. 导数应用

单调性与极值

f'(x) > 0  ⇒  f 递增；f'(x) < 0  ⇒  f 递减
极值点：驻点（f'=0）或不可导点

凹凸性与拐点

f''(x) > 0  ⇒  凹（下凸）；f''(x) < 0  ⇒  凸（上凸）
拐点：f'' 变号处

渐近线

类型	条件	方程
水平	`lim f(x) = A`（x→∞）	`y = A`
垂直	`lim f(x) = ∞`（x→x₀）	`x = x₀`
斜	`lim f(x)/x = k`，`lim [f(x)−kx] = b`	`y = kx + b`

最值步骤

求驻点与不可导点；
比较端点、驻点、不可导点函数值；
取最大 / 最小。

8. 考研常考题型

用导数定义求极限（凑定义式）；
分段函数在分段点可导性讨论；
中值定理证明题（构造辅助函数：F(x)=f(x)−f(a)−...）；
不等式证明（拉格朗日中值 / 单调性）；
参数方程与隐函数二阶导；
极值、最值、拐点、渐近线的综合题。

例题速览

例 1：设 f(x)=x²sin(1/x) (x≠0)，f(0)=0，讨论 x=0 处可导性。

f'(0) = lim(h→0) [h²sin(1/h) − 0]/h = lim h·sin(1/h) = 0
⇒ 可导，且 f'(0)=0。

例 2：证明 e^x ≥ 1 + x（x∈R）。

令 F(x)=e^x − x − 1，F(0)=0，F'(x)=e^x−1。
x>0 时 F'>0 递增，x<0 时 F'<0 递减 ⇒ x=0 为最小值 ⇒ F(x)≥0。

9. 易错点清单

可导必连续，连续不一定可导（尖点）；
复合函数求导别漏内层；
隐函数二阶导要先求一阶导表达式再对 x 求导；
洛必达必须验证型别，且每次使用后检查是否仍为未定式；
极值点未必是驻点（不可导点也可以是极值点）。

下一篇：一元微积分（积分学 + 微分方程）

离散数学 · 核心章节

2026-08-11T00:00:00+00:00

离散数学 · 核心章节

计算机科学的基础数学：逻辑 → 集合 → 关系/函数 → 图论 → 代数系统 → 组合计数。

1. 数理逻辑

命题逻辑

联结词	记号	读法
否定	¬p	非 p
合取	p∧q	p 且 q
析取	p∨q	p 或 q
蕴含	p→q	若 p 则 q
等价	p↔q	p 当且仅当 q

注意：p→q 只有 p 真 q 假 时为假；p→q ≡ ¬p∨q。

等值式（常用）

双重否定：¬¬p ≡ p
德摩根：¬(p∧q) ≡ ¬p∨¬q；¬(p∨q) ≡ ¬p∧¬q
吸收律：p∨(p∧q) ≡ p
蕴涵等值式：p→q ≡ ¬p∨q

推理规则

假言推理（MP）：p→q，p ⇒ q
拒取式（MT）：p→q，¬q ⇒ ¬p
析取三段论：p∨q，¬p ⇒ q
假言三段论：p→q，q→r ⇒ p→r

谓词逻辑

∀x P(x)：全称量词；∃x P(x)：存在量词
¬∀x P(x) ≡ ∃x ¬P(x)；¬∃x P(x) ≡ ∀x ¬P(x)

2. 集合论

运算

并 A∪B；交 A∩B；差 A−B；补 ∁A
对称差 A⊕B = (A−B)∪(B−A)

恒等式

德摩根：∁(A∩B) = ∁A∪∁B；∁(A∪B) = ∁A∩∁B
A∪(B∩C) = (A∪B)∩(A∪C)（分配律）

基数

|A∪B| = |A|+|B|−|A∩B|
|A∪B∪C| = |A|+|B|+|C|−|A∩B|−|A∩C|−|B∩C|+|A∩B∩C|（容斥）

3. 关系

二元关系性质

性质	定义
自反	所有 x，(x,x)∈R
反自反	所有 x，(x,x)∉R
对称	(x,y)∈R ⇒ (y,x)∈R
反对称	(x,y)∈R 且 (y,x)∈R ⇒ x=y
传递	(x,y),(y,z)∈R ⇒ (x,z)∈R

等价关系与划分

自反 + 对称 + 传递 = 等价关系
等价类 [x] = {y | xRy}；等价类集合构成集合的划分

偏序关系

自反 + 反对称 + 传递 = 偏序（≤）
哈斯图（Hasse 图）画法：去掉自反环与传递边
极大/极小元、最大/最小元、上/下界、上/下确界

关系闭包

自反闭包 r(R) = R ∪ E
对称闭包 s(R) = R ∪ R⁻¹
传递闭包 t(R) = R ∪ R² ∪ R³ ∪ …（Warshall 算法）

4. 函数

f: A → B
单射（一一）：不同自变量 → 不同函数值
满射（到上）：值域 = B
双射：既单又满

鸽巢原理：n+1 个物体放入 n 个盒子，至少一个盒子 ≥ 2 个。

5. 图论

基本概念

G = (V, E)；无向图 / 有向图
握手定理：Σdeg(v) = 2|E|（无向）
有向图：Σdeg⁺ = Σdeg⁻ = |E|

特殊图

图	判定
完全图 Kₙ	n(n−1)/2 条边
二部图	顶点可二分，边只跨部（无奇圈）
欧拉图	所有顶点度数为偶（有向：出入相等）
哈密顿图	必要条件（割点/度条件），充分条件 Dirac：`deg ≥ n/2`

树

n 个顶点的树：n−1 条边，连通无圈
生成树：连通图包含全部顶点的树
最小生成树：Prim（加点）/ Kruskal（加边，并查集判环）

平面图

欧拉公式：V − E + F = 2（连通平面图）
K₅ 与 K₃,₃ 是非平面图

图着色

四色定理：平面图 4 色足够
图着色 = 相邻顶点不同色，最少色数 χ(G)

6. 代数系统

系统	公理	例子
半群	封闭 + 结合	(N,+)
独异点	半群 + 单位元	(N,·)
群	独异点 + 逆元	(Z,+)、(Zₙ,+)
阿贝尔群	群 + 交换	(Z,+)
环	(R,+) 阿贝尔群 + 乘法结合/分配	(Z,+,·)
域	环 + 乘法可逆（除零外）	(R,+,·)、(Zₚ,+,·) p 素数

拉格朗日定理：有限群中子群的阶整除群的阶。

7. 组合计数

排列与组合

P(n,r) = n!/(n−r)!
C(n,r) = n!/[r!(n−r)!]

常用恒等式

C(n,r) = C(n, n−r)
C(n+1,r) = C(n,r) + C(n,r−1)（帕斯卡）
Σ C(n,k) = 2ⁿ

计数技巧

隔板法：n 个相同物分 k 组非空：C(n−1, k−1)；
错排数：Dₙ = n!·Σ(−1)^k/k!，如 D₃=2, D₄=9；
生成函数 / 母函数处理受限组合。

8. 考研 / 机试常考题型

命题公式等值演算与主范式；
关系性质判断、等价类与划分；
哈斯图与偏序元；
图论：握手定理、欧拉/哈密顿判定、着色；
最小生成树（Prim/Kruskal）与最短路（Dijkstra/Floyd）；
群判定与子群；
排列组合与容斥、错排。

例题速览

例 1：证明 (p→q) ∧ p ⇒ q（假言推理）：

p→q ≡ ¬p∨q；(¬p∨q)∧p ≡ q∧p ⇒ q

例 2：K₅ 的边数：

5·4/2 = 10

例 3：4 封信全装错信封的方法数：

D₄ = 4!·(1 − 1 + 1/2 − 1/6 + 1/24) = 9

9. 易错点清单

蕴含联结词 → 与日常“因果“含义不同；
自反/反自反、对称/反对称不互斥；
握手定理两边都算；
欧拉图关注“一笔画“，哈密顿关注“回路遍历所有顶点“；
群必须封闭、结合、有单位元、有逆元四条件齐备；
错排与隔板法别套错模型。

上一篇：概率论

线性代数 · 核心章节

2026-08-11T00:00:00+00:00

线性代数 · 核心章节

线代脉络：行列式 → 矩阵 → 向量组 → 方程组 → 特征值 → 二次型，前四章是后两章的工具。

1. 行列式

定义与性质

det(A) = Σ σ(p) a₁p₁ a₂p₂ … aₙpₙ

核心性质：

|Aᵀ| = |A|
两行（列）互换，行列式变号；
某行乘以 k，行列式乘以 k；
两行成比例 ⇒ 行列式为 0；
某行加另一行的 k 倍，值不变；
|AB| = |A|·|B|；|A⁻¹| = 1/|A|；|kA| = kⁿ|A|

展开定理（代数余子式）

按第 i 行展开：|A| = Σ(j) aᵢⱼ·Aᵢⱼ

特殊行列式

类型	结果
上/下三角	主对角线乘积
对角	对角线乘积
范德蒙德	∏(xⱼ−xᵢ)（i<j）
副对角	`(−1)^(n(n−1)/2)·∏aᵢ,ₙ₋ᵢ₊₁`

克拉默法则

Ax=b 且 |A|≠0 时：xᵢ = |Aᵢ|/|A|（Aᵢ 为替换第 i 列）。

2. 矩阵

运算

(AB)C = A(BC)；A(B+C) = AB + AC
(AB)ᵀ = BᵀAᵀ；(A+B)ᵀ = Aᵀ+Bᵀ
|AB| = |A||B|

逆矩阵

A⁻¹ 存在 ⇔ |A| ≠ 0 ⇔ A 可逆 ⇔ r(A) = n
A⁻¹ = A*/|A|（伴随矩阵法）
(AB)⁻¹ = B⁻¹A⁻¹；(Aᵀ)⁻¹ = (A⁻¹)ᵀ

常用公式：A·A* = |A|E ⇒ A* = |A|A⁻¹。

初等变换与初等矩阵

初等行变换不改变秩；初等矩阵左乘 = 行变换，右乘 = 列变换。

秩

r(A)：非零子式的最高阶数
r(A) ≤ min(m,n)；r(A+B) ≤ r(A)+r(B)
r(AB) ≤ min(r(A), r(B))；r(A)+r(B) − n ≤ r(AB)
r(A)=r(Aᵀ)；r(kA)=r(A)（k≠0）

3. 向量组

线性相关 / 无关

α₁,…,αₛ 线性相关 ⇔ 存在不全为 0 的 kᵢ 使 Σ kᵢαᵢ = 0
无关 ⇔ 只有全 0 系数成立

判定：

s > n（n 维向量）必相关；
含零向量 ⇒ 相关；
部分相关 ⇒ 整体相关；整体无关 ⇒ 部分无关；
等价向量组秩相同。

秩与极大无关组

秩 = 极大线性无关组中向量个数
向量组秩 ≤ 矩阵秩，且 r(α₁,…,αₛ) = r(矩阵)

4. 线性方程组

Ax = b（m×n）

解的存在性

条件	结论
`r(A) < r(A	b)`
`r(A) = r(A	b) = n`
`r(A) = r(A	b) = r < n`

齐次 Ax=0：非零解 ⇔ r(A) < n ⇔ |A|=0（方阵）。

解的结构

非齐次通解 = 齐次通解 + 一个特解
齐次通解 = C₁ξ₁ + … + Cₙ₋ᵣξₙ₋ᵣ（基础解系）

5. 特征值与特征向量

Ax = λx（x ≠ 0）
特征多项式：|λE − A| = 0

重要性质

Σλᵢ = tr(A)（迹）
∏λᵢ = |A|
不同特征值对应的特征向量线性无关
A⁻¹ 特征值 1/λ；Aᵀ 与 A 特征值相同；A^k 特征值 λ^k

相似对角化

A ~ Λ ⇔ A 有 n 个线性无关特征向量 ⇔ 每个 k 重特征值对应 k 个线性无关特征向量
P⁻¹AP = diag(λ₁,…,λₙ)，P 的列 = 特征向量
Aⁿ = P·Λⁿ·P⁻¹

6. 二次型

f = xᵀAx（A 对称）

标准形与规范形

配方法 / 正交变换法化标准形；
规范形：系数只有 1, −1, 0；
惯性定理：正、负惯性指数唯一；
合同：CᵀAC = B（C 可逆）⇔ 正负惯性指数相同。

正定判定

方法	条件
特征值	全为正
顺序主子式	全大于 0
定义	`∀x≠0：xᵀAx > 0`

7. 考研常考题型

行列式性质与抽象行列式计算；
求逆、伴随矩阵、A* 与 A 的关系；
秩的不等式；
向量组相关性的参数讨论；
含参数方程组的解判定与通解；
特征值特征向量、相似对角化、Aⁿ；
二次型化标准形、正定判断。

例题速览

例 1：已知 A 三阶，|A|=2，求 |3A⁻¹|。

|3A⁻¹| = 3³·|A⁻¹| = 27·(1/2) = 27/2

例 2：A 特征值 1, 2, 3，求 |A²+A+E|。

A 的特征多项式作用于 A：g(λ) = λ²+λ+1
|g(A)| = g(1)·g(2)·g(3) = 3·7·13 = 273

8. 易错点清单

(AB)ᵀ = BᵀAᵀ 次序互换；
|kA| = kⁿ|A| 不是 k|A|；
矩阵乘法不满足交换律；
AB=0 推不出 A=0 或 B=0；
相似（存在可逆 P）与合同（对称阵）别混淆；
特征向量必须非零。

上一篇：多元微积分｜下一篇：概率论

概率论 · 核心章节

2026-08-11T00:00:00+00:00

概率论 · 核心章节

概率主线：事件概率 → 随机变量分布 → 数字特征 → 极限定理 → 数理统计。

1. 随机事件与概率

概率公理

0 ≤ P(A) ≤ 1；P(Ω)=1；互斥可加

古典概型

P(A) = A 包含的基本事件数 / 总基本事件数（等可能）

条件概率与公式

P(A|B) = P(AB)/P(B)
乘法公式：P(AB) = P(A|B)·P(B)
全概率公式：P(B) = Σ P(B|Aᵢ)·P(Aᵢ)（Aᵢ 完备划分）
贝叶斯公式：P(Aᵢ|B) = P(B|Aᵢ)P(Aᵢ) / Σ P(B|Aⱼ)P(Aⱼ)

独立

P(AB) = P(A)·P(B) ⇔ A、B 独立

互斥 ≠ 独立（互斥通常不独立，除非概率为 0）。

2. 一维随机变量

分布函数

F(x) = P(X ≤ x)
性质：单调不减、右连续、F(−∞)=0、F(+∞)=1
P(a < X ≤ b) = F(b) − F(a)

离散型：常见分布

分布	参数	P(X=k)	期望	方差
0-1	p	p^k(1−p)^(1−k)	p	p(1−p)
二项 B(n,p)	n,p	C(n,k)p^k(1−p)^(n−k)	np	np(1−p)
泊松 P(λ)	λ	λ^k e^(−λ)/k!	λ	λ
几何	p	(1−p)^(k−1)p	1/p	(1−p)/p²

连续型：常见分布

分布	密度	期望	方差
均匀 U(a,b)	1/(b−a)	(a+b)/2	(b−a)²/12
指数 E(λ)	λe^(−λx) (x≥0)	1/λ	1/λ²
正态 N(μ,σ²)	1/(σ√2π)·e^(−(x−μ)²/2σ²)	μ	σ²

正态标准化：Z = (X−μ)/σ ~ N(0,1)。

指数分布无记忆性：P(X>s+t | X>s) = P(X>t)。

3. 二维随机变量

联合 / 边缘 / 条件

边缘分布：fₓ(x) = ∫ f(x,y) dy
条件密度：f(y|x) = f(x,y)/fₓ(x)
X、Y 独立 ⇔ f(x,y) = fₓ(x)·fᵧ(y)（连续型）

随机变量函数分布

离散和分布：卷积公式；
Z = X+Y（连续独立）：f_z(z) = ∫ fₓ(x)·fᵧ(z−x) dx；
正态可加性：独立正态之和仍正态；
max(X,Y) / min(X,Y) 分布函数法。

4. 数字特征

期望

离散：E(X) = Σ xᵢpᵢ
连续：E(X) = ∫ x·f(x) dx
性质：E(aX+bY+c) = aE(X)+bE(Y)+c（线性）

方差

D(X) = E(X²) − [E(X)]²
D(aX+b) = a²D(X)
X、Y 独立：D(X±Y) = D(X)+D(Y)

协方差与相关系数

Cov(X,Y) = E(XY) − E(X)E(Y)
ρ = Cov(X,Y) / (√D(X)·√D(Y))，|ρ| ≤ 1
ρ = 0 ⇔ 不相关（独立 ⇒ 不相关，反之不一定）

矩

k 阶原点矩：E(X^k)；k 阶中心矩：E[(X−E(X))^k]

5. 大数定律与中心极限定理

定理	条件	结论
切比雪夫不等式	存在 E(X)、D(X)	`P(
辛钦大数定律	独立同分布，E(X)=μ	样本均值依概率收敛于 μ
伯努利大数定律	n 次独立重复	频率依概率收敛于 p
独立同分布中心极限定理	方差有限	`(ΣXᵢ − nμ)/(σ√n) → N(0,1)`
棣莫弗–拉普拉斯	二项 B(n,p)	二项近似正态 N(np, npq)

6. 数理统计基础

统计量与抽样分布

样本均值 X̄ = (1/n)ΣXᵢ；样本方差 S² = 1/(n−1)·Σ(Xᵢ−X̄)²
总体 N(μ,σ²)：X̄ ~ N(μ, σ²/n)
χ² 分布：Σ[(Xᵢ−μ)/σ]² ~ χ²(n)
t 分布：(X̄−μ)/(S/√n) ~ t(n−1)
F 分布：两独立 χ² 之比

参数估计

矩估计：用样本矩估计总体矩；
最大似然估计：构造似然函数 L(θ)=∏f(xᵢ;θ)，取对数求导令 0；
无偏性：E(θ̂)=θ；有效性：方差小者优；一致性：依概率收敛。

假设检验（了解）

原假设 H₀ / 备择 H₁，显著性水平 α
拒绝域：|z| > z_(α/2)（正态总体均值双侧检验）
两类错误：拒真（α）与取伪（β）

7. 考研常考题型

全概率 / 贝叶斯应用题；
分布函数与密度互求、分段讨论；
二维联合分布求边缘、条件、独立性；
期望方差计算（用性质拆解）；
切比雪夫不等式估概率；
中心极限定理近似计算（二项/独立同分布）；
矩估计与最大似然估计。

例题速览

例 1：X ~ N(2, 4)，求 P(|X−2| < 2)。

P(|X−2| < 2) = P(|Z| < 1) = 2Φ(1) − 1 ≈ 0.6826

例 2：X ~ U(0,1)，求 E(X²)。

E(X²) = ∫(0..1) x² dx = 1/3

8. 易错点清单

独立 ⇒ 不相关，不相关 ⇏ 独立（正态联合除外）；
方差无线性可加（需独立）；
D(X) = E(X²) − [E(X)]² 别算错 E(X²)；
指数分布无记忆性常考；
矩估计 vs 最大似然估计方法别混；
样本方差分母是 n−1。

上一篇：线性代数｜下一篇：离散数学

考研 408 · 图核心知识点

2026-08-11T00:00:00+00:00

考研 408 · 图核心知识点

图是 408 大题最爱：存储 → 遍历 → 生成树 → 最短路 → 拓扑/关键路径。

1. 图的存储

邻接矩阵

      1   2   3   4
1  [  0   1   1   0 ]
2  [  1   0   1   1 ]
3  [  1   1   0   1 ]
4  [  0   1   1   0 ]

无向图对称；有向图按出边填写。判断两点是否相邻 O(1)，求度方便；但空间 O(n²)。

邻接表

1 → 2 → 3
2 → 1 → 3 → 4
3 → 1 → 2 → 4
4 → 2 → 3

空间 O(n+e)，适合稀疏图；求某点出度方便，判断相邻需扫描。

存储	空间	判断相邻	求所有邻点
邻接矩阵	O(n²)	O(1)	O(n)
邻接表	O(n+e)	O(degree)	O(degree)

2. 遍历

DFS（深度优先，用栈/递归）

访问顶点 → 递归访问第一个未访问邻点 → 回溯

BFS（广度优先，用队列）

访问顶点 → 邻点全部入队 → 逐个出队重复

复杂度：邻接表 O(n+e)，邻接矩阵 O(n²)。

BFS 还能求无权图最短路径（边数）、判断连通分量数。

3. 最小生成树 MST

Prim（加点）

从一个顶点出发，每次选择"连接已选集合与未选集合的最短边"加入集合，直到覆盖全部顶点。
复杂度：邻接矩阵 O(n²)；适合稠密图。

Kruskal（加边）

边按权排序，从小到大选边，用并查集避免成环，选 n−1 条为止。
复杂度：O(e·log e)；适合稀疏图。

示例

    1 --2-- 2
    |  \    |
    2    4  3
    |    \  |
    3 --1-- 4

按 Kruskal：先取 3-4(1)、1-2(2)、1-3(2)（跳过 2-4(3)） ⇒ MST 总权 5

4. 最短路径

Dijkstra（单源，非负权）

维护 dist[]，每次取未确定顶点中 dist 最小者，松弛其邻边。
复杂度：邻接矩阵 O(n²)；堆优化 O((n+e)log n)。
不能处理负权边。

Floyd（多源）

三重循环：d[i][j] = min(d[i][j], d[i][k] + d[k][j])
复杂度 O(n³)；可处理负权（无负环）。

示例（Dijkstra 从 1 出发）

      2
  1 ───── 3
  | 1   1 |
  2 ───── 4
      3

dist: 1→1=0, 1→2=1, 1→3=2, 1→4=3（经 3）

5. 拓扑排序（AOV 网）

无环有向图，顶点表示活动。
反复：选入度为 0 的顶点输出，删除其出边，直到全部输出。
若剩余顶点仍有入度 ⇒ 存在环。
复杂度：邻接表 O(n+e)。

示例

课程依赖：A→C, B→C, C→D
拓扑序之一：A B C D（不唯一）

6. 关键路径（AOE 网）

顶点 = 事件，边 = 活动（带权=耗时）
ve(最早发生) 正向取 max；vl(最迟发生) 逆向取 min
活动最早 e = ve(弧尾)；活动最迟 l = vl(弧头) − 权
e == l 的活动为关键活动，串联成关键路径
关键路径长度 = 工程最短工期

示例

   v1 ─2─▶ v2 ─3─▶ v4
     \            ▲
      4 ────────▶ 3
ve: v1=0, v2=2, v4=5, v3=4
vl: v1=0, v2=2, v4=5, v3=2（逆向）
关键活动：v1→v2(2), v2→v4(3)，关键路径长 5

7. 常考题型

画邻接矩阵/邻接表；
给图写 DFS/BFS 序列；
Prim/Kruskal 过程与总权；
Dijkstra/Floyd 逐步表；
拓扑排序与环检测；
求 ve/vl/e/l 与关键路径；
判断有向图强连通、无向图连通分量。

8. 易错点

Dijkstra 不适用负权，Floyd 可；
MST 不含权值相等的唯一性讨论（可能不唯一）；
拓扑排序不唯一；
关键路径可能不止一条；
BFS 求最短路只对无权图。

上一篇：树｜下一篇：排序

考研 408 · 排序核心知识点

2026-08-11T00:00:00+00:00

考研 408 · 排序核心知识点

排序是 408 高频选择题 + 偶尔大题：背总表、会手推过程、能判断稳定性。

1. 总表（必背）

算法	类别	最好	平均	最坏	空间	稳定
直接插入	插入	O(n)	O(n²)	O(n²)	O(1)	✅
希尔	插入	O(n^1.3)	—	O(n²)	O(1)	❌
冒泡	交换	O(n)	O(n²)	O(n²)	O(1)	✅
快速排序	交换	O(n log n)	O(n log n)	O(n²)	O(log n)	❌
简单选择	选择	O(n²)	O(n²)	O(n²)	O(1)	❌
堆排序	选择	O(n log n)	O(n log n)	O(n log n)	O(1)	❌
归并排序	归并	O(n log n)	O(n log n)	O(n log n)	O(n)	✅
基数排序	分配	O(d(n+r))	O(d(n+r))	O(d(n+r))	O(r)	✅

记忆点：稳定的只有直接插入 / 冒泡 / 归并 / 基数；快排最坏 O(n²)；归并空间 O(n)。

2. 插入类

直接插入

初始: [3] 1 4 2
第1趟: [1 3] 4 2
第2趟: [1 3 4] 2
第3趟: [1 2 3 4]

思想：把待排元素插入已有序前缀的合适位置。

希尔排序

按增量 d 分组做直接插入，增量逐步缩小到 1（最后一次就是直接插入）。
例：d=2 时分成奇偶两组分别插入排序。

3. 交换类

冒泡

第1趟: 3 1 4 2 → 1 3 2 [4]（4 冒到末尾）
第2趟: 1 3 2 → 1 2 [3] 4
第3趟: 1 [2] 3 4

无交换可提前结束，最好 O(n)。

快速排序（分治）

选基准（通常首元素）→ 一趟划分：左小右大 → 递归两侧
例 [4 2 5 1 3] 以 4 为基准一趟后：[1 2 3] 4 [5]

int partition(int a[], int low, int high) {
    int pivot = a[low];
    while (low < high) {
        while (low < high && a[high] >= pivot) high--;
        a[low] = a[high];
        while (low < high && a[low] <= pivot) low++;
        a[high] = a[low];
    }
    a[low] = pivot;
    return low;
}

快排平均 O(n log n)；若每次划分极不平衡（已有序）最坏 O(n²)。

4. 选择类

简单选择

每趟选剩余最小元素与当前位置交换：
[1] 3 4 2 → 1 [2] 4 3 → 1 2 [3] 4

比较次数固定 n(n−1)/2，与初始状态无关。

堆排序

建大根堆 → 堆顶与末尾交换 → 下沉调整
[4 3 2 1] 交换 1： [1 3 2] 4 → 下沉 → [3 1 2] 4 → 交换 → [2 1] 3 4 → ...

大根堆：parent ≥ children；调整（sift down）O(log n)
建堆 O(n)；排序 O(n log n)

5. 归并排序（二路）

分：数组二分到底；治：两两有序合并
[4 2 5 1] → [4 2][5 1] → [2 4][1 5] → [1 2 4 5]

void merge(int a[], int low, int mid, int high) {
    // 复制到临时数组，双指针比较归并
}
void mergeSort(int a[], int low, int high) {
    if (low < high) {
        int mid = (low + high) / 2;
        mergeSort(a, low, mid);
        mergeSort(a, mid + 1, high);
        merge(a, low, mid, high);
    }
}

稳定、O(n log n)、空间 O(n)；适合外部排序基础。

6. 基数排序

按"位"分配-收集：个位 → 十位 → 百位…
例 [12, 3, 45]：
  个位收集：3(03) 12 45 → 十位收集：3 12 45
复杂度 O(d(n+r))，d 位数、r 基数（十进制 10）

7. 408 高频结论

考点	结论
快排最坏	基本有序时退化 O(n²)
稳定性判断	相邻交换类（冒泡/插入）稳定；跳跃交换不稳定
比较次数与初始无关	简单选择、折半插入、基数
一趟排序后能确定位置	快排基准、选择类每趟定一个
与初始状态有关	插入/冒泡/快排（趟数）；选择/归并/基数无关
n 较小 / 基本有序	直接插入最佳

8. 外部排序（了解）

归并段（run）→ 败者树多路归并 → 置换选择排序生成更长段
总代价 ≈ 内部归并 + I/O 次数；I/O 次数 = 2×趟数×块数
增加归并路数、减少初始段数可减少 I/O

9. 例题速览

例 1：[1, 3, 2, 5, 4] 用直接插入排序第 2 趟结果。

第1趟: [1 3] 2 5 4
第2趟: [1 2 3] 5 4

例 2：下列哪个排序是稳定的？直接插入 / 快排 / 堆排 / 希尔。

答案：直接插入

上一篇：图

考研 408 · 字符串核心知识点

2026-08-11T00:00:00+00:00

考研 408 · 字符串核心知识点

408 中字符串以 模式匹配（朴素 / KMP） 为绝对重点，配合字符串存储与基本操作。

1. 字符串的存储

顺序存储：char s[MAXLEN]，用 '\0' 或 length 记录长度
堆分配：char* s，长度动态管理
块链存储：链表每个结点存多个字符（块），省指针空间

408 约定：字符数组下标常从 1 开始（s[1..n]），便于 next 数组推导；下标 0 存长度或不用。

2. 朴素模式匹配（BF）

主串 s（长 n）、模式串 p（长 m）：

从主串每个位置 i 起，与 p 逐位比较；
失配则 i 回退到 i+1，j 回到 1，继续。

时间复杂度：最坏 O(n·m)；平均 O(n+m)。

图示

主串: a b a b c a b
模式: a b c

第 1 趟: a b a  失配于 c vs a → 主串从第 2 位再来
第 2 趟:   a b a
第 3 趟:     a b c ✓ 匹配成功，位置 3

3. KMP 算法

核心思想

失配时主串不回溯，模式串沿 next 数组滑动，把已匹配前缀的信息利用起来。

int KMP(const char s[], const char p[]) {
    int i = 1, j = 1;
    while (i <= s[0] && j <= p[0]) {
        if (j == 0 || s[i] == p[j]) { i++; j++; }
        else j = next[j];
    }
    if (j > p[0]) return i - p[0];  // 匹配位置
    return 0;
}

next 数组定义（next[1] = 0）

next[j] = 模式串 p[1..j-1] 中"最长相等前后缀长度 + 1"
失配时 j = next[j] 再比。

求解 next（递推）

void getNext(const char p[], int next[]) {
    int j = 1, k = 0;
    next[1] = 0;
    while (j < p[0]) {
        if (k == 0 || p[j] == p[k]) {
            j++; k++; next[j] = k;
        } else {
            k = next[k];
        }
    }
}

图示（p = a b a b a a）

j   : 1  2  3  4  5  6  7
p   : a  b  a  b  a  a  -
next: 0  1  1  2  3  4  2

例：j=5 时 p[1..4] = a b a b，最长相等前后缀 "ab" 长 2 ⇒ next[5] = 3

nextval（优化 next）

若 p[j] == p[next[j]]，则 nextval[j] = nextval[next[j]]，进一步跳过相同字符比较。

时间复杂度：O(n+m)；空间 O(m)。

4. 常用题型

题型	解法要点
求 next / nextval 数组	手算“最长相等前后缀“
主串定位	KMP 主循环 + next
循环节问题	周期 = m − next[m]（若整除）
字符串相等判断	长度 + 逐位比较
模式串滑动次数	每趟失配后 j=next[j] 计数

5. 例题速览

例 1：主串 ababcabcacbab，模式 abcac，求 next 数组并用 KMP 找首次匹配。

p   : a b c a c
next: 0 1 1 1 2
比较过程：
  a b a b c a b c a c a b
  a b c        失配(c vs a) → j = next[3] = 1
    a b c a c  匹配成功，位置 6

例 2：next[7] 语义 = 当第 7 位失配时，模式串从第 next[7] 位继续比较。

6. 易错点

next 数组下标从 1 开始、next[1]=0；
前缀/后缀都是真子串（不含自身）；
KMP 主串指针只增不减；
朴素匹配最坏情况如 s=aaaaab, p=aaab。

下一篇：树

考研 408 · 树核心知识点

2026-08-11T00:00:00+00:00

考研 408 · 树核心知识点

树是 408 数据结构大题高发区：性质 → 遍历 → BST/AVL → 哈夫曼 → 并查集。

1. 二叉树基本性质

① 第 i 层至多 2^(i−1) 个结点
② 深度为 k 的二叉树至多 2^k − 1 个结点
③ 叶子数 n₀ = 度为 2 结点数 n₂ + 1
④ 完全二叉树 n 个结点：深度 = ⌊log₂n⌋ + 1
⑤ 顺序存储（完全二叉树）：i 的左孩子 2i、右孩子 2i+1、父 ⌊i/2⌋

二叉树的形态数

n 个结点的不同二叉树形态数 = 卡特兰数 C(n) = C(2n,n)/(n+1)

2. 遍历

递归序（先/中/后）

先序：根 → 左 → 右     DLR
中序：左 → 根 → 右     LDR
后序：左 → 右 → 根     LRD
层序：逐层从左到右

图示

          1
         / \
        2   3
       / \   \
      4   5   6

先序: 1 2 4 5 3 6
中序: 4 2 5 1 3 6
后序: 4 5 2 6 3 1
层序: 1 2 3 4 5 6

由遍历序列确定二叉树

必须知道中序 + （先序 或 后序 之一）
先序/后序确定根，中序划分左右子树
层序 + 中序亦可

非递归遍历要点

// 先序非递归：栈
push(root);
while (!stack.empty()) {
    node = pop(); visit(node);
    if (node->right) push(node->right);
    if (node->left)  push(node->left);
}
// 层序：队列
enqueue(root);
while (!queue.empty()) {
    node = dequeue(); visit(node);
    if (node->left)  enqueue(node->left);
    if (node->right) enqueue(node->right);
}

3. 线索二叉树

利用空指针域：
ltag = 0 左孩子 / 1 前驱；rtag = 0 右孩子 / 1 后继

中序线索化后，可快速找某结点的中序前驱/后继，遍历不需要栈。

4. 二叉排序树 BST

左子树 < 根 < 右子树

操作	平均复杂度
查找 / 插入 / 删除	O(log n)（树高）
最坏（退化为链）	O(n)

删除三种情况：叶子直接删；单孩子提升；双孩子用前驱或后继替换。

5. 平衡二叉树 AVL

平衡因子 = 左子树高 − 右子树高，绝对值 ≤ 1。

插入后失衡四种调整：

LL：右旋           RR：左旋
LR：先左旋再右旋   RL：先右旋再左旋

图示（LL 右旋）

      3                   2
     /       右旋        / \
    2       ─────▶      1   3
   /
  1

最小失衡子树调整后，整棵树恢复平衡；AVL 查找/插入/删除均 O(log n)。

6. 红黑树（408 要求掌握性质与插入过程）

① 结点非红即黑
② 根是黑色
③ 叶子（外部空结点）黑色
④ 红结点的两个孩子必为黑（无连续红）
⑤ 任一结点到其所有后代叶子的路径含相同数目的黑结点（黑高相等）

插入调整：先染红新结点，再按叔结点颜色分情况 变色 / 旋转；根始终染黑。

红黑树高度 ≤ 2·log₂(n+1)，保证 O(log n) 平衡查找。

7. 哈夫曼树与编码

构造

每次取权值最小的两棵树合并，新根权 = 两者之和，重复至一棵树。

性质

WPL = Σ(叶权 × 路径长度) 最小
只有度为 0 和 2 的结点：n 个叶子 ⇒ 2n−1 个结点

示例（权 7 5 2 4）

      18
     /  \
    7   11
       /  \
      5    6
          / \
         2   4

编码（左 0 右 1）：
7 → 0    5 → 10
2 → 110  4 → 111
WPL = 7×1 + 5×2 + 2×3 + 4×3 = 35

哈夫曼编码是最优前缀编码（任一编码不是另一编码的前缀）。

8. 树 / 森林 ↔ 二叉树

孩子兄弟表示法：
左孩子指针 = 第一个孩子；右孩子指针 = 下一个兄弟
森林转二叉树：各树根依次作为右子树连接

树的先序 = 对应二叉树的先序；树的后序 = 对应二叉树的中序。

9. 并查集

int find(int x) {
    while (parent[x] != x) x = parent[x];
    return x;
}
void unionSet(int a, int b) {
    int ra = find(a), rb = find(b);
    if (ra != rb) parent[ra] = rb;   // 可加按秩合并
}

用途：判断连通分量、Kruskal 判环、集合合并。路径压缩 + 按秩合并后近似 O(α(n))。

10. 堆

大根堆：parent ≥ children；小根堆：parent ≤ children
存储：完全二叉树顺序存储，下标 1 开始

操作	复杂度
建堆	O(n)
插入 / 删除堆顶	O(log n)
堆排序	O(n log n)

11. 常考题型

由先序+中序还原二叉树并求后序；
完全二叉树结点编号与父子关系；
AVL 插入旋转过程；
哈夫曼树构造与 WPL、编码；
树转二叉树后的遍历关系；
并查集查找次数与路径压缩；
判断是否为 BST / AVL / 堆。

上一篇：字符串｜下一篇：图

Jai 入门 · 语法详解

2026-08-11T00:00:00+00:00

Jai 入门 · 语法详解

Jai 是 Jonathan Blow（《Braid》《The Witness》作者）设计的面向性能与数据导向的静态强类型语言，目标之一是做“C 的现代替代品“。本文语料主要来自 GitHub 上的 JaiPrimer 与 The Way to Jai 社区教程。

1. Jai 的设计哲学

Jai 关注三件事：

写更快的代码：无 GC、无异常、无类继承包袱，程序员直接控制内存与性能特征；
减少摩擦：语法一致、重构成本低、编译快速；
数据导向（Data-Oriented Design）：程序本质是“填充内存的数据 + 高效算法“。

与 C/C++ 对比	C / C++	Jai
内存管理	malloc/free 或 RAII	`new` / `delete`，指针所有权 `!` 标记，无 GC
多态	虚函数 / 模板	函数级多态 `$T` + 编译期代码
构建	Make/CMake	构建过程由 Jai 源码本身指定
数据组织	AoS 为主	`struct SOA` 一键切换 SoA/AoS
反射	无原生支持	全类型信息运行时可查

2. 程序入口与基本结构

#import "Basic";

main :: () {
    print("Hello, Jai!\n");
}

要点：

main :: () 是入口过程；
#import 导入标准/自定义模块；
print 支持 % 占位符：print("x = %\n", x)。

3. 变量与类型

声明语法：`名字 : 类型 = 值;`

counter : int = 0;
name    : string = "Jon";
average : float = 0.5 * (x + y);

类型省略（编译器推断）：`名字 ::= 值;`

counter := 0;            // int
name    := "Jon";        // string
average := 0.5 * (x+y);  // float

只声明不初始化

counter : int;
flag    : bool;

基本类型

bool、int、int8/16/32/64、uint、float、float32/64、string、rawptr 等。整数和浮点不隐式混用，需显式转换（cast）。

4. 函数（过程）

语法统一：局部函数、匿名函数、全局函数写法完全一致，这是 Jai 重构友好的核心设计。

sum :: (x: float, y: float, z: float) -> float {
    return x + y + z;
}

main :: () {
    print("Sum: %\n", sum(1, 2, 3));
}

匿名函数：

add_one := (x: int) -> int { return x + 1; }

:: 表示“绑定一个常量名字到右侧值“；过程、结构体、枚举、常量都用它声明。

5. 结构体 / 枚举 / 联合

struct

Vector3 :: struct {
    x: float = 1;
    y: float = 4;
    z: float = 9;
}

v : Vector3;
v.x = 2;

成员可以带默认值。没有构造函数/析构函数（Jai 刻意去掉 RAII）。

enum

Color :: enum u16 {
    RED,
    GREEN,
    BLUE = 80,
    ALPHA,
}

union

Value :: union {
    i: int;
    f: float;
}

6. 数组与切片

a : [50] int;   // 定长数组
b : [..] int;   // 动态数组
c : [] int;     // 切片（宽指针，携带长度）

数组不会退化为指针，自带长度信息 count：

print_int_array :: (a: [] int) {
    n := a.count;
    for i : 0..n-1 {
        print("array[%] = %\n", i, a[i]);
    }
}

7. 控制流

if / else

if a == b {
    print("equal\n");
} else if a > b {
    print("greater\n");
} else {
    print("less\n");
}

if-case（对值列表匹配）

if x {
    1, 2, 3 => print("small\n");
    else    => print("other\n");
}

for

for i : 0..9 {            // 范围
    print("%\n", i);
}

for item : items {        // 遍历集合
    print("%\n", item);
}

while

while count < 10 {
    count += 1;
}

defer（作用域退出时执行）

{
    ptr := new int;
    defer delete(ptr);    // 离开作用域时自动释放
}

8. 指针与内存

p : *int = new int;    // 分配
p.* = 42;              // 解引用（后缀 .*）
delete p;              // 释放

结构体指针所有权：成员类型前加 ! 表示“该指针由本结构体拥有，删除结构体时一并删除“：

node :: struct {
    owned_a : !*node = null;
}

example := new node;
example.owned_a = new node;
delete example;      // owned_a 也会被释放

Jai 没有 GC 与自动内存管理，但用所有权标注 + defer 让手动管理可控。

9. 函数级多态（`$T`）

Jai 的多态在函数级，参数前加 $ 声明类型变量：

sum :: (a: $T, b: T) -> T {
    return a + b;
}

f3 := sum(1.0, 2.0);   // float + float
i3 := sum(1, 2);       // int + int

类型由 $ 标记的参数推断，并可以做类型特化（#if 按类型分支）。

Any 类型

print_any :: (a: Any) {
    if a.type.type == Type_Info_Tag.FLOAT {
        print("a is float\n");
    }
}

Any 携带类型信息，适合需要“任意类型“参数的场景。

进阶 1：类型约束（`$T/Foo` 与 `$T/interface`）

$T 不限制类型；要约束“必须拥有某组字段/成员“，用 / 写法（类似 trait / interface）：

Vec3 :: struct {
    x, y, z: float;
}

dot_product :: (a: $T/interface Vec3, b: T) -> float {
    return a.x * b.x + a.y * b.y + a.z * b.z;
}

// 任何"拥有 x/y/z float 字段"的结构体都能传入，不必继承 Vec3

区别：

写法	含义
`a: $T`	任意编译期已知类型
`a: Foo($T)`	必须是 `Foo` 的某种特化，内层 `$T` 任意
`a: $T/Foo`	只要结构体内 using 了 Foo 即可（组件式组合）
`a: $T/interface Foo`	只要拥有 Foo 的全部字段即可（结构鸭子类型）

进阶 2：多态结构体（编译期参数化）

Foo :: struct(T: Type) {
    some_data : T;          // 运行时成员，随 T 变化
}

f : Foo(int);
print("%\n", f.T);          // => int

编译期参数不止类型，还可以是常量值，甚至函数：

Foo :: struct(
    T: Type,
    fun: (T) -> T,          // 编译期烘焙，不占运行时内存
) {
    value: T;               // 运行时数据
}

多态结构体的“模式匹配“写法——三种等价风格：

Hash_Table :: struct (K: Type, V: Type, N: int) {
    keys:   [N] K;
    values: [N] V;
}

// 1) 显式模式匹配
f1 :: (t: Hash_Table($K, $V, $N), k: K, v: V) { }

// 2) $T/类型 + T.K 访问参数
f2 :: (t: $T/Hash_Table, k: T.K, v: T.V) { }

// 3) 隐式多态：直接用具体类型访问其编译期参数
f4 :: (t: Hash_Table, k: t.K, v: t.V) { }

进阶 3：多态数组（长度与元素类型都是类型的一部分）

foo :: (x: [$N]$T) {
    print("%: %, %\n", type_of(N), N, T);
}

x := int.[1, 2, 3, 4];
foo(x);   // => s64: 4, s64（N 本身是编译期 int）

注意：[4] int 与 [5] int 是不同类型，不能互相赋值。

进阶 4：由参数推导返回类型（Helper 结构体 + `#run`）

Helper :: struct(A: Type, B: Type) {
    T :: #run helper(A, B);     // 编译期计算返回类型
}

helper :: ($A: Type, $B: Type) -> Type {
    T : Type = A;               // 这里可以做类型层面的逻辑
    return T;
}

combine :: (a: $A, b: $B) -> Helper(A, B).T {
    // ...
}

进阶 5：`#modify`——编译期校验/变换多态参数

do_something :: (T: Type) -> bool {
    ti := cast(*Type_Info) T;
    return ti.type == .INTEGER || ti.type == .ENUM || ti.type == .POINTER;
}

function :: (dest: *$T, value: T)
#modify { return do_something(T); }   // false => 编译错误
{
    // 运行时实现
}

#modify 在每次调用解析时执行，可检查参数类型、做约束，是 Jai 在“类型层“做特化的入口。

10. 编译期执行（元编程核心）

#run：编译期运行任意代码

generate_table :: () -> [256] float {
    table : [256] float;
    for i : 0..255 {
        table[i] = pow(i / 255.0, 2.2);
    }
    return table;
}

srgb_table := #run generate_table();   // 编译期生成，运行期直接查表

编译期函数由编译器解释执行，结果直接烘焙进二进制。

#if：编译期条件

#if OS == "windows" {
    print("Windows build\n");
} else {
    print("Other build\n");
}

#if 也可用于结构体字段与枚举值的条件定义。

#bake：参数烘焙

add :: (a: int, b: int) -> int { return a + b; }
add_one := #bake add(1);     // 等价于单参数函数

11. 数据导向结构（SOA）

普通 AoS 与 struct SOA 只差一个关键字，内存布局自动切换：

Vector3 :: struct {        // AoS：x y z x y z ...
    x: float = 1;
    y: float = 4;
    z: float = 9;
}

Vector3SOA :: struct SOA { // SoA：x x x y y y z z z
    x: float = 1;
    y: float = 4;
    z: float = 9;
}

对缓存友好、批量更新场景（游戏实体、粒子系统）收益明显，且业务代码无需改动。

12. 反射与运行时类型信息

程序数据段保存完整类型表，可在运行时遍历：

for _type_table {
    print("%\n", it.name);
}

可用于序列化、网络复制、存档、调试器等（C/C++ 需要手写或宏实现）。

13. 模块与项目组织

#import "Basic";
#load "part2.jai";      // 追加编译另一个源文件

大型项目常用 main.jai 作为结构总览：#import 模块、#load 分片源文件，再定义 main()。

14. 学习路径建议

语法骨架：变量 → 过程 → 结构体 → 控制流；
内存：指针、new/delete、所有权 !、defer；
元编程：#run、#if、$T 多态、#bake；
数据导向：struct SOA、数组/切片、缓存局部性；
实战：参考 The Way to Jai 与 JaiPrimer 的示例项目。

注意：Jai 仍处于开发期，语法细节随编译器迭代可能变化，以官方最新文档为准。

23 种设计模式 · C++ 版优缺点与应用场景

2026-08-11T00:00:00+00:00

23 种设计模式 · C++ 版优缺点与应用场景

GoF《设计模式》23 种，按目的分三类：创建型（5）· 结构型（7）· 行为型（11）。本文给出每种模式的意图、C++ 关键代码、优缺点与典型应用场景。

总览

类别	模式	一句话
创建型	单例 Singleton	全局唯一实例
创建型	工厂方法 Factory Method	子类决定创建哪个类
创建型	抽象工厂 Abstract Factory	创建一族相关对象
创建型	建造者 Builder	分步构建复杂对象
创建型	原型 Prototype	复制已有对象
结构型	适配器 Adapter	接口转换
结构型	桥接 Bridge	抽象与实现分离
结构型	组合 Composite	树形整体-部分
结构型	装饰 Decorator	动态附加职责
结构型	外观 Facade	统一门面接口
结构型	享元 Flyweight	共享细粒度对象
结构型	代理 Proxy	替身控制访问
行为型	责任链 Chain of Responsibility	请求沿链传递
行为型	命令 Command	请求封装为对象
行为型	解释器 Interpreter	文法解释
行为型	迭代器 Iterator	顺序访问集合
行为型	中介者 Mediator	对象间解耦通信
行为型	备忘录 Memento	保存/恢复状态
行为型	观察者 Observer	一对多通知
行为型	状态 State	状态行为切换
行为型	策略 Strategy	算法族可替换
行为型	模板方法 Template Method	骨架固定、步骤可变
行为型	访问者 Visitor	数据结构与操作分离

一、创建型模式

1. 单例 Singleton

意图：确保一个类只有一个实例，并提供全局访问点。

class Logger {
public:
    static Logger& instance() {
        static Logger inst;  // C++11 线程安全
        return inst;
    }
private:
    Logger() = default;
};

优点	缺点
全局唯一、省资源	隐藏依赖，难测试
延迟初始化	多线程初始化需注意

场景：日志系统、配置中心、线程池、连接池。

2. 工厂方法 Factory Method

意图：定义一个创建对象的接口，让子类决定实例化哪个类。

struct Product { virtual ~Product() = default; };
struct ConcreteA : Product {};

class Factory {
public:
    virtual std::unique_ptr<Product> create() = 0;
};
class FactoryA : public Factory {
    std::unique_ptr<Product> create() override { return std::make_unique<ConcreteA>(); }
};

优点	缺点
解耦创建与使用	每加一个产品需加子类
开闭原则友好	类数量膨胀

场景：框架中由子类决定对象类型（如游戏单位工厂）。

3. 抽象工厂 Abstract Factory

意图：提供创建一族相关对象的接口。

struct Button { virtual ~Button() = default; };
struct WinButton : Button {};

class UIFactory {
public:
    virtual std::unique_ptr<Button> makeButton() = 0;
};
class WinFactory : public UIFactory {
    std::unique_ptr<Button> makeButton() override { return std::make_unique<WinButton>(); }
};

优点	缺点
保证产品族一致	新增产品族类型困难
隔离具体类	新增产品（方法）违反开闭

场景：跨平台 UI 组件、数据库访问层（不同方言）。

4. 建造者 Builder

意图：分步骤构建复杂对象，步骤可复用于不同表示。

class PizzaBuilder {
public:
    PizzaBuilder& size(int s) { size_ = s; return *this; }
    Pizza build() { return Pizza(size_); }
private:
    int size_ = 0;
};
// 使用：PizzaBuilder{}.size(12).build();

优点	缺点
构造参数可读、不可变	需要额外类
复用构建流程	简单对象反而过度设计

场景：复杂配置对象、文档/查询构建器。

5. 原型 Prototype

意图：通过克隆已有对象创建新对象。

struct Shape {
    virtual ~Shape() = default;
    virtual std::unique_ptr<Shape> clone() const = 0;
};
struct Circle : Shape {
    std::unique_ptr<Shape> clone() const override {
        return std::make_unique<Circle>(*this);
    }
};

优点	缺点
避免重复构造开销	深拷贝语义易出错
动态类型克隆	含资源成员需自定义拷贝

场景：编辑器复制图形、游戏单位克隆、配置模板。

二、结构型模式

6. 适配器 Adapter

意图：将不兼容接口转换为客户端期望的接口。

class Target { public: virtual void request() = 0; };
class Adaptee { public: void specific() {} };
class Adapter : public Target {
public:
    void request() override { adaptee_.specific(); }
private:
    Adaptee adaptee_;
};

优点	缺点
复用已有类，不改源码	过度使用使架构混乱
符合开闭原则	有性能微开销

场景：接入第三方库、新旧接口桥接。

7. 桥接 Bridge

意图：将抽象部分与实现部分分离，各自独立变化。

class Renderer { public: virtual void draw() = 0; };
class Shape {
public:
    explicit Shape(Renderer* r) : r_(r) {}
protected:
    Renderer* r_;
};
class Circle : public Shape {
public:
    using Shape::Shape;
    void draw() { r_->draw(); }
};

优点	缺点
抽象与实现可独立扩展	增加系统复杂度
符合开闭原则	需提前识别维度

场景：图形渲染后端（OpenGL/Vulkan）、跨平台设备驱动。

8. 组合 Composite

意图：将对象组织成树形结构，一致对待叶子与容器。

class Component {
public:
    virtual void render() = 0;
    virtual void add(Component*) {}
};
class Leaf : public Component { void render() override {} };
class Composite : public Component {
public:
    void add(Component* c) override { children_.push_back(c); }
    void render() override { for (auto* c : children_) c->render(); }
private:
    std::vector<Component*> children_;
};

优点	缺点
树形结构统一操作	叶子与容器接口耦合
易扩展新节点	违反接口隔离

场景：文件系统、UI 控件树、组织架构。

9. 装饰 Decorator

意图：动态给对象添加职责，替代继承。

class Stream { public: virtual void write(const std::string&) = 0; };
class FileStream : public Stream { void write(const std::string& s) override {} };
class EncryptedStream : public Stream {
public:
    explicit EncryptedStream(Stream* s) : s_(s) {}
    void write(const std::string& s) override { s_->write(encrypt(s)); }
private:
    Stream* s_;
};

优点	缺点
组合优于继承，灵活	层数多时难调试
运行时叠加能力	小对象过多

场景：IO 流加缓冲/加密/压缩、中间件管道。

10. 外观 Facade

意图：为复杂子系统提供统一简化的入口。

class VideoConverter {
public:
    void convert(const std::string& file) {
        codec_.load(file);
        filter_.apply();
        mux_.save();
    }
private:
    Codec codec_; Filter filter_; Muxer mux_;
};

优点	缺点
客户端使用简单	可能变成“上帝对象“
隔离子系统变化	隐藏了灵活性

场景：编译模块入口、播放器/转换器统一 API。

11. 享元 Flyweight

意图：共享细粒度对象，减少内存占用。

struct CharStyle { std::string font; int size; };
class StyleCache {
public:
    const CharStyle& get(const std::string& font, int size) {
        auto key = font + std::to_string(size);
        auto it = cache_.find(key);
        if (it == cache_.end())
            it = cache_.emplace(key, CharStyle{font, size}).first;
        return it->second;
    }
private:
    std::unordered_map<std::string, CharStyle> cache_;
};

优点	缺点
大幅减少内存	外部状态管理复杂
提高缓存命中	引入共享对象并发问题

场景：文本编辑器字符样式、游戏贴图/粒子模板、连接池。

12. 代理 Proxy

意图：提供替身控制对真实对象的访问（延迟/权限/缓存）。

class Image { public: virtual void show() = 0; };
class RealImage : public Image { void show() override {} };
class ImageProxy : public Image {
public:
    void show() override {
        if (!real_) real_ = std::make_unique<RealImage>();
        real_->show();          // 延迟加载
    }
private:
    std::unique_ptr<RealImage> real_;
};

优点	缺点
延迟加载、访问控制、日志	增加间接层
透明代理	过度代理增加延迟

场景：懒加载图片、智能指针、远程调用（RPC stub）。

三、行为型模式

13. 责任链 Chain of Responsibility

意图：多个处理者串成链，请求沿链传递直到被处理。

class Handler {
public:
    Handler* next(Handler* n) { next_ = n; return this; }
    virtual void handle(int level) {
        if (canHandle(level)) process();
        else if (next_) next_->handle(level);
    }
private:
    virtual bool canHandle(int) = 0;
    virtual void process() = 0;
    Handler* next_ = nullptr;
};

优点	缺点
发送者与处理者解耦	请求可能无人处理
灵活增删处理者	调试链长时困难

场景：日志级别过滤、事件冒泡、中间件管道。

14. 命令 Command

意图：把请求封装成对象，支持参数化、队列、撤销。

class Command {
public:
    virtual void execute() = 0;
    virtual void undo() = 0;
};
class CopyCommand : public Command {
    void execute() override {}
    void undo() override {}
};

优点	缺点
支持撤销/重做、任务队列	每个操作一个类
请求可参数化延迟执行	类数量增加

场景：编辑器撤销栈、事务、宏录制、线程任务。

15. 解释器 Interpreter

意图：为文法定义解释器，求值表达式。

struct Expr { virtual int eval() const = 0; };
struct Num : Expr { int v; int eval() const override { return v; } };
struct Add : Expr {
    const Expr *l, *r;
    int eval() const override { return l->eval() + r->eval(); }
};

优点	缺点
文法易扩展	复杂文法维护困难
领域语言表达力强	性能较低

场景：SQL/正则/数学表达式引擎、脚本解析。

16. 迭代器 Iterator

意图：不暴露内部结构，顺序访问集合元素。

class Iter {
public:
    virtual bool hasNext() = 0;
    virtual int next() = 0;
};
class RangeIter : public Iter {
    int cur_, end_;
public:
    RangeIter(int a, int b) : cur_(a), end_(b) {}
    bool hasNext() override { return cur_ <= end_; }
    int next() override { return cur_++; }
};

优点	缺点
集合遍历与结构解耦	简单集合反而多余
支持多种遍历策略	遍历中修改集合需约定

场景：STL 迭代器、分页遍历、树遍历。

17. 中介者 Mediator

意图：用一个中介对象协调多个对象的交互。

class Mediator {
public:
    void notify(const std::string& from, const std::string& msg) {
        for (auto* c : colleagues_) if (c->name() != from) c->receive(msg);
    }
    void add(Colleague* c) { colleagues_.push_back(c); }
private:
    std::vector<Colleague*> colleagues_;
};

优点	缺点
减少对象间网状依赖	中介者可能过于庞大
交互集中管理	单点故障

场景：聊天室、UI 控件协调、航班调度。

18. 备忘录 Memento

意图：在不破坏封装的前提下保存并恢复对象状态。

struct Memento { int state; };
class Originator {
public:
    Memento save() const { return {state_}; }
    void restore(const Memento& m) { state_ = m.state; }
private:
    int state_ = 0;
};

优点	缺点
状态快照与恢复简单	大对象快照开销高
不破坏封装	历史过多占内存

场景：编辑器撤销、游戏存档、事务回滚。

19. 观察者 Observer

意图：定义一对多依赖，状态变化自动通知。

class Observer { public: virtual void update() = 0; };
class Subject {
public:
    void attach(Observer* o) { obs_.push_back(o); }
    void notify() { for (auto* o : obs_) o->update(); }
private:
    std::vector<Observer*> obs_;
};

优点	缺点
主题与观察者解耦	通知顺序不确定
广播机制天然	级联更新难排查

场景：事件总线、MVC 视图刷新、发布订阅。

20. 状态 State

意图：对象状态改变时行为随之改变，替代大量 if-else。

class State { public: virtual void handle() = 0; };
class IdleState : public State { void handle() override {} };
class RunningState : public State { void handle() override {} };

优点	缺点
状态行为内聚、可扩展	状态类数量多
消除巨型条件分支	状态转换逻辑分散

场景：播放器状态、订单状态机、网络连接状态。

21. 策略 Strategy

意图：定义算法族并封装，运行时切换。

class SortStrategy { public: virtual void sort(std::vector<int>&) = 0; };
class QuickSort : public SortStrategy { void sort(std::vector<int>& v) override {} };
class MergeSort : public SortStrategy { void sort(std::vector<int>& v) override {} };

class Sorter {
public:
    void setStrategy(SortStrategy* s) { s_ = s; }
    void run(std::vector<int>& v) { s_->sort(v); }
private:
    SortStrategy* s_;
};

优点	缺点
算法可替换、开闭原则	客户端需了解策略差异
消除条件分支	策略对象数量增加

场景：排序算法选择、压缩/加密算法、价格计算。

22. 模板方法 Template Method

意图：定义算法骨架，子类实现可变步骤。

class DataParser {
public:
    void parse() {                 // 骨架固定
        open(); read(); process(); close();
    }
protected:
    virtual void process() = 0;    // 可变步骤
private:
    void open() {} void read() {} void close() {}
};

优点	缺点
复用公共流程	骨架修改影响全部子类
约束子类实现范围	违反 LSP 风险（子类改变骨架）

场景：框架生命周期（初始化-运行-清理）、解析器流程。

23. 访问者 Visitor

意图：在不修改类的前提下，为对象结构增加新操作。

class Visitor; 
class Node {
public:
    virtual void accept(Visitor& v) = 0;
};
class TextNode : public Node {
public:
    void accept(Visitor& v) override;
};
class Visitor {
public:
    virtual void visit(TextNode&) = 0;
};

优点	缺点
数据结构与操作分离，易加操作	新增节点类型需改所有访问者
操作内聚	破坏封装（需暴露内部）

场景：AST 编译/解释、对象结构统计与序列化。

选型速查

问题	推荐模式
全局唯一	单例
创建复杂对象	建造者 / 工厂 / 抽象工厂
接口不兼容	适配器
动态加职责	装饰
树形结构	组合
延迟/控制访问	代理
一对多通知	观察者
运行时换算法	策略
状态行为切换	状态
撤销重做	命令 + 备忘录
为结构加新操作	访问者

原则提醒：优先组合而非继承、面向接口而非实现、对扩展开放对修改关闭。模式是工具，不要为模式而模式。

《纯粹理性批判》读后感

2026-08-11T00:00:00+00:00

《纯粹理性批判》读后感

康德（Immanuel Kant）1781 年初版《纯粹理性批判》。本次精读先验感性论与先验分析论，兼及辩证论的开头部分。

一、问题意识：先天综合判断如何可能

康德面对两派：

学派	立场	问题
唯理论（莱布尼茨）	理性演绎一切	脱离经验，独断
经验论（休谟）	一切知识来自经验	因果等必然性无法保证

康德的问题是：存在既先于经验（先天）、又扩展知识（综合）的判断吗？ 数学与自然科学就是例子：

7 + 5 = 12        先天综合（不靠经验，却扩展了知识）
一切事件都有原因  先天综合（因果性不能从经验归纳出来）

回答这个问题，需要批判理性自身的能力与边界——这就是“纯粹理性批判“。

二、哥白尼式革命

传统认为认识必须符合对象；康德反转为：对象必须符合我们的认识形式。

不是知识围绕对象转，而是对象围绕我们的认知结构转

我们只能认识“对我们显现的现象“，而不能认识独立于我们的“物自体（Ding an sich）“。物自体不可知，但它的存在被设定为现象的根据。

三、先验感性论：时空

1. 时间与空间是直观形式

空间：外感官的形式——外部事物必须在空间中呈现
时间：内感官的形式——一切表象（含思维）都在时间中

时空不是经验中抽象出来的概念，而是感性的先天形式：它们使经验成为可能，也因此只适用于现象。

2. 数学为什么可能

几何基于空间的先天直观，算术基于时间的先天直观——这解释了数学的“普遍必然性“。

四、先验分析论：范畴与知性

1. 直观无概念则盲，概念无直观则空

思维无内容则空，直观无概念则盲

感性提供材料，知性用范畴整理材料，两者结合才产生知识。

2. 十二范畴（知性的先天概念）

量	质	关系	样式
单一性	实在性	依存性与实体	可能性
多数性	否定性	因果性与依存	现实性
全体性	限制性	协同性（共联）	必然性

3. 统觉的先验统一

“我思“必须能够伴随我的一切表象——这是知识统一的最高原理。范畴通过先验统觉把杂多表象综合为对象。

4. 人为自然立法

因果性、实体性等范畴是知性加到现象上的，而不是从自然里“读出来“的。因此：

自然界的普遍规律，是知性先天地规定的——“人为自然立法”。

五、先验辩证论（引子）：理性的越界

理性不满足于现象，总想把握“无条件者“，于是产生三类理念：灵魂、世界、上帝。理性把它们当作对象去认识，就会陷入幻相（如二律背反：世界有无开端、自由与必然等矛盾）。康德的任务不是消灭理性，而是为理性划界：

现象界：可认识（知性 + 感性）
本体界（物自体）：不可认识，只能思维（实践理性另论）

六、阅读体会

1. “划界“比“回答“更深刻

康德最打动我的不是某个结论，而是问题的提法：与其争论上帝存在与否，不如先问“我们能认识什么“。这种“先问能力边界“的姿态，和工程中的“先定义问题域“非常接近——很多争论之所以无解，是因为双方在错误的层面争论。

2. 时空与“接口“

把时空理解为“认知的接口“，是一个现代比喻：我们永远只能通过这个接口读取“外部系统“的数据，接口之外（物自体）只能假设其存在。这与软件中“接口隔离““内部实现不可见“的思想惊人地同构。

3. 范畴 = 认知的“内置 DSL“

因果、实体、必然等范畴，像是人类认知系统内置的“领域语言“：没有它们，经验只是杂乱的数据流。这也提醒我：工具（语言、框架）不仅描述世界，也在塑造我们能“看见“什么——正如范畴塑造经验。

4. 对科学边界的清醒

康德既为科学辩护（先天综合判断使牛顿力学成为可能），又为科学划界（物自体不可知）。这种“既肯定又限制“的平衡，在今天（AI 与科学的边界、数学公理系统的哥德尔界限）依然有回响。

5. 阅读难度与策略

《纯粹理性批判》公认难读：术语密集、论证层层嵌套。我的策略是：

先读导论与感性论（约前 80 页）建立框架；
用“表格化“整理十二范畴与判断表；
配合二手导读（如邓晓芒《康德<纯粹理性批判>句读》）逐段对照；
不求一次读通，先抓住“先天综合判断、现象/物自体、范畴、统觉“四个锚点。

七、值得回味的句子

哥白尼式的革命：不是知识依照对象，而是对象依照知识。

思维无内容则空，直观无概念则盲。

我不得不限制知识，以便为信仰留出地盘。

八、延伸阅读

邓晓芒《康德哲学讲演录》；
韩水法译《实践理性批判》；
叔本华《作为意志和表象的世界》（康德批判哲学的继承与反叛）；
波普尔《客观知识》（康德的“人为自然立法“在科学哲学中的回声）。

上一篇：《作为意志和表象的世界》读后感

《作为意志和表象的世界》读后感

2026-08-11T00:00:00+00:00

《作为意志和表象的世界》读后感

叔本华（Arthur Schopenhauer）1818 年出版《作为意志和表象的世界》。本次精读第一、二篇（世界作为表象 / 世界作为意志），兼及第三篇的审美思想。

一、作者与写作背景

叔本华在 30 岁前完成此书，自视极高，却长期无人问津；直到晚年（《附录与补遗》）才获得声誉。他承康德之余绪，却把康德“物自体“推演为意志，由此建立了一套以“痛苦与解脱“为核心的哲学。

二、第一篇：世界作为表象

1. 表象的世界

叔本华开篇即断言：

“世界是我的表象。”

我所能经验到的一切，都是我的表象——颜色、声音、时间、空间，都离不开认识主体而独立存在。这继承了康德的“现象/物自体“之分：我们能认识的只是显现给我们的现象。

2. 充足理由律

表象世界受充足理由律支配：

生成的理由（因果律）：万物皆有其因
认识的理由：判断须有依据
存在的理由：时间与空间中的位置关系
行为的理由（动机律）：人的行动有其动机

充足理由律是现象世界的“形式骨架“，但它只在表象领域有效。

3. 直观先于概念

叔本华特别强调**直观（Anschauung）**先于概念：概念是直观的抽象，是“表象的表象“。真正的认识从直观开始，科学是对直观关系的整理。这一立场使他与黑格尔式的抽象思辨划清界限，也预示了后来的现象学思路。

三、第二篇：世界作为意志

1. 从表象深入到意志

表象背后是什么？叔本华认为：世界的内核是意志（Wille）——一种无意识、无目的的欲求与冲动。现象世界的“物自体“就是意志。

2. 身体是意志的可见性

身体是理解意志的钥匙：

我的身体同时是表象（对象）与意志（内在体验）；
牙齿的“咬合欲“、胃的“消化欲“、性欲——器官本身就是客体化的意志；
饥饿、疼痛、欲望，都是意志的直接显现。

由此，一切现象都是意志的客体化：从低级无机物到高级动物，层层上升，直到人。

3. 意志的特征

特征	说明
无目的	意志没有终极目标，欲求永不停息
盲目	不服从理性，理性只是它的工具
不可满足	满足一个欲望，立刻生出新的欲望

4. 痛苦与无聊

由此推出叔本华著名的钟摆论：

人生就是欲望与满足之间的钟摆：欲望不得满足则痛苦，得到满足则无聊。

四、第三篇（延伸）：审美作为解脱

审美是暂时的解脱：当主体沉浸于直观，忘记欲望，对象脱离功利关系时，主体与客体都“上升“为纯粹的理念。音乐尤其如此——它不是表象的摹本，而是意志本身的直接写照。

五、阅读体会

1. 与康德的关系

叔本华把康德“物自体不可知“的谨慎立场，替换为“物自体就是意志“的大胆断言。这种替换使形而上学重新可能，但也把康德批判哲学留下的“知识边界“再次跨越了。读此书最好先读过康德《纯粹理性批判》的先验感性论与分析论，否则“表象/物自体“这对概念会缺少锚点。

2. 对现代人的触动

在消费主义与效率至上的今天，“意志永不满足“几乎可以翻译为：欲望是生产与消费的动力系统。广告、算法推荐都在制造新的欲求；而叔本华提醒我们，满足之后是空虚。这不是要人禁欲，而是让人看清欲望的结构，从而获得一点抽离。

3. 悲观主义的积极面

叔本华的悲观不是消沉，而是清醒：把人生的底色看清楚，反而能减少不切实际的期待。正如他说的，期望是痛苦的来源之一；降低对“外部世界必然回报“的预期，是一种心理上的减震。

4. 对技术工作的启发

作为程序员，我常把“意志的客体化“读成系统的演化逻辑：商业系统的目标是增长（无目的的意志），个体在其中只是功能单元（客体化的器官）。理解这一点，有助于在工程决策中区分“系统自身的欲求“与“真实的需求“，避免被卷进盲目迭代。

六、值得回味的句子

世界是我的表象。——这不是说世界是幻觉，而是说我们对世界的认识离不开认识的形式。

生命意志的本质就是挣扎。

一切满足都只是暂时的，新的欲求立刻接踵而至。

七、延伸阅读

康德《纯粹理性批判》（先验感性论、分析论）；
尼采《悲剧的诞生》（意志哲学的反转：肯定生命）；
张汝伦《现代西方哲学十五讲》（叔本华章）；
叔本华《附录与补遗》（更易读的通俗篇）。

下一篇：《纯粹理性批判》读后感

本机命令与类库总览：4271 个可执行文件 / 782 个 Homebrew 公式

2026-08-11T00:00:00+00:00

本机命令与类库总览

数据来源：print -l ${(k)commands} | sort | while read -r name; do print -- "$(whence -p -- "$name") $name"; done 共 4271 条命令；brew list --formula 共 782 个公式；brew list --cask 共 69 个 cask。

1. 统计总览

来源目录	命令数	说明
`/opt/homebrew/bin`	2588	Homebrew 公式主目录
`/usr/bin`	858	macOS 系统命令
`/usr/sbin`	217	系统管理命令
`/opt/homebrew/opt/llvm/bin`	167	LLVM 工具链
`/opt/homebrew/opt/ccache/libexec`	76	ccache 包装层
`/sbin`	72	系统引导/管理
`/Users/songhoujin/.ghcup/bin`	64	Haskell 工具链
`/opt/homebrew/opt/postgresql@17/bin`	37	PostgreSQL 客户端
`/bin`	36	macOS 基础命令
`(builtin/alias/function)`	31	zsh 内建/别名/函数
`/opt/homebrew/opt/ruby/bin`	26	Ruby 工具链
`/Users/songhoujin/.cargo/bin`	24	Rust/Cargo 工具
`/opt/homebrew/sbin`	23	Homebrew 系统命令
`/Applications/iTerm.app/Contents/Resources/utilities`	17	iTerm 自带工具
`/usr/local/bin`	14	第三方/手动安装
`/Users/songhoujin/.local/bin`	7	pipx/手动安装
`/Users/songhoujin/Jai/bin`	6	Jai 编译器
`/opt/homebrew/opt/gawk/libexec/gnubin`	1
`/Users/songhoujin/.craft/bin`	1
`/opt/homebrew/opt/make/libexec/gnubin`	1

2. 分类速查（核心用法）

按功能场景分组，选每个场景最常用的命令，给出直接可用的核心用法：

构建与编译

命令	说明	核心用法
`cmake`	跨平台构建系统（C++ 主力）	`cmake -B build -G Ninja && cmake --build build -j$(nproc)`
`ninja`	极速构建后端	`ninja -C build`
`mold`	高速链接器（替代系统 ld）	`cmake -B build -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=mold`
`ccache`	编译缓存（C/C++）	`export CC='ccache clang' CXX='ccache clang++'`
`bear`	生成 compile_commands.json（喂给 clangd）	`bear -- cmake --build build`
`meson`	Python 风格构建系统	`meson setup build && meson compile -C build`

C/C++ 核心类库

命令	说明	核心用法
`fmt`	现代格式化（std::format 前身）	`fmt::print("{}\n", 42);`
`spdlog`	高性能日志库	`spdlog::info("Hello {}", name);`
`nlohmann-json`	JSON 解析/序列化	`nlohmann::json j = nlohmann::json::parse(s);`
`boost`	C++ 标准库扩展大全	`brew install boost && #include <boost/asio.hpp>`
`eigen`	线性代数模板库	`#include <Eigen/Dense>`
`taskflow`	并行任务流（DAG）	`tf::Taskflow tf; auto [a,b]=tf.emplace(f1,f2);`

语言运行时与工具链

命令	说明	核心用法
`llvm`	Clang/LLVM 工具链全家桶	`clang++ -std=c++26 -O2 main.cpp -o main`
`rustup`	Rust 工具链管理器	`rustup update stable && cargo new hello`
`cargo`	Rust 构建/包管理	`cargo build --release && cargo test`
`go`	Go 编译/工具链	`go build ./... && go vet ./...`
`uv`	Python 包管理（极快）	`uv add requests && uv run main.py`
`node`	JavaScript 运行时	`node --version && npm init -y`
`jai`	Jai 编译器（内测）	`jai-macos hello.jai`

版本控制与协作

命令	说明	核心用法
`git`	版本控制	`git add -A && git commit -m 'msg' && git push`
`lazygit`	Git 终端 TUI	`lazygit`
`git-delta`	高亮 diff 分页器	`git config --global core.pager delta`
`difftastic`	结构化 diff	`difft file1 file2`
`cloc`	代码行数统计	`cloc --exclude-dir=build,.git .`

终端效率与美化

命令	说明	核心用法
`atuin`	历史命令检索（SQLite）	`atuin search cmake --interactive`
`zoxide`	智能目录跳转	`z blog && zi`
`fzf`	模糊查找器	`fzf --preview 'bat {}'`
`bat`	语法高亮 cat	`bat main.cpp`
`eza`	现代 ls	`eza --long --tree --level=2 --git --icons`
`fd`	现代 find	`fd '\.cpp$' src`
`ripgrep`	极速 grep	`rg 'TODO' --type cpp`
`starship`	跨 shell 提示符	`starship init zsh \| source`

网络与下载

命令	说明	核心用法
`curl`	HTTP 请求	`curl -OL https://example.com/file.tar.gz`
`xh`	人类友好 curl（httpie 风格）	`xh GET api.example.com/users`
`mtr`	网络路径+丢包诊断	`mtr -rw example.com`
`nmap`	端口/服务扫描	`nmap -sV 192.168.1.1`
`rclone`	云盘同步	`rclone sync local: remote:backup`

数据库与存储

命令	说明	核心用法
`postgresql@17`	PostgreSQL 数据库	`brew services start postgresql@17 && psql -d postgres`
`sqlite`	嵌入式 SQL 数据库	`sqlite3 data.db 'SELECT * FROM t;'`
`duckdb`	分析型列式数据库	`duckdb -c 'SELECT count(*) FROM read_csv_auto(f.csv)'`
`redis`	内存键值库	`redis-cli SET k v && GET k`
`zstd`	高压缩比压缩	`zstd -19 -o out.zst file && zstd -d out.zst`

媒体与图像

命令	说明	核心用法
`ffmpeg`	音视频转码/处理	`ffmpeg -i in.mp4 -c:v libx264 -crf 23 out.mp4`
`mpv`	极简播放器	`mpv --hwdec=auto video.mkv`
`imagemagick`	图像处理 CLI	`magick input.png -resize 800x out.png`
`tesseract`	OCR 文字识别	`tesseract scan.png out -l eng`

AI 与机器学习

命令	说明	核心用法
`llama.cpp`	本地 LLM 推理	`llama-cli -m model.gguf -p 'Hello'`
`ggml`	GGML 张量库	`#include <ggml.h>`
`onnx`	ONNX 模型运行时	`python3 -c 'import onnx'`
`openvino`	Intel 推理优化	`benchmark_app -m model.xml`

数学与科学计算

命令	说明	核心用法
`openblas`	BLAS 线性代数	`brew info openblas`
`graphviz`	图/依赖可视化	`dot -Tpng graph.dot -o graph.png`
`gnuplot`	科学绘图	`gnuplot -e "plot 'data.txt' u 1:2"`
`octave`	MATLAB 兼容计算	`octave --eval 'A=[1 2;3 4]; inv(A)'`

安全与加密

命令	说明	核心用法
`openssl`	TLS/加密 CLI	`openssl s_client -connect example.com:443`
`gnupg`	GPG 加解密/签名	`gpg --encrypt --recipient key file`
`pass`	密码管理（GPG）	`pass insert email/me && pass show email/me`
`hashcat`	密码哈希破解	`hashcat -m 0 hash.txt wordlist.txt`
`semgrep`	代码静态安全扫描	`semgrep scan --config auto .`

系统与监控

命令	说明	核心用法
`btop`	系统资源监控 TUI	`btop`
`mactop`	macOS 进程/温度监控	`mactop`
`tracy`	C++ 性能剖析	`tracy-profiler & 然后代码里 TRACY_ZONE_SCOPED`
`valgrind`	内存检测	`valgrind --leak-check=full ./a.out`
`samply`	Rust/Swift 采样剖析	`samply record ./app`

文本与数据处理

命令	说明	核心用法
`jq`	JSON 处理	`curl -s api \| jq '.items[].name'`
`gawk`	GNU awk（文本处理）	`gawk '{s+=$1} END{print s}' nums.txt`
`ast-grep`	结构化代码搜索/重构	`ast-grep -p 'unwrap' -l rust`
`pandoc`	文档格式转换	`pandoc a.md -o a.pdf --pdf-engine=xelatex`

3. Homebrew 已装公式完整清单（按功能分类）

共 782 个公式；： 后为要点说明。完整原始清单见附录。

构建与编译（34）

autoconf，automake，bazel：Google 构建系统 bear：compile_commands 生成，binutils，bison build2：C/C++ 构建工具链，ccache：编译缓存，clang-format：clang 格式化 clang-include-graph：头文件依赖图，clang-uml：clang UML 图，clangql：Clang AST 查询 cmake：CMake 构建系统，cmake-docs，corrosion gnu-getopt，just，just-lsp libtool，lld：LLVM 链接器，lld@21 llvm：LLVM/Clang 全家桶，llvm@21，m4 make，meson：Meson 构建，mold：高速链接器 ninja：Ninja 构建，pkg-config-wrapper，pkgconf re2c，sc-cmake，swig xdg-ninja

C/C++ 核心类库（185）

abseil，adaptivecpp，argparse argtable，armadillo，asio atomic_queue，aws-crt-cpp，aws-sdk-cpp behaviortree.cpp，blaze，blitz boost：Boost 库，boost-build，boost-python3 capnp，catch2：测试框架，cereal cli11，concurrentqueue，cpp-gsl cpp-httplib，cpp-peglib，cppcheck cppinsights，cpplint，cppman cpptest，cpptrace，cppunit cpputest，cppzmq，cpr crow，ctre，cxxopts dbg-macro，dispenso，doctest：单头测试框架 drogon，dylibbundler，eigen：线性代数库 eigen@3，entt，eventpp fast_float，flatbuffers，flecs fmt：格式化库，frozen，glaze glib，glibmm，glibmm@2.66 glog，google-benchmark：微基准库，googletest：Google 测试 gsl：GNU 科学库，highway，hiredis hopscotch-map，icu4c@78，immer inja，json-c，jsoncpp kokkos，leveldb，libaec libassuan，libb2，libcbor libcds，libcerf，libcutl libdatrie，libdeflate，libepoxy libev，libevent，libff libffi，libfido2，libghthash libgit2，libgpg-error，libgrape-lite libharu，libidn，libidn2 libimagequant，libjson-rpc-cpp，libksba liblinear，libmagic，libmicrohttpd libmpc，libmpdclient，libnetworkit libnghttp2，libnghttp3，libngtcp2 libomp，libpaper，libpcap libphonenumber，libplacebo，libpq libpqxx，libpsl，libraqm librdkafka，librsvg，libsigc++ libsigc++@2，libstxxl，libtasn1 libthai，libtins，libtomcrypt libtommath，libudfread，libunibreak libunicode，libunistring，libusb libuv，libx11，libxau libxc，libxcb，libxdmcp libxext，libxfixes，libxi libxrender，libxtst，libyaml libzip，log4cplus，log4cpp log4cxx，lzlib，magic_enum msgpack，mysql，nlohmann-json：JSON 库 oatpp，opentelemetry-cpp，parallel-hashmap pcaudiolib，pegtl，pistache plog，poco，prometheus-cpp pugixml，pybind11，quill range-v3，rapidjson，readerwriterqueue redis：内存 KV，robin-map，rocksdb：KV 存储引擎 scnlib，simdjson，simdutf soci，spdlog：日志库，sqlite：SQLite ta-lib，taskflow，tbb tinyxml2，tl-expected，tomlplusplus utf8cpp，xsimd，xtensor xtl，yalantinglibs，yaml-cpp zeromq，zug

语言运行时与工具链（34）

bun，delve：Go 调试器，deno elan-init：Lean 工具链，gcc，go：Go 语言 gobject-introspection，golangci-lint：Go 聚合 linter，gopls：Go LSP gource，lua，lua-language-server luajit，node：Node.js，nvm：Node 版本管理 odin：Odin 语言，openjdk：Java 工具链，openjdk@21 php，python-setuptools，python@3.11 python@3.12，python@3.13，python@3.14：Python 3.14 ruby：Ruby 语言，ruby-install，rust：Rust 语言 rust-analyzer：Rust LSP，rustnet，rustup：Rust 工具链 staticcheck：Go 静态检查，swiftlint，zig：Zig 语言 zigoku

版本控制与协作（12）

cloc：代码统计，cscope，czg：Commitizen Go 提交规范 difftastic：结构化 diff，ghidra：逆向分析，ghostscript git：版本控制，git-delta：diff 高亮，global lazygit：Git TUI，tokei：代码统计(Rust)，universal-ctags

终端效率与美化（42）

ack，ast-grep：AST 搜索，atuin：历史检索 bat：高亮 cat，borders：窗口边框，btop：系统监控 carapace，cheat，direnv：目录环境 eza：现代 ls，fastfetch，fd：现代 find fzf：模糊查找，has，hashcat：哈希破解 hexyl，jless，lf mactop：macOS 监控，mise：多运行时版本管理，mprocs navi，onefetch，reddix ripgrep：极速搜索，sketchybar：菜单栏定制，starship：提示符 tealdeer，the_silver_searcher，tmux：终端复用 tree-sitter：增量解析器，typioca，usage why，yabai：平铺窗口管理，yazi zoxide：目录跳转，zsh-autocomplete，zsh-completions zsh-patina，zsh-syntax-highlighting，zsh-you-should-use

网络与下载（24）

bind，croc，curl：HTTP 客户端 curlpp，dnsmasq，httpie：HTTP 客户端 ipatool，mirrord，mtr：网络诊断 netcat，netwatch，nexttrace nmap：网络扫描，openssh，rclone：云盘同步 sniffnet，socat，speedtest-cli syncthing：P2P 同步，tailscale：VPN 组网，telegram-downloader wget：下载，xh：HTTPie 风格 curl，yt-dlp：视频下载

数据库与存储（15）

brotli：压缩，cassandra-cpp-driver，cypher-shell duckdb：分析型数据库，libarchive，lz4 lzo，minizip，neo4j postgresql@17：PostgreSQL，snappy，xz：压缩 zlib，zlib-ng-compat，zstd：压缩

容器与虚拟化（3）

ansible，colima，lima

媒体与图像（82）

asciinema，cairo，cairomm@1.14 chafa，cmatrix，cowsay dav1d，ffmpeg：音视频处理，figlet flac，fltk，fontconfig fortune，freetype，giflib glbinding，glew，glfw glm，graphicsmagick，gtk+3 harfbuzz，imagemagick：图像处理，imath imlib2，jp2a，jpeg-turbo jpeg-xl，leptonica，libass libavif，libbluray，libcaca libde265，libexif，libheif libogg，libopenmpt，libpng libsamplerate，libsndfile，libtiff libvmaf，libvorbis，libvpx little-cms2，lolcat，mlpack molten-vk，mpg123，mpv：播放器 opencv：计算机视觉，openexr，openjpeg openjph，opus，pango poppler，qt5compat，qtbase qtdeclarative，qtsvg，qttools raylib，rubberband，sdl2 sdl2-compat，sdl2_image，sdl3 sfml，shaderc，sound-touch svt-av1，taglib，tesseract：OCR tgui，vtk，vulkan-headers vulkan-loader，webp，x264 x265

AI 与机器学习（7）

faiss：向量检索，ggml：张量库，libtensorflow llama.cpp：本地 LLM，llmfit，onnx：ONNX 运行时 openvino：Intel 推理

数学与科学计算（50）

arpack，autodiff，bandicoot cbc，ceres-solver，cgal cgl，cln，clp coinutils，cppad，dlib ensmallen，fftw，flint geographiclib，gismo，glpk gmp：大数库，gnuplot：科学绘图，graph-tool graphviz：图可视化，hdf5，hdf5-mpi highs，hypre，igraph kahip，lapack：LAPACK，lbfgspp lemon，metis，mpfr netcdf，networkit，nlopt octave：数值计算，openblas：BLAS，osi petsc，proj，quantlib s2geometry，scalapack，scip scipy，scotch，suite-sparse sundials，ttmath

安全与加密（25）

argon2，blake3，botan cbmc：C 模型检查，clamav，cryptopp esbmc：BMC 验证，flawfinder，gnupg：GPG gnutls，gpgme，gpgmepp libgcrypt，libsodium，libssh libssh2，mbedtls，openssl@3 openssl@4，pass：密码管理，pinentry secp256k1，semgrep：静态安全扫描，xxhash yara

文档与办公（11）

doxygen：代码文档，groff，libxml++ libxml2，mermaid-cli：Mermaid 渲染，pandoc：文档转换 plantuml：UML 图，pstoedit，psutils texinfo，xerces-c

系统与监控（11）

coreutils：GNU 核心工具，duf，gawk：GNU awk gperftools：性能工具集，moreutils：附加工具，ncdu osx-cpu-temp，samply：采样剖析，tracy：性能剖析 uutils-coreutils：Rust 版 coreutils，valgrind：内存检测

文本与数据处理（7）

jq：JSON 处理，qhull，qrencode qrupdate，qscintilla2，qtshadertools quantum++

开发工具杂项（13）

diu，hyperfine：基准测试，macpow merve，mole，paneru sag，songsee，summarize syswatch，topgrade：一键升级，watchman：文件监听 zen-mode

其他开发/系统库（227）

ada-url，aklomp-base64，alloy-analyzer ampl-asl，aom，apache-arrow apex，apr，apr-util async_simple，asyncplusplus，at-spi2-core autojump，aws-c-auth，aws-c-cal aws-c-common，aws-c-compression，aws-c-event-stream aws-c-http，aws-c-io，aws-c-mqtt aws-c-s3，aws-c-sdkutils，aws-checksums bash，bc，beecrypt bitwise，bitwuzla，boxes brew-gem，bstring，c-ares c4core，ca-certificates，cabin caddy，caf，ccrypt certifi，cffi，cgns chezmoi，choose-rust，chuck clblast，cliamp，cocoapods conan：C++ 包管理，cryptography，ctemplate dbus，deheader，doppler double-conversion，dragonbox，dwarfutils edencommon，elio，enet enkits，epstool，espeak-ng fastlane，fb303，fblog fbthrift，fig2dev，fizz flux，folly，freetds fribidi，fruit，functionalplus fuzzy-find，gd，gdb gdbm，gdk-pixbuf，gem-doing gettext，gflags，gl2ps glow，gmssl，gpk gputils，graphite2，grpc gsettings-desktop-schemas，gsoap，gts gumbo-parser，gzip，hdrhistogram_c helix，hicolor-icon-theme，howard-hinnant-date hwloc，ical-buddy，iguana include-what-you-use，indicators，ipopt isl，jansson，jasper jbig2dec，jemalloc，kfr krb5，lager，lame lcov，ldns，ledger litehtml，llhttp，lpeg luv，m-cli，mas matplotplusplus，md4c，meta-package-manager mfem，mimalloc，mpdecimal mujs，mvfst，nativefiledialog-extended nbytes，ncurses，neovim net-snmp，netpbm，nettle nginx，nng，nowplaying-cli npth，nspr，nss numpy，nuraft，onedpl oniguruma，open-mpi，openldap or-tools，oterm，p11-kit pcre2，physunits，pillow pipx：Python 应用隔离安装，pixman，plotutils pmix，popt，portaudio pre-commit，protobuf，protobuf-c proxygen，prrte，pv py3cairo，pycparser，pydantic pyenv，pygobject3，pyinstaller re2，readline，remindctl rm-safely，rpds-py，rsync rttr，s2n，sentry-native seqan3，serialize，sevenzip shared-mime-info，sl，sleepwatcher span-lite，spark，stow superlu，tcpdump，television telnet，terminal-notifier，theora thrift，tidy-html5，tlrc tlx，tomcat，trash tre，tree，uchardet udunits，unbound，unibilium unixodbc，usbutils，userspace-rcu utf8proc，uv：Python 包管理，uvwasi vapoursynth，vcpkg：C++ 包管理，vim wangle，websocketpp，xcbeautify xorgproto，yyjson，z3 zimg，zola

4. 非 Homebrew 命令（按来源）

来源	命令	说明
`~/.ghcup/bin`	`ghc`, `cabal`, `ghcup`	Haskell 工具链（ghcup 管理）
`~/.cargo/bin`	`cargo`, `cargo-clippy`, `cargo-fmt`, `cargo-miri`, `cargo-install-update`	Rust 构建/检查/格式化（rustup 管理）
`~/Jai/bin`	`jai`, `jai-macos`, `lld`	Jai 编译器（内测）与配套链接器
`~/.elan/bin`	`elan`, `lean`, `lake`, `leanc`	Lean 证明助手工具链
`~/.mcpp/bin`	`mcpp`	C 预处理器（可移植实现）
`~/.local/bin`	`clop`, `focr`, `mpm`, `pdf2zh`, `rcc`, `rcmd`	pipx 安装的 Python 工具（含 OCR/PDF 翻译）
`~/.craft/bin`	`craft`	C/C++ 轻量构建工作流工具
`~/.cache/lm-studio/bin`	lm-studio 相关	LM Studio 本地模型辅助脚本
`/usr/local/bin`	`container`, `update-container.sh` 等	手动安装的 macOS 容器/更新脚本
`/Applications/iTerm.app/.../utilities`	iTerm 集成工具	终端模拟器自带工具

5. macOS 系统命令简表

分组	说明	示例
ls/cp/mv/rm/mkdir	文件与目录基本操作	`ls -lah && mkdir -p dir && cp -R src dst`
cat/less/head/tail	查看文件	`less big.log && tail -f app.log`
grep/find/xargs	搜索与批处理	`grep -rn 'TODO' src && find . -name '*.cpp' \| xargs wc -l`
sed/awk(→gawk)	流式文本处理	`sed -i 's/old/new/g' f.txt`
sort/uniq/wc/cut/tr	文本管道处理	`cut -d, -f1 data.csv \| sort \| uniq -c`
tar/gzip/bzip2/xz/zip	压缩归档	`tar -czf out.tgz dir/ && unzip a.zip`
chmod/chown	权限管理	`chmod +x script.sh && chown -R user:staff dir`
ps/kill/top	进程管理	`ps aux \| rg nvim && kill -9 PID`
df/du	磁盘占用	`df -h && du -sh ~/* \| sort -h`
diskutil/mount	磁盘与挂载	`diskutil list && diskutil info disk3`
defaults/plutil	macOS 偏好与 plist	`defaults read com.apple.dock && plutil -p Info.plist`
launchctl	守护进程管理	`launchctl list \| rg brew && brew services list`
scutil/networksetup	网络配置	`scutil --proxy && networksetup -listallhardwareports`
system_profiler/sw_vers	系统信息	`system_profiler SPHardwareDataType && sw_vers`
xcode-select/xcrun	开发工具链选择	`xcode-select -p && xcrun --show-sdk-path`
codesign/security	签名与钥匙串	`codesign -dv App.app && security find-certificate -c 'Apple Dev'`
ssh/scp/rsync	远程与同步	`ssh host && scp f.txt host: && rsync -avz dir/ host:dir/`
ping/traceroute/curl	网络诊断	`ping -c 3 host && traceroute host`
lsof/netstat/ifconfig	端口与接口	`lsof -iTCP:8000 && netstat -rn && ifconfig en0`
open/osascript/say	macOS 集成	`open -a Safari && osascript -e 'beep' && say hello`
mdfind/mdls	Spotlight 索引	`mdfind 'kMDItemFSName == *.cpp' && mdls file`
file/strings/otool/nm	二进制分析	`file a.out && strings a.out \| rg pass && otool -L a.out`
pbcopy/pbpaste	剪贴板	`pwd \| pbcopy && pbpaste`
sips/textutil	图像/文档小工具	`sips -Z 800 in.png --out out.png && textutil -convert html a.rtf`
shasum/md5	校验和	`shasum -a 256 file.dmg`
defaults/plutil	配置读写	`defaults write com.apple.finder AppleShowAllFiles YES`

6. 附录：原始数据与复现

原始命令清单（4271 行）已归档为 commands-full-list.txt，与本文档同目录。复现命令：

print -l ${(k)commands} | sort | while read -r name; do
  print -- "$(whence -p -- "$name")  $name"
done > commands-full-list.txt
brew list --formula

提示：whence -p 对 zsh 内建/别名/函数返回空路径，因此清单中含少量非可执行条目，统计时已单独归组。

Zsh 配置体系体检与优化：启动链路分析

2026-08-11T00:00:00+00:00

Zsh 配置体系体检与优化：启动链路分析

TL;DR：本机 zsh -i 启动实测 ~715ms → 仅移除「每次启动自动运行 fortune|lolcat|cowsay」一项即降到 ~271ms（快 2.4 倍）。其余慢点集中在 compinit/compaudit 补全扫描，已通过 ZSH_DISABLE_COMPFIX、去重重复加载、清理死配置进一步收敛。全部优化不损失任何功能，改动均带 [OPT] 标记。

1. 配置体系地图

flowchart TD
    A[zsh 启动] --> B[.zshenv<br/>cargo env]
    B --> C[.zprofile<br/>仅登录 shell<br/>brew shellenv / OrbStack / pipx]
    C --> D[.zshrc<br/>交互式 shell]
    D --> E[p10k instant prompt]
    E --> F[brew shellenv]
    F --> G[Oh My Zsh 框架<br/>plugins: z git history brew sudo ...]
    G --> H[~/.zsh/paths 细分路径]
    H --> I[~/.zsh/functions 自定义函数]
    I --> J[compinit 补全初始化<br/>最大开销所在]
    J --> K[zsh-autocomplete + fzf-tab]
    K --> L[别名 / Vi 模式 / 历史]
    L --> M[p10k 主题]
    M --> N[❌ 旧版：每日箴言自动运行<br/>✅ 优化版：改为按需 qotd()]

2. 启动耗时构成（实测）

实测环境：hyperfine --warmup 2 --runs 5 'zsh -i -c exit'；耗时追踪用 zsh -ixc exit 2>&1 | ts -i '%.s' | sort -rn | head -20。

版本	平均启动耗时	用户态	系统态
优化前（原始 .zshrc）	714.9 ms（次轮 652.3 ms）	272.7 ms	387.7 ms
仅移除自动每日箴言	270.9 ms	123.0 ms	120.7 ms

启动耗时分布（估算，基于 -x 追踪与进程数）

compinit/compaudit 补全扫描  ██████████████████████████  约 60-70%（系统态高）
每日箴言 fortune|lolcat|cowsay ████████                    约 20-25%（3 个子进程）
Oh My Zsh + p10k + 其余       ████                        约 10-15%

pie title 优化前启动耗时构成（估算）
    "compinit/compaudit 扫描" : 65
    "每日箴言 3 进程" : 22
    "OMZ + p10k + 其他" : 13

说明：测试沙箱中无法写入 ~/.zcompdump，两次对比都走了 compinit 全量扫描路径，因此绝对数值偏大、但相对节省量真实可信。你本机有正常缓存时，优化后的实际数值会更低。

3. 优化点清单

#	优化点	问题	影响	处理
1	每日箴言自动运行	每次开 shell 都 fork `fortune \| lolcat \| cowsay` 3 个子进程	实测省 ~380ms（启动减半以上）	改为按需函数 `qotd()`，`# qotd` 注释即恢复
2	compaudit 安全扫描	冷启动时对 2000+ 补全文件做权限审计（追踪 TOP 慢点全在这）	冷启动数百 ms	`export ZSH_DISABLE_COMPFIX=true`（OMZ 官方支持，可一键还原）
3	ghcup env 加载 3 次	`.zshrc` 顶部 + 底部 + `env_path.sh` 各一次	重复 IO 与 PATH 追加	统一收敛到 `~/.zsh/paths/env_path.sh`
4	direnv hook 加载 2 次	`.zshrc` 底部与 `env_path.sh` 重复 eval	双倍 hook 开销	保留 `env_path.sh` 一份
5	perl5 环境块 2 份	`.zshrc` 底部与 `env_path.sh` 重复	重复 export	保留 `env_path.sh` 一份
6	补全 menu zstyle 冲突	先 `menu select` 后 `menu no`，后者覆盖前者，死配置	无功能损失但易误导	只保留 fzf-tab 需要的 `menu no`
7	autosuggestions 死变量	`ZSH_AUTOSUGGEST_*` 已设置，但插件从未加载	无效配置	注释保留，附启用说明
8	`alias .. =cd ..` 空格 bug	等号两侧有空格，别名实际不生效	`..` 回上级目录失效	修正为 `alias ..='cd ..'`
9	历史策略冲突	`appendhistory` 与 OMZ 的 `INC_APPEND_HISTORY` 冲突	历史追加行为不确定	统一为 `INC_APPEND_HISTORY SHARE_HISTORY`
10	`echo` 改 `print -n`	precmd/preexec 用 echo 输出光标控制序列	闪烁与额外开销	改用 `print -n`
11	autojump 残留加载	`/usr/local/etc/profile.d/autojump.sh` 是 Intel 时代路径（本机不存在），OMZ 插件已覆盖	死代码	移除

已经做得很好的部分（保留不动）：nvm 懒加载、kubectl 懒补全、.zcompdump 24 小时缓存策略、typeset -U path fpath 去重、p10k instant prompt。这些是标准做法，无需改动。

4. 复现与验证

# 1. 启动耗时基准
hyperfine --warmup 3 'zsh -i -c exit'

# 2. 定位启动慢点（Top 20）
zsh -ixc exit 2>&1 | ts -i '%.s' | sort -rn | head -20

# 3. 精确分析（zprof）：临时在 .zshrc 顶部打开 zmodload zsh/zprof，底部执行 zprof
zmodload zsh/zprof   # 顶部
zprof               # 底部，退出前输出耗时表

5. 应用优化（三步走）

# 0) 备份
cp ~/.zshrc ~/.zshrc.bak-20260811

# 1) 用优化版替换（文件在 outputs/zshrc.optimized；先 diff 确认差异）
diff -u ~/.zshrc /path/to/zshrc.optimized | less
cp /path/to/zshrc.optimized ~/.zshrc

# 2) 重建补全缓存并重启
rm -f ~/.zcompdump* && exec zsh

# 3) 验证：功能检查 + 启动时间复测
zsh -ixc exit 2>&1 | ts -i '%.s' | sort -rn | head -20
hyperfine --warmup 3 'zsh -i -c exit'

想完全还原：cp ~/.zshrc.bak-20260811 ~/.zshrc && exec zsh。

6. 其他文件的小改（可选）

文件	修改	原因
`~/.zsh/paths/env_path.sh`	`LC_ALL="en_US.UTF-8"` 重复两行，删一行	重复赋值
`~/.zsh/paths/env_path.sh`	`HOMEBREW_SSL_NO_VERIFY=1`	⚠️ 安全项：关闭了 Homebrew 全部 TLS 证书校验。若 USTC 镜像证书正常，建议删除并实测 `brew update`；若必须保留，至少知晓风险
`~/.zsh/paths/lang_rust.sh`	其中的 `source ~/.cargo/env` 与 `.zshenv` 重复	重复加载；保留 `.zshenv` 一份即可（非交互 shell 也需要）

7. 结论

本次优化没有删除任何功能：箴言变成按需调用、补全冲突收敛、重复加载去重、两处 bug 修复。核心收益在启动速度：实测单项优化即可把 715ms 压到 271ms，叠加 compinit 与去重优化后预期进入 200ms 以内（以你机器 zprof 实测为准）。优化后的 .zshrc 全文与原始版 diff 已随文档归档，可随时对照或还原。

2026-08-11 下午计划

2026-08-11T00:00:00+00:00

待办

进行中

已完成

博客- 热力图迭代

@start 2026-08-11 @due 2026-08-11 @priority 3 @goal complete @labels orange, sky @bg orange @top orange @cover full

222
3333

修复单日多博客可滚动选择跳转问题
更新最后一个单元格为当日, 往前获取近35天内博客数据

博客-看板迭代

@start 2026-08-11 @due 2026-08-11 @priority 1 @goal complete @bg red @top sky

看板仿 Trello
置顶功能搁置, 似乎实现不了 ?

进度

08-11 周二

验证01
验证0222

资源

目标

Homebrew 回退到历史版本：以 zola 0.22.1 为例

2026-08-06T00:00:00+00:00

Homebrew 回退到历史版本：以 zola 0.22.1 为例

TL;DR: 任何包管理器装“旧版本“都只能是固定快照——apt 装旧包、Homebrew 装历史公式都一样，因为 homebrew/core 里的 zola 永远只有最新版，旧版本天然无法“自动升级“。正确的姿势是：装旧版时用本地 tap 装历史公式，想升级时切回 core 的新公式，两步就回来了。

1. 背景：为什么要回退

zola 0.23.0 是破坏性版本（Tera v2：宏 / 短代码被替换为组件语法）。如果正在使用的主题（如 Ametrine）还没适配 0.23，站点会直接构建失败：

ERROR Failed to render page content of ...
ERROR Reason: error: `load_data`: ... doesn't exist

此时最稳妥的做法是暂时留在 0.22.1，等主题适配后再升级。

2. 为什么不能直接 `brew install` 旧版本

homebrew/core 的每个公式只有一个定义，永远指向最新稳定版，没有 zola@0.22.1 这种版本化公式；
旧版本公式只存在于 homebrew-core 的 git 历史中，需要“捞“出来；
新版 Homebrew 不允许直接安装游离的本地 .rb（brew install ./zola.rb 会报 Homebrew requires formulae to be in a tap）；
Homebrew 官方推荐的做法是 brew extract 到自己的 tap；本文用手动方式做等价操作，每一步都看得见。

3. 回退：安装 zola 0.22.1

3.1 从 homebrew-core 历史取公式文件

Formula/z/zola.rb 在提交 da70294 时对应 0.22.1（公式里 url 为 v0.22.1.tar.gz，sha256 为 0f59479e…）：

cd ~/Downloads
curl -fsSL -o zola.rb \
  "https://raw.githubusercontent.com/Homebrew/homebrew-core/da702940397d32e261f7e1a577555f7d49929a31/Formula/z/zola.rb"

3.2 放进本地 tap 再安装

brew tap-new --no-git local/zola-old
TAP_DIR="$(brew --prefix)/Library/Taps/local/homebrew-zola-old"
mkdir -p "$TAP_DIR/Formula"
cp ~/Downloads/zola.rb "$TAP_DIR/Formula/zola.rb"
brew install local/zola-old/zola
brew pin zola

验证：

zola --version          # zola 0.22.1
brew list --versions zola

几点说明：

公式自带 bottle（arm64 Tahoe/Sequoia/Sonoma 等），匹配的 macOS 直接下载预编译包；其他平台自动走源码编译（会自动装 rust，稍慢）；
brew pin zola 防止手滑 brew upgrade 把 zola 升走；
公式的 url/sha256 指向官方 v0.22.1 源码包，来源可靠。

3.3 备选：完全不管 brew 的临时方案

如果旧版只是临时用一下、之后 brew 永远保持最新版，也可以直接放官方二进制到 ~/.local/bin（这条脱离 brew 管理，不适合“想统一用 brew 管理“的需求）：

cd ~/Downloads
curl -OL https://github.com/getzola/zola/releases/download/v0.22.1/zola-v0.22.1-aarch64-apple-darwin.tar.gz
tar -xzf zola-v0.22.1-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin && mv zola ~/.local/bin/zola

（Intel 机器把文件名换成 zola-v0.22.1-x86_64-apple-darwin.tar.gz）

4. 升级：切回最新版

brew unpin zola
brew untap local/zola-old
brew upgrade zola        # 从 homebrew/core 拿最新版

万一 upgrade 有残留报错：

brew uninstall zola && brew install zola

结论： “升级能力“没有丢，只是它不在旧版本快照里，而在“随时可以切回 core“这个动作里。这正是 Homebrew 官方对“安装旧版本“的标准做法（brew extract 到自己的 tap），手动复制 .rb 只是等价实现。

5. 何时升级：等主题完全支持 0.23.0

zola 0.23.0 属于破坏性版本，主题需要把旧的宏 / 短代码迁移到新组件语法才能兼容。在正在使用的 Zola 主题（如 Ametrine）完全支持 0.23.0 之前，建议保持 0.22.1 不要升级；等主题适配完成、站点用 0.23.x 构建无报错后，再执行第 4 节的升级命令。

CMake 未来项目预研内容

2026-07-28T00:00:00+00:00

在 macOS 平台上使用 LLVM/Clang + CMake 构建中大型 C++ 项目（尤其是在金融量化、高频交易、计算密集型等对性能、稳定性和工程化要求极高的工业场景），行业内的工具链和工程范式在近年来已经发生了非常显著的升级。

除了你提到的基础套装（clang-format、clang-tidy、GoogleTest），目前工业界主流的中大型 C++ 工程架构通常围绕以下几个核心维度进行搭建：

1. 构建速度与编译加速（Build Acceleration）

对于中大型 C++ 项目，编译速度直接决定研发效率。

Ninja 替代 Make / Xcode 项目文件
- 在 CMake 配置时使用 -G Ninja。Ninja 的并行依赖调度比传统 Make 快得多，几乎是当前 C++ 工业界的标准 Generator。
ccache / sccache
- 作用： 编译结果本地/分布式缓存。配合 CMake 使用：set(CMAKE_CXX_COMPILER_LAUNCHER ccache)。
- 效果： 切分支或 clean build 时，90% 以上的增量编译可以实现秒级完成。
预编译头文件（PCH, Precompiled Headers）
- 利用 CMake 3.16+ 原生支持的 target_precompile_headers。将 <vector>, <string>, <memory>, boost 等通用常用头文件预编译，通常能提升 30%~60% 的编译速度。
LLVM LLD 链接器
- 在 macOS 上，默认的 ld64 在处理巨大符号表时较慢。可以尝试设置 -fuse-ld=lld 使用 LLVM 的 lld，能大幅缩短大型目标文件的 Link 时间。

2. 包管理与依赖控制（Dependency Management）

告别手动下载或依赖系统全局安装库（如 Brew 安装导致的版本冲突），现代化项目讲究自包含与确定性构建。

vcpkg 或 Conan 2.x
- 目前 vcpkg（微软主导）和 Conan 2.0 是业界两大主力。通过 vcpkg.json 或 conanfile.txt 声明依赖版本，实现跨平台/跨团队的零成本环境复现。
CMake FetchContent + CPM.cmake
- 对于轻量级依赖或内部私有 Git 仓库，结合 CMake 3.14+ 的 FetchContent 或其封装库 CPM.cmake，实现构建时动态拉取和按需编译，避免将第三方代码直接 Commit 到源码库中。

3. 动态运行时分析与内存安全（Sanitizers & Dynamic Analysis）

在金融/量化等领域，内存泄露、并发竞态（Data Race）或未定义行为（UB）是致命的。Clang 原生集成的 Sanitizers 是最强大的防御线：

ASan (AddressSanitizer)： 检测内存越界访问、内存泄露、Use-After-Free。
TSan (ThreadSanitizer)： 专门检测多线程代码中的数据竞态（Data Race），金融高并发系统必开。
UBSan (UndefinedBehaviorSanitizer)： 检测整数溢出、空指针解引用等未定义行为。
MSan (MemorySanitizer)： 检测读取未初始化的内存。

工程落地范式： 在 CMake 中增加 Option，如 -DENABLE_SANITIZER_ADDRESS=ON。要求 CI/CD 流水线中所有的单元测试必须在开启 ASan/TSan 的环境下运行通过。

4. 静态代码分析与代码质量控制（Static Analysis & Quality Control）

除了基本的 clang-tidy，工业界还会叠加多重防护：

Include-What-You-Use (IWYU)
- 配合 CMake 运行：set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "include-what-you-use")。分析项目头文件，自动移除冗余的 #include，防止头文件膨胀拖慢编译速度。
cppcheck / SonarQube
- 作为 clang-tidy 的补充，提供更多的规则集（如 MISRA C++ 标准）和安全漏洞扫描。
pre-commit 框架
- 使用 Python 的 pre-commit 工具挂载 Git Hooks，在开发者本地 git commit 时自动触发 clang-format 和简易静态检查，防止脏代码提交到远程仓库。

5. CMake 项目架构范式（Modern CMake Paradigm）

现代 CMake（CMake 3.20+）的写作风格已完全走向 基于 Target 的面向对象范式：

Strict Target/Property Scope（严禁全局污染）
- 废弃全局的 include_directories() / link_libraries()。
- 全部使用 target_include_directories()、target_link_libraries()，并严格区分 PUBLIC / PRIVATE / INTERFACE 传递属性。
CMakePresets.json 标准化
- CMake 3.19 引入的标准。在项目根目录下放置 CMakePresets.json，定义统一的 Debug/Release 配置、编译器路径、构建目录。
- 开发者在终端直接运行 cmake --preset debug 或在 VS Code/CLion/Xcode 中一键选择 preset，实现团队环境的无缝统一。
支持 C++ Modules (C++20/23)
- CMake 3.28+ 对 C++20 Modules 提供了正式支持。在新项目中，逐步用 Module 替换传统头文件，从根源上解决头文件重复解析的问题。

1. 语言服务与 IDE 开发体验（Language Server Protocol）

过去大家习惯用 Xcode 生成项目或用 VS Code 插件粗暴扫描，现在全行业基本上都在向 clangd 靠拢。

clangd + compile_commands.json
- 地位： LLVM 官方出品的 LSP 服务端，目前在代码补全、跳转、重构和实时错误提示上全面超越传统的 C/C++ 插件。
- 落地范式： 搭配 CMake 的 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)，生成 compile_commands.json 软链接到项目根目录。所有开发者（无论用 VS Code、Neovim 还是 CLion）都能享受毫秒级的精确代码分析与符号跳转。

2. 运行时性能剖析与诊断（Profiling & Benchmarking）

在金融与高频领域，“能跑通”只是第一步，“跑得有多快、延迟波动多大”才是核心竞争力。

Google Benchmark
- 作用： C++ 微基准测试（Microbenchmarking）的标准工具。
- 场景： 针对关键算法、数据结构（如无锁队列、定点数计算）编写性能测试代码，输出精确的 CPU 时间、内存带宽以及 Iterations/sec。可以集成到 CI 中防止性能退化（Performance Regression）。
macOS 原生工具链：Instruments / dtrace
- 在 macOS 上，不需要再去折腾 Linux 的 perf。直接使用 Xcode 自带的 Instruments（尤其是 Time Profiler, Allocations, System Trace），在图形界面中查看 CPU 缓存缺失（Cache Miss）、锁竞争以及指令周期（IPC）。
Tracy Profiler
- 作用： 极低开销的实时帧/事件 Profiler（带超强 GUI）。
- 场景： 相比于传统的抽样 Profiler，Tracy 支持在代码中注入微秒级 Mark，实时观察多线程协同、事件循环（Event Loop）延迟和内存分配轨迹，非常适合低延迟/高吞吐系统。

3. 测试维度的深度扩展（Advanced Testing Strategies）

除了普通的单元测试，现代工程还会加入以下两类强化手段：

模糊测试（Fuzzing）—— libFuzzer / AFL++
- 作用： 给你的 API 输入随机生成的海量变异数据，强行引发 Crash、内存越界或逻辑未定义。
- 落地： LLVM 原生集成了 libFuzzer（通过 -fsanitize=fuzzer 编译），专门用于解析器、网络协议包、数据序列化/反序列化（如 FIX 协议、Protobuf）的健壮性测试。
属性/基于策略的测试（Property-Based Testing）—— RapidCheck
- 作用： 类似 Haskell 的 QuickCheck。你只需要定义“这个函数的输入与输出应该满足什么数学属性”，工具会自动生成上万组边缘边界条件（例如极值、空值、非法组合）进行验证。

4. 依赖安全性与二进制可追溯性（Supply Chain & Observability）

Doxygen + Breathe + Sphinx / MkDocs
- 现代 C++ 项目不再直接看裸露的文档网页。主流做法是用 Doxygen 提取头文件注释生成 XML，再通过 Breathe 接入 Sphinx/MkDocs，构建出类似 Stripe / Rust 官方文档一样精美且可检索的 API 站点。
SBOM (Software Bill of Materials) 与依赖安全扫描
- 金融合规与安全防护的要求。配合 Conan 2.x 或 vcpkg，在构建时自动导出 SBOM 文件，并通过 trivy 或 grype 扫描第三方库是否存在已知漏洞（CVE）。

5. 极致加速：模块化与分布式构建（Next-Gen Build Systems）

如果你的项目达到了百万行级别，单机 ccache + Ninja 依然无法满足秒级编译：

BuildBuddy / Bazel
- 虽然 CMake 是行业通用标准，但在很多超大型金融量化巨头内部，会逐步转向 Bazel。 Bazel 依靠严格的“沙盒机制”保障绝对的构建确定性（Hermetic Builds），并天然支持分布式远程编译与全局缓存（Remote Build Execution, RBE）。
FASTBuild
- 如果依然保留 CMake，可以借助 FASTBuild 作为 Backend，实现跨局域网多台机器协同编译。

总结：现代 C++ 项目工程化“全家桶”一览

维度	基础工具（你已提到）	现代化演进补充 (2023-2026 工业落地)
代码格式与风格	`clang-format`	`pre-commit` hook 自动化触发
静态代码分析	`clang-tidy`	`Include-What-You-Use` (IWYU), `clangd` 实时 LSP
单元测试	`GoogleTest`	`Google Benchmark` (微基准), `libFuzzer` (模糊测试)
动态分析与内存	-	Sanitizers全家桶 (`ASan`/`TSan`/`UBSan`)
构建与加速	CMake	CMake + Ninja + ccache + CMakePresets
包与依赖管理	手动 / Brew	vcpkg / Conan 2.x / `FetchContent`
性能诊断	-	macOS Instruments, Tracy Profiler

3. 强化测试与代码鲁棒性（Fuzzing & Advanced Testing）

单元测试（GoogleTest/Catch2）只能覆盖“开发者能想到的边界”，而现代工程会引入模糊测试（Fuzzing）**与**属性测试（Property-based Testing）。

libFuzzer / AFL++ (American Fuzzy Lop)
- 作用： Clang 原生集成的结构化模糊测试工具（基于 -fsanitize=fuzzer）。
- 场景： 自动化生成数百万种变态的畸形输入数据（如网络报文解析、协议解码器、JSON/FIX 协议解析），结合 ASan 自动捕捉 Crash 和潜在的溢出漏洞。
Catch2 / doctest
- 在新建项目中，很多团队正在用 Catch2 v3 或 doctest 替代 GoogleTest。它们支持更现代的 BDD 语法（GIVEN / WHEN / THEN），且 doctest 的编译速度极快。

4. 依赖安全性与代码防腐（Dependency Guardrails）

include-cleaner
- LLVM 官方出品的新一代头文件清理工具（clang-tidy 的衍生组件），比旧版的 IWYU 更精准，能自动标注未使用的头文件以及缺失的直接依赖头文件。
mold (Linker)
- 虽然 macOS 上默认推荐 LLVM lld 或 Xcode 的 ld64/new-ld，但在 Linux/macOS 交叉编译或容器构建场景下，mold 是目前业界公认最快的链接器，能将几秒到几分钟的链接时间缩短至毫秒级。

5. 编译期检查与现代化语言规范

static_assert + C++20 Concepts
- 范式改变： 淘汰过去复杂的 SFINAE 模板黑魔法。全面使用 C++20 的 concept 和 requires 子句来约束模板参数。不仅编译错误信息变得极其人性化，而且能将大量的类型检查提前到编译期完成。
constexpr / consteval 静态计算
- 将金融业务中的静态查找表（LUT）、协议哈希计算、常量配置提前在编译期生成，做到零运行时开销（Zero-overhead abstraction）。

6. 现代 C++ 最佳工程实践清单总结

如果将现代中大型 C++ 工程的质量防护体系比作流水线，它的完整形态通常是：

阶段	采用工具 / 范式	解决的核心问题
代码编写	`clangd` + `clang-format` + `pre-commit`	统一代码规范、拼写与风格，防止低级错误进入仓库
构建管理	CMakePresets + Ninja + `ccache` + vcpkg	一键跨平台配置、秒级增量编译、依赖确定性
编译检查	Strict Warnings (`-Wall -Werror`) + C++20 Concepts	编译期拦截潜在 Bug 与模板滥用
动态测试	GTest / Catch2 + ASan / TSan / UBSan	运行期捕捉内存泄露、野指针与多线程数据竞态
质量安全	`libFuzzer` + Google Benchmark	自动发现隐蔽崩溃点，防止性能退化

现代化链接器替代

mold (或 sold/Apple ld64 优化版)
- 由 Rui Ueyama 开发的下一代链接器 mold 是目前速度最快（近乎达到硬件 I/O 极限）的链接器。在 macOS (ARM64/x86_64) 上，使用现代链接器替代旧版 ld，可以将大型金融系统的增量链接时间从十几秒压缩到 1 秒以内，极大提升 Edit-Compile-Test 循环体验。

2. 现代性能 Profiling 与内存追踪（金融量化核心）

在金融高频交易或低延迟服务中，性能调优不能靠猜，必须依靠低开销的 Sampling（采样）与 Frame-based Profiling。

Tracy Profiler
- 目前游戏界和量化界极具口碑的实时帧/低延迟 Profiler。侵入性极低，支持 CPU 线程甘特图、内存分配（Allocations）、锁竞争（Lock Contention）以及硬件 PMU 指标分析。
Perfetto (Google)
- 支持跨平台的系统级追踪分析，能够把 C++ 业务逻辑、OS 系统调用以及内存堆分配打通在一张 Web 时间轴图表中。
mimalloc / jemalloc / tcmalloc 替代与分析
- 金融系统很少直接使用系统默认的 malloc（在 macOS 上是 libSystem 的 malloc）。工业界常采用 Microsoft mimalloc 或 jemalloc，配合内存分配分析工具（如 bytehound），实现无锁高并发内存分配并精确追踪内存碎片。

3. 代码生成与 RPC / 序列化架构

中大型工程往往涉及跨语言（C++ 与 Python/Rust）调用，或者分布式节点通信。现代工程范式倾向于数据结构驱动代码生成。

FlatBuffers / Cap’n Proto
- 在金融行情/交易系统等要求 Zero-Copy（零拷贝）的场景中，逐渐取代传统的 Protocol Buffers。它们允许直接在内存缓存区中读取结构体，无需昂贵的 Unpack/Deserialize 过程。
reflect-cpp / C++20 反射过渡方案
- 在 C++26 静态反射正式落地前，目前工业界广泛采用基于 C++20 的编译期反射库（如 reflect-cpp），用极低的编译期开销自动生成 JSON/CBOR 的序列化与反序列化代码，淘汰手工编写的模板代码。

4. 自动化模糊测试（Fuzz Testing）

对于金融交易系统或处理外部非信任数据（如 API 报文解析、网络协议栈）的模块，传统的单元测试只能覆盖“已知边界”，而 Fuzzing 能跑出大量的“未知崩溃”。

libFuzzer (Clang 集成) / Honggfuzz
- 落地范式： 配合 -fsanitize=fuzzer,address 编译旗标。让 Fuzzer 自动生成随机输入向量，高强度轰炸解析函数。在 CI/CD 中定期（如夜间构建）运行 Fuzzing 测试，能提前拦截 90% 以上的内存越界与崩溃漏洞。

3. 现代化代码质量与安全范式

除了静态检查（clang-tidy），现代 C++ 更强调在编译期和代码设计层面将错误杜绝。

IWYU (Include-What-You-Use)
- 用来清理头文件包含循环和冗余依赖。直接集成到 CMake：set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "include-what-you-use")。大型 C++ 项目经常通过清理 #include 将整体编译时间缩短 40% 以上。
Coverage 报告工具 (llvm-cov + gcovr)
- 在使用 Clang 构建时，加上 -fprofile-instr-generate -fcoverage-mapping。
- 结合 llvm-profdata 和 llvm-cov 生成 HTML 覆盖率报告（或集成到 Codecov/SonarQube），强制要求新代码的单元测试覆盖率达到 80%+。
Contract-Based Programming (契约式编程/断言体系)
- 在金融系统中，虽然 C++26 的 Contracts 标准还在演进，但工业界普遍使用类似 gsl::Expects() / gsl::Ensures() 或自研的强力断言系统（Assertion System），在 Debug/Sanitizer 构建中强制 Crash，在 Release 构建中通过分支预测优化 (like [[likely]]) 去除开销。

1. 现代化自动化测试与验证工具（超越传统 GTest）

虽然 GoogleTest 依然是行业标准，但在追求极致安全和高吞吐量的工业场景下，单靠手动编写的单元测试远远不够：

Fuzz Testing（模糊测试：libFuzzer / LLVM-Fuzz）
- 适用场景： 解析器、网络协议栈（如 FIX 协议、自定义二进制 RPC）、数据序列化模块。
- 落地范式： 利用 Clang 原生的 -fsanitize=fuzzer。Fuzzing 引擎会自动生成海量的变异边界数据注入你的函数，结合 AddressSanitizer（ASan）自动捕捉非常隐蔽的空指针、内存越界和崩溃点。
Property-Based Testing（基于属性的测试：RapidCheck）
- 概念： 类似于 Rust 社区的 QuickCheck 或 Python 的 Hypothesis。
- 优点： 你不需要手动写具体的 EXPECT_EQ(a, b)，而是声明“属性规则”（例如：“不管输入什么数组，排序算法输出的结果必须递增”），测试框架会自动生成几万组极限边界用例来寻找打破规则的反例。

2. 核心架构设计与工程范式（Modern C++ Paradigms）

为了在大型项目中减少人造成的 Bug，工业界正在推行一种在编译期就把错误杜绝的编码设计范式：

放弃 C++ Exception，全面转向 `std::expected` / `tl::expected`

工业背景： 在高频金融或低延迟系统中，try-catch 带来的栈展开（Stack Unwinding）开销是不可接受的，且隐式抛出异常会导致代码执行路径难以预测。
落地范式： 采用 C++23 的 std::expected<T, E>（或 C++20 下的 tl::expected），将“错误”作为显式返回值类型返回。强制调用方必须显式处理错误，从设计层面解决未捕获异常崩溃的问题。

C++

// 现代 C++ 显式错误处理示范
auto result = parse_financial_packet(buffer);
if (!result) {
    log_error(result.error()); // 编译期提醒必须处理 Error
    return;
}
use_payload(*result);

强类型封装（Strong Types / Opaque Typedefs）

痛点： 传统代码中容易混淆含义相同的基本类型，比如 void place_order(int price, int quantity)，调换参数顺序编译依然能过。
解决方案： 使用强类型库（如 named_type 或内嵌轻量 struct 封装）：

C++
```
place_order(Price{100}, Quantity{500}); // 传反参数直接报编译错误
```

3. 高级静态分析与深度漏洞扫描（比 clang-tidy 更深）

当代码库规模达到数十万甚至上百万行时，普通的 AST 规则匹配（clang-tidy）很难捕捉跨文件、跨函数的深层逻辑缺陷：

PVS-Studio / Klocwork / SonarQube（商业级全栈扫描）
- 能力： 具备跨文件的数据流追踪（Data Flow Analysis）**和**污染分析（Taint Analysis）。例如：从网络 socket 读入的未清洗数据（Taint Input），经过层层传递最终作为数组下标使用，这类复杂漏洞只有商业级 SAST 才能精准识别。
CppDepend（架构可视化与依赖治理）
- 作用： 专门分析 C++ 项目结构。它可以将代码包、类之间的循环依赖转化为依赖矩阵（DSM），帮助架构师监控代码腐化、防止高层模块反向依赖底层实现。

4. 大型项目构建与 CI/CD 优化

随着项目膨胀，CMake 自身可能也会遇到性能瓶颈：

分布式构建（BuildBuddy / Remote Execution）
- 对于极大型 C++ 项目，本地 8 核/16 核 CPU 编译依然缓慢。金融大型团队会部署 Remote Build Execution (RBE) 集群，将编译任务并发分发到云端上百个 Node 同步编译，将半小时的 Build 缩短至几十秒。
Bazel 构建系统（替代 CMake 的备选项）
- 在 Google、Meta 以及部分头部量化巨头中，如果项目属于庞大的 Monorepo（单体大仓库），通常会用 Bazel 替代 CMake。Bazel 的依赖图判定极其严格且具备强大的分布式缓存能力，能做到绝对准确的“增量构建”。

在中大型 C++ 项目（尤其是在高频量化、金融系统、游戏引擎、实时渲染与分布式计算）中，如果我们跳出传统的“编译-测试-静态检查”三板斧，目前业界（2024–2026年）在极致性能优化、内存分配策略、ABI 稳定性治理、供应链安全与分布式调试等深水区领域，还有以下非常落地且硬核的现代工程工具与范式。

1. 运行时内存分配与缓存优化（Memory & Cache Operations）

对于对延迟和吞吐极其敏感的中大型系统，C++ 默认的 malloc/free（或 macOS 系统原生的 malloc）会带来严重的内存碎片和锁竞争，也是造成系统 Latency Spike（延迟毛刺）的罪魁祸首。

Mimalloc (微软) / JeMalloc (Meta) / TCMalloc (Google)
- 落地方案： 现代化项目通常会强行替换系统的内存分配器。在 CMake 中链接 mimalloc 或 jemalloc，或者通过 DYLD_INSERT_LIBRARIES 注入。
- 效果： 在多线程高并发场景下，直接提升 10%~30% 的整体内存吞吐量，同时大幅降低内存碎片。
自研/定制定制化 Allocator (std::pmr)
- 使用 C++17 引入的 PMR (Polymorphic Memory Resource)。对于局部短生命周期的大量临时对象（如交易引擎处理单笔订单），直接使用 std::pmr::monotonic_buffer_resource 在栈上或提前分配好的 Arena 内存池中高速分配，几乎零开销，且避免频繁触发系统调用。

2. 编译期与二进制层面优化（PGO & BOLT）

对于性能要求达到“微秒级”的中大型系统，单纯开 -O3 已经不够用了。现代工业界会通过反馈驱动优化（Profile-Guided Optimization）来挖掘 CPU 的极限。

PGO (Profile-Guided Optimization)
1. 第一阶段： CMake 加上 -fprofile-generate 构建二进制。
2. 第二阶段： 运行真实的生产线/仿真压力测试数据，生成 .profraw 运行轨迹。
3. 第三阶段： 用 llvm-profdata 汇总数据，再以 -fprofile-use 重新构建。
- 原理与效果： LLVM 会根据真实运行轨迹，自动优化分支预测（Branch Prediction）、重新编排 Basic Block 顺序以最大化 CPU L1 Instruction Cache Hit Rate，通常能获得 5%~15% 的无套利性能提升。
LLVM BOLT (Binary Optimization and Layout Tool)
- 定位： Meta 开源的二进制后优化工具。在 PGO 构建出二进制文件后，BOLT 在二进制汇编级别重新编排函数和代码块位置，降低 CPUTLB miss 和 Instruction Cache miss。

3. 供应链安全与二进制依赖治理 (SBOM & ABI Safety)

在中大型金融与工业级软件中，开源合规与供应链安全已提升到前所未有的高度。

SBOM (Software Bill of Materials，软件物料清单)
- 利用 Syft 或 vcpkg/Conan 自动导出 SPDX / CycloneDX 格式的 SBOM 文件。明确记录当前项目编译出的二进制文件中包含了哪些开源库、什么版本、什么 License（防止 GPL 污染）。
ABI / API 兼容性检测 (abi-compliance-checker / libabigail)
- 对于以动态库（.dylib / .so）形式对外交付的 C++ 基础设施项目，使用 libabigail（abidiff）在 CI 流水线中检查新旧版本之间的二进制 ABI 是否破坏。防止因隐式修改了类成员变量顺序或虚函数表（vtable）导致下游调用方崩溃。

4. 全局跨语言与分布式分布式跟踪（Tracing & Telemetry）

对于服务化、微服务化或复杂管道式的中大型 C++ 架构，崩溃和性能瓶颈往往不在单个 C++ 进程内。

OpenTelemetry C++ SDK (OTel)
- 概念： 云原生时代的分布式链路追踪标准。
- 落地： 在 C++ 关键函数和跨网络 RPC 节点中植入 OpenTelemetry Spans，将性能轨迹、日志与指标统一推送到 Jaeger / Datadog 等平台。让你清晰看到“从客户端发起请求，到 C++ 核心引擎处理，再到写盘”的完整耗时拓扑图。
Sentry C++ SDK / Crashpad
- 定位： 生产环境崩溃（Crash）捕获与符号化报告。
- 利用 Google 的 Crashpad 机制，当 C++ 程序在客户现场或生产服务器发生 Segfault 崩溃时，后台进程会自动捕获 Minidump 堆栈文件，自动上传到内部 Sentry 服务器，并通过 symbolicate 工具还原出崩溃发生的具体文件和行号。

在航天航空（Aerospace）、国防、医疗器械、自动驾驶以及核工业等对安全性、可靠性有“零容忍（Mission-Critical / Safety-Critical）”要求的行业中，对 C++ 的使用范式与普通互联网或金融高频交易有很大区别。

在这些行业，“性能最高”往往要让位于“行为绝对可预测（Deterministic）”。以下是这些行业在 LLVM/Clang + CMake 体系下落地的核心规范、限制与工程实践：

1. 行业顶级编码标准（Coding Standards）

在航天和安全敏感领域，你写的每一行 C++ 都必须通过合规性扫描（Compliance Check）。

MISRA C++:2023
- 地位： 目前安全关键领域的 “天花板”标准。2023 版将旧版的 MISRA C++:2008 与汽车业的 AUTOSAR C++14 进行了全面合并，专门针对 C++17 进行了重构。
- 核心理念： 彻底杜绝 C++ 语言中的未定义行为（Undefined Behavior, UB）、隐式类型转换、复杂多重继承等安全隐患。
DO-178C (DAL A/B) 指南
- 地位： 机载航空系统（如飞控、航电）软件认证的国际标准。
- 要求： 代码不仅要通过测试，还需要提供从 需求 -> 架构 -> 源代码 -> 汇编代码 的 100% 双向追溯性（Traceability）。
NASA JPL C++ Coding Standard (喷气推进实验室规范)
- NASA JPL 著名的“安全关键代码十条规则”（The Power of Ten Rules）：
  1. 限制所有控制流为简单的结构（禁用递归，确保所有循环有固定的上界）。
  2. 变量作用域尽可能最小化。
  3. 必须检查所有函数的返回值。
  4. 限制指针的使用层级（禁止双重指针/多级指针）。

2. 内存与运行时的“禁忌”与设计模式

为了保证系统在连续运行几年甚至几年内绝对不崩溃、不卡顿，航天级 C++ 规范对语言特性做出了极严苛的剥离：

彻底禁用动态内存分配（No `malloc` / No `new`）

为什么： 动态内存分配会导致内存碎片化（Memory Fragmentation），并在不可预知的时间点引发不确定的分配耗时（Non-deterministic Time）。
落地范式：
- 所有内存必须在系统启动的初始化阶段（Initialization Phase）一次性静态分配好，主循环运行期（Runtime Phase）严禁分配或释放内存。
- 使用 std::array 或类似 etl::vector（Embedded Template Library）替代 std::vector，容器容量必须在编译期确定（Fixed Capacity）。

禁用 C++ 异常（No Exceptions: `-fno-exceptions`）

为什么： C++ 异常处理机制（try-catch）的栈展开过程会导致无法预测的执行时间，且会隐式增加大量的二进制体积。
落地方案： 编译选项强制开启 -fno-exceptions。错误处理全面采用显示返回值模式（如前文提到的 std::expected 或状态码）。

禁用 RTTI（No Runtime Type Information: `-fno-rtti`）

为什么： 避免 dynamic_cast 带来的运行期虚表查找开销与不确定性，减少虚函数表 overhead。

3. 覆盖率与测试极高标准（MC/DC 覆盖率）

在常规工业界，代码覆盖率达到 80% 的行覆盖（Line Coverage）已经算优秀；但在航天级（如 DO-178C DAL-A 级别）项目中，测试覆盖率必须达到 MC/DC（Modified Condition/Decision Coverage，修正条件/判定覆盖） 100%。

什么是 MC/DC： 不仅要求每个函数、每行代码被跑过，还要求复合条件判断中的每一个独立条件在其他条件不变的情况下，能够单独影响最终的判定结果。
LLVM 工具支持：

使用 Clang 编译器的源码级覆盖率工具：

Bash
```
clang++ -fprofile-instr-generate -fcoverage-mapping ...
llvm-profdata merge ...
llvm-cov show ./binary -instr-profile=... -show-branches=count
```
配合 Polyspace, Helix QAC 或 VectorCAST 等专业工具输出审计合规报告。

4. 形式化验证与高级分析（Formal Verification）

在极端敏感场景，传统的“编写单元测试”被认为不足以证明代码 100% 正确，航天领域会引入形式化验证（Formal Verification）。

抽象解释（Abstract Interpretation）
- 工具如 Polyspace Bug Finder / Code Prover。
- 它利用数学公式证明你的代码在所有可能的输入组合下，都绝对不会发生：除零错误、缓冲区溢出、数组越界、空指针解引用。
硬件在环测试（HIL - Hardware-in-the-Loop）
- 配合 CMake 的构建流水线，代码编译完成后自动烧录至真实的 SoC 芯片（如 Xilinx Zynq、RISC-V 航天级芯片或 PowerPC），并在模拟器模拟的极热、极冷、高辐射环境下运行抗干扰测试。

5. 航天/安全级 CMake 与项目工程范例

在安全敏感项目中，CMake 的编写同样需要符合“可重复构建（Reproducible Build）”和“严谨性”要求：

CMake

cmake_minimum_required(VERSION 3.25)
project(AerospaceControlSystem LANGUAGES C CXX)

# 1. 强制确定性编译（去除编译路径差异，保证二进制构建结果 100% 一致）
add_compile_options(-ffile-prefix-map=${CMAKE_SOURCE_DIR}=.)

# 2. 剥离运行时不确定特性
add_compile_options(
    -fno-exceptions      # 禁用异常
    -fno-rtti            # 禁用 RTTI
    -fno-threadsafe-statics # 禁用局部静态变量的隐式加锁保护（防止死锁）
)

# 3. 开启最严格的警告，将一切警告视为错误
if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
    add_compile_options(
        -Wall -Wextra -Werror
        -Wconversion         # 阻止隐式缩窄转换
        -Wshadow             # 阻止变量作用域遮蔽
        -Wcast-qual          # 阻止指针 const 属性被强转剥离
        -Wdouble-promotion   # 警告 float 隐式转为 double（航天 FPU 性能损耗点）
    )
endif()

# 4. 集成 MISRA C++ / 静态检查分析门槛
set(CMAKE_CXX_CLANG_TIDY
    "clang-tidy;--checks=-*,misra-c++2023-*,bugprone-*,cert-*"
)

总结比较：普通工业 vs 航天安全敏感领域

维度	普通工业/金融高频	航天/航空/安全敏感领域
优先目标	极低延迟、高吞吐、快速迭代	绝对确定性、零故障、可预测
内存管理	Mimalloc / PMR 内存池 / Arena	零动态分配 (No Heap) / 编译期静态分配
错误处理	`std::expected` / 异常捕获	禁用 Exception，强校验返回值 / 降级策略
代码规范	Google C++ Style / Modern C++	MISRA C++:2023 / NASA JPL 10 条禁律
测试标准	行覆盖率 / 分支覆盖率 (~80%)	100% MC/DC 覆盖率 + 形式化数学证明

在航天航空、国防、医疗器械、自动驾驶和核工业等高安全与高可靠性（Safety-Critical）*领域，代码设计的核心哲学是*“把不确定性（Non-determinism）在编译期彻底抹杀”。

在 LLVM/Clang + CMake 现代架构下，这些领域除了严格限制语言特性外，还有以下极其深度的工程落地范式：

1. 替代 STL 的零堆内存标准库（Fixed-Capacity Containers）

由于 std::vector、std::unordered_map 等 STL 容器依赖堆内存（Heap）并在扩容时重新分配，这在安全敏感领域是绝对禁忌。工业界普遍采用编译期静态容量容器。

ETL (Embedded Template Library)
- 定位： 安全领域替代/补充标准 STL 的行业标杆库。
- 用法： 使用 etl::vector<T, Capacity> 替代 std::vector<T>。内存直接分配在栈上或 .bss 静态数据段中，完全禁用 malloc / free。
- 优点： 保持了类似 STL 的迭代器与算法接口，同时在编译期锁定最大内存边界。
std::array + std::span (C++20)
- 现代 C++ 代码中，函数参数传递严禁使用指针和引用偏移，统一采用 std::span 进行边界安全的连续内存视图传递。

2. 状态机与控制流的严格限制（No Dynamic Flow）

在飞控系统或医疗泵控制逻辑中，复杂的 if-else 或嵌套循环极易隐藏未覆盖的分支条件。

编译期确定界限（Bounded Loops）
- 禁止出现 while(true) 或没有显式上限的 while(condition) 循环。
- 所有循环必须写成固定次数上限的形式，防止死循环导致看门狗（Watchdog）触发系统复位：
C++
```
// 航天级规范循环示范
constexpr size_t MAX_SENSOR_RETRIES = 10;
for (size_t i = 0; i < MAX_SENSOR_RETRIES; ++i) {
    if (try_read_sensor()) break;
}
```
表驱动 / 形式化有限状态机（FSM）
- 业务逻辑必须重构成明确的状态转换矩阵（State Transition Matrix），通过 std::variant + std::visit 在编译期进行状态穷尽性检查（Exhaustive Matching）。如果少处理了一个状态，编译器直接报错。

3. 乱序执行与硬件层面的确定性（Memory Barriers & Volatile）

在核工业控制或高辐射环境中，除了软件逻辑错误，还需要抵御硬件故障（如单粒子翻转 Single Event Upset, SEU）。

数据三模冗余（TMR - Triple Modular Redundancy）

原理： 关键变量（如当前轨道姿态控制参数）在内存中同时存放 3 份，每次读取时进行“三选二”表决（Majority Voting）。
代码范式：

C++

template <typename T>
class RedundantVar {
    T val1, val2, val3;
public:
    T get() const {
        if (val1 == val2) return val1;
        if (val1 == val3) return val1;
        return val2; // 自动纠正单粒子翻转（SEU）带来的比特位突变
    }
};

指令重排控制（Compiler Barriers）
- Clang 的优化器非常强大，但在配合内存映射 I/O（MMIO）读写硬件寄存器时，代码重排可能导致致命后果。代码中会大量引入 std::atomic_thread_fence(std::memory_order_seq_cst) 或 asm volatile("" ::: "memory") 来约束 Clang 优化器的指令重排。

4. 自动化软件验证工具链（Toolchain Validation）

在 DO-178C / ISO 26262 认证中，“不仅你的代码要有保障，你用来编译代码的编译器本身也必须是安全可靠的”。

Compiler Qualification（编译器鉴定）
- 你不能随意从网络下载一个开源版的 LLVM/Clang 直接编译飞控软件。需要使用通过认证的商业级安全 Clang 编译器（例如 Tasking、Green Hills 或 Solid Sands 的 SuperTest 工具包认证后的 Clang）。
- 原理： 运行数百万个严格的语言边界测试集，证明当前 Clang 编译出的机器码汇编与 C++ 源码语义 100% 严格一致，没有编译优化带来的额外 Bug。
静态分析门槛：自动导出 SARIF 格式
- CMake 构建过程中集成静态分析，生成标准的 SARIF (Static Analysis Results Interchange Format) 文件，直接挂载到 CI 门的合规性审计系统中，做到“有警告即拒绝构建”。

5. 现代安全级项目整体工作流架构

Plaintext

 C++20/23 源码 (禁用 Exception, RTTI, Heap Memory)
   │
   ├── 编码设计: ETL 容器 + std::expected + 三模冗余 (TMR)
   │
   ├── 编译期拦截 (Clang + MISRA C++:2023 / NASA JPL 规则集)
   │     ├── -Werror (警告转错误)
   │     ├── -fno-exceptions -fno-rtti
   │     └── Clang-Tidy (SARIF 自动化输出)
   │
   ├── 形式化验证与抽象解释 (Polyspace / Helix QAC)
   │     └── 验证：彻底排除除零、越界、死循环
   │
   ├── 测试覆盖率检查 (llvm-cov)
   │     └── 必须满足：100% MC/DC (修正条件/判定覆盖)
   │
   └── 硬件在环测试 (HIL - Hardware-in-the-Loop)
         └── 烧录至真实板卡，进行高低温、辐射模拟与看门狗喂狗测试

在这种工程范式下，C++ 不再是一个追求“灵活与便利”的语言，而是一个被极其严格的规则围墙圈起来的、具备高度数学确定性的硬核系统描述工具。

在安全性敏感与高可靠性行业（Safety-Critical Systems），除了严格限制 C++ 的语言子集（禁用动态内存、禁用异常、遵从 MISRA C++:2023）之外，整个软件工程生命周期、编译器基础设施、代码运行机制都有着非常独特的工业落地范式。

继续深入来看，这些行业在 LLVM/Clang + CMake 体系以及硬件落地层面，还有以下极具代表性的工程设计：

1. 编译器合格化认证（Compiler Qualification / Safety Manual）

在普通行业，我们可以随意升级到最新的 Clang 18 或 GCC 14；但在航天、汽车（ISO 26262）和医疗（IEC 62304）行业，编译器本身被视为潜在的故障源。

安全认证编译器（Qualified Compilers）
- 落地工具： 工业界通常不会直接使用未认证的开源 Clang，而是使用经过安全认证的商业化 LLVM/Clang 发行版，如 Solid Sands SuperTest 测试套件认证过的编译器，或者 HighTec / Tasking Toolset（基于 Clang 的车规/航天级编译器）。
Safety Manual（安全手册遵守）
- 编译器厂商会随工具链提供一份《Safety Manual》，其中明确规定了哪些编译器优化选项（Optimization Flags）是安全的。例如：禁止开启 -Ofast 或某些可能改变浮点数精度的指令重排优化，只允许在特定可预测的优化级别（如 -O2 或特定指令集裁剪选项）下运行。

2. 软硬件冗余与“看门狗”架构设计（Redundancy & Fail-Safe）

单一代码库再完美，也无法抵御宇宙射线导致的比特翻转（Single Event Upset, SEU）或硬件老化。因此，代码架构设计上必须建立容错与降级机制：

双工 / 三工模冗余 (2oo2 / 2oo3 TMR Architecture)
- 落地范式： 关键控制逻辑（如飞控系统）由 3 个独立的硬件通道（可以是 3 块相同的 DSP/FPGA 或不同架构的 CPU）同时运行同一段 C++ 代码。在 CMake 中会将代码编译为 3 个独立构建的目标，运行时通过 表决器（Voter） 对输出结果进行“少数服从多数”的裁决。如果某一通道出现逻辑偏差或死锁，立刻剥离该通道。
状态机硬上限与 Watchdog（看门狗）超时
- 主循环必须严格遵从 Deterministic Execution Window（确定性时间窗口）。每一个 Task（任务）都有严格的 Worst-Case Execution Time (WCET，最坏情况执行时间) 预算。
- 如果在指定的微秒数内，C++ 任务没有向硬件 Watchdog 定时器“喂狗”，硬件看门狗将直接复位 CPU 或切入 Safe-Mode（安全降级模式）。

3. 硬件/底层接口隔离范式（Hardware Abstraction & Defensive C++）

在极高可靠性系统中，C++ 扮演着连接硬件寄存器与上层算法的桥梁，这要求对硬件访问做出极致的安全防御：

使用 volatile 与内存映射 I/O（MMIO）的严谨封装
- 禁止使用原始指针直接读取内存映射寄存器。必须通过强类型、模板化的寄存器抽象层（Register Abstraction Layer）进行读写，防止编译器对硬件状态的读取进行过度的“优化消除”。
防乱序与内存屏障（Memory Barriers）
- 在多核航天级芯片或 DMA 传输控制中，即使禁用多线程，也要显式插入 LLVM 内建屏障指令（如 __builtin_arm_dmb(15) 或 asm volatile("" ::: "memory")），防止 CPU 乱序执行导致硬件指令生效顺序错乱。

4. 自动化 Traceability（需求-代码-测试 100% 链路追溯）

在 DO-178C 或 ISO 26262 审核中，最耗费工程师精力的往往不是写代码，而是证明“每一行 C++ 代码都有据可查，且被测试覆盖”。

DO-178C 追溯标注范式
- 在 CMake 项目的头文件和源文件中，所有的类和关键函数都必须带有符合 Traceability 工具（如 ReqIF / Doors / Jama）识别的注释标签：

C++

/**
 * @brief 计算飞控舵机偏转角
 * @requirement REQ-AERO-2026-0812  <-- 对应软件需求文档编号
 * @safety_level DAL-A
 * @verification TEST_SUITE_SERVO_003
 */
int32_t calculate_actuator_angle(const SensorData& sensor_input) noexcept {
    // 逻辑实现...
}

构建自动化关联
- 利用 CMake 在构建阶段运行 Python/Clang-AST 扫描脚本，提取代码中的需求 ID。如果有任何新增代码没有关联需求 ID，或者有需求没有对应的 C++ 单元测试用例，构建流水线（CI）直接中断并报错。

5. 基于属性与模型的自动代码生成（Model-Based Design & CodeGen）

在现代航天（如 SpaceX、NASA）和汽车控制领域，最为核心的控制算法（如姿态控制、轨迹规划）往往不是工程师手写 C++ 的，而是通过模型自动生成的：

Simulink / Embedded Coder -> C++ 自动化导出
- 控制算法工程师在 MATLAB/Simulink 中建立数学模型并通过仿真验证。
- 使用 Embedded Coder 生成符合 MISRA C++ 规范的 C++ 代码，并直接丢进 CMake 项目工程中进行编译。
手动 C++ 代码的角色
- 软件工程师主要编写 手写 C++ 框架，负责系统初始化、驱动适配、通信协议栈、安全监控（Safety Monitor）以及将自动生成的控制算法代码“粘合”起来。

航天/安全级 C++ 体系结构全貌

Plaintext

               ┌──────────────────────────────────────────────┐
               │         上层控制需求 (Doors / Jama)          │
               └──────────────────────┬───────────────────────┘
                                      │ (双向追溯标签)
               ┌──────────────────────▼───────────────────────┐
               │  模型/手写 C++ (符合 MISRA C++:2023 / JPL 规范)│
               └──────────────────────┬───────────────────────┘
                                      │ (禁止 Heap / 异常 / 多重继承)
               ┌──────────────────────▼───────────────────────┐
               │    静态验证/形式化证明 (Polyspace / VectorCAST)│
               └──────────────────────┬───────────────────────┘
                                      │ (100% MC/DC 覆盖率)
               ┌──────────────────────▼───────────────────────┐
               │   通过 Safety Manual 认证的 LLVM/Clang 工具链 │
               └──────────────────────┬───────────────────────┘
                                      │ (确定性编译选项 & WCET 计算)
               ┌──────────────────────▼───────────────────────┐
               │     2oo3 三工模硬件 / 硬件看门狗 (Fail-Safe)   │
               └──────────────────────────────────────────────┘

这种“近乎偏执”的工程约束，虽然牺牲了现代 C++ 的部分灵活度与开发速度，但换来的是在极端的太空辐射、剧烈震动和高压环境下，系统依然能够零故障连续运行数年乃至数十年的绝对可靠性。

在中大型 Safety-Critical（航天/国防/核工业/车规自动驾驶）系统中，除了编译器认证、容错硬件和确定性内存策略外，工程体系的演进目前正在发生深层次的变革。

结合 2024–2026 年现代 C++ 工业界的最新发展，在对安全性与可靠性“零容忍”的领域，还有以下几项极其关键且正在大规模落地的高级工程范式与硬核技术：

1. C++ 与 Rust 的混合安全架构（C++ / Rust Interop）

这是当前安全敏感行业（尤其是自动驾驶、新一代国防与航天地面系统）最显著的趋势之一：用 Rust 编写新安全模块，并与现有百万行 C++ 代码库无缝缝合。

为什么产生： 即使有 MISRA C++，C++ 的内存安全（Memory Safety）依然依赖工程师的自觉。美国 NSA、CISA 及各大国防/车规巨头都在推动向内存安全语言过渡。
落地范式（CXX / cbindgen）：
- 利用 cxx（Rust/C++ 互操作库），在 C++ 和 Rust 之间建立编译期强类型绑定，无需编写繁琐且易错的 C 风格 FFI 接口。
- 在 CMake 项目中，通过 Corrosion（CMake 的 Rust 集成插件）将 Rust 编写的安全核心（如加密模块、网络解析器、状态机）直接作为 CMake Target 链接进 Clang 构建流水线。

2. 运行时栈安全与指令集级防护（Hardware-Assisted Security）

在极高安全级别的系统中，代码不仅要防逻辑 Bug，还要防硬件层面的恶意攻击或辐射导致的物理篡改（如缓冲区溢出攻击、ROP 攻击）。现代 Clang 编译器提供了指令集级别的安全防御能力：

Shadow Call Stack (SCS / -fsanitize=shadow-call-stack)
- 原理： 在 LLVM 编译时，将函数的返回地址（Return Address）额外备份在一个不可读取的硬件“阴影栈”中。当函数返回时对比两个栈的值，如果因为缓冲区溢出导致栈破坏，立刻触发硬件中断。
Control Flow Integrity (CFI / -fsanitize=cfi)
- 原理： LLVM 的控制流完整性校验。防止攻击者通过破坏虚函数表（vtable）或函数指针，强行跳转到未授权的代码区域（如跳转到危险的系统指令）。
Stack Canaries & Stack Clash Protection (-fstack-protector-strong)
- 强制在栈帧中插入随机保护金丝雀值（Canary），在每个函数返回前校验，彻底杜绝栈越界攻击。

3. 硬件最坏情况执行时间（WCET）计算与微架构分析

在航天和实时控制中，如果一个 C++ 函数绝大多数时候执行耗时 10 微秒，但因为 CPU Cache Miss 或分支预测失败，偶发耗时 200 微秒，这就叫 Non-deterministic（不可确定），在硬实时系统中是致命的。

抽象解释与微架构分析工具（如 AbsInt aiT）
- 流程： 工具直接读取 LLVM/Clang 编译出的二进制文件，配合目标芯片（如 ARM Cortex-R5/R8、PowerPC 或 RISC-V）的微架构模型（Pipeline, Cache, Memory Bus）。
- 效果： 给出该段 C++ 代码在数学上绝对不可能超过的最坏执行时间（WCET），并指出哪几行 C++ 代码会导致严重的 CPU Cache 缺失，指导工程师精细化重构。

4. 浮点数 determinism（跨平台绝对一致性）

在轨迹计算、姿态演算等数学密集型航天算法中，即使相同的 C++ 代码，在不同编译器、不同 CPU 指令集（如 x86 AVX 与 ARM Neon）或不同优化级别下，浮点数计算结果的最后几位小数可能会有微小差异。在大尺度航天计算中，这种微小差异会在几千公里外放大成巨大偏差。

严格 IEEE 754 模式（Strict Floating-Point Standard）
- 禁用项： 严禁使用 -ffast-math 或 -funsafe-math-optimizations。
- 编译选项： 在 Clang 中显式配置 -fno-fast-math -ffp-model=strict，强制要求编译器完全按照 IEEE 754 规范顺序执行浮点运算，禁用可能改变精度的指令合并（如某些隐式的 FMA 指令重排）。
软浮点（Soft-Float）与定点数（Fixed-Point Arithmetic）
- 对于极端敏感的核控制或飞控核心算法，甚至会放弃 CPU 的硬件浮点运算单元（FPU），使用 C++ 模板编写 定点数类（Fixed-Point Class），彻底消除不同硬件 FPU 带来的浮点不确定性。

5. 跨团队/供应链的“防污染”CMake 隔离范式

在国防和大型航天工程中，项目通常由数家不同研发单位共同开发。如何防止下游单位写的“垃圾代码”污染整个主工程的质量？

在 CMake 架构中，现代工业界采用了非常严格的隔离手段：

CMake

# 针对第三方或子系统代码强制设置安全沙箱
add_subdirectory(third_party/subsystem_a)

# 1. 强行屏蔽第三方代码库抛出的警告，防止干扰主代码编译
target_include_directories(subsystem_a SYSTEM PRIVATE ...)

# 2. 对特定外部依赖关闭某些不合规的编译选项
set_target_properties(subsystem_a PROPERTIES
    COMPILE_FLAGS "-w" # 忽略第三方警告
)

# 3. 强制在主工程链接阶段扫描未定义符号与隐藏依赖
set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--no-undefined")

极高安全等级 C++ 工程落地全景路线图

如果你要带领团队搭建一套完全符合现代安全敏感行业标准的 C++ 项目体系，你的全套基础设施可以概括为以下五道防线：

第一道防线（代码编写期）： ISO/MISRA C++:2023 规范 + clangd + 禁止动态内存/异常 + std::expected / Rust 安全组件扩展。
第二道防线（静态与形式化验证）： Clang-Tidy (MISRA 规则集) + Polyspace 抽象解释（证明绝对无 UB、无除零、无溢出）。
第三道防线（编译构建期）： 认证版 LLVM/Clang + -fno-exceptions -fno-rtti + -fsanitize=cfi,shadow-call-stack + 100% MC/DC 覆盖率测试。
第四道防线（二进制与时间分析）： 二进制 WCET 最坏执行时间数学演算 + IEEE 754 严格浮点确定性控制。
第五道防线（硬件运行期）： 2oo3 三工模硬件表决 + 硬件看门狗超时强行降级安全模式（Fail-Safe）。

在前面讨论的“确定性控制、代码硬隔离、硬件安全防护、Rust 混合架构”基础之上，如果将视角进一步延伸到 2024–2026 年最前沿的现代 C++ 工业实践，在航天、国防、医疗器械、核工业及自动驾驶等领域，工程范式正在从“事后验证与测试”向“编译期安全与数学级证明”全面演进。

以下是行业内正在落地、极具推荐价值的高级工程实践与工具链选择：

1. 编译期语法安全与元编程（Compile-Time Safety & Metaprogramming）

在安全敏感领域，最安全的代码是根本不需要在运行时运行的代码。利用 C++20 / C++23 的 constexpr / consteval 和模板元编程，可以将极多的运行时逻辑、物理单位换算以及状态机校验彻底移到编译期。

1.1 物理单位编译期类型检查（SI Units / Compile-Time Dimensions）

痛点： 历史上最著名的航天惨剧之一——NASA 火星气候轨道器（Mars Climate Orbiter）失事，原因就是一方使用的是英制单位（磅·秒），而另一方使用的是公制单位（牛顿·秒），数据直接传递导致轨道计算错误。
推荐方案： 引入强类型的物理单位库（如 mp-units，即 C++26 强类型单位标准提案的实现库）。
效果： 试图把“米”赋值给“秒”，或者将“力”和“速度”直接相加，在编译期就会报错，且运行时零性能开销。

C++

#include <mp-units/systems/si/si.h>

using namespace mp_units::si::unit_symbols;

// 强类型参数定义
void apply_thrust(mp_units::quantity<N> force, mp_units::quantity<s> duration) {
    // ...
}

int main() {
    // apply_thrust(100 * m, 5 * s); // 编译直接报错！无法将 'm' (米) 传给 'N' (牛顿)
    apply_thrust(100 * N, 5 * s);    // 编译通过
}

1.2 编译期零开销状态机（Compile-Time Finite State Machine, FSM）

推荐方案： 使用 Boost.SML 或基于 C++20 强类型实现的编译期 FSM。
优势： 传统的 switch-case 或状态模式容易漏掉未定义的转换状态。编译期 FSM 能在构建阶段对状态转换矩阵进行穷举校验。如果定义了无效的状态跳转（例如“直接从 INIT 跳到 LAUNCH 忽略了 CHECK”），编译器拒绝生成二进制。

2. 基于 LLVM/Clang 的定制化 Domain-Specific Checks（领域自定义检查）

只用 Clang-Tidy 内置的 MISRA 规则往往不够，因为每个航天或医疗项目都有自己特定的架构约束（例如：“所有通信报文序列化类必须包含 checksum() 方法”或“禁止在驱动层调用任何标准库头文件”）。

推荐实践：编写自定义 LibTooling / Clang Plugin

利用 LLVM 的 LibTooling API，针对项目编写专属的 Clang 语法树（AST）扫描插件：

AST Matchers 编写： 捕获不符合项目内部架构规约的代码模式。

集成到 CMake：

CMake

# 将自定义 Clang 插件挂载到 CMake 编译指令中
add_compile_options(-Xclang -load -Xclang ${CMAKE_BINARY_DIR}/libMySafetyPlugin.so)

落地效果： 在开发者点击编译的瞬间，对违规的项目专属逻辑弹出编译器级别的 Fatal Error，阻止非法架构蔓延。

3. 高高级静态断言与自愈式代码设计（Defensive Execution & Fail-Safe）

即使在静态分析阶段做到了极致，硬件层面的不可抗力（如粒子翻转导致内存比特位变异，Bit Flip）依然可能发生。因此，代码本身的自我防御（Defensive Programming）至关重要：

3.1 内存魔法数与数据校验（Magic Numbers & Poisoning）

在关键的 C++ 类或结构体头部加入魔数校验字段（Magic Word / Canary）：

C++

struct SensorPayload {
    uint32_t header_magic = 0xDEADBEEF; // 固定的结构有效性魔数
    float altitude;
    float velocity;
    uint32_t crc32;                     // 内存数据 CRC 校验码
};

运行时防御： 函数在处理该结构体前，必须先校验 header_magic 和 crc32。如果发现被内存翻转污染，拒绝继续执行并直接抛出硬件中断，切入安全降级分支。

3.2 变量三决 redundancy（Software-Based TMR）

在没有硬件三模块冗余（TMR）支持的低成本航天/车规节点上，可以采用软件级三重冗余存储：

C++

template<typename T>
class SafetyValue {
private:
    T v1, v2, v3; // 同一变量在不同内存偏移处备份三次
public:
    T get() const {
        if (v1 == v2) return v1;
        if (v1 == v3) return v1;
        if (v2 == v3) return v2;
        // 三个值都不一致，说明遭遇了严重硬件比特翻转！触发安全自愈或紧急降级
        trigger_safety_fault_handler();
    }
};

4. 落地建议：现代安全敏感项目的整体工程推荐矩阵

如果想为你的团队引入最符合当下趋势的优秀设计与规范，推荐按照以下分层路线逐步配置：

维度	推荐引入工具 / 范式	预期收益
语言规范	MISRA C++:2023 + NASA JPL 10 条禁律	彻底排除隐式类型转换、死循环与未定义行为
物理/逻辑安全	`mp-units` + `Boost.SML`	编译期杜绝单位算错、非法状态跳转
内存与并发	`etl` (Embedded Template Library)	替代 `std::vector`，做到零动态堆分配
定制扫描	LLVM LibTooling Custom Plugins	自动化强制约束项目专属的架构规则
静态验证	Polyspace Code Prover / SonarQube	获得除零、越界、空指针的 100% 数学证明
硬件安全	Clang `-fsanitize=cfi,shadow-call-stack`	硬件指令层防控制流篡改与栈破坏
测试硬指标	VectorCAST / Sonar (达到 100% MC/DC)	满足航天 DO-178C DAL-A 级软件审计要求

在把语言子集裁切（MISRA）、编译期计算（constexpr/mp-units）、形式化证明（Polyspace）、定制化 Clang 插件与硬件级安全（CFI/Shadow Call Stack）*都配置到位后，现代 Safety-Critical（航天、车规、核能、国防）行业在 2024–2026 年的工程前沿，开始聚焦于*“系统级确定性（Deterministic System Design）”、“软硬件协同分析”以及“基于大模型的安全审计与形式化代码生成”。

以下是这一领域的最新深度落地推荐与核心工程范式：

1. 编译期确定性编排与时间沙盒（Time-Triggered Architecture, TTA）

在极端敏感的实时控制系统中，传统的“多线程/抢占式 OS 调度”被认为具有不确定性（线程切换时刻不可预测、死锁概率不为零）。

时间触发架构（TTA）
- 范式： 放弃传统的事件驱动（Event-Driven）和抢占式调度，转向绝对时间触发。整个系统的所有 C++ 任务被划分在极度严格的离散时间片（Time Slots）内。
- 编译期排程： 使用 CMake 在构建阶段调用离线排程算法，为每一个 C++ 模块生成一份静态执行表（Schedule Table）。
- 时间沙盒（Execution Sandboxing）： 结合芯片的硬件定时器（如 ARM Generic Timer），如果某个 C++ 任务的执行时间超过了分配的微秒级时间片，硬件将触发不可屏蔽中断（NMI），强行将该任务挂起并记录故障日志，确保后续其他关键任务的时间绝对不受影响。

2. 基于 LLVM IR 的全局跨模块指令级追踪（Cross-Translation-Unit LLVM Pass）

仅仅在 C++ 源码层做检查（如 AST Matchers）有时无法发现由编译器优化导致的隐患。现代安全团队正在深度利用 LLVM 架构的中间表示（LLVM IR）：

自定义 LLVM Opt Pass
- 落地场景： 编写在 LLVM IR 级别运行的自定义分析 Pass，在优化阶段之后、汇编生成之前介入。
- 检查项：
  1. 隐式指令膨胀检查： 检查编译器是否自动生成了未预期的昂贵浮点指令或复杂的隐式函数调用。
  2. 死代码与未达路径彻底擦除： 确保安全敏感模块编译出的 IR 中不存在任何可能被利用的未初始化跳转分支。
  3. 寄存器清零（Data Wiping Pass）： 在安全密码学或核心控制逻辑函数返回前，利用 LLVM Pass 自动插入寄存器和栈空间重写指令，防止密钥或敏感状态留在 CPU 寄存器中。

3. 基于模型的自动代码生成与 AI 驱动的“安全级重构”

在 SpaceX、NASA 等新一代航天公司中，自动化与大模型（AI Agents）正在改变 Safety-Critical 代码的编写范式：

Simulink/Stateflow 到 C++20 的合规代码自动生成
- 工业界正在从手写复杂状态机彻底转向“模型驱动（Model-Based Design）”。使用严格约束的生成器（如 MathWorks Embedded Coder），直接导出 100% 符合 MISRA C++:2023 标准的现代 C++20/23 代码。
AI + 形式化验证 Agent（AI-Assisted Formal Verification）
- 2025–2026 最新实践： 将 AI Agents（基于 LLVM 编译上下文）集成到 CI/CD 流水线中。当工程师提交 C++ 代码时，AI Agent 不仅检查语法，还会自动提取代码的逻辑约束，并尝试用 Z3 SMT Solver（定理证明器）生成形式化数学证明，或者自动撰写符合 DO-178C 审计要求的规范文档。

4. 软件定义硬件与 RISC-V 航天级指令拓展（Custom ISA & C++ Bindings）

随着 RISC-V 在国防、航天以及汽车电子领域的快速崛起，C++ 工程正在与自定义硬件指令紧密结合：

C++ 内建函数与自定义指令的绑定
- 在特定航天级 RISC-V 芯片上，硬件工程师会设计专门针对“三模冗余校验”、“矩阵运算”或“CRC 硬件加速”的自定义指令集。
- 在 C++ 代码中，通过 Clang 的 __builtin_riscv_* 或内联汇编将这些底层硬件指令直接映射为 C++ 的内联函数。CMake 会自动感知硬件平台的指令集扩展标志（-march=rv64gc_zXcustom），实现最高效率且绝对确定性的硬件级控制。

5. 极高安全 C++ 研发全生命周期链条（End-to-End Safety Pipeline）

最终，将这所有的优秀实践连结起来，构成了一个能够应对航天、深空探测、核设施等零容忍场景的现代化 C++ 项目范式矩阵：

Plaintext

       ┌─────────────────────────────────────────────────────────┐
       │ 1. 需求与建模: Jama / DOORS + Simulink MBD 自动生成 C++20│
       └────────────────────────────┬────────────────────────────┘
                                    │
       ┌────────────────────────────▼────────────────────────────┐
       │ 2. 源码级约束: MISRA C++:2023 + mp-units (物理单位编译校验) │
       │                + etl (零堆内存) + std::expected         │
       └────────────────────────────┬────────────────────────────┘
                                    │
       ┌────────────────────────────▼────────────────────────────┐
       │ 3. 静态与形式化证明: LibTooling 自定义插件 + Polyspace   │
       │                      + Z3 形式化数学推理 (证明零 UB)     │
       └────────────────────────────┬────────────────────────────┘
                                    │
       ┌────────────────────────────▼────────────────────────────┐
       │ 4. 编译器级安全: 认证版 LLVM/Clang + 自定义 IR Pass     │
       │                  + Shadow Call Stack + CFI 控制流保护   │
       └────────────────────────────┬────────────────────────────┘
                                    │
       ┌────────────────────────────▼────────────────────────────┐
       │ 5. 目标机与硬件: 时间触发架构(TTA) + 2oo3 TMR 三模硬件表决  │
       │                  + 硬件看门狗 + 100% MC/DC 覆盖率测试   │
       └─────────────────────────────────────────────────────────┘

如果你正在规划或重构一个极高可靠性的 C++ 工业/航天项目，建议以 “零动态内存”、“编译期强类型/物理单位校验”、“100% MC/DC 覆盖” 以及 “LLVM 自定义安全分析 Pass” 作为首批落地的核心突破口。

理解了！前面的讨论确实偏向了航天、国防等极限安全领域。对于大多数通用但追求高品质、高可维护性、高编译效率的中大型 C++ 项目（如中大型桌面软件、高性能后端服务、量化引擎、游戏服务端等），我们不需要那些过于苛刻的规范（比如禁用堆内存或写形式化数学证明），而是需要兼顾“工程效率”与“代码质量”的现代通用最佳实践。

下面为你梳理一套现代（2023年至今）通用且优秀的中大型 C++ 项目的标准范式与工具链组合：

1. 现代化构建与工具链基础设施（Build & Tooling）

在中大型项目中，项目配置的规范性直接决定了团队协作的顺畅度。

CMakePresets.json（项目入口标准化）
- 作用： 解决“在我的电脑上能编，在别人电脑上编不过”的问题。
- 范式： 项目根目录下放一个 CMakePresets.json，把 Debug/Release 配置、编译器路径、生成目录统一写好。开发者无论是用 CLI、VS Code、CLion 还是 Xcode，只需选择 Preset，一键构建。
ccache + Ninja（开发体验提升首选）
- 方案： CMake 配置 -G Ninja，并开启 set(CMAKE_CXX_COMPILER_LAUNCHER ccache)。
- 效果： 团队日常切分支、增量编译的等待时间通常能从数分钟缩短到数秒。
CPM.cmake / vcpkg（轻量级依赖管理）
- 范式： 放弃在代码库里放 .a / .dylib 二进制库，推荐使用 CPM.cmake（基于 FetchContent 的轻量封装）。只需几行 CMake 代码，就能在编译阶段自动下载、构建第三方依赖（如 spdlog, fmt, nlohmann_json），非常干净。

2. 代码编写与现代 C++ 规范（Modern Coding Paradigms）

现代 C++（C++20/23）提供了许多能显著提升表达力和代码安全性的内置特性：

全面采用 std::expected / std::optional 处理错误
- 范式： 放弃使用 C 风格的错误码（如返回 -1）或抛出复杂的 Exception。用 std::expected<T, E>（C++23）显式表达“成功返回 T，失败返回 Error”。
- 优势： 强制调用方在编译期关注错误处理，逻辑清晰且无运行时异常开销。
采用 fmt (或 std::format) 替代 std::cout / printf
- 优势： 类型安全、编译期校验格式化字符串、性能远超 std::cout。
使用 clangd + .clangd 文件作为统一 IDE 引擎
- 范式： 在根目录放一个配置文件 .clangd，在里面统一开启 ClangTidy 诊断、未使用的 #include 自动提示（Unused Includes）等，让团队所有人的编辑器行为保持一致。

3. 代码质量与自动化拦截（Quality Control & Pre-commit）

把代码检查做成无感自动化，不给开发者增加心理负担。

pre-commit 自动化框架
- 落地： 使用 Python 的 pre-commit，在本地 .git/hooks/pre-commit 挂载任务。
- 效果： 在开发者执行 git commit 的那一刻，自动跑一遍 clang-format 修复格式、检查是否不小心提交了数 MB 的大文件或敏感配置，有问题直接在本地拦截。
静态分析三件套（CMake 零侵入配置）
- clang-tidy（代码潜在逻辑漏洞检查）
- include-what-you-use (IWYU)（自动清理无用的头文件，缩短编译时间）
- 在 CMake 中开启基础但严谨的编译警告：-Wall -Wextra -Wshadow -Wconversion，并将警告当成错误处理（-Werror）。

4. 自动化测试与动态分析（Testing & Sanitizers）

保证代码质量最省力的方式是“自动化”，而不是人工 Code Review。

Catch2 或 Doctest（比 GoogleTest 更现代化）
- 优点： 相比于 GoogleTest 的繁重，Catch2 / Doctest 支持 Header-only 或非常轻量级的引入，语法更加现代化，支持 BD-style（GIVEN, WHEN, THEN）测试写作，对现代 CMake 整合非常友好。
Sanitizers 作为 CI 的标准步骤
- 无需安装复杂软件，只需在构建时加上编译标志：
  - -fsanitize=address (ASan)：抓取野指针、内存越界、内存泄露。
  - -fsanitize=undefined (UBSan)：抓取整数溢出、空指针等未定义行为。
- 范式： 本地正常开发，但在 GitHub Actions / GitLab CI 自动化测试流水线中，强制在开启 Sanitizer 的模式下跑完所有单元测试。

5. 一个通用、现代化的项目文件结构范例

Plaintext

my_cpp_project/
├── CMakeLists.txt              # 主配置文件（干净、基于 Target 组织）
├── CMakePresets.json           # 统一的构建预设 (Debug/Release/ASan)
├── .clang-format               # 代码格式化规范
├── .clang-tidy                 # 静态代码检查规则
├── .clangd                     # 语言服务器 (clangd) 配置
├── .pre-commit-config.yaml     # Git 提交前自动化检查
├── cmake/
│   └── CPM.cmake               # 依赖自动化管理脚本
├── include/my_project/         # 对外暴露的头文件
├── src/                        # 核心业务实现代码
│   ├── CMakeLists.txt
│   └── main.cpp
└── tests/                      # 单元测试代码
    ├── CMakeLists.txt
    └── test_main.cpp

极简且优雅的主 `CMakeLists.txt` 参考

CMake

cmake_minimum_required(VERSION 3.22)
project(MyModernProject VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 自动生成 compile_commands.json 给 IDE / clangd 用
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# 1. 自动启用 ccache 编译加速
find_program(CCACHE_PROGRAM ccache)
if(CCACHE_PROGRAM)
    set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
endif()

# 2. 引入自动依赖管理 CPM
include(cmake/CPM.cmake)

# 引入现代化第三方库示例 (自动下载管理)
CPMAddPackage(
    NAME fmt
    GITHUB_REPOSITORY fmtlib/fmt
    GIT_TAG 10.1.1
)

CPMAddPackage(
    NAME Catch2
    GITHUB_REPOSITORY catchorg/Catch2
    GIT_TAG v3.4.0
)

# 3. 添加源代码子目录
add_subdirectory(src)

# 4. 自动化测试开关
if(BUILD_TESTING)
    enable_testing()
    add_subdirectory(tests)
endif()

总结落地清单

对于绝大多数通用优秀 C++ 项目，你只需要引入这几样东西，工程质量和研发体验就会有质的飞跃：

构建与依赖： CMakePresets.json + Ninja + ccache + CPM.cmake
代码体验： clangd + C++20 + std::expected + fmt
自动化拦截： pre-commit (跑 clang-format) + CI 中跑 ASan / Catch2 单测

在放弃了“禁用动态堆内存”、“写形式化证明”等航天极危领域的极端束缚后，我们回归到桌面客户端、高并发后端、量化交易引擎、游戏服务端等通用的工业级场景。

一个兼顾极致工程效率、代码鲁棒性、构建速度与开发者幸福感的中大型现代 C++ 项目（基于 macOS/Linux + LLVM/Clang + CMake），其“深入但不苛刻”的落地范式主要体现在以下 5 个核心维度：

1. 深度 CMake 与构建系统架构 (Advanced CMake Practices)

中大型项目最忌讳“全局变量污染”和“编译慢”。现代 CMake 的深度玩法在于模块化 Target 划分与确定性预设。

① `CMakePresets.json` + `CMakeUserPresets.json` 隔离范式

工程落地： CMakePresets.json 进 Git 仓库（定义 CI、Debug、Release、ASan 的统一生成参数）。
开发体验： 允许开发者新建 .gitignore 掉的 CMakeUserPresets.json，用来覆盖本地特有的 LLVM 路径或本地缓存路径，做到团队预设与个人环境绝对解耦。

② 严格的“纯 Target 驱动”设计 (Interface Libraries)

废弃所有的 include_directories() 或全局 add_compile_options()。使用 INTERFACE Target 封装项目通用的“编译选项库”：

CMake

# 1. 声明一个纯接口 Target 用于管理全局 Warning / Compiler Flags
add_library(project_warnings INTERFACE)
target_compile_options(project_warnings INTERFACE
    $<$<CXX_COMPILER_ID:Clang>:-Wall -Wextra -Wshadow -Wconversion -Wnon-virtual-dtor>
)

# 2. 声明一个纯接口 Target 用于开启 Sanitizer
add_library(project_sanitizers INTERFACE)
if(ENABLE_ASan)
    target_compile_options(project_sanitizers INTERFACE -fsanitize=address -fno-omit-frame-pointer)
    target_link_options(project_sanitizers INTERFACE -fsanitize=address)
endif()

# 3. 业务模块直接继承，避免选项隐式污染子模块
target_link_libraries(my_service PRIVATE project_warnings project_sanitizers)

③ Unity Build（编译加速终极武器）

对于上百个 .cpp 的大型 Target，在 CMake 3.16+ 中一键开启 Unity Build：

CMake

set_target_properties(my_service PROPERTIES
    UNITY_BUILD ON
    UNITY_BUILD_BATCH_SIZE 16 # 将 16 个 cpp 合并为一个编译单元
)

效果： 能将整体编译时间缩短 50%~80%，同时依然保持代码源文件的物理分离。

2. 依赖管理治理 (vcpkg Manifest + Binary Caching)

很多中大型项目死于“第三方库版本乱套”或“每个工程师都要重新编译一遍 Heavy Deps (如 Boost / OpenSSL)”。

vcpkg Manifest 模式 (vcpkg.json) + Lockfile

把 vcpkg 当作 npm/cargo 来用，在根目录放置 vcpkg.json，声明所有依赖及其明确的版本约束（Baselines）。
私有二进制缓存 (Binary Caching)

在中大型团队中，配置 CMake 环境变量 VCPKG_BINARY_STAGING_DIR 指向团队内部的 S3/NFS 缓存。当 CI 或新同事拉取代码时，vcpkg 直接下载编译好的 .dylib / .a，无需在本地重新编译 Boost，节省数小时环境准备时间。

3. 运行时观测与架构防腐 (Observability & Architecture)

通用优秀项目对运行时的掌控力体现在低开销日志、诊断与架构约束上。

① 低延迟异步日志 (spdlog / Quill)

规范： 业务线程严禁发生同步 Disk I/O。全量采用 spdlog 的 spdlog::create_async<spdlog::sinks::basic_file_sink_mt>，日志写入无锁环形队列（RingBuffer），由后台单线程刷盘。
语义化日志： 引入 fmt 编译期校验，禁止拼字符串。

② 内存分配器无缝替换 (Mimalloc)

在通用场景下，不禁用堆内存，但严禁直接用系统默认的 malloc。

利用 CMake 将微软开源的 Mimalloc 设为全局覆盖：

CMake

# 全局替换 malloc/free，高并发下内存碎片减少，性能提升 15%+
find_package(mimalloc CONFIG REQUIRED)
target_link_libraries(my_service PRIVATE mimalloc-static)

③ 模块间隐式耦合防护 (`std::span` & `std::string_view`)

范式： 跨模块函数调用接口严禁使用 const std::vector<T>& 或 const std::string& 作为入参，全面替换为 std::span<const T> 和 std::string_view。
收益： 彻底解除对特定容器实现的依赖，避免不必要的深拷贝（Deep Copy）与临时对象产生。

4. 增量静态扫描与 CI 自动化拦截 (Strict CI Pipeline)

不需要开启令人抓狂的全量检查，而是强调“谁修改，谁负责”的增量检查。

① `git-clang-format` 增量检查

在 pre-commit 或 CI 脚本中，不全量扫历史脏代码，只扫描本次 Diff：

Bash

# 只检查本次 Commit 涉及改动的行，避免全量重构历史代码的负担
git-clang-format --diff HEAD~1

② `clang-tidy` 增量集成 (.clang-tidy)

在 CMake 中使用 CMAKE_CXX_CLANG_TIDY 属性。重点开启以下工业级高收益规则：

YAML

Checks: '
  -*,
  bugprone-*,          # 捕获潜在 Bug (如未初始化的变量、死锁)
  performance-*,        # 捕获性能开销 (如不必要的拷贝、按值传递大对象)
  modernize-use-auto,   # 代码现代风格
  modernize-use-using,
  readability-redundant-smartptr-get
'
WarningsAsErrors: 'bugprone-*,performance-*'

5. 现代化调试与 Crash Dump 防御 (Post-Mortem Debugging)

在生产环境或用户桌面端发生 Segfault 崩溃时，要能够离线还原现场。

Google Crashpad 集成
- 落地： 在进程启动时初始化 Crashpad 进程。当发生崩溃时，Crashpad 在后台静默捕捉当前的线程上下文、寄存器状态和调用栈，生成 .dmp (Minidump) 文件。
符号表离线还原 (DSYM / PDB Store)
- 构建系统在 Release 模式下生成单独的符号文件（macOS 下的 .dSYM，Windows 的 .pdb）。
- 配合 Sentry 或自建的 Minidump 还原服务，在收到崩溃日志后，自动化还原出崩溃发生在源代码的哪一行。

现代通用优秀 C++ 项目落地矩阵总结

维度	落地工具/范式	引入后的工程提升
构建管理	`CMakePresets.json` + `INTERFACE Targets`	环境绝对统一，CMake 代码解耦无全局污染
编译加速	Unity Build + `ccache` + `Ninja`	大型项目增量构建速度提升 50%~80%
依赖管理	`vcpkg Manifest` + 私有 Binary Cache	依赖版本锁定，无需本地重复编译大大型 C++ 库
错误/接口	`std::expected` + `std::span` + `std::string_view`	强制显示错误处理，接口无隐式深拷贝开销
内存/日志	`Mimalloc` + `spdlog` (Async Queue)	显著降低多线程内存碎片与主线程 I/O 阻塞
质量拦截	`git-clang-format` + `clang-tidy` (增量模式)	不纠结历史旧代码，对新增改动做自动化拦截
崩溃防御	`Crashpad` + Minidump 离线符号还原	生产环境 Segfault 崩溃秒级定位具体代码行

. 现代化 IDE 与诊断体验 (`.clangd` + Diagnostician)

目前工业界中大型团队（特别是使用 VS Code, CLion, Neovim, Nova 等工具的团队）正全面转向以 clangd 作为核心语言服务器。与普通的 IDE 补全插件不同，通过在项目根目录深度配置 .clangd 文件，可以将代码质量检查无感融入日常敲代码的过程中：

YAML

# 项目根目录下的 .clangd
CompileFlags:
  Add:
    - "-Wall"
    - "-Wextra"
    - "-Wconversion"      # 实时提醒隐式类型截断/精度丢失
    - "-Iinclude"
  Remove: [-Werror]       # 在 IDE 编辑时不要把 Warning 显示为阻碍编辑的 Error

Diagnostics:
  UnusedIncludes: Strict # 实时高亮显示没有用到的头文件，引导开发者清理 include
  ClangTidy:
    Add:
      - performance-*     # 实时提示按值传递大对象等性能损耗
      - bugprone-*        # 实时提示死锁、野指针隐患
      - modernize-*       # 引导写出更现代的 C++20 代码
    Remove:
      - readability-implicit-bool-conversion

InlayHints:               # 编辑器内直接嵌入类型与参数名提示
  Designators: true
  Enabled: true
  ParameterNames: true
  DeducedTypes: true

落地收益： 开发者在打字的瞬间就能看到隐藏的性能与逻辑漏洞，无需等到本地编译甚至 CI 流水线报错才发现问题。

2. CMake 代码格式化与自动化 Linter (cmake-format & cmake-lint)

在一个多人协作的中大型 C++ 项目中，大家往往关注了 .cpp / .h 的格式，却忽略了 CMakeLists.txt 本身也是需要维护的代码。漫天飞舞、格式错乱的 CMake 代码是项目“腐化”的重灾区。

cmakelang (cmake-format / cmake-lint)
- 落地： 引入 Python 工具链中的 cmake-format，并在 .pre-commit-config.yaml 中配置。
- 效果： 自动将项目的 CMakeLists.txt 统一排版（例如缩进、参数换行规范、指令小写等），并使用 cmake-lint 检查是否存在废弃函数调用或未用变量。

YAML

# .pre-commit-config.yaml 中的 CMake 拦截片段
  - repo: https://github.com/cheshirekow/cmakelang
    rev: v0.6.13
    hooks:
      - id: cmake-format
      - id: cmake-lint

3. 极速单测与依赖 Mock 范式 (Catch2 v3 / Doctest + FakeIt)

传统 GoogleTest 的问题在于构建较重、需要编译单独的库，且 Mock 语法（GoogleMock）相对繁琐。现代通用 C++ 项目更推荐以下轻量且现代化的单元测试范式：

① Catch2 v3 / Doctest 的现代单测写法

Catch2 v3 已经改为了静态库链接模式（大幅提升单测编译速度），并原生支持由 C++20 驱动的 BDD（Behavior-Driven Development） 风格：

C++

#include <catch2/catch_test_macros.hpp>

SCENARIO("Order book processes incoming limit orders", "[matching_engine]") {
    GIVEN("An empty order book") {
        OrderBook book;

        WHEN("A new buy limit order is placed") {
            auto result = book.place_order(Price{100}, Quantity{10}, Side::Buy);

            THEN("The order should be accepted and added to the book") {
                REQUIRE(result.has_value());
                REQUIRE(book.buy_levels_count() == 1);
            }
        }
    }
}

② 结合伪造框架 (FakeIt / Trompeloeil) 隔离外部依赖

避免编写繁琐的继承与宏定义。利用 FakeIt 这类 Header-only 的轻量 Mock 框架，针对接口类（Pure Virtual Interface）在单测中快速模拟依赖行为（如网络 Socket、数据库连接）：

C++

// 快速 Mock 一个网络发送接口，而无需引入复杂的 GMock 宏
Mock<INetworkClient> mock_network;
When(Method(mock_network, send_packet)).AlwaysReturn(true);

INetworkClient& client = mock_network.get();
// 将 client 注入待测业务类中运行测试...

4. 依赖项升级与安全漏洞监控 (Dependabot / Renovate)

在中大型通用项目中，通常会依赖上百个第三方开源库（通过 vcpkg.json 或 CPM.cmake 引入）。如果长期不升级，不仅错过性能优化，还容易埋下安全 CVE 漏洞。

Renovate Bot (针对 vcpkg / Conan / CMake 的自动化依赖升级)
- 落地： 在 Git 托管平台（GitHub / GitLab）配置 Renovate。
- 机制： 机器人每周会自动扫描你的 vcpkg.json 或 CPMAddPackage 脚本，如果发现 spdlog 或 fmt 发布了新版本，会自动提一个 PR，并附带该版本的 ChangeLog。
- 配合 CI： 只要 CI 流水线（编译 + 跑单测 + ASan 测试）自动通过，架构师只需点击一下 Approve 即可无痛保持项目依赖处于最新状态。

1. ABI & Symbol Visibility Control (符号导出控制与库瘦身)

在中大型 C++ 项目中（特别是包含 .dylib / .so 动态库的项目），如果不显式控制符号导出，所有内部函数默认都会被导出到符号表中。这不仅会导致动态库体积膨胀，还会增加 Dynamic Linker (dyld) 在程序启动时的加载耗时（Symbol Binding / Fixups）。

默认隐藏所有符号 (-fvisibility=hidden) 在 CMake 中全局开启默认隐藏标志，仅显式标记要对外暴露的 API：

CMake
```
set(CMAKE_CXX_VISIBILITY_PRESET hidden)
set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
```

使用属性选择性导出 使用现代导出头文件控制宏（CMake 提供了 GenerateExportHeader 模块自动为你生成这个文件）：

C++

#include "my_engine_export.h"

// 只有标记了 MY_ENGINE_EXPORT 的类/函数才会被导出到 .dylib 符号表
class MY_ENGINE_EXPORT EngineCore {
public:
    void start();
};

// 内部实现类，外部无法感知，符号完全隐藏
class InternalScheduler {
    void do_work();
};

收益： 动态库体积缩减 20%~40%，程序启动加载速度提升，同时防止了外部使用者非法 Hook 或直接调用你的内部非公开函数。

2. 编译期反射与序列化范式 (Compile-Time Reflection & Serialization)

在中大型项目（如后端 RPC、游戏配置加载、桌面端 JSON 解析）中，传统的“手写 to_json / from_json 序列化”是代码冗余和 Bug 的温床。现代 C++ 倾向于利用 C++20 Struct Binding (结构体绑定) 与模板元编程 实现零开销/近乎无痛的自动序列化。

结合 nlohmann/json + magic_enum + Aggregate Struct 对于普通的 C++ 聚合结构体（Aggregate Structs），引入像 glaze 或利用 magic_enum 实现枚举字符串与数值的零成本转换：

C++

#include <glaze/glaze.hpp>
#include <magic_enum.hpp>

enum class OrderType { Limit, Market, Stop };

struct OrderRequest {
    std::string symbol;
    double price;
    int quantity;
    OrderType type;
};

// 使用 Glaze / Modern Reflection 方案
// 无需手写繁琐的 parse 函数，编译期自动做映射
void process_json(std::string_view json_str) {
    OrderRequest req;
    auto ec = glz::read_json(req, json_str);
    if (!ec) {
        // 解析成功，直接使用
        log_info("Order type: {}", magic_enum::enum_name(req.type));
    }
}

3. 跨平台/团队统一的工具构建脚本 (Task Runners / Just)

虽然有了 CMakePresets.json，但是在日常开发中，工程师除了 cmake --build 之外，往往还需要运行格式化、跑本地 CI 模拟测试、清理缓存、更新依赖等。

放弃复杂的 Makefile / Bash 脚本，转向 just (Just a Command Runner) 在中大型团队中，推荐在项目根目录提供一个 justfile。just 是一个现代化的命令运行工具（比 make 更简洁且专门用于任务调度）：

代码段

#根目录下的 justfile 示例

# 默认打印帮助信息
default:
    @just --list

# 本地一键配置并构建 Debug 模式
build:
    cmake --preset debug
    cmake --build --preset debug -j

# 运行全套单元测试并开启 Sanitizer
test:
    cmake --preset asan
    cmake --build --preset asan
    ctest --preset asan --output-on-failure

# 运行格式化与 clang-tidy 检查
check:
    git-clang-format HEAD~1
    cmake --build --preset debug --target clang-tidy

收益： 新员工入职第一天，克隆仓库后只需输入 just build 或 just test，即可拉起整套现代化流程，不需要去记忆冗长的 cmake 命令行参数。

4. 全套工业级架构流水线视角 (Full Modern Architecture Pipeline)

至此，我们将这套“深入、现代化、通用且高效”的中大型 C++ 工程架构归纳为如下清晰的协作闭环：

Plaintext

[ 编码与开发阶段 ]
  ├── 语义表达: C++20/23 (std::expected, std::span, std::string_view)
  ├── 交互辅助: .clangd 嵌入式诊断 + justfile 统一命令调度
  └── 依赖管理: vcpkg Manifest (vcpkg.json) + CPM.cmake 自动管理

[ 提交与增量拦截 ]
  ├── 本地 Check: pre-commit 脚本 (git-clang-format / cmake-format)
  └── 隐式保护: 符号隐蔽 (-fvisibility=hidden) + 强类型屏蔽隐式类型转换

[ CI/CD 极速构建 ]
  ├── 编译引擎: Ninja + ccache + Unity Build (增量秒级构建)
  ├── 依赖加速: vcpkg Binary Cache (二进制预编译缓存，跳过源码构建)
  └── 自动化测试: Catch2 v3 (BDD 风格) + ASan / UBSan 动态检查

[ 生产部署与观测 ]
  ├── 内存/日志: Mimalloc (取代默认 malloc) + spdlog (无锁环形队列日志)
  └── 崩溃追踪: Crashpad (自动捕获 Minidump) + DSYM 符号表离线还原

落地实施建议总结

如果你准备将你的 C++ 项目进行全面升级，建议采取“循序渐进”的引入策略，而不是一次性重构：

第一周（基础打底）： 引入 .clang-format + CMakePresets.json + ccache，解决构建环境不一致与编译慢的问题。
第二周（质量防护）： 配置 .pre-commit-config.yaml 跑增量 git-clang-format，并在 CI 中挂载 Catch2 + AddressSanitizer。
第三周（现代架构演进）： 在 CMake 中引入 INTERFACE Targets，并在代码中新编写的模块里全面推广 std::expected / std::span 替代 C 风格接口。
第四周（生产准备）： 挂载 Mimalloc 与 Crashpad，建立符号表存储机制，实现生产环境 Segment Fault 的精准离线定位。

既然你的目标是学习现代优秀 C++ 项目的设计范式与前沿工具，而不是重构旧项目，那么最有效的方法就是通过“剖析标杆开源项目” + “用极简 Sandbox 手操搭建”来建立直观认知。

以下为你梳理一套适合学习和消化这些前沿工具与范式的方法论，以及最值得你直接 clone 下来阅读的代码库：

1. 拆解学习：目前公认优秀的“现代 C++ 标杆项目”

看优秀开源项目的 CMake 怎么写、代码怎么组织，是学习现代范式最快的方式。建议去 GitHub 克隆并仔细阅读以下几个仓库：

2. 动手学习路线：从零打造你的“现代 C++ 学习脚手架”

学习这些工具最好的方式，是在本地 macOS 上从零搭建一个微型 Sandbox 项目，亲自跑通一遍流水线：

Plaintext

my-modern-cpp-sandbox/
├── CMakeLists.txt            # 1. 学习 Interface Target & CPM.cmake
├── CMakePresets.json         # 2. 学习统一环境配置
├── .clang-format             # 3. 学习 LLVM 代码排版规约
├── .clangd                   # 4. 学习 clangd 实时诊断配置
├── .pre-commit-config.yaml   # 5. 学习 Git Hook 自动化拦截
└── src/
    └── main.cpp              # 6. 练习 C++20 std::expected / std::span / fmt

学习任务步骤建议：

第 1 步（构建体验）： 尝试配置 .clangd 和 CMakePresets.json，在 VS Code / CLion 中体验打字时 clangd 给出的实时 performance-* 诊断提示。
第 2 步（依赖体验）： 尝试在 CMakeLists.txt 中用 CPM.cmake 自动抓取 fmt 和 Catch2，体会“无额外安装、开箱即用”的干净依赖管理。
第 3 步（安全体验）： 在 CMake 中写一个 -DENABLE_ASAN=ON 开关，故意写一个内存越界（Heap Out-of-Bounds）或野指针，跑一遍单测，直观感受 AddressSanitizer (ASan) 打印出的精确崩溃堆栈。
第 4 步（代码范式）： 用 std::expected 重新写一个简单的文件读取或网络解析逻辑，对比旧时代抛 std::runtime_error 异常或返回 int err_code 的感官差异。

3. 极简 Sandbox 代码实操 (可直接复制尝试)

你可以直接在本地创建以下两个文件，体验现代 CMake 与现代 C++ 语法的结合：

① `CMakeLists.txt`（现代 Target 风格 + CPM 依赖获取）

CMake

cmake_minimum_required(VERSION 3.22)
project(ModernCppSandbox LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# 1. 自动集成 ccache 编译加速
find_program(CCACHE_PROGRAM ccache)
if(CCACHE_PROGRAM)
    set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
endif()

# 2. 轻量级获取现代化依赖
include(gh:cpm-cmake/CPM.cmake@0.38.7)

CPMAddPackage("gh:fmtlib/fmt#10.1.1")

# 3. 声明项目的主 Target
add_executable(sandbox_app src/main.cpp)
target_link_libraries(sandbox_app PRIVATE fmt::fmt)

# 4. 严谨的 Warning 控制 Target (接口继承)
add_library(project_warnings INTERFACE)
target_compile_options(project_warnings INTERFACE
    $<$<CXX_COMPILER_ID:Clang>:-Wall -Wextra -Wconversion -Wshadow>
)
target_link_libraries(sandbox_app PRIVATE project_warnings)

② `src/main.cpp`（现代 C++20 / 错误处理 / 格式化）

C++

#include <fmt/core.h>
#include <expected>
#include <string_view>
#include <span>

// 现代范式 1: 使用 std::expected 显式传递错误
enum class ParseError { InvalidFormat, OutOfRange };

std::expected<int, ParseError> parse_port(std::string_view input) {
    if (input.empty()) return std::unexpected(ParseError::InvalidFormat);
    if (input == "8080") return 8080;
    return std::unexpected(ParseError::OutOfRange);
}

// 现代范式 2: 使用 std::span 接收连续内存片段，无拷贝且解耦 vector
void print_bytes(std::span<const uint8_t> bytes) {
    fmt::print("Buffer size: {} bytes, first byte: {:#x}\n", bytes.size(), bytes.empty() ? 0 : bytes[0]);
}

int main() {
    // 体验 std::expected 的显示错误处理
    auto result = parse_port("8080");
    if (result) {
        fmt::print("Successfully parsed port: {}\n", *result);
    } else {
        fmt::print("Failed to parse port.\n");
    }

    uint8_t dummy_data[] = {0xDE, 0xAD, 0xBE, 0xEF};
    print_bytes(dummy_data); // 自动隐式转换为 std::span

    return 0;
}

4. 学习总结与核心收获

以学习和理解为目的时，你只需要在头脑中建立起这套现代 C++ 工程思维图谱：

构建不是写脚本，而是“搞面向对象”： 现代 CMake 核心是 Target 和 Property 的传递（PUBLIC/PRIVATE/INTERFACE），放弃全局变量。
错误处理不再依靠“猜”或“捕获”： 现代化 C++ 倾向于用 std::expected / std::optional 在编译期强迫开发者处理错误分支。
性能优化靠“接口设计”而非“奇技淫巧”： 接口多用 std::span 和 std::string_view，减少深拷贝；分配用 Mimalloc，从源头解决碎片与并发锁。
高质量代码靠“工具链防御”： 依靠 clangd 的实时 Diagnostician、ASan 的动态抓取、clang-format 的自动纠偏，把“人工审查”的负担降到最低。

1. 变量替换引擎与交互式问答（Template Parameterization & Interactive Prompts）

痛点： 应用模板（apply）后，用户往往需要手动去修改 project(000_Single_Exe_Module)、namespace、作者名字、C++ 标准等。
优化方案： 引入轻量模版引擎（如 Liquid / Handlebars / Jinja），在模板根目录下支持 .sc-cmake.toml 参数配置文件。
效果： 运行 sc-cmake apply 000_Single_Exe_Module my_project 时，CLI 自动开启交互式提问（或解析命令行参数）：

Plaintext
```
? Project Name: my_finance_engine
? C++ Standard: [C++20 / C++23 / C++17] (默认 C++20)
? Include License: [MIT / Apache-2.0 / None]
? Enable Sanitizers (ASan/UBSan)? [Y/n]
? Dependency Manager: [vcpkg / CPM.cmake / Conan / None]
```
随后在解压模板时，自动填充 CMakeLists.txt 中的 project({{project_name}}) 以及源文件中的 #include <{{project_name}}/core.hpp>。

二、 CLI 交互与开发体验优化（Developer Experience）

1. 模糊搜索与交互式 TUI 菜单（Interactive Fuzzy Finder）

痛点： 模板多了之后，用户记不住具体名字，每次都要先 sc-cmake list 看一眼，再复制名字 apply。
优化方案： 如果用户直接运行 sc-cmake apply 或 sc-cmake info（不带参数），自动唤起类似 fzf 的终端 TUI 选择界面（终端方向键选择模板，并实时预览模板简介/目录树）。

2. 预览模式（Dry-Run）

优化方案： 增加 -n / --dry-run 选项。

Bash
```
sc-cmake apply 000_Single_Exe_Module my_project --dry-run
```
只打印出即将创建哪些文件、替换哪些变量，而不真正写入磁盘。这在用户担心覆盖当前目录已有文件时非常有用。

3. 智能健康检查与环境诊断（`sc-cmake doctor`）

现状： 你已经有了 check（模板健康检测），这非常棒！
扩展： 可以提供一个 sc-cmake doctor 专门检查本地 C++ 研发环境是否齐全：
- [✓] CMake version 3.25.1
- [✓] Clang 18.0.0
- [✓] Ninja generator found
- [✓] ccache detected
- [!] vcpkg not found in PATH (Optional)

四、极客细节与开发者体验（UX Polish）

终端彩色输出与格式对齐 (Chalk / Lipgloss 风格)：
- 使用高亮色彩区分：SUCCESS (绿色), WARNING (黄色), PATH (蓝色/下划线)。
- 在生成项目后，打印出漂亮的 “Next Steps”（下一步指南）：
  
  Plaintext
```
🎉 Project [my_finance_app] created successfully!

Next steps:
  1. cd my_finance_app
  2. cmake --preset debug
  3. cmake --build --preset debug
  4. ./build/debug/my_finance_app
```
支持命令别名（Aliases）：
- 比如允许 sc-cmake a 代表 sc-cmake apply，sc-cmake ls 代表 sc-cmake list，提升极客打字效率。

CMake 接入 clang-tidy：从开关到可维护门禁

2026-07-20T00:00:00+00:00

CMake 接入 clang-tidy

clang-tidy 适合当工程的静态门禁：比编译器警告更靠近「现代 C++ 习惯」和「API 误用」。难点通常不在「能不能跑」，而在 CMake 怎么挂、配置怎么钉死、本地与 CI 怎么一致。

本文按「能开关 → 能复现 → 能长期维护」三条线整理。

1. 先弄清两种挂法

1.1 编译时自动跑（`CMAKE_CXX_CLANG_TIDY`）

CMake 会把 tidy 绑到每个编译命令上：改一个 .cpp，编译时顺带分析。

option(CXX_ENABLE_CLANG_TIDY "Attach clang-tidy to CXX compile" OFF)

if(CXX_ENABLE_CLANG_TIDY)
  find_program(CLANG_TIDY_EXE NAMES clang-tidy REQUIRED)
  set(CMAKE_CXX_CLANG_TIDY
    "${CLANG_TIDY_EXE};-warnings-as-errors=*"
    CACHE STRING "" FORCE)
endif()

适合：小目标 / 模块化工程 / 想强制「脏代码编不过」。

代价：全量编译变慢；增量时只扫改过的 TU。

1.2 独立目标 / 脚本扫（不绑编译）

用 compile_commands.json + 自己的 clang-tidy 调用：

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
clang-tidy -p build src/**/*.cpp

适合：大仓库、只想在 PR 跑、或 tidy 与构建解耦。

2. 配置文件：把规则钉在仓库里

优先放仓库根或 cmake/ 旁的 .clang-tidy，避免每人本机「默认检查集」不一致。

最小可用示例：

Checks: >
  -*,
  bugprone-*,
  modernize-use-nullptr,
  modernize-use-override,
  readability-identifier-naming,
  performance-unnecessary-copy-initialization
WarningsAsErrors: ''
HeaderFilterRegex: '.*'
FormatStyle: none

经验：

做法	建议
一上来开 `*`	噪音爆炸，团队会关掉 tidy
从 `bugprone-*` + 少量 modernize 起步	易落地
`WarningsAsErrors: '*'`	适合 CI 门禁；本地可先关
第三方头文件	用 `HeaderFilterRegex` 限定自己的源码树

3. 与 CMake 分层基建的常见接法

现代工程常把开关放在 CompilerWarnings.cmake / ProjectSetup.cmake 一类文件里，例如：

# cmake/CompilerWarnings.cmake（示意）
function(cxx_enable_clang_tidy target)
  if(NOT CXX_ENABLE_CLANG_TIDY)
    return()
  endif()
  find_program(CLANG_TIDY_EXE NAMES clang-tidy)
  if(NOT CLANG_TIDY_EXE)
    message(WARNING "clang-tidy not found; skip")
    return()
  endif()
  set_target_properties(${target} PROPERTIES
    CXX_CLANG_TIDY "${CLANG_TIDY_EXE};--config-file=${CMAKE_SOURCE_DIR}/.clang-tidy")
endfunction()

对 C++23 modules / import std 工程：确认 tidy 用的 clang 版本与编译器同源（Homebrew LLVM 场景尤其常见），否则会出现「编译过、tidy 解析失败」。

4. 本地工作流（推荐）

export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

# 默认关闭 tidy，日常编译快
cmake -S . -B build -G Ninja
cmake --build build

# 需要门禁时显式打开
cmake -S . -B build -G Ninja -DCXX_ENABLE_CLANG_TIDY=ON
cmake --build build

把「默认 OFF、CI ON」写进 README / preset，比强迫人人开 tidy 更可持续。

5. CI 门禁清单

CMAKE_EXPORT_COMPILE_COMMANDS=ON（若用独立扫）
固定 clang-tidy 版本（或固定 LLVM formula 大版本）
.clang-tidy 进仓库
PR 必跑；main 上偶发全量
第三方目录进 .clang-tidy 忽略或 HeaderFilterRegex 排除

6. 小结

目标	做法
开发时提醒	本机可选 `CXX_ENABLE_CLANG_TIDY=ON`
合入质量	CI 打开 + `warnings-as-errors`
长期可维护	仓库内 `.clang-tidy` + 窄检查集逐步加宽

下一篇会写 .cmake 模块拆分与 CMakePresets.json 的使用技巧，和 tidy 开关如何一起放进 preset。

CMake .cmake 模块与 Preset：可复现构建的拆分技巧

2026-07-20T00:00:00+00:00

`.cmake` 模块与 Preset 使用技巧

根目录 CMakeLists.txt 一旦堆满 find_package、警告选项、生成器判定，项目会很快「能编但难讲」。更稳的做法是：

按职责拆 .cmake 模块（工具链 / 生成器 / 警告 / 日志 / 安装）
用 CMakePresets.json 固定常用组合（本机 Ninja、CI Release、开 tidy 等）

本文是实操向清单，偏 CMake 3.20+ / 4.x。

1. 为什么要拆 `.cmake`

问题	拆模块后
新人不知道改哪	README 写「改 `cmake/ToolchainClang.cmake`」
AppleClang / Homebrew LLVM 混用	工具链探测集中一处
生成器搞错（modules 需要 Ninja）	`Generator.cmake` 统一 FATAL
选项满天飞	preset 命名表达意图

建议分层（名字可自定，职责别混）：

cmake/
  Generator.cmake          # 强制/探测生成器
  ToolchainClang.cmake     # 编译器、sysroot、modules JSON
  StdlibConfig.cmake       # import std / stdlib 探测
  CompilerWarnings.cmake   # -Wall 与可选 tidy
  BuildLog.cmake           # 彩色日志 / tee
  ProjectSetup.cmake       # 打印关键变量摘要
  Modules.cmake            # 挂 CXX modules 相关

根 CMakeLists.txt 只做：project()、add_subdirectory / add_executable、按顺序 include()。

2. `.cmake` 编写技巧

2.1 用 `option()` / `CACHE` 暴露开关，默认保守

option(CXX_ENABLE_CLANG_TIDY "Enable clang-tidy" OFF)
option(CXX_ENABLE_GTEST "Build tests" OFF)
set(CXX_PREFERRED_COMPILER "clang++" CACHE STRING "clang++|g++")

默认 OFF，避免「拉下来编不过」。

2.2 致命条件用清晰单行字符串

CMake 的 list 与多参数 set(msg "a" "b") 容易把 FATAL_ERROR 显示成空白。拼错误信息时用 string(APPEND)：

set(_err "")
string(APPEND _err "Ninja is required for C++23 modules.\n")
string(APPEND _err "Hint: export CMAKE_GENERATOR=Ninja or use -G Ninja")
message(FATAL_ERROR "${_err}")

2.3 生成器：早失败

if(NOT CMAKE_GENERATOR STREQUAL "Ninja")
  message(FATAL_ERROR "Use Ninja (C++ modules / import std). Got: ${CMAKE_GENERATOR}")
endif()

配合根目录 .envrc：export CMAKE_GENERATOR=Ninja，减少「裸 cmake .. 掉进 Unix Makefiles」的缓存坑。

2.4 include 顺序要稳定

典型顺序：

include(cmake/Generator.cmake)
include(cmake/ToolchainClang.cmake)
include(cmake/StdlibConfig.cmake)
# … project() 之后再：
include(cmake/CompilerWarnings.cmake)
include(cmake/ProjectSetup.cmake)

工具链相关尽量在 project() 前完成；依赖 PROJECT_* 的摘要放后面。

3. `CMakePresets.json` 技巧

3.1 最小结构

{
  "version": 6,
  "configurePresets": [
    {
      "name": "dev",
      "displayName": "Dev (Ninja RelWithDebInfo)",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
        "CXX_PREFERRED_COMPILER": "clang++",
        "CXX_ENABLE_CLANG_TIDY": "OFF"
      }
    },
    {
      "name": "tidy",
      "inherits": "dev",
      "displayName": "Dev + clang-tidy",
      "cacheVariables": {
        "CXX_ENABLE_CLANG_TIDY": "ON"
      }
    }
  ],
  "buildPresets": [
    { "name": "dev", "configurePreset": "dev" },
    { "name": "tidy", "configurePreset": "tidy" }
  ]
}

3.2 实用习惯

技巧	说明
`inherits`	共用 `generator` / `binaryDir`，只覆盖差异
`binaryDir` 固定 `build/`	与文档「进 build 再 cmake」一致
显式写 `generator: Ninja`	不依赖环境变量也正确
分开 `dev` / `ci` / `tidy`	意图可读，少口头约定
勿把本机绝对路径写进 preset	用 `${sourceDir}`、环境变量

3.3 命令

cmake --preset dev
cmake --build --preset dev

cmake --preset tidy
cmake --build --preset tidy

无 preset 时等价习惯：

mkdir -p build && cd build
cmake -G Ninja ..
cmake --build .

4. 和 clang-tidy 的组合

日常：dev preset，tidy OFF
合入前 / CI：tidy preset 或 -DCXX_ENABLE_CLANG_TIDY=ON
规则文件：仓库根 .clang-tidy（见专栏上一篇）

这样「模块拆分」负责机制，「preset」负责场景，两边都不膨胀。

5. 排障速查

现象	处理
`cmake ..` 后生成器是 Makefiles	`rm -rf build && mkdir build`，再用 Ninja / preset
FATAL 信息空白	检查是否把错误字符串写成了 CMake list
tidy 找不到	PATH 含 Homebrew LLVM；或 `find_program` 失败时明确 WARNING
preset 不生效	确认 `CMakePresets.json` 在源码根；CMake ≥ 3.19（建议 3.23+ / 4.x）

6. 小结

把「怎么探测环境」放进 .cmake，把「这次我想怎样编」放进 preset。根 CMakeLists.txt 保持薄，专栏工程和脚手架模板就能共用同一套心智模型。

提前体验 macOS 时：Homebrew 被过旧 Xcode 卡住怎么办

2026-07-20T00:00:00+00:00

提前体验 macOS：没有对口 Xcode 时怎么更新 Homebrew

预装 / 抢先升级到新版 macOS（例如 27）时，常出现尴尬窗口：

系统已是 macOS 27
本机仍装着 Xcode 26.x
Homebrew 已要求 Xcode 27.0（或提示 delete it）
Command Line Tools 可能已经是 27，但 brew install / brew upgrade 照样 fatal

这和某个 formula 是否用 LLVM 编译无关：拦在 Homebrew 的前置诊断。本文记录根因、临时方案、恢复方案（本机已验证）。

1. 现象

Error: Your Xcode (26.3) at /Applications/Xcode.app is too outdated.
Please update to Xcode 27.0 (or delete it).

若只在 /Applications 里改名，仍可能看到：

Your Xcode (26.x => /Applications/Xcode-….app.bak/Contents/Developer)
at /Applications/Xcode-….app.bak is too outdated.

同时 brew 可能警告：当前 macOS 为预发布 / Tier 2——那是支持策略提示；真正挡住安装的是 Xcode 最低版本检查。

2. 根因分析

点	说明
谁在查	Homebrew `MacOS::Xcode`（`os/mac/xcode.rb`）+ `check_xcode_minimum_version`
怎么找	先看 `/Applications/Xcode.app`；否则用 Spotlight：`mdfind` + bundle id
为何「只改名」无效	`.app.bak` 仍带 `com.apple.dt.Xcode`，Spotlight 仍命中
与 CLT 的关系	即便 `xcode-select` 已指向 CLT 27，只要 `mdfind` 还能找到旧 Xcode，检查仍失败

两条诊断命令（验收用）：

mdfind 'kMDItemCFBundleIdentifier == "com.apple.dt.Xcode"'
brew config | grep -E 'Xcode|CLT'

结论： 临时绕过的成败标准是 —— mdfind 对 Xcode bundle id 的结果必须为空；不能只改文件名。

3. 临时方案（已验证）

前提：已装好 Command Line Tools 27（brew config 里 CLT: 27.…）。

# A. 开发目录切到 CLT
sudo xcode-select -s /Library/Developer/CommandLineTools

# B. 看清 Spotlight / Applications 里有哪些 Xcode
mdfind 'kMDItemCFBundleIdentifier == "com.apple.dt.Xcode"'
ls -d /Applications/Xcode* 2>/dev/null

# C. 移到 /opt 下「永不索引」目录（不要留在 /Applications）
sudo mkdir -p /opt/xcode-stash
sudo touch /opt/xcode-stash/.metadata_never_index
sudo mv /Applications/Xcode.app /opt/xcode-stash/Xcode-26.6.app
# 若之前已改名，把对应路径一并移进 /opt/xcode-stash/

# D. 关键：mdfind 必须为空
mdfind 'kMDItemCFBundleIdentifier == "com.apple.dt.Xcode"'
# 若仍有路径：
#   sudo mdutil -E /opt/xcode-stash
# 或挪到外置未索引盘 / 删除该 .app

# E. 确认后安装 / 升级
brew config | grep -E 'Xcode|CLT'   # 期望 Xcode: N/A ；CLT: 27.…
brew install sc-cmake               # 或 brew upgrade / 任意 formula

无效做法：

仅 mv /Applications/Xcode.app /Applications/Xcode-….app.bak
指望与本检查无关的 HOMEBREW_* 跳过变量

长期方案：从 Apple Developer Downloads 安装对口 Xcode 27+，或彻底删除旧 Xcode。

4. 恢复方案（brew 用完后恢复 IDE）

sudo mv /opt/xcode-stash/Xcode-26.6.app /Applications/Xcode.app
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p
mdfind 'kMDItemCFBundleIdentifier == "com.apple.dt.Xcode"'   # 又能找到，属正常

注意：恢复后若再跑 brew install / upgrade，旧 Xcode 会再次触发同样错误；需要 brew 时再执行第三节，或升级到对口 Xcode。

5. 和「提前体验 macOS」的关系

抢先升级系统时，系统版本、CLT、完整 Xcode 三者经常不同步：

CLT 往往先跟上（能撑日常编译）
完整 Xcode 滞后（体积大、渠道慢）
Homebrew 按「当前 macOS → 最低 Xcode」做硬检查

因此「尴尬期」的务实策略是：

编译：CLT +（如需要）Homebrew LLVM
装 brew 包：临时 stash 旧 Xcode，让 mdfind 为空
写 App / 开 Interface Builder：再恢复 /Applications/Xcode.app

把 stash 路径、恢复命令写进自己的笔记或 formula 文档（例如 Formula/README.md），避免下次又在 /Applications 里改名并误以为修好了。

6. 小结

步骤	命令意图
诊断	`mdfind` + `brew config \| grep Xcode\|CLT`
临时	stash 到 `/opt/xcode-stash` + `.metadata_never_index`
验收	`mdfind` 空；`Xcode: N/A`
恢复	搬回 `Xcode.app` + `xcode-select` 切回

根因一句话：Homebrew 用 Spotlight（mdfind + bundle id）找 Xcode；只在 /Applications 改名仍会被扫到。

7.13 – 7.19 第一周

2026-07-13T00:00:00+00:00

待办

Professional CMake: A Practical Guide 通读

@start 2026-07-13 @due 2026-06-26 @priority 5 @labels red, orange,green,blue @top red

基础通识
下载与导出
库（接口，静态，动态）
etc

先通读，再精读。生词后续纳入Eudic 最后在本地重写理解，编写XMind 文档

英语单词

@due 2026-06-29 @priority 3 @labels blue

墨墨记单词
Eudic

单词重新捡起来

资源

本地仓库搭建

@start 2026-06-15 @priority 2

Zola 本地 build --force
Codeberg 仓库写入权限

content/kanban/ 目录、ReDeplog 流水线。

参考素材

@priority 1

article_details 图标行
Trello 列布局截图

2026-07-12T17:30:00+00:00

2026年07月12日 17:30（东八区 / 北京时间）

热力图色差调整 · 文章页音乐播放器 · 进度条本地 seek 根因

概述

本轮三件事：归档/文章页热力图色阶分离、文章页可选音乐播放器（FLAC/MP3 + LRC）、本地 zola serve 下进度条无法跳转的根因与修复。日常构建流程（zola build / zola serve / ./dev.sh / ./build-site.sh）未改；CI 无需改动。

1. 热力图色差调整

1.1 目标

归档页（/archive/）：沿用 GitHub 贡献图绿色四档色阶，空格子与 L1 对比清晰。
文章页（右上角固定挂件）：使用紫色四档色阶，与全站 accent 一致，避免与归档页混淆。

1.2 实现

场景	CSS 类	文件
归档	`.blog-heatmap--archive`	`static/css/heatmap.css`
文章	`.blog-heatmap--article`	同上

色阶变量（浅色模式示例）：

档位	归档（绿）	文章（紫）
empty	`#ebedf0`	`#ebedf0`
L1	`#9be9a8`	`#e9d5ff`
L2	`#40c463`	`#c084fc`
L3	`#30a14e`	`#9333ea`
L4	`#216e39`	`#6b21a8`

深色模式在 @media (prefers-color-scheme: dark) 下各有一套对应值。

文章页热力图与音乐播放器叠放在 .article-widgets-fixed（templates/article.html），固定于右上角，移动端改到底部右侧。

2. 音乐播放器：设计思路

2.1 产品行为

项	说明
启用粒度	全站 `zola.toml` 开关 + 单篇文章 front matter
默认态	仅显示大号播放按钮；悬停/聚焦展开元信息、歌词、控制条
音源	`static/music/` 下 `歌手-歌名.flac` 或 `.mp3`，优先 MP3
歌词	同名 `.lrc`，UTF-8 / GB18030 自动识别；卡拉 OK + 横向滚动
元数据	文件名 `歌手-歌名` + LRC `[ti:]` / `[ar:]`，不用 ID3 标签库
音量	点击循环：25% → 50% → 75% → 100% → 静音；喇叭图标自下而上填充
进度条	细轨道 + 圆点滑块；点击/拖动任意位置跳转
循环	默认关；图标 `arrow-clockwise` / `repeat`
多曲	`tracks` 多于 1 首时显示随机下一首
Safari	检测后整组件移除（FLAC / seek 兼容性差）

2.2 文件结构

zola.toml                          # [extra.music_player] 全站开关
templates/article.html               # .article-widgets-fixed 挂载热力图 + 播放器
templates/partials/music_player.html # 挂件 markup + data-tracks JSON
static/css/music-player.css          # 三行布局：meta / lyric / bar
static/js/music-player.js          # 播放、LRC、seek、音量、Blob 兜底
static/music/                      # 音频与 LRC（构建时原样拷贝到 public/music/）

2.3 单篇启用示例

[extra.music_player]
enabled = true
tracks = [
  { file = "庄心妍-繁星点点" },
  { file = "周杰伦-青花瓷" },
]

测试文章：content/01Write_blog_CMake/2026-07-12-Libs-Manager/index.md。

2.4 关键代码细节

模板：data-tracks 注入曲目列表；data-base 为 /music（可配 base_url）。

resolveAudio()：HEAD 探测，优先 MP3，其次 FLAC。

歌词：parseLrc() 解析时间轴；isMetaLyric() 过滤作词作曲等元信息行；syncLyric() 按 timeupdate 切换行并用 clip-path 做逐字高亮。

进度条：不用 <input type="range">（会被主题全局 range 样式覆盖成粗条+白块）。改为 div 轨道 + --progress-pct CSS 变量 + pointerdown/move/up 计算 clientX 比例后设 audio.currentTime。

音量：VOLUME_LEVELS = [0.25, 0.5, 0.75, 1, 0]，clip-path: inset(...) 在喇叭图标上显示填充比例。

3. 本地无法拖动：根因分析

3.1 现象

在本地 zola serve 下，点击或拖动进度条后，播放位置回到 00:00 附近（像「从头重播」），而非跳到指定时间。

3.2 复现数据（Chrome 自动化）

环境	`audio.seekable.end`	设 `currentTime = 50%` 后
`zola serve`	0	4.73s → 0.23s
支持 Range 的静态服务	255.49（全长）	正常跳到 118.6s

3.3 根因

不是进度条 UI 坐标算错，而是 HTML5 音频 seek 依赖 HTTP Accept-Ranges: bytes：

浏览器需对音频 URL 发 Range 分段请求 才能建立可 seek 区间；
zola serve 不返回 Accept-Ranges，curl -H "Range: bytes=0-1023" 仍得 200 而非 206；
此时 audio.seekable 为空，设置 currentTime 无效，位置回到 0 附近。

线上 GitHub Pages 支持 Range，部署后（且 static/music/ 已发布）应能直接拖动，无需播完整首。

3.4 修复方案

层级	方案	说明
播放器 JS	`ensureSeekable()` Blob 兜底	首次点击进度条时 `fetch` 整首音频为 Blob URL，再 seek；不必播完一整首，但大 FLAC 首次可能需等待下载
本地可选	`scripts/serve-with-ranges.mjs`	带 byte-range 的静态服务，用于本地立刻验证 seek
日常流程	保持 `./dev.sh` → `zola serve`	不强制改用户习惯
CI / 部署	不改 `deploy_pages.yml`	仍 `./build-site.sh`

dev.sh 已恢复为：

node scripts/encrypt-content.mjs
exec zola serve "$@"

4. 本地 / 部署命令对照

场景	命令	进度条 seek
日常预览	`zola build` → `zola serve`	首次拖可能等 Blob 下载；之后正常
加密文章开发	`./dev.sh`	同上
正式构建 / CI	`./build-site.sh`	构建产物；线上 GitHub Pages 可直接 seek
本地想立刻拖	见下方两行	与线上一致，无需等 Blob

本地立刻可 seek（可选，不影响日常）：

zola build --base-url http://127.0.0.1:1111/
node scripts/serve-with-ranges.mjs --no-watch -p 1111

浏览器打开 http://127.0.0.1:1111/。--base-url 仅修正本地资源链接，seek 能力来自 serve-with-ranges.mjs。

5. 部署注意

音乐文件须纳入仓库 static/music/，随 ./build-site.sh 进入 public/music/。
当前若线上 /music/... 为 404，播放器无法加载音频；推送含音乐的构建后即可。
Workflow 无需修改。

6. 相关文档

用法速查已写入 @/03Share_blog/2026-06-22-zola-template-markdown-guide/index.md §8.1 音乐播放器、§8.2 构建命令对照。

CMake Lib Manager

2026-07-12T00:00:00+00:00

C++ 第三方类库本地管理

面向本机（macOS / Homebrew / vcpkg）的三种主流方式：

系统包管理器（Homebrew、vcpkg）
仅有源码：CPM / FetchContent
Git submodule

原则：钉版本、可复现、优先项目内声明依赖，少往 /usr/local 全局乱装。

0. 本机路径速查

用途	路径
Homebrew 前缀	`/opt/homebrew`
vcpkg 根目录	`$HOME/vcpkg`（即 `/Users/songhoujin/vcpkg`）
vcpkg 安装前缀（给 CMake 用）	`$HOME/vcpkg/installed/arm64-osx`
vcpkg 构建暂存	`$HOME/vcpkg/packages/<pkg>_arm64-osx`
vcpkg toolchain	`$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake`
归档工具	`AR=/usr/bin/ar`（勿用 binutils 的 GNU `ar`）
HTTP 代理（Clash）	`http://127.0.0.1:17890`（`http_proxy`/`https_proxy`/`all_proxy` 均用 http://，勿对 17890 使用 `socks5://`）

export AR=/usr/bin/ar
export VCPKG_ROOT=$HOME/vcpkg
export http_proxy=http://127.0.0.1:17890
export https_proxy=http://127.0.0.1:17890
export HTTP_PROXY=$http_proxy HTTPS_PROXY=$https_proxy
export all_proxy=http://127.0.0.1:17890 ALL_PROXY=$all_proxy

1. 系统包管理器：Homebrew / vcpkg

有 formula / port 时优先用包管理器：多项目共用、升级清晰、find_package 友好。

1.1 Homebrew

brew install fmt ftxui entt
brew --prefix fmt          # 查看单包前缀
ls "$(brew --prefix)/lib/cmake"

CMake 使用：

cmake -S . -B build -DCMAKE_PREFIX_PATH="$(brew --prefix)"
cmake --build build

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

find_package(fmt CONFIG REQUIRED)
add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE fmt::fmt)

安装位置： /opt/homebrew/{include,lib,lib/cmake,share}（Apple Silicon）。

1.2 vcpkg

export AR=/usr/bin/ar VCPKG_ROOT=$HOME/vcpkg
# 代理见上文；确认：env | grep -i proxy 中不应出现 socks5://127.0.0.1:17890

vcpkg install libassert unordered-dense mp-units
vcpkg list

CMake 使用（推荐带 toolchain）：

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

find_package(libassert CONFIG REQUIRED)
add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE libassert::assert)

安装位置：

给编译器用的：$HOME/vcpkg/installed/arm64-osx/{include,lib,share}
packages/ 仅为构建中转，不要把它当 CMAKE_PREFIX_PATH

1.3 何时用 brew、何时用 vcpkg

情况	建议
有 brew formula，且要系统级共用	Homebrew
无 brew / 要与 CMake 深度集成 / 钉 triplet	vcpkg
macOS 预发布导致 bottle 异常	可改 vcpkg，或 `brew install --build-from-source`（视公式而定）

2. 仅有源码：CPM / FetchContent

无 brew、无 vcpkg port（或故意跟 git）时，在 本项目 CMake 里拉取源码。默认只进当前 build/，不污染系统。

典型库：NVIDIA/stdexec、alibaba/yalantinglibs 等。

2.1 原生 FetchContent

cmake_minimum_required(VERSION 3.24)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

include(FetchContent)
FetchContent_Declare(
  stdexec
  GIT_REPOSITORY https://github.com/NVIDIA/stdexec.git
  GIT_TAG        <钉死的 tag 或 commit>   # 勿长期裸追 main
)
FetchContent_MakeAvailable(stdexec)

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)  # 目标名以该库文档为准

落盘位置（配置后）：

路径	内容
`build/_deps/<name>-src/`	下载的源码
`build/_deps/<name>-build/`	该依赖的构建目录
`build/_deps/<name>-subbuild/`	下载用子工程

删除 build/ 即清除缓存；换机器需重新 cmake -B build（需能访问 Git 仓库）。

2.2 CPM.cmake（推荐封装）

一次引入 CPM，之后一行加依赖：

mkdir -p cmake
curl -fsSL -o cmake/CPM.cmake \
  https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/CPM.cmake

cmake_minimum_required(VERSION 3.24)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

include(cmake/CPM.cmake)

# 形式：gh:owner/repo#tag_or_commit
CPMAddPackage("gh:NVIDIA/stdexec#<钉死的版本>")

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)

CPM 仍基于 FetchContent，缓存同样在 build/_deps/（也可设 CPM_SOURCE_CACHE 指向如 $HOME/.cache/CPM 跨项目复用下载）。

cmake -S . -B build -DCPM_SOURCE_CACHE=$HOME/.cache/CPM
cmake --build build

2.3 可选：安装到用户前缀（多玩具项目共用）

cmake -S /path/to/stdexec -B /tmp/stdexec-build \
  -DCMAKE_INSTALL_PREFIX=$HOME/.local \
  -DCMAKE_BUILD_TYPE=Release
cmake --build /tmp/stdexec-build
cmake --install /tmp/stdexec-build
# 其它项目：
cmake -S . -B build -DCMAKE_PREFIX_PATH=$HOME/.local

落盘： $HOME/.local/{include,lib,lib/cmake}。正式项目仍更推荐 FetchContent/CPM 钉在仓库内。

3. Git submodule

需要源码进仓库、可审计、可离线构建时使用。

3.1 添加与更新

cd /path/to/your-project
git submodule add https://github.com/NVIDIA/stdexec.git third_party/stdexec
# 钉到具体提交
cd third_party/stdexec && git checkout <commit> && cd -
git add third_party/stdexec
git commit -m "Pin stdexec to <commit>"

# 新克隆机器：
git clone --recurse-submodules <your-repo-url>
# 或已克隆后：
git submodule update --init --recursive

3.2 CMake 接入

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

add_subdirectory(third_party/stdexec)

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)

若上游不是「可 add_subdirectory 的 CMake 工程」，可改为：

target_include_directories(demo PRIVATE third_party/some_header_only/include)

3.3 落盘位置

路径	内容
`<项目>/third_party/<库>/`	源码（随 submodule 提交指针版本）
`build/`	你自己工程的构建树（依赖若被 `add_subdirectory`，对象文件也在 build 里）

4. 三种方式怎么选

场景	选
有 brew / vcpkg，多项目共用	§1 包管理器
无发行包、跟上游、单项目	§2 CPM / FetchContent
要进 git、审计、离线 CI	§3 submodule
仅本机随便玩	`$HOME/.local` 或 `~/src/...`（非正式）

共同要求：

钉 tag / commit，避免默默漂在 main
CI 与文档写清：代理、AR、CMAKE_TOOLCHAIN_FILE
同一依赖不要 brew + vcpkg + FetchContent 混装三份，除非有意隔离

5. 最小可粘贴工程骨架

myapp/
  CMakeLists.txt
  cmake/CPM.cmake          # 若用 CPM
  third_party/...          # 若用 submodule
  src/main.cpp

CMakeLists.txt 混合示例（包管理器 + CPM）：

cmake_minimum_required(VERSION 3.24)
project(myapp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

# 来自 brew / vcpkg（需 CMAKE_PREFIX_PATH 或 vcpkg toolchain）
find_package(fmt CONFIG REQUIRED)

# 仅有源码
include(cmake/CPM.cmake)
CPMAddPackage("gh:NVIDIA/stdexec#<version>")

add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE fmt::fmt STDEXEC::stdexec)

配置示例：

# 只用 brew
cmake -S . -B build -DCMAKE_PREFIX_PATH="$(brew --prefix)"

# 只用 vcpkg
cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake

# brew + vcpkg 同时找包时，toolchain + PREFIX 可一起设（注意别重复链接同一库的两套）

6. 排错速记

现象	处理
vcpkg `curl 35` / SSL timeout	检查代理：`all_proxy` 勿对 Clash HTTP 口用 `socks5://`；统一 `http://127.0.0.1:17890`
vcpkg `archive member '/' not a mach-o`	`export AR=/usr/bin/ar`，并从 `PATH` 去掉 `binutils` 的 `ar`
`find_package` 找不到	查 `CMAKE_TOOLCHAIN_FILE` / `CMAKE_PREFIX_PATH`；vcpkg 用 `installed/arm64-osx` 而非 `packages/`
FetchContent 每次重下	设 `CPM_SOURCE_CACHE`，或改用 submodule

文档用途：本机第三方 C++ 库管理备忘。可按项目需要删减示例中的库名与版本钉点。

CMake Lib Manager

2026-07-12T00:00:00+00:00

C++ 第三方类库本地管理

面向本机（macOS / Homebrew / vcpkg）的三种主流方式：

系统包管理器（Homebrew、vcpkg）
仅有源码：CPM / FetchContent
Git submodule

原则：钉版本、可复现、优先项目内声明依赖，少往 /usr/local 全局乱装。

0. 本机路径速查

用途	路径
Homebrew 前缀	`/opt/homebrew`
vcpkg 根目录	`$HOME/vcpkg`（即 `/Users/songhoujin/vcpkg`）
vcpkg 安装前缀（给 CMake 用）	`$HOME/vcpkg/installed/arm64-osx`
vcpkg 构建暂存	`$HOME/vcpkg/packages/<pkg>_arm64-osx`
vcpkg toolchain	`$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake`
归档工具	`AR=/usr/bin/ar`（勿用 binutils 的 GNU `ar`）
HTTP 代理（Clash）	`http://127.0.0.1:17890`（`http_proxy`/`https_proxy`/`all_proxy` 均用 http://，勿对 17890 使用 `socks5://`）

export AR=/usr/bin/ar
export VCPKG_ROOT=$HOME/vcpkg
export http_proxy=http://127.0.0.1:17890
export https_proxy=http://127.0.0.1:17890
export HTTP_PROXY=$http_proxy HTTPS_PROXY=$https_proxy
export all_proxy=http://127.0.0.1:17890 ALL_PROXY=$all_proxy

1. 系统包管理器：Homebrew / vcpkg

有 formula / port 时优先用包管理器：多项目共用、升级清晰、find_package 友好。

1.1 Homebrew

brew install fmt ftxui entt
brew --prefix fmt          # 查看单包前缀
ls "$(brew --prefix)/lib/cmake"

CMake 使用：

cmake -S . -B build -DCMAKE_PREFIX_PATH="$(brew --prefix)"
cmake --build build

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

find_package(fmt CONFIG REQUIRED)
add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE fmt::fmt)

安装位置： /opt/homebrew/{include,lib,lib/cmake,share}（Apple Silicon）。

1.2 vcpkg

export AR=/usr/bin/ar VCPKG_ROOT=$HOME/vcpkg
# 代理见上文；确认：env | grep -i proxy 中不应出现 socks5://127.0.0.1:17890

vcpkg install libassert unordered-dense mp-units
vcpkg list

CMake 使用（推荐带 toolchain）：

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

find_package(libassert CONFIG REQUIRED)
add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE libassert::assert)

安装位置：

给编译器用的：$HOME/vcpkg/installed/arm64-osx/{include,lib,share}
packages/ 仅为构建中转，不要把它当 CMAKE_PREFIX_PATH

1.3 何时用 brew、何时用 vcpkg

情况	建议
有 brew formula，且要系统级共用	Homebrew
无 brew / 要与 CMake 深度集成 / 钉 triplet	vcpkg
macOS 预发布导致 bottle 异常	可改 vcpkg，或 `brew install --build-from-source`（视公式而定）

2. 仅有源码：CPM / FetchContent

无 brew、无 vcpkg port（或故意跟 git）时，在 本项目 CMake 里拉取源码。默认只进当前 build/，不污染系统。

典型库：NVIDIA/stdexec、alibaba/yalantinglibs 等。

2.1 原生 FetchContent

cmake_minimum_required(VERSION 3.24)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

include(FetchContent)
FetchContent_Declare(
  stdexec
  GIT_REPOSITORY https://github.com/NVIDIA/stdexec.git
  GIT_TAG        <钉死的 tag 或 commit>   # 勿长期裸追 main
)
FetchContent_MakeAvailable(stdexec)

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)  # 目标名以该库文档为准

落盘位置（配置后）：

路径	内容
`build/_deps/<name>-src/`	下载的源码
`build/_deps/<name>-build/`	该依赖的构建目录
`build/_deps/<name>-subbuild/`	下载用子工程

删除 build/ 即清除缓存；换机器需重新 cmake -B build（需能访问 Git 仓库）。

2.2 CPM.cmake（推荐封装）

一次引入 CPM，之后一行加依赖：

mkdir -p cmake
curl -fsSL -o cmake/CPM.cmake \
  https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/CPM.cmake

cmake_minimum_required(VERSION 3.24)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

include(cmake/CPM.cmake)

# 形式：gh:owner/repo#tag_or_commit
CPMAddPackage("gh:NVIDIA/stdexec#<钉死的版本>")

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)

CPM 仍基于 FetchContent，缓存同样在 build/_deps/（也可设 CPM_SOURCE_CACHE 指向如 $HOME/.cache/CPM 跨项目复用下载）。

cmake -S . -B build -DCPM_SOURCE_CACHE=$HOME/.cache/CPM
cmake --build build

2.3 可选：安装到用户前缀（多玩具项目共用）

cmake -S /path/to/stdexec -B /tmp/stdexec-build \
  -DCMAKE_INSTALL_PREFIX=$HOME/.local \
  -DCMAKE_BUILD_TYPE=Release
cmake --build /tmp/stdexec-build
cmake --install /tmp/stdexec-build
# 其它项目：
cmake -S . -B build -DCMAKE_PREFIX_PATH=$HOME/.local

落盘： $HOME/.local/{include,lib,lib/cmake}。正式项目仍更推荐 FetchContent/CPM 钉在仓库内。

3. Git submodule

需要源码进仓库、可审计、可离线构建时使用。

3.1 添加与更新

cd /path/to/your-project
git submodule add https://github.com/NVIDIA/stdexec.git third_party/stdexec
# 钉到具体提交
cd third_party/stdexec && git checkout <commit> && cd -
git add third_party/stdexec
git commit -m "Pin stdexec to <commit>"

# 新克隆机器：
git clone --recurse-submodules <your-repo-url>
# 或已克隆后：
git submodule update --init --recursive

3.2 CMake 接入

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

add_subdirectory(third_party/stdexec)

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE STDEXEC::stdexec)

若上游不是「可 add_subdirectory 的 CMake 工程」，可改为：

target_include_directories(demo PRIVATE third_party/some_header_only/include)

3.3 落盘位置

路径	内容
`<项目>/third_party/<库>/`	源码（随 submodule 提交指针版本）
`build/`	你自己工程的构建树（依赖若被 `add_subdirectory`，对象文件也在 build 里）

4. 三种方式怎么选

场景	选
有 brew / vcpkg，多项目共用	§1 包管理器
无发行包、跟上游、单项目	§2 CPM / FetchContent
要进 git、审计、离线 CI	§3 submodule
仅本机随便玩	`$HOME/.local` 或 `~/src/...`（非正式）

共同要求：

钉 tag / commit，避免默默漂在 main
CI 与文档写清：代理、AR、CMAKE_TOOLCHAIN_FILE
同一依赖不要 brew + vcpkg + FetchContent 混装三份，除非有意隔离

5. 最小可粘贴工程骨架

myapp/
  CMakeLists.txt
  cmake/CPM.cmake          # 若用 CPM
  third_party/...          # 若用 submodule
  src/main.cpp

CMakeLists.txt 混合示例（包管理器 + CPM）：

cmake_minimum_required(VERSION 3.24)
project(myapp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

# 来自 brew / vcpkg（需 CMAKE_PREFIX_PATH 或 vcpkg toolchain）
find_package(fmt CONFIG REQUIRED)

# 仅有源码
include(cmake/CPM.cmake)
CPMAddPackage("gh:NVIDIA/stdexec#<version>")

add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE fmt::fmt STDEXEC::stdexec)

配置示例：

# 只用 brew
cmake -S . -B build -DCMAKE_PREFIX_PATH="$(brew --prefix)"

# 只用 vcpkg
cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake

# brew + vcpkg 同时找包时，toolchain + PREFIX 可一起设（注意别重复链接同一库的两套）

6. 排错速记

现象	处理
vcpkg `curl 35` / SSL timeout	检查代理：`all_proxy` 勿对 Clash HTTP 口用 `socks5://`；统一 `http://127.0.0.1:17890`
vcpkg `archive member '/' not a mach-o`	`export AR=/usr/bin/ar`，并从 `PATH` 去掉 `binutils` 的 `ar`
`find_package` 找不到	查 `CMAKE_TOOLCHAIN_FILE` / `CMAKE_PREFIX_PATH`；vcpkg 用 `installed/arm64-osx` 而非 `packages/`
FetchContent 每次重下	设 `CPM_SOURCE_CACHE`，或改用 submodule

文档用途：本机第三方 C++ 库管理备忘。可按项目需要删减示例中的库名与版本钉点。

Fast Open CodeProject

2026-07-12T00:00:00+00:00

进入项目目录，按照指定编辑器打开

❯ pwd                                                                                            ─╯
/Users/songhoujin/00BlogZola

❯ zed .                                                                                          ─╯
Found existing alias for "zed". You should use: "zd"

Habit Rebuild

2026-06-25T00:00:00+00:00

抛去旧习惯，在立刻行动中寻找意义

博客看板 - Blog Kanban

每天主动编写博客，根据你的活动和规划，有意识的去编写看板，看板并非随意编写，请郑重对待，那是你的承诺，言之有物，

自己做了什么，就写什么。量化自己的行为，直观的感受自己的变化；

每天在 kanban/中进行更新当日的完成的核心事项；

软件看板 - Stacks

自己主动的有意识推进和记录进步地方，后续可进行整理复盘；

Focus - 专注模式

自己在 SnippetsLab -> DevonThink 中基于专注模式的产品想法自己就培养这样的工作习惯，精简自己的工作环境。

在后续动摇时参与劳动

去跑个外卖或出门跑一跑，清醒下脑袋

习惯：主动去阅读开源代码

搜狗C++后台项目，腾讯广告C++ 项目，等都是优秀的项目去阅读吸收理解，提高自己的代码架构理解和设计；

习惯：音乐，陶冶心绪，疲惫时练练吉他

Zola 模板开发要点与 Markdown 语法速查

2026-06-25T00:00:00+00:00

Zola 模板的核心机制（结合 Zola 官方文档与本站实践），以及参考 daudix.one/content 整理的 Markdown / Shortcode 写法示例。

警告：zola.toml若启用新功能，记得在该文档中更新说明使用方法

# 拉取更新主题

git submodule status  # 查看当前子模块状态
git submodule update --init --recursive # 已克隆主仓库后递归拉取子模块
git submodule update --recursive --remote # 更新所有子模块到最新版本

# 提交推送博客到仓库
git add .
git status

git commit -m "Update MD file or Add new md file"
git push

zola build  # 构建 检测是否存在语法问题
zols serve  # 本机运行

一、Zola 模板：目录与优先级

Zola 的模板引擎是 Tera（语法接近 Jinja2 / Liquid）。站点根目录结构：

.
├── config.toml          # 全局配置
├── content/             # Markdown 内容（按 section 组织）
├── templates/           # 站点级模板（优先级高于 theme）
├── static/              # 原样拷贝的静态资源
├── sass/                # 可选，编译为 CSS
└── themes/ametrine/     # 主题（可被 templates/ 同名文件覆盖）

覆盖规则：templates/ 下与主题同路径的文件会完全替换主题模板。例如：

{# templates/article.html — 只改文章页，不动 theme #}
{%% extends "ametrine/templates/article.html" %%}

{%% block content %%}
&#123;&#123; super() &#125;&#125;
{# 追加滚动条、热力图等 #}
{%% endblock %%}

原则：不改 themes/ 内文件，在 templates/ 里 extends + block 扩展。

二、模板类型与 front matter 绑定

模板文件	用途	典型绑定方式
`base.html`	全站骨架（`<html>`、header、sidebar、footer）	被其他模板 extends
`section.html`	Section 索引页（`_index.md`）	section 默认模板
`page.html`	独立 Page	page 默认模板
`article.html`	单篇文章	`page_template = "article.html"`
`article_list.html`	文章列表 + 分页	`template = "article_list.html"`
自定义如 `archive.html`	归档页等特殊布局	`_index.md` 中 `template = "archive.html"`

Section 的 _index.md 示例（参考 daudix 的 blog/_index.md）：

+++
title = "效率-工作流"
sort_by = "date"
template = "article_list.html"      # 列表页模板
page_template = "article.html"      # 该 section 下每篇文章的模板
paginate_by = 10
generate_feeds = true
[extra]
no_header = true                    # 传给模板，控制是否渲染 h1
+++

三、Tera 核心语法

3.1 继承与块（extends / block / super）

{%% extends "ametrine/templates/base.html" %%}

{%% block content %%}
  <main>&#123;&#123; section.content | safe &#125;&#125;</main>
{%% endblock content %%}

在子模板中调用父块内容：super() 过滤器（写作 {{ super() }}）（本站 article.html 即此模式）。

3.2 引入片段（include / import）

{%% include "partials/heatmap_component.html" %%}

{%% import "macros/macros.html" as macros %%}
&#123;&#123; macros::translate(key="skip_to_content", default="Skip", language_strings=language_strings) &#125;&#125;

3.3 常用变量（构建时注入）

变量	含义
`config`	`zola.toml` 全文，含 `config.extra.*`
`page`	当前页面（title、date、content、permalink、taxonomies…）
`section`	当前 section（pages 列表、title…）
`lang`	当前语言
`current_url`	当前页面 URL

3.4 常用函数与过滤器

{# 跨 section 拉取文章 — archive.html 中的用法 #}
{%% set sec = get_section(path="03Share_blog/_index.md") %%}
{%% set posts = sec.pages | sort(attribute="date") | reverse %%}

{# 加载外部数据 #}
{%% set strings = load_data(path="i18n/en.toml") %%}

{# 过滤器链 #}
&#123;&#123; page.date | date(format="%Y-%m-%d") &#125;&#125;
&#123;&#123; heat_data | json_encode() | safe &#125;&#125;
{%% for year, posts in all_posts | group_by(attribute="year") %%}

3.5 图片处理（build 时）

主题 base.html 中常见写法：

{%% set blurnail = resize_image(path=page.colocated_path ~ banner, width=4, height=2, op="fill", format="webp") %%}

page.colocated_path 指向与 index.md 同目录，便于 co-located 资源。

四、Shortcode（短代码）

放在 templates/shortcodes/*.html，Markdown 中写作：

{%% shortcode_name(param="value") %%}
内容
{%% end %%}

或自闭合：{%% icon(name="github") %%}

在 Markdown 正文中展示 shortcode 字面量时，用 {%% / %%} 转义，避免被 Zola 当作 shortcode 执行。

查找顺序：站点 templates/shortcodes/ → 主题 themes/ametrine/templates/shortcodes/。

五、Markdown 语法示例

以下示例整理自 daudix.one 的常见写法，并标注 ametrine 支持情况。

5.1 Front matter（TOML）

+++
title = "文章标题"
description = "摘要，用于列表卡片与 SEO"
date = 2026-06-22
updated = 2026-06-22
draft = true                        # 草稿，需 zola build --drafts
[taxonomies]
tags = ["Zola", "Devlog"]
categories = ["Featured"]
[extra]
toc = true                          # 目录
accent_color = ["hsl(254 44% 55%)", "hsl(290 20% 71%)"]  # 浅色/深色强调色
banner = "banner.webp"              # 与 index.md 同目录的横幅图
[extra.fediverse]
host = "vmst.io"
user = "username"
id = "113295812044964246"           # 启用 Fediverse 评论
+++

section级(_index.md)

+++
title = "CMake 4.0 技术细节整理 专栏"
description = "My writings, I suppose."
sort_by = "date"
template = "article_list.html"
page_template = "article.html"
paginate_by = 10
generate_feeds = true             
[extra]
scripts = ["analytic/umami.js"]  # 启用访客来源统计
no_header = true

+++

page级(index.md)


+++
title = "Mac 本地网络 配置优化方案"
description = "提升网络访问性能，减少硬件性能损耗"
updated = 2026-06-20          # 最新更新时间， 若 section的_index.md 中设置以时间排序，以这个为准
date = 2026-06-20              # 👈 确保这里有规范的日期
[taxonomies]
tags = ["zsh","Mac" ]  # 标签
categories = ["Hot"]  # 分类
[extra]
accent_color = ["hsl(26.511627 25% 34%)", "hsl(26.75676 31% 53%)"]
+++

5.2 内部链接

Zola 专用 @/ 前缀，构建时解析为正确 permalink：

详见 [网站重写 Devlog](@/blog/2023-08-13-site-and-blog-devlog/index.md)

脚注式引用：[为什么叫这个名字？](@/03Share_blog/2025-10-04-Zola-build-deploy-circle/index.md)

5.2.0 页间跨页跳转

``TODO` 待补充

5.2.1 页内块跳转

``TODO` 待补充

5.3 标题与目录

## 二级标题        → 自动生成锚点
### 三级标题

[extra] toc = true  → 文章顶部自动生成目录

5.4 文本样式

**粗体**  *斜体*  ~~删除线~~  `行内代码`

> 引用块
> 可以多行

上标脚注引用[^1]，文末定义脚注内容。

[^1]: [Dependency hell](https://en.wikipedia.org/wiki/Dependency_hell)

5.5 术语块（daudix 风格）

 

**SSG：** Static Site Generator，将 Markdown 转为静态 HTML 的构建工具。

5.6 表格

| 页面 | 旧仓库 | 新仓库 |
| ---- | ------ | ------ |
| Home | pages  | website |
| Blog | blog-source | website |

5.7 代码块

支持语法高亮（本站 zola.toml 配置 monokai-pro 主题）：

TOML 配置示例：

[markdown]
smart_punctuation = true
github_alerts = true

HTML 模板示例（Tera 语法，写作时用 {%% / %%} 转义可在正文中展示字面量）：

{%% extends "base.html" %%}
{%% block content %%}&#123;&#123; page.content | safe &#125;&#125;{%% endblock %%}

Shell 命令：

zola build --force
zola serve --drafts

5.8 GitHub Alerts（`github_alerts = true` 时）

> [!NOTE]
> 这是提示框，无需手写 shortcode。

> [!WARNING]
> 警告信息。

> [!TIP]
> 小技巧。

等价的 shortcode 写法（ametrine alert.html）：

{%% alert(title="Note", icon="info", color="note") %%}
自定义图标与颜色的提示块。
{%% end %%}

5.9 图片

普通 Markdown 图片（与 index.md 同目录放 photo.png）：

![Obsidian 附件目录配置](obsidian-attachments.png)

daudix 技巧：URL 锚点控制样式（无需 Kramdown 的 {: .class}）：

![透明背景 PNG](context-menu.png#transparent)
![像素风渲染](sprite.png#pixels)
![无 hover 效果](logo.png#transparent#no-hover)

对应 SCSS 选择器示例：

img[src*="#transparent"] { background: transparent; }
img[src*="#pixels"]       { image-rendering: pixelated; }

Shortcode 图片（更多参数）：

{%% image(url="banner.webp", alt="横幅", full=true, drop_shadow=true) %%}

5.10 ASCII / CRT 艺术字

Section 首页与 daudix blog 首页常用的 crt shortcode：

{%% crt(label="ASCII 插画：左侧卡车，中间房屋，右侧火箭") %%}
         *                 *
  *              _________##
                @\\\\\\\\\##
 *             @@@\\\\\\\\##\
{%% end %%}

渲染为 .crt 样式的 <pre>，带 CRT 扫描线效果。

5.11 嵌入媒体

YouTube（隐私增强域名，需 CSP 允许 youtube-nocookie.com）：

{%% youtube(id="dQw4w9WgXcQ") %%}
{%% youtube(id="abc123", start=30, autoplay=false) %%}

Vimeo / 本地视频 / 音频：

{%% vimeo(id="123456789") %%}

{%% video(url="clip.mp4", controls=true, loop=true, muted=true) %%}

{%% audio(url="podcast.mp3", name="播客片段") %%}

5.12 图标

{%% icon(name="github") %%}
{%% icon(name="terminal", inline=true) %%}

图标来自 Phosphor SVG，主题 icons/phosphor/ 目录。

5.13 Emoji shortcode

当 render_emoji = false 时，可用 shortcode 插入：

{%% emoji(name="🦀") %%}

5.14 本站自定义 shortcode

templates/shortcodes/ 下还有：

Shortcode	用途
`badges`	徽章展示
`polaroid`	宝丽来相框图片
`window`	窗口 UI 框
`masonry`	瀑布流图片墙
`todo`	TODO 列表
`now_playing`	正在播放
`online`	在线状态

用法均为 {%% name(参数) %%}...{%% end %%}，具体参数见对应 html 文件。

六、模板开发注意点清单

不要改 theme：在 templates/ 覆盖或 extends。
safe 过滤器：page.content、| markdown | safe 输出已解析 HTML；纯文本勿加 safe。
Section 路径：get_section(path="03Share_blog/_index.md") 路径相对 content/。
全局变量：{%% set_global x = ... %%} 在 loop 内累加时使用。
CSP：嵌入 iframe / 外部脚本需在 zola.toml 的 [extra.csp] 声明域名。
静态资源：JS/CSS 放 static/，引用 /js/xxx.js；Sass 放 sass/ 由 Zola 编译。
Co-located 资源：图片与 index.md 同目录，构建后 permalink 同路径，便于搬运整文件夹。
分页：paginate_by = 10 + 模板中使用 section.pages 与 paginator partial。
多语言：content/ 下按语言分子目录，配合 i18n/*.toml。
调试：zola build --force 强制重建；zola serve --open 热重载预览。

七、本站实践对照

功能	实现位置
文章页扩展（热力图、滚动条、音乐）	`templates/article.html` extends + include partials
归档页 + 年份热力图	`templates/archive.html` + `heatmap_component.html`
文章页音乐播放器	`partials/music_player.html` + `static/js/music-player.js`
自定义列表模板	`templates/article_list.html` / `nanolog_list.html`
全局配置	`zola.toml` → `config.extra.*`
主题变量（颜色）	ametrine `--bg-muted-1`、`--accent-color` 等 CSS 变量

八、构建流程

8.1 音乐播放器：如何在新博客中启用

全站开关（`zola.toml`，已配置可跳过）

[extra.music_player]
enabled = true
base_url = "/music"   # 对应 static/music/ → public/music/

单篇文章 front matter

[extra.music_player]
enabled = true
tracks = [
  { file = "歌手-歌名" },
  { file = "周杰伦-青花瓷" },
]

资源文件命名（放在 `static/music/`）

文件	说明
`歌手-歌名.mp3` 或 `.flac`	音频；优先使用 MP3（体积更小、seek 更稳）
`歌手-歌名.lrc`	歌词；UTF-8 或 GB18030

file 字段不带扩展名，播放器自动探测 .mp3 → .flac。

行为摘要

挂件在文章页右上角（热力图下方），默认只显示播放按钮，悬停展开控制条。
进度条：细轨道 + 圆点，点击/拖动跳转。
音量：点击喇叭循环 25% → 50% → 75% → 100% → 静音。
Safari 不显示播放器（脚本内检测后移除组件）。

8.2 构建与预览命令对照

场景	命令	说明	进度条能否立刻拖
日常预览	`zola build` → `zola serve`	改样式、普通文章足够	首次拖可能需等整首下载（Blob 兜底）；之后正常
加密文章开发	`./dev.sh`	先 `encrypt-content.mjs`，再 `zola serve`	同上
正式部署 / CI	`./build-site.sh`	加密 → build → post-build → kanban 校验	线上 GitHub Pages 支持 Range，可直接拖（需 `static/music/` 已部署）
本地想立刻拖	见下方两行	可选；不改日常习惯	立刻可拖，与线上一致

日常预览与加密开发（标准流程，未改）：

# 普通文章
zola build
zola serve

# 新增/修改加密文章
./dev.sh

正式部署：

./build-site.sh
# CI 同：.github/workflows/deploy_pages.yml → ./build-site.sh --output-dir ../public_html

本地立刻验证进度条 seek（可选）：

zola build --base-url http://127.0.0.1:1111/
node scripts/serve-with-ranges.mjs --no-watch -p 1111

然后访问 http://127.0.0.1:1111/。说明：

--base-url 让构建出的 CSS/JS 链接指向本地，避免指向 suchaharcan.github.io。
seek 能力来自 serve-with-ranges.mjs（发送 Accept-Ranges: bytes），不是 zola serve。
zola serve 不支持 Range，故默认本地首次拖动会触发播放器 Blob 兜底（下载整首后再跳），不需要从头播到尾。

其他常用命令：

zola build --force   # 清空 output 后重建
zola check           # 检查链接，不输出站点

设计细节与根因分析见 Nanolog · 热力图与音乐播放器。

8.3 原构建命令速查

./build-site.sh  # 可选；若存在新增加密博客则必选
zola build --force
zola serve
zola check

九、部署与发布

部署源码参考 .github/workflows/deploy.yml

十、Zola.toml 配置节点作用解读

全局(zola.toml)

title = "Rocky‘s Blog"  
base_url = "https://suchaharcan.github.io/"
description = "月更 技术博客 CXX优先"

theme = "ametrine"

compile_sass = true
minify_html = true
feed_filenames = ["atom.xml", "rss.xml"]            # 生成的 RSS/Atom 订阅文件
build_search_index = true                            # 生成搜索索引
author = "Suchaharcan" 


taxonomies = [
  { name = "tags", feed = true, paginate_by = 10 },
  { name = "categories", feed = true },
]                                               # 分类和标签的配置

[markdown]
render_emoji = false
smart_punctuation = true
lazy_async_image = false
bottom_footnotes = true             # 脚注显示在底部
external_links_class = "external"
github_alerts = true            # 显示 GitHub 警告

[markdown.highlighting]
style = "class"
light_theme = "monokai-pro-light"
dark_theme = "monokai-pro"
extra_themes = [
  "themes/ametrine/giallo/themes/monokai-pro-light.json",
  "themes/ametrine/giallo/themes/monokai-pro.json",
]

[extra]
# Put all your custom variables here
# 全站 Umami：static/analytic/umami.js（覆盖首页 / 文章 / 标签 / 404 等所有页面）
scripts = ["analytic/umami.js"]

feed_sections = [

  { name = "Nanolog", path = "@/nanolog/_index.md" },
  { name = "Blog", path = "@/01Write_blog/_index.md" },
]                                 # 手动指定 哪些导航栏中的 RSS 可订阅项 sections 

accent_color = ["hsl(270 13% 48%)", "hsl(290 20% 71%)"]
# home_url = "@/home/index.md"
issues_url = "https://github.com/SuchaharCan/SuchaharCan.github.io/issues/new"            # 弃用 
source_url = "https://codeberg.org/SuzhaharCan/SuzhaharCan.codeberg.page"            # 网站源码在Codeberg ，可跳转直接在线修改博客， 在 kanban/ nanolog/ 中使用 
replog_url = "https://github.com/SuchaharCan/SuchaharCan.github.io/actions/workflows/deploy_pages.yml"            # 网站部署在 github.io， 可跳转点击 触发重新部署 。
copy_button = true
show_reading_time = true

show_backlinks = true
date_format = "%d %B %Y"
date_format_long = "%d %B %Y, %R (%Z)"
date_locale = "en_IE"                    # zola 暂不支持中文， 默认 英文
timezone = "Asia/Shanghai"               # 时区， HTML/JS 业务逻辑判断 使用


show_comments_qr = false  #评论二维码， 暂时禁用， 我有 社交账号，但我暂无 海外运营想法 禁用，若文章有价值， 我会直接 分享到HackerNews 上


csp = [
  { directive = "font-src", domains = [
    "'self'",
  ] },
]          # 内容安全策略，启用，限制外部脚本注入，提高网站 安全性， 若 后续功能开发的模块需要 JS脚本，此处需要 同步更新

[extra.music_player]
enabled = true
base_url = "/music"   # 音乐资源：static/music/ → /music/

单篇文章启用播放器：在文章 front matter 增加 [extra.music_player]，见 §8.1。

手动指定文章分类，用于文章列表页面的分类显示大类划分 : 归档，有价值，热门



[[extra.categories]]
name = "Tracking"
description = "Posts that need to be continuously updated."
color = "green"
icon = "fire"

构建脚本说明：`dev.sh` 与 `build-site.sh`

本站有两条常用入口脚本，分别对应本地开发预览与正式构建。二者都会在 Zola 构建前同步加密文章密文，但后续步骤不同。

一览

脚本	用途	输出	典型场景
`./dev.sh`	本地开发 + 热重载预览	不强调完整 `public/` 产物	改文章、改样式、调试加密页
`./build-site.sh`	正式静态站点构建	`public/`（或 `--output-dir` 指定目录）	部署前、CI、需要完整校验

`dev.sh` — 本地开发

作用

在本地启动 Zola 开发服务器（zola serve），保存文件后自动重建并刷新预览。

执行步骤

① node scripts/encrypt-content.mjs   # 同步加密文章密文
② zola serve [你传入的参数]          # 本地预览（默认 http://127.0.0.1:1111）

源码

node scripts/encrypt-content.mjs
exec zola serve "$@"

何时使用

新增或修改了加密文章（[extra.encryption] encrypt = true）时，需先跑密文同步再预览。
改普通文章、模板、样式、JS/CSS 时，也可用本脚本（密文同步幂等，多跑无害）。

不会做的事

不执行 post-build.mjs（RSS/Atom、搜索索引不会剔除加密文章条目）。
不执行 verify-kanban-build.mjs（看板产物完整性校验）。
不负责生成可部署的完整发布包；部署请用 build-site.sh。

常用示例

./dev.sh                    # 默认端口 1111
./dev.sh --open             # 构建后自动打开浏览器
./dev.sh -p 3000            # 指定端口

说明

zola serve 不支持 HTTP Accept-Ranges，本地音乐播放器进度条首次拖动可能需 Blob 兜底（见 Nanolog 2026-07-12）。
若仅改非加密内容、密文已存在，也可手动：zola build && zola serve（跳过加密同步）。

`build-site.sh` — 正式构建

作用

生成可部署的静态站点目录，并完成加密相关的构建后处理与看板校验。CI（.github/workflows/deploy_pages.yml）调用的是本脚本。

执行步骤

① node scripts/encrypt-content.mjs      # 全量同步加密密文
② zola build [可选参数]                  # 输出静态 HTML 到 public/
③ node scripts/post-build.mjs           # 从 RSS/Atom、搜索索引移除加密文章
④ node scripts/verify-kanban-build.mjs  # 校验 kanban 周页是否均已生成

各子步骤职责

步骤	脚本	说明
构建前	`encrypt-content.mjs`	扫描 `content/`，对 `encrypt = true` 的文章重加密；删除已取消加密的多余 JSON
构建	`zola build`	Zola 原生编译：Markdown → HTML，拷贝 `static/` → `public/`
构建后	`post-build.mjs`	加密页不出现在订阅源与站内搜索索引中
构建后	`verify-kanban-build.mjs`	确保 `content/kanban/YYYY-MM-DD.md` 在输出目录均有对应页面

何时使用

推送 / 部署到 GitHub Pages 之前。
需要验证看板、加密、订阅源行为是否正确时。
本地想确认与线上一致的完整产物时。

常用示例

./build-site.sh
./build-site.sh --output-dir ../public_html   # CI 用法；并 export ZOLA_OUTPUT_DIR 供后置脚本

参数

支持将额外参数原样传给 zola build（如 --output-dir）。
--output-dir 会设置环境变量 ZOLA_OUTPUT_DIR，供 post-build.mjs 与 verify-kanban-build.mjs 读取正确输出目录。

对比：何时用哪个

需求	推荐命令
本地边改边看	`./dev.sh` 或 `zola serve`
改了加密文章并要本地解密预览	`./dev.sh`
部署前完整构建	`./build-site.sh`
只改样式、不涉及加密	`zola build && zola serve` 即可
本地立刻验证音乐进度条 seek	`zola build --base-url http://127.0.0.1:1111/` 后 `node scripts/serve-with-ranges.mjs --no-watch -p 1111`（可选，见模板指南 §8.2）

与 CI 的关系

GitHub Actions 工作流 不调用 dev.sh，部署步骤为：

./build-site.sh --output-dir ../public_html

与本地正式构建一致，无需单独改 workflow。

参考

Zola Documentation
Tera Template Engine
daudix.one content — 本文 Markdown 示例主要来源
daudix: Zola vs Jekyll — 目录结构与模板覆盖的详细说明
daudix: My Blog Workflow — front matter 模板与图片工作流

本文即按上述规范编写：toc = true 启用目录，accent_color 设置页面强调色，内部链接使用 @/ 语法。

6.25 – 6.30 验证计划

2026-06-25T00:00:00+00:00

待办

Professional CMake: A Practical Guide 通读

@start 2026-06-25 @due 2026-06-26 @priority 5 @labels red, orange,green,blue @top red

基础通识
下载与导出
库（接口，静态，动态）
etc

先通读，再精读。生词后续纳入Eudic 最后在本地重写理解，编写XMind 文档

C++20 预研

@due 2026-06-28 @priority 3 @labels blue

第一章节

第一章节的内容就很多

408 动手

@due 2026-06-30 @priority 3 @labels blue

408 - 数据结构

408 备考是最重要的下半年的核心事项。

英语单词

@due 2026-06-29 @priority 3 @labels blue

墨墨记单词
Eudic

单词重新捡起来

已完成

本地仓库搭建

@start 2026-06-25 @due 2026-06-25 @priority 5 @labels red, blue @bg #FFF8E1 @top orange

01_cmake
02_cpp_syntax
03_algorithms

Codeberg仓库建立 ok 架构设计完成 ok 初次版本已推送 ok 2026-06-25 19:05:12

资源

本地仓库搭建

@start 2026-06-15 @priority 2

Zola 本地 build --force
Codeberg 仓库写入权限

content/kanban/ 目录、ReDeplog 流水线。

参考素材

@priority 1

article_details 图标行
Trello 列布局截图

目标

完成后：进入状态

@priority 5 @goal complete

进入学习状态
远离小说熬夜虚度光阴的环节

实现 Trello 式五列看板，替代纯 Markdown 表格维护。

未完成：进度失控与失效

@priority 4 @goal risk

继续沉迷，浪费时间

进度汇报

2026年06月25日第一天

@priority 5 @goal complete @bg #FFF8E1

CMAKE，C++，Algo 前置环境代码搭建
小说卸载，家务打扫，决定不再点外卖，自己做。
游戏，熬夜等不再参与，晚上11点后就休息
无关事项：刷新更新，看无意义的内容拒绝
主动有意思的使用博客进行记录和整理

远离小说熬夜虚度光阴的环节

第一天，坚持下去今天剩余的时间： 1小时单词 1小时技术文档通读 1小时原子习惯阅读

2026年06月26日到月底

@priority 5 @goal complete @bg #FFF8E1

CXX项目临时更新暂时搁置

2026年07月09日提交，回归正常，档期回归

2026-06-24T14:00:00+00:00

2026年06月24日 09:40（东八区 / 北京时间）

看板线上缺失排查 · Ametrine 子模块更新 · 新文章卡片样式

概述

本轮三件事：周计划看板本地/线上一致性排查、Ametrine 主题子模块更新到 6d1c244（New article card design）、Debug 专栏应用两种文章卡片样式。看板本地可用 zola build / zola serve；正式部署推荐 ./build-site.sh（含看板产物校验）。

1. 看板列表仅显示 1 张卡片

1.1 问题

环境	`/kanban/` 列表	`/kanban/2026-06-16/` 明细
本地 `public/`	2 张卡片	可打开
线上 gh-pages	1 张卡片	404

1.2 排查流程（源码 → 构建）

阶段 A：源码

检查项	本地 `00BlogZola`	Codeberg `content/kanban/`
`2026-06-16.md`	✓	✓
`2026-06-22.md`	✓	✓
`week_start` / `week_end`	均已配置	一致

结论：源码两侧一致，问题不在 Markdown 缺失。

阶段 B：构建产物

检查项	本地 `public/kanban/`	GitHub `gh-pages/kanban/`
`index.html` 中 `.kanban-week-card`	2	1
`data-json` 热力图条目	2 条	1 条
`2026-06-16/index.html`	✓ 存在	不存在
`2026-06-22/index.html`	✓	✓

结论：线上 gh-pages 是旧/不完整部署，并非前端 JS 把第二张卡片藏起来——HTML 里根本没有第二张卡片，明细页目录也未生成，手动输入 URL 必然 404。

1.3 根因

线上 gh-pages 某次部署产物不完整（缺少 2026-06-16/ 目录与列表第二张卡片），与本地是否使用 ./build-site.sh 无直接关系——GitHub Actions 同样只跑 zola build，看板理论上应能完整生成。部署流水线原先缺少 kanban 产物校验，异常未能被及时发现。

1.4 修复

文件	改动
`scripts/verify-kanban-build.mjs`	对比 `content/kanban/20.md` 数量与 `public/kanban//index.html`、列表卡片数
`build-site.sh`	构建末尾调用 verify
`.github/workflows/deploy_pages.yml`	改用 `./build-site.sh` + submodule init + verify

重新部署后（GitHub → Actions → Build Zola and Deploy to GitHub Pages → Run workflow），线上应出现 2 张卡片且 /kanban/2026-06-16/ 可访问。

1.5 补充：本地为何只用 `zola build` / `zola serve` 就能完整实现看板？

日常开发若只用 zola build、zola serve，不主动跑 ./build-site.sh，看板依然完整——这是预期行为，因为看板整条链路都在 Zola 原生构建内，不依赖 build-site.sh 额外步骤。

zola build 已覆盖看板所需：

content/kanban/*.md
    ↓  Zola 读取 front matter（week_start、stats…）
templates/kanban_list.html / kanban.html
    ↓  load_data 内嵌原始 Markdown 到 HTML
static/js/kanban-*.js
    ↓  浏览器解析、渲染热力图 / Trello 看板
public/kanban/

列表页与明细页模板在构建时用 load_data 把 Markdown 写进 HTML（无需 static/kanban/ 副本）：

templates/kanban_list.html — 每张周卡片内嵌 <textarea class="kanban-raw-source">
templates/kanban.html — 明细页 #kanban-raw-markdown

只要 content/kanban/ 下有带 week_start 的 .md，zola build 就会生成对应页面与列表卡片；zola serve 仅本地预览 public/。

build-site.sh 在四步中，看板只依赖第 ② 步：

步骤	脚本	作用	看板是否需要
①	`encrypt-content.mjs`	为 `[extra.encryption] encrypt = true` 的文章生成 `static/encryption/pages/*.json`	否 — kanban 未开加密
②	`zola build`	生成全部静态页	是 — 看板全靠这步
③	`patch-search-index.mjs`	修补 elasticlunr 搜索索引	否
④	`verify-kanban-build.mjs`	对比源码周数与构建卡片数	否 — 仅部署前防回归

何时才需要 ./build-site.sh？

场景	推荐命令
本地调试看板、普通文章	`zola serve`（或先 `zola build`）
本地调试加密文章详情	需先跑 ①，或直接 `./build-site.sh`
正式部署前	`./build-site.sh`（加密 + 搜索 + 看板校验）

与「线上少一张看板」的关系（再强调）：

	本地 `zola build`	线上 gh-pages（问题当时）
源码	2 个 kanban `.md`	Codeberg 同样 2 个 ✓
产物	`public/kanban/` 含 2026-06-16 + 2026-06-22	仅 2026-06-22，2026-06-16 目录缺失

结论：看板 = Zola 模板 + content + static JS，zola build 已足够；build-site.sh 是站点其他能力（加密、搜索、部署校验）的包装，不是看板运行的前提。 线上问题来自 gh-pages 部署产物不完整，而非本地少用了 build-site.sh。

2. Ametrine 子模块更新

cd themes/ametrine
git fetch origin main
git checkout main && git pull
# 父仓库记录新 commit
git add themes/ametrine

项目	值
远程	codeberg.org/daudix/ametrine
目标 commit	`6d1c244` — New article card design
参考效果	daudix.one/blog

主要变化：templates/partials/article_list.html 卡片布局（banner 缩略图置顶）、article_details.html 元数据分行、_article-list.scss 渐变/accent 视觉。

3. 两种文章卡片样式如何引用

Ametrine 通过 front matter 组合决定卡片形态（与 daudix 博客一致）：

样式 A — 带横幅图（`has-banner` + `has-accent-color`）

列表卡片顶部有大图；明细页开头由 base.html 的 #banner 渲染同目录图片。

[extra]
accent_color = ["hsl(210 25% 34%)", "hsl(210 31% 53%)"]  # 浅色 / 深色各一组 HSL
banner = "banner.jpg"           # 与 index.md 同目录
banner_position = "50% 40%"     # 可选，缩略图裁剪焦点

图片放在文章文件夹内，如 content/…/my-post/banner.jpg
构建时 Zola resize_image 自动生成 WebP 缩略图

本站示例（Debug 专栏）：

文章	目录
Mac Chrome ReOpen	`02Engineer_blog_Debug/2026-06-23-Chrome-ReOpen/`
VPN 断网排查	`02Engineer_blog_Debug/2026-06-20-VPN-noNet/`

样式 B — 纯 accent 渐变（`has-accent-color`，无 banner）

无列表缩略图；可展示 发布日 + 更新日 + 作者 等元数据行。

updated = 2026-06-21          # 与 date 不同则显示「更新」图标
authors = ["SuchaharCan"]     # 可选，显示 By …

[extra]
accent_color = ["hsl(145 22% 34%)", "hsl(145 28% 50%)"]
# 不写 banner

本站示例：

文章	特征
Little Snitch 教程	仅 accent + `updated`
One (Teardown)	accent + `authors`

明细页横幅

只要设置了 banner，列表与明细共用同一字段；明细页无需额外模板，主题 base.html 自动在正文前插入 #banner 大图（与 daudix 一致）。

accent_color 格式

推荐：["hsl(H S% L%)", "hsl(H S% L%)"] — 分别为浅色/深色模式
也支持单字符串 "hsl(270 50% 60%)"

4. 本地验证

看板调试可直接：

zola build && zola serve

正式部署或需加密/搜索/校验时：

./build-site.sh
# 期望输出：kanban verify OK: 2 week(s), list cards match

页面	检查
`/kanban/`	2026 年 6 月分组下 2 张卡片
`/kanban/2026-06-16/`	Trello 五列看板
`/02Engineer_blog_Debug/`	2 张带图卡片 + 2 张纯渐变卡片
`/02Engineer_blog_Debug/chrome-reopen/`	顶部 banner 大图

5. 看板列表卡片 UI · 热力图「今天 / 本周」标记

5.1 看板周卡片（列表页）

需求： 元数据参考 Ametrine 文章详情图标盒式风格；标题以下第二、三行加粗并居中；字号随卡片高度变化；天数跨度与卡片高度的视觉区分需更明显。

模板结构（templates/kanban_list.html）：

h3 标题（左对齐 + accent 竖线）
└─ .kanban-week-body（居中容器）
   ├─ .kanban-week-meta-row  日期 / 剩余 / 进度 / 星级
   └─ .kanban-week-stats      共 N 项 · 已完成 · 待办 · 进行中
└─ .kanban-week-span-spacer  （flex 占位，不再重复叠加高度）

样式要点（sass/kanban/style.scss）：

项	实现
图标	恢复 Ametrine `.icon` 盒式：`box-shadow` + 圆角背景 + `accent-color`
元数据加粗	`.kanban-week-meta-row`、`.kanban-week-stats` → `font-weight: 600`
居中	`.kanban-week-body` + `justify-content: center`
字号联动	`font-size: calc(0.78rem × var(--kanban-meta-scale))`，图标同理
卡片高度	单一变量 `--kanban-card-body-height`，去掉「基础高度 + spacer 再叠一层」

高度 / 字号映射（SSR 与 JS 共用同一公式，static/js/kanban-rules.js → applyListCardMetrics）：

--kanban-card-body-height = 88px + 280px × (span_days / 7)
--kanban-meta-scale       = 0.85 + 0.35 × (span_days / 7)

看板	跨度	卡片高度	meta-scale
2026-06-22	2 天	168px	0.95
2026-06-16	7 天	368px	1.20

kanban-list.js 与 kanban-heatmap.js 筛选后均调用 KanbanRules.applyListCardMetrics()，避免两套算法不一致。

CSS 变量（:root）：

--kanban-week-body-min: 88px;
--kanban-week-span-height: 280px;

若需进一步拉大/缩小高度差，优先调 --kanban-week-span-height。

5.2 热力图「今天 / 本周」标记

需求： 全年视图（周格子）与单月视图（天格子）下方，用空心三角标出当前周或当天；时区与站点一致；不破坏现有热力图样式。

时区： 读取 #kanban-week-list 的 data-timezone（来自 zola.toml → extra.timezone，当前 Asia/Shanghai），复用 KanbanRules.clockInTimezone。

显示规则：

视图	标记位置	显示条件
全年（周格）	对应周格子下方	所选年份 = 今年，且该周包含今天
单月（天格）	对应天格子下方	所选年/月 = 当前年/月，且该格 = 今天

DOM 结构：

.kanban-heatmap-week-slot / .kanban-heatmap-day-slot
├─ button.heatmap-week-cell / .heatmap-day-cell
└─ span.kanban-heatmap-today-marker   ← 仅 .is-current 时可见

样式（static/css/heatmap.css，仅作用于 Kanban 热力图）：

空心三角：::before 描边 + ::after 内层 --bg-muted-1 镂空，尖端朝上指向格子
非当前格不预留占位，避免整行高度被撑开

涉及文件：

文件	改动
`static/js/kanban-heatmap.js`	`getTodayContext`、`wrapWeekCell`、`wrapDayCell`
`static/css/heatmap.css`	`.kanban-heatmap-today-marker` 及 slot 布局

5.3 本地验证（看板 UI + 热力图）

页面	检查
`/kanban/` 首次打开	年份 = 当前年、月份 = 当前月（日视图 + 当月卡片）
`/kanban/` 全年	6 月对应周格下方有空心上三角；2 天 / 7 天卡片高度差明显
`/kanban/` 选 6 月	24 日格下方有标记；元数据两行居中加粗
切换年份	非当前年不显示周标记

zola build && zola serve
# 打开 http://127.0.0.1:1111/kanban/

5.4 热力图默认选中当前年 / 当前月

需求： 进入 /kanban/ 时，右上角年份、月份下拉不再默认「最近有数据的年份 + 全年」，而是直接落在当前年、当前月（按站点时区），省去手动切换。

默认逻辑（static/js/kanban-heatmap.js → init()）：

var todayCtx = getTodayContext(siteTimezone());
var activeYear = years.indexOf(todayCtx.year) >= 0 ? todayCtx.year : years[0];
var activeMonth = activeYear === todayCtx.year ? todayCtx.month : 0;

情况	年份	月份
当前年有看板数据	当前年	当前月（日视图热力图 + 当月卡片列表）
当前年无数据，回退到最近年份	`years[0]`	`0`（全年）

时区： 与 §5.2 相同，读 #kanban-week-list 的 data-timezone（zola.toml → extra.timezone）。

未改动的交互： 用户手动切换年份时，月份仍会重置为「全年」（原有行为）；仅首次加载默认当前年/月。

验证： 刷新 /kanban/，右上角应显示「年份: 2026」「月份: 6 月」，热力图为按天网格，下方列表为 6 月卡片，无需再点选月份。

最后补充：优先使用 Codeberg中的 workflow.此处是第一源，同步给 github

2026-06-24T10:00:00+00:00

2026年06月24日 10:11（东八区 / 北京时间）

GitHub Pages 部署流水线 ENAMETOOLONG · 看板 Markdown 误为 symlink

概述

SuchaharCan.github.io Actions #28 在 Init theme submodule and build 阶段失败：encrypt-content.mjs 遍历 content/ 时对 content/kanban/2026-06-16.md 调用 statSync 抛出 ENAMETOOLONG。本地 macOS 复现困难，Linux CI 必现。

根因：该文件在 Git 索引中被误记为 symlink（mode 120000），但 blob 内容是整篇 Markdown；Linux 检出后符号链接目标 ≈ 2500 字符的「伪路径」，stat 解析失败。附带修复了 build-site.sh 与 CI 验证路径问题。

1. 现象

1.1 CI 报错摘要

Error: ENAMETOOLONG: name too long, stat
  '.../zola_source/content/kanban/2026-06-16.md'
    at walkMd (scripts/encrypt-content.mjs:52)
    at main (scripts/encrypt-content.mjs:81)

流水线：deploy_pages.yml — Codeberg 拉源码 → ./build-site.sh --output-dir ../public_html → 首步即 node scripts/encrypt-content.mjs。

1.2 为何本地未报错

环境	`2026-06-16.md` 磁盘形态	`encrypt-content.mjs` 行为
本地 macOS	普通文件 `-rw-r--r--`	`stat` 正常
Linux CI	Git 检出为 symlink	`stat` 跟随链接 → 目标为整段 Markdown → `ENAMETOOLONG`

表面看报错路径长度正常（约 100 字符），容易误判为路径拼接 bug；需结合 Git 对象 mode 才能定位。

2. 根因定位（思考链）

2.1 排除项

假设	结论
`import.meta.url.pathname` 在 Linux 上算错 ROOT	可能改进，但无法解释仅单个 kanban 文件失败
`content/kanban/` 存在目录级 symlink 循环	本地 `find -type l` 无异常；问题在单文件 mode
kanban 需加密导致读文件失败	kanban 未开 `[extra.encryption]`；失败发生在 walk 阶段，尚未读内容

2.2 关键命令

git ls-files -s content/kanban/
# 120000 71584b78...  content/kanban/2026-06-16.md   ← symlink mode
# 100644 18e34c47...  content/kanban/2026-06-22.md   ← 正常文件

Git mode 120000 = symlink；blob 内本应只存 目标路径字符串
实际 blob 大小 2526 字节，内容为 +++ 开头的完整周计划 Markdown
Linux git clone 按 symlink 检出 → 链接目标 = 整篇文档文本 → statSync / readlink 解析时触发 ENAMETOOLONG

2.3 成因推测

某次提交或合并时，该文件被错误标记为 symlink（可能来自错误 git add、工具导入或复制粘贴异常），而 blob 仍写入 Markdown 正文。macOS 工作区可能曾被手动覆盖为普通文件，故与 CI 表现不一致。

2.4 附带问题（修复 CI 全流程时发现）

问题	说明
`build-site.sh` 未导出 `ZOLA_OUTPUT_DIR`	`./build-site.sh --output-dir ../public_html` 时，`patch-search-index.mjs` / `verify-kanban-build.mjs` 仍读 `public/`
workflow 验证路径错误	构建输出在 `../public_html`，步骤却检查 `zola_source/public_html`

3. 修复内容

文件	改动
`content/kanban/2026-06-16.md`	`git rm --cached` 后重新 `git add`，索引 mode `100644`（普通文件）
`scripts/encrypt-content.mjs`	`walkMd` 用 `readdirSync({ withFileTypes: true })`，跳过 symlink；`ROOT` 改用 `fileURLToPath`
`build-site.sh`	解析 `--output-dir`，export `ZOLA_OUTPUT_DIR` 供后续 Node 脚本
`scripts/patch-search-index.mjs`	读取 `ZOLA_OUTPUT_DIR` 定位搜索索引；输出目录不存在时安全退出
`scripts/verify-kanban-build.mjs`	`fileURLToPath` 统一 ROOT
`.github/workflows/deploy_pages.yml`	验证步骤改为 `[ -d "../public_html" ]`

加固后的 walkMd 逻辑（即使将来再误入 symlink 也不会拖垮构建）：

for (const ent of readdirSync(dir, { withFileTypes: true })) {
  if (ent.isSymbolicLink()) continue;
  // ...
}

4. 解决步骤

部署架构：Codeberg 私有源码 + GitHub.io 仅托管 workflow 与 gh-pages 静态页。

4.1 推送 Codeberg（必须）

仓库：codeberg.org/SuzhaharCan/SuzhaharCan.codeberg.page

git add content/kanban/2026-06-16.md \
        scripts/encrypt-content.mjs \
        scripts/patch-search-index.mjs \
        scripts/verify-kanban-build.mjs \
        build-site.sh
git commit -m "fix: kanban week file git mode and CI build output paths"
git push origin main   # 或当前默认分支

4.2 同步 GitHub.io workflow（若与 Codeberg 副本不一致）

仓库：SuchaharCan/SuchaharCan.github.io

将 deploy_pages.yml 中 Verify Kanban build output 的路径修正同步到该仓库（../public_html）。

4.3 重跑流水线

GitHub → Actions → Build Zola and Deploy to GitHub Pages → Run workflow

期望日志顺序：

encryption: N page(s) → static/encryption/pages/（无 ENAMETOOLONG）
zola build → Done in …ms
kanban verify OK: 2 week(s), list cards match
✅ 验证通过：public_html … index.html
Deploy push 至 gh-pages

4.4 线上验收

检查项	期望
`/kanban/`	2 张周卡片
`/kanban/2026-06-16/`	200，非 404
构建日志	无 `encrypt-content.mjs` 栈追踪

5. 本地验证

# 模拟 CI 自定义输出目录
ZOLA_OUTPUT_DIR=public_test ./build-site.sh --output-dir public_test
# 期望：kanban verify OK: 2 week(s), list cards match

# 确认 Git 索引 mode
git ls-files -s content/kanban/2026-06-16.md
# 期望：100644 ...

6. 经验小结

ENAMETOOLONG + 路径看起来不长 → 优先查 symlink 目标 与 git ls-files -s mode，不要只看路径字符串长度。
跨平台构建 → 加密/遍历类脚本应 不跟随 symlink，并用 fileURLToPath 解析 ESM 路径。
build-site.sh 包装多步 → --output-dir 须 显式传播 给所有读 public/ 的后置脚本。
CI 与本地目录布局不同 → workflow 验证路径要与 zola build --output-dir 同一基准（本次为 zola_source 的上一级 public_html）。

2026-06-24T04:00:00+00:00

2026年06月24日 12:00（东八区 / 北京时间）

站点更新总结：Umami 统计 · 文章加解密 · 管理员特权 · 访客随机解密 · 编辑按钮门控

概述

本轮迭代围绕 可观测性（Umami）、内容保护（构建期加密 + 运行时解密）、特权与访客双模式 以及 编辑类按钮的可见性控制 展开。所有改动均在站点根目录 templates/、static/、scripts/、zola.toml 完成，未修改 themes/。

构建入口统一为：

./build-site.sh   # encrypt-content.mjs → zola build → patch-search-index.mjs

1. Umami 流量统计

1.1 问题与根因

现象	原因
Umami 控制台长期无数据	`self_hosted_url` 误填为博客域名，脚本指向不存在的 `/script.js`
控制台 CSP 报错	`script-src` / `connect-src` 未放行 Umami Cloud
`gateway.umami.is/api/send` 被拦截	Umami 新版上报端点未加入 CSP

1.2 修复要点

配置 / 文件	说明
`zola.toml` `[extra.analytics]`	`service = "umami"`；留空 `self_hosted_url`（走 Umami Cloud）
`zola.toml` `[extra.csp]` `connect-src`	新增 `gateway.umami.is`
`static/analytic/umami.js`	全站幂等加载器；`zola.toml` → `scripts = ["analytic/umami.js"]`
`static/js/nanolog.js`	合并重复副本，统一路径

主题 build 模式仍会注入 cloud.umami.is/script.js；站点层脚本作兜底，避免漏统计。

1.3 验证

Network：cloud.umami.is/script.js → 200；gateway.umami.is/api/send 无 CSP 拦截
Umami 控制台

更细的调用链见同目录较早条目：2026-06-23T12:00:00Z.md。

2. 文章加解密（底层通用能力）

2.1 设计原则

构建期加密：正文不进 HTML 明文，降低「查看源代码」直接可读的风险
运行时解密：依赖 Web Crypto（需 HTTPS 或 localhost）
任意目录通用：凡 front matter 声明加密即纳入流水线，与板块路径无关

2.2 启用方式（单篇文章）

[extra.encryption]
encrypt = true

建议 [extra] 写在 [extra.encryption] 之前，避免 TOML 表顺序导致解析异常。

2.3 文件结构

层级	路径
站点配置	`zola.toml` → `[extra.encryption]`
构建脚本	`scripts/encrypt-content.mjs`、`scripts/encryption-lib.mjs`
密文输出	`static/encryption/pages/<相对路径>.json`
清单	`static/encryption/manifest.json`
全站注入	`templates/base.html` → `partials/encryption_config.html`
加密文章 UI	`templates/partials/encrypted_article.html`
文章模板	`templates/article.html`（判断 `encrypt` 后 include）
前端	`static/encryption/config.js`、`admin.js`、`visitor.js`、`crypto.js`、`article.js`
样式	`static/encryption/admin.css`、`article.css`

2.4 构建与 CSP

配置与密文通过 <textarea hidden> 注入页面，避免内联 <script> 触发 CSP 拦截
script-src 允许 'self'、cdn.jsdelivr.net（marked）、主题合并的 cloud.umami.is
未跑加密脚本仅 zola build 时，页面会提示「密文未找到，请先运行 ./build-site.sh」

2.5 测试文章

路径	说明
`content/00Read_blog_Math/2026-06-03-First Base Chater/`	数学板块加密试点
`content/02Engineer_blog_Debug/2026-06-23-Chrome-ReOpen/`	Debug 板块加密验证

3. 管理员特权模式

3.1 进入方式

连续点击左上角 #site-sidebar-header（站点图标）6 次：

点击次数	反馈
第 3–5 次	Toast：「再点击 N 次可进入管理员模式」
第 6 次	Toast：「你已经是管理员，可浏览所有加密博客啦」
已是管理员	鼠标悬停图标显示「你已经是管理员」

状态保存在 sessionStorage（blog-encryption-admin-until）。

3.2 有效期（`admin_ttl_secs`）

admin_ttl_secs = 60   # 秒，到期自动恢复访客

进入特权时按 TTL 设置 精确 setTimeout，并每 500ms 兜底检查
到期触发 encryption-admin-expired：移除 html.encryption-admin-active、文章重新上锁、看板恢复只读

3.3 管理员能力

解密所有 encrypt = true 的文章
显示并可用 Nanolog / 看板上的 ReDeplog、Edit Post 等编辑入口
看板在 week_start～week_end 窗口内可解锁拖拽；截止日当日 23:00（extra.timezone）前仍可编辑

4. 访客模式与随机解密

4.1 默认展示

加密文显示：「🔒 本文已加密」
提示语：「随机刷新时，可能会触发解密哦。」

4.2 随机解密逻辑（`static/encryption/visitor.js`）

visitor_refresh_min = 9
visitor_refresh_max = 20

每篇文章、每个浏览器 session 独立计数
首次访问随机抽取阈值（9～20 次刷新之间）
刷新次数达到阈值后 自动解密（无需管理员）
解密状态在该 session 内对该文保持

5. 编辑类按钮门控（交互隐藏）

原则：访客只见只读；编辑入口仅在管理员特权下出现。

位置	访客	管理员
Nanolog 列表	隐藏 ReDeplog、Edit Post、发布按钮	显示
看板明细	锁定按钮固定「🔒 只读」，不可解锁	有效期内可解锁；显示工具栏；截止日 23:00 后变「只读（已过期）」
加密文侧边栏 TOC	非管理员隐藏	管理员显示

实现：元素加 class encryption-admin-only；html.encryption-admin-active 时由 admin.css 显示。看板逻辑在 kanban-board.js 中额外校验 EncryptionAdmin.isAdminActive()。

6. 关联改动（本轮一并收敛）

项	说明
看板数据源	统一为 `content/kanban/`，构建时内嵌 MD，移除多余 `kanban/` 副本
Nanolog 列表宽度	`sass/nanolog/style.scss` 调至与正文同宽
`nanolog.js`	移除不存在的 `save-token-btn` 控制台警告

7. 配置速查（`zola.toml`）

[extra]
scripts = ["analytic/umami.js"]

[extra.analytics]
service = "umami"
id = "cdf54193-b449-4454-884b-029e82434c32"
exclude_hash = true

[extra.encryption]
enabled = true
algorithm = "AES-GCM"
key = "rocky-blog-dev-key-change-in-production"   # 生产环境请更换
admin_ttl_secs = 60
visitor_refresh_min = 9
visitor_refresh_max = 20

CSP connect-src 需包含：gateway.umami.is（以及主题自动合并的 cloud.umami.is、*.umami.dev）。

8. 自测清单

./build-site.sh 无报错，控制台输出 encryption: N page(s)
加密文：访客默认上锁；连点 6 次进入管理员可解密；TTL 到期后恢复上锁
加密文：无痕窗口反复刷新，约 9～20 次后访客随机解密
Nanolog / 看板：访客无 Edit Post、ReDeplog；管理员可见
看板：截止日 23:00 前可解锁，之后只读；列表剩余天数与明细一致
Chrome DevTools 无 CSP inline script 报错；Umami 上报 200

9. 看板列表 / 热力图 · 编辑窗口判定（追加）

9.1 列表页与热力图

项	说明
页头	移除大标题「周计划」；副标题居中加粗；补充「单个看板时间跨度 1 ~ 14 天」
年份 / 月份下拉	修复脚本重复加载导致菜单无法展开；月份含全年 + 1–12 月
年度视图	1–6 月 / 7–12 月两行；月份块间距 + 虚线分隔
周格填充	有效天数 / 7 比例自下而上着色；未满 7 天为部分填充
月份视图	切换具体月份后展开为按天网格，直观显示哪些日期纳入看板
验证数据	`content/kanban/2026-06-22.md`（06-22 ~ 06-23，2 天）

涉及文件：templates/kanban_list.html、static/js/kanban-heatmap.js、static/css/heatmap.css、sass/kanban/style.scss。

9.2 只读 / 可编辑判定（截止日 23:00）

原先按日历日比较 week_end，导致截止日当天 0 点起即只读。现改为：

截止日 week_end 当日 23:00 之前仍可解锁、拖拽、Edit Post
23:00 及之后（站点时区）永久只读
时区读取 zola.toml → [extra] timezone（当前 Asia/Shanghai），经模板 data-timezone 注入前端

例：截止 06-23，则 6 月 23 日 22:59 仍可编辑，23:00 起变只读。

位置	行为
明细页锁定按钮	访客：`🔒 只读`；超期：`只读（已过期）`；管理员且未超期：可锁定 / 解锁
列表剩余天数	截止日 23:00 前显示「今天」；当日 23:00 后显示「已截止」

公共逻辑：KanbanRules.isEditableWindow()、daysRemainingLabel()（static/js/kanban-rules.js）；看板页 data-timezone 在 templates/kanban.html，列表页在 #kanban-week-list。

# zola.toml
[extra]
timezone = "Asia/Shanghai"

参考： daudix.one · Umami 控制台

网站版本 1.0 正式版

2026-06-24T00:00:00+00:00

本文面向 访客与自建站参考者，说明本站 v1.0 正式版 的目录结构、设计架构，以及撰写博客时在 +++（TOML front matter）中可用的全部字段。技术栈为 Zola + Ametrine 主题；站点级定制在仓库根目录，不修改 themes/。

更细的模板 / Markdown 写法见 Zola 模板开发要点与 Markdown 语法速查；本轮功能迭代见 Nanolog 更新总结。

一、版本 1.0 能力总览

模块	路径 / 入口	说明
首页 Hub	`/`	个人介绍、徽章、联系方式
In - Reading	`/00Read_blog_Math/` 等	在读笔记（可加密）
Out - Writing	`/01Write_blog_CXX20/` 等	原创技术文
Out - Share	`/03Share_blog/`	工作流、工具分享
Debug	`/02Engineer_blog_Debug/`	排障记录
周计划看板	`/kanban/`	Trello 风格 + Markdown 规则引擎
Design	`/design/`	产品 / CLI / 插件展示
Nanolog	`/nanolog/`	站点开发短日志
BasB	`/basb/`	笔记树状整理
Archive	`/archive/`	全站文章归档 + 热力图
Umami 统计	全站	隐私友好访问量
文章加密	按文启用	构建期 AES-GCM + 管理员 / 访客双模式解密

构建命令：

./build-site.sh    # 加密 → zola build → 搜索索引补丁
zola serve         # 本地预览（加密解密需 localhost 或 HTTPS）

二、源码目录树

以下为 访客可见逻辑相关的仓库结构（省略 public/ 构建产物与主题内 demo 细节）：

00BlogZola/
├── zola.toml                 # 全站配置（导航、CSP、统计、加密、分类…）
├── build-site.sh             # 正式构建入口
├── scripts/
│   ├── encrypt-content.mjs   # 构建前：加密标记文章 → static/encryption/pages/
│   ├── encryption-lib.mjs    # 加密路径 / front matter 解析共用库
│   └── patch-search-index.mjs
├── content/                  # 所有页面内容（Markdown）
│   ├── _index.md             # 首页
│   ├── 00Read_blog_Math/     # 在读 · 数学
│   ├── 00Read_blog_English/
│   ├── 01Write_blog_*/       # 写作各子专栏（CMake / CXX / 论文…）
│   ├── 02Engineer_blog_Debug/
│   ├── 03Share_blog/
│   ├── kanban/               # 周计划（列表 + 每周 .md）
│   ├── nanolog/              # 开发日志（单文件即一篇）
│   ├── design/               # Design 页 + apps/* 子应用
│   ├── basb/                 # 树状笔记
│   └── archive/
├── templates/                # 覆盖主题的 Tera 模板（优先级高于 theme）
│   ├── base.html             # 全站：加密配置 + admin.js 注入
│   ├── article.html          # 文章：普通 / 加密分支
│   ├── partials/
│   │   ├── encrypted_article.html
│   │   ├── encryption_config.html
│   │   └── heatmap_component.html
│   ├── kanban.html / kanban_list.html
│   ├── nanolog.html / nanolog_list.html
│   ├── design.html / design_app.html
│   ├── archive.html / basb.html
│   ├── shortcodes/           # Markdown 短代码
│   └── macros/encryption.html
├── static/                   # 原样拷贝到站点根 URL
│   ├── analytic/umami.js
│   ├── encryption/           # 加解密运行时（admin / visitor / crypto / article）
│   ├── js/                   # kanban、nanolog、热力图、滚动条…
│   └── kanban/ …
├── sass/                     # 站点 SCSS（编译为 CSS）
│   ├── kanban/ nanolog/ design/ home/ …
└── themes/ametrine/          # 上游主题（勿改；用 templates/ 扩展）

模板覆盖原则： templates/foo.html 与主题同名时 完全替换 主题文件；常用模式为 {%% extends "ametrine/templates/....html" %%} + {%% block %%} 扩展。

三、设计架构

3.1 分层示意

flowchart TB
  subgraph build [构建期]
    MD[content/*.md]
    ENC[scripts/encrypt-content.mjs]
    ZOLA[zola build]
    MD --> ENC
    ENC -->|密文 JSON| STATIC_ENC[static/encryption/pages/]
    MD --> ZOLA
    STATIC_ENC --> ZOLA
    ZOLA --> PUBLIC[public/ 静态站点]
  end

  subgraph runtime [浏览器运行时]
    PUBLIC --> HTML[HTML + textarea 配置]
    HTML --> ADMIN[admin.js 特权模式]
    HTML --> VISITOR[visitor.js 随机解密]
    HTML --> ARTICLE[article.js 解密渲染]
    ADMIN --> ARTICLE
    VISITOR --> ARTICLE
    HTML --> UMAMI[umami.js 统计]
    HTML --> KANBAN[kanban-board.js]
    HTML --> NANO[nanolog.js]
  end

  subgraph theme [Ametrine 主题层]
    BASE[base.html 骨架]
    SIDE[sidebar 导航]
    HEAD[head.html CSP/脚本]
  end

  HTML --> BASE
  BASE --> SIDE
  BASE --> HEAD

3.2 内容 → 模板绑定

内容类型	front matter 关键字段	渲染模板
专栏列表	`template = "article_list.html"`	文章卡片列表
普通文章	`page_template = "article.html"`（section 默认）	文章页 + 可选热力图
加密文章	`[extra.encryption] encrypt = true`	`partials/encrypted_article.html`
周计划列表	`template = "kanban_list.html"`	周卡片 + 进度
周计划明细	`page_template = "kanban.html"`	五列看板
Nanolog 列表	`template = "nanolog_list.html"`	时间线短帖
Nanolog 单篇	`page_template = "nanolog.html"`	单条日志
Design	`template = "design.html"`	产品网格
Archive	`template = "archive.html"`	归档 + 热力图
BasB	`template = "basb.html"`	树状笔记索引

3.3 安全与特权模型

stateDiagram-v2
  [*] --> Visitor: 默认
  Visitor --> Admin: 连点左上角图标 6 次
  Admin --> Visitor: admin_ttl_secs 到期
  Visitor --> LuckyDecrypt: 同文刷新 9~20 次 session
  LuckyDecrypt --> Visitor: 关闭标签页 / 新 session
  Admin --> Decrypted: 全部加密文可读
  LuckyDecrypt --> Decrypted: 单篇可读

访客： 加密文默认上锁；看板固定「只读（已过期）」样式；隐藏 Edit Post / ReDeplog。
管理员： html.encryption-admin-active 时显示编辑按钮、可解密、看板在有效期内可解锁。
配置： zola.toml → [extra.encryption]（见下文站点级表）。

四、Front matter（`+++`）字段速查

Zola 使用 TOML 作为 front matter。以下汇总 本站实际可用 的字段；未列出的键也可写入 [extra]，但需自行在模板中读取才会生效。

4.1 顶层通用字段（Page / Section 均可）

字段	类型	必填	说明
`title`	string	推荐	标题；侧边栏、`<title>`、列表卡片
`description`	string	推荐	摘要；SEO、`og:description`
`date`	date	文章推荐	发布日期，如 `2026-06-24`
`updated`	date	可选	更新日期，显示在文章元信息
`draft`	bool	可选	`true` 时默认不构建；需 `zola build --drafts`
`weight`	int	可选	排序权重（配合 `sort_by = "weight"`）
`sort_by`	string	Section	子页排序：`date` / `weight` / `title` 等
`template`	string	Section	当前页使用的模板文件名
`page_template`	string	Section	子页面默认模板
`paginate_by`	int	Section	列表分页条数，如 `10`
`generate_feeds`	bool	Section	是否生成 atom/rss
`aliases`	[string]	可选	URL 别名，如 `["home"]`、`["Dev_log"]`
`authors`	[string]	可选	多作者（主题支持时显示）
`transparent`	bool	可选	用于 Archive / BasB 等透明背景布局

Section _index.md 示例：

+++
title = "效率-工作流"
sort_by = "date"
template = "article_list.html"
page_template = "article.html"
paginate_by = 10
generate_feeds = true
[extra]
no_header = true
scripts = ["analytic/umami.js"]
+++

4.2 `[taxonomies]` 分类法

本站 zola.toml 启用：

taxonomies = [
  { name = "tags", feed = true, paginate_by = 10 },
  { name = "categories", feed = true },
]

字段	类型	说明
`tags`	[string]	自由标签，如 `["Zola", "CXX"]`
`categories`	[string]	分类；枚举值见下表

categories 可选枚举（zola.toml → [[extra.categories]]）：

值	含义	主题色
`Archived`	归档文	purple
`Featured`	精选	yellow
`Hot`	热门	red

4.3 `[extra]` — 页面 / 专栏扩展（Ametrine + 本站）

继承规则：页面 page.extra.* 优先，否则回退 section.extra.*，再回退 config.extra.*。

布局与展示

字段	类型	枚举 / 格式	作用
`no_header`	bool	`true` / `false`	不渲染正文顶部 `<h1>`
`backlinks`	bool	`true` / `false`	文末显示反向链接（需全局 `show_backlinks`）
`toc`	bool	`true` / `false`	侧栏目录（实际由文内标题 + Zola `page.toc` 生成）
`accent_color`	string 或 [string, string]	见下方强调色枚举	页面主题色 / `theme-color`
`accent_color_dark`	string	HSL 或预设名	仅深色模式强调色（可选）
`banner`	string	文件名	与 `index.md` 同目录的横幅图
`banner_position`	string	CSS 值，如 `center top`	列表缩略图裁剪位置
`banner_pixels`	bool	`true`	横幅像素风渲染

accent_color 枚举与格式（主题文档）：

写法	示例	说明
预设名（双色同用）	`"blue"`	浅色/深色各用主题预设
预设数组	`["red", "blue"]`	浅色 red、深色 blue
单色 HSL	`"hsl(270 50% 60%)"`	两模式同色
HSL 数组	`["hsl(26 25% 34%)", "hsl(27 31% 53%)"]`	浅色 / 深色各一

预设名可选：red · orange · yellow · green · blue · purple

元数据与社交卡片 `[extra.meta]`

字段	类型	说明
`meta.card`	string	自定义 OG 卡片图（相对页面路径）
`meta.favicon`	string	页级 favicon
`meta.apple_touch_icon`	string / bool	页级 Apple 图标

声明块（文章顶部提示）

字段	类型	说明
`archive`	string (markdown)	归档说明条
`trigger`	string (markdown)	内容预警条
`disclaimer`	string (markdown)	免责声明条

资源加载

字段	类型	格式	说明
`styles`	[string]	相对 `static/` 或 sass 输出	额外 CSS，如 `["kanban/style.css"]`
`scripts`	[string]	相对 `static/`	额外 JS；页面级覆盖 section

常用 scripts 值：

值	用途
`analytic/umami.js`	Umami 统计
`js/nanolog.js`	Nanolog 发布 / 编辑
`js/kanban-rules.js`	看板规则引擎
`js/kanban-board.js`	看板明细交互
`js/kanban-list.js`	看板列表
`js/design-apps.js`	Design 应用网格
`encryption/*.js`	由 `base.html` 全站注入，一般无需手写

功能开关

字段	类型	说明
`copy_button`	bool	代码块复制按钮（可覆盖全站 `copy_button`）
`audio_button`	bool	文章朗读按钮

Fediverse 评论 `[extra.fediverse]`

字段	类型	说明
`host`	string	实例域名，如 `vmst.io`
`user`	string	用户名
`id`	string	帖子 ID；三者齐全时加载评论线程

侧栏媒体 `[extra.music]` / `[extra.weather]`

music — 数组，每项：

键	类型	枚举 / 说明
`type`	string	`album` · `track`
`mbid`	string	MusicBrainz ID（可选）
`artist`	string	艺术家名
`name`	string	曲名 / 专辑名

weather — 表：

键	类型	枚举 / 说明
`condition`	string	描述文字
`style`	string	`cloudy` · `showers` · `snowing`
`icon`	string	Phosphor 图标名
`temp`	string	温度数值
`unit`	string	`C`（默认）或 `F`

4.4 `[extra.encryption]` — 本站加密（单篇文章）

字段	类型	说明
`encrypt`	bool	`true` 时构建期加密正文

站点级开关与密钥在 zola.toml → [extra.encryption]，不要写在单篇文章里。

4.5 看板专用 `[extra]`（`content/kanban/*.md`）

字段	类型	说明
`week_start`	string	周一开始 `YYYY-MM-DD`
`week_end`	string	周日结束 `YYYY-MM-DD`
`core_tasks`	string	列表页 / 明细页核心任务一行摘要
`importance`	int	1–5 重要等级（列表五星）
`stats`	table	`{ total, done, todo, doing, progress_pct }` 预计算进度

4.6 Design 页专用 `[extra]`（`content/design/index.md`）

字段	类型	说明
`cli`	array of tables	`{ name, icon, repo, summary }`
`plugins`	array of tables	同上
`apps`	array of tables	`{ name, slug, icon, summary, description }`

子应用页：content/design/apps/<slug>/index.md 使用 template = "design_app.html"。

4.7 首页专用 `[extra]`（`content/_index.md`）

字段	类型	子键	说明
`graphics`	array	`name`, `text`, `url?`	顶部图形徽章
`badges`	array	`name`, `url?`	88×31 风格徽章 GIF
`contacts`	array	`name`, `url`, `favorite?`	联系方式
`socials`	array	同上	社交网络
`forges`	array	同上	代码托管 / 部署链接

4.8 Nanolog 单篇

可为空 front matter：

+++
+++

正文直接写 Markdown；日期由 文件名 YYYY-MM-DDTHH:MM:SSZ.md 决定。

4.9 完整文章示例（含常用字段）

+++
title = "文章标题"
description = "摘要，用于 SEO 与列表"
date = 2026-06-24
updated = 2026-06-24
draft = false
[taxonomies]
tags = ["Zola", "CXX"]
categories = ["Featured"]
[extra]
accent_color = ["hsl(254 44% 55%)", "hsl(290 20% 71%)"]
banner = "cover.webp"
no_header = false
copy_button = true
[extra.encryption]
encrypt = false
[extra.fediverse]
host = "vmst.io"
user = "username"
id = "113295812044964246"
+++

五、`zola.toml` 站点级配置（非单篇 front matter）

访客了解全站行为时可查阅：

段	关键字段	说明
`[extra.analytics]`	`service`	`goatcounter` · `umami` · `plausible`
	`id`	各平台追踪 ID
	`self_hosted_url`	自托管根 URL；Umami Cloud 留空
	`exclude_hash` / `exclude_search` / `do_not_track`	Umami 选项
`[extra.encryption]`	`enabled`, `key`, `algorithm`	全站加密开关（`AES-GCM`）
	`admin_ttl_secs`	管理员特权秒数
	`visitor_refresh_min` / `max`	访客随机解密刷新次数区间
`[extra.csp]`	`directive` + `domains`	CSP 白名单扩展
`[extra.nav]`	`links`	侧栏导航树
`[extra.categories]`	`name`, `color`, `icon`	分类元数据
`[extra]`	`scripts`, `source_url`, `replog_url`	全站脚本与编辑链接

六、Markdown 与 Shortcode（正文内）

正文除标准 Markdown 外，常用扩展包括：

能力	写法
站内链接	`[文字](@/03Share_blog/xxx/index.md)`
GitHub Alerts	`> [!NOTE]` / `WARNING` / `TIP`
图片 URL 样式	`![](pic.png#transparent#pixels#no-hover)`
Shortcode	`{%% youtube(id="…") %%}`、`{%% crt() %%}…{%% end %%}` 等

本站 templates/shortcodes/ 额外提供：badges · polaroid · window · masonry · todo · now_playing · online · games · age · icons · beeper。

七、参考链接

Zola 官方文档
Ametrine 主题
daudix.one 参考站
本站模板速查：@/03Share_blog/2026-06-22-zola-template-markdown-guide/index.md
本站 v1.0 迭代记录：@/nanolog/2026-06-24T04:00:00Z.md

v1.0 正式版：在「毛坯房但够用」的基础上，补齐统计、加密、看板与文档化；后续版本将在此基础上迭代，而不推翻目录结构。

2026-06-23T12:00:00+00:00

2026年06月23日（东八区）

功能调试：Umami 流量统计未生效

概述

站点启用 Ametrine 主题内置的 Umami 统计后，Umami 控制台长期无访客数据。本次排查确认根因为 zola.toml 中 self_hosted_url 误填为博客域名，导致追踪脚本指向不存在的 /script.js，且 CSP 未放行 Umami Cloud 域名。修复后仅改动站点根目录 zola.toml，未修改 themes/。

1. Umami 在源代码中的设计逻辑与调用链

Ametrine 主题（参考 daudix.one）将统计能力拆为 配置 → CSP 白名单 → 脚本注入 三层，全部在 themes/ametrine/templates/partials/ 中实现。

1.1 配置入口：`zola.toml`

[extra.analytics]
service = "umami"                                          # 统计服务：goatcounter | umami | plausible
id = "cdf54193-b449-4454-884b-029e82434c32"                # Umami Cloud 的 website ID
# self_hosted_url = "https://stats.example.com"            # 仅自托管 Umami 时填写
exclude_hash = true                                        # 可选：不采集 URL hash
# exclude_search = false                                   # 可选：不采集 URL 查询参数
# do_not_track = false                                     # 可选：尊重浏览器 DNT

字段	作用
`service`	选择统计后端，决定加载哪段 partial
`id`	Umami 的 `data-website-id`
`self_hosted_url`	自托管实例根 URL；留空则走 Umami Cloud（`cloud.umami.is`）
`exclude_hash` / `exclude_search` / `do_not_track`	映射为 `<script>` 上的 `data-*` 属性

主题默认示例见 themes/ametrine/config.toml 的 [extra.analytics] 段（daudix 使用自托管 https://stats.daudix.one）。

1.2 CSP 白名单：`partials/csp.html`

页面 <head> 内生成 Content-Security-Policy，决定是否允许加载外部脚本与上报数据：

config.extra.csp（zola.toml 自定义域）
        ↓
csp.html 合并 analytics 域
        ↓
<meta http-equiv="Content-Security-Policy" …>

Umami 相关逻辑（themes/ametrine/templates/partials/csp.html）：

条件	`script-src` 追加	`connect-src` 追加
设置了 `self_hosted_url`	该 URL	该 URL
未设置 + `service == "umami"`	`cloud.umami.is`	`*.umami.dev cloud.umami.is`

若误填 self_hosted_url 为博客地址，CSP 不会自动加入 cloud.umami.is，脚本即使写对也会被策略拦截。

1.3 脚本注入：`partials/head.html` → `partials/analytics.html`

触发条件（themes/ametrine/templates/partials/head.html）：


{%- if config.mode != "serve" and config.extra.analytics.service -%}
  {%- include "partials/analytics.html" -%}
{%- endif -%}

要点：

zola serve 开发模式不注入 — 本地热重载页面无统计脚本，属预期行为。
zola build 产物才包含 — 部署到 GitHub Pages 后访客才会被追踪。

Umami 脚本生成（themes/ametrine/templates/partials/analytics.html）：

条件	输出
`self_hosted_url` 有值	`<script … src="{{ self_hosted_url }}/script.js" data-website-id="{{ id }}">`
`self_hosted_url` 为空	`<script … src="https://cloud.umami.is/script.js" data-website-id="{{ id }}">`

等价于官方嵌入代码：

<script defer src="https://cloud.umami.is/script.js"
  data-website-id="cdf54193-b449-4454-884b-029e82434c32"></script>

1.4 完整调用链（生产环境）

zola build
  → head.html 读取 config.extra.analytics
  → csp.html 写入 script-src / connect-src 白名单
  → analytics.html 输出 <script defer src="cloud.umami.is/script.js">
  → 浏览器加载 script.js
  → script.js 向 *.umami.dev / cloud.umami.is 上报 pageview
  → Umami 控制台展示数据

2. 本次错误原因与修复方案

2.1 现象

检查项	修复前（线上）
页面 `<script>`	`src="https://suchaharcan.github.io/script.js"`
脚本 HTTP 状态	404（GitHub Pages 无此文件）
CSP `script-src`	`'self' https://suchaharcan.github.io …`（无 `cloud.umami.is`）
CSP `connect-src`	无 `*.umami.dev`
Umami 控制台	无访客记录

2.2 根因

复制 daudix.one 配置时，将 self_hosted_url 设成了博客域名 https://suchaharcan.github.io。

daudix 的 self_hosted_url = "https://stats.daudix.one" 指向独立的 Umami 自托管实例；本站点使用的是 Umami Cloud，不应填写 self_hosted_url。

连锁影响：

脚本 URL 错误 — 主题从 博客域名/script.js 加载，文件不存在。
CSP 错误 — 白名单指向博客域名，未放行 cloud.umami.is 与 *.umami.dev。
即使手动改 script 地址，上报请求仍会被 CSP 拦截。

2.3 修复

文件：zola.toml（仅此一处，未改 themes/）

 [extra.analytics]
 service = "umami"
 id = "cdf54193-b449-4454-884b-029e82434c32"
-self_hosted_url = "https://suchaharcan.github.io"
 exclude_hash = true

修复后 zola build 产物对比：

检查项	修复后
脚本	`src="https://cloud.umami.is/script.js"` → 200
CSP	`script-src … cloud.umami.is`；`connect-src … *.umami.dev cloud.umami.is`
website ID	`cdf54193-b449-4454-884b-029e82434c32` ✓

部署提醒：本地 build 已正确，需 push 触发 GitHub Pages 重建后线上才生效。

3. 验证方式与使用注意点

3.1 部署后验证（推荐）

浏览器 Network
- 打开 https://suchaharcan.github.io/
- DevTools → Network，筛选 script.js
- 确认来源为 cloud.umami.is，状态 200
查看页面源码
- 搜索 data-website-id，应出现 cdf54193-b449-4454-884b-029e82434c32
- 搜索 Content-Security-Policy，应含 cloud.umami.is
Umami 控制台
- 登录 Analytics 面板
- 刷新博客首页，Realtime / 今日访客应在数秒内更新

命令行快速检查（可选）

curl -sL "https://suchaharcan.github.io/" | grep -o 'cloud.umami.is/script.js'
# 应输出：cloud.umami.is/script.js

curl -sI "https://cloud.umami.is/script.js" | head -1
# 应输出：HTTP/2 200

3.2 使用注意点

场景	说明
`zola serve` 本地开发	不注入 analytics，Network 中看不到 Umami 脚本 — 正常
Umami Cloud vs 自托管	Cloud 用户不要填 `self_hosted_url`；自托管才填实例根 URL（如 `https://stats.example.com`）
CSP 自定义域	`zola.toml` 的 `[extra.csp]` 与主题自动合并；Umami Cloud 域由主题在 `self_hosted_url` 为空时自动追加
参考 daudix.one	可借鉴导航、CSP 结构等；`self_hosted_url` 不能直接照搬（daudix 为自托管）
不修改 themes/	统计逻辑已在主题内；站点级只需正确配置 `zola.toml` 并 build 部署
隐私 / 分享	数据分享页：https://cloud.umami.is/share/2hWVbYvlPUkk98Yz
AdBlock / 隐私扩展	访客若安装拦截器，可能不上报 — 控制台数据为「可统计访客」子集

3.3 配置对照速查

部署方式	`service`	`id`	`self_hosted_url`
Umami Cloud（本站）	`umami`	Cloud 控制台 website ID	留空
自托管 Umami	`umami`	实例中的 website ID	`https://你的-umami-域名`
GoatCounter / Plausible	对应 service 名	各服务文档	自托管时填实例 URL

修改文件

文件	变更
`zola.toml`	删除错误的 `self_hosted_url = "https://suchaharcan.github.io"`

Mac Chrome ReOpen

2026-06-23T00:00:00+00:00

问题描述：

Chrome 用 Command+Q 强制关闭程序后，程序在 Dock 栏自己弹了弹又重新弹起来了。

每次都要强制关闭两次以上才能真正把 Chrome 关掉。

Mac 本身的日志功能要多使用，有时能够反应出一定的问题

查看系统的终端报错日志（揪出幕后黑手）

log stream --predicate 'eventMessage CONTAINS[c] "launch"' | grep -i "Chrome"

运行后，终端会进入监听状态。此时你去对 Chrome 执行 Command + Q。 * 观察 Chrome 自动弹起的那一瞬间，终端里跳出来的日志。

2026-06-23 09:21:30.454905+0800 ... loginwindow: [com.apple.loginwindow.logging:TAL] -[PersistentAppsSupport appShouldBeRelaunched:] | entered. checking app: Google Chrome
2026-06-23 09:21:30.454921+0800 ... loginwindow: [com.apple.loginwindow.logging:TAL] -[PersistentAppsSupport saveLogoutPersistentState:finalSnapshot:] |            Adding to relaunchArray: Google Chrome

解释： loginwindow 是 macOS 的登录窗口及会话管理进程。这里的 TAL (Transparent App Lifecycle) 和 PersistentAppsSupport 是 macOS 的“窗口恢复/持久化应用”机制。

翻译成白话： 在 09:21:30 时，macOS 的系统级进程 loginwindow 介入，检测了 Chrome 的状态。它认为 Chrome “应该被重新拉起（appShouldBeRelaunched）”，并直接把它塞进了重启队列（Adding to relaunchArray）里。

随后在 09:21:34 左右，系统底层的 duetexpertd（苹果的智能预测/行为建议服务）和 runningboardd 协同，再次把 Chrome 给捞了起来。

日志时间线（08:41:01）时间事件含义 .637 checkAgainstApp: Google Chrome TAL 开始评估 Chrome 是否该被恢复 .638 appShouldBeRelaunched → Adding to relaunchArray 系统判定：Chrome 退出后应被重新拉起 .827 自动填充 (Google Chrome) state 3→4, quit Chrome 密码自动填充助手先退出 .855 appDeath for com.google.Chrome Chrome 主进程死亡 .855–.848 Google Chrome state 3→4, quit 主程序走完退出流程 .850（+6s） previouslyRunningApps 仍含 Chrome TAL 快照里 Chrome 未被清除关键：relaunchArray 写入发生在 Chrome 真正退出之前（.638 vs .855）。说明 macOS 在退出流程早期就决定了要恢复 Chrome，不是事后误判。

两个直接原因

TAL 持久列表里已有 Chrome 你的 ~/Library/Preferences/ByHost/com.apple.loginwindow.*.plist 中：

BundleID = “com.google.chrome” BackgroundState = 3 Path = “/Applications/Google Chrome.app” BackgroundState = 2：前台运行、有窗口 → 应恢复 BackgroundState = 3：后台/hidden 状态 → 仍会被记录

每次 CMD+Q，loginwindow 都会重新评估并再次写入 relaunchArray。

NSQuitAlwaysKeepsWindows 未设置 defaults read com.google.Chrome NSQuitAlwaysKeepsWindows

→ key not found

未设置时，macOS 默认行为是退出时保留窗口状态（Resume）。有窗口的 Chrome 退出 → appShouldBeRelaunched 返回 YES → 进 relaunchArray。

exit_type: Normal 已修复，但 TAL 仍会因「有窗口 + 保留状态」而恢复。

自动填充 (Google Chrome) 是什么？这是 Chrome 的密码自动填充系统组件，在 loginwindow 里被当作独立 Application 跟踪。退出时它先于主进程退出，可能让 TAL 认为 Chrome 生态尚未完全结束，加剧恢复判定。

针对这份日志的修复（按顺序）第一步：强制 Chrome 退出时不保留窗口 Chrome 必须正在运行时执行：

defaults write com.google.Chrome NSQuitAlwaysKeepsWindows -bool false 然后按住 Option 再按 CMD+Q（或菜单：Chrome → 退出时按住 Option 变为「退出并保留窗口关闭」）。

第二步：从 TAL 持久列表移除 Chrome killall “Google Chrome” 2>/dev/null python3 << ‘PY’ import plistlib, os, subprocess, re uuid = re.search(r’“IOPlatformUUID” = “([^”]+)“’, subprocess.check_output([“ioreg”,“-rd1”,“-c”,“IOPlatformExpertDevice”], text=True)).group(1) path = os.path.expanduser(f“~/Library/Preferences/ByHost/com.apple.loginwindow.{uuid}.plist“) with open(path, “rb”) as f: d = plistlib.load(f) before = len(d.get(“TALAppsToRelaunchAtLogin”, [])) d[“TALAppsToRelaunchAtLogin”] = [ a for a in d.get(“TALAppsToRelaunchAtLogin”, []) if “chrome” not in a.get(“BundleID”, “”).lower() ] with open(path, “wb”) as f: plistlib.dump(d, f) print(f“Removed Chrome from TAL: {before} -> {len(d[‘TALAppsToRelaunchAtLogin’])} apps“) PY 第三步：关闭 Chrome 密码自动填充系统扩展系统设置 → 密码 → 密码选项 → 自动填充取消勾选 Google Chrome（或 Chrome 相关自动填充项）。

这会让自动填充 (Google Chrome) 不再作为独立进程被 loginwindow 跟踪。

第四步：验证 log stream –predicate ‘process == “loginwindow” AND eventMessage CONTAINS[c] “Chrome”’ –style compact CMD+Q 后，不应再出现 Adding to relaunchArray: Google Chrome。

与之前分析的关系项目当前状态 Yandex Mail.app 已删除 ✓ exit_type 已是 Normal ✓ 系统后台项已关闭 ✓ TAL 持久列表仍有 Chrome ← 当前主因 NSQuitAlwaysKeepsWindows 未设置 ← 触发 appShouldBeRelaunched 自动填充助手日志中可见，建议关闭这份日志说明：不是 Chrome 崩溃重启，而是 macOS TAL 正常的窗口恢复机制在 CMD+Q 时主动标记 Chrome 为「应 relaunch」。根因是 TAL 列表 + 退出时保留窗口，而非后台项或 flags。

macOS 排查常用 CLI 速查

排查 Chrome 自动拉起时用到的主要是 sfltool、log、pgrep。下面按工具整理常见用法。

sfltool — 后台项 / 登录项注意：不是 stltool，正确命令是 sfltool（Shared File List tool）。主要用于查看 Login Items 和 Allow in the Background（后台允许）注册信息。

基本命令

查看帮助 sfltool
最常用：导出所有 Background Task Management (BTM) 条目 sfltool dumpbtm
筛选 Chrome / Google 相关 sfltool dumpbtm | grep -i -A12 "Google Chrome"
只看后台任务类型 sfltool dumpbtm | grep -i -B2 -A8 "background tasks"
其他子命令（较少用）

sfltool list          # 列出 shared file list
sfltool list-info     # 详细信息
sfltool csinfo        # codesign 信息
sfltool resetbtm      # ⚠️ 重置全部 BTM，慎用

典型排查场景

确认 Chrome 是否在系统后台项中注册
sfltool dumpbtm 2>/dev/null | grep -i -E 'chrome|google'
对比：传统登录项（osascript 方式）
osascript -e 'tell application "System Events" to get the name of every login item'

log — 统一日志系统（Unified Logging） macOS 10.12+ 的日志不再散落在文本文件里，主要靠 log stream（实时）和 log show（历史）。

实时监听 — log stream
 基础：监听 loginwindow 所有日志
log stream --predicate 'process == "loginwindow"' --style compact
排查 Chrome 被 TAL 拉起（我们用的）
log stream --predicate 'process == "loginwindow" AND eventMessage CONTAINS[c] "Chrome"' --style compact
更宽：任何含 launch 的日志，再 grep Chrome
log stream --predicate 'eventMessage CONTAINS[c] "launch"' | grep -i "Chrome"
监听 TAL 子系统
log stream --predicate 'subsystem == "com.apple.loginwindow.logging"' --style compact
多进程联合监听
log stream --predicate 'process == "loginwindow" OR process == "runningboardd" OR process == "duetexpertd"' \
  --style compact | grep -i chrome
历史查询 — log show
最近 2 小时 loginwindow 里含 Chrome 的日志
log show --last 2h \
  --predicate 'process == "loginwindow" AND eventMessage CONTAINS[c] "Chrome"' \
  --style compact
最近 7 天：quit / relaunch / unexpectedly 相关
log show --last 7d \
  --predicate 'eventMessage CONTAINS "Google Chrome" AND (eventMessage CONTAINS "quit" OR eventMessage CONTAINS "relaunch" OR eventMessage CONTAINS "unexpectedly")' \
  --style compact
只看错误级别
log show --last 1h --predicate 'process == "loginwindow"' --level error --style compact

–predicate 语法要点写法说明 process == “loginwindow” 精确匹配进程名 eventMessage CONTAINS[c] “Chrome” 消息含 Chrome，[c] = 忽略大小写 subsystem == “com.apple.talagent” 按子系统过滤 messageType == error 只看 error AND / OR 组合条件实用技巧输出到文件，避免刷屏 log stream –predicate ‘process == “loginwindow” AND eventMessage CONTAINS[c] “Chrome”’
–style compact > ~/Desktop/chrome-quit.log

时间范围（历史）

log show –start “2026-06-25 08:40:00” –end “2026-06-25 08:42:00”
–predicate ‘process == “loginwindow”’ –style compact 我们抓到的关键日志模式 appShouldBeRelaunched: Google Chrome Adding to relaunchArray: Google Chrome applicationQuit: for app:Google Chrome appDeath for com.google.Chrome previouslyRunningApps: ( … com.google.chrome … ) 3. pgrep — 按名称查进程比 ps aux | grep 更干净（不会 grep 到自己）。

基本用法

# 进程是否存在（静默，适合脚本判断）
pgrep -x "Google Chrome" && echo "Chrome 在运行"
# 列出 PID + 完整命令行（排查最有用）
pgrep -lf "Google Chrome"
# 不区分大小写
pgrep -lf -i 'chrome|google chrome'
# 只输出 PID
pgrep "Google Chrome"
常见组合
# CMD+Q 后确认是否还有残留
pgrep -lf "Google Chrome" || echo "已完全退出"
# 看 Chrome 各 Helper 进程
pgrep -lf "Chrome Helper"
# 统计 Chrome 相关进程数
pgrep -lf -i chrome | wc -l
# 配合 killall 做彻底退出
killall "Google Chrome" 2>/dev/null
sleep 1
pgrep -lf "Google Chrome"   # 应无输出

pgrep 常用选项选项含义 -l 显示进程名 -f 匹配完整命令行（而不只是进程名） -i 忽略大小写 -x 精确匹配进程名 -u $USER 只查当前用户的进程 4. 配套命令（同一套排查里常用） TAL 持久恢复列表

# 读取「注销/重启时重新打开的应用」列表
UUID=$(ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}')
defaults -currentHost read com.apple.loginwindow TALAppsToRelaunchAtLogin
# 或直接看 plist
plutil -p ~/Library/Preferences/ByHost/com.apple.loginwindow.${UUID}.plist | grep -A5 chrome
launchctl — 启动项 / 服务
# 当前用户已加载的服务，筛 Chrome/Google
launchctl list | grep -i -E 'chrome|google'
# 查看 LaunchAgent 内容
plutil -p ~/Library/LaunchAgents/com.google.GoogleUpdater.wake.plist
defaults — 应用偏好
# Chrome 是否保留退出时的窗口
defaults read com.google.Chrome NSQuitAlwaysKeepsWindows
# 强制关闭保留窗口（Chrome 运行中执行）
defaults write com.google.Chrome NSQuitAlwaysKeepsWindows -bool false
# 全局：退出时是否关闭窗口
defaults read NSGlobalDomain NSQuitAlwaysKeepsWindows
pluginkit — 系统扩展 / 自动填充
# 查看 Chrome 相关系统插件（如自动填充）
pluginkit -m -A -v | grep -i -E 'chrome|google|autofill'
5. 一套完整排查流程（可复制）
# === 1. 静态状态 ===
sfltool dumpbtm | grep -i -A10 "Google Chrome"
defaults -currentHost read com.apple.loginwindow TALAppsToRelaunchAtLogin | grep -i chrome
pgrep -lf "Google Chrome"
# === 2. 开终端 A：实时日志 ===
log stream --predicate 'process == "loginwindow" AND eventMessage CONTAINS[c] "Chrome"' --style compact
# === 3. 对 Chrome 执行 CMD+Q ===
# === 4. 终端 B：确认进程 ===
pgrep -lf "Google Chrome" || echo "OK: 无残留"
# === 5. 历史补查 ===
log show --last 5m --predicate 'process == "loginwindow" AND eventMessage CONTAINS[c] "relaunch"' --style compact

常见坑问题说明 log stream 刷屏必须加 –predicate，否则 I/O 日志量极大 log show 很慢务必加 –last 1h 或 –start/–end 限定范围 pgrep 匹配过宽 -i chrome 会匹配到 Cursor 的 chrome_crashpad_handler，必要时加 |Google Chrome 精确匹配 sfltool 与系统设置不一致 UI 显示 Google Chrome.app，dumpbtm 可能还有独立的 background tasks 条目 defaults read 报 key not found 不等于 false，可能意味着「未设置、走系统默认」

系统日志很好用

需求 1：macOS 系统日志功能（Unified Logging）使用要点整理 macOS 自 10.12 引进统一日志系统 (Unified Logging System) 后，日志不再零散存储于各个文本文件中，而是由 diagnosticd 统一收集并二进制压缩存储。

核心命令工具：log 实时流监控 (log stream)：

要点：它类似于传统 Linux 的 tail -f，但必须配合 –predicate（谓词过滤器）使用，否则海量的系统级 I/O 日志会瞬间刷屏，导致终端卡死。

历史日志检索 (log show)：

要点：用于查看过去发生的事情。必须限定时间范围，否则检索极其缓慢。

示例：查看过去 10 分钟内关于 Chrome 的报错：

log show --last 10m --predicate 'eventMessage CONTAINS[c] "Chrome"' --level error

谓词过滤 (–predicate) 的高级语法谓词基于 Apple 的 NSPredicate 架构，大小写敏感（除非加 [c] 表示忽略大小写）：

process == “loginwindow”：精准匹配进程名。

processImageUUID CONTAINS[c] “Chrome”：匹配进程路径或动态库中包含 Chrome 的行为（对抓取 Helper 应用极有效）。

messageType == error 或 messageType == fault：只看错误或严重故障（fault）。

日志等级的隐蔽陷阱 macOS 日志分为五个等级：Default、Info、Debug、Error、Fault。

痛点：出于性能和隐私考虑，Info 和 Debug 等级的日志默认是不写入磁盘，也不在实时流中展示的。

解决办法：如果你在调自建脚本（如你的自定义自动化脚本）发现看不到详细日志，需要手动为该进程开启 Debug 级写入：

sudo log config --mode "level:debug" --subsystem com.your.app

需求 2：开源 macOS (Darwin xnu) 代码架构与设计思路你拉取的仓库实际上是 Darwin（macOS 的开源核心），其内核名为 XNU（X is Not Unix）。XNU 是一个独特的混合内核 (Hybrid Kernel)，它融合了 Mach 的灵活性和 BSD 的成熟稳定性。

核心代码架构（目录结构解密）在官方开源的 xnu 仓库中，核心架构主要由以下四大板块交织而成：

xnu/
├── mach/               # Mach 微内核层（核心调度与 IPC）
│   ├── kern/           # 线程调度、时钟、任务管理
│   └── vm/             # 虚拟内存管理 (VM Object, Pager)
├── bsd/                # BSD 层（提供 POSIX 标准与上层抽象）
│   ├── kern/           # 进程管理 (PID)、credentials、sysent
│   ├── vfs/            # 虚拟文件系统切换 (Virtual File System)
│   └── netinet/        # TCP/IP 网络协议栈
├── iokit/              # I/O Kit（C++ 驱动框架，负责硬件交互）
│   └── Drivers/        # 磁盘、网络、USB 等基础驱动抽象
├── libkern/            # 内核基础库（C++ 运行时支持、容器类）
└── pexpert/            # 平台专家层（处理不同硬件架构如 ARM64/Intel 的引导初始化）

核心设计思路 ⚙️ 思路一：微内核与宏内核的“双管齐下”（混合内核） Mach（微内核）：只负责最底层、最极致的单一任务——进程间通信 (IPC/Mach Ports)、进程隔离、底层线程调度。Mach 认为万物皆为 “Port”（端口）。

BSD（宏内核）：由于微内核频繁进行上下文切换（Context Switch）会导致性能低下，苹果在内核空间里直接嵌套了一个改版的 BSD。BSD 把 Mach 的底层概念包装成 POSIX 标准。

逻辑关系：系统调用进来，上层看到的是 BSD 的 PID（进程 ID），但 BSD 底层其实映射的是 Mach 的 Task。

🔒 思路二：严格的权限与资源断言机制（RunningBoard 的由来）为什么你会在前面的日志里频繁看到 runningboardd、ttl 和 assertion（断言）？

在 XNU 的设计进化中（特别是引入 iOS 和 Apple Silicon 移动架构后），内核极其看重功耗与生命周期管理。

XNU 引入了 Assertion（资源断言）机制。一个应用（如 Chrome）在前台时，runningboardd 会向内核申请一个 frontmost 强断言，内核据此分配高优先级 CPU 和能效核心（E-cores/P-cores）。当应用转入后台或准备退出时，断言被 Invalidating（作废），内核会瞬间限制或冻结其 Helper 进程，这也是导致多页面 Chrome 回收假死而被系统强制拉起的底层诱因。

💻 思路三：面向对象的驱动安全（I/O Kit & DriverKit）传统的 Unix 驱动是用 C 语言写的，一死全死。XNU 独辟蹊径，在内核中实现了一个受限的 C++ 运行时 (libkern)。

设计目的：利用 C++ 的面向对象特性（如依托 OSMetaClass 管理生命周期），让驱动程序对象化。如今苹果正逐步将 I/O Kit 迁移到用户空间（DriverKit），让绝大多数驱动在内核外运行，即使崩溃也不会导致 Mac 蓝屏/紫屏。

通过结合这两点，你会发现：你用 log stream 抓到的每一行状态，其实都是 XNU 内核中 Mach Task、BSD 进程状态以及 RunningBoard 断言在系统层面的具象化表现。

2026-06-22T12:00:00+00:00

2026年06月22日（东八区）

大版本更新：周计划看板 v1.0 + Design 页

概述

本次为站点 Out - Projects 区的一次大功能迭代：上线 周计划看板（列表 + 明细 + 规则引擎 + 加权进度），并同步完成 Design 应用网格 样式对齐。数据与 content/ 同级存放在 kanban/，未修改 themes/。

更新明细

1. 周计划看板 · 架构

层级	路径 / 文件
数据源	`kanban/<周一日期>.md`
Zola 分区	`content/kanban/`（symlink 指向数据源）
静态读取	`static/kanban/` → 前端 fetch 原始 MD
规则引擎	`static/js/kanban-rules.js`
明细 UI	`static/js/kanban-board.js` + `templates/kanban.html`
列表 UI	`static/js/kanban-list.js` + `templates/kanban_list.html`
样式	`sass/kanban/style.scss`
映射文档	`kanban/kanban-mapping.md`
Edit 缓冲	`kanban/_edit-buffer.md`

入口：侧边栏 → Out - Projects → 周计划 → /kanban/

2. 列表页（图一）

标题显示 core_tasks（如「看板规则引擎 · Trello 明细页…」），不显示日期区间
元信息一行（article 图标风格）：开始 · 截止 · 剩余天数 · 进度% · 重要等级（5 星）
剩余天数 = 截止日 − 基准日（东八区；早于 week_start 时以开始日为基准）
统计行：共 N 项 / 已完成 / 待办 / 进行中
背景色：待办 > 3 → 全红；全完成 → 浅绿；其余 → 按加权进度渐变

3. 明细页（图二 · Trello 五列）

列	参与进度	说明
待办 / 进行中 / 已完成	✅	可拖拽（解锁后）
资源	❌	淡绿托盘，列出所需资源
目标	❌	`@goal complete` 淡蓝 / `@goal risk` 灰爆样式

页头仅显示 本周核心（core_tasks），无重复日期标题
卡片：顶栏色（@top）+ 标签条（@labels）+ checklist + 描述；不显示开始/截止/星级（这些只在列表页）
列头深色块：待办蓝 / 进行中橙 / 已完成绿 / 资源绿 / 目标灰

4. 锁定 / 解锁 / 保存

状态	行为
锁定（默认）	不可拖拽；隐藏 ReDeplog / Edit Post / 映射说明
解锁	仅在 `week_start`～`week_end`（东八区）内可切换；可拖拽跨列（本地预览）
Edit Post	点击前按规则引擎序列化 → 写入 buffer → 复制剪贴板 /（可选 Token）API 覆盖 `kanban/<周>.md`
超期	超过 `week_end` 永久只读

5. 加权进度公式

以 50% 为基准，仅统计前三列：

列	单项贡献
待办	−10% × n
进行中	+5% × n
已完成	+15% × n

n = 该卡片 @labels 数量（无标签时 n = 1）。结果 clamp 至 0–100%，写入 stats.progress_pct。

示例（6.16–6.22 周）：待办 4 / 进行中 2 / 已完成 2 → 45%；待办 > 3 → 列表背景红色。

6. Design 页（同期）

/design/ 应用网格对齐 ensili.co More apps 布局
文件：templates/design.html、sass/design/style.scss、static/js/design-apps.js

7. 其他

zola.toml 导航增加 周计划
示例看板：kanban/2026-06-16.md
完整映射：kanban/kanban-mapping.md

看板简易映射规则

# 列名          → 看板一列（待办 / 进行中 / 已完成 / 资源 / 目标）
## 卡片标题     → 一张卡片

@start 2026-06-16    开始（数据用，列表页展示）
@due 2026-06-22      截止
@priority 4          重要等级 1–5（列表页星级）
@top orange          明细页顶部粗色条
@labels red, blue    明细页顶部细色条 + 进度权重 n
@bg #FFF8E1          卡片背景色
@goal complete       目标看板 · 完成效果（淡蓝）
@goal risk           目标看板 · 未完成后果（灰爆）
- [ ] / - [x]        checklist 勾选框

Front Matter 要点：

[extra]
week_start = "2026-06-16"
week_end = "2026-06-22"
core_tasks = "本周核心任务一句话"
importance = 4
stats = { total = 8, done = 2, todo = 4, doing = 2, progress_pct = 45 }

下次更新计划

测试解锁后编辑功能
- 解锁 → 拖拽跨列 / 勾选 checklist → 点击 Edit Post
- 验证序列化往返、kanban/_edit-buffer.md 缓冲、Codeberg 粘贴 / Token 同步
- 确认 ReDeplog 部署后列表进度与明细一致
针对特定设备显示解锁功能
- 评估移动端 / 平板是否展示「解锁 · 可拖拽」（触摸拖拽与桌面差异）
- 可按 viewport 或 UA 限制：小屏只读、桌面可编辑；或提供显式「桌面模式」提示

相关链接：映射说明 · 示例看板 · 周计划列表

2026-06-22T02:00:00+00:00

2026年06月22日（东八区）

功能更新：周计划看板（Kanban 瀑布流）

概述

新增 周计划 模块：列表 + 明细双模板，数据存放在仓库根目录 kanban/（与 content/ 同级），一份 Markdown 对应一个自然周。

核心能力

Markdown 规则引擎（static/js/kanban-rules.js）
- # 一级标题 → 看板列
- ## 二级标题 → 卡片
- @due · @labels · @bg · @top · - [ ] 与看板元素映射
- 同步时按当前 UI 状态 序列化回写 Markdown
明细页 Trello 风格（templates/kanban.html）
- 多列布局、标签条、顶栏色、截止日期、checklist
- 锁定 / 解锁：仅在 week_start～week_end（东八区）内可编辑
- 解锁后可 拖拽卡片跨列；同步按钮写回 kanban/<周>.md
- Edit Post / ReDeplog 链接对齐 Nanolog 工作流
列表页进度视觉（templates/kanban_list.html）
- 展示本周起止、核心任务、完成统计
- 全完成 → 浅绿；完成 < 3 → 全红；其余 → 进度渐变

文档与示例

映射说明：kanban/kanban-mapping.md
示例看板：kanban/2026-06-16.md（6.16 – 6.22）

入口

侧边栏 Site Dev Log → 周计划 → /kanban/

谮言 · 简单的总结

2026-06-22T00:00:00+00:00

人不能活在别人的评价里

沉默成本不参与重大决策

Mac Asesome Software Tool

2026-06-22T00:00:00+00:00

Net

VPN - Quantumult X

尝试过并排除的方案: 小火箭，Surge , Loon;

防火墙 - Little Snitch

优点：非VPN情况下，网络设备终端直接屏蔽路由器为网络终端，屏蔽等级比设备防火墙高；

RSS

NetNewWire

TWM

Yabai

最新支持系统版本 Mac26;

常见详细排查命令

2026-06-22T00:00:00+00:00

SSH

ssh 排查问题

ssh -vvvT git@codeberg.org

CMake

cmake 构建明细排查

cmake --verbose

Zola

zola 博客搭建

zola check  #  Try to build the project without rendering it. Checks links

6.22 – 6.23 验证计划

2026-06-22T00:00:00+00:00

待办

高等数学第一章

@start 2026-06-22 @due 2026-06-23 @priority 4 @labels red, orange @top red

极限与连续
导数基础习题

第一章精读，配合习题巩固。

CMake 文档阅读

@due 2026-06-23 @priority 3 @labels blue

install / target 章节
与 Zola 构建脚本对照

通读官方文档，记录与当前项目相关的要点。

进行中

网站版本 1.0 发布

@start 2026-06-22 @due 2026-06-23 @priority 5 @labels green, yellow, purple @bg #E8F5E9 @top green

架构文档
部署流水线确认
发布公告

汇总加解密、统计、热力图等模块，准备对外发布。

C++20 预研

@start 2026-06-22 @due 2026-06-23 @priority 3 @labels sky, pink

concepts 语法速览
ranges 与现有代码对照

为后续工程化改造做技术储备。

已完成

加解密模块

@priority 4 @labels green

构建时加密 content
访客幸运解密与管理端解锁

网站流量统计模块

@priority 3 @labels sky, blue

Umami Cloud 接入
CSP connect-src 放行

热力图模块

@priority 4 @labels orange, blue

年度按周 · 部分填充
月份按天视图

管理员模式隐藏按钮

@priority 3 @labels pink

六连击侧边栏标题
Edit Post 按钮门控

本周家务

@priority 2 @labels lime

整理桌面与备份

看板功能开发

@priority 5 @labels yellow, purple

规则引擎映射
Trello 明细页与列表进度条

2026-06-21T19:30:00+00:00

2026年06月21日（东八区）

功能调试：Edit Post 提交后看板明细空白

背景

按 v1.0 发布说明「下次更新计划」第 1 项，测试 解锁 → 拖拽 → Edit Post → Codeberg 粘贴提交 → ReDeplog 重建 全流程。

触发变更：Codeberg commit c02b75a（更新 kanban/2026-06-16.md）。

现象

页面	提交前	提交后
列表页 `/kanban/`	正常：stats、进度条、星级	正常：待办 3 / 进行中 3 / 进度 60% 已更新
明细页 `/kanban/2026-06-16/`	五列 + 卡片 + 拖拽	空白：仅标题与「已锁定」，无列无卡片

初看像「映射规则解析失败」，因为明细区完全无 DOM 输出。

问题定位

排除解析层
用 kanban-rules.js 对提交后的 kanban/2026-06-16.md 做 parseMarkdown：仍得到 5 列、12 张卡片，映射规则本身无异常。
对比 commit diff
用户粘贴的 Markdown 在 front matter 中删掉了：
```
styles = ["kanban/style.css"]
scripts = ["js/kanban-rules.js", "js/kanban-board.js"]
```
根因是 serializeMarkdown() 序列化时不会写回这两项，Edit Post 往返必然丢失。
脚本加载链
明细页看板 100% 客户端渲染：kanban-board.js fetch /kanban/<slug>.md → parseMarkdown → 写 DOM。
脚本来源（themes/ametrine 的 head.html）：
- 有 page.extra.scripts → 用页面级
- 否则 → 回退 section.extra.scripts
配置实际加载

页面 FM 含 scripts kanban-rules.js + kanban-board.js ✓

页面 FM 无 scripts section 仅 kanban-rules.js + kanban-list.js ✗ 缺 board.js

列表页只需 kanban-list.js，故列表正常；明细页缺 kanban-board.js，故空白。

解决思路

原则：明细页核心脚本不应依赖 front matter 是否被 Edit Post 保留。

templates/kanban.html
模板内固定注入 kanban-rules.js + kanban-board.js（与已有 inline kanban/style.css 一致），脱离 page.extra.scripts。
static/js/kanban-board.js
解析结果 columns 为空时，在 #kanban-status 输出明确错误，便于与「脚本未加载」区分。
正反映射
parseMarkdown → serializeMarkdown → parseMarkdown 往返：列/卡片/stats 保持一致；FM 的 styles/scripts 非看板数据，不写入序列化输出，避免与模板重复加载。

修改文件

文件	变更
`templates/kanban.html`	文末 `<script defer>` 加载 rules + board
`static/js/kanban-board.js`	空解析结果时 status 报错

验证

Node 往返：5 列 → 5 列，12 卡 → 12 卡
zola build --force 通过；产物 /kanban/2026-06-16/ 含 kanban-board.js
部署后：即使 FM 无 scripts（与远程 commit 一致），明细页也应正常渲染

经验

列表与明细共用 section，但脚本需求不同 → 明细模板应自包含，不能假设 page FM 永远完整。
Edit Post 是数据回写路径 → 序列化只负责看板 Markdown 本体；运行时依赖放模板/静态层更稳。
排查时先区分「没加载 JS」与「JS 加载但解析失败」：前者 DOM 容器空、无报错；后者可在 status / console 看到线索。

相关链接：映射说明 · 示例看板 · 问题 commit

2026-06-21T08:30:00+00:00

2026年06月21日

功能更新：文章发布热力图 (Contribution Heatmap)

概述

新增基于全站文章数据的 GitHub 风格热力图组件，支持在文章页与归档页以不同尺寸和配色展示写作活跃度。

核心能力

双模式展示
- 文章页 (article)：右侧 sticky 固定，仅显示上个月 + 本月；深紫背景、淡紫渐变格点，参考 GitHub 紧凑尺寸。
- 归档页 (archive)：插入于 Total: N posts 与分隔线之间，展示当年完整热力图；GitHub 标准绿色配色。
交互
- 悬浮：显示当天标签数最多的文章标题（同天多篇时按 tags 数量降序取首篇）。
- 点击：跳转至对应文章。
模块化文件
- templates/partials/heatmap_component.html — 聚合各板块文章数据并渲染容器
- static/css/heatmap.css — 布局与双主题样式
- static/js/heatmap-init.js — 轻量渲染逻辑（无 Heat.js 重型 UI）

集成方式

文章页（templates/article.html）：


<aside class="article-heatmap-sidebar">
  {% set heatmap_mode = "article" %}
  {% include "partials/heatmap_component.html" %}
</aside>

归档页（templates/archive.html）：


{% set heatmap_mode = "archive" %}
{% include "partials/heatmap_component.html" %}

设计说明

放弃 Heat.js 默认「Heat.js [ Map ]」大标题 UI，改用自研紧凑渲染，更接近 GitHub Contributions 视觉。
移动端（≤960px）热力图自动移至正文上方，避免遮挡阅读。

启用主题内置数据统计功能；

[extra.analytics] service = “umami” id = “cdf54193-b449-4454-884b-029e82434c32” self_hosted_url = “https://suchaharcan.github.io” exclude_hash = true

https://cloud.umami.is/share/2hWVbYvlPUkk98Yz 是数据分享页面

2026-06-21T07:49:32+00:00

2026年06月21日

功能模块说明：智能滚动导航组件 (Smart Scroll-Navigation)

概述本组件是一个常驻于页面右下角的圆形交互按钮，集成了全屏滚动进度展示与双向智能导航功能。它能够根据用户的阅读深度，动态调整自身视觉形态与交互行为。
核心交互机制该模块基于页面滚动深度（Scroll Progress）实现智能状态切换：

视觉状态同步：

顶部进度条：固定于视窗顶部的 3px 极细线性进度条，同步反馈阅读进度。

环形按钮进度：按钮外圈环绕的 SVG 进度条与顶部进度条完全同步，保证视觉一致性。

统一圆形形态：按钮采用 border-radius: 50% 设计，内部进度条绕圆心延伸，无视觉断层。

上下文智能导航：

区域 A（阅读深度 < 50%）：组件处于“向下”状态，箭头指向底部。点击触发 smooth scroll 至页面尾部，方便用户快速跳过开头进入正文或评论区。

区域 B（阅读深度 > 50%）：组件处于“向上”状态，箭头翻转 180 度指向顶部。点击触发 smooth scroll 至页面头部，方便用户回溯文章。

架构方案本功能采用轻量级模块化设计，无外部依赖，确保页面加载性能：

HTML (Partial)：负责结构定义，通过 partials 引入，实现代码解耦。

CSS (Static)：采用 CSS Flexbox 实现内容垂直居中，利用 SVG stroke-dasharray 属性实现环形进度条的高性能渲染。

JavaScript (Static)：通过 requestAnimationFrame 优化滚动监听性能，利用 dataset 属性安全管理组件的导航方向状态。

应用场景与设计哲学极简审美：摒弃传统“回顶按钮”单一、生硬的交互，将阅读感知融入组件中。

空间优化：将进度反馈与导航功能合并，减少 UI 元素对屏幕空间的占用。

自适应体验：逻辑完全基于 scrollHeight 动态计算，无论是几百字的小短文还是长篇技术分析，导航阈值均能自动适配，无需手动维护。

安装与集成提示模块引入：在你的 article.html 中通过 {% include “partials/scroll-progress-bar.html” %} 引入结构。

资源引用：在模板的头部引入 scroll-progress-bar.css，底部引入 scroll-progress-bar.js。

性能保障：由于使用了 requestAnimationFrame，即使在复杂的长文档页面中，该组件也不会导致页面滚动时的视觉卡顿，满足极客对高性能页面的要求。

如果你需要将此模块部署到其他页面（如 index.html 或 archive.html），只需在相应模板中重复以上引用步骤即可。

看板 Markdown 映射说明

2026-06-21T00:00:00+00:00

周计划看板 · Markdown 映射说明

看板数据统一存放在 content/kanban/（一个 .md 文件 = 一个自然周，或单日「上午 / 下午 / 晚上」时段看板）。
Zola 构建时将原始 Markdown 内嵌到页面，规则引擎直接解析，无需 static/ 副本。

文件命名

规则	示例
多天（跨天周计划）：`周开始-周结束(月-日)-打开编辑器时的时分`	`2026-06-16-06-22-2236.md`（= 6.16 – 6.22，22:36 打开 GUI）
单日「全天」（不选时段）：`周开始`	`2026-10-13.md`
单日 + 时段：`周开始_时段`	`2026-10-13_上午.md` / `2026-10-13_下午.md` / `2026-10-13_晚上.md`
修改已有看板	沿用原文件名，不会因为改内容而改 URL
路径	`content/kanban/<文件名>.md`

文件名同时是「生成并复制到剪贴板 / 同步到仓库」时提示的目标文件名（新建时按上面的规则生成，时分取自打开 GUI 编辑器的那一刻，编辑过程中不再变化）。

URL 唯一性（重要）：Zola 会把文件名开头的 YYYY-MM-DD 当成页面日期并从 slug 中剥离，只剩余下部分参与 URL。因此每块看板都在 front matter 里显式写 slug（= URL 安全化的文件名），否则会出现两类事故：不同日期的同一时段撞车（2026-08-11_晚上.md 与 2026-10-13_晚上.md 都会变成 /kanban/wan-shang/，构建报 Found path collisions）；多天与单日「全天」也会混淆。GUI 新建 / 编辑时都会自动写入 slug。

看板类型	文件名	生成的 URL
多天（跨天周计划）	`2026-06-16-06-22-2236.md`	`/kanban/2026-06-16-06-22-2236/`
单日「全天」（不选时段）	`2026-10-13.md`	`/kanban/2026-10-13/`
单日上午	`2026-10-13_上午.md`	`/kanban/2026-10-13-shang-wu/`
单日下午	`2026-10-13_下午.md`	`/kanban/2026-10-13-xia-wu/`
单日晚上	`2026-10-13_晚上.md`	`/kanban/2026-10-13-wan-shang/`

因为多天看板的文件名带上了结束日期与创建时分，多天、全天、上午、下午、晚上这五类看板可以在同一天共存，且 URL 各自唯一。

历史文件：2026-06/07 创建的 4 块多天看板已统一迁移为新命名（2026-06-16-06-22-0934.md 等），并在 front matter 里加了 slug（新 URL）与 aliases（旧 URL），老链接照常可访问；用 GUI 修改这些看板并保存时，slug 与 aliases 都会被保留。

编辑时的锁定规则

看板类型	周开始	周结束	时段
单日（含「全天」）	锁定	锁定（起止同一天）	锁定
多天（跨天）	锁定	可改（开始 +13 天以内）	不适用

修改已有看板时不会重命名文件、也不会改写已有 slug，因此 URL 保持稳定。

新建时的重复提示

新建看板时，如果所选时间段与已有看板重叠，编辑面板会直接提示：

完全相同（起止一致）→ 「该时间段已有看板：<核心任务>（起 ~ 止），建议到列表里点它的「✎ 编辑」修改，而不是新建。」
部分重叠 → 「该时间段与已有看板重叠：<核心任务>（起 ~ 止），继续新建会同时存在两块时间重叠的看板。」

提示数据来自列表页内嵌的看板清单，随你调整起止日期实时更新；修改已有看板时不会出现该提示。

Front Matter（页面元数据）

+++
title = "6.16 – 6.22 周计划"
description = "列表页摘要，可选"
date = 2026-06-16
template = "kanban.html"
[extra]
week_start = "2026-06-16"
week_end = "2026-06-22"
core_tasks = "本周核心任务一句话"
stats = { total = 8, done = 3, todo = 3, doing = 2 }
+++

单日看板（带时段）额外写一行 slug，GUI 新建 / 编辑时会自动带上：

+++
title = "2026-10-13 晚上 计划"
date = 2026-10-13
slug = "2026-10-13-wan-shang"
template = "kanban.html"
[extra]
week_start = "2026-10-13"
week_end = "2026-10-13"
period = "晚上"
+++

字段	说明
`week_start` / `week_end`	顶格时间约束：必须优先设置；跨度 1 ~ 14 天（默认新建 = 今日到今日）；修改已有看板时 `week_start` 锁定，单日看板 `week_end` 一并锁定、多天看板 `week_end` 最大为开始 +13 天；全部卡片的 `@start` / `@due` 必须落在该区间内（GUI 编辑器校验并限制日期选择）
`period`	时段：`上午` / `下午` / `晚上`（仅单天看板参与文件名与 URL；配合自动生成的 `slug` 保证同日多看板 URL 唯一）
`slug`	看板 URL（= URL 安全化的文件名）：多天 `2026-06-16-06-22-2236`、全天 `2026-10-13`、时段 `2026-10-13-wan-shang`。GUI 新建、编辑时自动写入；手写文件时必须自己补，否则会和其它看板撞 URL
`core_tasks`	列表卡片展示的核心任务
`board_bg`	看板背景（预置色名或 `#RRGGBB` / `gradient(...)`，Trello 风格）
`favorite`	`true` / `false`，看板标题旁星标收藏（需保存生效）
`stats`	进度统计（按列名自动计算）

结构映射

Markdown	看板元素
`# 列表名`	一列（待办 / 进行中 / 已完成 / 资源 / 目标）
`## 卡片标题`	一张卡片，归属上方最近的 `#` 列表

列顺序 = 文件中 # 出现顺序。
卡片顺序 = 各列内 ## 出现顺序。

列表级可选指令（写在 # 列名 之后、第一张卡片之前）：

指令	语法	看板表现
列内排序	`@sort manual / due / priority / title / checklist`	明细页按该规则排序显示（默认 manual）
排序方向	`@sort-order asc / desc`	升序（默认）/ 降序

卡片属性 · 规则引擎指令

指令单独占一行，写在 ## 标题 之后、正文之前。以 @ 开头，大小写不敏感。

指令	语法	看板表现
截止日期	`@due 2026-06-20`	卡片底部截止图标 + 日期
开始日期	`@start 2026-06-16`	卡片底部开始图标 + 日期
重要等级	`@priority 4` 或 `@importance 4`	1–5 星（淡黄色，满星填充）
目标类型	`@goal complete` / `@goal risk`	目标看板：完成效果（淡蓝）/ 未完成后果（灰爆）
颜色标签	`@labels red, blue` 或 `@label green`	明细页顶栏色条（权重 n）；列表页不显示
顶栏色	`@top red` 或 `@top orange`	明细页卡片顶部粗色条（Trello 顶栏）
封面尺寸	`@cover half` / `@cover full`	半封面（默认）= 顶部色条；全封面 = 整卡背景着色（浅色自动深字）
完成状态	`@done` 或 `@complete`	卡片正面打勾、标题划线、截止徽标变绿（Trello “标记完成”）
置顶	`@pin` 或 `@置顶`	同一列表可多卡片置顶；置顶卡片优先显示，卡片带 📌 徽标
背景封面色	`@bg orange` 或 `@bg #FFE0B2`	卡片封面：半封面 = 顶部色条；配合 `@cover full` = 整卡背景着色
顶栏色	`@top red` 或 `@top #E53935`	卡片顶部细色条（Trello 顶栏）
勾选框	`- [ ] 未完成` / `- [x] 已完成`	卡片内 checklist

预置标签色名

red · orange · yellow · green · blue · purple · pink · sky · lime · black

也支持 #RGB / #RRGGBB 十六进制。

描述正文

除 @ 指令与 checkbox 行以外的 Markdown（段落、列表、加粗等）→ 卡片描述区。

完整示例

# 待办

## 规则引擎文档
@due 2026-06-18
@labels blue, green
@top purple

- [ ] 编写 kanban-rules.js
- [ ] 补充映射说明

完成 **Markdown ↔ 看板** 双向转换说明。

# 进行中

## 看板 UI
@bg #FFF3E0
@top orange
@due 2026-06-20

- [x] Trello 列布局
- [ ] 拖拽交互

# 已完成

## 需求梳理
@labels green

- [x] 对齐 article / nanolog 结构

编辑方式

状态	行为
锁定（默认）	不可拖拽；隐藏 ReDeplog / Edit Post / 映射说明
解锁	仅在 `week_start`～`week_end` 窗口内可切换；可拖拽卡片跨列（本地预览）
保存	点击 Edit Post：先将当前看板按映射规则序列化写入 `content/kanban/_edit-buffer.md`（缓冲），再覆盖 `content/kanban/<周>.md`；无 Token 时复制到剪贴板并在 Codeberg 编辑器粘贴
超期	截止日 `week_end` 当日 23:00（站点 `zola.toml` → `extra.timezone`）之后永久只读，无法解锁

看板详情页（Trello 对齐）

明细页 UI 全盘参考 Trello 重构：

区域	行为
看板头部	返回链接 · 标题 · 收藏星标（`extra.favorite`）· 开始/截止/剩余天数/进度/星级元信息行
背景	由 `extra.board_bg` 控制；菜单 → 背景可快速切换 12 种预置渐变（需保存生效）
工具栏	锁定 / 筛选（快捷键 `F`）/ 菜单 / GUI 编辑 / Edit Post / ReDeplog / 映射说明
筛选	关键词 + 标签 + 截止状态（已逾期/即将到期/无截止）+ 最低优先级 + 隐藏已完成；列计数显示 `可见/总数`
列	头部 = 列名 + 计数 + `⋯` 菜单（添加卡片 / 排序 / 重命名 / 删除列）；解锁后可拖拽列头调整顺序
卡片正面	标签药丸（带文字）· 封面（`@bg` + `@cover`）· 完成圆圈（`@due` 时显示，切换 `@done`）· 置顶 📌 徽标（`@pin`）· 徽标行（描述/开始/截止/清单进度/优先级）
截止徽标	按 Trello 色义：灰色（未到）· 黄（今天/即将到期）· 红（逾期）· 粉（逾期超 1 天）· 绿（已完成）
菜单抽屉	关于此看板（进度条）· 背景色板 · 搜索卡片（回车进入筛选）· 更多（GUI 编辑 / 保存 / ReDeplog / 映射说明）
快捷添加	解锁后每列底部「＋添加卡片」、看板右侧「＋添加列表」，回车即插入（保存走 Edit Post）

以上所有本地修改都会提示“有未保存的本地修改”，统一通过 Edit Post 序列化保存。

GUI 编辑器（新建 / 修改看板）

除了直接编写 Markdown，看板提供 GUI 方式生成 / 修改：按「看板图标 / 指令的可选值」用下拉框或手动输入设置，自动生成 Markdown。

布局（Trello 风格：画布 + 检查器）

左侧画布：实时渲染当前看板（背景、列、卡片封面/标签/徽标），点击列或卡片即可选中编辑；底部/右侧可「添加列表」「添加卡片」。
右侧检查器：根据选中对象切换编辑面板：
- 未选中（看板）：周起止（顶格时间：先设置；1–14 天；新建默认今日；修改时开始锁定） / 时段 period（单天唯一性） / 核心任务 / 标题 / 描述 / 星级 / 收藏 / 看板背景色板；
- 选中列表：列名 / @sort 排序 / @sort-order 方向 / 添加卡片 / 上移下移 / 删除列 / 卡片列表；
- 选中卡片：标题 / 开始 / 截止（新建时默认按创建时间=今日填充，可编辑但限制在周起止区间内）/ 优先级 / 目标 / 封面（@bg + @cover）/ 顶栏色 / 标签 / 完成 @done / 置顶 @pin / 勾选清单 / 描述。
Markdown 预览：底部可折叠，输入时实时更新。

入口

位置	按钮	模式
列表页 `/kanban/` 页头	＋新建看板（管理员可见；Mac-Chrome 浏览器也可见）	新建：默认今日 → 今日（单天，按当前时间预选上午/下午/晚上）+ 六列（待办 / 进行中 / 已完成 / 进度 / 资源 / 目标）
列表页每张周卡片	✎ 编辑（管理员可见）	修改：读取该周已有 Markdown 载入表单
明细页工具栏（解锁后）	GUI 编辑	修改：读取当前看板载入表单

字段与指令对应（每个“图标“的可选值）

表单字段	生成指令	输入方式
开始日期	`@start YYYY-MM-DD`	日期下拉（默认按创建时间=今日填充，限 [week_start, week_end]）
截止日期	`@due YYYY-MM-DD`	日期下拉（默认按创建时间=今日填充，限 [week_start, week_end]）
重要等级	`@priority 1–5`	下拉（1–5 星 / 无）
目标类型	`@goal complete / risk`	下拉（完成效果 / 未完成后果 / 无）
颜色标签	`@labels red, blue, …`	预设色块多选 + 手输自定义（`#RRGGBB` 或颜色名，逗号分隔）
背景封面色	`@bg`	预设色名下拉 + 自定义色值手输 + 实时色块（Trello 封面）
封面尺寸	`@cover`	下拉（默认半封面 / 全封面）
顶栏色	`@top`	预设色名下拉 + 自定义色值手输 + 实时色块
完成状态	`@done`	复选框
置顶	`@pin`	卡片面板「置顶 / 解除置顶」按钮；同一列表可多卡片置顶
勾选清单	`- [ ] / - [x]`	逐行添加：勾选状态 + 文本
描述正文	其余 Markdown	多行文本
列	`# 列名` + `@sort` / `@sort-order`	画布添加/删除 + 检查器列名/排序
周起止 / 核心任务 / 星级	Front Matter	日期 / 文本 / 下拉
看板背景 / 收藏	Front Matter	背景色板 / 复选框
时段 period	Front Matter（单天命名）	下拉：无 / 上午 / 下午 / 晚上

默认新建布局

待办    进行中    已完成    进度        ← 主流程列（竖向一排）
资源    目标                             ← 底部并排一行

进度列：从 week_start 到 week_end 每一天生成一张卡片（标题如 07-13 周一），每张默认含一条勾选清单「记录当日完成内容」（可勾选 / 划线）；
修改顶格时间且进度列仍为自动生成样式（标题匹配 MM-DD 周X）时，编辑器会自动重排天数；
置顶：置顶卡片始终显示在同列表顶部（多个可同时置顶），卡片正面带 📌 徽标；解锁模式下每张卡片都有「📌 置顶 / 📌 置顶中」切换按钮，点击即置顶/取消置顶；GUI 编辑器卡片面板同样提供按钮。

生成 → 剪贴板 → 创建 / 修改流程

填写表单，右侧 Markdown 预览实时更新（也可点「仅复制 Markdown」）。
点 生成并复制到剪贴板：
- 自动将序列化后的 Markdown 复制到剪贴板；
- 弹出操作流程提示，明确区分创建还是修改：
  - 创建（content/kanban/<周>.md 不存在）：打开 Codeberg 新建文件 → 粘贴 → 保存提交 → ReDeplog 部署 → 刷新列表；
  - 修改（文件已存在 / 编辑已有看板）：打开 Codeberg 覆盖文件 → 全选替换 → 保存提交 → ReDeplog 部署 → 刷新列表。
若浏览器已保存 kanbanToken，可点 用 Token 直接同步到仓库（文件不存在走 POST 创建，存在走 PUT 覆盖），再打开 ReDeplog 部署。

列表页进度色

仅「待办 / 进行中 / 已完成」三列参与进度；「资源 / 目标」不参与。

背景色规则

条件	卡片背景
`todo > 3`	全红 `#FFEBEE`
`done == total` 且 total > 0	浅绿 `#E8F5E9`
其余	按加权进度百分比渐变（红 → 黄 → 绿）

加权进度公式

以 50% 为基准，逐卡片累加（标签数 n 为权重，无标签时 n = 1）：

所在列	单项贡献
待办	−10% × n
进行中	+5% × n
已完成	+15% × n

例：进行中列卡片有 2 个 @labels → +5% × 2 = +10%。

结果 clamp 至 0–100%，写入 front matter stats.progress_pct。

列表页标题显示 core_tasks（非日期）；元信息行含开始 / 截止 / 剩余天数 / 星级（importance 字段，1–5）。

after close VPN, analyze why no Net

2026-06-20T00:00:00+00:00

tl; dr => 通用解决方案

前置知识

VPN原理 VPN 改动 DNS服务器地址虚拟DNS 服务器，所有的 DNS请求都会走虚拟DNS服务器，相当于代理工具接管系统DNS服务器，再由虚拟DNS服务器处理发往真正的DNS服务器关闭代理工具，但虚拟DNS服务器按理来说是不存在，应当消失，回归系统DNS服务器；

该问题触发场景

日常使用时尽量避免

VPN不关闭且 < 熄屏或休眠太久> 重新打开
多个DNS软件同时使用（ Adguard，VPN，等）覆写DNS时被其他软件接管或中断
小众VPN 套壳Clash 是老版本， MacOS 新版本中网络模块没有相应的补丁修复 Github 上有相关的issue

优化点：

VPN 用完就关
尽量使用小火箭 QX Surge 等及时更进系统更新有网络补丁和协议支持的软件
Install TraceBar

没有遥测数据，没有分析数据，也没有账户。所有数据都保存在内存中，退出后就会丢失
可视化示数据通过互联网传输到目的地的路径，并显示沿途的任何网络问题。它可以帮助您诊断和定位网络问题，从而确定是您的 Wi-Fi 故障、互联网连接故障、网络服务提供商故障，还是其他原因导致的同类专业级软件：Pingplotter

brew tap tracebar-app/tracebar && brew install --cask tracebar

常用命令

# 查看当前DNS服务器地址
cat /etc/resolv.conf
scutil --dns  

# 查看默认的DNS服务器
scutil --dns | grep nameserver

# 路由信息查看
netstat -r

# DNS 解析域名
dig @[DNS服务器] [域名]

连接VPN 前


❯ cat /etc/resolv.conf                                  ─╯
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 192.168.231.1
nameserver 192.168.1.1

DNS 指向局域网网关 192.168.231.1 和 192.168.1.1

scutil --dns                                          ─╯
DNS configuration

resolver #1
  nameserver[0] : 192.168.231.1
  nameserver[1] : 192.168.1.1
  if_index : 7 (en0)
  flags    : Request A records
  reach    : 0x00000002 (Reachable)

resolver #2
  domain   : local
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 300000

resolver #3
  domain   : 254.169.in-addr.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 300200

resolver #4
  domain   : 8.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 300400

resolver #5
  domain   : 9.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 300600

resolver #6
  domain   : a.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 300800

resolver #7
  domain   : b.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records
  reach    : 0x00000000 (Not Reachable)
  order    : 301000

DNS configuration (for scoped queries)

resolver #1
  nameserver[0] : 192.168.231.1
  nameserver[1] : 192.168.1.1
  if_index : 7 (en0)
  flags    : Scoped, Request A records
  reach    : 0x00000002 (Reachable)

❯ scutil --dns | grep nameserver                        ─╯
  nameserver[0] : 192.168.231.1
  nameserver[1] : 192.168.1.1
  nameserver[0] : 192.168.231.1
  nameserver[1] : 192.168.1.1

说明 DNS …

连接VPN 后

❯ cat /etc/resolv.conf                                  ─╯
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 198.18.0.2

DNS 依然被锁定在 198.18.0.2（这通常是 Clash 等代理/VPN 工具使用的 Fake IP 或者是其内置 TUN 模式的 DNS 服务地址）前后比对，DNS解析地址被替换，路由信息被更新“ 当 VPN 关闭后，这个 IP 变得不可达，导致你的 Mac 无法解析任何域名，从而“断网”。

命令方式解析 dig @[DNS服务器] [域名]

dig @114.114.114.114 www.baidu.com

一、命令行定位与分析步骤既然怀疑是 DNS 问题，我们可以通过以下命令行组合进行精准排查：

验证是否只是 DNS 解析失败（排除物理断网）在终端中尝试直接 ping 一个公网 IP（如 Google 或腾讯的公共 DNS），再 ping 一个域名：


ping -c 3 114.114.114.114
ping -c 3 baidu.com

分析：如果 ping 114.114.114.114 能通，但 ping baidu.com 提示 cannot resolve baidu.com: Unknown host，说明网络连接完全正常，100% 是 DNS 的锅。

查看 macOS 真正的 DNS 配置正如你截图中 macOS 自带的警告所说，macOS 并不真正依赖 /etc/resolv.conf，它有自己的系统配置框架（Configuration Daemon）。执行以下命令查看当前生效的 DNS：

scutil --dns

分析：检查输出中的 nameserver[0]。你会发现即使关闭了 VPN，这里可能依然残留着 198.18.0.2。这是因为 VPN 客户端退出时，未能正常调用系统 API 将修改的 DNS 还原。

查看网络服务（以 Wi-Fi 为例）的硬件 DNS 设置

networksetup -getdnsservers Wi-Fi

分析：如果这里输出了 198.18.0.2 或提示存在特定的 DNS，说明 VPN 直接修改了你网卡的硬配置。如果输出 There aren’t any DNS Servers set on Wi-Fi.，说明走的是 DHCP 自动获取（这是正常的，不正常的配置残留在内存的 scutil 守护进程中）。

❯ ping -c 3 114.114.114.114                                                                ─╯
PING 114.114.114.114 (114.114.114.114): 56 data bytes
64 bytes from 114.114.114.114: icmp_seq=0 ttl=64 time=3.109 ms
64 bytes from 114.114.114.114: icmp_seq=1 ttl=64 time=1.630 ms
64 bytes from 114.114.114.114: icmp_seq=2 ttl=64 time=1.009 ms

--- 114.114.114.114 ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 1.009/1.916/3.109/0.881 ms

 ~ ────────────────────────────────────────────────────── system Node  at 08:45:41 AM ─╮
❯ ping -c 3 baidu.com                                                                      ─╯
PING baidu.com (124.237.177.164): 56 data bytes
64 bytes from 124.237.177.164: icmp_seq=0 ttl=64 time=4.223 ms
64 bytes from 124.237.177.164: icmp_seq=1 ttl=64 time=1.734 ms
64 bytes from 124.237.177.164: icmp_seq=2 ttl=64 time=0.817 ms

--- baidu.com ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.817/2.258/4.223/1.439 ms

 ~ ────────────────────────────────────────────────────── system Node  at 08:45:49 AM ─╮
❯ scutil --dns                                                                             ─╯
DNS configuration

resolver #1
  nameserver[0] : 198.18.0.2
  if_index : 24 (utun11)
  flags    : Supplemental, Request A records, Request AAAA records
  reach    : 0x00000003 (Reachable,Transient Connection)
  order    : 102200

resolver #2
  nameserver[0] : 198.18.0.2
  if_index : 24 (utun11)
  flags    : Request A records, Request AAAA records
  reach    : 0x00000003 (Reachable,Transient Connection)
  order    : 200000

resolver #3
  domain   : local
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 300000

resolver #4
  domain   : 254.169.in-addr.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 300200

resolver #5
  domain   : 8.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 300400

resolver #6
  domain   : 9.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 300600

resolver #7
  domain   : a.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 300800

resolver #8
  domain   : b.e.f.ip6.arpa
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)
  order    : 301000

DNS configuration (for scoped queries)

resolver #1
  nameserver[0] : 192.168.231.1
  nameserver[1] : 192.168.1.1
  if_index : 7 (en0)
  flags    : Scoped, Request A records
  reach    : 0x00000002 (Reachable)

resolver #2
  nameserver[0] : 198.18.0.2
  if_index : 24 (utun11)
  flags    : Scoped, Request A records, Request AAAA records
  reach    : 0x00000003 (Reachable,Transient Connection)

 ~ ────────────────────────────────────────────────────── system Node  at 08:45:55 AM ─╮
❯ ping baidu.com                                                                           ─╯





 ~ ──────────────────────────────────── INT ✘  took 7s  system Node  at 08:49:05 AM ─╮
❯                                                                                          ─╯
cat /etc/resolv.conf
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 192.168.231.1
nameserver 192.168.1.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:49:16 AM ─╮
❯ ping baidu.com                                                                           ─╯
^C

 ~ ──────────────────────────────────── INT ✘  took 6s  system Node  at 08:49:28 AM ─╮
❯ dig @192.168.231.1 www.baidu.com                                                         ─╯
;; communications error to 192.168.231.1#53: timed out
;; communications error to 192.168.231.1#53: timed out
;; communications error to 192.168.231.1#53: timed out

; <<>> DiG 9.20.24 <<>> @192.168.231.1 www.baidu.com
; (1 server found)
;; global options: +cmd
;; no servers could be reached

 ~ ─────────────────────────────────────────── took 15s  system Node  at 08:49:59 AM ─╮
❯                                                                                          ─╯
cat /etc/resolv.conf
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 192.168.231.1
nameserver 192.168.1.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:52:48 AM ─╮
❯ ping -c 3 192.168.231.1                                                                  ─╯
PING 192.168.231.1 (192.168.231.1): 56 data bytes
64 bytes from 192.168.231.1: icmp_seq=0 ttl=63 time=4.427 ms
64 bytes from 192.168.231.1: icmp_seq=1 ttl=63 time=1.954 ms
64 bytes from 192.168.231.1: icmp_seq=2 ttl=63 time=2.018 ms

--- 192.168.231.1 ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 1.954/2.800/4.427/1.151 ms

 ~ ────────────────────────────────────────────────────── system Node  at 08:52:54 AM ─╮
❯ netstat -nr | grep default                                                               ─╯
default            192.168.1.1        UGScg                 en0
default                                 fe80::%utun0                            UGcIg               utun0
default                                 fe80::%utun1                            UGcIg               utun1
default                                 fe80::%utun2                            UGcIg               utun2
default                                 fe80::%utun3                            UGcIg               utun3
default                                 fe80::%utun12                           UGcIg              utun12
default                                 fe80::%utun13                           UGcIg              utun13

 ~ ────────────────────────────────────────────────────── system Node  at 08:53:20 AM ─╮
❯ sudo route -n delete default 192.168.1.1                                                 ─╯
Password:
delete net default: gateway 192.168.1.1

 ~ ──────────────────────────────────────────── took 4s  system Node  at 08:56:11 AM ─╮
❯ sudo route -n add default 192.168.231.1                                                  ─╯
add net default: gateway 192.168.231.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:56:25 AM ─╮
❯ cat /etc/resolv.conf                                                                     ─╯
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 192.168.231.1
nameserver 192.168.1.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:58:04 AM ─╮
❯ netstat -nr | grep default                                                               ─╯
default            192.168.1.1        UGScg                 en0
default                                 fe80::%utun0                            UGcIg               utun0
default                                 fe80::%utun1                            UGcIg               utun1
default                                 fe80::%utun2                            UGcIg               utun2
default                                 fe80::%utun3                            UGcIg               utun3
default                                 fe80::%utun12                           UGcIg              utun12
default                                 fe80::%utun13                           UGcIg              utun13

 ~ ────────────────────────────────────────────────────── system Node  at 08:58:14 AM ─╮
❯ sudo route -n delete default 192.168.1.1                                                 ─╯
delete net default: gateway 192.168.1.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:58:23 AM ─╮
❯ sudo route -n add default 192.168.231.1                                                  ─╯
route: writing to routing socket: Network is unreachable
add net default: gateway 192.168.231.1: Network is unreachable

 ~ ────────────────────────────────────────────────────── system Node  at 08:58:31 AM ─╮
❯ cat /etc/resolv.conf                                                                     ─╯
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 192.168.231.1
nameserver 192.168.1.1

 ~ ────────────────────────────────────────────────────── system Node  at 08:58:40 AM ─╮
❯ netstat -nr | grep default                                                               ─╯
default                                 fe80::%utun0                            UGcIg               utun0
default                                 fe80::%utun1                            UGcIg               utun1
default                                 fe80::%utun2                            UGcIg               utun2
default                                 fe80::%utun3                            UGcIg               utun3
default                                 fe80::%utun12                           UGcIg              utun12
default                                 fe80::%utun13                           UGcIg              utun13

❯ ping -c 3 192.168.231.1 ─╯

PING 192.168.231.1 (192.168.231.1): 56 data bytes

64 bytes from 192.168.231.1: icmp_seq=0 ttl=63 time=4.427 ms

64 bytes from 192.168.231.1: icmp_seq=1 ttl=63 time=1.954 ms

64 bytes from 192.168.231.1: icmp_seq=2 ttl=63 time=2.018 ms

— 192.168.231.1 ping statistics —

3 packets transmitted, 3 packets received, 0.0% packet loss

round-trip min/avg/max/stddev = 1.954/2.800/4.427/1.151 ms

 ~ ────────────────────────────────────────────────────── system Node  at 08:52:54 AM ─╮

❯ netstat -nr | grep default ─╯

default 192.168.1.1 UGScg en0

default fe80::%utun0 UGcIg utun0

default fe80::%utun1 UGcIg utun1

default fe80::%utun2 UGcIg utun2

default fe80::%utun3 UGcIg utun3

default fe80::%utun12 UGcIg utun12

default fe80::%utun13 UGcIg utun13

破案了！这是一起非常典型的多网卡/双网关路由冲突引发的“高级故障”。

你的测试结果给出了最关键的线索：

ping 192.168.231.1 可以通，说明物理链路和该网段是通的。

netstat -nr | grep default 暴露了致命问题：你的 IPv4 默认网关（default）指向的是 192.168.1.1，走的是 en0 接口。

一、 深度原理分析：为什么会断网？
回到你上一张图的 /etc/resolv.conf：

Plaintext
nameserver 192.168.231.1
nameserver 192.168.1.1
你当前系统里其实并存了两个物理网络（或者一个多网段的复杂网络），一个是 192.168.231.x，另一个是 192.168.1.x。

数据包的迷路过程：
当你执行 dig @192.168.231.1 www.baidu.com 时，系统查路由表发现，要前往 192.168.231.1 不需要走默认网关，因为它属于本地直连网段。
但是，你的默认路由（负责所有外网流量）被死死绑定在了 192.168.1.1 上。当 VPN 关闭后，192.168.1.1 这个网关可能根本没有通往外网的权限，或者它是个死网关。

总结： 你的 Mac 目前误把没有外网能力的 192.168.1.1 当作了主力出口，而把真正能上网的 192.168.231.1 晾在了一边。

二、 命令行解决方案
我们需要明确告诉 macOS：把外网出口（默认网关）切换回 192.168.231.1。

步骤 1：手动修正 IPv4 默认路由
强行删除错误的 192.168.1.1 默认网关，并指向正确的 192.168.231.1：

Bash
# 1. 删除当前指向 192.168.1.1 的默认路由
sudo route -n delete default 192.168.1.1

# 2. 添加真正能上网的 192.168.231.1 作为默认网关
sudo route -n add default 192.168.231.1
步骤 2：彻底清除残留的 utun 虚拟接口路由（可选）
你的输出中有一大堆 utun0 到 utun13 的 IPv6 残留。虽然它们是 IPv6，但为了防止干扰，可以直接让网络服务重新加载：

Bash
# 触发网络接口配置更新（将 en0 软重启）
sudo ifconfig en0 down && sudo ifconfig en0 up
步骤 3：调整 macOS 网络服务优先级（长久之计）
如果你的 Mac 同时连接了多个网络接口（比如 Wi-Fi 和以太网，或者两个不同的虚拟网络），你需要让提供 192.168.231.x 的那个接口在系统里处于最高优先级。

先查看你所有的网络服务名称：

Bash
networksetup -listnetworkserviceorder
假设你的以太网叫 USB 10/100/1000 LAN，Wi-Fi 叫 Wi-Fi。如果你希望以太网优先，可以使用以下命令调整顺序（把你希望优先的服务写在最前面）：

Bash
# 示例命令，请根据你上一步查到的实际名称修改
sudo networksetup -ordernetworkservices "USB 10/100/1000 LAN" "Wi-Fi" "Bluetooth PAN"
三、 验证网络
完成路由调整后，请再次测试：

Bash
# 1. 再次检查默认网关是否已变为 192.168.231.1
netstat -nr | grep default

# 2. 测试域名解析
dig www.baidu.com

# 3. 测试外网是否畅通
ping -c 3 baidu.com



当 VPN 关闭后发生断网，其根本原因通常是 VPN 软件未能干净地撤销它对系统网络栈（DNS、路由表、虚拟网卡、防火墙）的接管。按照一个标准的数据包从“域名解析”到“物理网卡发出”的 正常网络访问链路，我们可以从上到下、由表及里地梳理出一套完整的命令行（CLI）排查与验证指南。🌐 正常网络访问链路排查总览为了方便记忆，排查链路分为以下 5 个核心节点：应用层/DNS 映射（/etc/resolv.conf）系统 DNS 解析引擎（mDNSResponder / scutil）网络层路由转发（netstat / route）链路层/物理网卡状态（ifconfig / networksetup）系统防火墙与流量拦截（pfctl）🛠️ 各链路节点排查与命令总结节点 1：配置文件层（检查基础 DNS 地址）数据包发出的第一步，是检查系统基础的域名解析服务器指向。查看命令：Bashcat /etc/resolv.conf
异常表现： nameserver 后面依然残留 VPN 的私有 DNS（如 198.18.0.2 等 Fake IP 映射地址）。正常表现： 应该指向你的局域网网关（如 192.168.1.1）或公共 DNS（如 114.114.114.114）。节点 2：系统 DNS 解析层（检查实际 DNS 路由与解析能力）macOS 并不直接依赖上一步的配置文件，而是通过配置画布（Configuration Daemon）管理。查看实际生效 DNS：Bashscutil --dns
检查 nameserver[0] 是否为有效的外网 DNS。测试指定 DNS 接口解析：Bash# 强制使用你本地的网关（如 192.168.231.1）去解析外网域名
dig @192.168.231.1 www.baidu.com
测试系统默认 DNS 解析：Bashdig www.baidu.com
异常表现： dig 提示 timed out 或 no servers could be reached（即使网关能 ping 通）。此节点修复命令（刷新 DNS 缓存）：Bashsudo killall -HUP mDNSResponder
节点 3：网络层路由转发（检查默认网关）DNS 解析成功（或直接访问 IP）后，数据包需要知道从哪一个“出口”发往外网。查看全局路由表（特别是默认网关）：Bashnetstat -nr | grep default
测试物理网关的连通性：Bash# 替换为你实际的网关 IP
ping -c 3 192.168.231.1
异常表现： 1. 存在多个 default 路由，导致路由冲突。2. default 错误的指向了已关闭的 VPN 虚拟网卡（如 utunX），或者指向了一个没有外网能力的死网关（如多网卡环境下的错误内网网关）。此节点修复命令（重置默认路由）：Bash# 删除错误的网关，并添加正确的物理网关
sudo route -n delete default 192.168.1.1
sudo route -n add default 192.168.231.1
节点 4：链路层与硬件接口（检查物理网卡状态）确保你的物理网卡（以太网/Wi-Fi）处于激活状态，且获得了正确的 IP 分配。查看所有网络接口状态：Bashifconfig
检查你的物理网卡（如 en0）是否带有 status: active 以及正确的 inet (IP 地址)。查看硬件端口与服务的绑定关系：Bashnetworksetup -listallhardwareports
此节点修复命令（网卡软重启/重新触发 DHCP）：Bash# 以 en0 为例，先禁用再启用，强制重新向路由器申请 IP 和路由
sudo ifconfig en0 down && sudo ifconfig en0 up
节点 5：防火墙与安全策略层（检查流量拦截）很多现代 VPN 软件（如 Clash 增强模式、Surge、Tailscale 等）会写入内核级别的防火墙（PF）转发规则。软件关闭时如果未清理，会把所有非 VPN 流量直接丢弃（Drop）。查看防火墙状态与规则：Bashsudo pfctl -s rules
异常表现： 存在大量指向 127.0.0.1 或是虚拟网卡的 redirect (rdr) 转发规则。此节点修复命令（强制关闭 PF 防火墙拦截）：Bashsudo pfctl -d
📋 快速排查口诀表排查顺序检查目标核心 CLI 命令正常标准Step 1配置文件cat /etc/resolv.confnameserver 为物理网关或公网 DNSStep 2DNS 解析dig www.baidu.com能正确返回 A 记录（IP 地址）Step 3路由网关netstat -nr | grep defaultdefault 唯一且指向真正能上网的物理网关Step 4物理链路ping -c 3 [网关IP]0% packet loss（延迟通常在几毫秒内）Step 5流量拦截sudo pfctl -d彻底关闭可能残留的防火墙拦截规则


终极病灶分析：什么是 link#27？
看看你之前的路由表输出：

Plaintext
default            link#27            UCSg                utun16
在 macOS 中，link#X（如 link#27）代表的是系统内核直接绑定的链路层接口（Link-layer Interface）。
当 VPN 软件（特别是开启了 TUN 模式、Enhance 模式或智能路由的客户端）运行时，它会在内核中创建一个名为 utun16 的虚拟网卡，并把全局默认路由的下一跳直接绑死在物理链路 link#27 上。

这就是为什么你断开 VPN 后依然无法访问的原因：
普通的 sudo route delete default 只能删除常规的 IP 路由，但这种由 VPN 强行写入内核、绑定在 link# 上的链路层条件路由（UCSg 标记）具有极高的优先级，它像胶水一样粘在系统里。即使你以为 VPN 关了，系统在发送 SSH 数据包时，依然通过 link#27 丢给了已经失效的 utun16，导致 Codeberg 的服务器直接断开或根本收不到正确的握手包。

🛠️ 终极命令行解决方案
我们必须用点“暴力”手段，将这些残留的虚拟网卡接口和内核路由彻底抹去。

步骤 1：强行卸载/关停残留的 utun16 接口
既然流量总是被吸进 utun16，我们直接在链路层把它禁用：

Bash
sudo ifconfig utun16 down
(如果执行后路由表里还有别的 utunX 占领 default，可以针对性地将其 down 掉)

步骤 2：强制刷新 macOS 内核路由表（终极重置）
既然常规命令删不掉 link#27，我们直接通过重启 macOS 网络核心配置框架，逼迫系统重新扫描物理网卡：

Bash
# 1. 强制清理并重置系统的网络配置守护进程（这会顺便冲刷掉内核残留的 link 路由）
sudo configd -b -d

# 2. 软重启你的物理网卡 en0，让它重新拿回唯一的 default 控制权
sudo ifconfig en0 down && sudo ifconfig en0 up
步骤 3：验证路由表是否恢复纯净
现在执行以下命令，观察输出：

Bash
netstat -nr | grep default
【正确标准】： 此时输出应该有且只有一行，且必须指向你的物理网关，绝对不能再出现 link# 或 utun：

Plaintext
default            192.168.1.1        UGSc           en0
🧪 最终验证
当路由表被彻底清洗干净，只剩下物理网卡 en0 后，再次发起冲击：

Bash
ssh -vT git@codeberg.org
这一次，数据包终于能顺着真正的物理网线飞往 Codeberg 了！




从这份最新的路由表来看，你的 IPv4 路由表现在是非常干净且正确的：

只有一个 IPv4 默认网关 default 指向 192.168.1.1，并且成功绑定在物理网卡 en0 上。

之前残留的 link#27 和 utun16 的 IPv4 拦截已经彻底消失了。

剩下的 utun0 到 utun13 都是 IPv6 的本地链路多播路由（fe80:: 开头），属于 macOS 的正常系统组件（或 OrbStack 的内部通信），不会影响你的 IPv4 外网访问。

既然 IPv4 路由表已经完全正常，为什么 ssh -vT git@codeberg.org 依然卡在 kex_exchange_identification？

这就排除了路由表的嫌疑，问题被锁死在以下两个最后可能的原因：

🔍 终极原因定位与验证
1. 终端的环境变量中残留了代理
虽然你的 VPN 软件关闭了，路由也清干净了，但如果你当前使用的这个终端窗口是在关闭 VPN 之前打开的，它里面可能依然保留着旧的 ALL_PROXY 或 HTTP_PROXY 环境变量。SSH 会尝试去走这个已经死掉的代理端口，导致连接直接被挂断。

验证与解决命令：
在当前终端直接执行以下命令，清空所有可能的代理变量：

Bash
unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
或者，直接新开一个全新的终端标签页（Terminal Tab）来测试。

2. 运营商或本地宽带网络对 Codeberg 的 22 端口进行了封锁
Codeberg（217.197.84.140）的服务器在海外。在不挂 VPN 的纯国内物理网络下，部分地区的运营商（如移动、长城宽带等）常常会直接拦截或干扰境外非主流 Git 平台的 22 端口（SSH 握手包被审查直接阻断）。

验证命令（测试 22 端口是否能正常建立流传输）：

Bash
nc -vzt codeberg.org 22
或者使用带有探测性质的 curl：

Bash
curl -v ssh://codeberg.org:22
分析： 如果执行 nc 很久没反应，或者显示 Connection refused，说明你的物理宽带网络在没有 VPN 的情况下，本身就无法直接连接 Codeberg 的 SSH 服务。

🛠️ 终极解决方案
如果你清空了环境变量（或换了新终端），并且发现不挂 VPN 就是连不上 Codeberg 的 22 端口，请使用以下两个终极对策：

对策 A：使用 Codeberg 官方提供的 SSH 备用端口（443）
为了应对 22 端口被防火墙或运营商封锁的情况，Codeberg 官方支持通过 443 端口（通常用于 HTTPS，不易被封）来走 SSH 协议。

修改你的 ~/.ssh/config，将 codeberg 的配置改成这样：

Plaintext
Host codeberg.org
    HostName altssh.codeberg.org
    User git
    Port 443
    IdentityFile ~/.ssh/id_ed25519_codeberg
    IdentitiesOnly yes
修改完后，直接测试：

Bash
ssh -vT git@codeberg.org
这个方法非常有效，它依然走的是你的 SSH 密钥认证，但完美绕过了被运营商封锁的 22 端口。

对策 B：切换为 HTTPS 协议克隆/推送
如果 SSH 无论如何都不通，最省心的办法就是放弃 SSH 协议，改用 HTTPS 协议（通过 Codeberg 的账号 + Token/密码）进行代码管理：

Bash
# 修改你本地 Git 仓库的远程连接地址为 HTTPS
git remote set-url origin https://codeberg.org/你的用户名/你的仓库名.git


❯ ping baidu.com                               ─╯
ping: cannot resolve baidu.com: Unknown host

 ~ 
❯ cat /etc/resolv.conf                         ─╯
#
# macOS Notice
#
# This file is not consulted for DNS hostname resolution, address
# resolution, or the DNS query routing mechanism used by most
# processes on this system.
#
# To view the DNS configuration used by this system, use:
#   scutil --dns
#
# SEE ALSO
#   dns-sd(1), scutil(8)
#
# This file is automatically generated.
#
nameserver 223.5.5.5

 ~ ────────── system Node  at 10:39:09 AM ─╮
❯ dig @223.5.5.5 www.baidu.com                 ─╯
;; communications error to 223.5.5.5#53: timed out
;; communications error to 223.5.5.5#53: timed out
;; communications error to 223.5.5.5#53: timed out

; <<>> DiG 9.20.24 <<>> @223.5.5.5 www.baidu.com
; (1 server found)
;; global options: +cmd
;; no servers could be reached

现在的问题和之前的 Hosts 已经没有关系了。这就是最典型、最致命的 “VPN 关闭/残留引发的系统全局 DNS 死锁”。

看这三个连续的致命报错：

Could not resolve host: mirrors.aliyun.com（连国内的阿里云都无法解析）

ping: cannot resolve baidu.com: Unknown host（百度无法解析）

dig @223.5.5.5 www.baidu.com ... timed out（直接向阿里公共 DNS 53端口发包全完超时）

🔍 根源分析：你的 Mac 经历了什么？
虽然你的 /etc/resolv.conf 里写着 nameserver 223.5.5.5，但因为你之前开启过 VPN（TUN 模式、增强模式或系统代理），VPN 在断开或者关闭时，没有干净地把接管的系统底层路由表（Routing Table）和虚拟网卡（utun）卸载掉。

导致的结果是：你的 Mac 依然盲目地把所有 DNS 流量（53端口）丢给一个已经不存在的 VPN 虚拟网关，导致你现在连国内网络、DNS 服务器全部失联。

强行重置 macOS 网络层

# 🛠️ 针对以太网的终极修复步骤
## 找出你当前以太网的准确“服务名称”
不同的扩展坞，以太网在系统里的名字不一样。我们先用这个命令列出你所有的网络接口：

```Bash
networksetup -listallnetworkservices

❯ networksetup -listallnetworkservices                                                           ─╯

An asterisk (*) denotes that a network service is disabled.
Ethernet
Thunderbolt Bridge
Wi-Fi
Shadowrocket

看一眼输出结果：

你会看到类似 AX88179A、USB 10/100/1000 LAN、Thunderbolt Ethernet 或 Ethernet 的名字。请记住这个名字（下面以 Ethernet 为例，如果你的叫别的，请自行替换）。

通用解决方案

网络环境描述：关闭VPN 软件；网络保留一种（有线或无线）简化排查和解决难度
方案默认使用有线网络Ethernet ，根据你自己的网络微调

强行给以太网注入国内骨干 DNS

用官方命令强行把你的有线网络 DNS 冲刷干净，彻底摆脱 VPN 残留：

# "Ethernet"
sudo networksetup -setdnsservers "Ethernet" 223.5.5.5 119.29.29.29

物理层重启以太网卡（重洗路由表）

我们需要让你的有线网卡重新向路由器申请一次内网 IP 和网关。

查明以太网的物理设备名：

networksetup -listallhardwareports
找到你以太网服务对应的 Device（比如 en0 或 en2）。

强行断开并重启该网卡：

Bash
# 是 en0
sudo ifconfig en0 down && sudo ifconfig en0 up


# 定位到是en0
❯ networksetup -listallhardwareports                                                             ─╯


Hardware Port: Ethernet
Device: en0
Ethernet Address: d0:11:e5:8a:4f:6c

Hardware Port: Ethernet Adapter (en5)
Device: en5
Ethernet Address: 9a:86:59:a9:af:e2

Hardware Port: Ethernet Adapter (en6)
Device: en6
Ethernet Address: 9a:86:59:a9:af:e3

Hardware Port: Ethernet Adapter (en7)
Device: en7
Ethernet Address: 9a:86:59:a9:af:e5

Hardware Port: Thunderbolt Bridge
Device: bridge0
Ethernet Address: 36:fd:e1:09:fc:c0

Hardware Port: Wi-Fi
Device: en1
Ethernet Address: d0:11:e5:79:c5:4f

Hardware Port: Thunderbolt 1
Device: en2
Ethernet Address: 36:fd:e1:09:fc:c0

Hardware Port: Thunderbolt 2
Device: en3
Ethernet Address: 36:fd:e1:09:fc:c4

Hardware Port: Thunderbolt 4
Device: en4
Ethernet Address: 36:fd:e1:09:fc:cc

VLAN Configurations
===================

瞬间冲刷全网 DNS 缓存

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

🧪 验证网络

现在，拔掉再重新插一下你的以太网网线，让它亮起绿灯。然后再次在终端测试：
该步骤不可省略，有时就是这步没有操作

ping -c 3 baidu.com

dig @223.5.5.5 www.baidu.com

只要 ping 能够通，你的系统网络就彻底复活了！

Mac 本地网络配置优化方案

2026-06-20T00:00:00+00:00

软件搭配

SwitchHosts
AdguardHome ： https://github.com/AdguardTeam/AdGuardHome#automated-install-linux-and-mac
LittleSnitch

# 打印出到底是哪个进程在占用 53 端口
sudo lsof -i :53 -P

特性 / 维度	💻 SwitchHosts	🛡️ AdGuard Home	🧱 Little Snitch
软件定位	本地 `hosts` 文件快捷管理工具	全局 DNS 拦截与隐私防火墙	macOS 专用的应用级网络防火墙
主要应用场景	* 后端/前端开发本地环境切换 * 简单的域名静态重定向（如 `127.0.0.1 myproject.test`） * 手动拉取固定的阻断列表	* 局域网/全机全局去广告与恶意追踪拦截 * 屏蔽恶劣高频设备心跳包 * 自建加密 DNS 服务器	* 监控单个软件的联网行为 * 阻止特定 App 后台偷偷上传隐私或心跳包 * 发现并拦截未授权的入站/出站连接
工作机制	系统文件层：通过直接修改 macOS 系统的 `/etc/hosts` 文件，在系统发起网络请求的第一步（DNS 解析前）强行指定域名的 IP。	DNS 层：作为本地的“域名翻译官”。当软件请求域名时，如果是黑名单域名，直接返回空 IP（`0.0.0.0`），在解析阶段将其阻断。	系统内核/网络扩展层：接管 macOS 的网络驱动。不管域名怎么解析，它直接监控哪个进程（Process）在往哪个 IP/域名发包，属于 IP/端口拦截。
使用方法 (如何配置维护)	1. 手动添加规则（如 `0.0.0.0 bad-telemetry.com`）。 2. 支持配置远程 URL 定时刷新（但不支持复杂的 AdGuard 过滤语法）。	1. 配置上游加密 DNS。 2. 在界面中添加支持正则、通配符的动态 DNS 黑白名单。 3. 自动 24 小时后台静默维护。	1. 运行时采用“交互模式”：有软件联网时弹窗询问“允许”或“拒绝”。 2. 可以在规则面板里针对特定 App 封杀特定域名或端口。
拦截颗粒度	最粗：只能精确匹配一个域名，不支持 `*.com` 这种泛解析，无法拦截特定端口。	中等：可以支持通配符和正则表达式（如 `
系统资源占用	极低（只在切换文件时写入，日常运行几乎不占 CPU/内存）。	较低（作为一个轻量级后台服务，常驻处理 DNS 请求）。	中等（因为要实时审计网卡上每一个进出的数据包，对 CPU 会有一定常驻开销）。

6.16 – 6.22 周计划

2026-06-16T00:00:00+00:00

待办

规则引擎单元测试

@start 2026-06-16 @due 2026-06-18 @priority 4 @labels blue, purple

parseMarkdown 覆盖全部指令
serializeMarkdown 往返无损

编写 kanban-rules.js 的解析与序列化测试用例。

映射说明文档

@due 2026-06-17 @priority 3 @labels green

补充颜色名对照表
增加边界情况说明

见 content/kanban/kanban-mapping.md。

列表进度条样式

@due 2026-06-19 @priority 3 @labels orange

待办 > 3 全红
加权进度公式
图标 + 星级元信息

进行中

看板明细页 UI

@start 2026-06-16 @due 2026-06-20 @priority 5 @labels yellow, blue @bg #FFF8E1 @top orange

Trello 多列布局
拖拽跨列
锁定 / 解锁

参考 Trello 列 + 卡片顶栏色；标签仅参与权重计算。

同步回写 Codeberg

@due 2026-06-21 @priority 4 @labels sky @top sky

读取 raw markdown
PUT 更新 content/kanban 路径

Nanolog 功能公告

@due 2026-06-22 @priority 2 @labels pink

东八区时间
附映射文档链接

已完成

需求与目录结构

@priority 3 @labels green

看板 Markdown 统一放在 content/kanban/
一级标题 = 列表，二级 = 卡片

article / nanolog 结构对齐

@priority 2 @labels lime

列表 + 明细模板分离
Edit Post / ReDeplog 链接

资源

开发环境与权限

@start 2026-06-16 @priority 2

Zola 本地 build --force
Codeberg 仓库写入权限

content/kanban/ 目录、ReDeplog 流水线。

参考素材

@priority 1

article_details 图标行
Trello 列布局截图

目标

完成后：周计划可视化管理

@priority 5 @goal complete

列表页一眼看清加权进度
明细页拖拽预览 + Edit Post 回写

实现 Trello 式五列看板，替代纯 Markdown 表格维护。

未完成：进度失控与失效

@priority 4 @goal risk

待办堆积超过 3 条
长期不更新周计划

列表页标红警示；周计划失去追踪意义，部署与开发节奏脱节。

Zsh Autocomplete DIY

2026-06-10T00:00:00+00:00

契机：zsh 智能提示和 BSH 两个都想要，但是不兼容， Gemini 推荐 zsh-autocomplete插件，简单尝试下，果断切换问题：默认zsh智能补全自带的，需手动添加 homebrew中的zsh补全文件，自定义的cli命令/函数的智能补全方案的尝试主要集中和常用的就是自定义函数如何进行加载

该文件提前加载进来，补充 _cs_completion和 compdef _cs_completion cs即可

#2026年06月10日
# 功能： 防爆折行、严选护眼相位、哈希去重消费，融入了现代化的实时补全系统
function cs() {
    local fortune_dir="$HOME/00Fortunes/bin"
    local src_dir="$HOME/00Fortunes/src"  # 新增：源码目录变量
    local pool_file="$fortune_dir/.fortune_hash_pool"
    local map_file="$fortune_dir/.fortune_hash_map"
    local temp_output="$fortune_dir/.fortune_current"

    # =================================================================
    # ✨ 新增参数解析：支持 --edit 参数跳转
    # =================================================================
    if [[ "$1" == "--edit" ]]; then
        if [[ -d "$src_dir" ]]; then
            echo "📂 [词库编辑]: 正在前往源码目录..."
            cd "$src_dir" || return 1
        else
            echo "🚨 [路径错误]: 未找到源码目录 $src_dir，正在为你创建..."
            mkdir -p "$src_dir" && cd "$src_dir" || return 1
        fi
        return 0
    elif [[ -n "$1" ]]; then
        # 如果输入了其他不认识的参数，给予友好提示
        echo "💡 [使用提示]:
        cs         - 随机读取一条未读格言 (彩虹小牛)
        cs --edit  - 快速跳转至词库源码目录进行编辑"
        return 1
    fi

    # =================================================================
    # ✨ 严选护眼相位池
    # =================================================================
    local eye_safe_phases=(30 45 60 15 135 150 165 315 330)
    local random_idx=$(( (RANDOM % ${#eye_safe_phases[@]}) + 1 ))
    local chosen_phase=${eye_safe_phases[$random_idx]}

    local md5_cmd="md5"
    ! command -v md5 &>/dev/null && md5_cmd="md5sum"

    # =================================================================
    # 逻辑 1：桶初始化
    # =================================================================
    if [[ ! -f "$pool_file" || ! -s "$pool_file" || ! -f "$map_file" || ! -s "$map_file" ]]; then
        echo "🔄 [哈希重置]: 正在为你的精美词库建立全量唯一哈希索引池..."
        : > "$map_file"
        : > "$pool_file"

        local raw_all=""
        for f in "$fortune_dir"/*; do
            if [[ -f "$f" && "${f:t}" != *.dat && "${f:t}" != .* && "${f:t}" != *.tmp && "${f:t}" != *.pool && "${f:t}" != *.map ]]; then
                raw_all+="$(cat "$f" | tr -d '\r')\n%\n"
            fi
        done

        echo "$raw_all" | awk '
            BEGIN { RS="\n%\n"; block="" }
            {
                clean_block = $0;
                gsub(/^[ \t\n]+|[ \t\n]+$/, "", clean_block);
                if (clean_block != "" && clean_block != "%") {
                    print "---BLOCK_START---"
                    print $0
                    print "---BLOCK_END---"
                }
            }
        ' | while IFS= read -r line; do
            if [[ "$line" == "---BLOCK_START---" ]]; then
                block_content=""
            elif [[ "$line" == "---BLOCK_END---" ]]; then
                local my_hash=$(echo -n "$block_content" | $md5_cmd | awk '{print $1}')
                echo "==HASH:${my_hash}==" >> "$map_file"
                echo "$block_content" >> "$map_file"
                echo "%%" >> "$map_file"
                echo "$my_hash" >> "${pool_file}.raw"
            else
                [[ -z "$block_content" ]] && block_content="$line" || block_content+=$'\n'"$line"
            fi
        done

        if [[ -f "${pool_file}.raw" ]]; then
            shuf "${pool_file}.raw" > "$pool_file"
            : > "${pool_file}.raw"
        fi
    fi

    # =================================================================
    # 逻辑 2：精准消费
    # =================================================================
    local target_hash=$(head -n 1 "$pool_file" | tr -d ' \t\r\n')

    if [[ -n "$target_hash" && -f "$map_file" ]]; then
        : > "$temp_output"
        sed -n "/==HASH:${target_hash}==/,/^%%/p" "$map_file" | sed "1d;/\^%%/d" | sed '/^%%/d' > "$temp_output"

        if [[ -s "$temp_output" ]]; then

            # =========================================================
            # ✨ 【全新护眼抗洪核心】：折行防爆 + 动态方框
            # =========================================================
            (
                # 1. 展开 Tab 键，同时利用 fold 命令限制单行视觉最大显示宽为 90（支持中文智能截断）
                #    这样超长命令会自动换到下一行，绝不会把方框和 lolcat 撑爆！
                local clean_text=$(expand -t 4 "$temp_output" | fold -s -w 90)

                # 2. 动态精准计算截断后的最大列宽
                local max_w=0
                while IFS= read -r line; do
                    local line_w=${(m)#line}
                    (( line_w > max_w )) && max_w=$line_w
                done <<< "$clean_text"

                local padding_x=4
                (( max_w < 24 )) && max_w=24

                echo ""

                # 绘制方框顶部
                printf "  ╭"
                printf '─%.0s' {1..$((max_w + padding_x * 2))}
                printf "╮\n"

                printf "  │"
                printf ' %.0s' {1..$((max_w + padding_x * 2))}
                printf "│\n"

                # 3. 完美包裹折行后的正文
                while IFS= read -r line; do
                    local line_w=${(m)#line}
                    local total_spaces=$((max_w - line_w))

                    printf "  │"
                    printf ' %.0s' {1..$padding_x}
                    printf "%s" "$line"
                    printf ' %.0s' {1..$((total_spaces + padding_x))}
                    printf "│\n"
                done <<< "$clean_text"

                printf "  │"
                printf ' %.0s' {1..$((max_w + padding_x * 2))}
                printf "│\n"

                # 绘制方框底部
                printf "  ╰"
                printf '─%.0s' {1..$((max_w + padding_x * 2))}
                printf "╯\n"
            ) | lolcat -p $chosen_phase -F 0.20 -S 1

            # 4. 灰色小牛独立打印
            echo -e "\033[1;30m         \\   ^__^"
            echo "          \\  (oo)\\_______"
            echo "             (__)\\       )\\/\\"
            echo "                 ||----w |"
            echo "                 ||     ||\033[0m"
            echo ""

            # =========================================================
            # 5. 裁剪哈希桶
            # =========================================================
            local tmp_pool="${pool_file}.tmp"
            tail -n +2 "$pool_file" > "$tmp_pool"
            cat "$tmp_pool" > "$pool_file"
            : > "$tmp_pool"

            # 6. 统计剩余数量
            local remain_count=$(wc -l < "$pool_file" | tr -d ' ')
            echo -e "\033[0;37m📊 [词库统计]: 今日箴言已读。池子里还剩 💡 \033[1;32m$remain_count\033[0;37m 条未读内容。\033[0m"
        else
            fortune "$fortune_dir" | lolcat
        fi
    else
        echo "🚨 [异常触发]: 索引映射发生错位，正在强制重置重洗..."
        : > "$pool_file"
        fortune "$fortune_dir" | lolcat
    fi

    [[ -f "$temp_output" ]] && : > "$temp_output"
}
# ==============================================================================
# ✨ 专属 cs 函数的 Zsh 智能补全脚本（完美适配 zsh-autocomplete / fzf-tab）
# ==============================================================================
_cs_completion() {
    # 核心要点：描述必须紧跟在参数后面的中括号内，不能用冒号分隔！
    # 这样 zsh-autocomplete 的正则引擎才能百分之百解析它是一个合法 Option
    _arguments -s -S \
        '--edit[📂 跳转至词库源码目录进行编辑]'
}

# 注册绑定
compdef _cs_completion cs

Fortune - 适配改造分享

2026-06-06T00:00:00+00:00

fortune 缺陷描述

默认词库不合心意，但可手动维护
纯随机算法，无法保证每条摘录能出现
默认输出文本颜色样式呆板

设计思路

lolcat , cowsay 解决呆板，实现彩虹色输出
fortune 参数可指定词库，但无记忆统计功能
哈希桶思路解决记忆
编写Makefile实现自动编译并生成哈希文件
编写Function 适配
词库直接由坚果云同步，解决备份不丢失问题

最初我只描述实现效果，没有参与逻辑设计，被动测试和把控；
随机生成的思路一眼假或者说是似是而非，总是有漏洞，所以 AI还需要发展，需要设计者参与核心思路的设计和主动把控；
AI作为解放代码和快速编写还是很不错的，快速生成，简单审核内容和逻辑是否偏离

使用哈希一次性将所有内容哈希化，不依赖原生fortune直接调用，因为它是纯随机的，通过哈希可以主动校验

微调lolcat 避免彩虹干扰眼睛

微调 cowsay对中文，过长文本的排版错乱限制，手动动态生成边框
统计打印输出剩余可读数量
初次AI使用 rm命令，我系统 rm已被safely-rm接管，除非手动指出绝对路径，但本身的思路就是不对，只需要将文件内容清空而非删除再重建

安装

基础包

仅安装这一个其余通过脚本来满足个性化现代改造

brew install fortune #提供基础fortune设置词库和解析词库的能力

验证：是否安装成功

❯ brew info fortune                                                                                                                   ─╯
==> fortune ✔: stable 9708 (bottled)
Infamous electronic fortune-cookie generator
https://www.ibiblio.org/pub/linux/games/amusements/fortune/!INDEX.html
Installed (on request)
From: https://mirrors.ustc.edu.cn/homebrew-core.git/Formula/f/fortune.rb
License: BSD-4-Clause-UC
==> Installed Kegs and Versions
fortune ✔ 9708 (85 files, 2.6MB) [Linked]

创建个人词库

创建词库根文件夹，示例提供的是00Fortunes 下方提供目录结构 bin 存储编译结果， Makefile为编译工具， src存放词库因为 src 文件走坚果云同步所以是引用文件夹，也一并补充具体内容

❯ tree                                                                                                                                ─╯
.
├── bin
│   ├── cli_tools
│   ├── cli_tools.dat
│   ├── micro_think
│   └── micro_think.dat
├── Makefile
└── src -> $HOME/Library/CloudStorage/坚果云/src


❯ tree                                                        
.
├── cli_tools
└── micro_think

创建函数脚本

建议创建独立的zsh脚本文件，引入到你的配置文件中或者直接复制粘贴到你的配置文件（.zshrc/.bashrc)中
默认函数名称 cs 和 fortune-sync 可修改

# 2026年06月06日
# 打印输出函数 
# fortune_cs.zsh文件形式保存
function cs() {
    local fortune_dir="$HOME/00Fortunes/bin"
    local pool_file="$fortune_dir/.fortune_hash_pool"
    local map_file="$fortune_dir/.fortune_hash_map"
    local temp_output="$fortune_dir/.fortune_current"

    # =================================================================
    # ✨ 严选护眼相位池
    # =================================================================
    local eye_safe_phases=(30 45 60 15 135 150 165 315 330)
    local random_idx=$(( (RANDOM % ${#eye_safe_phases[@]}) + 1 ))
    local chosen_phase=${eye_safe_phases[$random_idx]}

    local md5_cmd="md5"
    ! command -v md5 &>/dev/null && md5_cmd="md5sum"

    # =================================================================
    # 逻辑 1：桶初始化
    # =================================================================
    if [[ ! -f "$pool_file" || ! -s "$pool_file" || ! -f "$map_file" || ! -s "$map_file" ]]; then
        echo "🔄 [哈希重置]: 正在为你的精美词库建立全量唯一哈希索引池..."
        : > "$map_file"
        : > "$pool_file"

        local raw_all=""
        for f in "$fortune_dir"/*; do
            if [[ -f "$f" && "${f:t}" != *.dat && "${f:t}" != .* && "${f:t}" != *.tmp && "${f:t}" != *.pool && "${f:t}" != *.map ]]; then
                raw_all+="$(cat "$f" | tr -d '\r')\n%\n"
            fi
        done

        echo "$raw_all" | awk '
            BEGIN { RS="\n%\n"; block="" }
            {
                clean_block = $0;
                gsub(/^[ \t\n]+|[ \t\n]+$/, "", clean_block);
                if (clean_block != "" && clean_block != "%") {
                    print "---BLOCK_START---"
                    print $0
                    print "---BLOCK_END---"
                }
            }
        ' | while IFS= read -r line; do
            if [[ "$line" == "---BLOCK_START---" ]]; then
                block_content=""
            elif [[ "$line" == "---BLOCK_END---" ]]; then
                local my_hash=$(echo -n "$block_content" | $md5_cmd | awk '{print $1}')
                echo "==HASH:${my_hash}==" >> "$map_file"
                echo "$block_content" >> "$map_file"
                echo "%%" >> "$map_file"
                echo "$my_hash" >> "${pool_file}.raw"
            else
                [[ -z "$block_content" ]] && block_content="$line" || block_content+=$'\n'"$line"
            fi
        done

        if [[ -f "${pool_file}.raw" ]]; then
            shuf "${pool_file}.raw" > "$pool_file"
            : > "${pool_file}.raw"
        fi
    fi

    # =================================================================
    # 逻辑 2：精准消费
    # =================================================================
    local target_hash=$(head -n 1 "$pool_file" | tr -d ' \t\r\n')

    if [[ -n "$target_hash" && -f "$map_file" ]]; then
        : > "$temp_output"
        sed -n "/==HASH:${target_hash}==/,/^%%/p" "$map_file" | sed "1d;/\^%%/d" | sed '/^%%/d' > "$temp_output"

        if [[ -s "$temp_output" ]]; then

            # =========================================================
            # ✨ 【全新护眼抗洪核心】：折行防爆 + 动态方框
            # =========================================================
            (
                # 1. 展开 Tab 键，同时利用 fold 命令限制单行视觉最大显示宽为 90（支持中文智能截断）
                #    这样超长命令会自动换到下一行，绝不会把方框和 lolcat 撑爆！
                local clean_text=$(expand -t 4 "$temp_output" | fold -s -w 90)

                # 2. 动态精准计算截断后的最大列宽
                local max_w=0
                while IFS= read -r line; do
                    local line_w=${(m)#line}
                    (( line_w > max_w )) && max_w=$line_w
                done <<< "$clean_text"

                local padding_x=4
                (( max_w < 24 )) && max_w=24

                echo ""

                # 绘制方框顶部
                printf "  ╭"
                printf '─%.0s' {1..$((max_w + padding_x * 2))}
                printf "╮\n"

                printf "  │"
                printf ' %.0s' {1..$((max_w + padding_x * 2))}
                printf "│\n"

                # 3. 完美包裹折行后的正文
                while IFS= read -r line; do
                    local line_w=${(m)#line}
                    local total_spaces=$((max_w - line_w))

                    printf "  │"
                    printf ' %.0s' {1..$padding_x}
                    printf "%s" "$line"
                    printf ' %.0s' {1..$((total_spaces + padding_x))}
                    printf "│\n"
                done <<< "$clean_text"

                printf "  │"
                printf ' %.0s' {1..$((max_w + padding_x * 2))}
                printf "│\n"

                # 绘制方框底部
                printf "  ╰"
                printf '─%.0s' {1..$((max_w + padding_x * 2))}
                printf "╯\n"
            ) | lolcat -p $chosen_phase -F 0.20 -S 1

            # 4. 灰色小牛独立打印
            echo -e "\033[1;30m         \\   ^__^"
            echo "          \\  (oo)\\_______"
            echo "             (__)\\       )\\/\\"
            echo "                 ||----w |"
            echo "                 ||     ||\033[0m"
            echo ""

            # =========================================================
            # 5. 裁剪哈希桶
            # =========================================================
            local tmp_pool="${pool_file}.tmp"
            tail -n +2 "$pool_file" > "$tmp_pool"
            cat "$tmp_pool" > "$pool_file"
            : > "$tmp_pool"

            # 6. 统计剩余数量
            local remain_count=$(wc -l < "$pool_file" | tr -d ' ')
            echo -e "\033[0;37m📊 [词库统计]: 今日箴言已读。池子里还剩 💡 \033[1;32m$remain_count\033[0;37m 条未读内容。\033[0m"
        else
            fortune "$fortune_dir" | lolcat
        fi
    else
        echo "🚨 [异常触发]: 索引映射发生错位，正在强制重置重洗..."
        : > "$pool_file"
        fortune "$fortune_dir" | lolcat
    fi

    [[ -f "$temp_output" ]] && : > "$temp_output"
}


# 2026年06月06日
# 功能清单：
# 1. 编译生成 bat源词库
# 2. 清理既往中间池， 保证 源词库 与 中间池一致的问题
# Makefile 文件 


# 2026年06月06日
# 功能清单：
# 1. 编译生成 fortune 专用 .dat 源词库
# 2. 生成最新哈希文件
# 路径定义
SRC_DIR = src
BIN_DIR = bin
STRFILE = /opt/homebrew/bin/strfile

# 【核心升级】定义最新的哈希池与哈希映射表文件路径
HASH_POOL = $(BIN_DIR)/.fortune_hash_pool
HASH_MAP  = $(BIN_DIR)/.fortune_hash_map

# 获取 src 下所有没有后缀的文件名
SOURCES = $(wildcard $(SRC_DIR)/*)
# 定义目标文件：每个源文件在 bin 目录下都要有一个对应的文本和 .dat 文件
TARGET_TEXTS = $(patsubst $(SRC_DIR)/%, $(BIN_DIR)/%, $(SOURCES))
TARGET_DATS = $(patsubst $(SRC_DIR)/%, $(BIN_DIR)/%.dat, $(SOURCES))

all: $(BIN_DIR) $(TARGET_DATS)

# 创建 bin 目录
$(BIN_DIR):
	mkdir -p $(BIN_DIR)

# 规则：当 src 下的文本更新时，同步到 bin 并生成 .dat
$(BIN_DIR)/%.dat: $(SRC_DIR)/%
	@echo "🛠️  Processing: $<"
	@cp $< $(BIN_DIR)/$*
	@$(STRFILE) -s $(BIN_DIR)/$* $(BIN_DIR)/$*.dat
	# 【数据一致性联动】只要有任何源文件更新，使用原生系统命令绝对路径强刷哈希桶与字典
	# 绕过 rm-safely 的物理删除，迫使 cs 函数在下次运行时重新全量生成哈希字典并打散洗牌
	@/bin/rm -f $(HASH_POOL) $(HASH_MAP)

clean:
	rm -rf $(BIN_DIR)

.PHONY: all clean

# fortune-sync.zsh独立文件形式保存
fortune-sync () {
	(
		cd "$HOME/00Fortunes" && make
	)
}

使用

词库维护 `fortun-sync`

前置安装工作完成，并重启刷新配置文件；样例词库 cli_tools;
每条以%作为分隔符
编辑完成后 fortune-sync 生成词库文件

rm-safely更安全
rm --help  #查看帮助
rmbuild *  # 清空build编译输出目录
rm --list-trash # 列出
rm --empty-trash #清空
/bin/rm -f  #系统内置rm命令地址
%
ccache -z  #重置统计
ccache -s  #查看统计
%
container start -i gcc16    # 交互模式进入容器
%
brewup   #批量更新工具链
%
mo optimize   # 硬件优化
%
j music #跳转已进入的目录
autojump 底层是这个，后续有更复杂需求 ，编写函数
%
fortune  --- 个人谮言 /备忘录 /Users/songhoujin/00Fortunes/src
fortune-sync      #编辑更新完 同步更新生成最新哈希值
cs 基于哈希桶的带有记忆功能的fortune函数
%
Little Snitch - 网络出关设置;
%
Object-See
BlockBlock - 检测持久化拦截
KnockKnock - 恶意软件检测
%
p10k configure # 自带的配置流程
%
cloc - 静态代码信息打印输出
%

打印输出 `cs`

直接输入cs 即可查看效果

知识蒸馏整理

通过编写自定义脚本，和AI交互中，学到哪些新的知识和技能？

查看 man 帮助手册操作

默认使用 less 文本阅读器所以man 命令的快捷键和 less 一致； 基础翻页

f（Forward) 向下翻一页； Sace, PageDown
b (Backward) 向上翻一页； PageUp
d (Down) 向下翻半页；
u (Up) 向上翻半页；

微调滚行

j :向下滚动一行
k :向上滚动一行

瞬间跃迁

g: 手册顶部
G:手册底部

强力搜索

/+关键字 ，向下搜索内容， eg: /---stream ，高亮所有匹配项
？+关键字， 向上搜索内容
n(Next)：配合搜索使用， 跳转到下一个高亮关键字
N（Shift+n) 配合搜索使用， 反向跳转上一个高亮关键字

退出 q(QUit) 退出手册，切回控制台

bat , cat 获取文件内容
pbcopy 将管道内容粘贴到剪切板中
tree 打印输出目录结构
cloc 代码行统计工具

One

2026-06-05T00:00:00+00:00

墨墨记单词周进度和安排

One

2026-06-05T00:00:00+00:00

测试

TL;DR: Fun game.

As you may know, I occasionally play games, which is shocking in itself, but even more shocking is that I’ve never blogged about it, so let’s change that! (well, I just don’t know what to blog about xD)

测试

Teardown is a game released back in 2022, but I have played the early access version released in 2020 on YouTube (as in, I watched let’s plays). Recently I decided to replay it, and it’s been pretty fun, the process of

测试的

carefully coming up with an optimal route and then executing it in under 60 seconds is pretty entertaining. My little brother seems to enjoy watching all this happen as well.

CMake 学习

2026-06-05T00:00:00+00:00

官方文档和 Professional CMake: A Practical Guide 是第一信息源本地仓库已建立 2026-06-25 开始到月底30号共计 5天，搞定它时间足够充裕

一天速通 CMake 的“核心困难“不在语法，而在心智模型。官方文档是参考手册而不是教程，按顺序读很容易陷入“每个命令都认识、但就是不会搭项目“的状态。核心困难点大致如下：三阶段心智模型（最大的坎） CMake 不是“怎么编译“的脚本，而是“配置 → 生成 → 构建“三阶段：cmake -S . -B build 只做 configure + generate，生成 Ninja/Makefile 后才真正编译。所有变量和条件判断都在配置期求值，没有“运行时“概念。不理解这一点，后面所有现象都会显得“莫名其妙“。

新旧两种范式并存，必须只学新的旧风格是改全局变量（include_directories、add_definitions、CMAKE_CXX_FLAGS），新风格（Modern CMake）是以 target 为中心：target_include_directories、target_link_libraries、target_compile_features，靠 PUBLIC / PRIVATE / INTERFACE 传播依赖。官方文档里两种风格混着写，网上旧答案更是遍地旧风格。困难在于：你要主动忽略旧范式，否则会学出“能跑但一扩展就崩“的项目。

生成器表达式（Generator Expressions） $<BUILD_INTERFACE:…>、$<TARGET_PROPERTY:…> 这类 $<…> 是“生成期“才求值的语法，等于又加了一层求值时机。写库的导出、条件编译、路径传播时绕不开，是新手最容易卡住的地方。

依赖管理的丛林 find_package（MODULE vs CONFIG 模式）、FetchContent、add_subdirectory、ExternalProject、imported target 概念。真实项目 70% 的 CMake 时间都花在这里。一天内只掌握 find_package + FetchContent 两个就够用，其余的知道存在即可。

官方文档是“字典“，不是“路线图“ 文档按命令/变量/属性组织，读了不会形成“项目该怎么分层、目录怎么放、哪些用 target 属性哪些用 cache 变量“的结构感。速通的关键是对照真实小项目读，而不是线性读文档。

调试体验差报错往往信息量低（“No rule to make target”、policy 警告、IMPORTED_LOCATION 未设置）。你得会 cmake –trace、message() 打日志、–debug-output，否则卡住时只能瞎猜。

One

2026-06-05T00:00:00+00:00

测试

TL;DR: Fun game.

测试

测试的

carefully coming up with an optimal route and then executing it in under 60 seconds is pretty entertaining. My little brother seems to enjoy watching all this happen as well.

2026-06-04T05:14:12+00:00

Done

归档功能 - 适配多分类下的综合展示跳转
移植 Blog - Article 核心功能可用状态
尝试产品展示页面浮动特效失败

Undo

模板数据未移除
电子屏的ASCII 有软件进行生成

Doing

今天就动手学习 CMake

2026-06-03T10:02:29+00:00

碎碎念

目前环境网络波动，容易损耗镜面屏电容寿命，心疼。购买华为UPS800W(间接限定后续服务器的瓦数)

目前基础后端服务搭载在公网上，流水线借助GitHub(编译后清空源码信息) 后面使用自有服务器；暂定的DIY方案

🛠 EPYC 7502 编译服务器搭建方案📊 硬件配置与预算清单部件推荐型号/规格价格 (元)选型理由CPUAMD EPYC 7502 (正代正式版)~100032核64线程，并行编译的绝对主力，Zen2 架构。主板永擎 (Asrock Rack) ROMED8-2T 或超微 H12SSL-i~900SP3插槽（支持7002系列）。自带 IPMI 远程管理，带双千兆或万兆网口。内存DDR4 2666MHz ECC REG 16G × 4 (共64G)~280C++ 编译大型项目非常吃内存，先上 4 根跑满 4 通道，后期可补满 8 根。系统/编译盘三星 PM9A1 1TB 或致态 TiPro7000 1TB~450编译时会产生密集的 I/O 读写，必须用高质量、高性能的 PCIe 4.0 NVMe 固态。散热器拓普龙/超微 SP3 4热管/6热管风冷~120专为服务器 LGA4094/SP3 接口设计的散热器。电源长城巨龙 1250W 或海韵/全汉 750W 品牌二手~150 - 2007502 的 TDP 是 180W，满载编译加上主板内存，额定 650W - 750W 比较稳妥。机箱普通 ATX 兼容大机箱 / 4U 工业机箱~80只要能塞下 ATX 主板和服务器散热器即可。总计约 2980 元万元以内无敌的编译生产力工具

💡 方案深度解析与注意事项

为什么主板这么贵？（服务器主板的灵魂：IPMI）服务器主板（如永擎、超微）自带一颗特殊的芯片叫 IPMI（远程管理卡）。

不需要显卡：这颗 CPU 没有核显，主板自带了基础显示芯片，你甚至不需要插独立显卡。

盲操远程：只要插上电源和网线，你在你日常用的笔记本上，通过浏览器输入服务器的 IP 地址，就能远程看屏幕、进 BIOS、挂载本地 ISO 镜像重装 Linux 系统、远程开断电。这才是纯正的服务器体验。

为什么选 16G × 4 内存？ C++ 并行编译的黄金法则是：每个编译线程（Thread）至少分配 2GB - 4GB 的内存。你现在有 64 个线程：

如果只给 16G/32G 内存，当 make -j64 全开时，内存会瞬间爆掉，导致触发 Linux 的 OOM Killer 机制直接崩溃。

64G 内存是这颗 32 核处理器的及格线。

网络与存储扩展这类工业级主板上通常带有 SlimSAS 或 Oculink 接口，以及大量的 PCIe 插槽。这意味着，如果你以后想让它兼顾 NAS 存储功能，你不需要买任何转换卡，直接可以挂载 8-16 块大容量机械硬盘，或者插满 4 块 NVMe 固态硬盘做高速编译缓存。

选项 A：AMD EPYC 7502（推荐：更先进、带宽高）核心参数： 32核 64线程，基础频率 2.5GHz，加速 3.3GHz。

CPU价格： ~1000 元（随着 7002/7003 系列退役，目前性价比极高）。

为什么选它：它是 Zen 2 架构（7nm），单核性能比老一代大涨。更恐怖的是它支持 8通道 DDR4 内存。C++ 编译在链接（Linking）阶段需要极高的内存吞吐，8通道是无敌的存在。

围绕 AMD EPYC 7502 这颗 CPU 搭建的服务器，整机的功耗（瓦数）需要分三个场景来看：待机功耗、日常轻载功耗、以及最关键的多核全满载编译功耗。以下是具体的瓦数测算和电源选型建议：📊 整机功耗（瓦数）实测预估运行场景CPU 自身功耗整机总功耗（含主板/内存/SSD）10小时电费估算 (按0.6元/度)1. 远程待机 (挂机/写代码不编译)~30W - 40W约 70W - 90W~0.5 元2. 日常轻载 (跑几个Docker/轻量运行)~50W - 60W约 100W - 120W~0.7 元3. C++ 多核全满载编译 (make -j64)180W (满TDP)约 240W - 260W~1.5 元

总计 3000 元;

Third

2026-06-03T00:00:00+00:00

一、彻底搞懂 paginator 与 section在 Zola 中，section 和 paginator 是两个最核心的上下文对象，它们决定了数据如何流向模板。1. 什么是 section.pages？是什么：它代表当前目录（Section）下包含的所有文章（Pages）的集合（一个数组）。判定与生效机制：结构判定：无论是单文件 hello.md，还是文件夹包裹的 hello/index.md，只要它们躺在 content/01Write_blog/ 目录下，Zola 就会把它们识别为该目录的 Page。致命的过滤判定（为什么你之前会失踪）：Zola 默认是按照时间（Date）对 section.pages 进行排序的。如果你的 .md 文件中：没有写 date 字段。或者 date 格式不规范。或者你没有在 _index.md 中显式指定 sort_by = “date”。Zola 在渲染 section.pages 时，可能会因为排序混乱或未发布（如误识别为草稿），导致计算出的 section.pages | length 变成 0。2. 什么是 paginator.pages？是什么：它是当前分页切片后的文章集合（比如第 1 页的 10 篇文章）。判定与生效机制：它不会自动产生。只有当你在该目录的 _index.md 中，显式地配置了 paginate_by = 数字时，Zola 才会实例化 paginator 对象。一旦开启，section.pages 的控制权就会移交给 paginator.pages。📊 它们在模板中的各自作用对象属性存在条件主要作用section.pages只要目录下有有效文章就有值用来不分页地一次性循环输出所有文章。paginator.pages必须在 _index.md 中配置 paginate_by用来做翻页导航（上一页/下一页），只展示当前页内容。

在 Zola 中，section.pages 默认只能抓取到当前目录下直属的文章。比如，你的归档页面在 content/archives/_index.md，如果你把博客都放在 content/01Write_blog/ 下，由于它们是平级（兄弟）关系，或者是完全独立的树枝，archives 页面去读取 section.pages 时，拿到的结果必然是空的（长度为 0），因此它什么都渲染不出来。

Third

2026-06-03T00:00:00+00:00

2026-06-01T23:05:22+00:00

2026年06月02日

修复

修复 Nanolog Edit编辑不在源代码的问题 (直接编辑源码,但不立即推送更新到公开仓库)
重置 Nanolog 内容, 书写自己的网站维护内容

细节打磨

博客网页 Nanolog处添加 ReDeplog 按钮，同 Edit Post 一致（编辑源码，重编译推送）已添加
定时发送邮件提醒自己手动更新博客待添加

开发进度

Done

源码推送在Codeberg, 网站15天后自动拉取编译更新网站github.io ; 实现源码/网站分离 (优点: 高频推送隐私信息剥离,后续可加装密码解锁网页; 缺点: 构建与推送分离需单独管理)
拆分一级板块:Read, Write,Share,Project, Site Dev Log ; 及其二级分类
Nanolog 模块开发完成 . 处于可用状态 (展示,可直接 Edit)
Blog模块未完成(需编写 index.html 及 blog.html 2个模板文件)
Basb模块开发完成,并处于可用状态, 暂定该模块用来进行周记录 , 考虑将 EditPost/ReDeplog功能同步过去 ;

UnDo

熟悉该主题文件的MD 博客编辑模式(该模式精细,具有观赏性)
搜索功能待开发(index.html 自有功能)
密码封锁爬虫和无关访客 (该模块优先开发 ,最小可用方案推出,后续迭代)
在Nanolog 中添加固定格式：约定更新时间，考虑添加网页倒计时，并提前1小时发送邮件提醒给自己该功能可考虑
Codeberg 中补充 CI/CD 流水线, 该功能还是必要的;
后续添加后端服务 (C++编写核心模块, Go/.NET 进行Web后端API开发) 在 Vercel 或者 Cloudflare 中进行部署

Doing

Blog 模块正在开发调试中

细节补充

完整流程阐述:

本地拉取私有源码仓库 Codeberg, 更新构建成功后推送(Zed 编辑模板, Obsidian 编辑 MD); 手动触发公开博客网站Github.io仓库workflow拉取编译最新源码; 菜单栏Deplog 提醒构建推送状态; NetNewWire 对网站进行RSS订阅

熟悉了解 Zola功能及 Ametrine主题功能
对其他博主博客有趣基础刚性功能务必添加,但柔和功能考虑添加
补充 CICD 流水线, 虽然本地是编译成功, github跨网站拉取codeberg 私有库也成功, 但还是有必要进行构建cicd流水线的熟悉流水线搭建,还有保证环境搭建的流程能够复现出来 ,例如拉取主题仓库,更新依赖git模块, mac环境模拟zola 等细节 ; 该功能属于基础自动化功能,一旦实现,后续受益
评论区? 自认为有价值适合分享的文章, 我会主动发布到 HackerNew 上的; 我个人不加载和存储评论数据, 使用HackerNew 足够了;

常用命令

git pull    # 拉取最新代码，因为Nanolog 存在线上Edit Post，所以 本地修改需谨慎，优先拉取最新代码

git add .   # 添加所有修改的文件
git status  # 查看修改状态
git commit -m "update nanolog"  # 提交修改
git push    # 推送修改

#上述操作 均是在本地编辑Codeberg仓库 ，与 公开网站Github无关
# 若基础信息更改， github 的编译流水线yml文件需同步修改，否则拉取编译失败

约定/预订下次更新时间

本周六

2026年5月广告与产品收入对账单

2026-05-31T00:00:00+00:00

这里是三级明细《5月账单》的内容。

2026年5月广告与产品收入对账单

2026-05-31T00:00:00+00:00

这里是三级明细《5月账单》的内容。

Git 常用命令集合

2026-05-30T00:00:00+00:00

放弃本地某文件修改

❯ gst                                                                                                                                                                         ─╯
 m themes/ametrine
 M zola.toml

git submodule update --init --recursive --checkout --force themes/ametrine

作用：这行命令会强制（–force）将 themes/ametrine 子模块恢复到当前主项目 master 分支所记录的那个精确的 Commit 节点，直接抹去本地所有未提交的修改

cd themes/ametrine
git reset --hard HEAD
git clean -fd

操作后，

❯ git status                                                                                                                                                                  ─╯
Found existing alias for "git status". You should use: "gst"
Found existing git alias for "status". You should use: "git st"
 M zola.toml

Gemini: Exe

2026-05-30T00:00:00+00:00

The Rewrite

The first rewrite attempt happened pretty much right after I published

自制 Zola 效率插件高效发布博客

2026-05-30T00:00:00+00:00

这里是三级明细《Zola插件》的内容。

自制 Zola 效率插件高效发布博客

2026-05-30T00:00:00+00:00

这里是三级明细《Zola插件》的内容。

        Reply    18

ShioWSX 2024 年 10 月 18 日建议是 AMD 的 9950X （预算不够就 7950X ） 64G ddr5 6400 1 、上半年我做过测试笔记本的 6800H 7950X 双路 6133 以及两个云服务器（ 32c 64G 配置）一个 epyc 一个三代铂金志强 2 、综合下来 7950X 是最快的，我编译的是 Linux 5.10 和 mysql 5.8 全量编译, 3 、C++工程模版展开以及内联多是比较吃 cpu 的，C 系的工程相对开销小一点 4 、最关键的是最后的链接环节基本上是单核的，9950X 比服务器的 U 单核强的不是一点 5 、最后可以先上个云服务试一下，反正可以按小时计费，配置拉满测试一天也花不了多少，可以看看 Geekbench 多核跑分榜单 6 、如果项目确实很大，且长时间编译的话，得上服务器的 ECC 大内存了，毕竟家用只能上 128G 就到顶了

一步到位

C++编译这个条件足够使用了；

Gemini: Exploring the Cozy World of Capsules and Space

2026-05-20T00:00:00+00:00

Backstory

It’s been about 4 months since the last post, all this time I’ve been procrastinating, doing some side projects, learning Blender, and… rewriting my website from scratch!

Zola Blog Site build deploy share

2025-10-04T00:00:00+00:00

数据流向模板细节

分页和时间排序必须选一个；一、彻底搞懂 paginator 与 section在 Zola 中，section 和 paginator 是两个最核心的上下文对象，它们决定了数据如何流向模板。1. 什么是 section.pages？是什么：它代表当前目录（Section）下包含的所有文章（Pages）的集合（一个数组）。判定与生效机制：结构判定：无论是单文件 hello.md，还是文件夹包裹的 hello/index.md，只要它们躺在 content/01Write_blog/ 目录下，Zola 就会把它们识别为该目录的 Page。致命的过滤判定（为什么你之前会失踪）：Zola 默认是按照时间（Date）对 section.pages 进行排序的。如果你的 .md 文件中：没有写 date 字段。或者 date 格式不规范。或者你没有在 _index.md 中显式指定 sort_by = “date”。Zola 在渲染 section.pages 时，可能会因为排序混乱或未发布（如误识别为草稿），导致计算出的 section.pages | length 变成 0。2. 什么是 paginator.pages？是什么：它是当前分页切片后的文章集合（比如第 1 页的 10 篇文章）。判定与生效机制：它不会自动产生。只有当你在该目录的 _index.md 中，显式地配置了 paginate_by = 数字时，Zola 才会实例化 paginator 对象。一旦开启，section.pages 的控制权就会移交给 paginator.pages。📊 它们在模板中的各自作用对象属性存在条件主要作用section.pages只要目录下有有效文章就有值用来不分页地一次性循环输出所有文章。paginator.pages必须在 _index.md 中配置 paginate_by用来做翻页导航（上一页/下一页），只展示当前页内容。

补充

后面要抓取补充主题开发者的文档信息；

常见媒体的样式写法整理

仓库名称 / 作者	建议重点看什么	学习价值
`fmtlib/fmt` (Formatting Library)	• `CMakeLists.txt` 的纯 Target 设计 • C++20 `constexpr` 编译期字符串解析与元编程	C++ 工业界第一标杆。代码极其干净，是学习现代 CMake、符号隐藏（`-fvisibility=hidden`）和现代 C++ 模板的最佳范本。
`quill` (Quill Asynchronous Logger)	• 低延迟环形缓冲区（RingBuffer）设计 • C++20 强类型与无锁队列（Lock-free Queue）	高频/量化级别的通用日志库。展示了如何用现代化 C++ 榨干 CPU 性能，且工程结构非常规整。
`velox` (Meta 开源 C++ 执行引擎)	• 大型项目的 `CMakePresets.json` 与模块拆分 • 内存分配器（Arena/Memory Pool）与矢量化计算	Meta 级别的现代 C++ 大体量工程。展示了现代中大型 C++ 基础设施是如何组织依赖、处理异常和利用矢量化 (SIMD) 的。
`glaze` (Glaze JSON/Serialization)	• C++20 Compile-time Reflection（编译期反射） • 极简现代 C++ 接口设计，完全无宏设计	现代 C++ 模板与反射的巅峰之作。看它如何完全抛弃旧式的反射和宏，做到超越 C 的解析性能。

路径	说明
`scripts/encrypt-content.mjs`	构建前加密同步
`scripts/post-build.mjs`	构建后 feed / 搜索过滤
`scripts/verify-kanban-build.mjs`	看板产物校验
`scripts/encryption-lib.mjs`	加密与 feed 处理共享库
`scripts/serve-with-ranges.mjs`	可选：带 byte-range 的本地静态服务（非 `dev.sh` 默认流程）

配置	实际加载
页面 FM 含 `scripts`	`kanban-rules.js` + `kanban-board.js` ✓
页面 FM 无 `scripts`	section 仅 `kanban-rules.js` + `kanban-list.js` ✗ 缺 board.js

文件	作用
`content/kanban/`	看板 Markdown 唯一维护目录
`static/js/kanban-rules.js`	解析 / 序列化规则引擎
`static/js/kanban-board.js`	看板 UI、锁定、拖拽、Edit Post 缓冲写入
`static/js/kanban-list.js`	列表页剩余天数、动态刷新进度
`static/js/kanban-editor.js`	GUI 编辑器：表单生成、剪贴板复制、创建 / 修改流程提示
`templates/partials/kanban_editor.html`	编辑器模态框
`content/kanban/_edit-buffer.md`	Edit Post 前的 Markdown 缓冲文件
`templates/kanban.html`	周计划明细（Trello 风格）
`templates/kanban_list.html`	周计划列表

Rocky‘s Blog

求真 求实

RSS/Atom 订阅只见部分文章、刷不出新文：根因定位与修复方案

概述

一、现象

二、根因定位

2.1 站点级 feed 从未生成（主因）

2.2 实际存在的只有「分板块」feed，自动发现只暴露 2 个板块

2.3 被当作「Blog」的 01Write_blog 板块几乎没有文章

2.4 新文章恰好都发在「没被订阅」的板块

2.5 加密文章被主动剔除

三、修复方案

方案 A（推荐，一步到位）：生成全站 feed

方案 B：扩充自动发现的板块

方案 C（订阅者侧临时办法）

四、注意

CMake

Markdown

Markdown

标题

引用块 ✅

引用块可以嵌套。在要嵌套的段落前添加 >>。

Components - 组件

链接 ⭐

Images and Videos

CRT

Audio

YouTube

Vimeo

BiliBili

Overflow Auto

Description List

Form Input

Figure Captions

Accordion

Side Comment

Abbreviation

Aside

Keyboard Input

Mark Text

Deleted and Inserted Text

Progress Indicator

Sample Output

Inline Quotation

Unarticulated Annotation

Titles

External Links

Spoilers

Buttons

Accent Color

下载指定路径中的文件

URL 和电子邮件地址

格式化链接 ⭐✅

引用式链接

图像[5]

标题 ID \

My Great Heading \

My Great Heading

UML等图

Zola

Blog-md 标签头

颜色

RSS/Atom订阅

归类

字体字号

加解密

屏蔽RSS/Atom订阅

Banner

Blog-md 内容主体

看板

主题更新 -ametrine

ASCII - 表情符号在博客文章

字典映射规则集合

看板命名与 URL 唯一化：多天 / 全天 / 上午 / 下午 / 晚上 五类各自独立可达 · 修复 path collisions

概述

一、报错现象

二、根因：文件名的日期段被剥离成页面日期

三、修复方案

3.1 编辑器自动写入 slug

3.2 文件名与 URL 方案

求真求实

引用块可以嵌套。在要嵌套的段落前添加 `>>`。

图像^[5]

看板命名与 URL 唯一化：多天 / 全天 / 上午 / 下午 / 晚上五类各自独立可达 · 修复 path collisions

2026-10-13 晚上计划

B.1 `bin/brew-curl`（19 行）

B.2 `bin/brew-git`（35 行）