我的技术博客

AI 模型网关的通用架构：从 API 代理到推理治理层

Sun, 04 Oct 2026 00:00:00 +0000

最初接入大模型时，直接在业务里配置一个 Base URL 和 API Key，往往就够了。问题出现在模型越来越多之后：不同供应商的协议和错误格式不一样，密钥散落在各个服务里，模型切换要改业务配置，用量和成本也很难统一统计。

这时，系统中间多出一层模型网关（AI Gateway）就有了意义。但网关不应该只是「把请求转发到另一个 URL」；它还要回答一系列治理问题：谁可以调用哪个模型？请求应该走哪个渠道？出错时能不能安全切换？费用如何归属？

本文从通用架构角度拆解这些问题，并以 ai-gateway 作为一份具体实现的例子。关注的是可复用的设计思路，而不是某一种技术栈的标准答案。

从反向代理到推理治理层

普通反向代理主要关心转发、负载均衡和连接管理。模型网关当然也要转发请求，但模型调用还带着一些特殊语义：

请求里有模型名、采样参数、工具调用、流式选项等模型概念；
上游计费通常基于 token 或其他 usage，而不是单纯的请求次数；
不同渠道可能提供同一个逻辑模型，也可能有不同的价格、能力和稳定性；
流式响应开始返回后，客户端已经看见部分内容，重试不能再当作透明操作。

因此，网关更像一个推理治理层：把身份、权限、路由、可靠性、成本和审计集中在请求路径上，让业务不必逐家供应商实现这些能力。

它不一定需要负责训练模型、提供公开的用户付费系统，或实现无限规模的服务发现。边界由使用场景决定；关键是让业务接入面稳定，同时让内部策略有清晰的归属。

先分清控制面和数据面

把管理配置和实际推理请求分开，是一种有用的思考方式：

控制面（管理与配置）
供应商 / 渠道 / 模型 / 密钥 / 价格 / 限额 / 运行参数
                     │
                     │ 配置快照或变更通知
                     ▼
数据面（在线请求路径）
客户端 → 协议入口 → 策略处理 → 路由与适配 → 上游模型
                     │
                     └→ 用量、成本、日志与指标

控制面负责维护「系统应该怎样运行」；数据面负责让一条具体请求经过这些规则并得到响应。小型单体服务可以把二者放在同一个进程里，但职责仍然值得分开：管理接口不应绕过统一的配置入口，在线请求也不应该随意到处读取和修改管理状态。

多实例部署时还要回答一个问题：控制面修改了配置，数据面实例何时看到新值？每次请求都查数据库，语义直观但会把数据库放进热路径；本地缓存则减少依赖和延迟，但需要解决更新传播与消息丢失。常见折中是本地快照 + 变更通知 + 定时刷新兜底。这不是唯一解，配置规模、更新频率和一致性要求才决定选择。

请求链路：先统一入口，再分阶段处理

一个典型的数据面可以抽象成这样：

客户端协议
    │
    ▼
解析与归一化 → 鉴权 / 权限 → 配额与成本预估 → 隐私处理
    │
    ▼
路由准备 → 上游调用（适配 / 重试 / 熔断 / 降级）
    │
    ▼
响应归一化 → usage 结算 → 日志 / 审计 / 指标

这张图是职责图，不要求所有实现都严格按同一种顺序执行。例如有些检查可以并行，有些策略只在特定请求上启用。重要的是把每个阶段的输入、输出和失败语义定义清楚：鉴权失败不该进入上游调用；成本预估失败时是拒绝请求还是走降级预算；客户端断开时已预扣的额度由谁释放。

把处理步骤定义为过滤器、拦截器或责任链都可以。形式不是重点，重点是避免把鉴权、路由、计费和 HTTP 细节全部塞进一个巨大方法里，也不要让每个适配器各自重复一遍公共策略。

协议归一化：统一核心，不要假装差异不存在

多协议入口通常需要一个内部请求模型。例如 OpenAI 风格的 Chat Completions 和 Anthropic Messages，可以各自解析外部请求，再转换成内部的 ChatRequest，进入同一条鉴权和路由路径：

1
2
3

OpenAI 请求 ─────┐
                 ├─→ 内部请求模型 → 策略链 → 上游适配器
Anthropic 请求 ──┘

这样可以避免每增加一种客户端协议，就复制一套完整网关逻辑。但「归一化」不等于「所有协议完全相同」。工具调用、思考内容、图片输入、缓存 usage、流式事件等能力可能只有部分协议或供应商支持。如果内部模型只保留最小交集，能力会丢失；如果无限制地塞入供应商专属字段，内部模型又会退化成杂物袋。

较稳妥的做法是：稳定的通用字段进入核心模型；差异能力通过明确的能力声明、扩展字段或协议适配层处理；不支持的功能要显式拒绝或说明，而不是静默丢弃。供应商适配器负责把内部模型转换成上游请求，并把响应、错误和 usage 翻译回来。

扩展点要放在变化的边界上

模型网关里有几类变化特别频繁：供应商协议、路由策略、限流策略和计费口径。把它们放在明确的扩展边界上，能减少新增能力对已有代码的影响。

以供应商适配器为例，可以定义类似这样的能力边界：

ProviderAdapter
  ├─ 声明支持的能力（chat / embedding / streaming 等）
  ├─ 构造上游请求
  ├─ 解析普通响应和流式事件
  └─ 统一错误与 usage

新增供应商时，理想情况是增加一个适配器，而不是在路由、计费、管理页面里同时加入大量 if provider == ...。但抽象也不必过度：如果两个供应商协议完全兼容，复用兼容适配器比为每一家创建空壳类更简单。

用一个具体实现校验架构

ai-gateway 采用 Java 21、Spring WebFlux，内部把 OpenAI 和 Anthropic 入站请求收敛到统一处理链，并通过上游适配器接入多类模型协议。它将管理配置与在线请求处理分开组织，热路径主要使用配置快照，而不是每次请求都重新查询完整配置。

这些选择是一个项目的落地方式，不是架构定律。小型个人工具可能不需要多实例配置广播；只接 OpenAI 兼容服务时，也可能不需要独立的协议归一层。判断标准不是模块数量，而是变化是否集中在合理边界、请求链路是否可理解、失败行为是否可预测。

小结

设计 AI Gateway 时，可以先抓住四件事：

把它定位为推理治理层，而不只是反向代理；
区分管理配置的控制面和处理在线请求的数据面；
用统一内部请求模型复用公共策略，同时明确保留协议差异；
把适配器、路由和策略放在清楚的变化边界上，并写明失败语义。

做好这些，后续再增加计费、故障恢复或合规能力时，才有一个可扩展而不是越改越乱的骨架。

项目地址：liku-yu/ai-gateway。

相关阅读：

多模型路由与故障恢复：重试、熔断和降级的边界 —— 聚焦请求如何选择上游，以及失败后如何处理
模型网关的治理设计：计费、密钥与隐私保护 —— 聚焦成本、安全与运营治理

多模型路由与故障恢复：重试、熔断和降级的边界

Sun, 04 Oct 2026 00:00:00 +0000

把多个模型接进同一个网关，只是完成了统一入口。真正影响可用性的，是请求该去哪里，以及上游出错之后网关该怎么办。

如果路由只是「挑一个 URL」，遇到 429、超时或渠道故障时，业务仍要自己承担不确定性。反过来，如果网关不加区分地重试、切换和降级，也可能把一次故障放大成重复扣费、重复输出或全局雪崩。

本文从通用架构角度讨论模型路由和故障恢复，并用 ai-gateway 的设计作为一个落地参照。

先区分逻辑模型和实际渠道

业务通常希望请求一个稳定的名字，例如 chat-default，而不是把 vendor-x/model-y 写进每个服务。这就需要区分两个概念：

逻辑模型：业务侧请求的名称，代表一组约定好的能力和策略；
渠道（channel）：一次真实的上游调用配置，包含供应商、凭据、模型映射和运行状态。

逻辑模型：chat-default
    ├── 渠道 A：供应商甲 / model-1 / 优先级高
    ├── 渠道 B：供应商乙 / model-2 / 优先级低
    └── 渠道 C：兼容接口 / model-3 / 备用

这个映射让业务和供应商解耦，但逻辑模型不能只是一张别名表。备用渠道是否具备相同上下文长度、工具调用、图像输入和输出格式？成本是否在可接受范围？这些都决定降级是不是语义上安全。

路由通常分成两步

把「哪些渠道可用」和「可用渠道里选哪个」分开，能让策略更清楚：

候选过滤：移除被禁用、没有目标模型映射、已熔断、处于冷却或容量不足的渠道；
候选排序/选择：按优先级、权重、连接数、成本或一致性等策略选择一个渠道。

常见策略并不存在通用的最佳答案：

策略	更适合的目标	需要留意的地方
优先级	主渠道优先，备用渠道兜底	主渠道恢复后流量可能瞬间回切
加权随机	按比例分散流量	权重不等于实时容量，仍要结合限流
最少连接	避免请求集中到忙碌渠道	长短请求差异和流式连接会影响判断
一致性 Hash	同一租户或键尽量命中同一渠道	节点变化会导致映射迁移，且可能造成热点
成本优先	降低平均推理成本	价格最低不代表能力、延迟或可靠性满足要求

真实路由往往先做资格过滤，再应用一种主要策略，并保留健康状态和业务规则。不要把各种策略都做成一个复杂的加权公式，却没有办法解释某次请求为什么去了某个渠道。

重试：预算和错误分类比次数更重要

「失败就重试三次」看起来简单，却没有回答几个关键问题：哪些错误可重试？每次等多久？是否已经超过用户可接受的等待时间？是否会重复产生副作用？

一个更稳妥的策略至少要考虑：

错误分类：连接错误、超时、429 或部分 5xx 可能是瞬时问题；鉴权失败、模型不存在和参数错误通常不适合原样重试。具体状态码仍要看供应商语义。
总 deadline：每次尝试共享一个总时间预算，不能每次重试都重新获得完整超时。
退避与抖动：间隔逐渐增大并加入随机抖动，避免大量请求同时重试。
尝试上限：换渠道重试也消耗上游配额与时间，必须有明确上限。

简单伪代码：

deadline = now + request_budget
for candidate in candidates:
    if now >= deadline:
        stop
    remaining = deadline - now
    result = invoke(candidate, timeout=remaining)
    if success:
        return result
    if not retryable(result.error):
        stop
    wait(backoff_with_jitter(attempt), at_most=remaining)

这比单纯设置 maxRetries = 3 更能表达真实约束：重试是在剩余预算内尝试恢复，而不是无限延长一次请求。

流式请求有一条重要边界

非流式请求失败后，客户端还没有看到响应内容，网关有时可以尝试另一个渠道。但流式响应一旦开始向客户端输出，局面就不同了：客户端已经收到一部分内容，网关再从头请求一次会造成重复、拼接错误，甚至两段回答互相矛盾。

因此常见的策略是：

1
2

首个响应内容发给客户端之前：可以按规则重试或切换
首个响应内容发给客户端之后：不再透明重试，转为结束流并报告错误

这要求网关跟踪响应是否已经开始向外发送，而不只是上游 TCP 连接是否成功。还要分别考虑连接超时、首字节超时和流式空闲超时：请求已经持续输出时，不能因为一个很长的总时长限制而误杀正常生成。

如果上游协议支持续传或响应 ID，可能有更复杂的恢复方案；但在一般的文本生成接口中，不能假设流式请求可以从断点继续。

熔断和冷却解决的是不同时间尺度的问题

重试处理的是当前这一次请求；熔断处理的是一段时间内持续失败的上游。当某渠道连续失败时，继续把新请求发给它只会浪费延迟预算，也可能加剧故障。

典型熔断器有三种状态：

1
2
3

CLOSED（正常）──失败达到阈值──→ OPEN（暂时拒绝调用）
     ↑                             │
     └── HALF-OPEN（放少量探测请求）┘

多实例场景还要考虑状态在哪里维护。本地熔断器实现简单，但每个实例看到的失败历史不同；共享 Redis 冷却窗口可以让实例更快达成一致，却引入了共享状态依赖。也可以让本地熔断器负责快速保护，让共享冷却信息负责实例间协调。选择要匹配系统规模和对一致性的要求。

熔断范围也很重要。按整个供应商熔断，隔离面大但可能误伤该供应商上的健康模型；按渠道或模型粒度隔离更精细，却需要更多状态和配置。

降级不是“换个模型继续”，而是能力契约

当主模型不可用时，备用模型可以提高可用性，但要检查它是否满足当前请求的最低能力要求：

是否支持流式输出、工具调用或多模态输入？
最大上下文和输出长度是否足够？
输出格式是否与调用方预期兼容？
费用和延迟是否在可接受范围？

所以降级链最好表达的是「可接受的替代关系」，而不只是按名称排序的模型列表。对于强依赖特定能力的请求，正确行为可能是明确失败，而不是悄悄换到一个不能完成任务的模型。

在 ai-gateway 中，路由策略、换渠道重试、模型降级和渠道熔断是协同工作的；项目也明确避免在流式内容已经开始输出后透明重试。这是具体实现选择，其他系统仍需要根据上游协议、业务容忍度和预算重新评估。

小结

设计模型路由和故障恢复时，先把这些边界讲清楚：

逻辑模型提供稳定的业务入口，渠道代表真实上游能力；
先过滤不可用候选，再按目标策略选渠道；
重试要分类错误、共享 deadline，并使用退避和上限；
流式响应开始对外输出后，通常不能再透明重试；
熔断保护持续失败的上游，降级则必须满足能力契约。

高可用不等于「多试几次」。更好的目标是：在有限预算内恢复可恢复的失败，对不可恢复的失败尽早、明确地停止。

项目地址：liku-yu/ai-gateway。

相关阅读：

AI 模型网关的通用架构：从 API 代理到推理治理层 —— 了解网关的职责边界与请求链路
模型网关的治理设计：计费、密钥与隐私保护 —— 了解路由之外的成本与安全治理

模型网关的治理设计：计费、密钥与隐私保护

Sun, 04 Oct 2026 00:00:00 +0000

一个模型网关即使能稳定转发请求，如果不知道是谁在调用、费用算到哪里、上游 Key 是否可能泄漏，它依然很难成为可靠的共享基础设施。

这些问题看起来分别属于计费、安全和运维，实际上都围绕同一条请求生命周期：请求进来时要验证身份、检查预算和处理隐私；响应返回后要结算真实用量、记录审计信息。本文从通用架构角度讨论这些治理能力，并用 ai-gateway 作为具体案例。

两类密钥，不要交给同一层管理

业务调用网关需要一种客户端凭据；网关访问模型供应商又需要另一种上游凭据。两者的生命周期和泄漏影响不同，应该分开管理：

`1`	`业务服务 ── 虚拟 Key ──→ 网关 ── 上游 Key ──→ 模型供应商`

业务侧只拿到网关签发的虚拟 Key。它可以关联应用、模型权限、余额或预算，泄漏后能被吊销，而不直接暴露供应商真实凭据。

虚拟 Key 本身通常应当只在签发时明文展示一次，存储侧保留用于校验的摘要，而不是长期保存明文。上游 Key 则需要由网关在调用时取用；如果必须持久化，可以使用经过管理的加密方式保存，并严格限制读取路径。加密不是密钥管理的全部：主密钥轮换、备份、权限隔离和日志脱敏同样重要。

ai-gateway 将上游密钥加密保存，管理接口只返回掩码，并把生产所需的加密主密钥、虚拟 Key 盐值等配置设为显式必需项。这里的设计重点不是某个具体算法，而是减少明文凭据出现的时间和位置。

计费要拆成预留和结算

模型请求结束前，网关通常不知道最终准确的 token usage。若等到响应完成后才扣费，余额可能已经被并发请求同时花超；若一开始按最坏情况直接扣掉，也会让用户体验很差。

一种常见做法是两阶段处理：

1
2
3

请求前：估算成本 → 检查预算 → 预留额度
请求后：读取上游真实 usage → 计算实际成本 → 结算差额
异常结束：按失败语义释放或调整预留额度

这里最难的不是乘单价，而是状态一致性：客户端断开、上游超时、进程重启或结算重复执行时，预留额度不能永久挂住，也不能重复扣款。可以为一次请求建立唯一计费记录，并让结算、退款和释放操作具备幂等性；对于可能并发修改的余额，则需要原子地完成检查和更新。

模型用量也不总是简单的输入 token 与输出 token。有些供应商会单独报告缓存读写 token，若它们有不同价格，就应在归一化 usage 时保留这些维度，而不是提前合并丢失。预扣估算与真实结算的口径也要一致，否则差额会持续偏大或偏小。

限额要明确作用维度与故障语义

“限流”不是一个开关，而是多个维度的策略组合：

Key 或应用的请求数 / 预算；
单模型的 token 速率；
上游渠道的 RPM、TPM 或并发上限；
全局保护阈值。

每个维度解决的问题不同。应用预算用于控制消费，渠道配额用于保护上游，全局限流则用于防止自身资源被打满。实现时还要决定 Redis 或限流服务不可用时是 fail-open（尽量继续服务）还是 fail-closed（拒绝请求保护预算）。没有一种答案适合所有维度：一次营销活动的全局保护与一项严格预算控制，容忍的风险可能完全相反。

多实例限流通常需要共享状态。使用 Redis Lua 等原子操作可以把“检查额度并占用额度”合并成一个操作，避免多个实例同时读到旧值后一起放行。但原子性只解决并发竞态，不会自动解决窗口定义、时钟偏差、超额补偿和故障降级等策略问题。

脱敏应该定义清楚边界

把敏感内容送往外部模型前进行脱敏，可以降低不必要的数据暴露。但“用正则替换一下”并不等于完整的隐私保护：

识别规则可能漏报，也可能误伤普通文本；
替换后的占位符要能否回填，取决于业务语义；
多轮对话和流式输出会让替换范围更复杂；
日志、错误信息和调试追踪也可能意外保存原文。

一个相对清晰的处理流程是：在调用上游前识别敏感值，为需要保留语义的值生成不可预测的占位符映射；映射只在当前请求生命周期内使用；响应是否回填由明确策略决定；日志默认不记录原始敏感值。

该项目实现了手机号、身份证、邮箱、银行卡、IP 和密钥等类别的识别，并将占位符映射限制在内存中。它是一层风险降低措施，不是合规证明，也不能替代访问控制、数据保留策略或组织层面的隐私评估。

可观测性要服务于排障和核算

请求日志、审计事件和指标解决的问题不同：

请求日志帮助排查单次请求，但要避免记录凭据和完整敏感内容；
审计事件回答谁修改了渠道、价格或策略；
指标帮助观察总体趋势，例如延迟、错误率、限流、熔断、token 和成本。

指标标签要控制基数。模型名或渠道名可能是合理维度，但把 request ID、用户输入或 Key 放进标签，会让时序数据库的时间序列数量迅速膨胀。单次请求的细节应由日志或追踪承载，而不是无限加到指标标签里。

异步写日志能避免数据库变慢时阻塞推理热路径，但队列必须有容量上限，并明确满载时的行为：丢弃、采样、阻塞还是降级。对在线推理而言，“日志绝不丢”未必比“模型请求不被日志拖死”更重要；这需要根据审计要求决定。

把治理动作纳入同一条生命周期

一个治理型网关可以把关键状态变化整理成如下流程：

鉴权与模型权限
    ↓
预算校验 / 额度预留
    ↓
隐私处理与上游调用
    ↓
读取真实 usage，结算或释放额度
    ↓
记录访问日志、审计事件与指标

请求链路中任何位置失败，都要知道此前占用过哪些资源，以及由谁负责释放。把清理和结算逻辑集中在一个幂等的终结路径上，通常比让每个错误分支各自退款更容易维护。

小结

模型网关的成本与安全治理，可以归纳为几条原则：

业务凭据与上游凭据分离，减少明文密钥暴露面；
将费用核算拆成预留和真实用量结算，并让状态变更可重试、可幂等；
按不同维度设计限额，并明确共享状态不可用时的策略；
把脱敏当作风险降低手段，而不是完整的隐私保证；
区分日志、审计和指标，既要能排障，也要保护敏感数据。

这些能力最终都要回答同一个问题：请求无论成功、失败还是中断，网关能不能解释发生了什么，并把占用的预算和资源妥善收尾。

项目地址：liku-yu/ai-gateway。

相关阅读：

AI 模型网关的通用架构：从 API 代理到推理治理层 —— 了解网关的整体职责与请求链路
多模型路由与故障恢复：重试、熔断和降级的边界 —— 了解上游选择与失败恢复的约束

Agent 的工程细节：上下文裁剪、重试、编码与打包

Wed, 30 Sep 2026 00:00:00 +0000

第一篇把 Agent 的核心循环跑通了，第二篇加了安全护栏。但一个「能给自己用」的脚本，和一个「能打包给别人用」的工具，中间隔着的正是这篇要讲的东西。

它们都不涉及模型能力，却决定这个 Agent 能不能稳定地用下去。

上下文预算：历史不能无限增长

Responses API 是无状态的，每一轮都要把完整历史发回去。而 Agent 的工具调用会产生大量输出（命令结果、文件内容……），几轮之后请求体就会膨胀到一个危险的大小。

于是需要一个粗糙但有效的预算机制：用序列化后的字符数估算体积，超过阈值就裁剪：

MAX_CONTEXT_CHARS = 200_000

def _items_size(items):
    return sum(len(json.dumps(it, ensure_ascii=False, default=str)) for it in items)

裁剪的难点在于不能随便切。 历史不是一串独立消息，而是有依赖关系的 item 序列——function_call 和它的 function_call_output 必须成对存在，call_id 要能对上。如果从中间截断，就会留下一个「有调用、没结果」的悬空结构，模型可能因此报错或行为异常。

所以裁剪的单位是**「整轮对话」**——按用户消息切分，最旧的整轮优先丢弃：

def _compact(input_items):
    if len(input_items) <= 2 or _items_size(input_items) <= MAX_CONTEXT_CHARS:
        return
    system = input_items[0]
    groups, cur = [], []
    for it in input_items[1:]:
        if it.get("type") == "message" and it.get("role") == "user":
            if cur:
                groups.append(cur)      # 遇到新的用户消息 = 上一轮结束
            cur = [it]
        else:
            cur.append(it)              # 工具调用/结果归入当前轮
    if cur:
        groups.append(cur)

    while len(groups) > 1 and \
            _items_size([system] + [x for g in groups for x in g]) > MAX_CONTEXT_CHARS:
        groups.pop(0)                   # 丢掉最旧的一整轮

    input_items[:] = [system] + [x for g in groups for x in g]

system 永远保留，最少保留一轮，保证「成对」关系不被破坏。

重试：只在还没输出之前

网络抖动、429、5xx 都值得重试。先定义「什么算瞬时错误」：

_TRANSIENT_STATUS = {408, 409, 429, 500, 502, 503, 504}

def _is_transient(exc):
    if isinstance(exc, httpx.TransportError):
        return True
    if isinstance(exc, httpx.HTTPStatusError):
        return exc.response.status_code in _TRANSIENT_STATUS
    return False

但流式请求的重试有个陷阱：如果已经开始往终端输出，再重试就会把内容重复打印一遍。所以重试必须加一个大前提——「本轮尚未产生任何事件」：

started = False   # 一旦收到任何事件就置 True

# ...
if _is_transient(e) and not started and attempt < MAX_RETRIES:
    attempt += 1
    delay = min(2 ** attempt, 8)          # 指数退避，封顶 8 秒
    time.sleep(delay)
    continue
raise

这个 started 标志是个很典型的「流式接口才有的约束」——非流式请求随便重试都无所谓，流式就要为「已经吐出去的内容」负责。

Windows 编码：两个独立的坑

这是整个项目里最 Windows 特有的部分，而且中文环境下几乎必踩。

坑一：控制台代码页是 GBK。 模型返回 UTF-8 文本，默认输出流按 GBK 编码，轻则乱码、重则遇到非 GBK 字符直接抛异常。解决办法是强制把 stdout/stderr 设为 UTF-8：

for stream in (sys.stdout, sys.stderr):
    reconfigure = getattr(stream, "reconfigure", None)
    if reconfigure is not None:
        try:
            reconfigure(encoding="utf-8", errors="replace")
        except Exception:
            pass

坑二：管道输入的代理字符。 当 stdin 是管道时（如 echo "..." | agent.py --one），如果按 GBK 解码 UTF-8 字节，可能产生 surrogate code point（代理项）。这种字符串在 json.dumps 时会让整个请求构造失败——报错信息还很难懂。

处理方式是：stdin 只在它是管道时才重设为 UTF-8（交互式终端不碰），读取时也直接走 bytes 解码：

def read_stdin_text() -> str:
    try:
        return sys.stdin.buffer.read().decode("utf-8", errors="replace").strip()
    except Exception:
        return sys.stdin.read().strip()

规律很清楚：交互式输入交给终端，管道输入自己按 UTF-8 解码。把这两者混在一起处理，就会踩到代理字符的坑。

TUI 与核心解耦：一个 emit 回调

如果核心逻辑里直接写 rich.print，那它就再也离不开界面库了。这个项目的做法是：核心只负责产出事件，渲染交给外层。

核心定义了一个回调签名：

`1`	`Emit = Callable[[str, dict], None]`

然后所有「想显示点什么」的地方都调用 emit(事件名, 数据)，而不是直接打印：

事件	含义
`reasoning` / `reasoning_done`	推理过程的增量与结束
`text` / `text_done`	最终回答的增量与结束
`tool`	一次工具执行（命令 + 结果 + 状态）
`notice` / `error` / `aborted`	提示、错误、中断

tui.py 传入自己的 emit 实现，用 prompt_toolkit + Rich 渲染成带边框的版面；而 --plain 模式传 None，核心就退回直接写 stdout/stderr。同一套逻辑，两种前端。

TUI 还做了一层 try/except ImportError 的懒加载——没装 rich/prompt_toolkit 时自动退回纯文本 REPL，不会因为缺一个可选依赖就整个跑不起来。

另外有个 Git Bash 特有的守卫：终端如果缺少原生 Windows 控制台，prompt_toolkit 会崩溃。所以启动前先探测一下：

if os.name == "nt" and "xterm" in os.environ.get("TERM", "") and not _has_windows_console():
    console.print(Text("TUI 需要原生 Windows 控制台。\n"
                       "  Git Bash 请用：winpty uv run python agent.py", style=ERROR))
    sys.exit(1)

_has_windows_console() 通过 GetConsoleMode 判断句柄是否是真控制台——因为 mintty 暴露的只是一个 xterm pty。

打包：单文件 exe，但 key 不入包

最后是分发。用 PyInstaller 打成一个 exe，而 TUI 依赖（rich、prompt_toolkit）需要显式收集，tui 还得作为隐藏导入，否则会被漏掉：

from PyInstaller.utils.hooks import collect_all

hiddenimports = ['tui']
for pkg in ('rich', 'prompt_toolkit'):
    d, b, h = collect_all(pkg)
    datas += d; binaries += b; hiddenimports += h

a = Analysis(['agent.py'], hiddenimports=hiddenimports,
             excludes=['tkinter', 'unittest', 'pydoc'],
             optimize=2)

有一个安全红线：API Key 绝不能打进二进制。所以运行时才去读：

def _key():
    env = os.environ.get("DEEPSEEK_API_KEY", "").strip()
    if env:
        return env
    # 打包成 onefile 后 __file__ 指向临时解压目录，
    # 所以还要在真正的 exe 旁边找 .env
    base = (os.path.dirname(os.path.abspath(sys.executable))
            if getattr(sys, "frozen", False)
            else os.path.dirname(os.path.abspath(__file__)))
    ...

getattr(sys, "frozen", False) 用来区分「源码运行」和「打包后运行」——onefile 模式下 __file__ 指向临时目录，只有 sys.executable 才指向 exe 本身，.env 要放在它旁边才找得到。

构建脚本则封装成一条命令：

`1`	`uv run pyinstaller --noconfirm --clean --distpath "$OUT" deepseek-agent.spec`

小结

这些细节单独看都不起眼，但每一个都能让「能跑的 demo」变成「不想用的工具」：

上下文裁剪要按整轮处理，因为工具调用是成对的结构；
流式重试必须判断「是否已输出」，否则会重复渲染；
Windows 编码要把交互输入和管道输入分开对待；
TUI 解耦靠一个 emit 回调，核心不依赖渲染库；
打包时显式收集可选依赖，并让密钥留在运行时读取。

写完这些，我才真正体会到：Agent 的「智能」来自模型，但「可用」来自工程。

项目地址：liku-yu/deepseek-agent。

相关阅读：

从零开始写一个 Agent：一次极简的尝试

Wed, 30 Sep 2026 00:00:00 +0000

市面上的 Agent 框架越来越多，封装的层次也越来越厚。看多了反而有个疑问挥之不去：一个 Agent 剥离掉所有框架之后，剩下的核心到底是什么？

为了搞清楚这件事，我用最朴素的方式从零写了一个：不引入任何 agent 框架，只有一个 HTTP 客户端、一个工具，和一个循环。项目叫 deepseek-agent——极简命令行 Agent，唯一能做的事就是在 Git Bash 里执行命令。

这篇记录整个尝试的思路。技术栈简单到有点无聊：httpx 负责请求，bash 是唯一的工具，剩下的全靠自己写。

说明

本文讲的都是代码结构与设计，不需要真实调用 API。文中出现的 Key 一律脱敏为 sk-****。

Agent 和聊天机器人的区别

先想清楚这件事，后面才有的写。

普通对话（chatbot）是一问一答：你发消息，模型回消息，结束。模型的知识和手都停在上一次训练里。

而 Agent 多了一件事：模型可以调用工具，观察真实结果，然后决定下一步。当你让它「看看当前目录里有什么」，它不是凭记忆猜，而是：

1
2
3

模型：我要执行 `ls`
本地：执行 → 得到真实输出
模型：（看到输出）好的，目录里有 a.txt、b.txt…

也就是说，Agent = 模型 + 工具 + 一个循环。剥掉所有框架，核心就是这个反馈回路：

loop {
    把对话历史发给模型
    如果模型要求调用工具：
        执行工具，把结果追加进历史
        继续循环
    否则：
        模型给出了最终回答，结束
}

想通这一点，实现就变得具体了。

输入不再是一串消息，而是一组 items

这个项目用的是 Responses API（POST /v1/responses）。它和常见的 Chat Completions 有一个关键区别：请求体的 input 不是简单的 messages，而是一组带类型的 items：

def _system_item():
    return {"type": "message", "role": "system",
            "content": [{"type": "input_text", "text": SYSTEM}]}

def _user_item(text):
    return {"type": "message", "role": "user",
            "content": [{"type": "input_text", "text": text}]}

一开始觉得这比 {"role": "user", "content": "..."} 啰嗦，但很快发现它是为工具调用准备的——因为工具调用和它的返回值也是 item：

1
2

{"type": "function_call",        "call_id": "...", "name": "bash", "arguments": "{...}"}
{"type": "function_call_output", "call_id": "...", "output": "命令输出"}

整个 Agent 的历史就是这些 item 的列表。call_id 把「模型发起的调用」和「我执行后的结果」配成一对，这是后面回填的基础。

定义唯一的工具：bash

工具用 JSON Schema 描述，模型靠它知道「有这么个工具、参数长什么样」：

TOOLS = [{
    "type": "function",
    "name": "bash",
    "description": "Run a shell command in Git Bash and return its stdout, stderr and exit code.",
    "parameters": {
        "type": "object",
        "properties": {
            "command": {"type": "string", "description": "The shell command to run."}
        },
        "required": ["command"],
    },
}]

只给一个 bash 是刻意的克制：它能做几乎所有事（读文件、跑测试、装依赖……），省掉了一堆专用工具的复杂度。当然，这也直接引出安全问题——留到下一篇讲。

核心循环：二十几行就是全部

有了 items 和工具，主循环短得出乎意料：

def run_agent(input_items, emit=None, confirm=None):
    while True:
        output_items = stream_call(input_items, TOOLS, emit)
        input_items.extend(output_items)              # 回填模型这一轮的输出

        tool_calls = [it for it in output_items if it.get("type") == "function_call"]
        if not tool_calls:
            return                                     # 没有工具调用 = 最终回答

        for call in tool_calls:                        # 执行每个工具调用
            result = execute_tool(call["name"], call["arguments"], emit, confirm)
            input_items.append({
                "type": "function_call_output",
                "call_id": call["call_id"],
                "output": result,
            })

几个设计选择：

不限轮数：while True 一直转到模型不再调用工具。这是取舍——不设上限意味着一个复杂任务可以自主推进很多步；代价是万一模型「钻牛角尖」，得靠用户手动中断（见第二篇的取消机制）。
回填模型自己的输出：input_items.extend(output_items) 不只是把工具结果塞回去，连模型这轮的 reasoning 和 function_call 也一并保留，下一轮它才能「记得」自己刚才做了什么。
每一轮都是完整历史：Responses API 是无状态的，每次请求都要把全部 items 发过去。历史会越来越长，于是就有了第三篇要讲的上下文裁剪。

流式：让等待变得可感知

调用模型时如果不流式，用户就要盯着黑屏等好几秒。所以请求带 stream: True，响应是 SSE（Server-Sent Events），逐行读：

with httpx.stream("POST", f"{API_BASE}/responses", headers=headers,
                  json=body, timeout=180) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith("data:"):
            continue
        data = line[5:].strip()
        if data == "[DONE]":
            continue
        evt = json.loads(data)                    # 解析事件
        t = evt.get("type")

事件类型里，最有意思的是它把推理过程和最终回答分开：

事件	含义
`response.reasoning_text.delta`	推理过程的增量（可以灰色流式展示）
`response.output_text.delta`	最终回答的增量
`response.output_item.done`	一个完整 item 结束（收集起来回填用）
`response.completed`	本轮结束，附带 usage

这里有个很容易踩的坑：流式接口里，失败往往不是抛异常，而是发一个事件。如果不处理，程序会「安静地成功」——什么都没输出，却当成正常结束：

# 必须显式把 API 侧失败变成异常
if t in ("response.failed", "error", "response.incomplete"):
    err = evt.get("error") or (evt.get("response") or {}).get("error") or t
    raise AgentError(f"{t}: {err}")

与此同理，网络抖动导致的瞬时错误要能重试，但只在「还没输出任何内容」时才重试，否则会把已经渲染的内容重复打印一遍——这个细节也放在第三篇展开。

工具执行：把命令跑起来

工具执行看着最简单，其实藏着不少东西。最朴素的版本是 subprocess.run，但它会在两个地方掉链子：超时和取消——只 kill 掉 bash 本身，它启动的子进程还会流浪。

所以这里手动管理进程，并让它跑在独立的进程组里，超时或取消时连同整棵进程树一起干掉：

if os.name == "nt":
    popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
else:
    popen_kwargs["start_new_session"] = True

返回值也做成了模型容易读的紧凑格式：

exit_code=0
stdout:
...
stderr:
...

把 stdout/stderr 各截断到 4000 / 2000 字符，避免一次 cat 大文件就把上下文撑爆。

跑通之后，问题才刚开始

到这里，「模型 + 工具 + 循环」已经能用了：输入一句「用 bash 看看当前目录」，它就会真的执行 ls 并把结果讲给你听。核心代码加起来不到 200 行。

但一个能给别人用的 Agent，还有两座大山：

安全：你等于把 shell 交给了模型。危险命令、敏感文件、偷偷外传数据怎么办？靠一个正则黑名单显然不够，但完全没有防护更不行。
工程：历史无限增长、网络抖动重试、Windows 控制台中文乱码、TUI 与核心逻辑耦合、打包成单个 exe……这些和「模型聪不聪明」无关，却决定它能不能用。

这两块我都单独写了：

小结

回到最初的问题——剥掉框架，Agent 的核心是什么？

答案比想象中简单：一个把「模型的工具调用请求」变成「真实执行结果」再喂回去的循环。工具的定义是 JSON Schema，历史是一组带类型的 item，call_id 负责配对，流式负责体验。剩下的都是工程。

这个认识最大的价值是去神秘化：Agent 不是一个新物种，它就是一个反馈回路。理解了这个回路，再看各种框架，就只是「谁把这圈包得更舒服」的区别了。

项目地址：liku-yu/deepseek-agent。

相关阅读：

让 AI Agent 安全地执行命令 —— 给模型 shell 权限时，如何加护栏
Agent 的工程细节：上下文裁剪、重试、编码与打包 —— 让这个循环真正可用的那些事

让 AI Agent 安全地执行命令

Wed, 30 Sep 2026 00:00:00 +0000

在上一篇里，我给这个 Agent 只配了一个工具：bash。它因此能做几乎任何事，也意味着我把 shell 交给了模型。

这不是危言耸听。模型可能因为一次误判，执行 rm -rf 删掉不该删的目录；可能读走 .env 里的密钥；也可能在某些情况下把敏感信息通过 curl 发出去。给 Agent 执行能力的那一刻，安全就不再是可选项。

这篇讲这个最小 Agent 是怎么加护栏的。先说清楚：它是启发式防护，不是沙箱——但即便如此，也比毫无防护强得多。

三类需要警惕的命令

与其维护一张巨大的黑名单，不如先想清楚「什么命令值得停下来问一句」。这个项目归纳成三类：

类别	含义	例子
`destructive`	可能造成不可逆破坏	`rm -rf`、`mkfs`、`dd if=`、fork 炸弹
`sensitive-file`	触碰密钥/凭据文件	`.env`、`.ssh/`、`id_rsa`、`.aws/credentials`
`network-egress`	可能把数据传出去	`curl`、`wget`、`ssh`、`nc`

分类结果是一个列表，只要非空就进入审批流程：

def classify_command(command: str) -> list[str]:
    if not command:
        return []
    s = _normalize(command)
    reasons = []
    if _rm_recursive_force(s) or _DESTRUCTIVE_RE.search(s):
        reasons.append("destructive")
    if _SENSITIVE_RE.search(command):
        reasons.append("sensitive-file")
    if _has_network_egress(s):
        reasons.append("network-egress")
    return reasons

匹配之前先「归一化」

命令匹配最容易被绕过的地方，是各种等价写法：rm -rf x 和 rm -fr x 是一回事，'rm' -RF x 加引号和多余空格也能跑。所以匹配前先做归一化——去掉引号与反斜杠、压缩空白、转小写：

1
2
3

def _normalize(command: str) -> str:
    s = re.sub(r"[\"'`\\]", "", command)
    return re.sub(r"\s+", " ", s).lower()

rm -rf 还单独解析了一遍，因为它的参数顺序和分片写法很灵活。做法是先按 ;&| 把命令切成段，只看每段开头的 rm，再检查是否同时带上递归和强制标志：

def _rm_recursive_force(s: str) -> bool:
    for seg in re.split(r"[;&|]+", s):
        toks = seg.split()
        if not toks or "rm" not in toks[0]:
            continue
        flags = " ".join(t for t in toks[1:] if t.startswith("-"))
        if re.search(r"(^|\s)-[a-z]*r|--recursive", flags) and \
           re.search(r"(^|\s)-[a-z]*f|--force", flags):
            return True
    return False

危险命令则用一张正则表覆盖常见的「一次性毁灭」操作：

_DESTRUCTIVE_RE = re.compile("|".join([
    r"\bmkfs\b", r"\bdd\s+if=", r":\(\)\s*\{",              # 格式化 / 覆盖磁盘 / fork 炸弹
    r"\b(shutdown|reboot|halt|poweroff)\b",
    r"\bformat\s+[a-z]:", r"\bdel\s+/[sfq]\b",
    r"remove-item[^\n]*-recurse",
    r"\bfind\b[^\n]*\s-delete\b", r"\bgit\s+clean\b[^\n]*-[a-z]*[dfx]",
    r"\bshred\b", r"\btruncate\s+-s\s*0",
]), re.I)

敏感文件同样用正则，覆盖 .env、.ssh/、私钥、各类凭据文件。这里用了分隔符和边界断言，尽量避免把普通单词误判：

_SENSITIVE_RE = re.compile(
    r"(^|[\s=<>@/\\\"'`])(\.env(\.[\w.-]+)?|\.ssh/|id_rsa|id_ed25519|"
    r"\.aws/credentials|\.git-credentials|\.netrc|\.npmrc|\.pypirc|"
    r"credentials(\.json)?)(?=$|[\s\"'`);|&><])", re.I)

审批：把决定权交回用户

检测到风险后，不是直接拒绝，而是问用户要不要放行。项目里有个 confirm 回调，TUI 模式下弹一个 [y/N]：

reasons = classify_command(command)
if reasons:
    allow = (os.environ.get("DEEPSEEK_ALLOW_DANGEROUS", "").strip().lower()
             in ("1", "true", "yes", "on"))
    if not allow:
        tag = ", ".join(reasons)
        if confirm is None:                       # 没有审批通道 = 非交互模式
            return (f"BLOCKED ({tag}): 该命令有风险，请用户手动执行，"
                    "或设置 DEEPSEEK_ALLOW_DANGEROUS=1 覆盖。")
        if not confirm(command):
            return f"BLOCKED ({tag}): the user denied this command."

两个关键设计：

非交互模式（--one）直接拦截：管道/脚本场景下没人能点确认，confirm 是 None，于是默认拒绝，而不是默默放行。这是个「fail closed」的选择。
留一个显式逃生舱：DEEPSEEK_ALLOW_DANGEROUS=1 用于你明确知道自己在干什么的场景。默认关闭。

重要：这是启发式防护，不是沙箱

正则黑名单永远可以被绕过（字符串拼接、变量展开、间接执行的脚本……）。它只能挡住「模型无意中踏入危险区」这类常见失误，挡不住蓄意攻击。真正需要隔离时，请用容器、虚拟机或受限用户权限来限制进程能触碰的范围。

防外泄：把密钥从子进程环境里摘掉

一个容易被忽略的泄露路径：模型可以让你执行 env 或 printenv，然后「顺便」读走环境变量里的 API Key。既然工具是模型控制的，就不能假设它不会这么做。

对策是在启动子进程前，把所有名字里带 KEY/TOKEN/SECRET 等字样的环境变量剔除：

_ENV_SECRET_RE = re.compile(r"(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|PASSWD)", re.I)

def _child_env() -> dict:
    """Environment for the bash tool with secrets removed (anti-exfiltration)."""
    return {k: v for k, v in os.environ.items() if not _ENV_SECRET_RE.search(k)}

这样即便模型执行 env，也看不到 DEEPSEEK_API_KEY 之类的东西。注意 Agent 自己仍然能读到 key（请求模型需要），只是它不继承给被执行的命令。

取消与超时：Ctrl+C 到底做了什么

交互式 Agent 里，Ctrl+C 的默认行为是「中断进程」，直接退出程序。但用户往往只是想打断当前这一轮，不是想关掉整个会话。

所以这里把 SIGINT 的语义改掉：不抛异常，而是设置一个取消标志，由各处轮询：

_cancel = threading.Event()

@contextlib.contextmanager
def cancellable():
    clear_cancel()
    old = signal.getsignal(signal.SIGINT)
    signal.signal(signal.SIGINT, lambda *_: request_cancel())   # 只设置标志
    try:
        yield
    finally:
        signal.signal(signal.SIGINT, old)
        clear_cancel()

模型流式请求和命令执行都会检查这个标志。命令执行处每 0.2 秒轮询一次，超时或取消都会杀掉整棵进程树：

while True:
    try:
        out, err = proc.communicate(timeout=0.2)   # 短超时轮询
        code = proc.returncode
        break
    except subprocess.TimeoutExpired:
        if _cancel.is_set():
            _kill_tree(proc)
            return "exit_code=130\nstdout:\n(cancelled)\nstderr:\n(cancelled)"
        if time.monotonic() >= deadline:
            _kill_tree(proc)
            return "exit_code=124\nstdout:\n(timed out)\nstderr:\n(timed out)"

杀进程树的实现区分平台：

if os.name == "nt":
    subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], capture_output=True)
else:
    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)

/T 表示连同子进程一起杀，os.killpg 则对整个进程组下手。

如果你只用 subprocess.run(cmd, timeout=...)，会得到一个隐蔽的问题：超时只终止 bash，它启动的子进程会变成孤儿继续跑。手动管理进程组 + 轮询 + 杀进程树，才让「取消」真正干净。

退出码也沿用了 Unix 惯例，模型和用户都能看懂：124 = 超时，130 = 被中断。

小结

给 Agent 执行能力，安全设计应该和主循环一起做，而不是事后补丁。这个项目的做法可以总结为四条：

分类：把命令分成破坏性 / 敏感文件 / 网络外传三类，命中就停下来；
审批：默认问用户，非交互模式 fail closed，另留显式的覆盖开关；
隔离：执行前剥离环境里的密钥，切断最直接的泄露路径；
可控：Ctrl+C 只取消当前轮，超时与取消都清理整棵进程树。

同时要清醒地认识到它的边界——这些是启发式护栏，不是沙箱。它们能显著降低「模型手滑」的代价，但替代不了真正的隔离。

项目地址：liku-yu/deepseek-agent。

相关阅读：

从零开始写一个 Agent：一次极简的尝试 —— 先搞懂那个核心循环
Agent 的工程细节：上下文裁剪、重试、编码与打包 —— 让循环真正可用的工程问题

把 yt-dlp 封装成好用的下载器：vidgrab 的设计笔记

Wed, 23 Sep 2026 00:00:00 +0000

yt-dlp 大概是目前最强的开源视频下载器，内置上千个站点解析器。但它的接口是给命令行高级用户设计的：合并音视频要 ffmpeg、B 站高清要登录态、分片要并发数、下不动要换代理、批量要写文件……对不常用命令的人来说，门槛不低。

vidgrab 就是给它套的一层壳：基于 yt-dlp 内核，用 uv 管理依赖，双击一个 .bat 就能用。这篇不讲怎么用，而是讲讲这层壳在设计上做对了哪些事。

免责声明

本工具仅用于下载你有权保存的内容。请遵守目标平台的服务协议与当地版权法律。项目不包含、也不支持任何绕过 DRM 或付费墙的代码。

它长什么样

交互式菜单是主要入口，任何提问处输入 0 或 q 都能安全退出、不下载任何东西：

  ▸ 1. 下载链接                2. 编辑 urls.txt 链接清单并批量下载
    3. 仅下载音频（MP3）        4. 查看链接信息与可用画质
    5. 按关键词搜索并下载        6. 快速设置
    7. 查看支持的站点           8. 打开下载目录         9. 退出程序

同时保留完整的命令行入口：

uv run python main.py "<链接>"                                   :: 最高画质
uv run python main.py -q 1080p -o "D:/Videos" "<链接1>" "<链接2>"
uv run python main.py --audio --audio-format mp3 "<链接>"
uv run python main.py -f urls.txt --jobs 3                       :: 批量 + 3 并发
uv run python main.py --search "关键词" --search-site bilibili --search-limit 5

架构：四层 + 一个贯穿全局的 Settings

src/vidgrab/
├─ config.py    # 纯数据：Settings dataclass + 画质/音频/搜索预设表
├─ core.py      # 下载核心：把 Settings 翻译成 yt-dlp 选项、批量调度、搜索
├─ cli.py       # argparse 命令行 + 交互菜单
└─ ui.py        # 终端适配：ANSI/ASCII、进度条、菜单组件

关键设计是：所有可调参数都收进一个 Settings dataclass。

命令行解析出的参数、菜单里选择的项，最终都只是往 Settings 里写值；core.Downloader 只认 Settings，不关心它从哪来。好处很直接——菜单和命令行不会出现「命令行能做、菜单做不到」的割裂；加一个新参数，只需要在 Settings 里加一个字段、在构造 yt-dlp 选项时读一次。

设计一：配置驱动，把 Settings 翻译成 yt-dlp options

yt-dlp 的 Python API 选项很多，硬编码在各处会迅速失控。vidgrab 把它们集中到一个 build_opts() 里构造，画质档位则用一张预设表维护：

QUALITY_FORMATS = {
    "best":  "bv*+ba/b",   # 最高画质（自动合并音视频）
    "1080p": "bv*[height<=1080]+ba/b[height<=1080]",
    "720p":  "bv*[height<=720]+ba/b[height<=720]",
    "worst": "wv*+wa/w",   # 最小体积
}

档位	format 表达式
`best`	`bv*+ba/b`
`1080p`	`bv*[height<=1080]+ba/b[height<=1080]`
`720p`	`bv*[height<=720]+ba/b[height<=720]`
`worst`	`wv*+wa/w`

后处理器链同样是声明式地拼出来的：

pps = []                       # postprocessors
if s.audio_only:
    pps.append({"key": "FFmpegExtractAudio",
                "preferredcodec": s.audio_format,
                "preferredquality": s.audio_quality})
if s.embed_metadata:
    pps.append({"key": "FFmpegMetadata"})
if s.embed_thumbnail:
    pps.append({"key": "EmbedThumbnail"})
if s.embed_subs:
    pps.append({"key": "FFmpegEmbedSubtitle"})
opts["postprocessors"] = pps

好处是各功能开关彼此独立，组合起来就是完整能力，不需要为每种场景写一条分支。

设计二：进度条要算「整批总进度」

yt-dlp 的 progress_hooks 只给当前文件的进度。但批量下载时，用户真正关心的是「这一批下到哪了」。所以进度条做了两层：

`1`	`[1/2] [████████████░░░░░░░░░░░░] 50.4% 2.0MiB/4.0MiB 3.1MiB/s ETA 00:00 │ 总 25.2%`

50.4% 是当前文件，│ 总 25.2% 是按已完成任务数加权的整批进度。两个细节值得说：

总进度只增不减：同一个视频会分「视频流 / 音频流」两次下载，进度会重置。不处理的话总进度会来回跳。代码里记录历史峰值，下降时保持峰值不动。
按输出目标切换渲染策略：终端（TTY）用 \r 原地刷新；一旦重定向到文件或管道，就按 10% 分档节流输出，避免刷屏。

设计三：搜索要「flat 优先 + 带退避的重试」

关键词搜索形如 bilisearch10:关键词，实现上有两个关键决策。

其一，flat 优先。先用 extract_flat 一次请求拿到候选列表，再对缺标题的条目小并发补全。因为某些平台的 flat 搜索只返回 id（B 站就是一串 av 号），而直接非 flat 搜索又会因连续快速请求被风控——先轻量拿列表、再按需补全，是折中。

其二，把风控当成概率事件。B 站搜索接口会间歇性返回 HTTP 412，实测相同参数连续请求成功率约 4/6。所以失败后不是直接报错，而是等待并重试：

for attempt in range(1, attempts + 1):
    try:
        ...
        break
    except Exception as exc:
        last_exc = exc
        if attempt < attempts:
            time.sleep(1.5 * attempt)   # 1.5s / 3s 退避

设计四：ignoreerrors 的陷阱

这是个很容易写错的地方。yt-dlp 的 Python API 里，一旦设置 ignoreerrors=True，下载失败不会抛异常——错误只会从你传入的 logger 的 error() 方法里冒出来。如果只检查 ydl.download() 的返回值，失败任务会被误判为成功。

做法是自定义 logger，把错误收集进一个 sink：

class _Logger:
    def error(self, msg: str) -> None:
        # ignoreerrors=True 时不抛异常，错误只从这里出来，
        # 必须记录，否则失败任务会被误判为成功
        self.sink.setdefault("errors", []).append(msg)

更进一步，它区分了整体失败和部分成功：播放列表里有些条目成功、有些失败时，TaskResult 标记为 partial，汇总时单独统计，而不是笼统算作失败。

小结

vidgrab 的功能本质上是「给 yt-dlp 套壳」，但几个设计决策让它明显比「写个脚本调 yt-dlp」更成熟：

一个 Settings 贯穿全局：命令行和菜单共用一套逻辑，扩展成本低；
配置驱动：画质、音频、字幕、元数据都是独立开关，组合自由；
贴着实况做交互：总进度只增不减、风控退避重试、部分成功单独统计；
不放过 API 的坑：ignoreerrors 下错误只从 logger 来，漏了就会误判。

项目地址：liku-yu/video-downloader（MIT License）。

相关阅读：

一个下载器的工程化踩坑：单文件 .bat、cmd 陷阱与 uv 锁源 —— 分发与跨平台的另一半故事
用 Markdown 写文章：Void 主题写作指南

一个下载器的工程化踩坑：单文件 .bat、cmd 陷阱与 uv 锁源

Wed, 23 Sep 2026 00:00:00 +0000

做一个小工具，功能写出来只算完成一半。另一半是分发：怎么让拿到它的人不用配环境、不用看文档，双击就能跑起来。

vidgrab 走的是「Windows 优先、零依赖启动」的路线，为了做到这一点踩了不少坑。这篇就聊聊这些工程细节，每一条都是真实撞出来的。

先把整份程序塞进单个 .bat

项目提供两种用法：文件夹版（run.bat + 源码）和单文件版（只有一个 vidgrab-standalone.bat）。后者只需要一个文件就能运行，它的原理是「批处理脚本 + 内嵌载荷」：

1. 用 zipapp 把 src/vidgrab 打成单文件应用 vidgrab.pyz
2. 把 .pyz 做 base64 编码，内嵌到 .bat 末尾（纯 ASCII，不受编码影响）
3. .bat 运行时：
     findstr 定位载荷行 → more 跳过前面的批处理代码提取 base64
     → certutil -decode 还原 vidgrab.pyz
     → uv run --with yt-dlp ... python vidgrab.pyz

对应的批处理核心几行：

for /f "delims=:" %%i in ('findstr /n /b /e /c:"rem __VIDGRAB_PAYLOAD__" "%~f0"') do set "SKIP=%%i"
more +%SKIP% "%~f0" > "%B64%" 2>nul
certutil -f -decode "%B64%" "%PYZ%" >nul 2>nul
"%UV%" run --with "yt-dlp[default]" --with "curl_cffi" --with "imageio-ffmpeg" python "%PYZ%"

依赖不打包，而是运行时用 uv run --with 按需拉取——省掉了维护体积巨大的内嵌依赖，代价是首次要联网下载约 40MB。

但构建产物会过期：用 `--check` 卡住

单文件 .bat 是构建产物，一旦改了源码却忘了重新生成，发出去的就是旧版本。所以有个 --check 模式：从已提交的 .bat 里还原出 .pyz，逐文件比对是否与当前源码一致，不一致就非零退出，直接卡在 CI 里。

1
2

x vidgrab-standalone.bat 与当前源码不一致，请重新生成：
    已过期 vidgrab/cli.py

踩坑 1：cmd 注释里的 `->` 会真的创建文件

批处理里写 rem 双击 -> 打开菜单 看起来人畜无害。但 cmd 会把 rem/echo 行里没有被引号包住、也没用 ^ 转义的 < > | & 当作重定向符——于是真的会在磁盘上创建一个名为「打开菜单」的空文件。

作者的做法是写了个审计函数，构建时扫描所有 rem/echo 行并对危险字符报错：

_DANGER_RE = re.compile(r"(?<!\^)[<>|&]")

def audit_bat(text: str, label: str) -> list[str]:
    ...
    stripped = re.sub(r'"[^"]*"', '""', st)   # 引号内的字符是安全的
    for m in _DANGER_RE.finditer(stripped):
        problems.append(f"{label} 第 {i} 行出现 {m.group()!r}：{st[:70]}")

后来统一把 -> 换成了全角 →，并把审计挂进构建自检——cmd 的坑也适用于 Windows，不只是老式 DOS。

踩坑 2：Python 3.9 不认 f-string 里的多行表达式

项目声明支持 Python 3.9+，但下面这种写法只有 **3.12+（PEP 701）**才合法：

1
2
3

# ❌ 3.9~3.11 报 "EOL while scanning string literal"
say(f"    {dim(_s("（输入 0 或 q 可退出）",
                  "(0 or q to quit)"))}")

3.9~3.11 的 f-string 里不能出现跨行的表达式，也不能复用同种引号。所以把 _s(...) 提到 f-string 外面：

1
2

hint = _s("（输入 0 或 q 可退出）", "(0 or q to quit)")
say(f"    {dim(hint)}")

问题在于：compileall 这类语法检查也发现不了——它是运行时才炸。于是项目补了一个不联网、不需要 pytest 的冒烟测试，专门覆盖这类跨版本问题。

踩坑 3：uv.lock 和镜像源是绑定的

开发机的 pypi.org 被 DNS 解析到 fake-ip、索引页只有 ~15 KB/s，而阿里云镜像是 ~1.6 MB/s。所以项目默认走阿里云镜像。但代价是：

uv.lock 会记录每个包是从哪个索引解析来的——当前锁文件里的引用全部指向阿里云镜像。

于是在用官方源的环境里执行 uv sync，uv 会判定锁文件过期、重新解析并改写 uv.lock（git status 变脏）。CI 的对策是显式对齐镜像源：

1
2

env:
  UV_DEFAULT_INDEX: https://mirrors.aliyun.com/pypi/simple/

这样 CI 和本地看到的是同一个索引，锁文件才稳定。

踩坑 4：Windows 控制台的 ANSI 和 UTF-8

这是两个独立的问题。

其一，传统 cmd.exe 默认不解析 ANSI 转义序列，不开启的话彩色输出会变成 ←[32m 这类乱码，进度条也无法原地刷新。需要手动开启 VT 处理：

1
2

# ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
kernel32.SetConsoleMode(handle, mode.value | 0x0004)

其二，默认 GBK 代码页下中文会乱码，需要强制 UTF-8：

`1`	`stream.reconfigure(encoding="utf-8", errors="replace")`

此外还留了一个纯 ASCII 模式（VIDGRAB_ASCII=1），给字体缺字或乱码的老终端兜底。

让「双击」真的零门槛

一个「双击即用」的工具，难点其实在环境准备。run.bat 做了三级兜底，尽可能不让用户手动干活：

1
2

装 uv：winget  →  pip  →  官方安装脚本
同步依赖：阿里云镜像  →  清华镜像  →  退回最小依赖（不含内置 ffmpeg）

CI 也用矩阵在三套环境上验证，尤其是声明的最低版本和主目标平台：

matrix:
  include:
    - { os: ubuntu-latest,  python: "3.9"  }   # 声明的最低版本
    - { os: ubuntu-latest,  python: "3.13" }
    - { os: windows-latest, python: "3.13" }   # 主要目标平台

跑的不只是编译：语法检查、导入检查、冒烟测试、CLI 冒烟，以及「单文件版是否与源码同步」。那个不联网、不依赖 pytest 的冒烟测试，正好补上 compileall 覆盖不到的运行时问题（比如上面那个 3.9 的 f-string 坑）。

小结

这个项目的功能不复杂，本质是给 yt-dlp 套壳。但要真正做到「双击即用」，得同时处理好这几类问题：

分发：单文件自解压 + --check 防止产物过期；
平台怪癖：cmd 的重定向陷阱、Windows 控制台编码与 ANSI；
跨版本兼容：低版本 Python 的语法差异，且静态检查发现不了，只能靠运行时测试；
依赖可复现：uv.lock 与索引源绑定，需要本地和 CI 对齐。

比起「写个脚本调 yt-dlp」，这些才是把它变成给别人也能用的工具所需要的部分。

项目地址：liku-yu/video-downloader（MIT License）。

相关阅读：

把 yt-dlp 封装成好用的下载器：vidgrab 的设计笔记 —— 分层设计与配置驱动的另一半
用 Minecraft 红石入门数字电路

yt-dlp 技术解析：一条视频是怎么被解析、选择并下载的

Sun, 20 Sep 2026 00:00:00 +0000

很多人对 yt-dlp 的印象是「一条命令下载视频」。但它其实是一条完整的管线：从 URL 匹配到对应的站点解析器，抽取出结构化的元数据，再从几十种视频流里按规则挑出要下的那几个，最后交给下载器和 ffmpeg 完成合并。

理解这条管线，比背参数有用得多。这篇就把它拆开看。

免责声明

本文涉及的工具仅用于下载你有权保存的内容。请遵守目标平台的服务协议与当地版权法律，不要用它绕过 DRM 或付费墙。

一条视频的旅程

URL
 │
 ▼
① Extractor（站点解析器）── 匹配站点，抽取统一的 info_dict
 │
 ▼
② formats 列表 ── 一个视频往往有几十种流（分辨率/编码/容器/是否含音轨）
 │
 ▼
③ 格式选择（-f / -S）── 从 formats 里挑出要下载的流
 │
 ▼
④ Downloader ── 直链下载，或按分片（HLS/DASH）并发下载
 │
 ▼
⑤ PostProcessor ── 用 ffmpeg 合并音视频、转码、嵌入字幕/封面/元数据
 │
 ▼
输出文件

下面逐段看。

① Extractor：把每个网站翻译成统一的 info_dict

yt-dlp 内置上千个 extractor（站点解析器），每个负责一个（或一类）网站。它的职责是把网页或接口返回的内容，翻译成一份统一结构的 info_dict——这是整条管线的通用货币。

因为平台差异被 extractor 吸收掉了，后面的格式选择、下载、后处理才能对所有站点一视同仁。

1
2
3

yt-dlp --list-extractors        # 列出所有解析器
yt-dlp -F "<链接>"               # 列出该视频的全部 formats
yt-dlp -J "<链接>"               # 打印完整 info_dict（JSON）

info_dict 里比较关键的字段：

字段	含义
`id` / `title`	视频 id 与标题
`uploader` / `channel`	作者 / 频道
`duration` / `upload_date`	时长 / 发布日期
`formats`	可用格式列表（后文的核心）
`entries`	播放列表的条目列表
`webpage_url` / `url`	页面地址 / 媒体直链
`extractor_key`	命中它的解析器名

播放列表会体现在 entries 上。默认会对列表里每个视频做完整解析，如果只想快速拿到条目列表（不解析每个视频），可以用：

`1`	`yt-dlp --flat-playlist -J "<播放列表链接>"`

代价是部分元数据会缺失——这也是为什么工具里常见「先 flat 拿列表、再按需补全」的两段式做法。

② formats：一个视频为什么有几十种流

以 YouTube 为例，同一支视频通常提供多种分辨率 × 编码 × 容器的组合，而且视频流和音频流往往是分开的（DASH 协议的特性）：

137  mp4  1920x1080  avc1     (仅视频)
248  webm 1920x1080  vp9      (仅视频)
140  m4a  audio      aac      (仅音频)
251  webm audio      opus     (仅音频)
18   mp4  640x360    avc1+aac (视频+音频合体)

format code（如 137）是 extractor 特定的，不同站点不通用；
高清画质几乎都是「视频流 + 音频流」分离的，想要一个能播放的文件就必须合并——这正是 ffmpeg 存在的意义；
低清往往有「音视频合体」的格式，不依赖 ffmpeg 也能直接下。

③ 格式选择：一门迷你语言

默认行为

不传任何参数时，yt-dlp 的默认选择等价于：

`1`	`yt-dlp -f "bestvideo*+bestaudio/best"`

含义是：优先选「最佳含视频的流」+「最佳纯音频流」并合并；如果前者已经自带音频，就直接用它；实在不行退回最佳合体格式。

注意 bv* 和 bv 的区别：bv*（带星号）表示「含视频的流，可能也有音频」，bv 则要求纯视频。

特殊名称

选择器	含义
`best` / `b`	同时含视频和音频的最佳格式
`bestvideo` / `bv`	最佳纯视频格式
`bestvideo` / `bv`	最佳含视频格式（可能也含音频）
`bestaudio` / `ba`	最佳纯音频格式
`worst` / `w`	同时含视频和音频的最差格式
`all`	所有格式（配合过滤器用）
`mp4` / `webm`	该扩展名的最佳单文件格式
`137`	指定 format code（站点相关）

三个运算符

运算符	作用	例子
`+`	合并多个流（需 ffmpeg）	`bv+ba`
`/`	回退：左边优先，不可用则用右边	`22/17/18`
`,`	多选：全部下载（而非只挑一个）	`137,140`

组合起来可以表达相当复杂的偏好，例如「优先 1080p 以内、mp4 封装」：

`1`	`yt-dlp -f "bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080]"`

过滤器：用 `[...]` 写条件

方括号里可以放条件。数值字段支持 < <= > >= = !=：

`1`	`yt-dlp -f "bv[height<=?720][tbr>500]"`

常用的数值字段有 height、width、fps、filesize、tbr、abr、vbr、asr、audio_channels 等。

字符串字段则支持 =（等于）、^=（前缀）、$=（后缀）、*=（包含）、~=（正则），并可用 ! 取反：

1
2

yt-dlp -f "bv[vcodec^=avc1]"      # H.264 编码
yt-dlp -f "ba[ext=m4a]"           # m4a 音频

一个容易被忽略的细节：字段值未知时，该格式会被排除。如果希望「未知也算通过」，在比较符后加 ?：

`1`	`yt-dlp -f "bv[height<=?720]" # 未知高度的也纳入候选`

`-S`：换一种更清晰的思路

用 -f 写「最差画质」是个常见误区：worst 选的是所有维度都最差的格式，而不是体积最小的。更合理的做法是用 -S（--format-sort）定义什么叫「最好」：

1
2
3

yt-dlp -S "+size,+br"        # 体积最小
yt-dlp -S "res:720"          # 不超过 720p 的最佳（没有更小的就选最小的）
yt-dlp -S "res:1080,vcodec:avc1,fps"   # 多字段依次排序

排序规则：

字段默认降序，前缀 + 改为升序（+size = 越小越优先）；
field:value 表示「偏好接近该值」（res:720 即不超过 720p 的更大者）；
field~value 则偏好「最接近」该值（filesize~1G）。

默认排序字段是 lang,quality,res,fps,hdr:12,vcodec,channels,acodec,size,br,asr,proto,ext,hasaud,source,id，其中 hdr:12 意味着默认不优先 Dolby Vision（兼容性考虑）。

Tip

想看清 yt-dlp 到底怎么排的，用 yt-dlp -v -F "<链接>"——它会按「最差 → 最好」把 formats 打印出来，正好可以验证你的 -S 有没有按预期生效。

④ Downloader：分片、并发与反爬

拿到选中的流后，下载器开始工作。要点：

分片下载：HLS/DASH 视频由许多小分片组成。-N/--concurrent-fragments 可以并发拉分片，默认是 1，适当调大能显著提速：

`1`	`yt-dlp -N 8 "<链接>"`

断点续传：默认会写 .part 临时文件，中断后重跑可续传（--no-part 可关闭）。
限速与礼貌请求：面对有风控的站点，反爬手段通常是组合拳：

1
2

yt-dlp --limit-rate 2M --sleep-interval 3 --retries 20 \
       --cookies-from-browser chrome --impersonate chrome "<链接>"

其中 --cookies-from-browser 直接读取浏览器登录态（B 站高清、需要登录的内容都靠它），--impersonate 则伪装浏览器 TLS 指纹。

⑤ PostProcessor：ffmpeg 真正负责的部分

下载只是拿到一堆流，后处理才把它们变成一个正常文件。常见的后处理器：

选项	作用
`--merge-output-format mp4`	合并音视频时使用指定容器
`-x` / `--extract-audio`	只保留音频
`--audio-format mp3`	音频转码为 mp3（依赖 ffmpeg）
`--embed-metadata`	写入标题/作者等元数据
`--embed-thumbnail`	把封面嵌入文件
`--embed-subs`	把字幕嵌入视频
`--remux-video` / `--recode-video`	重封装 / 重编码
`--sponsorblock-remove`	按 SponsorBlock 数据剪掉赞助片段

这些操作几乎都由 ffmpeg 完成。所以「ffmpeg 没装」的后果不是不能下载，而是高清视频无法合并、无法转码——你会得到分离的视频流和音频流。用 --ffmpeg-location 可以指定 ffmpeg 路径。

CLI 只是 Python API 的一层壳

命令行所有选项，本质上都是在往一个 params 字典里写值，然后交给 YoutubeDL：

from yt_dlp import YoutubeDL

opts = {
    "format": "bv*+ba/b",
    "outtmpl": "%(title).120s [%(id)s].%(ext)s",
    "progress_hooks": [lambda d: print(d.get("status"))],
}

with YoutubeDL(opts) as ydl:
    info = ydl.extract_info(url, download=False)  # 只解析，不下载
    ydl.download([url])                            # 执行下载

几个关键的扩展点：

progress_hooks：下载进度回调，拿到 downloaded_bytes / total_bytes / speed / eta；
postprocessor_hooks：后处理阶段回调，能拿到合并后的 filepath；
logger：接管日志输出。特别注意：设置了 ignoreerrors=True 后，下载失败不会抛异常，错误只会走 logger 的 error()——不接管 logger 就会把失败误判成成功；
postprocessors：用字典声明后处理链，效果等同于上面的 CLI 选项。

这也是各类「给 yt-dlp 套壳」的工具（包括我自己的 vidgrab）普遍采用的接入方式。

实用速查

需求	命令
只看信息不下载	`yt-dlp -J <url>`
列出可用格式	`yt-dlp -F <url>`
限高 1080p	`yt-dlp -S "res:1080" <url>`
只要音频	`yt-dlp -x --audio-format mp3 <url>`
批量 + 跳过已下	`yt-dlp -a urls.txt --download-archive done.txt`
登录态	`yt-dlp --cookies-from-browser chrome <url>`
分片加速	`yt-dlp -N 8 <url>`

小结

yt-dlp 的强大，来自它把「解析 → 格式选择 → 下载 → 后处理」清晰分层：

Extractor 吸收各站点差异，产出统一的 info_dict；
格式选择是一门小而完整的表达式语言：+///, 三个运算符、[...] 过滤器、以及更清晰的 -S 排序；
Downloader 处理分片、并发与反爬；
PostProcessor 借助 ffmpeg 把流变成能播放的文件。

理解这套结构之后，那些看起来密集的参数就有了共同的心智模型——你不必记住每一条，只需要知道「我现在在哪一层」。

相关阅读：

当游戏引擎也有竞态条件：从 Minecraft 红石看时序设计

Fri, 18 Sep 2026 00:00:00 +0000

写业务代码时，「竞态条件」是个绕不开的词：两个操作谁先谁后不确定，结果就不确定，于是出现了偶发 Bug、难以复现、换个环境就好。

有意思的是，Minecraft 的红石系统里有一模一样的坑。而且因为它的时间尺度和空间边界都被明确暴露出来，反而是理解竞态的好教具。

游戏没有「实时」，只有游戏刻

Minecraft 世界不是连续演化的，而是以固定的时间片推进。所有逻辑都挂在这个节拍上：

单位	换算	角色
游戏刻 gt	1 秒 = 20 gt（每刻 50ms）	游戏主循环的最小时间片
红石刻 rt	1 rt = 2 gt = 0.1 秒	红石元件的延迟计量单位

这和任何事件循环是同一个模型：它不是「发生即处理」，而是「攒到一个 tick，按顺序处理一批」。中继器的 1–4 档延迟、活塞的伸缩、比较器的响应，全都在这个离散网格上排队。

1
2
3

真实时间 →  0ms    50ms   100ms   150ms  ...
游戏刻   →   t0     t1      t2      t3
                └──── 每刻处理一批方块更新 ────┘

关键点：在同一个 tick 内，多个事件的处理顺序是由引擎内部实现决定的。只要你的设计依赖「A 一定先于 B」，而 A、B 又在同一 tick 内被触发，那你就踩进了未定义行为的领地。

同类问题一：单刻脉冲会「丢事件」

中继器、比较器这类元件的响应，有一个容易忽略的前提——输入必须维持足够长的时间。如果产生的是一个只有一个 tick 宽的瞬时脉冲，比较器很可能根本来不及响应，事件就被漏掉了。

这几乎是前端里同一个 tick 内连续 setState 被批处理、或事件在下一帧才被消费的翻版：你以为发出去了，实际上接收方还没轮到执行。

对策也很直白：不要假设接收方随时待命。要么用中继器把窄脉冲拉宽到接收方来得及响应，要么在接收端加一个锁存器先「接住」信号，再异步处理。这就是电路里的缓冲 / 背压。

同类问题二：方块更新的「水平 vs 垂直」顺序

这是红石里最经典的竞态来源：当一次更新同时向水平和垂直方向传播时，两条路径的传播顺序并不保证一致。谁先到达、谁后到达，可能因上下文而变化。

如果你的电路恰好对到达顺序敏感（比如两条路径各控制一个活塞，而它们必须先左后右），那装置就会表现得时好时坏——典型的偶发 Bug。

它在软件里的对应物太多了：

红石现象	软件对应
水平/垂直更新顺序不确定	并发任务完成顺序不确定
依赖某个方向的更新先到	依赖 `Promise` 的 resolve 顺序
装置「时好时坏」	竞态导致的偶现失败
同一结构在不同位置表现不同	换个环境 / 换个机器就复现不了

对策：不要指望引擎保证顺序，而是用中继器把顺序显式写出来。给其中一条路径加 1 rt 延迟，先后关系就从「不确定」变成「确定」。在并发编程里，这对应的就是用队列 / 序列化 / 加锁把并发改成有序。

同类问题三：跨区块边界的「卡刻」

Minecraft 的世界按**区块（chunk）**划分，区块是加载、卸载、乃至并行处理的基本单位。当一个装置横跨两个区块时，问题来了：区块边界上的刻推进并不总是同步的，在加载/卸载的瞬间尤其容易「卡刻」——装置停住不动了。

把它类比成分片系统就很好懂：一个事务跨了两个分片，而两个分片的时钟/提交时机不一致。轻则延迟，重则状态不一致。

对策：把核心闭环放在同一个区块内。设计时先用 F3 + G 打开区块边界显示，确认机器最关键的反馈回路不跨越边界。这就是分布式系统里的数据局部性（data locality）——让强相关的东西待在一起，避免跨节点协调。

一条经验法则

红石装置的核心反馈回路，尽量收敛到同一个区块内。跨区块不是不能做，而是每一次跨越都在向引擎「借」顺序保证，而这些保证在区块加载/卸载的边界上并不可靠。

同类问题四：把「未修复的特性」当时序契约

BUD（方块更新检测）依赖活塞的准连接性，零刻脉冲（0-tick）依赖单刻内完成一次完整动作——这些技巧效率极高，但它们全都建立在引擎某个具体实现细节之上，而不是被承诺的行为。

这就像在代码里依赖某个库的私有内部实现，或者依赖语言的未定义行为：能跑，而且跑得很爽，但升级一次就可能全线崩塌。

对策有两条：

隔离：把依赖特性的部分做成独立模块，别让它渗透进整套产线的骨架
验证：大版本更新后先小范围试跑，确认行为没变，再决定要不要批量建造

这其实就是软件里的依赖风险管控 + 灰度发布。

把红石时序映射到软件工程

把上面几点收拢成一张对照表，会发现两边几乎是同一套知识：

红石 / Minecraft	软件工程
游戏刻、红石刻	事件循环 / 固定时间步长
单刻脉冲丢失	事件丢失、批处理、丢帧
更新顺序不确定	并发完成顺序不确定
中继器显式延迟	队列 / 序列化 / 加锁
跨区块卡刻	跨分片事务、跨节点时序
`F3+G` 看区块边界	可观测性 / tracing
BUD、0-tick	依赖未定义行为 / 私有 API
大版本先小范围验证	灰度发布 / canary
核心闭环同区块	数据局部性

小结

红石装置调试时那种「怎么又不动了」「换台电脑就好了」的挫败感，和后端排查竞态 Bug 时几乎一模一样。区别在于：Minecraft 把时间单位和空间边界都摊在你面前，竞态不再是看不见的幽灵，而是能拿中继器和区块边界直接观察、直接消除的东西。

所以反过来，用红石练手时序思维是划算的：

任何依赖「谁先谁后」的设计，都要问一句：这个顺序是谁保证的？
顺序没有保证时，就用显式的延迟、队列或约束把它变成确定
需要强一致的部分，尽量放在同一个边界内
依赖实现细节的优化，永远准备好回滚方案

相关阅读：

用 Minecraft 红石入门数字电路 —— 红石数字逻辑的基础
深入理解 useEffect 的依赖数组 —— 前端里的同类竞态问题

用 Minecraft 红石入门数字电路：从非门到 RS 锁存器

Fri, 18 Sep 2026 00:00:00 +0000

很多人第一次接触「数字电路」是从课本上的逻辑门符号开始的：一个三角形加个圈就是非门，两条线交叉就是锁存器。符号记住了，但它到底在干什么、为什么需要它，往往一直悬着。

Minecraft 的红石系统提供了一个难得的中间层：它足够简单，你能亲手把每一根导线、每一个逻辑门搭出来；又足够完整，你可以在里面实现从非门到存储器的全部基础电路。这篇文章就借红石，把数字电路的核心概念串一遍。

红石系统 = 一套数字电路

红石可以理解为 Minecraft 的「电力系统」，由三部分组成：

数字电路	红石对应物	作用
电源 / 高电平	红石块、拉杆、按钮、红石火把	提供信号
导线	红石粉	传输信号
缓冲器 / 延迟线	中继器	刷新信号、引入延迟、单向导通
逻辑门	红石火把、比较器	运算
输出 / 指示灯	红石灯、活塞、门	执行动作

它和真实数字电路最大的区别是：红石的「电平」不是只有 0 和 1。

信号强度：不是二值，而是 0–15

电源（火把、拉杆、按钮）输出满级信号 15，红石粉每传播一格衰减 1 级：

`1`	`15 → 14 → 13 → … → 1 → 0`

也就是说，单股红石线最长只能传 15 格，到 0 就彻底失效。想继续往前传，必须在中间插入中继器把信号重新拉回 15。

这个特性和真实电路里的信号衰减、网络里的传输距离限制是一回事：任何长距离链路都需要中继/放大。这也解释了为什么红石电路里「中继器」出现频率极高——它既是逻辑元件，也是物理上的信号再生器。

电压类比：可以把 0–15 看成模拟电压等级，而逻辑门真正读取的只是「是否大于 0」。这也正是数字电路从模拟信号里提取 0/1 的过程。

第一个逻辑门：红石火把就是非门

数字电路里最基本的门是非门（NOT）：输入 0 输出 1，输入 1 输出 0。

红石火把默认是点亮的（输出 15）。当它附着的方块被供能时，火把会熄灭——输出从 1 变成 0。这恰好就是非门的真值表：

输入 A	输出 Q = ¬A
0	1
1	0

\text{NOT}: Q = \overline{A}

在电路图里，一个非门就是一个三角形加一个小圆圈；在 Minecraft 里，它就是「一根红石火把 + 一个被供能的方块」。符号和实体第一次对上了。

有了非门，就可以继续往下搭：

非门串联 → 缓冲（两次取反还原，但引入了延迟）
非门并联取最大 → 或门 NOR 基础
多条输入接到同一个火把附着方块 → 只要有一条供能，火把就熄灭

中继器：缓冲器 + 延迟元件 + 二极管

中继器是红石里最被低估的元件，它同时承担了三个数字电路里独立存在的功能：

信号再生：输出固定 15，抵消衰减（缓冲器）
单向导通：信号只能从前端流向后端，反向不通（二极管）
可调延迟：右键切换 1–4 rt 的延迟（延迟线）

把它看成电路里的「带延迟的缓冲器」就很好理解。这三个属性组合起来，让中继器成了时序控制的核心工具——在数字电路里，几乎所有需要「等一会儿再执行」的地方，都需要延迟元件。

时间单位要记牢：

单位	换算	说明
游戏刻 gt	1 秒 = 20 gt	游戏主循环的最小时间片
红石刻 rt	1 rt = 2 gt = 0.1 秒	红石元件的延迟计量单位

中继器的 1–4 档延迟，对应的就是 1/2/3/4 rt，也就是 0.1–0.4 秒。

RS 锁存器：保存 1 bit 的记忆

组合逻辑电路（非门、与门、或门）有个共同点：输出只取决于当前输入。一旦输入消失，输出也就没了。要「记住」状态，就需要带反馈的时序逻辑电路。

最基础的就是 RS 锁存器（SR Latch）：用两个非门交叉耦合，每个门的输出接到另一个门的输入。

它的逻辑是：

Q = \overline{R \lor Q}, \qquad \overline{Q} = \overline{S \lor \overline{Q}}

置位端 S（Set）拉高 → Q 变 1 并保持
复位端 R（Reset）拉高 → Q 变 0 并保持
S、R 都为 0 → 维持上一次的状态（这就是「记忆」）

在 Minecraft 里，把两个红石火把交叉接起来就能得到这个结构：火把 A 的输入来自火把 B 的输出，火把 B 的输入来自火把 A 的输出。拉一下 S 或 R 的拉杆，状态被锁住，松手也不会丢。

这一个结构就撑起了很多装置：

用途	说明
密码门 / 机关	按对顺序后锁定开启状态
电梯楼层记忆	记住当前在哪层
状态标志位	记录「是否已触发」
防抖	把抖动输入锁成稳定状态

从非门到锁存器，是数字电路里「组合逻辑 → 时序逻辑」的分水岭。有了记忆，电路才开始有状态。

时钟电路：让电路自己动起来

锁存器需要有人来拉 S/R，那能不能让电路周期性自己触发？可以，用一个非门把输出接回输入，就构成了振荡器——输出不断在 0/1 之间翻转，这就是时钟信号。

实际搭建时，通常用中继器环来做：把若干个中继器首尾相接成环，信号绕圈传播，每绕一圈就产生一个脉冲。调整中继器数量和档位，就得到不同频率的时钟。

时钟是时序电路的心跳：

驱动重复动作（自动农场、自动收割）
作为计数器的节拍
给状态机提供步进信号

边沿、脉冲与检测

最后补一组概念，它们是把模拟世界里的「变化」转成数字逻辑能处理的「事件」的关键：

概念	含义
上升沿	信号从 0 变 1 的瞬间
下降沿	信号从 1 变 0 的瞬间
正脉冲	0 → 1 → 0 的一次短暂拉高
负脉冲	1 → 0 → 1 的一次短暂拉低
相位	两个信号「同相 / 反相」的关系，反相记作 `!`

边沿检测的典型实现是：让信号走两条路径，一条延迟、一条不延迟，再把两者做比较——只有变化的那一瞬间两条路径状态不同，从而输出一个短脉冲。这个「一个脉冲只触发一次」的思想，正是数字电路里边沿触发触发器的基础。

版本特性提醒

BUD（方块更新检测）、零刻脉冲（0-tick）这类进阶技巧，依赖的是游戏未修复的特性。它们能大幅提升效率，但一旦某个版本修掉对应行为，整套装置就会失效。建议每次大版本更新后先小范围验证，再决定是否批量建造。

小结

把红石和数字电路对照起来，一条清晰的脉络就出现了：

电源/导线      → 信号与传输
非门           → 基本逻辑运算
中继器         → 缓冲 + 延迟 + 单向
RS 锁存器      → 1 bit 存储（时序逻辑）
时钟电路       → 周期性节拍
边沿/脉冲检测  → 事件提取

红石的价值不在于「游戏里能造机器」，而在于它是一个可以被拆开看的数字系统。当你在课本上再看到非门符号或 RS 锁存器时，脑子里能浮现出那两根交叉的红石火把——抽象概念就落地了。

相关阅读：

当游戏引擎也有竞态条件 —— 从工程视角看红石里的时序与竞态问题
想了解信号在长链路里如何衰减与再生，可以拆解一下中继器的三种模式（锁存、单向、延迟档位）

Pagefind 静态搜索技术解析：纯前端也能做的全文搜索

Tue, 08 Sep 2026 00:00:00 +0000

本博客的搜索功能就是基于 Pagefind 实现的。这篇文章讲讲它为什么能在纯静态站点上提供全文搜索，以及它的工作原理。

为什么静态博客需要搜索

静态博客（Hugo、Hexo、Jekyll 等）没有后端、没有数据库，传统的站内搜索需要：

服务端分词 + 倒排索引（如 Elasticsearch）
或者第三方案例服务（如 Algolia，需付费账号）

Pagefind 的答案是：把搜索索引在构建时生成好，运行时在浏览器本地完成检索。这既保留了静态部署的简单，又能提供接近实时的搜索体验。

工作原理总览

构建阶段（Node CLI）
┌────────────────────────────────────────────┐
│  npx pagefind --site public                │
│  ① 爬取 public/ 下所有 HTML                │
│  ② 提取文本 → 分词 → 建立倒排索引           │
│  ③ 压缩输出到 public/pagefind/             │
└────────────────────────────────────────────┘
                │ 产物（纯静态文件）
                ▼
运行时阶段（浏览器）
┌────────────────────────────────────────────┐
│  ① 检测 <html lang> → 加载对应语言索引      │
│  ② 用户输入 → Intl.Segmenter 分词          │
│  ③ 按需加载索引块 → WASM 计算相关度         │
│  ④ 加载片段 → 生成高亮摘要 → 渲染结果       │
└────────────────────────────────────────────┘

构建阶段：索引怎么生成

Pagefind 的 CLI 会爬取构建产物目录，对每个 HTML 页面：

提取正文：去除导航、页脚等重复内容（通过 data-pagefind-body / data-pagefind-ignore 标记控制权重区域）
分词：按语言规则切词，中英文都能处理
建立倒排索引：记录「词 → 出现在哪些页面 + 位置」
压缩输出：索引、片段、语言元数据分别压缩存储

倒排索引长什么样

倒排索引（inverted index）是搜索引擎的核心数据结构——反向的目录：给定一个词，立刻查到它出现在哪些文档的哪些位置：

{
  "防抖":   [{ "doc": 3, "pos": [12, 58], "weight": 0.42 }],
  "依赖":   [{ "doc": 4, "pos": [3, 27] }],
  "grid":   [{ "doc": 5, "pos": [0, 40, 99] }]
}

相比正排（文档 → 词）需要扫描全库，倒排索引让查询复杂度降到只查相关条目，这也是 Pagefind 能秒回的原因之一。

控制哪些内容参与索引

默认整页都参与，但可以用标记颗粒化控制：

<!-- data-pagefind-body：只索引本区域（正文），导航/页脚被忽略 -->
<div data-pagefind-body>
  <article>这里的内容会进入搜索</article>
</div>

<!-- data-pagefind-ignore：显式排除某块 -->
<footer data-pagefind-ignore>版权信息不参与搜索</footer>

本站主题的正文区域就带了 data-pagefind-body，所以搜索只命中文章内容，不会把导航菜单、页脚版权都搜出来。

生成的核心文件（都在 public/pagefind/ 下）：

文件	作用
`pagefind-entry.json`	入口元数据（版本、语言、页面数）
`index/zh_*.pf_index`	倒排索引块（词 → 文档）
`fragment/zh_*.pf_fragment`	每个页面的内容片段（用于生成摘要）
`wasm.*.pagefind`	搜索内核（Rust 编译的 WebAssembly）
`pagefind.js` / `pagefind-worker.js`	运行时桥接 + Web Worker

运行时：浏览器怎么搜

1. 语言自动检测

1
2
3

// 从 <html lang> 读取语言
const langCode = document.querySelector("html").getAttribute("lang");
// 加载对应语言的索引和分词元数据

本站 <html lang="zh">，Pagefind 自动选择中文索引。

2. 分词：Intl.Segmenter

中文没有空格分词，Pagefind 利用浏览器内置的 Intl.Segmenter 按语言切词：

const segmenter = new Intl.Segmenter("zh", { granularity: "word" });
for (const { segment: word } of segmenter.segment("防抖函数")) {
  console.log(word); // 逐个切出的词
}

这就是为什么中文文章能精确搜到「防抖」「依赖数组」等关键词。

3. 按需加载索引块

Pagefind 不会把整个索引都塞进浏览器，而是先问 WASM 内核哪些块包含了查询词，再只加载那些块：

// 向 WASM 请求：哪些索引块包含这些词
const index_array = backend.request_indexes(ptr, term);
// 按返回的哈希只加载需要的块
index_array.forEach(hash => loadChunk(hash));

4. 相关度排序：BM25

检索核心是 BM25 算法（信息检索领域的经典排序模型），公式如下：

\text{score}(D,Q) = \sum_{i=1}^{n} \text{IDF}(q_i) \cdot \frac{f(q_i, D) \cdot (k_1 + 1)}{f(q_i, D) + k_1 \cdot (1 - b + b \cdot \frac{|D|}{\text{avgdl}})}

其中：

$f(q_i, D)$ — 词 $q_i$ 在文档 $D$ 中出现的频率
$|D|$ — 文档长度， $\text{avgdl}$ — 平均文档长度
$k_1, b$ — 调节参数（词频饱和度、长度归一化）
$\text{IDF}(q_i)$ — 逆文档频率（越稀有的词权重越高）

直观理解：关键词出现越多、文档越短、词越稀有 → 得分越高。Pagefind 的 WASM 内核里就是这套计算。

5. 摘要与高亮

搜索到结果后，Pagefind 从 fragment 里加载页面片段，选择关键词最密集的段落作为摘要，并自动包上 <mark> 高亮：

<p>
  防抖（debounce）是前端高频场景的基础工具：**在事件停止触发一段时间后…
  <mark>防抖</mark>把"连续触发"折叠成"一次执行"…
</p>

在本站的接入

本站通过 npm 脚本串联构建与索引：

`1`	`npm run build # = hugo + pagefind --site public`

搜索页（content/search.md）用主题自带的模板挂载 UI：

<link rel="stylesheet" href="pagefind/pagefind-ui.css">
<div id="search"></div>
<script src="pagefind/pagefind-ui.js"></script>
<script>
  new PagefindUI({
    element: "#search",
    showSubResults: true,
    translations: { placeholder: "搜索..." }
  });
</script>

优缺点

优点

零后端：纯静态文件即可部署，GitHub Pages / Vercel / Nginx 都行
隐私好：搜索在浏览器本地完成，不把查询发给第三方（Algolia 会）
无费用：不依赖付费搜索服务
速度快：索引分块按需加载，WASM 内核高效

注意

构建多一步：每次要重新生成索引（已打包进 npm run build）
中文无词干还原：不支持英文那样搜索复数/时态变形（对中文无影响）
无服务端统计：看不到搜索词统计（需要自行埋点）

小结

Pagefind 的思路很巧妙：把"建索引"这步重活放在构建时，把"检索"放在浏览器端的 WASM 里。静态站点因此也能拥有带相关度排序、高亮摘要的全文搜索，且部署、隐私、成本都比第三方搜索服务更有优势。

如果你也想在自己的 Hugo / 静态站里加搜索，试试 npm i -D pagefind && npx pagefind --site public，配上本文前面的配置即可。

用 TypeScript 写一个可即时取消的防抖函数

Fri, 28 Aug 2026 00:00:00 +0000

防抖（debounce）是前端高频场景的基础工具：在事件停止触发一段时间后，才执行最后一次回调。

为什么需要防抖

输入框的实时搜索、窗口 resize、按钮连点，这些场景的事件频率远超我们的处理能力。防抖把"连续触发"折叠成"一次执行"，是最廉价的性能优化手段之一。

防抖 vs 节流

两者常被混淆，先分清：

	防抖 debounce	节流 throttle
行为	停止触发后延迟执行最后一次	固定间隔内最多执行一次
场景	输入搜索、窗口 resize 结束	滚动监听、拖拽、游戏频率限制
类比	电梯等人：没人进就关门	限流：每 100ms 最多放一次

1
2
3

连续点击 10 次（间隔 50ms）：
  debounce(300ms)  → 停止后第 300ms 执行 1 次
  throttle(300ms)  → 前 300ms 内最多执行 1 次

第一版：最简实现（trailing edge）

function debounce<F extends (...args: any[]) => void>(
  fn: F,
  delay = 300
): (...args: Parameters<F>) => void {
  let timer: ReturnType<typeof setTimeout> | null = null;

  return (...args: Parameters<F>) => {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
}

关键在泛型 F：Parameters<F> 保留了原函数参数类型，调用方无需任何类型断言——这也是 ReturnType / Parameters 这套内置工具类型的核心用法。

第二版：支持取消与立即执行（flush）

光靠闭包收尾还不够，业务上常需要：

cancel()：组件卸载时作废未执行的调用
flush()：立即执行积压的最后一次（比如表单提交前）

interface Debounced<F extends (...args: any[]) => void> {
  (...args: Parameters<F>): void;
  cancel(): void;
  flush(): void;
}

function debounce<F extends (...args: any[]) => void>(
  fn: F,
  delay = 300
): Debounced<F> {
  let timer: ReturnType<typeof setTimeout> | null = null;
  let lastArgs: Parameters<F> | null = null;

  const debounced = (...args: Parameters<F>) => {
    lastArgs = args;                       // 记下最新参数
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      timer = null;
      fn(...args);
    }, delay);
  } as Debounced<F>;

  debounced.cancel = () => {
    if (timer) clearTimeout(timer);
    timer = null;
    lastArgs = null;                       // 连参数一起清掉
  };

  debounced.flush = () => {
    if (timer && lastArgs) {               // 有积压才立即执行
      clearTimeout(timer);
      timer = null;
      fn(...lastArgs);
      lastArgs = null;
    }
  };

  return debounced;
}

注意 flush 里要保留 lastArgs 在调用前读取——否则 clearTimeout 之后再次读取会拿到 null。

进阶：leading edge（先执行一次，再防抖）

默认版本是"停止后才执行"（trailing）。但有时想要"第一次立即触发展，后续节流"——典型的抢购按钮、防重复提交：

function debounceLeading<F extends (...args: any[]) => void>(
  fn: F,
  delay = 300
): Debounced<F> {
  let timer: ReturnType<typeof setTimeout> | null = null;
  let lastArgs: Parameters<F> | null = null;

  const debounced = (...args: Parameters<F>) => {
    lastArgs = args;
    if (timer !== null) return;            // 还在窗口期内 → 忽略

    fn(...args);                           // 首次立即执行
    timer = setTimeout(() => {
      timer = null;
      // 结束后若还有新输入，可在 next tick 再触发（可选：trailing 补发）
    }, delay);
  } as Debounced<F>;

  // cancel / flush 略，与上一版类似
  return debounced;
}

完整 Lodash 支持 { leading: true, trailing: true } 双模式，本文聚焦核心思路，两个方向各给一版。

this 绑定的坑

上两版用 fn(...args) 调用，会丢失 this。如果原函数依赖 this（对象方法）：

const obj = {
  value: 42,
  print() { console.log(this.value); }
};
const d = debounce(obj.print, 100);   // ❌ 调用时 this 是 undefined（严格模式）
d();

修复：在调用时显式回传 this：

type DebounceFn<F> = F & { cancel(): void; flush(): void };

function debounce<F extends (this: unknown, ...args: any[]) => void>(
  fn: F,
  delay = 300
): F & { cancel(): void; flush(): void } {
  let timer: ReturnType<typeof setTimeout> | null = null;

  function debounced(this: unknown, ...args: Parameters<F>) {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);  // ✅ 用 apply 回传 this
  }

  debounced.cancel = () => { if (timer) clearTimeout(timer); timer = null; };
  debounced.flush = function (this: unknown) { /* 同样 apply */ };

  return debounced as typeof debounced & { cancel(): void; flush(): void };
}

const d = debounce(obj.print, 100);
obj.d = d;
obj.d();        // ✅ this 指向 obj，输出 42

React 中集成（useRef 保引用稳定）

React 组件里直接 const onSearch = debounce(...) 会导致每次渲染都新建防抖函数，定时器状态丢失。正确做法是 useRef 存一份：

import { useRef, useCallback } from "react";

function SearchBox() {
  const debouncedRef = useRef<ReturnType<typeof debounce> | null>(null);

  // 只在挂载时创建一次
  if (!debouncedRef.current) {
    debouncedRef.current = debounce((keyword: string) => {
      fetch(`/api/search?q=${keyword}`);
    }, 500);
  }

  // 卸载时清理
  useEffect(() => {
    const d = debouncedRef.current!;
    return () => d.cancel();
  }, []);

  return <input onChange={e => debouncedRef.current!(e.target.value)} />;
}

更省事的方式：用 useRef 存最新回调（useLatest），避免闭包陈旧值；或直接引入 lodash/debounce 封装成 useDebouncedCallback。

使用示例

1
2
3

const onSearch = debounce((keyword: string) => {
  console.log("请求搜索接口：", keyword);
}, 500);

输入框每次 keyup 都调用 onSearch(value)，但只有停顿 500ms 后才会真正发出请求；组件卸载时调用 onSearch.cancel()，避免回调在组件销毁后触发导致内存泄漏。

1
2
3

// flush 场景：搜索框失焦/提交时立即拿到结果
input.addEventListener("keyup", () => onSearch(input.value));
input.addEventListener("blur", () => onSearch.flush());  // 不等防抖结束

单元测试（fake timers）

验证防抖逻辑，用 vi.useFakeTimers()（Vitest）或 Jest 的 fake timers：

import { vi, describe, it, expect } from "vitest";

describe("debounce", () => {
  it("只在停止触发后执行一次", () => {
    vi.useFakeTimers();
    const fn = vi.fn();
    const d = debounce(fn, 300);

    d();
    vi.advanceTimersByTime(100);
    d();
    vi.advanceTimersByTime(100);
    d();                          // 最后一次触发
    expect(fn).not.toHaveBeenCalled();

    vi.advanceTimersByTime(300);  // 超过延迟
    expect(fn).toHaveBeenCalledTimes(1);
  });

  it("cancel 后不再执行", () => {
    vi.useFakeTimers();
    const fn = vi.fn();
    const d = debounce(fn, 300);

    d();
    d.cancel();
    vi.advanceTimersByTime(500);
    expect(fn).not.toHaveBeenCalled();
  });

  it("flush 立即执行积压调用", () => {
    vi.useFakeTimers();
    const fn = vi.fn();
    const d = debounce(fn, 300);

    d(1);
    d.flush();
    expect(fn).toHaveBeenCalledWith(1);
  });
});

小结

一个成熟的防抖函数 = 闭包管理定时器 + 泛型保留类型 + cancel/flush 控制流。掌握这三个层次的实现，你不仅能封装出类型安全的工具，也能在 React、组件卸载、表单提交等场景里正确使用它。

延伸阅读：

节流（throttle）实现与防抖几乎同构：换成"记录上次执行时间戳"即可
Lodash 的 debounce 支持 leading/trailing/maxWait，生产项目可直接引入

深入理解 useEffect 的依赖数组

Thu, 20 Aug 2026 00:00:00 +0000

useEffect 的依赖数组（dependency array）是 React 文档里反复强调"不要骗它"的东西。理解它的判定规则，能少踩 80% 的坑——剩下 20% 是竞态问题，本文也一并讲清楚。

依赖数组是什么

useEffect(() => {
  // 副作用逻辑
  return () => {
    // 清理逻辑
  };
}, [dep1, dep2]);

依赖数组只做一件事：告诉 React 什么时候重新执行副作用。 每次渲染后，React 会比较新旧依赖数组，只要有一个元素用 Object.is 判断不相等，就：

先执行上一次的清理函数（如果有）
再执行新的副作用

Object.is 判定的细节

sameValueZero（Object.is 的变体）意味着：

比较	结果	解释
`1 === 1`	相等	原始值按值比较
`NaN === NaN`	相等（`Object.is` 视 NaN 相等）	与 `===` 不同
`{} === {}`	不相等	对象按引用比较
`fn1 === fn2`（每次渲染新建）	不相等	函数按引用比较

关键推论：依赖数组里放对象 / 函数 / 数组，每次渲染都是新引用 → 每次都会触发 effect。这是海量 Bug 的来源。

三个常见陷阱

陷阱 1：忘记加依赖（闭包陷阱）

const [count, setCount] = useState(0);

useEffect(() => {
  const id = setInterval(() => setCount(count + 1), 1000);
  return () => clearInterval(id);
}, []);            // ❌ 依赖数组为空，count 永远闭包住初始值

count 永远是首次渲染闭包里的 0，setCount(count + 1) 会一直把状态设成 1。

正确做法：用函数式更新，让 setState 自己读到最新值：

useEffect(() => {
  const id = setInterval(() => setCount(c => c + 1), 1000);
  return () => clearInterval(id);
}, []);            // ✅ 不引用 count 本身，无需加入依赖

或：把 count 加进依赖数组（每次 count 变化重建定时器）：

useEffect(() => {
  const id = setInterval(() => setCount(count + 1), 1000);
  return () => clearInterval(id);
}, [count]);       // ✅ 逻辑直白但定时器频繁重建

陷阱 2：依赖每次渲染都变（引用不稳定）

1
2
3

useEffect(() => {
  fetchData(props.obj);
}, [props.obj]);   // ❌ props.obj 每次都是新引用 → 无限循环

父组件只要重新渲染，props.obj 就是新对象，effect 永远达不到"稳定"状态，反复触发甚至死循环。

解法：用 useMemo 稳定引用，或依赖原始值：

const obj = useMemo(() => ({ id: props.id, mode: props.mode }), [props.id, props.mode]);
useEffect(() => { fetchData(obj); }, [obj]);

// 或更简单——直接依赖最底层的原始值
useEffect(() => { fetchDataById(props.id); }, [props.id]);

陷阱 3：函数依赖导致反复重跑

// 每次渲染都新建 onSave → effect 每次都重跑
useEffect(() => {
  save(onSave());          // ❌ onSave 引用不稳定
}, [onSave]);

解法是 useCallback 稳定函数：

const onSave = useCallback(() => {
  save(data);
}, [data]);              // 只有 data 变化时 onSave 才换新

useEffect(() => {
  onSave();
}, [onSave]);

竞态问题（最容易忽略的坑）

异步请求 + 用户快速切换，旧请求可能后返回并覆盖新结果：

const [data, setData] = useState(null);

useEffect(() => {
  let cancelled = false;          // ① 用标志位标记"已过期"
  fetch(`/api/user/${id}`)
    .then(res => res.json())
    .then(json => {
      if (!cancelled) setData(json);   // ② 只有未过期才写状态
    });
  return () => { cancelled = true; }; // ③ 清理时把旧请求作废
}, [id]);

原理：effect 重新执行前，React 会先调用上一次的清理函数——把 cancelled 置 true，旧请求的 then 回调即使晚到也不会污染状态。

这是"不要骗依赖"之外的进阶版：即使依赖填对了，异步竞态依然存在。接口请求、轮询、订阅这三类副作用务必带上清理逻辑。

StrictMode 下 effect 执行两次（开发模式）

React 18+ 的 <StrictMode> 在开发模式下会故意挂载 → 卸载 → 再挂载，让 effect 跑两遍：

useEffect(() => {
  console.log("effect 执行");
  return () => console.log("清理");
}, []);
// 开发模式输出：effect → 清理 → effect
// 生产模式输出：effect

这是故意的，目的是暴露"忘记写清理函数"的问题（比如订阅、监听器没解绑）。不要惊慌，也不要靠 useRef 强行跳过——写对清理函数，生产环境只会跑一次。

exhaustive-deps：让 ESLint 帮你把关

eslint-plugin-react-hooks 的 exhaustive-deps 规则会自动检查依赖是否写全：

`1`	`npm install -D eslint-plugin-react-hooks`

// .eslintrc.json
{
  "plugins": ["react-hooks"],
  "rules": { "react-hooks/exhaustive-deps": "warn" }
}

当它提示 React Hook useEffect has missing dependencies，不要靠 // eslint-disable 蒙混——那等于把 bug 留下来。正确流程：

看提示缺了谁
问自己：这个值真的应该触发 effect 吗？
是 → 加进依赖；不是 → 用 useCallback/useMemo 稳定它，或函数式更新化掉

旧 React 时代有人教"依赖数组删掉就是只在挂载时跑一次"——那是误用。真正"只在挂载跑一次"的场景应该没有外部依赖，写了依赖就不该删。

与 useLayoutEffect 的区别

	`useEffect`	`useLayoutEffect`
执行时机	浏览器绘制后（异步）	DOM 更新后、绘制前（同步）
适用场景	数据请求、订阅、埋点	测量 DOM、同步改样式
闪烁风险	无	会阻塞绘制
SSR	不执行	警告（SSR 下不执行）

// 要在绘制前同步调整 DOM —— 用 useLayoutEffect
useLayoutEffect(() => {
  const width = el.getBoundingClientRect().width;
  setLayout({ width });
}, []);

绝大多数场景用 useEffect 就够；只有"改完 DOM 之前必须测量/修正"才需要 useLayoutEffect。

结论

依赖数组不是"性能优化开关"，而是"同步契约"。不要靠删依赖来"修"问题，要搞清楚副作用真正依赖什么。

把依赖数组当作函数参数来思考，大部分疑难 Bug 都能迎刃而解：

依赖什么就写什么，原始值优先
对象/函数用 useCallback / useMemo 稳定引用
有副作用就有清理，异步请求务必防竞态
交给 exhaustive-deps 提醒，但理解它为什么提醒

用 Markdown 写文章：Void 主题写作指南

Mon, 10 Aug 2026 00:00:00 +0000

Hugo + Void 主题的写法主体仍是 Markdown，但这个主题额外提供了目录导航、代码高亮、KaTeX 数学公式、暗色模式等特性。

如何写一篇文章

在 content/posts/ 下新建 my-post.md，文件开头填写 frontmatter：

---
title: "文章标题"
date: 2026-09-07
tags: ["TypeScript", "前端"]
---

支持的可选字段：

description — 摘要，显示在列表卡片
tags — 标签（自动生成标签页）
language — 单篇语言覆盖（如给中文博客里的英文文章标 language: "en"）
numbered: true — 章节自动编号（1 / 1.1 / 1.1.1）

代码高亮

Void 使用 Hugo 内置的 Chroma 高亮，代码块带语言标签与复制按钮，暗/亮模式自动切换配色：

1
2

def greet(name: str) -> str:
    return f"Hello, {name}!"

提示框（Callout）

支持短代码与栅栏两种写法：

Note

这是 info 类型的提示框。

Tip

这是 tip 类型。技术文章中推荐这么做时用它最合适。

Caution

这是 warning 类型。提醒读者注意的坑、边界情况。

Danger

这是 danger 类型，用来警告严重的错误或高风险操作。

支持的 type：info（默认）、tip、warning、danger、neutral。

数学公式（KaTeX）

KaTeX 在构建时渲染（无需客户端 JS），支持 $…$ 行内与 $$…$$ 块级：

行内公式 $E = mc^2$ ，以及块级公式：

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

甚至可以在 callout / 表格里内嵌公式：

定义

状态-动作价值函数：

v_\pi(s_t, a_t) = \mathbb{E}_\pi\left[ \sum_{i=t}^T \gamma^{i-t} r_i \right]

注意：块级公式要换行写，前后留空行；公式里含 \{ 等花括号时用 callout 的栅栏语法（避免误解析）： ```callout {.neutral title="定义"} 把 title 写进属性即可。

目录（TOC）

文章存在标题时自动生成目录：宽屏下显示在右侧栏，窄屏下折叠在文章顶部，带滚动高亮。

写作约定

项目	约定
语言	中文为主，代码注释用英文
格式	`.md`（支持 GFM 表格、代码高亮、KaTeX）
代码块	标注语言名，构建时自动高亮
图片	使用完整 URL，或放在 `static/` 下用 `/xxx.png` 引用
更新	记得同步更新 `date` 字段

想新增内容？直接在 content/posts/ 新建 .md 文件即可。

CSS Grid 常用布局速查表

Fri, 31 Jul 2026 00:00:00 +0000

Grid 一出手，布局焦虑全没有。下面是平时写业务最常用的几种写法，以及藏在写法背后的关键概念。

先理解 fr 单位

fr（fraction，分数）是 Grid 独有的弹性单位，表示剩余空间的比例分配：

.container {
  display: grid;
  grid-template-columns: 240px 1fr 2fr;
  /*         固定宽度  ① ②    */
  /* 两个 fr 列按 1:2 瓜分 240px 之外的所有剩余宽度 */
}

与 flex: 1 类似的逻辑，但更干净：240px 1fr 2fr 一眼可读，无需 flex-basis 那套。

对比：1fr 和 auto 不同——auto 按内容收缩，1fr 至少占据一整行剩余空间。想保持列宽不被内容撑破，用 minmax 兜底（见下）。

两栏布局（侧边栏 + 主内容）

.layout {
  display: grid;
  grid-template-columns: 240px 1fr;
  gap: 24px;
}

/* 希望侧边栏收缩、主内容占满剩余： */
.layout {
  grid-template-columns: minmax(180px, auto) 1fr;
}

响应式卡片墙（auto-fit + minmax）

.cards {
  display: grid;
  gap: 16px;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
}

这是本节最重要的一个写法：每张卡片至少 280px，屏幕宽就自动增多列、窄就自动换行，零媒体查询。

auto-fit vs auto-fill 的差别

两者都是"能放几列放几列"，差别在于列多出来了怎么办：

/* auto-fill：即使没有内容，也留出空轨道（常用于滚动容器占位） */
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));

/* auto-fit：空轨道被折叠，内容列拉伸填满（卡片墙用这个） */
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));

一句话：卡片墙用 auto-fit，需要固定占位格子用 auto-fill。

一行实现水平垂直居中

.center {
  display: grid;
  place-items: center;
}

place-items 是 align-items（垂直）+ justify-items（水平）的合并速记。记住这一行，居中再也不用 position: absolute 那套了。

完整的后台布局模板（grid-template-areas）

适合整页骨架：头部、侧边栏、主区、页脚。用命名区域写布局，结构一目了然：

.app {
  display: grid;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  grid-template-columns: 240px 1fr;
  grid-template-rows: auto 1fr auto;  /* 中间行撑满，头部页脚自适应 */
  height: 100vh;
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main    { grid-area: main; }
.footer  { grid-area: footer; }

换布局只需改 grid-template-areas 的 ASCII 图：

/* 手机端：侧边栏挪到底部 */
@media (max-width: 768px) {
  .app {
    grid-template-areas:
      "header"
      "main"
      "sidebar"
      "footer";
    grid-template-columns: 1fr;
  }
}

隐式网格：grid-auto-rows

不指定行数时，多出来的行是"隐式轨道"，默认 auto（按内容）。要控制它们（比如让所有卡片等高）：

.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  grid-auto-rows: 1fr;   /* 所有自动行等高 */
}

grid-auto-flow 则控制自动排列方向：默认 row（逐行排），column（逐列排）、dense（允许洞补位）。

对齐系统：两条轴四个属性

属性	作用轴	作用对象	示例
`justify-items`	水平	单元格内内容	`center` 让格子内水平居中
`align-items`	垂直	单元格内内容	`center` 让格子内垂直居中
`justify-content`	水平	整个轨道	`space-between` 轨道两端对齐
`align-content`	垂直	整个轨道	`center` 轨道整体垂直居中

/* 内容在格子里居中 */
.grid {
  justify-items: center;
  align-items: center;
  /* 等价简写：place-items: center; */
}

/* 轨道整体水平两端对齐、垂直居中（当列宽小于容器时） */
.grid {
  justify-content: space-between;
  align-content: center;
}

Grid 与 Flexbox 怎么选

维度	Grid	Flexbox
模型	二维（行 + 列同时控制）	一维（单主轴）
典型场景	整页骨架、卡片墙、表格	按钮组、导航栏、单行排列
对齐	行列都可精确控制	沿主轴 + 交叉轴
换行	由轨道定义（auto-fit 自动）	需 `flex-wrap` + 手动设置宽度

经验法则：内容是"围着内容走"的用 Flexbox（一排按钮、导航），结构是"区域划分"的用 Grid（页面骨架、卡片墙）。两者可以嵌套混用——外层 Grid 切区域，区域内小布局用 Flex。

速查：一行式布局汇总

/* 垂直居中 */
.center { display: grid; place-items: center; }

/* 侧边栏 + 内容 */
.side { grid-template-columns: 240px 1fr; }

/* 卡片墙（响应式） */
.cards { grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); }

/* 等高卡片 */
.cards { grid-auto-rows: 1fr; }

/* 等宽分栏 */
.cols { grid-template-columns: repeat(3, 1fr); }

/* 内容区外左右留白 */
.wrap { grid-template-columns: 1fr minmax(0, 800px) 1fr; }

最后一行的 minmax(0, 800px) 是防溢出技巧：给内容列设上限，让两侧 1fr 吃掉多余宽度，内容永远居中且不超宽。

你好，这是我的技术博客

Thu, 30 Jul 2026 00:00:00 +0000

欢迎来到我的技术博客 👋

这个博客主要记录我在写代码过程中的技术笔记、踩坑记录和思考。内容以技术文章为主，偶尔会有工具和效率相关的分享。

如何发布新文章

操作非常简单，一共三步：

在 content/posts/ 目录下新建一个 .md 文件（文件名就是文章链接，例如 hello-world.md → /posts/hello-world/）
在文件开头填写元信息（frontmatter）
用 Markdown 写正文，执行 hugo server 本地预览，构建后自动发布

想了解本主题支持的 Markdown 扩展能力（frontmatter 字段、提示框短代码等），看这篇：用 Markdown 写文章：Void 主题写作指南。

现有内容一览

博客目前主要覆盖这些方向，欢迎按需阅读：

前端基础：CSS Grid 常用布局速查表 — 响应式卡片墙、居中、整页骨架
React：深入理解 useEffect 的依赖数组 — 闭包陷阱、竞态、exhaustive-deps
TypeScript：用 TypeScript 写一个可即时取消的防抖函数 — 泛型与 cancel/flush
搜索原理：Pagefind 静态搜索技术解析 — 倒排索引与 WASM 检索

下面是一个文章模板：

---
title: 文章标题
date: 2026-09-05
tags: [TypeScript, 前端]
description: 一句话摘要，会显示在列表卡片上
---

写作约定

项目	约定
语言	中文为主，代码注释用英文
格式	`.md`（支持 GFM 表格、代码高亮、KaTeX 数学公式）
代码块	标注语言名，构建时自动高亮
图片	使用完整 URL，或放在 `static/` 下用 `/xxx.png` 引用
更新	记得同步更新 `date` 字段

祝你写作愉快 🚀

我的技术博客

AI 模型网关的通用架构：从 API 代理到推理治理层

从反向代理到推理治理层

先分清控制面和数据面

请求链路：先统一入口，再分阶段处理

协议归一化：统一核心，不要假装差异不存在

扩展点要放在变化的边界上

用一个具体实现校验架构

小结

多模型路由与故障恢复：重试、熔断和降级的边界

先区分逻辑模型和实际渠道

路由通常分成两步

重试：预算和错误分类比次数更重要

流式请求有一条重要边界

熔断和冷却解决的是不同时间尺度的问题

降级不是“换个模型继续”，而是能力契约

小结

模型网关的治理设计：计费、密钥与隐私保护

两类密钥，不要交给同一层管理

计费要拆成预留和结算

限额要明确作用维度与故障语义

脱敏应该定义清楚边界

可观测性要服务于排障和核算

把治理动作纳入同一条生命周期

小结

Agent 的工程细节：上下文裁剪、重试、编码与打包

上下文预算：历史不能无限增长

重试：只在还没输出之前

Windows 编码：两个独立的坑

TUI 与核心解耦：一个 emit 回调

打包：单文件 exe，但 key 不入包

小结

从零开始写一个 Agent：一次极简的尝试

Agent 和聊天机器人的区别

输入不再是一串消息，而是一组 items

定义唯一的工具：bash

核心循环：二十几行就是全部

流式：让等待变得可感知

工具执行：把命令跑起来

跑通之后，问题才刚开始

小结

让 AI Agent 安全地执行命令

三类需要警惕的命令

匹配之前先「归一化」

审批：把决定权交回用户

防外泄：把密钥从子进程环境里摘掉

取消与超时：Ctrl+C 到底做了什么

小结

把 yt-dlp 封装成好用的下载器：vidgrab 的设计笔记

它长什么样

架构：四层 + 一个贯穿全局的 Settings

设计一：配置驱动，把 Settings 翻译成 yt-dlp options

设计二：进度条要算「整批总进度」

设计三：搜索要「flat 优先 + 带退避的重试」

设计四：ignoreerrors 的陷阱

小结

一个下载器的工程化踩坑：单文件 .bat、cmd 陷阱与 uv 锁源

先把整份程序塞进单个 .bat

但构建产物会过期：用 --check 卡住

踩坑 1：cmd 注释里的 -> 会真的创建文件

踩坑 2：Python 3.9 不认 f-string 里的多行表达式

踩坑 3：uv.lock 和镜像源是绑定的

踩坑 4：Windows 控制台的 ANSI 和 UTF-8

让「双击」真的零门槛

小结

yt-dlp 技术解析：一条视频是怎么被解析、选择并下载的

一条视频的旅程

① Extractor：把每个网站翻译成统一的 info_dict

② formats：一个视频为什么有几十种流

③ 格式选择：一门迷你语言

默认行为

特殊名称

三个运算符

过滤器：用 [...] 写条件

-S：换一种更清晰的思路

④ Downloader：分片、并发与反爬

⑤ PostProcessor：ffmpeg 真正负责的部分

CLI 只是 Python API 的一层壳

实用速查

小结

但构建产物会过期：用 `--check` 卡住

踩坑 1：cmd 注释里的 `->` 会真的创建文件

过滤器：用 `[...]` 写条件

`-S`：换一种更清晰的思路