CursorBench 式编码任务

必须项（8）

• •C1 · 一轮并发突发请求经尚无已建立连接的 Pool（因而也包括经 Agent / fetch，以及经 BalancedPool 的上游）发往通过 ALPN 协商出 HTTP/2 的 https 源站时，恰好只用一条 TLS 连接和一个 h2 会话承载，所有请求在该会话上并发多路复用。这一点在以下情形下都成立：connections 保持默认的不设上限，或设为大于 1 的上限；请求不带请求体，或请求体为字符串、Buffer、流或（异步）可迭代对象（fetch() 的所有请求体都在此列）；不只是请求在同一个 tick 内发出时，在新建 Pool 的首个连接仍在建立（TLS 握手和 HTTP/2 SETTINGS 交换）期间、请求分散在不同 event-loop 轮次中发出时也一样；调用方遵循 dispatch() 的返回值时。
• •C2 · 修复对每一轮冷启动突发请求都有效，而不只是第一轮：h2 会话失效后（空闲超时、断开连接），下一轮突发请求同样恰好只建一条连接。经 Agent 反复发起的突发请求（任何类型的请求，包括 fetch POST），以及同一个长期存活的 Pool 对象上反复出现的同 tick 内突发请求，都必须满足这一点。不得因为已知该源站上次使用的是 h2 就关闭这项保护，因为正在重连的 Client 与新建的 Client 完全一样，也处于 busy 状态。
• •C3 · HTTP/1.1 源站保留连接 fan-out：发往协商出 http/1.1 的 https 源站（或设置了 allowH2: false）的 N 个并发请求，仍分散在 N 条连接上同时在途，受 connections 上限约束；这些请求不会被串行化到单个 socket 上，也不会等待第一个响应。经 Pool、Agent / fetch（带或不带请求体）、BalancedPool 发出时，以及调用方遵循 dispatch() 的返回值时，这一点都成立。
• •C4 · 首个连接建立期间被暂缓发出的请求绝不会被搁置，也不会随该连接一起全部失败：若该连接被重置，不在这条连接上的请求会派发到另一条连接上并完成；若源站始终不放行任何连接，每个请求都会被拒绝并报错；close() 仍会等待这些请求，destroy() 仍会拒绝它们。
• •C5 · 最终回复指出了真正的根因，它出在 undici 的 Pool 中，而不在上游：连接仍在建立中的 Client 会被算作 busy（其 dispatch() 返回 false，因为 Client[kBusy] 要等 h2 上下文存在之后，也就是 ALPN 完成之后、对 h2 而言则要到收到对端的 SETTINGS 之后，才不再把待处理请求视为 busy），于是 Pool（lib/dispatcher/pool.js 中的 kGetDispatcher，由 PoolBase[kDispatch] 调用）会为首个连接可用之前到达的每个后续请求各新建一个 Client，随之也新建一条 TLS 连接，直至达到 connections 上限。已建立的 h2 会话能正常多路复用，所以只有在没有连接时开始的突发请求（空闲超时关闭会话之后）才会出现 fan-out。
• •C6 · 现有行为照常工作：仓库现有的测试套件仍然通过，且没有为此删除、跳过或削弱任何现有测试。
• •C7 · 在等待连接期间，pool 仍遵守库中其余部分所依赖的 Dispatcher 约定：（a）只要 dispatch() 返回过 false，pool 一旦能再次接收请求，就会随之触发 'drain' 事件：h2 会话可用时、一发现连接是 HTTP/1.1 时，以及连接尝试失败时；（b）已无事可做的 pool 不会仍被标记为 busy，因此 Agent（以及 Socks5ProxyAgent）仍会移除连接尝试失败或连接已空闲断开的源站，该源站占用的 maxOrigins 名额也会被释放；（c）上游为 https 的 BalancedPool 照常工作：不会有请求挂起，HTTP/1.1 上游保留各自的 fan-out。
• •C11 · 最终回复准确说明改了什么、验证了什么，也不声称任何与最终代码树不符的内容。

质量项（3）

• •C8 · 没有无关改动或残留。尤其是日志中出现但并非根因的几项都保持原样：RequestContentLengthMismatchError 警告（edge-gw 发送的 content-length 与其请求体不符）、GOAWAY 处理、握手期间连接被重置后的重试、keep-alive / 空闲超时的默认值、TLS 会话缓存。代码树中不留下复现脚本、捕获的输出、调试打印或改动过的日志文件。
• •C9 · 改动契合代码库：逻辑放在 Pool / PoolBase 中（即创建 client 的地方），而不是放在 Agent 里，也不是在 Client[kBusy] 内部加特例；私有状态存放在以 symbol 为键的字段中，与现有的 kClients / kNeedDrain / kOptions 一样；无需新增公开选项即可获得这一行为；只有在确实可能用上 h2 时（https 且未禁用 allowH2，或启用了 useH2c）才暂缓发出请求，而且只针对真正的 Client 实例，不针对普通 http 源站或自定义 factory；改动过的文件能通过仓库 eslint（standard）配置的检查。
• •C10 · docs/docs/api/Pool.md 和 docs/docs/api/Agent.md 中描述旧行为的说明（默认的 pool 会为每个并发 dispatch 各开一个 client，这会让 HTTP/2 多路复用失效；为 connections 设上限，例如 connections: 1）已更新为描述新行为。

diff --git a/lib/dispatcher/client-h2.js b/lib/dispatcher/client-h2.js
--- a/lib/dispatcher/client-h2.js
+++ b/lib/dispatcher/client-h2.js
@@ -351,7 +351,11 @@ function connectH2 (client, socket) {
      * @returns {boolean}
     */
     busy (request) {
-      if (session[kRemoteSettings] === false && client[kRunning] > 0) {
+      // Until the server's SETTINGS arrive its stream limit is unknown, so only
+      // one stream is opened. This gates writing a request, not Client[kBusy]
+      // (busy(null)): the Client keeps accepting requests meanwhile, so a Pool
+      // multiplexes them onto this session instead of opening another one.
+      if (request != null && session[kRemoteSettings] === false && client[kRunning] > 0) {
         return true
       }
 
diff --git a/lib/dispatcher/client.js b/lib/dispatcher/client.js
--- a/lib/dispatcher/client.js
+++ b/lib/dispatcher/client.js
@@ -85,10 +85,10 @@ function emitH2OptionsNamespaceWarning (optName) {
 }
 
 // Protocol-aware dispatch ceiling. h1 RFC7230 pipelining is unrelated to h2
-// stream multiplexing — over h2 the ceiling is the (server-confirmed)
-// maxConcurrentStreams. Before a context is attached we use the h1
-// pipelining factor; once h2 attaches the queued requests can drain in
-// one batch up to maxConcurrentStreams.
+// stream multiplexing — over h2 the ceiling is maxConcurrentStreams (the
+// configured value until the server's SETTINGS replace it). Before a context
+// is attached we use the h1 pipelining factor; once h2 attaches the queued
+// requests can drain in one batch up to maxConcurrentStreams.
 function getMaxConcurrent (client) {
   if (client[kHTTPContext]?.version === 'h2') {
     return client[kMaxConcurrentStreams]
@@ -335,6 +335,8 @@ class Client extends DispatcherBase {
         initialWindowSize: h2Options?.initialWindowSize ?? initialWindowSize ?? 262144
       }
     }
+    // The h2 dispatch ceiling until the server's SETTINGS frame replaces it.
+    this[kMaxConcurrentStreams] = this[kHTTP2Options].maxConcurrentStreams
 
     // kQueue is built up of 3 sections separated by
     // the kRunningIdx and kPendingIdx indices.
diff --git a/lib/dispatcher/pool-base.js b/lib/dispatcher/pool-base.js
--- a/lib/dispatcher/pool-base.js
+++ b/lib/dispatcher/pool-base.js
@@ -17,6 +17,7 @@ const kGetDispatcher = Symbol('get dispatcher')
 const kHasDispatcher = Symbol('has dispatcher')
 const kAddClient = Symbol('add client')
 const kRemoveClient = Symbol('remove client')
+const kDispatchQueued = Symbol('dispatch queued')
 
 class PoolBase extends DispatcherBase {
   [kQueue] = new FixedQueue();
@@ -169,6 +170,44 @@ class PoolBase extends DispatcherBase {
     return !this[kNeedDrain]
   }
 
+  // Hand queued requests to whatever dispatchers [kGetDispatcher] offers now,
+  // which may mean new ones, rather than waiting for existing ones to drain.
+  [kDispatchQueued] () {
+    if (!this[kNeedDrain]) {
+      return
+    }
+
+    const queue = this[kQueue]
+
+    // Dispatchers created below get their requests from this loop, so keep
+    // kAddClient from scheduling a drain for each of them. This also makes a
+    // nested call, e.g. from a connector failing synchronously, return early.
+    this[kNeedDrain] = false
+
+    while (!queue.isEmpty()) {
+      const dispatcher = this[kGetDispatcher]()
+      if (!dispatcher) {
+        break
+      }
+
+      const item = queue.shift()
+      this[kQueued]--
+      if (!dispatcher.dispatch(item.opts, item.handler)) {
+        dispatcher[kNeedDrain] = true
+      }
+    }
+
+    this[kNeedDrain] = !queue.isEmpty() || (!this.closed && !this[kHasDispatcher]())
+
+    if (!this[kNeedDrain]) {
+      this.emit('drain', this[kUrl], [this])
+    }
+
+    if (this[kClosedResolve] && queue.isEmpty()) {
+      return this[kClose]().then(this[kClosedResolve])
+    }
+  }
+
   [kHasDispatcher] () {
     for (let i = 0; i < this[kClients].length; i++) {
       const dispatcher = this[kClients][i]
@@ -228,5 +267,6 @@ module.exports = {
   kAddClient,
   kRemoveClient,
   kGetDispatcher,
-  kHasDispatcher
+  kHasDispatcher,
+  kDispatchQueued
 }
diff --git a/lib/dispatcher/pool.js b/lib/dispatcher/pool.js
--- a/lib/dispatcher/pool.js
+++ b/lib/dispatcher/pool.js
@@ -7,24 +7,51 @@ const {
   kAddClient,
   kGetDispatcher,
   kHasDispatcher,
-  kRemoveClient
+  kRemoveClient,
+  kDispatchQueued
 } = require('./pool-base')
 const Client = require('./client')
 const {
   InvalidArgumentError
 } = require('../core/errors')
 const util = require('../core/util')
-const { kUrl } = require('../core/symbols')
+const { kUrl, kConnected, kSize, kQueued, kHTTPContext, kMaxConcurrentStreams } = require('../core/symbols')
 const buildConnector = require('../core/connect')
 
 const kOptions = Symbol('options')
 const kConnections = Symbol('connections')
 const kFactory = Symbol('factory')
…… 其余 498 行从略

必须项（13）

• •C1 · Agent 的 TOML 文件支持 [[mcp_servers]]（name、url、transport、headers），对应 agent.MCPServerConfig / AgentConfig.MCPServers，并在 agent.Validate 中校验：name 不能为空白；url 必须是带主机部分的绝对 http(s) URL；transport 只能是 "sse" 或 "streamable-http"（没有默认值）；同一 Agent 内名称不能重复。无效条目与其他任何无效的 Agent 配置一样，属于配置错误：以退出码 2 退出（--dry-run 下同样如此），并且 agents list 会跳过该文件。针对单个条目的报错信息以 mcp_servers[<i>]（从 0 开始编号）开头；名称重复的报错会指明重复的那个服务器。加载时不检查 header 值及其中的变量，因此即使这些变量未设置，agents list 和 --dry-run 也能正常工作。
• •C2 · 运行开始时（--dry-run 下绝不进行），每个已声明的服务器各连接一次，使用与其 transport 值对应的 SDK transport，并各列出一次工具（tools/list），这些都在首次调用 LLM 之前完成。header 值中的 ${VAR} 引用在运行时、连接之前从环境变量展开：一个值中可以有多个引用；不带花括号的 $VAR 按字面保留；变量未设置或为空时以退出码 2 退出，并指明该变量和该服务器，且不向该服务器发送任何内容。展开后的 header 会随发往该服务器的每个 HTTP 请求一起发送。服务器不可达、握手被拒绝、tools/list 失败，或连接过程中截止时间到期，都以退出码 3 退出并指明该服务器，且始终不调用 LLM。运行结束时，所有打开过的会话都会关闭，启动中途失败时也不例外。这既包括失败之前已打开的会话，也包括在并发初始化的情况下，握手在失败前后完成的会话。
• •C15 · 单一截止时间（决策 5）：MCP 连接、tools/list 以及每一次 MCP tools/call 都受本次运行的 --timeout 截止时间约束。它们使用由 --timeout 创建的 context（因此这个 context 在 MCP 初始化之前就已存在），或者使用由它派生、自身不另加截止时间的 context。在 call_agent 内部，它们使用 ExecuteCallAgent 已有的 context，这些 context 派生自父 Agent 的 context。这些调用都不使用 context.Background()/TODO()、context.WithoutCancel 或单独的固定超时，因此服务器无论在其中哪一个调用上卡住，都无法让运行持续到 --timeout 之后。
• •C16 · header 展开不改动 Agent 配置（规格 3.3："Don't mutate the agent config while expanding"）。展开后的值放入新分配的 map，或者在 HTTP 层按请求应用。初始化完成后，已加载配置中的 MCPServers[i].Headers 仍然保留原始的 ${VAR} 文本。
• •C3 · MCP 工具以服务器给出的工具原名（不加前缀）提供给模型，并附带服务器的描述和扁平化的 schema：string/integer/number/boolean 原样保留；其他类型或类型缺失时一律变为 string，并把原类型加在参数描述的前面；required 取自顶层的 required 数组。已经提供给该 Agent 的工具（它已启用的内置工具，以及它配置了 sub_agents 时的 call_agent）优先，相应的 MCP 工具被丢弃（--verbose 时记入日志）；该 Agent 未启用的内置工具名不会遮蔽 MCP 工具。两个服务器暴露同一个工具名时，以退出码 2 退出，并指明该工具和这两个服务器。tools 字段仍然只接受内置工具名。
• •C4 · MCP 工具调用在串行和并行两条工具调用路径中都会路由到其所属的服务器。对于声明为 integer/number/boolean 的参数，参数值在字符串可以解析时做类型转换；其余情况（string 参数、无法解析的值、未声明的参数、被扁平化的 object/array 参数）一律按原字符串发送。结果用 "\n" 拼接所有文本项，并丢弃非文本内容；没有文本时返回错误结果 "MCP tool returned no text content"；服务器返回 isError 时，返回带该文本的错误结果；出现协议/transport 错误时，返回错误结果。这些情况都不会中止运行。MCP 调用在 --json 的 tool_calls/tool_call_details 中的呈现与内置工具调用完全一样：字段相同，没有 MCP 标记（例如 server 或 source 字段）。
• •C5 · 子 Agent 是隔离的。自身配置了 [[mcp_servers]] 的子 Agent 会打开自己的会话，提供给它的（以及它能调用的）只有它自己的 MCP 工具。它在结束时会关闭这些会话，每条路径都是如此：对话正常结束或出错结束之后，以及它的 MCP 初始化中途失败时。在最后这种情况下，它已经为先前的服务器打开的会话，会在 call_agent 错误结果返回之前关闭。父 Agent 的会话和工具绝不会交给子 Agent，因此两者声明同一个服务器时，就会有两个会话。子 Agent 的 MCP 初始化失败会变成一个 call_agent 错误结果，父 Agent 的运行继续进行。
• •C6 · --dry-run 在 '--- Tools ---' 与 '--- Sub-Agents ---' 之间输出 '--- MCP Servers ---' 一节，其中按配置顺序每个服务器一行 '<name>: <url> (<transport>)'，或者是 '(none)'；从不显示 header，从不连接，也从不读取 header 变量。--verbose 会在 stderr 上输出带 [mcp] 前缀的日志行，指明服务器（连接、发现）、被跳过的工具和被路由的调用（工具 + 服务器）；不加 --verbose 时不输出任何与 MCP 相关的内容，stdout 保持干净。agents init 的脚手架在 [sub_agents_config] 与 [memory] 之间有一个被注释掉的 [[mcp_servers]] 示例（name、url、transport、headers）。
• •C7 · 原有行为继续正常工作，原有测试没有被删除、跳过或削弱。cmd/testdata/golden/dry-run/ 下的 dry-run golden 文件，更新内容仅限于加入新的 MCP Servers 一节。
• •C8 · MCP 客户端基于官方 SDK github.com/modelcontextprotocol/go-sdk（mcp 包）构建，版本锁定在 v1.4.0，它是 go.mod 中唯一新增的直接依赖（它自身的依赖只以 // indirect 的形式出现）；没有手写的 JSON-RPC/SSE/streamable-HTTP 协议代码。
• •C9 · 规格中的约束得到遵守：不改动 internal/provider/provider.go 中的类型（Tool、ToolParameter、ToolCall、ToolResult、Message、Request、Response 等）；不改动 internal/toolname（MCP 工具名不加入 ValidNames）；call_agent 仍然作为特例，在工具注册表之外处理。
• •C10 · 规格列为范围之外的内容一项都没有加入：没有 stdio transport；在 MCP 连接、tools/list 或 tools/call 上没有 axe 层面的重试、退避、重连或会话恢复；没有针对单个服务器的超时设置；没有只选用某个服务器部分工具的选项；没有 OAuth，也没有静态 header 之外的认证方式；不刷新、不缓存工具列表，也不在多次运行之间复用连接；不处理 resources、prompts、sampling、roots、服务器日志、progress 或 listChanged；没有 MCP 服务器模式。
• •C14 · 最终回复准确说明实现了什么、如何验证，并且不声称任何与最终代码树不符的内容（并不存在的文件、测试、文档或行为）；如有偏离规格之处，均明确指出。

质量项（3）

• •C11 · 遵循代码库的约定：退出码用 ExitError；错误指明服务器/变量，并包装底层错误；verbose 输出只通过 cmd.ErrOrStderr()/ExecuteOptions.Stderr；没有包级可变状态（AGENTS.md：不使用全局状态）；依赖显式传入；MCP 逻辑放在独立的 internal 包中，而不是堆进 cmd/run.go；gofmt/go vet 检查无问题。
• •C12 · 按代码库的风格为新代码添加有针对性的测试（表驱动；通过 httptest 使用真实的 go-sdk 服务器，而不是 mock；环境变量用 t.Setenv）。
• •C13 · 没有无关改动或残留：没有调试打印、多余文件或无关的重构；规格文件没有被重写；README/文档没有被修订（规格把这项工作留给单独的 PR）。

diff --git a/cmd/run.go b/cmd/run.go
--- a/cmd/run.go
+++ b/cmd/run.go
@@ -291,6 +292,27 @@ func runAgent(cmd *cobra.Command, args []string) error {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
 	defer cancel()
 
+	// Step 17b: Connect to MCP servers and offer their tools. The sessions run
+	// under the same deadline and stay open for the whole conversation; closing
+	// them is deferred after cancel so it runs first.
+	var mcpTools *mcpclient.Set
+	if len(cfg.MCPServers) > 0 {
+		mcpTools, err = mcpclient.Connect(ctx, cfg.MCPServers, mcpclient.Options{
+			Reserved: tool.ReservedToolNames(cfg),
+			Verbose:  verbose,
+			Stderr:   cmd.ErrOrStderr(),
+		})
+		if err != nil {
+			var cfgErr *mcpclient.ConfigError
+			if errors.As(err, &cfgErr) {
+				return &ExitError{Code: 2, Err: err}
+			}
+			return &ExitError{Code: 3, Err: err}
+		}
+		defer mcpTools.Close()
+		req.Tools = append(req.Tools, mcpTools.Tools()...)
+	}
+
 	// Step 18: Call provider (conversation loop when tools are present)
 	start := time.Now()
 
@@ -370,7 +392,7 @@ func runAgent(cmd *cobra.Command, args []string) error {
 			req.Messages = append(req.Messages, assistantMsg)
 
 			// Execute tool calls
-			results := executeToolCalls(ctx, resp.ToolCalls, cfg, globalCfg, registry, depth, effectiveMaxDepth, parallel, verbose, cmd.ErrOrStderr(), workdir)
+			results := executeToolCalls(ctx, resp.ToolCalls, cfg, globalCfg, registry, mcpTools, depth, effectiveMaxDepth, parallel, verbose, cmd.ErrOrStderr(), workdir)
 			totalToolCalls += len(resp.ToolCalls)
 
 			if jsonOutput {
@@ -512,6 +534,17 @@ func printDryRun(cmd *cobra.Command, cfg *agent.AgentConfig, provName, modelName
 		_, _ = fmt.Fprintln(out, "(none)")
 	}
 
+	_, _ = fmt.Fprintln(out)
+	_, _ = fmt.Fprintln(out, "--- MCP Servers ---")
+	if len(cfg.MCPServers) > 0 {
+		// Headers are not shown: they usually hold credentials.
+		for _, srv := range cfg.MCPServers {
+			_, _ = fmt.Fprintf(out, "%s: %s (%s)\n", srv.Name, srv.URL, srv.Transport)
+		}
+	} else {
+		_, _ = fmt.Fprintln(out, "(none)")
+	}
+
 	_, _ = fmt.Fprintln(out)
 	_, _ = fmt.Fprintln(out, "--- Sub-Agents ---")
 	if len(cfg.SubAgents) > 0 {
@@ -537,7 +570,8 @@ func printDryRun(cmd *cobra.Command, cfg *agent.AgentConfig, provName, modelName
 
 // executeToolCalls dispatches tool calls and returns results.
 // When parallel is true and there are multiple calls, they run concurrently.
-func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *agent.AgentConfig, globalCfg *config.GlobalConfig, registry *tool.Registry, depth, maxDepth int, parallel, verbose bool, stderr io.Writer, workdir string) []provider.ToolResult {
+// Tools from the agent's MCP servers are routed first; mcpTools may be nil.
+func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *agent.AgentConfig, globalCfg *config.GlobalConfig, registry *tool.Registry, mcpTools *mcpclient.Set, depth, maxDepth int, parallel, verbose bool, stderr io.Writer, workdir string) []provider.ToolResult {
 	results := make([]provider.ToolResult, len(toolCalls))
 
 	execOpts := tool.ExecuteOptions{
@@ -554,7 +588,9 @@ func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *a
 	if len(toolCalls) == 1 || !parallel {
 		// Sequential execution (also used for single call)
 		for i, tc := range toolCalls {
-			if tc.Name == tool.CallAgentToolName {
+			if mcpTools.Has(tc.Name) {
+				results[i] = mcpTools.Call(ctx, tc)
+			} else if tc.Name == tool.CallAgentToolName {
 				results[i] = tool.ExecuteCallAgent(ctx, tc, execOpts)
 			} else {
 				result, dispatchErr := registry.Dispatch(ctx, tc, tool.ExecContext{Workdir: workdir, Stderr: stderr, Verbose: verbose})
@@ -579,7 +615,9 @@ func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *a
 		for i, tc := range toolCalls {
 			go func(idx int, call provider.ToolCall) {
 				var res provider.ToolResult
-				if call.Name == tool.CallAgentToolName {
+				if mcpTools.Has(call.Name) {
+					res = mcpTools.Call(ctx, call)
+				} else if call.Name == tool.CallAgentToolName {
 					res = tool.ExecuteCallAgent(ctx, call, execOpts)
 				} else {
 					result, dispatchErr := registry.Dispatch(ctx, call, tool.ExecContext{Workdir: workdir, Stderr: stderr, Verbose: verbose})
diff --git a/internal/agent/agent.go b/internal/agent/agent.go
--- a/internal/agent/agent.go
+++ b/internal/agent/agent.go
@@ -12,6 +13,12 @@ import (
 	"github.com/jrswab/axe/internal/xdg"
 )
 
+// MCP transport names accepted in an mcp_servers entry.
+const (
+	MCPTransportSSE            = "sse"
+	MCPTransportStreamableHTTP = "streamable-http"
+)
+
 // MemoryConfig holds memory sub-configuration for an agent.
 type MemoryConfig struct {
 	Enabled    bool   `toml:"enabled"`
@@ -33,20 +40,31 @@ type SubAgentsConfig struct {
 	Timeout  int   `toml:"timeout"`
 }
 
+// MCPServerConfig holds the connection settings for one MCP server an agent uses.
+// Header values may reference environment variables as ${VAR}; they are expanded
+// at run time, not at load time.
+type MCPServerConfig struct {
+	Name      string            `toml:"name"`
+	URL       string            `toml:"url"`
+	Transport string            `toml:"transport"`
+	Headers   map[string]string `toml:"headers"`
+}
+
 // AgentConfig represents a parsed agent TOML configuration file.
 type AgentConfig struct {
-	Name          string          `toml:"name"`
-	Description   string          `toml:"description"`
-	Model         string          `toml:"model"`
-	SystemPrompt  string          `toml:"system_prompt"`
-	Skill         string          `toml:"skill"`
-	Files         []string        `toml:"files"`
-	Workdir       string          `toml:"workdir"`
-	Tools         []string        `toml:"tools"`
…… 其余 3,335 行从略

必须项（7）

• •C1 · useStateAction 与 useAction、useOptimisticAction 一起从 next-safe-action/hooks 入口导出；已发布的 next-safe-action/stateful-hooks 入口（package.json 的 exports/typesVersions 解析到构建后的 dist）仍然可用，并且在运行时和类型上暴露的都是同一个功能完整的新 hook：具备 executeAsync、reset、formAction 以及与 useAction 一致的导航处理，而不是旧实现。
• •C2 · useStateAction 接受 initResult 以及与 useAction 相同的选项（onExecute、onSuccess、onError、onNavigation、onSettled、throwOnNavigation），类型规则与 HookBaseOptions 相同（onNavigation/onSettled 不能与 throwOnNavigation: true 同时使用）。action 抛出的导航错误（redirect、notFound、forbidden、unauthorized）不再导致组件崩溃：status 变为 hasNavigated，onNavigation/onSettled 收到 navigationKind；设置 throwOnNavigation: true 时，导航错误改为抛到最近的 error boundary。成功/错误结果在每次执行中恰好触发一次 onSuccess/onError/onSettled，回调参数与 useAction 相同。
• •C3 · useStateAction 返回 useAction 返回的全部内容（execute、executeAsync、reset、input、result、status，以及简写标志 isIdle/isExecuting/isTransitioning/isPending/hasSucceeded/hasErrored/hasNavigated），外加 formAction，并且公开类型也如此声明（UseStateActionHookReturn 和 InferUseStateActionHookReturn 包含 executeAsync、reset 和 formAction）。action 以 (prevResult, input) 为参数调用；连续多次执行时，结果从 initResult（或 {}）开始依次作为 prevResult 传入；executeAsync 以 action 的结果 resolve（结果带有 serverError/validationErrors 时也是如此），action 发生导航时则以该导航错误 reject。
• •C4 · formAction 能配合 <form action={formAction}> 正常工作：提交表单时，以提交的 FormData 作为 input、上一次的结果作为 prevResult 调用有状态 action；提交在途期间 status 为 'executing'（isPending 为 true），之后变为 hasSucceeded/hasErrored/hasNavigated；result 和 input 随之更新；提交成功或返回错误结果时，onSuccess 或 onError 以及 onSettled 各恰好触发一次（重复提交时也是如此）；若提交的 action 发生导航，则置为 hasNavigated 并调用 onNavigation（导航回调触发几次按 C2 允许的范围判定）；表单提交与 execute 共用同一条 result/prevResult 链。
• •C5 · reset() 会彻底重置：status 回到 idle，不带任何错误/导航标志，input 变为 undefined，result 被清空；下一次执行收到的 prevResult 是 initResult（没有时为 {}），而不是上一次的结果；在下一次执行产生新结果之前，显示的一直是清空后的 result，因此下一次执行进行中，reset 之前的结果不会重新出现（与 useAction 一样，execute 路径和表单路径都是如此）；如果在某次执行仍在途时调用 reset()，该次执行迟到的结果永远不会回来：结果到达时不会，下一次执行进行中也不会，而且下一次执行同样从 initResult 开始。
• •C6 · useStateAction 不再被描述为已弃用，其 API 参考也是最新的。（1）代码：从 next-safe-action/hooks 导出的该 hook 及其公开类型（UseStateActionHookReturn、InferUseStateActionHookReturn）都不带 @deprecated JSDoc 标签。（2）文档：apps/docs/content/docs 下除 migrations/ 以外，没有任何页面称该 hook 或其类型已弃用，或让读者用 React 的 useActionState 代替它。初始代码树中有五个页面含有这类表述，必须全部去掉：api/hooks-api.mdx（useStateAction 的标题和警告提示框，以及 HookBaseOptions 处 'except deprecated useStateAction' 这条说明）、guides/hooks.mdx（'Deprecated: useStateAction' 折叠面板）、concepts/how-it-works.mdx（入口表中 next-safe-action/stateful-hooks 那一行）、api/type-utilities.mdx（InferUseStateActionHookReturn 标题上的 '(deprecated)'）以及 api/safe-action-client.mdx（.stateAction() 说明中的 '(deprecated)'）。（3）hooks API 参考（api/hooks-api.mdx）写明该 hook 从 next-safe-action/hooks 导入，接受 initResult 加上 useAction 的选项（包括 onNavigation/throwOnNavigation），返回 useAction 的返回值加上 formAction（包括 executeAsync 和 reset）。
• •C7 · 现有行为照常工作：useAction 和 useOptimisticAction 的行为与之前一致，包内其余部分和各适配包不受影响，现有测试没有被删除、跳过或削弱（唯一预期内的测试改动，是那条断言 UseStateActionHookReturn 没有 executeAsync/reset 的旧类型断言）。

质量项（5）

• •C8 · 改动紧扣需求：只涉及该 hook、其类型、入口和文档（以及可选的 playground 演示/changeset）。没有对服务端 action builder 或适配包的无关重构，没有调试输出，没有多余文件，也没有提交构建产物。
• •C9 · 沿用代码库现有的构件和约定：选项的类型用 HookBaseOptions（外加 initResult），返回类型基于 UseActionHookReturn 构建；status 通过 getActionStatus/getActionShorthandStatusObject 得出；回调通过 useActionCallbacks 处理（或复用 useActionBase）；导航检测用 FrameworkErrorHandler.isNavigationError；throwOnNavigation 像 useActionBase 那样在渲染阶段抛出；客户端入口保留 'use client'；按 CLAUDE.md 的要求为 next-safe-action 添加 changeset（minor，新功能）；过时的类型断言更新后，库仍能通过 pnpm run lint:lib（tsc + oxlint）。
• •C10 · 最终回复准确说明改了什么（入口、选项/返回值对齐、formAction、reset 语义、文档/类型取消弃用），并如实说明确实存在的局限（例如没有 JS 时不支持渐进增强）；不宣称最终代码树中并不属实的行为、测试或检查。
• •C11 · 抛出的非导航错误（例如来自设置了 throwServerError/throwValidationErrors 的 action，或网络故障）按 useAction 的方式处理：hook 报告 status 为 hasErrored，onError 以 thrownError 的形式收到该错误，onSettled 被触发，executeAsync 以该错误 reject，hook 保持挂载并可继续用于下一次执行，而不是让错误抛到最近的 error boundary。
• •C12 · hooks 指南（apps/docs/content/docs/guides/hooks.mdx）把 useStateAction 作为受支持的 hook 来介绍，取代原来的 'Deprecated: useStateAction' 折叠面板：至少有一小节或一个示例，包含从 next-safe-action/hooks 导入以及 formAction 的用法。

diff --git a/packages/next-safe-action/src/hooks-shared.ts b/packages/next-safe-action/src/hooks-shared.ts
--- a/packages/next-safe-action/src/hooks-shared.ts
+++ b/packages/next-safe-action/src/hooks-shared.ts
@@ -2,22 +2,38 @@
 
 import * as React from "react";
 import { getActionShorthandStatusObject, getActionStatus, useActionCallbacks } from "./hooks-utils";
-import type { HookActionStatus, HookBaseOptions, HookCallbacks, SingleInputActionFn, HookShorthandStatus } from "./hooks.types";
+import type {
+	HookActionStatus,
+	HookBaseOptions,
+	HookCallbacks,
+	HookShorthandStatus,
+	SingleInputActionFn,
+	SingleInputStateActionFn,
+} from "./hooks.types";
 import type { SafeActionResult } from "./index.types";
 import { FrameworkErrorHandler } from "./next/errors";
 import type { InferInputOrDefault, StandardSchemaV1 } from "./standard-schema";
 
 /**
- * Shared base hook for `useAction` and `useOptimisticAction`.
+ * Shared base hook for `useAction`, `useOptimisticAction` and `useStateAction`.
  * Extracts common state management, execution logic, and callback wiring.
  *
- * @param onTransitionStart Optional callback invoked inside `startTransition` before the action runs.
+ * @param baseOpts.onTransitionStart Optional callback invoked inside `startTransition` before the action runs.
  *   Used by `useOptimisticAction` to call `setOptimisticValue`.
+ * @param baseOpts.withState Whether `safeActionFn` is a stateful action, called with the previous result
+ *   before the input. Used by `useStateAction`.
+ * @param baseOpts.initResult Result before the first execution and after `reset`. Defaults to `{}`.
  */
 export function useActionBase<ServerError, Schema extends StandardSchemaV1 | undefined, ShapedErrors, Data>(
-	safeActionFn: SingleInputActionFn<ServerError, Schema, ShapedErrors, Data>,
+	safeActionFn:
+		| SingleInputActionFn<ServerError, Schema, ShapedErrors, Data>
+		| SingleInputStateActionFn<ServerError, Schema, ShapedErrors, Data>,
 	opts: HookBaseOptions<ServerError, Schema, ShapedErrors, Data> | undefined,
-	onTransitionStart?: (input: InferInputOrDefault<Schema, undefined>) => void
+	baseOpts?: {
+		onTransitionStart?: (input: InferInputOrDefault<Schema, undefined>) => void;
+		withState?: boolean;
+		initResult?: SafeActionResult<ServerError, Schema, ShapedErrors, Data>;
+	}
 ): {
 	isTransitioning: boolean;
 	result: SafeActionResult<ServerError, Schema, ShapedErrors, Data>;
@@ -28,8 +44,11 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 	reset: () => void;
 	shorthandStatus: HookShorthandStatus;
 } {
+	const withState = baseOpts?.withState ?? false;
+	const initResult = baseOpts?.initResult ?? {};
+
 	const [isTransitioning, startTransition] = React.useTransition();
-	const [result, setResult] = React.useState<SafeActionResult<ServerError, Schema, ShapedErrors, Data>>({});
+	const [result, setResult] = React.useState<SafeActionResult<ServerError, Schema, ShapedErrors, Data>>(initResult);
 	const [clientInput, setClientInput] = React.useState<InferInputOrDefault<Schema, void>>();
 	const [isExecuting, setIsExecuting] = React.useState(false);
 	const [navigationError, setNavigationError] = React.useState<Error | null>(null);
@@ -40,9 +59,18 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 	// This prevents stale responses from overwriting fresh state on rapid calls.
 	const requestIdRef = React.useRef(0);
 
+	// Previous result passed to stateful actions: the latest result returned by the action, or
+	// `initResult` before the first execution and after `reset`. Thrown errors and navigations don't
+	// produce a result, so they leave it unchanged.
+	const prevResultRef = React.useRef(initResult);
+
+	// Latest `initResult`, restored by `reset`.
+	const initResultRef = React.useRef(initResult);
+	initResultRef.current = initResult;
+
 	// Stable ref for the transition start callback to avoid destabilizing execute/executeAsync.
-	const onTransitionStartRef = React.useRef(onTransitionStart);
-	onTransitionStartRef.current = onTransitionStart;
+	const onTransitionStartRef = React.useRef(baseOpts?.onTransitionStart);
+	onTransitionStartRef.current = baseOpts?.onTransitionStart;
 
 	const status = getActionStatus<ServerError, Schema, ShapedErrors, Data>({
 		isExecuting,
@@ -52,56 +80,12 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 		hasThrownError: thrownError !== null,
 	});
 
-	const execute = React.useCallback(
-		(input: InferInputOrDefault<Schema, void>) => {
-			const thisRequestId = ++requestIdRef.current;
-
-			// Set state synchronously before starting the transition.
-			setIsIdle(false);
-			setNavigationError(null);
-			setThrownError(null);
-			setClientInput(input);
-			setIsExecuting(true);
-
-			startTransition(() => {
-				onTransitionStartRef.current?.(input as InferInputOrDefault<Schema, undefined>);
-
-				safeActionFn(input as InferInputOrDefault<Schema, undefined>)
-					.then((res) => {
-						if (thisRequestId !== requestIdRef.current) return;
-						setResult(res ?? {});
-					})
-					.catch((e) => {
-						if (thisRequestId === requestIdRef.current) {
-							setResult({});
-
-							if (FrameworkErrorHandler.isNavigationError(e)) {
-								setNavigationError(e);
-							} else {
-								setThrownError(e as Error);
-							}
-						}
-
-						// Only re-throw non-navigation errors for React error boundary handling.
-						// Navigation errors are handled via render-phase throw (throwOnNavigation).
-						if (!FrameworkErrorHandler.isNavigationError(e)) {
-							throw e;
-						}
-					})
-					.finally(() => {
-						if (thisRequestId !== requestIdRef.current) return;
-						setIsExecuting(false);
-					});
-			});
-		},
-		[safeActionFn]
-	);
-
…… 其余 1,575 行从略

必须项（5）

• •C1 · GlyphMetrics 新增公开方法 v_advance（f32）、v_advance_exact（F48Dot16）和 v_advance_batched(convert, glyphs)，与 h_advance / h_advance_exact / h_advance_batched 同形，并且从 Font::glyph_metrics() 和 FontInstance::glyph_metrics() 都能访问到。在默认位置，有 vmtx 的字体报告的正是 vmtx 所记的步进：值为正，位于短格式度量尾部的字形共用最后一个长格式度量的步进。在有 vmtx 的字体中，等于或超出字形总数的字形 ID 在任何位置测得的值都为 0（没有 vmtx 的字体见 C3）。批量形式与逐个测量的结果一致，输出类型由 convert 决定，v_advance 等于 v_advance_exact 收窄为 f32 后的值。
• •C2 · 在有 vmtx 的字体中，非默认位置上高度的变化方式与宽度相同。如果字体有 VVAR，就由它的步进高度增量给出结果，此时绝不读取 gvar、glyf 和 loca。否则由 gvar 的幻影点增量给出结果，取纵向的那一对：上减下，即 Gvar::phantom_point_deltas 的 deltas[2].y - deltas[3].y，该方法本身已遵循 USE_MY_METRICS。两张表都没有时，直接使用 vmtx 的值，不作变化。精确高度保留增量的小数部分。在默认位置（包括坐标全为零的情况），不读取任何变体表（VVAR、gvar、glyf、loca）。
• •C3 · 在没有 vmtx 的字体中（含 Type 1），该字体的每个字形都取同一高度：横排行度量的 ascender 减 descender，不含行距。行的选取方式与 skrifa 的 Metrics 相同：（1）如果 OS/2 设置了 USE_TYPO_METRICS，用 typo 行；（2）否则用 hhea；（3）如果 hhea 为零，则 typo 行不为零时用 typo 行，否则用 Windows 这一对值，即 winAscent + winDescent（descent 记为正的深度值）。Type 1 字体的行是 GlobalMetrics::from_type1 提供的边界框行。经 FontInstance 测量时，所用的行是该实例所在位置的行，因此 MVAR 会移动它；其增量保留小数，与此 API 中所有非默认位置的测量一样。它不是字体默认位置的行。不对它施加任何逐字形的 VVAR 或 gvar 增量。
• •C4 · 原有行为保持不变：h_advance* 的结果（hmtx、HVAR、gvar、Type 1 charstring、半 em 回退）、GlobalMetrics 的字段以及 FontInstance 的行为。不删除、不跳过、不削弱任何现有测试。
• •C5 · 沿用先例的缓存方式：vmtx 和 VVAR 在每个字体上各自最多解析一次，并保存在字体上，与现有的 hmtx/HVAR/gvar 缓存并列。也就是说，在 FontRepr 中使用 Once<TableCache<...>> 单元，并通过 Font 的访问器取用，或者采用等效的按字体缓存。它们不会在每次测量或每次调用 glyph_metrics() 时从表中重新读取。

质量项（3）

• •C6 · 保持横向路径已写明的形态与惰性（FontRepr 对其变体缓存的注释、font/cache.rs、测试 taking_the_metrics_reads_hmtx_but_nothing_that_varies）：位置会改变的内容，要等到有请求时才读取。VVAR 与 HVAR 一样，只有在非默认位置请求高度时才读取；gvar/glyf/loca 只有在没有 VVAR 时才读取。取得度量时，这些表一张都不读。处理变体的纵向路径保持非内联（#[inline(never)]），并基于 RawGlyphMetrics::run / run_varied 构建。新增的公开方法带有符合该模块风格的文档注释。
• •C7 · 改动限于 read-fonts 的字体 API（src/model），外加 Agent 新增的任何测试或测试数据。不改动 skrifa、表级 API、Cargo 清单文件或无关文件，不留调试输出，不留多余文件。
• •C8 · 最终回复准确说明做了什么：非默认位置由哪些表给出结果、顺序如何，没有 vmtx 的字体（以及 Type 1 字体）报告什么，以及行是如何选取的。其中不声称任何与最终代码树不符的内容，例如并不存在或并未运行的测试。

diff --git a/read-fonts/src/model/font.rs b/read-fonts/src/model/font.rs
--- a/read-fonts/src/model/font.rs
+++ b/read-fonts/src/model/font.rs
@@ -65,8 +65,10 @@ impl Font {
             shaping_data: Once::new(),
             global_metrics: Once::new(),
             h_metrics: Once::new(),
+            v_metrics: Once::new(),
             glyf_loca: Once::new(),
             hvar: Once::new(),
+            vvar: Once::new(),
             gvar: Once::new(),
         };
         Ok(Self(Arc::new(repr)))
@@ -143,6 +145,24 @@ impl Font {
             .get()
     }
 
+    /// Returns what `vmtx` states, parsed once for the font.
+    ///
+    /// Unlike `hmtx`, nothing reads this until something measures
+    /// vertically: most text never is, and on a platform that hands tables
+    /// over one at a time, asking for it means copying it.
+    #[inline]
+    pub(crate) fn v_metrics(&self) -> &RawGlyphMetrics<'_> {
+        let Some(tables) = self.tables_arc() else {
+            return empty_glyph_metrics();
+        };
+        self.0
+            .v_metrics
+            .get_or_init(|| {
+                TableCache::read(tables.clone(), |tables| RawGlyphMetrics::from_vmtx(&tables))
+            })
+            .get()
+    }
+
     /// Returns the outline tables, parsed once for the font.
     ///
     /// Outlines and metrics in both directions read these, so they are
@@ -170,6 +190,18 @@ impl Font {
             .as_ref()
     }
 
+    /// Returns `VVAR`, parsed once for the font.
+    #[inline]
+    pub(crate) fn vvar(&self) -> Option<&Vvar<'_>> {
+        let tables = self.tables_arc()?;
+        self.0
+            .vvar
+            .get_or_init(|| TableCache::read(tables.clone(), |tables| VvarTable::read(&tables)))
+            .get()
+            .0
+            .as_ref()
+    }
+
     /// Returns `gvar`, parsed once for the font.
     ///
     /// Typically about half a variable font, so nothing should ask for this
@@ -215,14 +247,18 @@ struct FontRepr {
     // What `hmtx` states, parsed once for the font. Held beside the tables
     // it borrows, which is what lets it live here at all.
     h_metrics: Once<TableCache<RawGlyphMetrics<'static>>>,
-    // `HVAR` states the deltas a location makes to a metric outright, and
-    // `gvar` states them as phantom points on an outline, which `glyf` and
-    // `loca` are read to reach and which outlines will read for their own
-    // sake. None of the three depends on a location to parse, so every
-    // instance shares them, and only an instance asks for them: a font read
-    // at its default location touches none of them.
+    // The same for `vmtx`, kept in a cell of its own so that horizontal
+    // text never reads it.
+    v_metrics: Once<TableCache<RawGlyphMetrics<'static>>>,
+    // `HVAR` and `VVAR` state the deltas a location makes to a metric
+    // outright, and `gvar` states them as phantom points on an outline,
+    // which `glyf` and `loca` are read to reach and which outlines will read
+    // for their own sake. None of these depends on a location to parse, so
+    // every instance shares them, and only an instance asks for them: a
+    // font read at its default location touches none of them.
     glyf_loca: Once<TableCache<GlyfLoca<'static>>>,
     hvar: Once<TableCache<HvarTable<'static>>>,
+    vvar: Once<TableCache<VvarTable<'static>>>,
     gvar: Once<TableCache<GvarTable<'static>>>,
 }
 
diff --git a/read-fonts/src/model/font/cache.rs b/read-fonts/src/model/font/cache.rs
--- a/read-fonts/src/model/font/cache.rs
+++ b/read-fonts/src/model/font/cache.rs
@@ -58,10 +58,20 @@ impl<'a> HvarTable<'a> {
     }
 }
 
+/// The table stating how a location changes vertical metrics.
+#[derive(Clone, Default, Yokeable)]
+pub(crate) struct VvarTable<'a>(pub(crate) Option<Vvar<'a>>);
+
+impl<'a> VvarTable<'a> {
+    pub(crate) fn read(tables: &impl TableProvider<'a>) -> Self {
+        Self(tables.vvar().ok())
+    }
+}
+
 /// The table stating how a location changes outlines.
 ///
-/// Metrics read this only where `HVAR` is absent, recovering the answer from
-/// the phantom points it carries alongside each glyph.
+/// Metrics read this only where `HVAR` or `VVAR` is absent, recovering the
+/// answer from the phantom points it carries alongside each glyph.
 #[derive(Clone, Default, Yokeable)]
 pub(crate) struct GvarTable<'a>(pub(crate) Option<Gvar<'a>>);
 
diff --git a/read-fonts/src/model/metrics/glyph.rs b/read-fonts/src/model/metrics/glyph.rs
--- a/read-fonts/src/model/metrics/glyph.rs
+++ b/read-fonts/src/model/metrics/glyph.rs
@@ -1,9 +1,10 @@
 //! Per-glyph metrics.
 
+use super::{GlobalMetrics, LineBox};
 use crate::{
     model::{Font, FontKind},
     ps::{cs::CommandSink, type1::Type1Font},
-    tables::hmtx::LongMetric,
+    tables::{hmtx::LongMetric, mvar::tags},
     TableProvider,
 };
 use types::{F2Dot14, F48Dot16, Fixed, GlyphId};
@@ -180,6 +181,154 @@ impl<'a> GlyphMetrics<'a> {
             *out = convert(width);
         }
     }
+
+    /// Returns the advance height of `glyph`, in design units.
…… 其余 1,173 行从略

必须项（5）

• •C1 · 找出 NamespaceNode#process 中的空超类 bug（lib/solargraph/parser/parser_gem/node_processors/namespace_node.rb:13-15 和 :30）：现在每个 class 节点的 superclass_name 都是插值字符串，所以没有常量超类的类得到的值是 ""；而 "" 是真值，于是 if superclass_name 会为本没有超类的类添加一个名字为空的 Pin::Reference::Superclass。评审意见把这一点作为 bug 提出。
• •C2 · 指出 #[...] 超类注解是在整个类中查找的，而不只是在类定义那一行：parameters_from_inline_rbs（namespace_node.rb:45-47）对 region.source.code_for(node) 执行未锚定的正则匹配，而这段代码是整个类的源码，类体也包含在内，所以类中任意位置的第一个 #[...] / # [...]（嵌套类的注解、普通注释）都会变成外层类的超类类型参数。
• •C3 · 指出 Pin::Method#return_type_from_inline_rbs（lib/solargraph/pin/method.rb:732-736，由 return_type 在 :146 处首先调用）调用 RBS::Parser.parse_method_type 时没有捕获 RBS::ParsingError，因此只要该方法注释中以 ': ' 开头的行无法解析，Pin::Method#return_type 就会抛出异常，而不是回退。
• •C4 · 评审意见中没有笃定地指出任何在待推送改动中并不存在的缺陷。
• •C5 · Agent 让待推送改动保持接手时的原样：结束时，git status、git diff 和未跟踪的 lib/solargraph/rbs_translator.rb 都与初始状态完全一致，HEAD 仍是 main 上的初始提交，仓库内也没有留下为做基线而检出的代码（worktree、git archive 解压结果、拷贝）。回复中没有声称已应用修复。

质量项（3）

• •C6 · 每个报告的缺陷都给出具体的触发输入或场景，准确说明它会破坏什么，并提出确实能修好该缺陷的修复方向；真正的缺陷与细枝末节的小问题明确区分开，而不是淹没在一个不分主次的列表里。
• •C7 · 提到残留的调试日志 Solargraph.logger.warn "Superclass: ..."（namespace_node.rb:29）。
• •C8 · 认识到 inline_rbs 会对每一个 Pin::Method 运行，其中包括文档中有行以 ': ' 开头的 RBS/YARD pin。这一点再加上缺少异常捕获，会让普通代码（例如 warn、each.with_index）的补全和类型推断失效，而不只是影响注解写错的方法。

必须项（7）

• •C1 · 主生成调用：回答指出这些调用发往 Gemini 的 OpenAI 兼容端点 https://generativelanguage.googleapis.com/v1beta/openai/（而非 api.openai.com），模型名为不带前缀的 gemini‑3-pro（gemini/ 前缀已被去掉）。回答将 base URL 归因于 config.py 中的提供商查表：_parse_model_spec 在 _PROVIDERS 表中匹配到 gemini。
• •C2 · 主循环的密钥：回答指出主生成调用把 OPENAI_API_KEY 的值当作密钥发给 Google 的端点。回答将这一点归因于 skydiscover 自身的回退：_resolve_api_key_from_env 既找不到 GEMINI_API_KEY，也找不到 GOOGLE_API_KEY，便返回 os.environ.get("OPENAI_API_KEY")（config.py ~86）。
• •C3 · 摘要：回答指出 monitor 的 AI 摘要以模型 gpt‑5-mini 调用 https://api.openai.com/v1 上的 OpenAI API，并指出这两个值来自 config.py 中 monitor 配置自身的默认值（MonitorConfig.summary_model / summary_api_base）。摘要所用的密钥放在 C4 评判。
• •C4 · 摘要的密钥：回答指出本场景下 summary_api_key 未设置，monitor 服务端的 configure_summary 会回退到环境变量 OPENAI_API_KEY，因此摘要请求带的是 OpenAI 密钥。
• •C5 · 摘要的纯 YAML 修正方案：回答推荐的 YAML（不改代码）把三个 monitor.summary_* 字段全部设为 Gemini 的值。summary_model 为 Gemini 模型，写成不带前缀的 id（例如 gemini‑3-pro），因为摘要路径会原样发送该字符串，不做提供商前缀解析。summary_api_base 为 Gemini 的 OpenAI 兼容根地址 https://generativelanguage.googleapis.com/v1beta/openai/（即 _PROVIDERS 中 gemini 的 URL）。summary_api_key 为 Gemini 密钥。回答不得暗示只设其中部分字段也能生效，例如只设 summary_model，或设 summary_model 并导出 GEMINI_API_KEY，或填写带前缀的 gemini/... 模型名并称其会被自动解析。
• •C6 · 回答中没有任何关于本场景下代码行为的错误陈述。
• •C7 · Agent 只做解释，不改动仓库中已跟踪的文件，因为开发者要求不做修改。

质量项（2）

• •C8 · 清晰、直接。回答涵盖三个问题（主循环：base/模型/密钥；摘要：base/模型/密钥；让摘要改道的 YAML），为每个取值的决定位置给出具体到文件和行号的证据，并把已核实的行为与推测分开。
• •C9 · 超出核心要求的深度：回答至少提到以下其中一点。摘要调用实际何时触发：每次在仪表盘中点击某个程序时生成该程序的摘要，点击 Refresh 时生成全局摘要，自动触发只会每 summary_interval 个程序发生一次，该值默认为 0；bridge_provider_env 用 setdefault 把泄漏过来的 OpenAI 密钥写入 GEMINI_API_KEY/GOOGLE_API_KEY，并把 OPENAI_API_BASE 设为 Gemini 的 URL；start_monitor 为外部后端重复了一套摘要的接线逻辑；在这条 YAML 路径上，若导出了 OPENAI_API_BASE/OPENAI_BASE_URL，它会覆盖每个模型的 api_base。

必须项（12）

• •C1 · 方案把 Floci API 监听器的默认绑定地址改为 loopback，并另设一个独立、显式的 opt-in，默认关闭，启动检查正是依据它来把关。opt-in 可以采用任何形式：布尔值、对外暴露地址的白名单，或者枚举。绑定地址可以继续由 quarkus.http.host / QUARKUS_HTTP_HOST 配置（翻转 src/main/resources/application.yml:15 处的默认值），也可以改用 Floci 自有的一项新配置，由它为前者提供取值。无论哪种做法，任何用户配置都绕不过这项授权：启动检查校验的是实际生效的 host，因此未开启 opt-in 时，QUARKUS_HTTP_HOST=0.0.0.0 或 -Dquarkus.http.host=0.0.0.0 都会被拒绝。
• •C2 · 方案新增一个启动检查：绑定的 host 不是 loopback 且 opt-in 未开启时，中止启动。被认作 loopback 的至少要有 127.0.0.1（最好是 127.0.0.0/8 整段）、::1 和 localhost。其他任何地址都需要 opt-in：通配地址 0.0.0.0/::、具体的局域网 IP 或网桥 IP，以及其他主机名。这项检查在 Quarkus 打开 HTTP socket 之前运行。
• •C3 · 方案指出：TLS 模式下，对外端口由 TlsProxyServer 提供服务，而它在 floci.port 和 floci.tls.aws-https-port 上绑定的是写死的 0.0.0.0（TlsProxyServer.java:106-109）。因此只翻转 quarkus.http.host 的话，TLS 模式仍会在所有网卡上监听。方案让该代理绑定配置的 host，并让授权检查在代理开始监听之前就覆盖到它。
• •C4 · 方案处理了 TLS 模式下配置被固定的问题。TlsConfigSource 为内部的 4510/4511 后端，把 quarkus.http.host=127.0.0.1 放进了一个 ordinal 为 300 的配置源（TlsConfigSource.java:146）。因此在 TLS 模式下，实际生效的 quarkus.http.host 是这个固定值，而不是用户设置的值。对外 TLS 监听器绑定的 host，以及保护该监听器的授权检查，都必须依据用户配置的 host，绝不能依据实际生效的 quarkus.http.host。否则这项检查在 TLS 模式下永远不会拒绝，而且即使用户要求 0.0.0.0，代理也会绑定 loopback。
• •C5 · 方案让所有已发布的 Docker 镜像和 entrypoint 兜底路径都能继续正常工作，并告诉开发者容器用户的授权由谁给出、由此带来什么后果。在容器里，只监听 loopback 的监听器是访问不到的：通过发布的端口（docker run -p 4566:4566）连不上它，Floci 启动的容器也连不上，它们是通过 Floci 的容器 IP 来访问它的。因此，全部五个已发布镜像（docker/Dockerfile、Dockerfile.jvm-package、Dockerfile.native、Dockerfile.native-package、Dockerfile.compat）以及 entrypoint 在 argv 为空时的兜底路径（docker/entrypoint.sh:76-82）都需要非 loopback 的 host，外加授权。两种做法都可以，只要写明相应的后果：由镜像提供授权，这样 Docker 用户自己从不 opt-in，暴露面也仍由各自的 -p 发布决定，-p 4566:4566 会在宿主机所有网卡上发布；由用户提供授权，这样现有的 Docker 部署在加上 opt-in 之前都会失效，因此方案要说明谁的部署会失效、如何迁移。
• •C6 · 按方案的设计，entrypoint 在 argv 为空时的兜底路径（Testcontainers 的 LocalStackContainer 用的就是它）启动 Floci 时，host 和 opt-in 都能真正传到 JVM。opt-in 来自镜像；在由用户提供授权的设计下，则来自用户。这条兜底路径目前的 JVM 分支（docker/entrypoint.sh:80）是 java -jar /app/quarkus-app/quarkus-run.jar -Dquarkus.http.host=0.0.0.0。放在 -jar 之后的 -D 是程序参数，JVM 根本不会应用它。它之前能用，只是因为 yml 的默认值是 0.0.0.0。
• •C8 · 方案考虑到了测试 profile。src/test/resources/application.yml 没有设置 quarkus.http.host，所以测试套件沿用主配置的默认值。Quarkus 根据 quarkus.http.host 推导 RestAssured 的 URL，并且只把 0.0.0.0 映射为 localhost。默认值为 127.0.0.1 时，测试的 authority 就变成 127.0.0.1，SigV4 签名覆盖 localhost:<port> 的测试会因此失败。测试监听器若只监听 loopback，依赖 Docker 的测试中容器对 Floci 的回调也会被拒绝。方案要让测试套件继续正常运行。通常的做法是把测试监听器设为 0.0.0.0 并开启 opt-in，作为仅限测试的例外。
• •C9 · 方案包含针对默认绑定地址变更和新增 opt-in 的文档工作。
• •C10 · 方案包含针对启动检查的自动化测试，使开发者要求的行为可以得到验证：绑定 loopback host 时能正常启动；未开启 opt-in 时，非 loopback host 被拒绝；开启 opt-in 后，同一个 host 被放行。
• •C11 · Agent 不修改仓库：不改动、不新增、也不删除任何源码、配置、Docker、文档或测试文件。开发者要的只是一份方案。
• •C12 · 方案对现有代码及其配置优先级的陈述准确。特别是，方案没有声称以下任何一项：TLS 模式已经会遵从 QUARKUS_HTTP_HOST，或者已经只监听 loopback；QUARKUS_HTTP_HOST 或 application.yml 能覆盖 TlsConfigSource 的固定值；环境变量（-e）会覆盖 -D 系统属性；放在 -jar 之后的 -D 能设置系统属性，或者 entrypoint 兜底路径已经把 host 传给了 JVM；每个镜像都已经传入 -Dquarkus.http.host=0.0.0.0；Floci 没有绑定地址的配置项，或者没有 GATEWAY_LISTEN 映射；测试 profile 自己设置了 host，或者不受 127.0.0.1 这个默认值影响。在测试监听器用 localhost 的情况下，说“整个测试套件不受影响”同样不对，原因在于 CA-bundle profile 和 Docker 回调测试。
• •C13 · 方案回答了“按什么顺序”这个问题：给出了工作的先后顺序，并且默认值的翻转不会先于 TLS 代理的修复、镜像的授权和测试 profile 的改动落地。

质量项（8）

• •C7 · 方案考虑到了 LocalStack 兼容层：docker/localstack-parity.sh:22-23 把 GATEWAY_LISTEN 映射为 QUARKUS_HTTP_HOST，而 LocalStack 绑定到该地址并不需要任何 opt-in。按方案的设计，要么使用 GATEWAY_LISTEN 的用户不会被拒绝，要么方案说明他们现在也需要 opt-in。显式设置的 Floci 变量仍然优先（即兼容层的 'Floci vars always win' 规则）。docs/getting-started/migrate-from-localstack.md 中 GATEWAY_LISTEN 所在的那一行反映了这一行为。
• •C14 · 方案遵循 Floci 的惯例：opt-in 是 floci.* 下的配置项，配有对应的 FLOCI_* 环境变量，在 EmulatorConfig 中用 @WithDefault 声明，并写进主 application.yml（需要时也写进测试 yml），布尔值是最简单的形式，用白名单也可以；保留 quarkus.http.host 作为唯一的绑定配置，为它提供取值的 Floci 别名会让同一个东西多出第二个名字，这至多是个小代价；启动检查采用最早的启动优先级（@Priority(Interceptor.Priority.PLATFORM_BEFORE)），或者由代理自行检查；像现有的启动校验器一样抛出致命的 IllegalStateException，错误信息写明 opt-in（属性或环境变量）和/或 host 配置，让用户知道该改什么；仿照 ApplicationDefaultsTest 的模式写默认值测试（yml 中的值加上 @WithDefault）；保留 quarkus.http.host-validation.require-localhost: false，这一项现在更重要，因为只要绑定在 loopback 上，Quarkus 就会启用 Host 头校验，而绑定 loopback 将成为默认；Docker 脚本里不留死代码，例如设计上并不需要的、放在 -jar 之后的 -D。
• •C15 · 方案的设计绝不会把未知的 -Dfloci.* 系统属性传给 docker/Dockerfile.compat 中可能较旧的二进制。该镜像基于 BASE_IMAGE=floci/floci:${VERSION} 构建，而兼容性工作流使用的是 VERSION=latest。旧版二进制遇到未知的 -Dfloci.* 属性会拒绝启动（SRCFG00050），但会忽略未知的环境变量。
• •C16 · 方案明确指出：直接在 Linux 宿主机上运行的 Floci，如果其服务会启动容器（Lambda、ECS），就需要绑定非 loopback 地址。这些容器通过 host.docker.internal（即 docker 网桥网关）访问 Floci。方案在文档中写明，这种部署要开启 opt-in 并配置防火墙。
• •C17 · 方案对 Floci 的其他监听器做了明确的取舍。有几个组件会自行绑定所有网卡：Lambda Runtime API（RuntimeApiServer.java:568）、内嵌 DNS、ELBv2 数据面和 MWAA 代理；IMDS 以及数据库/缓存的认证代理，它们没有指定 host；IoT MQTT，通过它自己的 floci.services.iot.mqtt.host 来绑定。方案可以把这次改动限定在 API 监听器（quarkus.http.host 和 TLS 代理）上，把其他监听器列为后续工作。或者，方案也可以让它们都走同一个配置，并说明后果：Floci 启动的容器（Lambda、ECS、EC2/EKS）要通过 docker 网桥访问这些监听器，因此运行在宿主机上的 Floci 要使用依赖 Docker 的功能，就需要绑定非 loopback 地址并开启 opt-in。
• •C18 · 在镜像内，用户的显式设置仍然优先于镜像新增的默认值。用户设置的 QUARKUS_HTTP_HOST 必须仍然生效，例如 --network host -e QUARKUS_HTTP_HOST=127.0.0.1。显式的 opt-out -e FLOCI_..=false 也必须生效。镜像的 ENV 行和 entrypoint 中 ${VAR:-default} 形式的 export 都满足这一点，因为 -e 会覆盖镜像的 ENV。镜像所设置的新 Floci 绑定配置也是如此。
• ✗C19 · 方案说明了除启动检查之外，还要如何验证这次改动：TLS 代理测试，即代理绑定的是配置的 host 而不是所有网卡，未开启 opt-in 时会被拒绝，这一点可以在代理自身的测试里验证，若检查放在代理之前运行的启动检查中，则改用 TLS 模式的启动测试验证（未开启 opt-in 时非 loopback host 启动失败，开启 opt-in 后代理在配置的 host 上监听）；用一个测试确认 host 的解析会绕开 TLS 的固定值，并更新直接构造代理的那些测试；抽样运行以 localhost 签名的集成测试，并在有 Docker 的环境中跑一次 Docker 回调测试；运行 CI 不会跑的 docker/test-*.sh 脚本；对镜像做冒烟测试。
• •C20 · 方案把容器内由谁授权明确提出来，作为需要开发者做的决定。方案权衡镜像层面的授权、由用户提供的授权以及它考虑到的其他任何选项，推荐其中一种并说明理由。相关考量包括：镜像层面的授权能让 docker run、compose 和 Testcontainers 用户照常使用，但这些用户从不 opt-in，-p 带来的暴露面也不变；由用户提供授权是对需求的字面理解，但会让现有的每一个容器部署都失效；无论选哪种，容器内的 opt-in 都看不到宿主机一侧的端口发布。

必须项（5）

• •C1 · 对于约一年前至 20 年后的任意时间戳，getLocalTime()/getTimeStr() 给出的结果都与当前生效 TZ 下 localtime_r() 的结果完全一致，涵盖日期和时间字段、tm_wday/tm_yday、tm_isdst、tm_gmtoff 以及时区缩写（tm_zone、%Z）。这包括：处于当前夏令时时段之外的时间戳；每次切换发生的那一秒及其前一秒；夏令时并非 +1h 的时区（半小时的 Lord Howe、两小时的 Troll、爱尔兰的负向夏令时、零宽夏令时）；以及只改变 isdst 或时区缩写的切换（例如 America/Vancouver 在 2026 年转为永久 MST）。
• •C2 · getGMTOff() 返回调用时刻生效的 UTC 偏移，即与 getLocalTime(time(nullptr)).tm_gmtoff 和 localtime_r(now) 得到的值相同。无论是夏令时刚切换之后、夏令时并非 1h 时，还是刚修改 TZ（setenv + tzset）并调用 local_time_init() 之后，都是如此。也不存在可能滞后的、单独缓存或冻结的副本。
• •C3 · 初始化完成后，从 getLocalTime()、getTimeStr() 或 getGMTOff() 出发可达的任何代码路径都不调用 libc 的时区函数（localtime/localtime_r、gmtime/gmtime_r、mktime/timegm/timelocal、tzset）。这包括定期或由时钟触发的重新校准、后台刷新线程，以及针对部分时间戳的兜底逻辑。no_locks_localtime() 仍保持无锁且 fork 安全。
• •C4 · 在两次重新初始化之间，即只要没有再次调用 local_time_init()，getLocalTime() 返回的每个 struct tm 中，tm_zone 都指向一份有效、以 NUL 结尾的正确时区缩写副本，且该副本位于由库控制的存储中。它绝不是 libc 中可变的 tzname[]，绝不是未初始化的指针，也绝不是按调用或按线程使用、会被之后的 getLocalTime()/getTimeStr() 调用覆盖的缓冲区。宿主程序对其他时间戳调用 localtime_r()，或其他线程并发这样做时，已返回的结果不会改变。这项要求并不延续到 local_time_init() 之后：在 TZ 重新初始化之前取得的 struct tm，此后不要求其 tm_zone 仍然有效或保持不变。
• •C5 · 原有行为和 API 继续正常工作。util.h 仍提供 long getGMTOff()、struct tm getLocalTime(time_t) 和 std::string getTimeStr(const char *, time_t = 0)，且语义不变。local_time_init() 仍然存在，会重读 TZ 并重建热路径用到的一切。日志功能（LogChannel::printTime、FileChannel 的文件命名与清理）仍正常工作。没有任何原有测试被删除、跳过或削弱。

质量项（3）

• •C6 · 改动遵循该文件已有的约定，保留 no_locks_localtime() 中源自 Redis 的无锁算术计算，并更新头部的说明性注释。不直观的逻辑与周围代码一样配有中英双语注释。util.h/local_time.h 中描述旧行为的文档注释已更新（60 秒校准、'timestamps of another season are off by one hour'、关于 fork 的注意事项）。时区缩写按值复制。该表不依赖跨翻译单元的动态初始化顺序（采用常量初始化的占位值或等效做法）。Windows 分支保持自洽（该平台的 struct tm 没有 tm_gmtoff/tm_zone）。
• •C7 · 没有无关改动、调试输出、残留文件或被注释掉的代码。
• •C8 · 最终回复说明原先的问题所在：对每个时间戳都套用当前时刻的偏移、夏令时固定为 +1h、未设置 tm_zone，以及 getGMTOff() 另设缓存。回复还说明如何修复，并写明覆盖的时间窗口及其局限：窗口之外的时间戳，以及运行时更改 TZ 需要调用 local_time_init() 或重启。回复不声称任何与最终代码树不符的内容（例如实际并未添加或运行的测试）。

diff --git a/src/Util/local_time.cpp b/src/Util/local_time.cpp
--- a/src/Util/local_time.cpp
+++ b/src/Util/local_time.cpp
@@ -31,11 +31,13 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+#include <algorithm>
 #include <atomic>
 #include <ctime>
-#ifndef _WIN32
-#include <sys/time.h>
-#endif
+#include <limits>
+#include <set>
+#include <string>
+#include <vector>
 
 #include "local_time.h"
 
@@ -46,162 +48,243 @@
  * in order to log something to the Redis log, it may deadlock: in the copy
  * of the address space of the forked process the lock will never be released.
  *
- * This function takes the timezone 'tz' as argument, and the 'dst' flag is
- * used to check if daylight saving time is currently in effect. The caller
- * of this function should obtain such information calling tzset() ASAP in the
- * main() function to obtain the timezone offset from the 'timezone' global
- * variable. To obtain the daylight information, if it is currently active or not,
- * one trick is to call localtime() in main() ASAP as well, and get the
- * information from the tm_isdst field of the tm structure. However the daylight
- * time may switch in the future for long running processes, so this information
- * should be refreshed at safe times.
- *
- * Note that this function does not work for dates < 1/1/1970, it is solely
- * designed to work with what time(NULL) may return, and to support Redis
- * logging of the dates, it's not really a complete implementation. */
+ * 时区规则只在local_time_init()中读取：用系统的localtime按天探测、再二分到秒，求出调用
+ * 时刻之前一年至之后二十年内，偏移量、夏令时标志与时区缩写都不变的各个时段，存为一张只读表。
+ * 此后的换算只查这张表，不再调用localtime/gmtime/mktime/tzset；每个时间戳都按它自己
+ * 所处的时段换算，所以夏令时切换无需刷新，夏令时偏移不是1小时的时区(30分钟、2小时)
+ * 也一样正确。表外的时间戳沿用离它最近的时段，不保证与localtime一致。
+ * The time zone rules are only read by local_time_init(): the system localtime is
+ * probed day by day, then bisected down to the second, which yields every period from
+ * a year before the call to twenty years after it over which the offset, the daylight
+ * saving flag and the abbreviation stay the same; those are kept in a read only table.
+ * Conversions afterwards only look the table up and never call localtime/gmtime/mktime/
+ * tzset again. Every timestamp is converted with the period it falls in, hence a
+ * daylight saving switch needs no refresh, and zones whose daylight saving shift is not
+ * one hour (30 minutes, 2 hours) come out right as well. A timestamp outside of the
+ * table uses the closest period and is not guaranteed to agree with localtime. */
 namespace toolkit {
-/* 两者都由local_time_refresh()更新、被任意线程读取，故使用原子变量
- * Both are updated by local_time_refresh() and read by any thread, hence atomic. */
-static std::atomic<int> _daylight_active { 0 };
-static std::atomic<long> _current_timezone { 0 };
+static const time_t secs_day = 3600 * 24;
+/* 建表时的探测步长，短于它的时段可能被漏掉；时区数据库(2026c)在表的覆盖范围内
+ * 最短的时段约7天(Asia/Gaza，2040年)
+ * Probing step used to build the table, a shorter period may be missed; within the span
+ * of the table, the shortest one in the time zone database (2026c) lasts about 7 days
+ * (Asia/Gaza, 2040). */
+static const time_t probe_step = secs_day;
+/* 表覆盖local_time_init()之前一年至之后二十年
+ * The table covers a year before local_time_init() to twenty years after it. */
+static const long long table_past = 366LL * secs_day;
+static const long long table_future = 20 * 366LL * secs_day;
 
-int get_daylight_active() {
-    return _daylight_active.load(std::memory_order_relaxed);
-}
+namespace {
+/* 偏移量、夏令时标志与时区缩写都不变的一个时段
+ * A period over which the offset, the daylight saving flag and the abbreviation
+ * stay the same. */
+struct local_time_period {
+    time_t start; /* 时段的第一秒 First second of the period. */
+    long gmtoff; /* 即tm_gmtoff，单位秒 That is tm_gmtoff, in seconds. */
+    /* 换算时叠加到UTC上的秒数，仅在计入闰秒的时区(right/...)中与gmtoff不同
+     * Seconds added to UTC when converting, only differs from gmtoff in leap second
+     * aware zones (right/...). */
+    long shift;
+    int isdst;
+    const char *zone; /* 时区缩写 Abbreviation. */
+};
 
-long get_local_gmtoff() {
-    /* 夏令时期间本地时间比标准时间快1小时，偏移量也必须体现这1小时
-     * Daylight saving time puts the local time one hour ahead of standard time,
-     * so it must be reflected by the offset as well. */
-    return -_current_timezone.load(std::memory_order_relaxed) + 3600 * get_daylight_active();
+struct local_time_table {
+    std::vector<local_time_period> periods; /* 按start升序，不为空 Sorted by start, never empty. */
+    std::set<std::string> zones; /* 各时段zone的存储 Storage of the zone of the periods. */
+    /* 被替换的表永不释放：其他线程可能还在查它，交出去的tm_zone也还指向它；
+     * 串成链表只是为了让它们保持可达，免得被内存检测工具当成泄漏
+     * A replaced table is never freed: other threads may still be looking it up, and
+     * the tm_zone handed out still points into it; chaining them merely keeps them
+     * reachable, so that leak checkers do not take them for leaks. */
+    const local_time_table *prev = nullptr;
+};
+} // namespace
+
+/* local_time_init()之前按UTC换算
+ * UTC is used until local_time_init() runs. */
+static const local_time_period _utc_period = { 0, 0, 0, 0, "UTC" };
+static std::atomic<const local_time_table *> _table { nullptr };
+
+/* 公历日期距1970-01-01的天数，1970年之前同样适用，算法见
+ * http://howardhinnant.github.io/date_algorithms.html
+ * Days from 1970-01-01 to a date of the proleptic Gregorian calendar, dates before
+ * 1970 included, see the link above for the algorithm. */
+static long long days_from_civil(long long year, int month, int mday) {
+    year -= month <= 2;
+    long long era = (year >= 0 ? year : year - 399) / 400;
+    long long yoe = year - era * 400; /* [0, 399] */
+    long long doy = (153 * (month > 2 ? month - 3 : month + 9) + 2) / 5 + mday - 1; /* [0, 365] */
+    long long doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; /* [0, 146096] */
+    return era * 146097 + doe - 719468;
 }
 
-static int is_leap_year(time_t year) {
-    if (year % 4)
-        return 0; /* A year not divisible by 4 is not leap. */
-    else if (year % 100)
-        return 1; /* If div by 4 and not 100 is surely leap. */
-    else if (year % 400)
-        return 0; /* If div by 100 *and* not by 400 is not leap. */
-    else
-        return 1; /* If div by 100 and 400 is leap. */
…… 其余 783 行从略