Ruby China 社区 Ruby 节点

终于等到！这个周末我去“玩”了一场纯聊技术的招聘专场

XXXXX — Fri, 05 Jun 2026 09:34:23 +0800

说真的，我已经受够了一次次投简历、做笔试题、等通知的循环。上周末朋友拉我去参加了一个线下技术沙龙，结果去了才发现——居然是一个大厂的“隐藏版”内推会！没有笔试，没有 HR 面，直接跟技术负责人聊项目、聊架构、聊你踩过的坑。我带着随便看看的心态，跟一个后端团队聊了四十分钟，从 Redis 集群聊到 Go 的 GC 优化，对方直接说“你下周来我们组试试”。那一刻真的觉得，技术人最爽的“面试”就是不面试，只有切磋。现场还看到不少前端和测试的兄弟也拿到了意向，氛围比我想的热闹太多。正好，我最近发现一个靠谱渠道，也是这种“技术优先”的风格——技术大厂，前端 - 后端 - 测试，全国均有机会，待遇和稳定性都还不错~ 感兴趣可以试试：https://jsj.top/f/o38ijj 如果你也厌倦了刷题刷到麻木，不如换个路子。反正填个信息也不亏，万一打开新机会呢？周末有空也可以多留意下身边这种线下局，有时候机会就藏在聊天的代码里。

Ontology driven Agent：从“提示词工程（Prompt Engineering）”向“智能体软件工程（Agent Software Engineering）”

shoushen — Fri, 05 Jun 2026 09:10:45 +0800

目前，我感觉全球的 agent 开发陷入了一个瓶颈期，虽然大家在做各种努力，但本质上仍然是提示词工程。

我最近在看本体论，我发现将本体论（Ontology）加入到 agent 开发中来，能够彻底改变当前 agent 开发遇到的问题。

一、消除幻觉。提示词只能用自然语言“建议”模型去遵循规则，但 LLM 随时可能产生幻觉。本体论则是用严格的数据结构定义了业务的“物理法则”。
二、动态能力路由与权限控制。当不同的用户或子 Agent 介入时，系统通过图谱查询动态计算出当前上下文应该拼装哪些 Tool 的 Schema，然后再转化为提示词发给模型。
三、增强逻辑推理能力。通过推理机实现推理，而不是依赖于大语言模型。
四、提示词无法可靠地控制复杂的先后顺序和错误恢复。本体定义了有向无环图 (DAG) 依赖关系，可以驱动工作流。

还有：

安全护栏、动态本体上下文裁剪、反思与自我纠错、分布式本体、多 agent、长期记忆、自适应演进、零代码 Agent、事件和时间、跨智能体协议、复杂任务、神经 - 符号混合推理等方面，在引入本体论后都有更优雅的实现方式。

特别是：

在编程 agent 中，将代码以某种形式本体化后，就可以实现代码、业务逻辑、开发流水线的有机融合，将会极大的提高编程 agent 的工程能力。

另外补充：/

看了这个项目的解释视频（我也是看到这个视频的启发），虽然比较初步，但是可以看到将本体论引入编程 agent 的巨大潜力。

打听一个人 https://github.com/matzbot

zzz6519003 — Wed, 03 Jun 2026 14:08:30 +0800

who！

關於 spinel 的原理和侷限

mizuhashi — Sat, 30 May 2026 05:20:38 +0800

今天和 claude 一起研究了一下 https://github.com/matz/spinel ，大概知道了它和別的靜態語言有什麼不同。

spinel 的特點是需要對整個程序進行類型推斷，也就是一個方法的類型，實際上是由所有 call site 決定的。當看到一個方法調用的時候，分析器會把參數的類型記下來，然後把它疊到方法的定義上。例如一個方法factorial(n)，當分析器看到factorial(1) factorial(2)的時候，它就知道 factorial 能接受 integer，如果整個程序都沒有傳別的類型，那麼它就能斷定 n 是 integer，然後可以輸出很高效的 c 代碼。但如果分析器之後看到 factorial('1')，n 就會變成 integer | string，會需要額外處理多態，實際生成的 c 代碼就會包含這部分的處理。

這樣做的後果是，整個程序如果變了一行，之前的推導就要全部重新來過，因為這個是基於整個程序的推導。其他靜態語言由於會聲明函數的類型，推導對於函數體內和函數外是獨立的，因此一個函數在編譯了之後，如果簽名沒變就可以一直用，可以做到增量編譯。

crystal 實際上也是用整個程序做推斷的，所以會有和 spinel 一樣的侷限，沒辦法做增量編譯。

用 Ruby 构建 AI Agent（更新第二篇：工具调用）

Rei — Tue, 26 May 2026 23:20:42 +0800

AI Agent（人工智能体）是指以 LLM（大语言模型）作为推理引擎，能够自主调用外部工具，规划并解决实际问题的程序。

构建 AI Agent 已经成为目前最火热的开发领域。从构建通用 AI 助手，到传统应用引入 AI 功能，都需要用到构建 AI Agent 的知识。

同时 AI Agent 又和传统软件有很大不同。传统软件需要程序员设计程序运转的完整流程，AI Agent 却要将思考外包给大语言模型，由大语言模型自主决定怎么做。构建 AI Agent 的过程，就好像给一个大脑安装五官和四肢。

无论是为了业务需要，还是为了提升个人能力，学习构建 AI Agent 都会有所收益。

为什么用 Ruby

在 LLM 训练领域，Ruby 可以说毫无存在感，那是 Python 和 C++ 的主场。构建 AI Agent 则回到了 Ruby 熟悉的领域——开发应用。

AI Agent 最主要的两个操作是调用外部 API 和数据持久化，其实用什么语言开发都差不多。Ruby 的优势在于开发效率。

下面是用 RubyLLM 库调用大语言模型的最小例子：

require "ruby_llm"

RubyLLM.chat.ask "Hello!"

Ruby 社区追求优雅代码的传统让 LLM 的库比别的语言更精简。

如果要为已有的 Ruby 应用添加 AI 功能，那么用同样的语言开发可以减少技术栈的复杂度。

接下来我们会逐步学习如何构建 AI Agent。

在 Reddit 上发了一个 Ruby Agent 开发的帖子有点火了

lyfi2003 — Tue, 26 May 2026 19:38:02 +0800

https://www.reddit.com/r/ruby/comments/1tnynx8/built_a_full_ai_agent_in_ruby_metaprogramming/

大家有 reddit 账号的可以围观看下~ 另外，我们想在 hackernews 上也发一下但最近他们对账号有要求（要一直活跃才行），谁有合适的账号请求帮助啊

有没有用 rails+AI 做了审批流的功能模块或 gem，交流下经验

stephen — Tue, 26 May 2026 08:03:42 +0800

RT，感觉还可以

Ruby 4.0.4 修复了一个性能问题

Rei — Fri, 15 May 2026 16:04:29 +0800

我的网站在升级 Ruby 4.0 的时候遇到了性能问题，具体表现为，如果网站有大量的 html 内容需要 sanitize，那么在执行 2、3 次后网站就会卡死，cpu 100%。

排查了很久自己的代码和依赖的 gem 也没解决，不得已只好回退 3.4。

问题原因在这里：https://bugs.ruby-lang.org/issues/21856

最近发布的 Ruby 4.0.4 已经修复了这个问题，我升级了网站不再出现卡死。有需要的可以升级测一测。

Harness 工程经验分享：实现 100% 缓存命中 OpenClacky（RubyAgent）的 7 个关键决策

lyfi2003 — Thu, 14 May 2026 19:40:04 +0800

感谢社区朋友的支持，OpenClacky 的关注量从 200+ 马上破 400 了~ 用户活跃量已经翻倍。

我把这二年的坑和 Ruby 重写 AIAgent 的思考放出来，大家一起看看离 ClaudeCode 这种顶级 Harness 工程还有多远。

开篇

为了让新朋友重新了解一下我们的评测结果，我再列一下。

成本极优：3 项任务实测，4 家 Agent 横评，OpenRouter CSV 逐请求核算：

Agent	总成本	请求数	Cache 命中率
OpenClacky	$5.10	51	90.6%
Claude Code	$5.49	70	95.2%
OpenClaw	$15.70	81	88.7%
Hermes	$30.14	218	60.3%

完整数据和产物对比：openclacky.com/benchmark

51 个请求 + 90.6% 命中率 → $5.10。218 个请求 + 60.3% 命中率 → $30.14。成本差距的直接原因就两个：请求数和 cache 命中率。

不要忘了，OpenClacky 是一个全功能 Agent：WebUI + 命令行、长期记忆、Skill 技能库、定时任务、IM 接入（飞书/企微/微信）、浏览器自动化、子 Agent、运行时切模型、Skill 自进化与动态加载。

而很多开源 Agent 也许有较好的 Token 消耗，或功能不全，或命中率不高。

在实践中最大的问题是：这些功能里很多跟"高 cache 命中率"是结构性冲突的。

举例：

切模型 → 模型 ID 写在哪？写进 system prompt 就 cache 失效一次。
中途装 skill → skill 列表写在哪？写进 system prompt 就 cache 失效一次。
知道"今天日期" → 写进 system prompt？跨天就失效。
加"读 PDF"能力 → 最容易的实现是再加一个工具 → 工具 schema 变了 → cache 失效面变大，模型选错工具的概率也变大。
上下文不爆 → 最容易的做法是开一次独立 LLM call 做压缩 → 压缩本身 100% miss，压完之后主对话 cache 也凉了。

单看任意一头都不难做：少做功能，命中率自然高；不管账单，功能可以堆得很猛。难的是两头同时做。这篇文章讲我们在每个冲突点上具体怎么取舍。

效果已经不是当前 Agent 的主要矛盾，成本才是。

起步：两年失败史

第三代之前还有两代，失败的很严重。但我感觉现在还有很多人在踩坑，估计很多人有争议，但我 100% 站我自己的观点。

第一代（2024-2025 上半）：RAG / 知识库

把用户 codebase、文档、历史会话全 embedding 进向量库，hybrid 检索 + 重排 + query rewrite。Agent 流程是"先查上下文，再答"。

实际跑下来的问题：

成本高，每次更新的 codebase，需要同步更新向量，实时性无法保证。
准确率有限，例如听起来 90% 的召回率是不是还不错，但是对不起，不仅没有用，还可能有害，我预测，97% 的召回率可能才刚刚够用。
多了一个会失败的部件（向量库），增加了很多延迟。

结论：千万不要搞任何 RAG、知识库分片。如果你要上 Agent，请直接上 Agent，外加一个适合 AI 去阅读的网站就可以了。（参考我们自反思 Skill product-help 的实现）

第二代（2025 中期）：SWEBench / 多 Agent 工作流

Planner / Coder / Reviewer / Tester 各一个 agent，消息总线 + 角色 prompt 编排。

实际跑下来的问题：

每个 sub-agent 各有 system prompt，各有 cache 命名空间。Agent 间交接靠消息序列化状态，每次交接 = 一次 cache miss。
一个单 agent 4 分钟能完成的任务，多 agent 编排到 14 分钟，成本 6×。
SWEBench 分数能刷上去，但榜单跑分跟用户实际感受脱节得很厉害。

结论：

不要做工作流编排。 多 Agent 在结构上就是 cache 灾难。人类的分工不对 AI 有任何价值。AI 是万能的。
不要被 benchmark 绑架。 模型每 6 个月跨一个台阶，用今天的二流模型 + 工作流堆出来的分数，会被半年后顶级模型 + 朴素 harness 直接抹平。把工程预算花在 harness 上，不要花在编排上。对 Agent 工程来说，Benchmark 本身也并不重要，一个朴素的 Agent 思想打败一切：站在 AI 的角度思考你的上下文。

第三代（2025 年底至今）

Ruby 从零重写，4 个月。围绕"cache 局部性"和"工具集稳定性"来组织。后面讲的所有决策都属于这一代。

核心决策 1：双 cache 标记 + 允许失败回退

OpenClacky 同时跑在 Claude / OpenAI 兼容这两条主线上，两边的 prompt cache 行为不同，但工程上我们只关心一个共性：cache 是按"前缀"匹配的——前缀里改一个字节，从那里往后全部失效。

所以前缀的"层次"和"标记位置"，决定了你下一轮还能 hit 到哪里。我们把请求前缀分成几段考虑：

session-stable 段：system prompt、工具 schema。session 内绝不变。
append-only 段：历史消息。只追加、不修改。
session-volatile 段：当前轮新消息（用户输入、工具结果、模型回复）。

前两段交给"系统提示词层"的天然断点，后续每轮都能 hit。真正需要工程的是"append-only 段"——它每轮都在长尾部，标记打哪儿、打几个，决定了下一轮还认不认得它。

朴素做法为什么不够

最直觉的做法是"每轮在 messages 末尾打一个 marker"。它在以下场景都会失效：

history 单调追加：第 N 轮在 messages[-1] 打 marker，第 N+1 轮 messages 又长了一条，原 marker 的位置内容已经不一样了——服务端找不到匹配，整段 history 上 cache miss。
模型回退一次工具调用：工具报错、用户 Ctrl-C 重试、或者模型自己决定换一种 tool call——这一刻"原本的最后一条"被丢弃，单 marker 直接作废。
运行时切模型：用户在 session 中途从 Sonnet 切到 Opus，请求路由到新 endpoint，最理想情况下我们希望两个模型共享尽可能多的前缀。任何不必要的 marker 抖动都会让"切换"成为新的 cache miss 事件。

我们一开始就栽在 (1) 上。修复链能从 git log 里看出节奏：

8ff66cc fix: cache
6ea99fe fix: prompt cache
e9a3602 feat: prompt cache works fine
7734c97 feat: try 2 point cache

前三个 commit 是逐步逼近，最后一个是结构性正解。

双标记是怎么工作的

每轮我们标两条连续消息，不是一条：

第 N 轮：    [..., msg_A, msg_B(*), msg_C(*)]
                                ↑       ↑
                          marker 1   marker 2

第 N+1 轮：  [..., msg_A, msg_B(*), msg_C(*), msg_D(*)]
                                ↑       ↑          ↑
                          (仍在)   (仍在)     新 marker

第 N+1 轮发出请求时：

服务端尝试匹配 msg_C 的 marker → 命中到 msg_C 之前的所有内容（system prompt + 工具 + 整段历史除最后一条）。
我们在 msg_D 上加新 marker，建立新的尾部断点供下一轮使用。

这是一个滚动双缓冲：任何时刻都持有两个断点——一个"刚建立的"（写）和一个"上一轮建立的"（读）。下一轮把"读"再读一次，把"写"扔掉，再在新尾部写一个。永远不会出现两个 buffer 同时失效的瞬间。

为什么是 2，不是 3 或 4

主流大模型的 cache 都允许多个标记位（上限不一），但更多并不更好：

每多一个 marker，那一轮就多一次 cache write，按写入费率收。
双标记要解决的失败模式只有一个位置："昔日尾部 / 今日尾部"这个边界。两个 marker 正好覆盖。第三个 marker 落在更靠前的位置，对应的 cache 段在下一轮仍然会被前两个 marker 之一覆盖——它写的是一段永远不会被独立读到的前缀。
标记多了之后，部分 endpoint 上服务端的候选前缀匹配代价也会涨。

简单说：2 是覆盖尾部边界的最小数量，3 多余，4 浪费。

允许失败：单步回退仍然命中

这是双标记的第二个好处，也是当时 7734c97 的真正动机。

模型偶尔需要回退一次 tool call：工具返回错误、用户 Ctrl-C 重试、或者上游 streaming 断了一半。这种情况下"昨天的最后一条"被丢弃了，但倒数第二个 marker 通常仍然落在仍存在的消息上——单步回退后还能命中。

单 marker 在回退时直接作废；双标记是能扛住单步回退的最小数量。我们没继续往上加（三标记也能扛两步回退，但成本不划算）——回退超过一步的概率已经低到可以接受全 miss 一次。

模型切换：为什么要 marker 不动

OpenClacky 支持在 session 中途换模型。工程上要保证两件事：

新模型的请求前缀和老模型尽量一致。 我们不在 system prompt 里写当前模型 ID（写在 [session context] 块里，见决策 2），换模型不动 system prompt。
marker 位置不变。 切完模型的下一轮，前两个 marker 落在和切换前完全相同的 message 上。新 endpoint 第一次请求会因为"换了上游账号 / 区域"产生一次 cache write，但前缀的几何结构是连续的，warm-up 只发生一轮。

这个细节不做的话，每次切模型一定要都要付完整 cache 重建的钱，用户会很不开心。

不能标的位置

marker 选择逻辑里有一条硬规则：跳过 system_injected: true 的消息。

[session context] 块就是典型例子——它是一次性信息，下一轮尾部已经变了，落在它身上的 marker 是一笔永远读不回来的写入。压缩指令注入也是同样的处理（决策 5 会展开）。

marker 选择从尾部往前走，system_injected 的跳过，凑够两个真实对话消息为止。

本节总结

system prompt + 工具 schema：靠 system prompt 段的天然断点 hit。
history 滚动：靠双标记。
单步回退：靠双标记容错。
模型切换：靠"动态信息不写进 system prompt"+ marker 位置不变。

把这四件事同时做到，普通一轮的 cache 命中率才有可能稳定在 95%+。前三件是 cache 几何，第四件是设计纪律。

决策 2：永不变的 system prompt

OpenClacky 的 system prompt 在 session 启动时一次性构建，之后字节冻结。 任何"想往 system prompt 里塞动态信息"的需求，必须重定向到别的位置。

这条纪律是 cache 命中率的第一道地基——system prompt 一变，后面所有 cache 全废，没有任何"局部修补"能挽回。

但日常跑下来，至少有四类信息"天然想插入到 system prompt"：

当前时间、当前工作目录、操作系统——模型需要这些来生成正确的命令和路径。
当前模型 ID——模型知道自己是谁有助于自适应行为。
用户装了新 skill——模型需要看到新的 skill 名称和描述才能调用。
用户更新了 USER.md / SOUL.md——agent 的人格和用户偏好发生了变化。

这四类信息都是"session 中途可能变"的。如果写进 system prompt，任何一次变更都意味着全量 cache 失效。

[session context] 块

我们的做法是把这些信息写进 message 流，而非 system prompt。每当环境发生模型需要感知的变化时（跨天、切模型、切工作目录），agent 在 history 里追加一条 user 角色的消息：

[Session context: Today is 2026-05-13, Tuesday. Current model: claude-sonnet-4-6.
OS: macOS. Working directory: /Users/.../project]

这条消息被标记为 system_injected: true。它不会被 cache marker 选中（决策 1 已经讲过），不会被算作真实用户轮数，压缩时也不会被原样搬进新历史。

注入是按日期 gate 的：同一天内只注入一条。跨天了，插一条新的。切了模型，插一条新的。大多数 session 里你只会看到一条 session context 块。

这个设计踩过的坑

第一版 inject_session_context 是在 agent 构造期就急切注入的。结果 @history.empty? 返回 false，run() 误以为是后续轮，跳过了 system prompt 的构建——第一次请求带着一条"today is Tuesday"但没有 system prompt 就发出去了。agent 的行为诡异了大约一天才定位到。

修复只有一行：等 system prompt 构建完毕之后再注入。代码里有一段注释记录了这个约束：

# IMPORTANT: Skip injection when the system prompt hasn't been built yet.
# Otherwise, appending a user message to an empty history makes
# @history.empty? false, which causes run() to skip building the
# system prompt entirely.

教训是：前缀的组装顺序比前缀的内容更要紧。 你可以花大力气设计每一段的内容，但只要组装顺序错一步，整个 cache 策略就是废的。

Skill 列表怎么处理

Skill 列表是最容易跟"永不变的 system prompt"冲突的需求。用户可以随时装新 skill，模型需要看到 skill 名和描述才能通过 invoke_skill 去调用它。

我们的取舍：skill 列表在 session 启动时渲染进 system prompt，之后冻结。 session 中途装的新 skill，模型在当前 session 里看不到——它会看到一条 [session context] 通告说"skill 列表已更新，新 skill 从下一个 session 可用"。

这意味着用户装完 skill 想立刻用会发现用不了，要开新 session。我们接受这个摩擦，因为替代方案是重渲染 system prompt 导致全量 cache 失效——这个代价打到所有用户的所有 session 的每一轮上。装 skill 是低频操作，cache 命中是每轮都在享受的收益，取舍方向很清楚。

USER.md / SOUL.md 的更新也是同样的处理：session 启动时读取，session 内不再变。

但是，在用户体验上，我们虽然降低了一些 Skill 发现的概率，但一旦用户主动提起新的 skill 时，我们系统仍能及时发现新 Skill。没有任何缓存，每次都会重建 Skill 列表。

决策 3：invoke_skill 的妙用

invoke_skill 是 OpenClacky 的 16 个工具之一，它是整个 OpenClacky 最核心的设计，花费的时间也最多，它提供 Skill 热加载能力，子 Agent 架构支持，记忆召回能力、Skill 进化能力，但它只占 system prompt 不超过 200 个 Token。

启动子 agent。
子 agent 用的工具集跟主 agent 完全相同（16 个）。它不是一个"精简版"，它能做主 agent 能做的一切事情。
子 agent 执行完后，把结果文本返回给主 agent，主 agent 的 history 里只看到"invoke_skill → 结果"这一对消息。

这个设计一口气解决了好几个问题：

子 agent = 状态隔离

做代码审查的 skill 可能需要读几十个文件、跑 grep、输出长篇分析。如果这些中间步骤都在主 agent 的 history 里，history 会膨胀得很快——cache 命中率没变，但上下文总量上去了，压缩触发得更早，成本更高。

子 agent 把这些中间过程隔离在自己的 session 里。主 agent 只看到最终结论。主 agent 的 history 没有被污染。

动态加载 Skill，不改 system prompt

装新 skill 的流程就是把一个 SKILL.md 放到 ~/.clacky/skills/<name>/ 或 .clacky/skills/<name>/ 下。skill 列表渲染进 system prompt 的时间点是 session 启动，决策 2 已经讲过。

但 invoke_skill 这个工具本身是始终存在的——它不需要 system prompt 里列出所有 skill 才能调用。模型可以通过 [session context] 通告知道新 skill 的名称，然后直接 invoke_skill(skill_name: "xxx")。Skill 的 SKILL.md 是在调用那一刻才读取的，不是预编译进 system prompt 的。

所以"动态加载 skill"这个能力，实际上是 invoke_skill 的运行时读取 + [session context] 的通告组合出来的。不需要改 system prompt，不需要改工具列表，不需要重启 session。

Skill 注入与路径处理

每个 skill 的 SKILL.md 可以引用相对路径的资源文件（模板、配置等）。invoke_skill 在启动子 agent 之前会把 skill 的目录作为上下文路径注入，子 agent 能用 file_reader、glob 直接读到 skill 附带的资源。

这让 skill 可以做到"自包含"——一个 skill zip 包里既有指令又有模板，装上就能用。

加密 Skill 与选择性落盘

部分 skill 包含商业敏感内容（客户的 prompt 策略、内部流程等）。OpenClacky 支持对 SKILL.md 做加密存储，运行时解密到内存、用完不落盘。同时 session 的落盘也是选择性的——对于涉及加密 skill 的 session，可以配置为不持久化到磁盘，只在内存中存在。

这不是 cache 工程的范畴，但它是 invoke_skill 架构的延伸：因为子 agent 的状态是隔离的，选择性不落盘可以精确到某次 skill 调用，而不需要把整个 session 的落盘关掉。

决策 4：控制稳定可靠的工具集 16 个

工具 schema 紧贴 system prompt 之后，在 cache 前缀里。schema 一变，后面全失效。这意味着：每多加一个工具，你不只是多了一份 schema 的 token 成本，你还多了一份"下次改工具时全量 cache 失效"的风险面。

另一面，工具太少也有代价：模型本来一步能做完的事，现在要分两三步（先调一个通用工具获取信息，再调另一个来操作），轮次上去了，每轮都要付 cache 和 output 的钱。

所以这不是一个"越少越好"的问题，而是一个经验平衡点。我们的答案是 16 个。

这 16 个分别是什么

类别	工具	说明
文件读写	`file_reader`, `write`, `edit`	读、写、搜索替换
代码搜索	`glob`, `grep`	文件查找 + 内容搜索
执行	`terminal`	shell 命令
浏览器	`browser`	接管 Chrome/Edge
网络	`web_search`, `web_fetch`	搜索 + 抓取网页内容
任务管理	`todo_manager`, `list_tasks`, `undo_task`, `redo_task`	规划、撤销、重做
交互	`request_user_feedback`	需要用户输入时
扩展	`invoke_skill`	调用 skill（决策 3）
安全	`trash_manager`	安全删除（rm → trash）

设计原则

简化参数。 每个工具的参数尽量少、语义尽量明确。比如 glob 只要 pattern 和 base_path，不需要模型去组合 --include / --exclude / --type 这些 flag。参数越多，模型出错的概率越高，出错就要重试，重试就是成本。

够用但不冗余。 glob 和 grep 是两个工具而不是一个：glob 负责"哪些文件匹配"，grep 负责"文件里哪些行匹配"。合成一个会让参数变复杂，模型调错的概率上升。但也没有继续拆成 find_files / list_dir / tree 三个——glob 一个就能覆盖这三个场景。

为每个工具写丰富的测试用例。 工具是 agent 跟外部世界的接口，一个工具出 bug 的代价远高于普通代码出 bug——它会让模型产生错误的观察，进而做出错误的决策，进而需要更多轮次来纠正。我们一共有 1600+ 的用例去覆盖各种场景的处理。最近有朋友给我们提交了子项目扫描慢（对，OpenClacky 支持子项目处理）的一个相关优化 issue。

为什么不是 10 个，也不是 25 个

10 个做不到。undo_task / redo_task / list_tasks 这些看起来"可以不要"的工具，拿掉之后模型就只能用 terminal 跑 git 来处理代码回滚——成功率远低于专用工具，而且 git 操作的副作用很难控制。很多工具设计了一个 code_run，我们并不推荐，实测反而导致任务变慢（需要写长代码），轮次变多（多次尝试）。

不需要 40+，只需要 16 个。

省掉的能力	替代方式	工具数节省
代码库分析专用工具	code-explorer Skill	~5 个
记忆读写专用工具	recall-memory Skill	~3 个
浏览器自动化（多动作拆分为多工具）	单一 browser 工具统一覆盖	~8 个
Sub-agent 编排工具	invoke_skill 统一入口	~6 个
定时任务管理工具	cron-task-creator Skill	~4 个

如果以后需要第 17 个，我们会加。4 个月了，还没加。

决策 5：压缩——不换模型、空闲时做、压到底

上下文窗口是有限的。不管 200K 还是 1M，长任务跑下来总会填满。填满之前必须压缩，否则要么截断丢信息，要么溢出直接报错。

压缩是 cache 命中率最大的单点威胁：老的消息被替换成一段摘要，前缀从那一刻起就跟之前不一样了——必然 cache miss。但压缩不可避免，所以问题不是"要不要压"，而是"怎么把压缩的破坏降到最低"。

结论一：不要换模型压缩

很多 agent 的压缩流程是开一个独立的 LLM call，用一个便宜/快速的小模型来做摘要。

问题：

独立 call 的 system prompt 跟主 session 不一样（通常是"你是一个摘要助手"），跟主 session 的 cache 没有任何共享前缀，压缩本身就是一次 100% cache miss。
压缩完之后，主 session 的 history 被替换了（老消息变成了摘要），主 session 的 cache 也跟着失效——接下来 4–5 轮跑在 cold 费率上。

等于你为每次压缩付了两笔钱：一笔给压缩 call 本身的 cache miss，一笔给主 session 压缩后的 cold-warm 阶段。

我们的做法：压缩不开独立 call，而是把压缩指令作为一条消息插进当前对话的末尾（Insert-then-Compress）。

这条指令被打上 system_injected: true，走正常请求路径。效果：

压缩 call 命中现有 cache：同样的 system prompt、同样的 tools、同样的 history 前缀。只有尾部的压缩指令是 cold 的，几百 token。
压缩完成后，重建 history：[system_prompt, summary, last_N_messages]。这一刻 cache 确实会 miss 一次——但只 miss 一轮，从第二轮开始双标记重新接管。

对比（一次 50K-token 会话的压缩事件）：

	独立 call 方案	Insert-then-Compress
压缩 call 的 cache hit	0%	~95%
压缩期间 cold token	~50,000	~500
主 session cold-warm 轮数	4–5	1

结论二：20–30 万 token 是压缩的甜区

太早压：浪费了上下文里还有价值的细节，摘要丢信息。太晚压：上下文太长导致模型注意力分散、推理变慢、输出质量下降。

我们测过多个阈值。20–30 万 token 是效果和成本的甜区——模型还能有效利用上下文，但离溢出还有足够余量来完成压缩本身。

压缩后无论如何会压到 1 万 token 以内。这不是省钱，这是控制后续每一轮的 baseline 成本——history 越短，每轮 input 越少，cache miss 时的惩罚也越小。

结论三：空闲第 3 分钟启动压缩

这是跟 cache TTL 的博弈。大模型厂商的 prompt cache 普遍有 TTL——cache 在一段时间无请求后会过期。过期之后下一轮的 input 是全量 cold，直接翻到 10× 成本。而且后续每轮都在叠加成本，直到 cache 重新 warm 起来。

所以我们跑了一个空闲计时器（idle_compression_timer.rb）：

用户停止输入 90 秒后开始检查。
如果 history 已经接近压缩阈值 → 立刻触发压缩。此时 cache 还是热的，压缩代价很低。
压缩完之后，新的短 history 在 TTL 过期前就建立了新的 cache 断点。

效果是：用户思考了几分钟回来，看到的是一个已经压缩好、cache 已经 warm的 session。相比之下，如果不做空闲压缩，用户回来时面对的是一个 cache 过期的长 history——那一轮的 input 可能是 30 万 token 全量付费。单这一个行为，在长思考间隔的场景下就能省 10× 的钱。

空闲计时器跑在后台线程里。记得加锁！

百万上下文的真相

"百万 token 上下文"听起来很性感，但做 agent 有两个现实：

过长的上下文对模型效果并不总是正面的。 模型在超长上下文里的注意力分散问题是已知的——关键信息被淹没在大量历史里，输出质量反而下降。
你真不一定用得起。 记住，模型每轮都要把上一轮所有的上下文全部带上。100 万 token 的 input，即使全部 cache hit（0.1× 费率），一轮也要付 10 万 token 等价的钱。如果 cache miss 了一次，那就是 100 万 token 全价。

真实世界用户停下来思考太过于常见，Cache Missing 太容易发生，Agent 开发者必须想办法帮用户减少开销。

所以我们的策略不是"尽量用满上下文"，而是"积极压缩，保持 history 短小"。1 万 token 的压缩后 history + 95% cache hit，比 100 万 token 的未压缩 history + 99% cache hit 便宜得多，效果也更可控。

如何确保压缩后仍然保证足够好的效果，这是另一个话题，我们后面展开。

决策 6：自进化的工具能力

PDF、Excel、Word、PPT 的阅读和解析是 Agent 经常遇到的需求。处理这类文件通常有两种路径：

内置一个 tool：比如 read_pdf、read_excel。好处是开箱即用，坏处是每个格式一个工具，工具列表膨胀（违背决策 4），而且解析库的依赖链往往需要 C 扩展，装起来就不"零痛"了。
做成 skill 让用户装：对用户来说不友好——遇到一个 PDF 还得先去装 skill，体验断裂。而且 skill 描述怎么写、什么时候触发，AI 效果不可控。

我们选了第三种路径：首次安装时把预设的文档处理脚本 copy 到用户目录，之后允许 AI 自行更新维护这些脚本。

具体做法：

首装 OpenClacky 时，onboard skill 会把一组 Python 脚本（PDF 解析、Excel 读取、OCR 等）copy 到 ~/.clacky/scripts/。
这些脚本不是 Ruby，而是 Python 3。原因很实际：Python 的文档处理生态（pdfplumber、openpyxl、python-docx、python-pptx）是当前最成熟的，OCR 方面 pytesseract / paddleocr 也远比 Ruby 生态完善。
当 agent 需要读一个 PDF 时，它不调一个专用 tool——它用 terminal 工具跑 python3 ~/.clacky/scripts/read_pdf.py <file>。工具列表没有增加。
如果脚本跑不过去（缺依赖、格式变了），agent 可以直接 write 修改脚本、terminal 跑 pip install 装依赖。下次再遇到同类文件就不会出问题了。

这就是"自进化"的含义：处理文档的能力不是写死在 gem 里的，它活在用户目录的脚本里，agent 自己可以维护。 第一次可能需要装个 pdfplumber，装完之后就是永久能力。

这个设计把"文档处理"从工具层面拉到了脚本层面，避免了工具列表膨胀，也避免了硬编码 C 扩展依赖。trade-off 是用户机器上需要有 Python 3——但 macOS 和大多数 Linux 发行版默认自带，这个前提在实际用户群里几乎都满足。

决策 7：内置浏览器工具，No Headless

浏览器自动化是 Agent 越来越重要的能力——验证前端改动、抓取文档、自动化测试流程。

市面上主流的做法有两种：

Headless 浏览器（Puppeteer / Playwright）：agent 启一个无头浏览器实例，完全在后台跑。
外接 MCP：通过 MCP 协议连接一个外部浏览器服务，agent 发 JSON-RPC 指令。

我们两种都不用，或者说——我们自己内置了一个 MCP Client，去接管用户已经在跑的 Chrome / Edge。

为什么不用 Headless

Headless 浏览器的问题是"看不见"。agent 操作的页面用户看不到、不知道 agent 在干什么、出了问题也无法判断。对于 Agent 的使用场景——用户在旁边盯着 agent 干活——"看不见"是很大的信任问题。

另外，Headless 经常遇到反爬检测：登录态拿不到、Cloudflare challenge 过不去、需要手动验证。用户自己的浏览器里已经登录好了、cookie 都在，为什么不直接用？

我们怎么做的

lib/clacky/tools/browser.rb（610 行）+ lib/clacky/server/browser_manager.rb 是整套实现。架构是：

用户的 Chrome / Edge 开启 Remote Debugging 端口（一次性配置，browser-setup skill 引导完成）。
OpenClacky 内置一个 MCP Client，通过 stdio JSON-RPC 2.0 连接 chrome-devtools-mcp 这个 daemon。
daemon 进程首次调用时启动，后续跨多次 tool call 保持存活。
browser 工具对外暴露的是高层语义动作：snapshot、click、type、navigate、screenshot 等——不是底层 CDP 指令。

对模型来说，"浏览器"就是 16 个工具里的 1 个，schema 跟其他工具一样稳定，不会因为浏览器的状态变化而改 schema。 这符合决策 4 的原则。

为什么不把浏览器做成外部 MCP

我们可以不内置浏览器、让用户自己配一个 Browser MCP 服务。但这样做的问题是：

用户体验差：装 agent 之外还要装 MCP 服务、配端口、配认证。
稳定性不可控：外部 MCP 的版本、协议兼容性、超时行为都不在我们手里。
工具 schema 不可控：外部 MCP 可能暴露几十个细粒度工具（page.click、page.evaluate、page.waitForSelector……），直接打进主 agent 的 tool list 就违背了决策 4。

内置一层封装的代价是我们要自己维护 MCP Client 和 daemon 的生命周期管理——browser_manager.rb 里处理了 daemon 启动、心跳检测、超时、crash recovery。但这个代价是一次性的工程投入，换来的是用户零配置（只要 Chrome 在跑）和工具列表的稳定。

最后，选择 Ruby 的理由

这不是一个显而易见的选择。LLM agent 生态里 Python 和 TypeScript 是主流，Ruby 几乎没有前例。但我们选 Ruby，而且选对了。

动态语言 + 元编程

Ruby 的元编程能力是我们实现 Skill 自进化、动态加载、工具注册等能力的基础。method_missing、define_method、class_eval 这些能力让运行时的行为修改非常自然。Python 也有类似能力，但 Ruby 在这一层的表达力明显更高。

对于一个"agent 自己可能改自己的辅助脚本"的系统来说，动态语言比静态语言更合适——你不需要重编译、不需要重启，改了就生效。

极致的分发能力

gem install openclacky 一行搞定。RubyGems 的分发链路非常成熟：版本管理、依赖解析、全局可执行文件注册（clacky 命令）都是开箱即用的。用户不需要 clone 仓库、不需要 npm install、不需要 pip 虚拟环境。

对比 Python 的分发——pip install + 虚拟环境 + 可能的 C 扩展编译——Ruby gem 的安装体验明显更丝滑。

零 C 库依赖

这是我们做了大量工程投入才做到的。看 openclacky.gemspec 的依赖列表：

faraday, thor, tty-prompt, tty-spinner, diffy, pastel,
tty-screen, tty-markdown, base64, logger, websocket,
webrick, artii, rubyzip, rouge, chunky_png

全部是纯 Ruby gem，没有一个需要编译 C 扩展。

这意味着在 macOS / Linux 上，只要有 Ruby（2.6+），gem install openclacky 就能装上、立刻能跑。不需要 brew install libxml2，不需要 apt-get install libffi-dev，不需要 Xcode Command Line Tools。

为了做到这一点，我们做了一些反常规的选择：

WebSocket：没有用 websocket-driver（需要 C 扩展做 UTF-8 校验），而是用了纯 Ruby 的 websocket gem。性能差一点点，但对 agent 场景来说完全够用，换来的是安装零阻力。
LLM 接口调用：完全零依赖，没有用任何第三方 LLM SDK（anthropic-rb、ruby-openai 等都没用）。直接用 faraday 做 HTTP，自己处理 streaming、tool_use 协议、cache_control 注入。这样我们对请求格式有完全的控制权——决策 1 的双标记就是在 client.rb 里直接操作 cache_control 字段实现的。
TUI：没有用 curses（C 扩展），直接用 tty-screen + ANSI escape code "画"出整个终端界面。

这一切是 AI Coding 的产物

说实话，"从零重写 WebSocket 客户端"、"从零实现 LLM streaming 协议"、"用 ANSI escape code 手画 TUI"——这些事情如果纯手写，工程量很大，这在以往完全不现实。

但 OpenClacky 本身就是一个 AI coding agent。这些"为了极致安装体验而大胆从零重写依赖"的决策，是用 OpenClacky 自己来完成的。一个能写代码的 agent 让"零依赖"从不切实际变成了可执行。这是一个自举的过程——产品帮助自己变得更好。

结语

回头看这 7 个决策，它们背后其实只有一句话：把工程预算花在 harness 上，把智能预算留给模型。

不做 RAG，不做多 Agent 编排，不做工具堆叠——不是因为这些东西没用，而是因为模型在快速变好。半年前需要 4 个 agent 协作才能勉强通过的任务，今天一个 agent + 一个好的 harness 就能做得更快更便宜。

我们选择把精力放在那些不会随模型进步而过时的事情上：cache 命中率、工具稳定性、安装体验、压缩策略。这些是 harness 层面的基础设施，不管模型换到哪一代都用得上。

如果这篇对你有用，请帮我们点赞，欢迎 PR。欢迎转发和分享。

OpenClacky 完全开源，MIT 协议：github.com/clacky-ai/openclacky

gem install openclacky 一行装完即用，不需要 Docker、不需要 clone 仓库。如果你也在做 Agent，欢迎试试，遇到问题直接开 issue 聊。

4 家 Agent 横评的完整数据、产物对比、录像回放：openclacky.com/benchmark

本文引用的核心代码：Cache 标记 · Insert-then-Compress · Session context 注入 · 空闲压缩 · 浏览器工具

matz 用 claude 把 mruby 的 issues 全关了

xiaoLinger — Tue, 12 May 2026 10:13:16 +0800

https://github.com/mruby/mruby/issues 已经只有一个 issues 了

随便点开几个基本上都是 matz and claude committed

11 英寸 MacBook 的第二春：从零开始配置 Ruby on Rails 开发环境

AixCoder — Sun, 10 May 2026 13:22:14 +0800

🌸 旧 MacBook 的第二春：从零配置 Ruby on Rails 开发环境

"最好的设备是你手里那台。"

很多同学手里都有一台旧的 MacBook Air，可能是当年为了写论文买的。现在用起来有点卡，打开 App 要转圈圈，似乎只能沦为追剧专用机。

但别急着放弃它。

MacBook 的硬件做工一向扎实，老机器的问题往往不是性能不够，而是系统里堆积了太多垃圾，以及没有装对工具。就像一间堆满杂物的房间，不是房子太小，而是需要重新整理。

给这台旧电脑重装系统 → 安装 Homebrew → 配置 Ruby → 搭建 Rails，它就能从追剧神器变身成一台趁手的编程学习机、写作工具，甚至是一台随身携带的代码终端。

安装前的准备：重装系统

强烈推荐先重装系统。 如果这台 MacBook 从买来到现在就没重装过，系统里可能积累了各种残留文件。

操作很简单：

备份重要文件到移动盘或云盘
开机时按住 Option + Command + R，进入在线恢复模式
选择重新安装 macOS，把系统恢复到最干净的状态

重装后的系统就像刚搬进的空房子，接下来我们往里面添置需要的家具。

第一步：安装 Homebrew

Homebrew 是什么？

Homebrew 就像 Mac 中隐藏版的应用商店，但比 App Store 强大得多。

想象你想在新家里添置家具：

App Store	Homebrew
像大型商场，卖的都是精装成品（爱奇艺）	像万能仓库，程序员需要的各种工具、语言、软件，一条命令就能自动下载、安装、配置好
买不到专业工具，或者版本很旧	永远是最新版，不需要你到处找安装包、点下一步、输密码

安装命令

打开终端，复制粘贴下面这行命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

系统会提示你输入开机密码（输入时不会显示字符，这是正常的，输完直接回车）安装过程可能需要几分钟，取决于网速。(建议安装的过程中全局科学上网)

安装 Homebrew 的过程中，它会顺带安装 Command Line Tools for Xcode。

Command Line Tools for Xcode 是什么？ Xcode 是苹果官方出的集成开发工具，里面包含了开发 iPhone App 需要的所有重型设备（几十个 GB）。但对于 90% 的开发者来说，我们不需要那个庞然大物，只需要里面最核心的几件工具

编译器 (Compiler)：把人类能看懂的代码，"翻译"成电脑能听懂的机器指令 构建工具 (Make)：相当于安装指南，告诉电脑第一步拼哪块，第二步缝哪条线

这就是 Command Line Tools for Xcode，包含了所有让代码"跑起来"的必要工具。

验证安装成功

brew --version

如果显示出版本号（例如 Homebrew 5.1.10），恭喜你，Homebrew 已经就位。

第二步：安装 rbenv

rbenv 是什么？

rbenv 是 Ruby 的「版本管家」。 它让你在同一台电脑上安装多个 Ruby 版本，想用什么版本就切什么版本，互不干扰。

为什么我们需要它？

想象一下，你是一个热爱生活且多才多艺的女生：

今天你想做一个现代感十足的网站，需要请 Ruby 3.2 大师来帮忙
明天你想维护一个几年前的老项目，那个项目很挑剔，需要指定某个版本的 Ruby
而你的 Mac 系统一直带着一个"老古董" Ruby 2.6 系统管理员，它是用来维持系统运行的，你最好不要动它

如果没有 rbenv： 你得在电脑里装好几个 Ruby，它们会为了争夺"谁才是真正的 Ruby"打架，最后把你的系统搞得一团糟

有了 rbenv： 简单管理多个版本的 Ruby，系统自带的旧版本不动，新版本各住各的房间，互不打扰

安装命令

brew install rbenv

安装的过程可能比较慢，因为电脑比较老了，很多工具得现场编译，耐心等待吧⌛️

安装完成后，请运行以下命令来配置 rbenv

rbenv init

关闭终端，重新打开，以确保更改生效。

验证安装

rbenv -v

第三步：安装 Ruby

Ruby 的美丽：一门像诗一样的编程语言

rbenv 管家已经就位，现在该请真正的主角进场了。

Ruby 像一首诗

它的发明者松本行弘（Yukihiro Matsumoto）说过一句话：

"我希望 Ruby 让程序员感到快乐。"

安装命令

先查看 rbenv 目前能提供的比较稳定的几个 Ruby 版本：

rbenv install -l

对于这台老旧 MacBook，我装了的 Ruby3.3.10，和其他设备保持版本一致性

rbenv install 3.3.10

💻 老旧 MacBook 特别提示：编译 Ruby 可能需要 10-20 分钟，风扇会狂转，这是正常的。建议插电进行，去泡杯茶，回来就好了。

装完后，设为默认版本：

rbenv global 3.3.10

验证安装

ruby -v

ruby 3.3.10 (2025-10-23 revision 343ea05002) [x86_64-darwin20] 旧 MacBook 现在拥有了一颗年轻的心脏

第四步：安装 Rails

Rails：Ruby 的黄金搭档，让想法快速落地

如果说 Ruby 是一首诗，Rails 就是一家出版社 它不负责写诗，但它让诗能被印刷、装订、送到读者手中，而且整个过程快得惊人。

Rails 像是一套「盖房子的标准化流程」。

你想搭一个网站，Rails 已经帮你把地基打好了、水电接通了、门窗装好了。你只需要决定：墙上刷什么颜色的漆、客厅里摆什么家具。

想象你去一家很懂你的咖啡馆：

你一坐下，店员就知道你要燕麦拿铁、半糖、去冰
不需要你每次都说一遍

Rails 就是这样。它假设你「大概率会这样做」，所以提前帮你把选择做好了。这种哲学叫 "约定优于配置"（Convention over Configuration）。

对于初学者来说，这太重要了。 你不需要先成为「全栈专家」，就能先做出一个「能用的东西」。成就感来得早，学习动力就足。

记得当时做一个诗歌小站——可以读诗、投稿、玩一个简单的文字游戏，结合 AI 编程，好像用了大半天就做出来了。

gem 是什么？

当你通过 rbenv 安装好 Ruby 的那一刻，gem 就已经坐在你电脑里了。

gem 的全名叫 RubyGems，是 Ruby 官方的包管理器，可以理解成 Ruby 世界的「快递总站」。

它的工作流程：

你在终端说：gem install rails
gem 就联网去 rubygems.org（Ruby 的官方仓库）
找到 Rails，把它连同所有依赖一起打包下载、自动安装

安装命令

gem install rails -v 你想要的rails版本

⚠️ 如果下载很慢：因为 gem 默认去国外的仓库拉货，可能会卡很久。建议先换成国内镜像源（ruby-china 镜像源）

安装过程可能需要几分钟，gem 会自动下载 Rails 及其所有依赖。

验证安装

rails -v

第五步：创建并启动你的第一个项目

1. 新建项目

在终端里输入：

rails new rails_nice

你会看到很多绿色的输出，正在新建项目，请稍等。

💻 老旧 MacBook 特别提示：第一次创建项目时，Rails 需要安装依赖，可能会比较慢，请耐心等待。

2. 进入项目文件夹

cd rails_nice

3. 启动服务器

bin/rails s

4. 你会看到什么？

终端里会显示：

=> Booting Puma
=> Rails 7.2.3 application starting in development 
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 8.0.1 ("Into the Arena")
* Ruby version: ruby 3.3.10 (2025-10-23 revision 343ea05002) [x86_64-darwin20]
*  Min threads: 3
*  Max threads: 3
*  Environment: development
*          PID: 14775
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

看到 Listening on http://127.0.0.1:3000，就是启动成功了。

5. 在浏览器里查看成果

打开 Safari（或任何浏览器），地址栏输入：

http://127.0.0.1:3000

写在最后

从重装系统，到 Homebrew，到 rbenv，到 Ruby，到 gem，到 Rails，再到 bin/rails s——这台旧 MacBook，终于焕发了第二春。

旧物值得被认真对待，学习也可以从当下便宜的设备开始。

M 芯片的 MacBook 就留着干重活吧，这台 macbook air 小电脑，很轻巧。

💡 小结

整个流程其实就是一个“套娃”安装的过程：

用 command line tools for xocde 为 Homebrew 铺路。
用 Homebrew 安装 rbenv。
用 rbenv 安装 Ruby。
用 Ruby（自带的 gem）安装 Rails。

每一个上层工具都依赖下层提供的环境。这就是为什么当初我们必须先解决 Xcode 开发工具安装的问题。

好啦，看到这台“小破机”重新跑起代码，😄 作为编程学习机和写作工具来说真是很好，非常适合带出门轻度使用。小电脑，很轻巧。

Spinel -- Ruby AOT 编译器

Rei — Fri, 24 Apr 2026 17:12:44 +0800

https://github.com/matz/spinel

Spinel 将 Ruby 源代码编译成独立的本地可执行文件。它执行全程序类型推断并生成优化的 C 代码，与 CRuby 相比速度显著提升。

试图交了个提升 Ruby Hash 性能的补丁

dsh0416 — Thu, 23 Apr 2026 13:15:53 +0800

动机

昨天在参加 RubyKaigi 的时候顺便瞄到了 st.c 的实现，然后让我回想起来，现在的 Ruby 的 Hash 实现主要来自于 Vladimir Makarov 在 2016 年实现的精心调优的 open-addressing 实现的版本。我突然想起 Google absl 实现里有个 Swiss Tables 实现吊打了 C++ 标准库的实现，而 Rust 的标准库实现基于的 hashbrown 也是基于相同的原理。我就在思考时隔十年我们能不能把 SwissTables 相关的算法移植到 Ruby 上进一步提升 Ruby 处理 Hash 类型的性能，要知道 Hash 类型是 Ruby 中调用极其频繁的类型，它替代了很多其它语言中 struct 的功能，因此性能提升能带来很直观的收益。

尝试

直接的移植后发现性能不升反降了，这和 Ruby 中 Hash 的用法很有关系。Ruby 中非常多的 Hash 对象非常小，而 Makarov 2016 年的实现对此做了非常细腻的优化。

于是我的做法转变成了，保留 Ruby 中原先对不同大小 Hash 的分层存储，从 Swiss Tables 对 control bit 更好的对超标量 / 向量化的支持和 H2 短哈希更好的缓存命中这两个角度进一步进行优化，只针对大的 Hash 对象（容量 >= 64）的情况进行处理。

设计

1. 三数组布局

array	width	role
`entries[]`	16B (以前为 24B)	以插入顺序记录 `(key, record)` 的日志
`hashes[]`	每 slot 4B	与之并行的截断 32 位哈希数组（也编码删除标记）
`bins[]`	自适应 1 / 2 / 4 / 8B	基于哈希的索引数组，存放指向 `entries[]` 的索引
`ctrl[]`	每 slot 1B	`H2`（哈希的高 7 位）或 `EMPTY (0xff)` / `DELETED (0xfe)`

entries[] 和 hashes[] 长度相同并由相同索引寻址，因此迭代和 slot 重用保持简单。ctrl[] 是快速拒绝过滤器，和 bins[] 并列；只有当某个 ctrl 字节与 H2 匹配时，我们才会加载（现在更小的）entry 和并行哈希以确认匹配。对 ctrl[] 在 uint64_t 读取上完成，这本质上是一种 SWAR 优化。

2. 紧凑的 `st_table_entry`

修改前：

struct st_table_entry {
    st_hash_t  hash;    /* 8 B */
    st_data_t  key;     /* 8 B */
    st_data_t  record;  /* 8 B */
};                       /* 24 B */

修改后：

struct st_table_entry {
    st_data_t  key;     /* 8 B */
    st_data_t  record;  /* 8 B */
};                       /* 16 B */

哈希移入 tab->hashes[i]，由于大多数情况可以依赖 H2 进行匹配。因此这样我们可以进一步提升 cacheline 的命中效率，从而提高 CPU L1 的命中率。

3. 新的哈希函数

仅存储低 32 位哈希意味着我们不能再从原始 unsigned long 哈希的高位 7 位读取 H2，而这是 SwissTables 原先设计所采用的做法。naive 的实现是在每次重建/重哈希/st_shift/st_general_foreach 中重新计算完整 64 位哈希以保证正确性，但会严重损害插入和重建性能 —— 尤其是对于类似 string 这样的变长类型的性能损害很大。

解决方法是从截断的 32 位哈希的一个不同位段推导 H2，该位段与用于选取 bin 的位段不重叠：

/* bin index: low `bin_power` bits, masked by `bins_mask(tab)`     */
hash_bin(uint32_t h, st_table *tab) { return h & bins_mask(tab); }

/* H2: bits 25..31 of the same 32-bit hash, never overlaps with     */
/* the bin index because bin_power is capped well under 25 in       */
/* practice.                                                        */
static inline unsigned char
st_swiss_h2(st_hash_t hash) {
    return (unsigned char)((hash >> 25) & 0x7f);
}

这使得存储的 uint32_t 是自包含的：每次探测都能从同一字中读取 bin 索引和 H2 字节，无需调用 do_hash()，重建/重哈希/移位/foreach 全部使用 ST_HASH_AT_IDX(tab, i) 而不是重新计算。

截断带来的另外两个细节：

normalize_hash_value() 已更新，以确保 0xFFFFFFFF（32 位哈希 slot 的墓碑标记）永远不会与真实哈希值冲突——如果截断结果落在该保留值上我们会进行跳变（bump）。在未启用 ST_USE_SWISS_BINS 编译的平台上保留 64 位的保留值。
MARK_ENTRY_DELETED / DELETED_ENTRY_P 宏新增了 table 参数，以便读取/写入并行的哈希 slot。

4. 在 H2 匹配时进行 prefetch

当 SWAR 在控制组中找到候选的 H2 匹配时，下一步是加载匹配的 st_table_entry 的哈希。我们在 find_table_entry_ind / find_table_bin_ind / find_table_bin_ptr_and_reserve 中在检测到匹配后立即对两者发出 __builtin_prefetch。在以查找为主的工作负载上，这能掩盖 SWAR 快速过滤器本会暴露的 CPU L2 缓存延迟。

与 `master` 的结果比较

两个二进制均来自相同代码树（master = 42b3cdc51a，swiss = 3c0446847f），相同编译器，相同编译选项。每个脚本运行 5 次，使用 --disable-gems，报告最佳结果。内存为 macOS arm64（M4 Max）上 /usr/bin/time -l 的最大常驻集大小（maximum resident set size）。

吞吐量（时间越低越好）

benchmark	master (s)	swiss (s)	speedup
aref_int_large	0.8352	0.6862	+17.8 %
aref_str_large	0.9915	0.8406	+15.2 %
aref_miss_large	1.0803	0.7896	+26.9 %
aref_mix_50	1.0337	0.8201	+20.7 %
insert_grow	0.1138	0.1105	+2.9 %
churn (mixed RW)	0.0321	0.0304	+5.5 %
iterate	0.0566	0.0565	±0.1 %

查找是主要的收益点——成功查找（+15 % … +20 %）和未命中（+27 %）均有提升，后者的原因是缺失的 key 现在能在第一个 SWAR 组立即短路，无需加载 entry/bin。插入和混合负载略有提速，因为重建不再调用 do_hash。迭代不受影响（它不需要访问 bins 或 ctrl）。

内存

benchmark	master (MB)	swiss (MB)	delta
insert_grow	66.62	60.44	−9.3 %
aref_str_large	15.27	15.23	−0.3 %
aref_mix_50	16.64	16.61	−0.2 %
churn	13.19	13.03	−1.2 %

每表内存（通过 ObjectSpace.memsize_of，在多个哈希上求和）：

workload	master	swiss	delta
2 000 hashes × 200 entries	14.66 MB	12.11 MB	−17.4 %
1 hash × 100 000 entries	4.19 MB	3.28 MB	−21.9 %

2000 hashes × 200 entries 模拟了常见的 Rails 负载，这可以节省 ~17.4% 的 Hash 内存占用。

这两种内存视图一致：任何保留大量存活条目的工作负载（无论是一个大哈希还是许多小哈希）都会因条目从 24B → 16B 的变化以及每槽 1B 的 ctrl[] / 4B 的 hashes[] 配对而显著减少内存，因为它们合计（每槽 5B）仍小于在 entries[] 中每槽节省的 8 B。表的每表开销在小于约 64 条目时大致保持不变；Swiss 路径仅在 entry_power ≥ 6（表容量 ≥ 64）时启用。

详见

https://bugs.ruby-lang.org/issues/22011

用 railway 这个服务器部署 ruby on rails, 发现很不错，但是有点贵，大家看看可以参考

shibin — Thu, 16 Apr 2026 19:31:53 +0800

我最近帮客户做网站，我把网站放到了 railway.com 上面，用 railway 的服务器和数据库，用 Google 存储，存储图片，

里面有 330 个产品信息。分别是 330 个产品图片、中英产品介绍。

但是用了 13 天，railway 的 5 美金就花完了，又充值了 5 美金...

感觉对这客户有点贵，官网展示网站，服务器费用一个月得超过 10 美金...

用 kamal 部署 rails 至阿里云主机总结

flchenhp — Mon, 13 Apr 2026 01:25:32 +0800

需求背景

rails 开发速度很快，体验很好，但是如果无法部署到服务器上，最后也就是自己在本机玩玩，开发的网页服务不能给别人使用。我在 deepseek 的帮助下经过一周的摸索终于实现了部署，特记录供自己后期查阅，也供其他人借鉴。真的感谢好时代，有 deepseek 不然想也不敢去想我一个个人业余开发者，身边没一个同语言开发指导老师怎么敢去想自行摸索完成部署功能。

让 deepseek 总结 kamal 一次完整部署的生命周期

下面是 Kamal 从初始化到部署完成的完整工作流程，每一步都对应具体的操作：

阶段 0：准备工作（只需一次）

初始化配置：运行 kamal init，生成 config/deploy.yml 配置文件
配置服务器列表：在 deploy.yml 中指定服务器的 IP 地址或域名
配置容器注册表：设置注册表的用户名和密码（通过环境变量加密存储）
设置 SSH 密钥：确保本地可以免密登录服务器
编写 Dockerfile：Rails 7+ 会自动生成，确保镜像构建正确

阶段 1：初始部署（`kamal setup`）

这个命令会完成服务器的首次配置：

SSH 连接并安装 Docker：连接到配置文件中的服务器，如果 Docker 未安装，自动通过 apt-get 安装
登录容器注册表：在本地和远程服务器上都登录，以便推送和拉取镜像
构建 Docker 镜像：使用项目根目录的 Dockerfile 构建镜像
推送镜像到注册表：将构建好的镜像推送到配置的容器注册表
在服务器上拉取镜像：通过 SSH 命令让服务器从注册表拉取镜像
启动 Kamal Proxy：确保代理服务正在运行，并监听 80/443 端口
启动应用容器：基于拉取的镜像启动新的 Docker 容器
健康检查：验证应用是否响应 GET /up 请求（必须返回 200 OK）
清理旧资源：删除未使用的镜像和停止的容器，防止磁盘占满

阶段 2：后续部署（`kamal deploy`）

这是日常更新应用的命令，只执行部署流程，不重复安装 Docker：

构建新镜像：基于最新的代码构建新版本镜像
推送到注册表：新镜像被推送到注册表，标签通常是 Git commit hash
SSH 连接服务器并拉取新镜像：服务器从注册表拉取新版本镜像
启动新容器（旧容器仍在运行）：在旧容器旁边启动新容器，确保服务不中断
健康检查：等待新容器通过健康检查（GET /up）
Kamal Proxy 切换流量：代理原子性地将流量从旧容器切换到新容器
停止旧容器：新容器稳定运行后，停止并删除旧容器
清理资源：删除旧镜像和未使用的容器，释放磁盘空间

我理解 kamal 的功能（没怎么接触过 docker）

我理解 kamal 大致功能是先将本机的开发环境和项目通过 docker 打包成镜像，push 到镜像仓库，然后登陆服务器先下载 docker，然后从镜像仓库 pull 这个镜像再还原运行。之前尝试过在本机和服务机均安装网络代理工具，这一步实现了，但是直接参考 rails guide 部署还是会存在问题，没搞明白。只能尝试将所有可能会用到科学上网的源替换成国内的源。

部署记录

step1：准备 hello world 项目

新建 rails 项目

ruby -v
rails -v
rails new rails106

用编辑器（我用的是 trae）打开项目，做初始化保存

#iterm
git add .
git commit -m "initial commit"

将 gem 源改成 rubychina 的源

# gemfile
-source "https://rubygems.org"
+source "https://gems.ruby-china.com"

添加 hello world 页面

#iterm
rails g controller welcome index

# app/views/welcome/index.html.erb
+<h1>hello world</h1>
-<h1>Welcome#index</h1>
-<p>Find me in app/views/welcome/index.html.erb</p>

# config/routes.rb
  root "welcome#index"
  get "welcome/index"

启动项目，查看 hello word 页面

# iterm
bin/dev

将代码加入 git 保存

# iterm
git add .
git commit -m "add hello world page"

step2:选择云主机

阿里云主机可以直接添加 docker，免去安装 docker 的麻烦。直接用 root 账号和设定的自定义密码，这个会用于远程服务器。

远程主机验证 docker 安装成功：

# 云主机命令行
docker --version
docker run hello-world

step3:申请阿里云容器镜像服务（ACR）

进入控制台：登录后搜索“容器镜像服务”，或直接访问容器镜像服务控制台。
按提示创建个人版实例（下面的信息都很重要，部署的配置文件要用）
按提升建立命名空间
按提示设置密码，获取登录命令
获取个人加速器地址

step4:在本机下载 docker

访问 Docker Desktop for Mac 下载页面选择适宜自己电脑版本下载安装
点击 Mac 顶部菜单栏的 Docker 图标，选择 Settings。在左侧菜单选择 Docker Engine，将阿里云和一些其他的加速器地址填上 { "builder": { "gc": { "defaultKeepStorage": "20GB", "enabled": true } }, "experimental": false, "registry-mirrors": [ "https://5ex1e6il.mirror.aliyuncs.com", "https://docker.1panel.live", "https://hub.rat.dev", "https://docker.m.daocloud.io", "https://docker.nju.edu.cn", "https://docker.xuanyuan.me", "https://docker.1ms.run" ] }
打开“终端”应用，运行docker --version 和docker run hello-world 进行验证 docker 是否正确安装

step5:进行部署配置

#rails106/config/deploy.yml
-image: rails106
+image: myrailsapp/rails106 # myrailsapp是阿里云的镜像仓库命名空间

-    - 192.168.0.1
+    - 47.x x.xx.236 # 这是阿里云的IP地址

-  server: localhost:5555
+  # 这里填阿里云的镜像仓库的公网地址
+  server: crpi-xxxxxxxxxxx.cn-zhangjiakou.personal.cr.aliyuncs.com 

-  # username: your-user
+  # 这里填阿里云的账号
+  username: chenxxxxxx21

-  # password:
+   # 这里填阿里云的镜像的固定秘密
+  password: cxxxxxx9

代码类似

# rails106/Dockerfile
-# syntax=docker/dockerfile:1
+# #syntax=docker/dockerfile:1 # 第一行这里要再加个注释符号注释，不然会报错，不知道为什么

-FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
+# FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
+# 要换成ruby的国内的源，不然会卡住
+FROM docker.m.daocloud.io/library/ruby:$RUBY_VERSION-slim AS base

WORKDIR /rails
+# 设定 apt 源为阿里云镜像，不然会卡住
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \
+    sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
# Install base packages
RUN apt-get update -qq && \

代码类似加入 git 仓库

# iterm
git add .
git commit -m "add deploy set"

step6:打部署命令开始部署

# iterm
bin/kamal setup

部署成功：浏览器输入 ip 测试大功告成！！！

cloudfare vercel 部署后得到的链接国内用不了，求推荐域名服务～

zzz6519003 — Tue, 31 Mar 2026 15:37:42 +0800

///

Ruby 小白，做了个女性友好的诗歌 web app

AixCoder — Mon, 23 Mar 2026 14:45:29 +0800

📱：https://pomes.petercat.life/

起初的想法

去年冬天的时候就想着设计一款女性友好的诗歌 app

落地实现

2026 年开春了，借着当下 AI 编程的浪潮

选择用 Ruby 技术展现出这么个诗歌网站

这么个诗歌的小屋，用到的不过是那一点点技术几行 Ruby 代码，一个 SQLite3，再加上让文字呼吸顺畅的 CSS 间距。

在古法编程的时代来看一个小白要做出一个 app 并部署上线，要学习比较长时间的如今来看这么个 app 并没有什么傲人的地方，门槛也比较低

但是有的时候也常常想，如果更多女性来学这一点点技，多一些这样的港湾也蛮好

ps：想问问群里的一些深耕 Ruby 领域多年的“老员工”

Ruby 在国内的就业市场相比几年前下滑？

几年前就听说 Ruby 在国内用人招人不好招 😂

不过呢，学习 Ruby 倒不是说一味的奔着找工作去的

目前以兴趣在驱动着学习，能够把自己的一些想法借助 AI coding 落地（以兴趣为主）

最近学 rust，vibe 了一个序列化器，想念宏魔法

zzz6519003 — Thu, 19 Mar 2026 21:08:18 +0800

整出这样的代码

use crate::ast::Json;
use crate::parser::parse;
use std::collections::HashMap;

pub trait ToJson { fn to_json_value(&self) -> Json; }
pub trait FromJson: Sized { fn from_json_value(v: Json) -> Result<Self, String>; }

pub trait Serialize { fn serialize(&self) -> String; }
pub trait Deserialize: Sized { fn deserialize(s: &str) -> Result<Self, String>; }

impl<T: ToJson> Serialize for T { fn serialize(&self) -> String { self.to_json_value().to_string() } }
impl<T: FromJson> Deserialize for T { fn deserialize(s: &str) -> Result<Self, String> { let j = parse(s)?; FromJson::from_json_value(j) } }

// Primitive impls
impl ToJson for String { fn to_json_value(&self) -> Json { Json::String(self.clone()) } }
impl ToJson for &str { fn to_json_value(&self) -> Json { Json::String(self.to_string()) } }
impl ToJson for bool { fn to_json_value(&self) -> Json { Json::Bool(*self) } }
impl ToJson for f64 { fn to_json_value(&self) -> Json { Json::Number(*self) } }
impl ToJson for i64 { fn to_json_value(&self) -> Json { Json::Number(*self as f64) } }
impl ToJson for u64 { fn to_json_value(&self) -> Json { Json::Number(*self as f64) } }

impl FromJson for String { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::String(s) = v { Ok(s) } else { Err("expected string".into()) } } }
impl FromJson for bool { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Bool(b) = v { Ok(b) } else { Err("expected bool".into()) } } }
impl FromJson for f64 { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Number(n) = v { Ok(n) } else { Err("expected number".into()) } } }
impl FromJson for i64 { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Number(n) = v { Ok(n as i64) } else { Err("expected number".into()) } } }
impl FromJson for u64 { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Number(n) = v { Ok(n as u64) } else { Err("expected number".into()) } } }

// Option
impl<T: ToJson> ToJson for Option<T> { fn to_json_value(&self) -> Json { match self { Some(v) => v.to_json_value(), None => Json::Null } } }
impl<T: FromJson> FromJson for Option<T> { fn from_json_value(v: Json) -> Result<Self, String> { match v { Json::Null => Ok(None), other => Ok(Some(FromJson::from_json_value(other)?)) } } }

// Vec
impl<T: ToJson> ToJson for Vec<T> { fn to_json_value(&self) -> Json { Json::Array(self.iter().map(|v| v.to_json_value()).collect()) } }
impl<T: FromJson> FromJson for Vec<T> { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Array(arr) = v { arr.into_iter().map(|el| FromJson::from_json_value(el)).collect() } else { Err("expected array".into()) } } }

// HashMap<String, T>
impl<T: ToJson> ToJson for HashMap<String, T> { fn to_json_value(&self) -> Json { let mut m = HashMap::new(); for (k, v) in self.iter() { m.insert(k.clone(), v.to_json_value()); } Json::Object(m) } }
impl<T: FromJson> FromJson for HashMap<String, T> { fn from_json_value(v: Json) -> Result<Self, String> { if let Json::Object(map) = v { let mut out = HashMap::new(); for (k, v) in map { out.insert(k, FromJson::from_json_value(v)?); } Ok(out) } else { Err("expected object".into()) } } }

有没有山东省的 ruby on rails 爱好者？请加我，一起做事

shibin — Thu, 19 Mar 2026 17:56:16 +0800

有没有山东省的 ruby on rails 爱好者？请加我，一起做事，微信：shibincare

没买海外 vps 时如何解决 kamal deploy 的 EOF 问题

jicheng1014 — Wed, 18 Mar 2026 11:40:51 +0800

最近在部署 3qruok.com 的时候被墙又戏耍了，在国内环境下使用 Docker，网络问题始终是绕不开的痛点。即便你本地开启了系统的 TUN 模式或全局代理，在使用 Kamal 进行部署时，依然可能遇到下面这种让人冒火的“玄学”报错：

DEBUG [1ecc2695] ERROR: failed to build: failed to solve: failed to fetch anonymous token: 
Get "[https://auth.docker.io/token?scope=repository%3Alibrary%2Fruby%3Apull&service=registry.docker.io](https://auth.docker.io/token?scope=repository%3Alibrary%2Fruby%3Apull&service=registry.docker.io)": EOF
...
docker stdout: #0 building with "kamal-local-docker-container" instance using docker-container driver

明明机器已经开启了 TUN 模式，为什么 Docker 构建时还是拿不到 Token 导致 EOF？

核心矛盾：消失的网络继承

问题的根源在于 Kamal 默认的构建机制。Kamal 在打包时会创建一个名为 kamal-local-docker-container 的构建器，它使用的是 docker-container 驱动。

什么是 docker-container 驱动？

它的本质是在你的 Docker 中启动一个独立的 BuildKit 容器：

它的使命：实现跨平台构建（Multi-platform builds）。它内部集成了一个独立的 QEMU 模拟器，这使得它能完全脱离宿主机硬件架构的影响。无论你的 Mac 是 Intel 还是 M 系列芯片，它都能为你“直出”目标环境（如 x86）的镜像。
它的副作用：由于它运行在一个高度隔离的容器内，它拥有完全独立的网络命名空间。它不会自动继承宿主机的 TUN 代理或环境变量，甚至会忽略你在 Docker Desktop 界面设置的镜像源（Registry Mirrors）。这导致它在尝试拉取基础镜像（如 ruby:slim）时，依然在直接撞墙。

解决方案：回归宿主机驱动

要解决这个问题，最简单的办法是让构建任务交还给宿主机的 Docker Daemon 来处理，从而直接利用宿主机已经配置好的网络环境。

操作步骤

修改 deploy.yml 在配置文件中明确指定 builder 的驱动为 docker：
```
builder:
  driver: docker
```
提交配置（关键点） Kamal 部署时会检查 Git 状态。如果 deploy.yml 的修改没有被 git add，Kamal 可能会读取旧的配置导致修改不生效：
```
git add config/deploy.yml
```
清理旧的构建器 删掉那个由于网络原因卡死的旧构建实例，强制 Kamal 重新初始化：
```
docker buildx rm kamal-local-docker-container
```
重新运行部署 执行 kamal deploy，此时构建进程将直接调用本地 Docker 环境。

深度解析：为什么 `driver: docker` 依然能打出 x86 镜像？

你可能会担心：如果不用 docker-container 驱动，我在 ARM 架构的 Mac 上还能打出生产环境需要的 x86 镜像吗？

答案是肯定的。 这是因为 Docker Desktop for Mac 已经在其底层的 Linux 虚拟机里注册了 QEMU。当你切换到 driver: docker 时：

架构模拟：依然由 Docker 虚拟层底层的 QEMU 负责，跨平台打包能力依然存在。
网络控制：构建进程此时运行在宿主机 Docker 的“亲生”环境下，它能完美识别并使用你本地调教好的代理或镜像站。

总结

在 Kamal 部署流程中，如果你遭遇了 Docker 认证阶段的 EOF 错误，通常是因为默认的构建容器陷入了“网络孤岛”。

将 builder 的驱动修改为 docker 是目前国内开发者最务实的解决方案。它通过牺牲一点点构建隔离性，换取了对宿主机网络环境的完美继承，让部署过程不再卡在第一步。